know-thy-build weekly downloads statistics

know-thy-build

Before you write a single line of code, know what you're building, why, and how.

know-thy-build is a multi-agent project definition and quality assurance framework for Claude Code. Through Socratic dialogue — not forms — it helps you define your project, design features, establish a QA framework, and orchestrate implementation with built-in design and architecture review.

The result is a set of living documents and an automated workflow where every implementation is reviewed by designer, architect, and QA agents before it ships.

Why

We jump into code too fast. A new project starts, and within minutes we're picking frameworks, creating files, writing functions — before we've truly asked ourselves what we're building and why.

The cost of skipping this step is real: • Vague goals → wasted effort • Undefined boundaries → scope creep • Unspoken assumptions → wrong decisions — by you or by AI agents • No QA framework → "done" is an opinion, not a fact • No design intent → developers guess what to build

know-thy-build exists to define the project, design the experience, establish what "done" means, and enforce quality through multi-agent review — all before you write a line of code.

Quick start

Pick a language, and 13 commands are installed into your .claude/commands/ — one per human decision point (§13): Define (5) and Operate (8, meaningful once factory init has run).

Define

| Command | Role | Output |

| /know-thy-build:project | Define what it is, why it exists, and what it must become | docs/PROJECT.md | | /know-thy-build:technical | Define how your project will be built | docs/TECHNICAL.md + docs/factory/CHARTER.md (draft) | | /know-thy-build:qa | QA the product — test framework with behavioral axes, then run and verify with evidence | docs/QA.md | | /know-thy-build:feature | Design a feature before building it | docs/features/NNN.md + backlog issue | | /know-thy-build:issue | Log a bug, chore, or small change — no spec doc | backlog issue only |

Operate

| Command | Role | Output |

| /know-thy-build:harness | Fix a failing doctor / adopt a brownfield repo | harness.toml, doctor PASS | | /know-thy-build:next | Pick the next issue to queue | Label transition, human-decision | | /know-thy-build:clarify | Answer needs-info questions on a spec | Updated spec/issue, label transition | | /know-thy-build:unstick | Resolve a stuck issue (needs-human) | human-decision, derived issues, label transition | | /know-thy-build:proposal | Review a retro/harness proposal PR | PR comment (dry-run), human-decision | | /know-thy-build:role | Create or edit a reviewer/plan role | .claude/agents/reviewer-.md (or plan-.md), roles.toml diff, PR | | /know-thy-build:digest | Weekly summary of what shipped | docs/factory/digests/YYYY-Wnn.md | | /know-thy-build:status | Read-only dashboard (Needs You / in progress / queue) | none (read-only) |

designer and architect remain installed as optional Phase 1 helpers (invoked from :feature for complex UI or structural work) — 15 files installed in total.

The pipeline

[ ] = optional, invoked when needed.

Phase 1: Project Definition (once)

These three commands run once at project start. They produce the foundation documents that every subsequent command reads.

Phase 2: Feature Development (per feature, repeating)

Verification is the factory's job, not a manual step: its review roster (including the qa reviewer) and the deterministic gates decide whether a PR is mergeable. /know-thy-build:qa sets up the framework and the per-feature test cases those roles judge against.

Phase 2 — factory (dark build loop)

Once Phase 1 is done, npx know-thy-build factory runs the labelled-issue pipeline in CI (triage → plan → implement → review → merge):

Status: 1.3.0 — self-dogfooded on this repo (KTB #3 → PR #4, 2026-09-14) and adopted on another repo, own-calendar (#3 → PR #5, 2026-09-14); numbers in ADR-020.

• factory init — install .factory/, .claude/, .github/workflows/, docs/factory/ into the repo root (never overwrites; --diff/--upgrade to refresh package-owned files). On the Claude side that's 4 workflow scripts (.claude/workflows/factory-{triage,plan,implement,review}.js), 14 role agents (.claude/agents/*.md), and 4 dispatcher commands (.claude/commands/factory-*.md) • factory doctor — verify the harness contract (commands, gates, hooks, workflows, GitHub setup); exit 1 on any FAIL • factory rehearse — run the harness once on the runner before the first issue (ADR-025). See "Adopting a repo" below • factory bootstrap — labels, branch protection, required checks, FACTORY_TOKEN_ISSUED_AT (run it after the first git push). It also picks the merge-authority mode from the secrets it finds — see below

Secrets — two actors, two tokens (ADR-021). The factory wants merge power to be unreachable from any stage an agent runs in, by permission rather than by blocking command patterns:…

Description from the npm listing.