build-orchestration
Run a multi-agent build session: the main session acts as manager — cutting a goal into units, spawning implementer, tester, and adviser subagents, and running the test-and-review loop to completion u
SKILL.md.claude/skills/build-orchestration/SKILL.md
GitHubBuild 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 binding spec under
docs/plan/(start atREADME.md; milestones in07-milestones.md). docs/plan/PROGRESS.mdfor where work left off.- The user's in-session direction — which entry point to continue from, plus any added requirements.
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
- Spawn
design-adviserand/orsecurity-adviserover the unit's spec, each only if the spec meets itsDeploy whentrigger (Review axes). Neither → skip to step 4. - Surface the gate findings to the user; the call is theirs, not yours to resolve.
- Record the user's decision in the spec.
- Spawn
blackbox-testerand oneimplementerper unit, from the settled spec, in parallel. - On the
blackbox-testerreport, move its tests from.agent-scope/into the repo's test-dirs, then clear the jail (Spawning rules). Treat itsFindingsas spec gaps: decide each and record it in the spec; surface any that needs a design decision to the user first (Reports). Never route aFindingto an implementer. - Before the first merge, stamp the session base:
agent-worktree.sh start(finalize collapses to it). Then, as each implementer report arrives, integrate it withagent-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>). - On failure, follow the escalation ladder (Guardrails).
- Once the units are merged and green, spawn
whitebox-tester. - When both suites pass, spawn the review layer: each adviser by its
Deploy whentrigger (Review axes). - Consume each reviewer report (Reports — demand and consume).
- Rerun both suites after each fix batch; repeat until the reports are clean, or log the remainder to build-log as unresolved risk.
- Write the record (below).
- Finalize onto your branch. Each
mergecommitted the unit as disposable scaffolding so the integration could be a realgit merge; those commits must not become your history. Runagent-worktree.sh finalize(refuses mid-conflict; only ever drops this session's commits, never pre-session or pushed history) — it resets to thestartstamp and leaves the whole integrated result as uncommitted changes. Then produce the real commit(s), including the build-log, through thegit-commitskill, 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-commentingskill, 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.mdline (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.
- Scope refusal (out-of-scope path): push it back to the same worker; for an
implementer unit, bump its
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
implementerfor a unit → add itsstrike-count.mdline,<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.
| Axis | Agent | Deploy when | Must |
|---|---|---|---|
| Correctness (logic, edge cases, contract) | correctness-adviser |
the unit has non-trivial logic or branching (near-default) | ● |
| Security risk | security-adviser |
the unit touches auth, input handling, crypto, file/network I/O, or secrets | ● |
| Design / architecture | design-adviser |
the unit adds or changes an abstraction, interface, or module boundary | — |
| Redundancy, over-complication | simplicity-adviser |
the diff is large or tangled | — |
| Performance, efficiency | performance-adviser |
the unit loops over unbounded data, hits the DB, or sits on a hot path | — |
| Documentation, comments | docs-adviser |
the unit changes public API or user-facing docs | — |
| Legal, licensing, compliance | legal-adviser |
the unit adds a dependency or copied / third-party code | ● |
| Change discipline (diff vs. its mandate) | change-discipline-adviser |
the diff smells: scope creep, weakened or deleted tests, an outsized diff | — |
| Decision-coverage testing (optional) | mcdc-tester |
the unit is decision-dense: auth, pricing, validation, state machines | — |
| Root-cause diagnosis on failure | debugger |
the escalation ladder stalls (Guardrails) | — |
Guardrails against thrashing
- Escalation ladder — after 2 strikes you diagnose, you do not re-attempt; re-read the
unit's
strike-count.mdline before each escalation decision.- Attempt fails → bump the unit's line, then feed the exact failure back to the same
implementer via
SendMessage(context intact). At most twice. - Still failing → stop changing code. Spawn
debuggerfor the root cause. No further edit until the cause is named. - Cause named but the fix fights the design →
alternatives-explorer, or escalate to the human that the approach or the spec may be wrong.
- Attempt fails → bump the unit's line, then feed the exact failure back to the same
implementer via
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 thefix-tagged problems into fix units by severity, each dispatched to an implementer with itsdirections;high/mediumblock finalize,low→ build-log as unresolved risk.decide: surface to the user, never an implementer.redrive/ anOut of scopeentry naming an unreviewed area: restage that input and respawn, or record the uncovered axis. - blackbox-tester —
accept|decide|redrive.Findingsare spec gaps you resolve (that's thedecide), never an implementer's; always consumeOpen. - whitebox / mcdc-tester —
accept|fix|decide|fix+decide|redrive. The tests land on any non-redriveroute.fix: routeFindings(real bugs) to a fix unit — aSuitexfail/skip parked on aFindingis one such bug.decide: anOpenitem pends — always consume it.redrive: the suite wouldn't run → respawn. - implementer —
accept|decide|accept+decide|redrive.accept:Buildpassed, noOpen→ integrate the unit.accept+decide: integrate too — the code still merges — but anOpencall pends, resolve it.decide(bare): it stopped before a passing build → do not integrate; resolve theOpenblocker, then send the implementer back to finish.redrive:Build: fail→ escalation ladder. - alternatives-explorer —
accept. Take the singleRecommendationinto a design decision, then a fix unit. - debugger —
fix|decide|fix+decide|redrive.fix:Root causeFix locationfeed the next fix unit;redriveis 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 theS<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>.mdper 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 unresolved risk. Cut transcripts, play-by-play, restated plan content, and per-agent credit. - Run the build-log through the
human-writingskill before committing.