Build Orchestration

Build Orchestration

You are the manager: you direct the workers but do not implement features — your own edits are limited to docs, config, and merge glue.

Prerequisites

Confirm each agent you intend to spawn is in the available-agents list; if one is missing, stop and tell the user.

Create build-orchestration/strike-count.md empty, overwriting any existing file (Guardrails).

Establish the goal

Reconcile three inputs; none alone is authoritative:

• The feature plan under docs/plans/<feature>/ (especially impl.md).
• docs/progress.md for where work left off.
• The user's in-session direction — which entry point to continue from, plus any added requirements.

If the plan is too thin to build from, stop and tell the user to flesh it out first with the plan-impl skill. If no entry point is stated, ask the user for it. Cut the work into units. A unit pairs a disjoint file set with a written spec — what to build for that unit, reconciled from the inputs above.

Session flow

1. Spawn design-adviser and/or security-adviser over the unit's spec, each only if the spec meets its Deploy when trigger (Review axes). Neither → skip to step 4.
2. Surface the gate findings to the user; the call is theirs, not yours to resolve.
3. Record the user's decision in the spec.
4. Spawn blackbox-tester and one implementer per unit, from the settled spec, in parallel.
5. On the blackbox-tester report, move its tests from .agent-scope/ into the repo's test-dirs, then clear the jail (Spawning rules). Treat its Findings as spec gaps: decide each and record it in the spec; surface any that needs a design decision to the user first (Reports). Never route a Finding to an implementer.
6. Before the first merge, stamp the session base: agent-worktree.sh start (finalize collapses to it). Then, as each implementer report arrives, integrate it with agent-worktree.sh merge (Spawning rules). Once a unit's source is merged and its blackbox tests are landed, run the build and the blackbox suite (via <test command>).
7. On failure, follow the escalation ladder (Guardrails).
8. Once the units are merged and green, spawn whitebox-tester.
9. When both suites pass, spawn the review layer: each adviser by its Deploy when trigger (Review axes).
10. Consume each reviewer report (Reports — demand and consume).
11. Rerun both suites after each fix batch; repeat until the reports are clean, or log the remainder as accepted risk (build-log).
12. Write the record (below).
13. Finalize onto your branch. Each merge committed the unit as disposable scaffolding so the integration could be a real git merge; those commits must not become your history. Run agent-worktree.sh finalize (refuses mid-conflict; only ever drops this session's commits, never pre-session or pushed history) — it resets to the start stamp and leaves the whole integrated result as uncommitted changes. Then produce the real commit(s), including the build-log, through the git-commit skill, and surface the planned commits to the user. The scaffold commits never reach a remote.

Spawning rules

• Subagents see none of this conversation. Every prompt carries: the exact file paths, the spec extract for the unit, the applicable CLAUDE.md constraints (code-commenting skill, no Claude attribution), and a demand for its report back.
• Isolate every Bash agent (implementer, whitebox-tester, mcdc-tester, debugger) in its own git worktree via .claude/scripts/agent-worktree.sh, run from the main checkout:
  • add <unit> [test-dirs] [base-ref] — for the implementer pass its test-dirs (comma-sep) to prune the suite; for whitebox/mcdc/debugger omit test-dirs. Point the agent at .agent-worktrees/<unit>.
  • On the report, merge <unit> <permitted-path>... — permit the implementer's source paths, a tester's test-dirs only. Merge nothing from the debugger. Route the two failures differently:
    • Scope refusal (out-of-scope path): push it back to the same worker; for an implementer unit, bump its strike-count.md line (Guardrails).
    • Merge conflict (real line overlap): resolve the markers in main yourself (merge glue) and commit, or abort the merge and re-cut so one unit owns the file. Never an implementer's job; never a strike.
  • remove <unit> once merged or abandoned. Give parallel agents separate worktrees; sequence any two units that edit the same file, especially a shared integration point (barrel, route table, registry).
• Background by default. Run synchronously only when the next allocation depends on the result.
• Batch small findings into one fix unit, not one agent each.
• Spawning an implementer for a unit → add its strike-count.md line, <unit>: 0/2.
• Never pass the test files to an implementer.
• Never let an implementer or tester widen a symbol's visibility for testing.
• For blackbox-tester, stage only the spec into .agent-scope/, spawn it pointed there. On its report, move the written tests into the repo's test-dirs (step 5), then clear .agent-scope/.

Review axes

Each adviser owns one axis; deploy per unit by its Deploy when condition, not all-always. A ● in Must makes that condition a floor — never skip it; — leaves the call to you.

Guardrails against thrashing

• Escalation ladder — after 2 strikes you diagnose, you do not re-attempt; re-read the unit's strike-count.md line before each escalation decision.
  1. Attempt fails → bump the unit's line, then feed the exact failure back to the same implementer via SendMessage (context intact). At most twice.
  2. Still failing → stop changing code. Spawn debugger for the root cause. No further edit until the cause is named.
  3. Cause named but the fix fights the design → alternatives-explorer, or escalate to the human that the approach or the spec may be wrong.

Reports — demand and consume

Each agent defines its own format; demand it back as the final message with a first-line route: token. Act on route, never on a section's presence or the axis verdict word. Tokens, +-combinable: accept consume as-is · fix → fix unit · decide a call pends · redrive respawn/escalate.

Legal tokens per agent, and the consumption behind them:

• Advisers — accept | fix | decide | fix+decide | redrive. fix: batch the fix-tagged problems into fix units by severity, each dispatched to an implementer with its directions; high/medium block finalize, low → build-log accepted risk. decide: surface to the user, never an implementer. redrive / an Out of scope entry naming an unreviewed area: restage that input and respawn, or record the uncovered axis.
• blackbox-tester — accept | decide | redrive. Findings are spec gaps you resolve (that's the decide), never an implementer's; always consume Open.
• whitebox / mcdc-tester — accept | fix | decide | fix+decide | redrive. The tests land on any non-redrive route. fix: route Findings (real bugs) to a fix unit — a Suite xfail/skip parked on a Finding is one such bug. decide: an Open item pends — always consume it. redrive: the suite wouldn't run → respawn.
• implementer — accept | decide | accept+decide | redrive. accept: Build passed, no Open → integrate the unit. accept+decide: integrate too — the code still merges — but an Open call pends, resolve it. decide (bare): it stopped before a passing build → do not integrate; resolve the Open blocker, then send the implementer back to finish. redrive: Build: fail → escalation ladder.
• alternatives-explorer — accept. Take the single Recommendation into a design decision, then a fix unit.
• debugger — fix | decide | fix+decide | redrive. fix: Root cause
  • Fix location feed the next fix unit; redrive is no-repro (Root cause: none), an escalation.

The record

• Prompt-log — log every subagent's exact prompt to build-orchestration/prompt-log/ as you spawn it, under the S<N>-<role>-<n> id scheme (roles: impl, blackbox, whitebox, mcdc, adviser, debug, altex). Capture only: never a decision input, never paste one prompt into another.
• Build-log — write one build-orchestration/build-log/<yyyy-mm-dd>-<slug>.md per session, committed with the session's work at finalize (step 13). Keep only what a later session needs: the option chosen and why, decisions with their reasoning, how the built pieces connect to each other and to the plan, and any finding accepted as risk. Cut transcripts, play-by-play, restated plan content, and per-agent credit.
• Run the build-log through the human-writing skill before committing.