build

name

build

description

Run the autonomous build loop that drives a system-design spec to shipped features — optional spec-authoring front (spec-writer → review-spec gate → clarifications) → initiator (roadmap) → executor (TDD) → evaluator (judge) → whole-spec panel → commit, looping per Success Criterion. Use when asked to build the app, run the loop, or turn a list of requirements/todos into shipped features. The orchestrator is the main session (bootstrap) + a Workflow (the SC-stream), NOT a sub-agent.

build — the autonomous build loop

The orchestration playbook. Drives a from-zero project — or a fresh list of requirements — to shipped features on the spec → plan → execute rails, with the human gate kept only on the core/product spec approval, the bootstrap glance, and any blocking spec clarification the review gate surfaces.

Two entry points feed the same loop:

• An Approved spec already exists → skip straight to the loop (§"The loop").
• The author arrives with raw requirements / todos (docs/todo.md or an inline list) → run the optional spec-authoring front first (§"Optional front") to turn them into reviewed, Approved specs, then fall into the same loop.

Who drives (the orchestrator is NOT a sub-agent)

A Claude Code sub-agent can't spawn sub-agents, so the driver lives at the top level:

• Bootstrap (zero → green skeleton): the main session drives it interactively — the author watches the project skeleton + the verify-gate growth land in one commit.
• The SC-stream (the per-feature loop): a Workflow drives it hands-off — deterministic, resumable; it dispatches the workers below.

Inputs

• docs/ui-ux.md — product spec (WHAT: budgets, scenarios, fixed decisions).
• docs/<feature>_system_design.md — per-feature system designs (HOW: Success Criteria + the ## Tests acceptance intent).
• docs/todo.md — the request inbox: the author's raw, un-shaped requests. The optional front turns the agreed ones into specs (single-writer-per-fact: a promoted item leaves todo.md).

Optional front: from a request list to Approved specs

Use this only when no Approved spec exists yet for the work — the author shows up with a list of requirements / todos instead of a spec. It is the spec-authoring stage of the operating model (product spec → system-design spec → plan), made autonomous with a quality gate. When a spec is already Approved, skip this entirely and go to "The loop".

1. Triage → roadmap. initiator reads the product spec + existing specs + the agreed items in docs/todo.md, and writes/updates docs/roadmap.md: each feature ordered by dependency, marked needs spec or pointing at its spec. (It links, never copies SC detail.)

2. Author each needs spec item — the draft→review→fix loop. For each, dispatch a spec-writer (generator): it drafts to the template and self-reviews adversarially (review-spec) in an inner loop, returning a provisional verdict + unverifiedClaims. Fan this out — spec-writing is the canonical safe-parallel case (disjoint docs/*.md, no shared resource; see "Parallelism").

3. Independent gate. A separate spec-reviewer (read-only, Bash-grep-backed) runs review-spec over each draft — verifying the seam/reference/cross-spec claims the writer couldn't, judging against the fixed product invariants. It returns not-ready | ready-with-fixes | ready-to-approve

   • blockers + numbered clarification questions. (Generator–evaluator split: the writer is never the sole judge of its own spec.)

4. Clarification batch — the human gate. Collect every [blocking] question across all specs and present them to the author once, as a batch. A hands-off Workflow cannot answer these — it stops here and surfaces them. The author answers → spec-writer incorporates → re-gate.

5. Approve — a main-session (human-gated) action. Drive Approval off the independent verdict:

   • ready-to-approve (no blockers, no live [blocking]) → auto-approves as a spin-off: flip to Status: Approved and commit it, so veto is timely.
   • ready-with-fixes (only warnings, no blocker) → surfaced for a quick author glance — approve as-is or polish the warnings first; it does not silently auto-approve.
   • not-ready (a blocker / live [blocking]) → waits on the step-4 clarification batch.

   When the front runs as the author-specs Workflow, the Workflow only writes the Draft specs and returns the verdicts + clarification batch; the main session does the Status: Approved flip, the commit, and the per-spec build-feature launch (a hands-off Workflow can't take the approval / clarification call).

6. Hand to the loop. Each Approved spec drops into "The loop" below (per-feature, the build-feature Workflow).

WHY a review gate in front (and not blind auto-approval): auto-approval must be earned — a spin-off still auto-approves, but only once it converges through the independent gate; genuinely blocking unknowns become a clarification batch instead of a silently half-baked Approved contract.

The loop

0. Bootstrap (once, main session). No stack exists yet → stand up the skeleton from the spec (your stack), the test runner, and grow the verify gate into one command ([verify command]: docs guardrails + lint + typecheck + tests). Eyeball that commit — it is the success oracle every later "green" depends on.
1. initiator → reads the input docs → a feature-level roadmap (docs/roadmap.md: ordered, done/not), each item linked to its spec. SC-level detail stays in each spec's ## Tests table.
2. For each roadmap item, until done:
   • No Approved spec? → run the Optional front above.
   • Plan stage (optional, complexity-gated). Before the executor, a plan-writer drafts the feature's EXECUTION plan (file-by-file changes, step order, the TDD sequence per SC, any chained artifact linearized onto the live head, seam-reuse confirmation — the HOW-in-what-order, not a re-statement of the design), and a plan-reviewer (read-only, grep-backed) gates it via a bounded fix loop. The plan is ephemeral (never committed) and handed to the executor as an advisory blueprint — a clean, distilled context, not token thrift. ON by default for multi-SC features (≥3 SCs), OFF for thin ones; its hit-rate is logged (planReview in the Workflow return) so the stage is defaulted OFF if it rubber-stamps (the per-SC-evaluator precedent).
   • executor → plans its own TDD steps (ephemeral, refining the plan-stage blueprint when one was produced) then Red→Green→Refactor; strict test-first on the core invariants, tests-after on thin glue. Task + context are passed to it. Mocking heavy/slow/expensive calls in the fast tests is encouraged, but per the one-real-test rule (docs/agent_rules/testing.md §1/§8) every mocked external boundary also needs 1–2 real live-marked tests — kept light/cheap. Never mock a call path whose real adapter has never run green.
   • evaluator (full cycle only — optional; default OFF) → independent judge vs the SC + budgets + dependency rules; for live flows, the ui-verify skill. request-changes → back to executor (bounded retries); verified → advance. Empirically a near-rubber-stamp in the source harness (verified 35/35 across 19 features), so the abridged cycle skips it and leans on the verify gate + the whole-spec e2e gate (which re-exercises every SC through the real seam) as the per-SC oracle.
   • Commit each verified SC. This is the inner gate (per-SC, narrow, fast).
3. Whole-spec acceptance — evaluator-spec (the "big" judge), once a feature's SCs are all green. The outer gate the per-SC pass structurally cannot be: does the FINISHED feature satisfy the whole spec as a coherent system (cross-SC integration, end-to-end flows, budgets on the assembled path, spec intent)? Run evaluator-spec as an adversarial panel — N instances, one per lens (end-to-end/live-flow · integration/contracts · security/privacy · UX/budgets · [your domain lens]), each handed the full project docs dynamically (the caller picks which to pass; the agent is doc-agnostic). Verify each finding with a separate skeptic agent (kills false positives; the abridged cycle skips it and trusts the panel raw — faster, but a false positive can drive a wasted fix), then route confirmed blocking/major findings to executor for a fix round (re-run the gate on the result). The panel itself (lenses + the e2e gate) is never optional — only the skeptic and the per-SC evaluator are.
   • Loop policy: iterate evaluator-spec until convergence OR a hard cap of 5 iterations, whichever comes first — only then tick the roadmap item done. Convergence = a full-coverage round (all lenses succeed, zero dropouts) that finds zero new confirmed blocking/major. Each round dedups against already-fixed findings (tell the panel what's landed; it flags only genuinely new issues) so the loop actually converges instead of re-litigating. A round with any dropped lens can't be declared clean → it re-runs (so coverage gaps never fake a "clean"). If the cap is hit while real majors remain, surface them — don't loop forever.
   • Run the panel full-parallel (all lenses at once); the loop tolerates the occasional API-throttle dropout via the re-run rule above.
   • evaluator-spec is a separate agent from the per-SC evaluator — the inner gate stays untouched, and neither context pollutes the other.
   • Real-render gate: a user-facing feature is not accepted on backend seams. The end-to-end / live-flow + UX/budgets lenses MUST drive the rendered client via ui-verify and rule on a screenshot (docs/agent_rules/testing.md §5). Endpoint-green / route-200 / JSON-correct is the seam, not the UX; a render nobody screenshotted is a blocking finding, and pipeline_works is false until every user-facing SC has a clean real-render screenshot.
   • Panel agents are read-only and run in parallel; but any lens driving a browser / computer-use serializes (one browser/screen — see Parallelism below).

Parallelism — quality first; it's a throughput tool, not a goal

The objective is the most correct, highest-quality result, never merely the fastest. Parallelism earns its place only when tasks are genuinely independent, and it never justifies a worse outcome. Default to sequential; fan out only when all three hold:

1. File-disjoint — the streams don't edit the same files. A shared foundation (one core, one schema, one data model) is coupled: its pieces extend the same modules, so they run sequential, shared-tree — each step builds on the prior committed-green state. Forcing them parallel trades minutes saved for merge-conflict + re-verify pain (a net loss).
2. No shared exclusive resource — two tasks that both drive one stateful runtime can't run at once; they fight over it. Concretely: anything using a browser or computer-use (one browser, one screen) must serialize — parallel UI-verification corrupts both runs. Same for any other singleton: a fixed dev-server port, a non-isolated shared DB, an interactive login.
3. Not tightly coupled / delicate — when the parts inform each other, sequential keeps the reasoning coherent and the quality high. Splitting it just to parallelize degrades the result.

Where parallelism is genuinely safe and worth it:

• Spec-writing — spec-writer across all needs spec roadmap features at once: pure disjoint docs/*.md, zero conflict, no shared resource. Always fan this out.
• File-disjoint feature implementation — thin clients and self-contained modules → parallel worktree-isolated streams (isolation: 'worktree'), then a sequential reconcile stage that merges and re-runs the gate on the merged tree ("green in a worktree" ≠ "green on the trunk"). Work that touches a shared chained artifact (e.g. a linear migration chain) → keep it coordinated, not concurrent.

When in doubt, run it sequentially: a correct, coherent build beats a fast, tangled one.

Evaluator feedback log (auditable in git)

Every evaluator verdict is persisted to an append-only log beside the spec, so the author can read — straight from git log — what the judges flagged and how the executor fixed it.

• One log per feature: docs/<feature>_evaluator_feedback.md, sibling to docs/<feature>_system_design.md. It is an event-genre artifact — append-only rounds (## Round N …), never rewritten — not a spec.
• Per-SC evaluator (inner gate) appends and commits its own round — it runs sequentially, so there is no append race. Both request-changes and the closing verified are logged.
• Whole-spec evaluator-spec (outer gate) runs as a parallel panel, so its lenses must not each write the file (concurrent appends would race). The lenses return findings; the orchestrator consolidates the round into one block and persists it with a single writer (dispatch one spec-writer append — it is the docs-write-scoped agent), then commits once.
• The flag→fix story in history: each docs(feedback): commit sits right before the executor's fix commit (whose message references the round), so git log reads feedback → fix → re-judge per round.

Commit policy (automatic — no prompt)

Every checkpoint commits itself; nothing waits for a human (so the build survives a crash, a context reset, or compaction — state lives in git, not the session). Four points:

1. Spec lands → docs(specs): … — after initiator writes roadmap.md, and after spec-writer writes + auto-approves a feature spec.
2. Evaluator round lands → docs(feedback): <feature> <scope> round N (<judge>: <verdict>) — pathspec-scoped to the feedback file so nothing else is swept in.
3. executor checkpoint (on the feature branch) → after the first green implementation, and after each requested fix (commit message references the feedback round it addresses). Each is a recovery point.
4. verified → merge to the trunk → squash-merge the branch as one clean feat: … commit. Trunk = verified only, always shippable.

Branch-per-feature + squash keeps granular recovery on the branch and a clean milestone history on the trunk. (Solo-simple alternative: commit straight to the trunk per checkpoint — no branches, messier history.)

Auto-commit needs the git write commands in the allow-list (git add · git commit · git switch · git checkout -b · git merge); the deny-list (force-push / hard-reset) stays, so recovery uses git revert, never a destructive reset. Until those are allowed, each commit prompts for approval.

Gates kept

• Core + product spec approval — human.
• Bootstrap commit — author glances.
• Spec readiness — the spec-reviewer independent gate must return ready-to-approve before a spin-off spec auto-approves; a blocking clarification surfaces to the author (the front's human gate).
• Spin-off feature-specs — auto once they converge through that gate (veto post-hoc).
• Every increment — the verify gate must be green.
• Every user-facing increment — a ui-verify real-render screenshot was opened and ruled clean. No screenshot ⇒ not verified.
• Every finished feature — the evaluator-spec adversarial panel must come back clean (outer gate), including its real-render gate on every user-facing surface.

Launch

• From a request list → the main session drives the Optional front — it builds the roadmap (initiator) and dispatches the spec-writer + spec-reviewer gate (directly, or by launching the author-specs Workflow for the parallel fan-out). The front stops and surfaces the clarification batch; you answer; the main session flips the converged specs to Status: Approved and commits them; then it launches the build-feature Workflow per Approved spec. The author-specs Workflow itself only authors + gates and returns verdicts — it never approves, commits, or launches.
• From an Approved spec → the main session drives bootstrap (first run), then asks the two launch questions below and launches the build-feature Workflow hands-off. When Approved specs (and a roadmap listing them) are handed in directly, the whole spec-authoring front AND initiator are skipped — they are the optional "step 0"; the loop starts at build-feature per spec.

Two launch questions (ask once, then go silent)

Before launching the (long, silent) build-feature Workflow, the main session asks the author exactly two things via AskUserQuestion, maps the answers to Workflow args, and then runs hands-off — no further prompts until it returns:

1. Cycle depth — full or abridged? Sets fullCycle (the Workflow expands it to perScEval + skeptic; both also overridable individually):
   • Full → {fullCycle: true} — per-SC evaluator ON + skeptic ON. Maximum scrutiny, maximum cost.
   • Abridged → {fullCycle: false} — both OFF: no per-SC pass, and panel findings drive fixes unverified (faster/cheaper; a panel false positive can cause a wasted fix).
   • Lean (recommended default) → omit fullCycle (or {skeptic: true, perScEval: false}) — drops only the near-useless per-SC eval but keeps the high-signal skeptic. Best cost/signal ratio.
2. Iteration budget — 1 / 3 / 5 / converge? Sets the acceptance-loop cap (and the e2e backstop): 1→{maxIters:1, e2eBackstop:1}, 3→{maxIters:3, e2eBackstop:3}, 5→{maxIters:5, e2eBackstop:5}, converge→{maxIters:8, e2eBackstop:8} (loops until a full-coverage round finds zero new confirmed majors, with a generous safety cap).

Required args (set once, not questions). verifyCommand — the repo's verify gate in strict mode (a down dependency FAILS the gate, never skips). Optional: invariants (the fixed product invariants, as strings), lenses (the panel's specialist lenses for this product), migrationHeadsCommand / liveTestsCommand (if the repo has a chained artifact / live boundaries).

Model/effort split (optional, not a question). The Workflow runs roles on different models: heavy generative work (implement + fix rounds) on the strong model at high effort, read-only judges on a cheaper model at max effort, the mechanical gate cheap+low. Defaults: execModel = inherit session + execEffort: 'xhigh'; judgeModel: 'sonnet' + judgeEffort: 'max'; gateModel = judge + gateEffort: 'low'. Override any via args.

Commit provenance (optional arg). Pass sessionUrl (this run's session URL) so the executor/fix commits get a Claude-Session: trailer; omit it and commits carry only the Co-Authored-By line — never a stale hardcoded session id.

Plan stage (optional arg). planReview defaults ON for multi-SC features (≥3 SCs), OFF for thin ones; pass planReview: true|false to force it, planMaxIters to bound its fix loop. Its hit-rate is in the Workflow return (planReview), to be defaulted OFF if it rubber-stamps.

For full hands-off, the permission allow-list is first widened to the build/test/commit commands the executor needs (the deny-list — force-push / hard-reset / rm-rf — stays).

Reference

• Workers: .claude/agents/{initiator,spec-writer,spec-reviewer,plan-writer,plan-reviewer,executor,evaluator,evaluator-spec}.md (spec-writer = spec generator + self-review; spec-reviewer = independent spec gate; plan-writer = execution-plan generator; plan-reviewer = independent plan gate; evaluator = per-SC inner gate; evaluator-spec = whole-spec adversarial outer gate).
• Skills: .claude/skills/{create-spec,review-spec,feature}/ and the Workflows .claude/workflows/{author-specs,build-feature}.workflow.js.
• WHY the kit ships this: docs/decisions/004.ship-the-advanced-harness-in-the-kit.md.