One planner, three builders, and reviewers who didn't write the code
How I run several AI coding agents on one hard problem without them breaking each other's work, with frozen contracts, separate worktrees, independent reviews and a strict spending rule.
Where it came from: How I ran a planner model and several builder agents on one hard construction-takeoff build.
The first time I pointed three AI agents at the same hard problem, they finished fast and broke each other's work. One changed a shared type. Another was building on the old version. The third wrote tests that mocked the exact code the first one had broken, so everything passed.
What fixed it was organization, not a better model.
The cast
- A strategy reviewer. The strongest model I have reads the goal and the code and writes the plan: architecture, lanes, which files each lane owns, and what "done" means. It doesn't write production code.
- Lanes. Builder agents, each owning a set of files and one deliverable.
- Independent reviewers. Fresh sessions that never saw how a lane reasoned. They get the code and the acceptance criteria, and they write reproduction scripts, not opinions.
- Root. The coordinator, either me or one session acting for me. Root assigns ownership, can overrule the planner, integrates the work and decides on release. Only root merges.
Two things get frozen early
The shared contract. One lane writes the shared interfaces first, and root freezes them. A later change is published as v2 next to v1, never edited in place, so nobody's foundation shifts under them.
Acceptance. The definition of done is hashed and frozen. Later additions can make it stricter but never looser. That stops anyone from quietly moving the goalposts when a test is hard to pass, and that includes me.
Everything is a file
Each lane writes an append-only status log. Root keeps timestamped coordinator notes. Reviews are JSON with a verdict, findings, the evidence that passed, the limits of what was checked, and the exact commit reviewed. When an agent hits a usage limit at 2am, the next session reads the files and picks up where it stopped.
The spending rule
This is the rule I'd put first if you're paying for API credits. Development and review run on the subscription. API credits are only for running the product itself, capped per run and tied to a frozen code hash. If a lane runs out of usage, it stops and saves its work. It never switches to a paid route to keep going.
I added this after a build burned through a shared credit balance halfway through a test run and returned a payment error. Now the rule goes into every lane's instructions.
What I learned
- Mocks lie. Reviewers now have to exercise at least one real path per lane.
- Sharing a working folder isn't isolation. File ownership alone wasn't enough, so each lane now gets its own git worktree.
- Interrupt with evidence. When root stops a lane, the message says what was found and that the original goal still stands. Otherwise the agent decides it's been given a new task.
- The planner can be wrong. I've overruled it, and the decision file says why. One of its shortcuts would have hidden failures, and that's never acceptable.
- Check the layer. When three rounds of fixes don't move the result, ask whether the problem is in a different part of the system than the one you're fixing. That question saved me a week.
Steal it
The skill is lane-orchestrator in my John Lab plugin.
/plugin marketplace add johnarndt/john-lab
/plugin install john-lab@john-lab/plugin marketplace add johnarndt/john-lab /plugin install john-lab@john-labDownload lane-orchestrator.zipView on GitHub
View SKILL.md
---
name: lane-orchestrator
description: "Use when a user wants several AI coding agents to build one hard change in parallel without stepping on each other. Triggers include 'have a reviewer plan it and agents build it', 'split this across agents', 'use a planner model and builder models', 'spin up parallel lanes', 'get an independent review before merging', or 'coordinate multiple Claude sessions on this repo'. Sets up a strategy review first, file-owned lanes in separate worktrees, append-only status logs, frozen contracts, independent reviewers with reproductions, and an explicit spending rule."
---
# Lane orchestrator
Parallel agents go fast and break things in parallel. This skill is the coordination layer: one planner, a few builders with clear ownership, reviewers who did not write the code, and a root that decides. Everything is a file, so any session can resume after a limit or a crash.
## Roles
- **Strategy reviewer** (the strongest model available): reads the goal and the code, then writes the plan. It does not write production code.
- **Lanes** (builder models): each owns a set of files and a written deliverable.
- **Independent reviewers:** fresh sessions that never saw the lane's reasoning. They get the code and the acceptance criteria, and they write reproductions, not opinions.
- **Root** (you, or the coordinating session): assigns ownership, accepts or overrides the reviewer, integrates and decides on release. Only root merges or deploys.
## Workspace
```
coord/
plan.md # strategy review output
coordinator-notes.md # root's timestamped decisions, append-only
contracts/ # shared interfaces, versioned: contracts.v1.ts, contracts.v2.ts
acceptance.v1.md # what "done" means, frozen by hash
lanes/<lane>-status.md # each lane's append-only log
reviews/<lane>-<sha>/review.json + repro scripts
decisions/<date>-<topic>.json
```
Review JSON: `{ "verdict": "accept|blockers", "findings": [...], "positiveEvidence": [...], "acceptanceLimits": [...], "reviewedSha": "..." }`.
## Flow
1. **Strategy review.** The reviewer writes `plan.md`: architecture, lanes, file ownership per lane, the shared contract to freeze first, and the acceptance criteria.
2. **Freeze the contract.** One lane writes the shared types or interfaces within the first short block of work. Root freezes it. Later changes publish `v2` alongside `v1`; nothing is rewritten in place.
3. **Freeze acceptance.** Record a hash of the acceptance file. Later additions are addenda that may tighten but never relax it.
4. **Run lanes.** Each lane gets its own git worktree and branch, starting from the same commit. It edits only its owned files, logs progress and published interfaces to its status file, commits, and stops at its deliverable.
5. **Independent review.** For each finished lane, a reviewer at the frozen SHA writes findings with reproduction scripts. Blockers go back to the lane as a narrow follow-up with the repro attached.
6. **Integrate.** Root merges accepted lanes into an integration worktree, runs the full suite and the acceptance checks, and records a decision file.
7. **Release** only from a clean integration commit, by root, after the owner approves.
## Spending rule
Write it in `plan.md` and in every lane prompt: which accounts pay for development and which pay for product test runs. A sensible default is to build and review on the subscription, and to spend API credits only on runs of the product itself, capped per run and frozen to a code hash. If a lane hits a usage limit, it stops and preserves its work. It never switches to a paid route to keep going.
## Rules learned the hard way
- **Mocks lie.** Tests that mock the data layer passed while the real path read the wrong field. Reviewers must exercise at least one real path per lane.
- **Shared worktrees collide.** File ownership alone is not enough isolation; give each lane its own worktree.
- **Interrupt with evidence, not new scope.** When root interrupts a lane, the message says what was found and that the original objective stands.
- **The reviewer can be wrong.** Root may override the strategy reviewer and records why. Reject any shortcut that would hide failures, such as skipping work because something looks present.
- **Check the layer.** If repeated fixes do not move the result, ask the reviewer whether the failure lives in a different layer than the one being fixed.