multi-agent-build

name	multi-agent-build
description	Orchestrate building a planned, multi-PR feature (or a greenfield MVP from a PRD) with a coordinated subagent loop: one agent implements each PR, independent agents review and judge it, and the agent running THIS skill is the coordinator that verifies the gate, arbitrates findings, and ships each PR. Trigger when the user (or the brain orchestrator) hands over a planning scratchpad / PRD and asks to build it via the multi-agent / coordinated workflow ('orchestrate this', 'have the agents build it', 'run the loop'). Each PR runs implement -> hard gate -> independent quality review + acceptance judge -> coordinator arbitration -> ship, with a 3-attempt cap. Two modes: A (autonomous, merge each PR on green CI) and B (open PR, human merges, then continue). Do NOT use for single-file edits, quick fixes, refactors, bugs, or maintenance — this spawns multiple agents and burns real tokens; it is only for substantial, plan-driven feature builds explicitly opted into. Requires Solo and a per-project .solo/workflow.md profile.
license	MIT
metadata	{"author":"artisan-build","origin":"Generalized from hone's multi-agent-build skill (which was Mode B / monorepo-specific). The universal method lives here; all project specifics come from the project's .solo/workflow.md. Canonical source: brain/skills/multi-agent-build."}

Multi-Agent Build (general method)

Orchestrate a planned, multi-PR feature build. You are the coordinator — you do NOT write the feature code. You decompose the plan, spawn subagents to implement and review each PR, verify the hard gate yourself, arbitrate findings, and ship each PR per the project's merge policy.

Bias: quality over speed. Sequential is the default; only parallelize PRs that are genuinely independent (different surfaces, no shared files). The point of the loop is that independent agents catch what a single pass — or the deterministic gate alone — misses.

This skill is the method. Everything project-specific (the gate command, dependency install, harness mapping, branch/PR target, release steps, stack quirks) comes from the project profile.

Step 0 — Load the project profile (do this first)

Read .solo/workflow.md at the repo root (and the ## Workflow section of CLAUDE.md). It defines, for THIS project:

• phase — pre-launch | launched | maintenance.
• mode default and merge_policy — see Modes below.
• hard gate — the exact command(s) that must be green (e.g. composer ready, npm run check), plus any per-package/per-workspace suites.
• dependency install — the real install command for a fresh worktree (e.g. composer install, npm ci), and whether the repo is a monorepo (install per touched package/workspace).
• harness map — which runtime fills each role (implementer / quality reviewer / acceptance judge) and any invocation quirks.
• ship details — branch naming, PR target repo, merge method (e.g. gh pr merge --squash), release/split steps.
• plan location — the scratchpad / PRD that holds the build plan.
• Solo project — name/id for spawning scope.

If .solo/workflow.md is missing, STOP and ask the orchestrator/user to create one (template in brain). Do not invent project conventions.

Modes (set by the orchestrator at spawn, recorded in your brief)

The loop is identical in both modes; only the ship step (7) differs.

• Mode A — autonomous (default, most common): you drive the whole feature. On PASS, open the PR, wait for CI to go green, merge it yourself (per the profile's merge method), then proceed to the next PR. The local gate + agentic review + acceptance judge are the quality bar; the PR's CI is the final deterministic check before auto-merge. CI red = treat as a gate failure → rework.
• Mode B — review-each-PR: on PASS, open the PR and stop. The PR is the handoff. Tag the human; wait for them to confirm the merge before starting the next dependent PR.

Default the mode from phase (pre-launch → A) but the brief's explicit mode always wins.

Roles & runtimes (deliberate harness decorrelation)

Use the harness map from the profile. The default mapping:

Role	Who (default)	How
Coordinator	this session	Decomposes PRs, writes acceptance criteria + critical test assertions, spawns/awaits agents, verifies the gate, arbitrates, writes the report, keeps the run-log, ships per mode.
Implementer	OpenCode (Solo agent)	Persistent Solo agent in the PR worktree; implements + writes tests until the gate is green.
Quality reviewer	Codex (one-shot CLI)	Quality/security/perf/standards. Different harness than the implementer.
Acceptance judge	Claude (Solo agent)	Judges strictly against acceptance criteria; must read REAL test output, never vibe-judge.

Different model lineages touch every PR so reviewers don't share the implementer's blind spots. The coordinator reads all the code when writing the report — a final holistic pass.

Spawn mechanics: spawn_agent(agent_tool_id) → prepend the returned agent_instructions → send_input(process_id, input).

Confirm work is actually underway BEFORE you arm the long idle-timer. A freshly-spawned agent that is stuck at a permission/credential prompt — or that died on an early error — reads as idle, so arming timer_fire_when_idle_any right after send_input can put you to sleep while a sub-agent sits frozen at a gate (a real failure mode: an implementer waiting for file-read permission while the coordinator naps on a 30-min timer). So:

1. Check in at SHORT intervals early — get_process_output every ~30–60s for the first few minutes after spawning — until you see real progress: files read, tools run, output produced, clearly past initial setup.
2. If it's blocked at a permission/credential gate (or hasn't moved), surface it to the human (it likely needs access granted) rather than waiting on it — a gate won't clear on its own.
3. Only once work is confirmably underway, arm timer_fire_when_idle_any([pid], max_wait_ms, body) for the long hands-off wait, and capture with get_process_output.

⚠️ Idle-timers do NOT reliably catch permission stalls — for two opposite reasons — so POLL during prompt-heavy phases (especially initial worktree setup):

• Some agents stuck at a prompt read as idle → the timer can fire prematurely (above).
• OpenCode's animated TUI never registers as idle even while parked at a permission spinner → the idle-timer does NOT fire until its max_wait ceiling, so you can burn the entire window (e.g. 20 min) while the implementer is frozen at a gate. Mitigation: when OpenCode's worktree permission prompt appears, grant the worktree-root permission (covers the whole dir) to kill all further per-directory prompts; the next idle transition is then genuine completion.

Any harness-specific invocation quirk lives in the profile.

Worktree setup (per PR)

Each PR gets its own git worktree off the latest origin/main, with its own real dependency install (command from the profile):

git worktree add <path> -b <branch> origin/main
cd <path> && <install cmd>   # + any env/db setup the profile lists

Never symlink or cp -R the dependency dir (vendor/, node_modules/) from the main checkout — it makes tooling resolve paths to the wrong checkout and produces phantom failures. A real install is the only reliable provisioning. If the profile marks the repo a monorepo, install inside each touched package/workspace too. Read-only reviewers don't rely on cwd — give them absolute paths and git -C <worktree>.

The hard gate (objective, non-negotiable)

The gate command(s) come from the profile. Rules:

• You verify the gate yourself, on the COMMITTED SHA, in a clean tree — never trust the implementer's "it passed." Run the REAL gate command, not a partial shortcut.
• The gate is a precondition to review — don't spawn reviewers until it is green. A red gate bounces to the implementer and does NOT consume an attempt.
• The LLM judge is additive on top of the gate, never a substitute; it must inspect real output.
• Confirm the working tree is clean (no uncommitted churn the "green" depended on).

The per-PR loop

1. PLAN      Decompose the PR into tasks + write acceptance criteria AND the critical acceptance-test
             assertions up front (TDD-leaning, so the implementer can't teach to a weak test).
2. BUILD     Spawn the implementer in the PR worktree. Brief it fully (tasks, ACs, locked assertions,
             the gate, "keep git status clean — only intended files", commit footer, do NOT
             push/PR/merge). It loops until the gate is green.
3. GATE      Re-verify the gate on the committed SHA in a clean tree. Red -> back to BUILD.
4. REVIEW    Green -> launch the quality reviewer AND the acceptance judge, independent + blind to
             each other, both against the committed diff.
5. ARBITRATE Apply the severity rubric and decide. Verify any blocking finding in the code yourself.
6. REWORK    Blocking issue(s) -> tight rework brief to the SAME (warm) implementer. Back to GATE.
             attempts < 3. Trivial coordinator-verifiable fix -> verify by inspection, no full re-review.
7. SHIP      Gate green + no blocking -> read the full diff, write the implementation report, push the
             branch, open the GitHub PR with the report as the body. THEN:
               Mode A: wait for CI green -> merge (profile method) -> next PR. CI red -> rework.
               Mode B: stop. Tag the human. Wait for their merge before the next dependent PR.

Bail: after 3 attempts still blocking → stop, do not touch the next PR, write a standalone scratchpad (branch, per-round diffs, surviving findings, what each attempt tried, a hypothesis about which planning assumption broke) and tag the human. A bail means the PLAN, not just the code, needs revisiting.

Severity rubric — YOU own the call

LLM reviewers always find something; without discipline the loop never terminates.

• Reviewer [BLOCKING]/[ADVISORY] tags are advisory INPUT, not verdicts. You decide true severity by weighing real-world likelihood and impact, not theoretical correctness.
• BLOCKING = a failing gate, a security/credential issue, an unmet acceptance criterion, a missing/weak test for required behavior, or data-integrity that can actually occur. Only blocking findings trigger a rework round and consume an attempt.
• ADVISORY = nits, can't-happen edge cases, low-impact robustness. Surface in the PR body; do NOT spend a cycle. (In Mode A, file advisories as issues or note them in the report rather than blocking the merge.)
• Don't escalate a low-likelihood/low-impact issue to blocking just because a reviewer flagged it, and don't over-cycle: verify trivial changes by inspection.

Attempts: initial implementation = attempt 1; each blocking-driven rework = +1; max 3. A red gate the implementer is still resolving does NOT burn an attempt — only a reviewed round with surviving blocking findings does. Infrastructure failures you caused do NOT count.

Tag the human in — only when

Run hands-off otherwise. Tag the human when: (a) you bailed (3 attempts), (b) you're blocked needing a human decision or a credential you don't have, (c) Mode B merge gate, or (d) a planning assumption broke. Use the run-log scratchpad as the live window; the human can interrupt anytime.

Artifact contract

• One run-log scratchpad for the whole feature — append at every transition (spawn, gate result, findings, arbitration, attempt count, PR link, merge). The human's live window.
• One Solo todo per PR — body holds tasks + acceptance criteria; encode the PR dependency DAG with todo_add_blocker; status tracks loop state; complete on merge (Mode A) or after the human merges (B).
• The PR is the handoff — push + open the PR with the implementation report as the body.
• History to brain: at feature completion (or bail), write a concise summary the brain orchestrator harvests into brain/projects/<name>/log.md — what shipped, key decisions + rationale, anything that needs follow-up. This is the long-horizon record.

Implementation report (the PR body)

Read the full diff and write: what shipped vs the plan (1–2 lines); deserves attention (anything complex/fragile or a deviation forced by an in-flight discovery — and why); findings disposition (blocking found + how fixed; advisories deferred); gate evidence (the gate command output + which ACs the judge confirmed); risk / next. Flag prominently any core behavior that isn't automatically testable and needs manual verification.

Scope

Use for: substantial, plan-driven feature builds, and occasionally greenfield MVP builds where the plan scratchpad is a PRD. Do NOT use for single-file edits, quick fixes, refactors, bugs, or maintenance — those have a separate (TBD) workflow.