NagareNegishi/Job-Application-Tracker / .claude/skills/build-orchestration
build-orchestration
VerifiedRun 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 under anti-thrash guardrails.
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>/(especiallyimpl.md). docs/progress.mdfor 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
- 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |