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

npx know-thy-build

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-<short>.md (or plan-<short>.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

Define:     :project → :technical → :qa setup
Per feature: :feature → [:designer] → [:architect] → :issue/:next → factory → ship

[ ] = optional, invoked when needed.

Phase 1: Project Definition (once)

/know-thy-build:project      What are we building and why?
/know-thy-build:technical    How do we build it? (stack, architecture, testing strategy)
/know-thy-build:qa           Set up the QA framework (environment, behavioral axes, test profiles)

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)

/know-thy-build:feature      Define the feature (problem, value, stories, AC, design intent)
/know-thy-build:designer     [optional] Deep UX analysis (heuristics, prototyping, accessibility)
/know-thy-build:architect    [optional] Code design for complex features (stubs, tests, agents)
factory (labelled issue → triage → plan → implement → review → merge)

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:

• FACTORY_BOT_TOKEN — the agent actor. A PAT belonging to a non-admin account (a machine user invited as a plain write collaborator). Scope repo only — never workflow: the workflow scope would let the agent push .github/workflows/<anything>.yml onto its own branch, and a workflow on a same-repo branch is handed the repository secrets, so the merge actor's admin PAT would leave the repo without anything being merged (ADR-021 r1 MF-2). Dropping it costs nothing: workflow changes go through a human-merged factory:harness PR, and the sweeper's gh workflow run (Actions dispatch) needs repo, not workflow. Every agent stage uses this token: checkout, comments, labels, lock branches, PR creation, pushing claude/* and factory/* branches.
• FACTORY_MERGE_TOKEN — the merge actor. An admin/owner PAT (scope repo) belonging to a different account. Store it as an environment secret, not a repository secret: gh secret set FACTORY_MERGE_TOKEN --env factory-merge (factory bootstrap creates the factory-merge environment, whose deployment branch policy is the default branch only, and the merge job declares environment: factory-merge). A repository secret is readable by a workflow running on ANY same-repo branch — that is the hole the environment closes. It appears only in script-only jobs (the merge stage, which never starts claude, and that job's credential-scrub step) — never in a checkout token or an agent step. A lint rule (merge-token-scope) enforces that across every file in .github/workflows/.
• CLAUDE_CODE_OAUTH_TOKEN (or ANTHROPIC_API_KEY) — the model credential.

With both actor tokens set, factory bootstrap requires 1 approving review from a code owner on the base branch (require_code_owner_reviews) and writes .github/CODEOWNERS naming the merge actor — commit and push it, GitHub reads CODEOWNERS from the base branch. Counting approvals alone was not enough: a write collaborator can approve any PR it did not author, so the identity of the approver has to be part of the rule (ADR-021 r1 MF-1). With it, no PR is mergeable with the agent's token — the one it authored because GitHub refuses self-approval, any other because the approval must come from the merge actor. The merge stage approves as the merge actor and then merges. The sweeper runs factory doctor's merge-authority checks under the bot token every 30 minutes, so tokens.agent-is-admin, tokens.agent-workflow-scope and protection.codeowners get real grades (they read WARN "unverified until CI" locally). With only FACTORY_BOT_TOKEN (single-actor mode — e.g. a private repo on GitHub Free, where branch protection is unavailable at all), everything still works but merge power stays reachable from agent stages and hooks are the only layer: factory doctor says so with a tokens.single-actor WARN on every run.

• factory run <stage> <issue> — run a stage locally with the exact scripts CI uses
• factory run <stage> <issue> --remote — dispatch the same stage as a GitHub Actions workflow run instead of running it locally (also restarts a stalled/blocked stage; merge accepted)
• factory run retro [--force] — run the merge-triggered retro job (light deterministic harvest every merge; full analysis + dark lessons/examples PR, human-approved proposal PR, or --force to skip the merge-count threshold)
• factory status — Needs You / queue / in progress / recent merges / usage (read-only)
• Live progress in the heartbeat comment (ADR-022) — a running stage edits one issue comment every 2 minutes with the current step, every agent's status and last tool, and tokens/cost so far, plus a machine-readable <!-- factory-progress:v1 {…} --> marker that also lands in docs/factory/runs/<n>.md when the run ends. It is read off the session transcripts the agents already write, never from tool results — so no file content or secret can ride out on a public comment.
• factory board — the viewer for all of that, across repositories. See below.

qa evidence — the contract, the tool, the probe (ADR-024)

The qa reviewer does not describe what it saw; it leaves the artifacts and cites them. One issue's evidence is one file — .factory/out/qa/<issue>/manifest.json (factory.qa-evidence.v1) — and the canonical way to write it is the shipped CLI (no dependencies, installed by factory init). Five subcommands:

node .factory/bin/qa-evidence.js probe  --issue 42
node .factory/bin/qa-evidence.js record --issue 42 --claim dw2 --summary "export writes the header row" -- npx vitest run test/export.test.js
node .factory/bin/qa-evidence.js attach --issue 42 --claim dw3 --kind screenshot --file /tmp/export-dialog.png --summary "the dialog the user actually sees"
node .factory/bin/qa-evidence.js na     --issue 42 --claim dw5 --reason "this tier has no UI surface"
node .factory/bin/qa-evidence.js finish --issue 42

The 42 is a placeholder, and the tool will not catch you for leaving it there. The --issue number must match the issue the current checkout's .factory/out/context.qa.json / .factory/out/context.json was generated for: that file — not the flag — is where finish reads the done_when contract it grades the manifest against (stageContext in .factory/bin/qa-evidence.js). It never compares the two issue numbers, so in a checkout that is mid-review for issue 18, finish --issue 42 silently prints issue 18's coverage table and spec-evidence-missing: verdict — no error, and nothing in the output says whose contract it just used. Replace every 42 above with the issue you are reviewing before you run anything. A mistyped number also leaves litter: record/attach/na never clean up, so .factory/out/qa/<that number>/ stays in the repo (only probe removes the directory it created).

Trying the five lines on their own? The last one exits 1 — that is the tool working, not a defect in the demo. Outside a live review there is no .factory/out/context.qa.json / .factory/out/context.json in the checkout (right after factory init, or in a plain clone, there is none), so finish has no done_when contract to grade the manifest against and says exactly that: coverage: INCOMPLETE — done_when could not be resolved — coverage is undecidable, then factory: qa evidence not acceptable — done_when could not be resolved …, exit code 1. It is rejection rule 2 below, met early and harmlessly — nothing was judged, nothing is reported to any issue, and a manifest whose contract cannot be read is not a complete one. Inside a review stage (where the factory wrote that context file before the qa reviewer started) the same line reads that real done_when contract and grades the manifest against it. It prints the coverage table and exits 0 only when every done_when id is covered — by a passing record/attach claim or a justified na; any id left uncovered makes it exit 1 with spec-evidence-missing: <ids> (rejection rule 1), the same verdict lines 128-129 show for a mistyped issue. So the five lines above, run as-is, do not finish green: they cover at most dw2/dw3/dw5, and a real issue's done_when has other ids. finish reports what is still missing and rejects — that, not a clean exit, is the steady state until the qa reviewer has left a claim for every id. The only thing the walkthrough leaves behind is .factory/out/qa/42/: remove it when you are done.

• record runs a command for real and stores its stdout, stderr and exit code as one claim (secrets are scrubbed before the file is written, and the payload after -- is judged by the same hooks a direct Bash call would hit — the tool is not an escape hatch).
• attach takes in a screenshot, a state dump or a log you already have (binaries are copied byte for byte).
• na closes an id with a reason — an exemption without a reason is a gap, not an exemption.
• finish prints the per-done_when coverage table and fails if the manifest does not meet the maturity minimum (M0 a command or log per id · M1 a state claim when the impact paths touch data · M2 a screenshot per UI-facing id).
• probe asks the one question that used to be asked too late: can this session write there at all?

The probe runs before the review, not after it. The review stage runs probe right after the overlay and before claude -p whenever the roster contains qa. If the evidence path is broken, the outcome is not a builder reject and not a RED review — it is factory:blocked with cause undecidable, because nobody has judged anything yet. (KTB #3 burned 8 implement rounds on spec1: qa evidence missing while the defect was a deny rule; "the directory is empty" is now a forbidden phrase in a reviewer's verdict.) factory doctor asks the same question as qa.evidence-probe.

Three things get a qa round rejected, each by name rather than by "evidence missing":

1. An all-na manifest — when every done_when id is not_applicable, that is a report, not a review; a roster carrying qa means at least one id was meant to be reproduced.
2. An unresolvable contract — when the plan handoff's done_when could not be resolved, coverage is undecidable, so the round is graded factory:blocked/undecidable rather than passed.
3. An out-of-bounds attach — when attach --file points outside the repo (and the temp dirs), or the path matches this session's own Read(...) deny rule, the tool refuses: the factory will not copy a file it is forbidden to read into a public handoff.

What the manifest does not claim: it is not a proof of authorship. The qa role can write there by design, so qa_manifest=<sha256> on the run record proves "a valid manifest for this commit existed at review time and has not changed since" — not "the tool produced it". The contract buys cost and visibility; the roster buys trust.

When a person merges a protected-path PR (KTB-46)

A PR that touches a protected path (.factory/**, .claude/**, .github/**, docs/factory/CHARTER.md, the build config — the [protected] block of .factory/harness.toml is the single source) is never auto-merged. The merge stage refuses with protected paths changed — human merge required and the issue goes to factory:needs-human. Then:

1. You merge it on GitHub, by hand, after reading the diff. That is the whole manual step.
2. You do not touch the labels. Within one sweeper pass (≤ 30 min) the sweepHumanMerged arm finds the issue, finds the merged PR on claude/fq-<n>, and moves it factory:needs-human → factory:merged, closing it if Closes #n did not (KTB-46, spec §12.3-2).
3. The evidence is not waived — only its source is. Before that transition the sweeper re-asks, with the same functions the auto-merge path uses: the merged PR's head sha equals the latest review handoff's head_sha (otherwise the merged PR belongs to an earlier cycle and it stays quiet); this head really reached factory:approved; the review quorum is all-approve over the roster resolved at the handoff's tier_effective, within limits.K; and the factory-posted commit statuses plus every required check in [factory].required_checks are green on that head, posted by the factory's own logins. Any of those missing leaves the issue in needs-human with one refusal comment — the sweeper will not repeat itself for that PR.

Two checks this door does not re-derive (KTB-48, plan task 12): ① the factory/records provenance cross-check against the review run record (auto-merge's §(6b)), and ② the re-comparison of that record's qa_manifest= digest against the handoff's manifest. The sweep job has no records checkout. Everything else is the same as an auto merge; KTB-48 covers both and the "not re-derived" sentence goes away when it lands.

And a :unstick retry after K currently buys nothing (KTB-47, plan task 11): a human retry resumes at the label the issue came from and the extra round, even when it approves 4/4, is refused at the merge stage's review round > K check — so the run ends in a human merge anyway. Until KTB-47 lands (resume at factory:rework, and K_effective = K + one round per human retry), treat a K-exhausted issue as one you will merge yourself.

Adopting a repo: install → doctor → rehearse → first issue (ADR-025)

factory doctor PASS means the harness is coherent, not that its commands run on the runner — it is a static check (--no-run/--offline), and --run runs the commands on your laptop, with your PATH and your toolchain. The first repo adopted after that distinction was noticed (own-calendar, 2026-09-14) paid for it with three dark rounds, one defect each: [runtime].setup never installed the toolchain so the gate exited 127; analyze exited 1 on pre-existing infos; test_files/test_one were handed repo-root-relative paths after the harness did cd client. None of the three is visible anywhere but a runner.

npx know-thy-build factory rehearse      # dispatches factory-rehearse.yml, waits, prints the table

The job runs what a stage runs, with no issue, no labels and no claude -p: lint (whole repo) · unit (full) · test_files on a real file from [test].test_glob · test_one on a real test name from that file · lint_file on a source file · a write probe into .factory/out/qa/ · the no-write clean check against the setup baseline · the prove-test machinery (base worktree + dependency install) · gh api user, the label list and a git push --dry-run to a scratch branch. Every step is timed and capped; one RED does not stop the rest — the three-round bill came from finding the defects one at a time. The verdict is one markdown table in the job summary and in .factory/out/rehearsal.json (uploaded, scrubbed, 7 days).

A GREEN rehearsal writes FACTORY_REHEARSED = sha256(harness.toml + CHARTER frontmatter) as a repo variable and — where variables need admin, which is the normal case under the two-actor setup, since the workflow holds a non-admin bot token — as a factory/rehearsal commit status on the fingerprint commit: the last default-branch commit that touched .factory/harness.toml or docs/factory/CHARTER.md. (Not the branch head: that moves on every unrelated merge, which would orphan the record and shut the queue from the first merge onward.) Both sources are read and either may open the queue; if neither matches, the queue stays shut.

transition.js refuses → factory:queue — for scripts and for people — while that record is missing or its hash no longer matches: harness changed since the last rehearsal — run factory rehearse. The check is opt-out, not opt-in: a queue transition needs a wired checker (the human CLI, the sweeper's harness unpark, the merge stage, the flaky harvester all wire it) or an explicit test-only bypass, and refuses without one. The job itself only runs on the default branch, and a recording failure makes the run RED — factory rehearse says "not recorded — queue stays closed" and exits non-zero rather than claiming the queue is open. factory doctor says the same thing as rehearsal.current (PASS / WARN when never rehearsed / FAIL when stale), and a push to the default branch that touches .factory/harness.toml or docs/factory/CHARTER.md re-runs the rehearsal by itself.

factory board

npx know-thy-build factory board                                   # the current repo, http://127.0.0.1:4173
npx know-thy-build factory board --repo owner/a --repo owner/b     # several repos in one board
npx know-thy-build factory board --port 8080 --interval 30         # bind elsewhere / poll faster
npx know-thy-build factory board --once --json | jq .issues        # one snapshot for a script

A local, read-only viewer of every issue the factory is carrying (ADR-022 Task B). Three views:

• 레인 보드 (lanes) — a column per state in graph order (queue · ready · planned · in-progress · awaiting-review · approved · merged) with side lanes for needs-human / blocked / needs-info. Each card carries the stage, the elapsed time in that state, a freshness dot (heartbeat fresh < 5 min · stale < 30 · dead — the same 30 minutes the sweeper calls stale), the current step, a mini agent table (label · status · last tool · in/out tokens), cost so far, a link to the Actions run, and the last handoff one-liner. Several issues running at once are several cards; several repos put a repo chip on each card and a repo filter in the header.
• 타임라인 (timeline) — one row per issue, x axis 6h / 24h / 7d, one bar per stage coloured by state. Retries show as a second bar in the same state with the blocked gap between them; hover gives the exact durations.
• 상세 패널 (detail) — click a card for the full transition list with per-state durations, every agent with tokens and cost, the files touched, and the links.

Where the data comes from. Nothing new is written: state is the label, "since when" is the transition comment, "is it alive" is the heartbeat's first line, "what is it doing" is that comment's factory-progress:v1 marker, "how much" is the usage: lines on the factory/records branch, and "which job" is gh run list. Every GitHub call goes through your own gh CLI — the board never reads, stores or prints a token, which is why private repos just work.

Two ways to open the page. docs/factory/board/index.html is installed by factory init and is the very file the CLI serves — no build step, no CDN, no external request at all.

The CLI server binds loopback only. /api/board and /api/events carry no authentication, so --host accepts only 127.0.0.1, localhost or ::1 (ADR-022 decision 1) — anything else is refused (exit 2) rather than quietly publishing issue titles, handoff summaries and cost to the network.

| | CLI mode (factory board) | Static mode (file / GitHub Pages) | |---|---|---| | data | /api/board + SSE push on change | api.github.com direct, ?repo=owner/name | | auth | your local gh (private repos work) | unauthenticated (60 req/h, remaining quota shown) or a personal token kept in localStorage only | | cost | finished runs (records branch) + live run | live run only — the chip says live | | polling | every --interval seconds (default 60) | 10 min without a token, 2 min with one |

The reduced static model is deliberate: implementing the same cost sum twice is how "live $0.41 / final $0.38" happens (ADR-022 decision 5). Static mode also guards its own call budget: it skips a pull entirely once the remaining quota drops to 3 or below (showing when it will retry), and only fetches comments for issues updated in the last 24 hours — the rest render from labels alone, flagged stale-data. The page's header help says all of this in the UI.

Design and rationale: docs/superpowers/specs/2026-09-10-factory-design.md · decisions: docs/factory/DECISIONS.md

Watching a run — factory analyze

The board answers "where is it now". When a run has already failed, the question is "why", and that answer used to live in five to seven places: the FACTORY_GATES: line on the records branch, the gates-detail: line beside it, the self-gate retry comment, the transition-refused comment, the review handoff, and the usage: line. factory analyze prints all of it as one timeline.

npx know-thy-build factory analyze 39           # that issue's whole run, stage by stage
npx know-thy-build factory analyze 39 --json    # the same data, for a script
npx know-thy-build factory analyze --health     # the aggregated behavioural signals

A stage-run is one execution of one stage, identified by its run id — not one appendRunRecord call. A single run appends many record sections (demo #20's record has 11 sections for 3 runs), so they are grouped back together and the cost of every agent call in that run is summed. Per run: the stage, runner and run id, the artifact pointers, the FACTORY_GATES summary plus each failing gate's detail (the failing test names, the exit code, whether the report parsed, and the head of the output snippet), the self-gate result (ran / skipped / blocked, and the KTB version that judged it), the per-role context manifest (what each reviewer was actually shown — the way a starved role becomes visible), and the cost both for the run and per agent.

Everything else — transitions and their refusals, review verdicts with every must_fix, self-gate retries, human decisions — lands in a single chronology, each line placed by its own timestamp alongside the run starts. An event is attributed to a run only when it actually carries that run's id (heartbeats do; a transition comment does not), because a guessed attribution sends you to the wrong run's logs.

Then the findings, classified by the very same functions the retro uses on merge (harvestFindings + classifyFinding) — so a [ktb] tag here is a prediction you can trust: it is the issue the retro would open upstream. Each finding carries its tags, causal path and owner, its attribution evidence, and its fingerprint. Evidence lines that no heartbeat binds to a real run are shown flagged UNBOUND and counted, because harvest ignores them — "no findings" and "no findings we were allowed to read" are different answers.

── 2. implement · 2026-09-20T10:08Z → 2026-09-20T10:41Z · gha-99001 (run 99001)
   3 record sections appended by this run
   FACTORY_GATES: level=fast status=RED passed=1 failed=1 failing=unit …
   gate unit: RED (exit 1, report parsed)
     failing: plan roster contract > carries the debate roster
   self-gate: BLOCKED · ran=gates,contract · ktb 1.3.2
   cost: $5.45 · 131.0k in / 17.2k out · 42 turns
     agent builder:impl (subagent/done): $3.51 · 90.0k in / 12.0k out · 30 turns

── chronology (an event is attributed to a run only when it carries that run's id)
   2026-09-20T10:08Z    ▶ stage-run implement starts · gha-99001 (run 99001)
   2026-09-20T10:44:00Z transition REFUSED: factory:in-progress → factory:awaiting-review — plan roles [synthesizer,skeptic] != roster []

Findings · 3 (2 the retro would route)
   [ktb] transition-refused — plan roles [synthesizer,skeptic] != roster []
       causal: .factory/lib/requirements.js · owner=factory · high confidence · routed

It never needs an Actions artifact. Everything above is read from the factory/records branch and the issue's comments, both of which are durable — so a run from three months ago reads exactly like this morning's, long after the 7-day artifacts expired. It also does not need a local clone of the records branch: the default read is a single gh api …/contents?ref=factory/records call, so it works from a laptop. Read-only, like factory status — it opens no issue, writes no comment and moves no label.

Roles

Project — What & Why

/know-thy-build:project

Socratic conversation that explores: Problem, Persona, Competitive Landscape, Vision, Output, User Journey, Boundaries, Success, Risks, Principles.

Also generates a Development Workflow in CLAUDE.md — the orchestrator model that enforces multi-agent review for all implementation.

Result: docs/PROJECT.md

Technical — How

/know-thy-build:technical

Requires docs/PROJECT.md. Explores: Tech Stack (with structured comparison research), Architecture (with Component Responsibility Map), Data, Interfaces, Testing Strategy, Error & Resilience, Constraints.

Every significant decision is recorded as a Technical Decision Record (TDR) — context, options, decision, rationale, consequences, validation method. Includes a Technical Adversarial Review (Minimalist, Operator, Future Developer) and Risk-First Validation.

Result: docs/TECHNICAL.md

Feature — Specific Work

/know-thy-build:feature

References both docs/PROJECT.md and docs/TECHNICAL.md. 3-pass exploration:

• Pass 1: Problem → Value → User Stories → Solution → Scope
• Pass 2: Acceptance Criteria (Given-When-Then → AC → edge cases → verification)
• Pass 3 (UI features): Design Intent Map (action → outcome → decision → QA verification)

Result: docs/features/NNN.md

QA — Test the Product

/know-thy-build:qa

Produces and maintains docs/QA.md — the single source of truth for all testing.

Three modes:

| Mode | When | What | |------|------|------| | SETUP | After :technical | Build QA framework: environment, tools, behavioral axes, test profiles, failure injection methods | | REVIEW | After each :feature | Define executable test cases per feature — this IS the definition of "done" | | TEST | After implementation | Actually run the product, execute test cases, capture evidence |

Research-grounded approach (PersonaTester FSE 2026, τ-bench CMU 2026, VISTA 2026):

• Behavioral Testing Axes instead of character personas — orthogonal axes (Mindset × Strategy × Habit × Cooperation) combined into test profiles
• Turn-level behavior instructions instead of narrative descriptions — "3초 안에 반응 없으면 새로고침하라" not "act like an impatient user"
• Failure State Injection — network failure, resource deletion, session expiry, concurrent mutation (+42% unique failures vs UI-only, VISTA 2026)
• QA Self-Check — metrics to prevent "easy mode" (scenario diversity, unique failures, cooperation drift)
• Insight Synthesis — patterns, failure taxonomy, actionable recommendations (not just pass/fail)

Result: docs/QA.md

Designer — User Experience (Deep Dive)

/know-thy-build:designer

Optional. For features with complex UI that need deeper analysis than the feature's Pass 3 Design Intent.

Produces a Design Intent Map — every user action traced to the design decision that enables it. Includes flow decomposition, state catalog, visual direction, prototyping, Nielsen heuristic evaluation, accessibility audit, cognitive walkthrough.

Anti-Slop Protocol — explicit list of AI-generated design clichés to avoid.

Result: ## Design section in the feature spec + prototype artifact(s)

Architect — Implementation Design

/know-thy-build:architect

Optional. For Architectural features (new subsystem, multi-component, structural change). Uses Program Sketching — creates code scaffolds with Design by Contract comments (PRE/POST/WHY/EXAMPLE) and signature tests, then orchestrates agents.

Includes CRC Cards, Adversarial Review (Minimalist/Implementer/Skeptic), Over-Specification Prevention, Hardest-First Vertical Slice.

Result: Code stubs + test suites + ## Architecture Notes in feature spec

Multi-Agent Development Workflow

When you run /know-thy-build:project, it generates a Development Workflow in your CLAUDE.md. This workflow enforces:

User Session (Orchestrator only — never implements directly)
│
├── Dispatches Implementation Agent
│   ├── Pre-work: reads PROJECT.md, TECHNICAL.md, feature spec, QA.md
│   ├── Implements within defined scope
│   │
│   └── Post-implementation Review Loop
│       ├── Designer Review Agent (Design Intent verification)
│       ├── Architect Review Agent (code quality, patterns, structure)
│       │   └── Both must pass before QA begins
│       └── QA Review Agent (runs the product, executes test cases)
│           └── All test cases must be ✅ with evidence
│
└── Loop until all reviewers pass → Feature complete

Documents Produced

| Document | Created by | Purpose | |----------|-----------|---------| | docs/PROJECT.md | :project | Project identity, persona, vision, principles | | docs/TECHNICAL.md | :technical | Tech stack, architecture, TDRs, testing strategy | | docs/QA.md | :qa | Test environment, behavioral axes, test cases, results | | docs/features/NNN.md | :feature + :designer + :architect | Feature spec, design intent, architecture notes | | CLAUDE.md | :project | Project compass + development workflow | | Code stubs + tests | :architect | Implementation scaffolds |

Evolution

All documents support evolution. Run the same command again on a completed document:

| Command | On complete document | Effect | |---------|---------------------|--------| | :project | docs/PROJECT.md | Evolve mode — what changed and why | | :technical | docs/TECHNICAL.md | Evolve mode — update TDRs, re-run adversarial review | | :feature | docs/features/NNN.md | Edit by number | | :qa | docs/QA.md | Re-test after changes, regression check | | :designer | ## Design section | Update design, re-verify |

Changes are tracked with reasoning in a changelog — not just what changed, but why.

Migration from v0.3.x

If you have existing PROJECT.md, TECHNICAL.md, or features/ at your project root, they will be automatically moved to docs/ the next time you run any /know-thy-build:* command. References in CLAUDE.md are updated automatically.

Session resilience

All conversations track state in document frontmatter. If a session breaks, run the same command again — it picks up where you left off.

| status | What it means | |-----------|---------------| | drafting | In progress — will resume | | complete | Done — running again enters evolve mode | | evolving | Evolve in progress — will resume |

Install options

npx know-thy-build              # Install in current project
npx know-thy-build --global     # Install to ~/.claude/commands/ (all projects)
npx know-thy-build --lang ko    # Skip language prompt (Korean)

Supported shortcuts: en, ko, ja, zh, es, fr, de, pt — or pass any language name directly.

All conversation and generated documents use the chosen language. Technical terms stay in English.

Foundations

know-thy-build draws on established techniques from philosophy, software engineering, and AI research.

Socratic Prompting

The tool applies the Socratic method — questioning to surface latent knowledge. In Plato's Meno, Socrates demonstrates that learning is recollection: the right questions draw out what the learner already knows. know-thy-build operates on the same premise — you already know what you want to build, you just haven't articulated it yet.

• Chang, "Prompting Large Language Models With the Socratic Method" (2023)
• Princeton NLP, "The Socratic Method for Self-Discovery in Large Language Models"
• SocraticLM (NeurIPS 2024 Spotlight)

Dialectical Reasoning

Each exchange follows a thesis-antithesis-synthesis cycle. This is Hegelian dialectic applied to project definition.

• "Self-reflecting LLMs: A Hegelian Dialectical Approach" (2025)

Requirements Elicitation

Requirements elicitation is the process of discovering what stakeholders actually need — requirements are discovered, not merely captured.

• Zave & Jackson, "Four Dark Corners of Requirements Engineering" (1997, ACM TOSEM)
• "AI-based Multiagent Approach for Requirements Elicitation and Analysis" (2024)

Behavioral Testing Research

The QA framework is grounded in 2026 research on AI agent-based testing:

• PersonaTester (FSE 2026) — orthogonal behavioral axes for test persona definition
• Mind the Sim2Real Gap (CMU 2026) — LLM simulators inflate success rates vs human baselines
• VISTA (2026) — QA quality self-measurement, failure state injection (+42%)
• NCUser (ICLR 2026) — non-cooperative user axes
• Persona Policies (UW 2026) — turn-level behavior instructions outperform character descriptions
• CANDOR (TOSEM 2026) — role separation: oracle accuracy requires requirement understanding

Multi-Agent Debate

know-thy-build adopts multiple perspectives through specialized roles (project, technical, feature, designer, QA, architect) — each with its own adversarial review protocol.

• Liang et al., "Encouraging Divergent Thinking in Large Language Models through Multi-Agent Debate" (EMNLP 2024)

Design Thinking

The output maps to the Define phase of Design Thinking (Stanford d.school).

License

MIT