Field manual · agent team workNovember 2026

Leading an
agent team

What held up when one lead agent ran a team of headless worker agents through a real product build: the loop, the rules, and the numbers behind each rule.

55one-shot worker runs: build, review, repair, verify
$247total, priced from token counts at list price
4 + ~25blocking and major defects found by review that the builders' own tests missed
814tests green on main at the end, release gates closed from a fresh clone
I
The idea

The lead owns the contracts, not the code.

One agent is the lead engineer. It writes the architecture, the invariants, the expected results and the briefs. It dispatches every task, reads every diff, integrates, and accepts or rejects. Workers each do one bounded task in their own git worktree and hand back a schema-validated report.

The lead never writes feature code. Its own fixes are limited to about 20 lines of mechanical glue. Anything bigger becomes a card for a worker. This keeps the lead's context for judgment: what to build, what counts as done, and whether a result is true.

The setup this was measured on: Claude Code as the lead, headless OMP (oh-my-pi) workers, and a small runner that launches each worker in a tmux session, waits on it, and validates its report.

II
The loop

Ten steps, every card

Solid steps happen for every card. Dotted steps belong to integration and release.

  1. ContractsBrief, architecture, numbered invariants, independent expected results
  2. CardsOne outcome, ≤45 min, allowed files, size budget
  3. Route by riskPick the builder and whether a design step comes first
  4. DispatchOwn worktree, own branch, single-use task id
  5. AcceptReport, then diff. Check the served model and the budget
  6. ReviewA different model family, given code and contracts only
  7. RepairNew task, findings verbatim, one regression test each
  8. IntegrateMerge into an int/* branch, run the full suite
  9. GateLead's own evidence, from a fresh clone
  10. RecordBoard, decision log, lessons with evidence

↺ Steps 06 → 07 repeat until review finds nothing blocking. After a blocking finding, always review again.

III
The rules

Twelve rules that paid for themselves

Write the contracts before any code, including a numbered invariants list.

Cross-cutting rules that no single card owns (which clock is used for security timing, what counts as "new", ordering of ingestion) go in one numbered list. Every brief and every review cites the numbers.

Most of the cost went to repair rounds for invariants that were only discovered in review. One foundation card took three repairs, another two. The lead was the only one who caught three cross-cutting mistakes, because nothing else held the whole picture.

Name the hazards of the code a card reuses.

A worker trusts existing functions. If an existing path has a sharp edge, the contract has to say so.

On one card, two of the three blocking defects came from an existing sync path that re-registered its source from whatever snapshot it was given. The contract never mentioned it, and every builder reused it.

Keep cards small, with a size budget that counts tests honestly.

One outcome per card, about 45 minutes or less. Give allowed files, and run cards in parallel only when those sets don't overlap. Budget about 25 test lines per observable rule, and about 30 lines per regression test in a repair.

Six runs stopped incomplete at their time limit. Every builder on one 12-rule card blew a 450-line budget (657–727 lines), because the budget forgot the tests. Each repair then ran 2× over its own budget, for the same reason.

Route each card by risk.

High-risk means it touches authorization or tokens, ingestion or migrations, concurrency or a state machine, money, deletion, or a new subsystem. Cheap models build normal cards. The strongest builder takes risky cards. A design step comes first only for a protocol core, and that design is reviewed before anything is frozen. The routing table is below.

Every high-risk change gets a review from a different model family.

Reading the diff yourself does not replace it. Neither do green tests.

Cross-family reviews found 4 blocking and about 25 major defects that the builders' tests missed: a bearer token sent to any host, snapshot races, leaks after access was revoked. One was in code the lead had already read and approved. On the scheduling card, every concurrency defect was found by review, while the test suite and a hidden acceptance suite stayed green throughout.

Give reviewers the code and the contracts, never your opinion.

A reviewer told what you suspect will confirm it. Ask for two axes: correctness and security, and engineering quality. If engineering isn't a named axis, nobody checks it.

A quadratic audience query (28.7 s at 5,000 documents, 84 ms after the fix) was found only in a second review, because that reviewer happened to run a benchmark. It cost a third repair round.

Repairs are new tasks, with findings quoted verbatim and one regression test per finding.

Each test must fail before the fix and pass after it. Send local fixes to the cheap builder, and structural ones to the strongest.

Don't fix a design flaw in repair rounds. Redesign after the second finding.

For races: find the lock that already serializes the competing actions, make the decision while holding it, and compare identity (a row id), never clock time.

The lead accepted timestamp guards for two rounds. Each review then reproduced another double run. The fix that held was a 177-line redesign: admit the job under the per-source lock by the latest attempt's id. See the case study below.

Write brief rules without exception clauses.

"Every path does X, except Y keeps its current behaviour" gets read as permission to skip X. State the exception as its own rule with an observable outcome, or leave it out.

One major review finding came directly from a lead brief worded like that.

Integrate on a branch, and run the full suite there.

Merge accepted task branches into int/<milestone> and run everything. Only integration branches the lead has verified reach main.

This caught every seam between tasks during the build.

Close gates with your own evidence, from a fresh clone.

No existing virtualenv, no .env, only the documented commands. Never close a gate on a worker's report.

This is how the build found that make gates was running on the system Python.

Put guardrails in the runner, not in the prompt.

Give each task its own worktree, a schema-validated report, and a frozen file list the worker cannot change. Check that the model that served the run is the one you asked for. Audit for delegation, so no worker quietly starts sub-agents. Price runs yourself from token counts.

A smoke test found that one worker tool could spawn sub-agents, so it was removed. The harness's own price table overstated one model's list price by 25% on output and 5× on cache reads.
IV
Routing

Who does what

CardRoute
NormalFast implementer → lead reads the diff → integrate
High-riskStrongest builder → cross-family review → repair → re-review → integrate
High-risk with a protocol core (cross-process claims, ordering, a state machine)Designer writes the note, interfaces and failing tests → reviewer checks the design → lead approves → implementer builds with those files frozen → review → repair
Bug with an unknown causeDesigner diagnoses without fixing, and delivers a repro test that fails reliably → implementer fixes with the repro frozen → review
RoleModel usedWhy
ImplementerClaude Sonnet 5.5Narrow, well-specified cards at about ⅛ the cost of the big model (about $0.90 a run)
Hard implementerClaude Opus 5.5 (high effort)Default builder for risky cards, plus repairs. Cheapest and fastest route in the bake-off
DesignerClaude Fable 5.2Protocol cores and diagnosis only. As a solo builder it was the slowest and costliest, with no gain in quality
ReviewerGPT-6 AstraA different family from every builder. About $3.60 a review

Why not "cheap model drafts, strong model fixes"? A reviewer or refiner anchors on the draft's structure. It fixes defects but rarely changes the design. So the structure has to come from a strong model: a strong builder, or a reviewed design step.

V
Case study

A bake-off, and what shipping the pick took

One high-risk card: scheduled syncs plus permission-freshness monitoring. Three routes were built from the same contract, then judged by a hidden 13-test black-box suite and by blind cross-family reviews.

Route X

Design → build

Cost
$7.44
Time
18 min
Hidden
12 / 13
Review
1 blocking · 3 major
Route Y

Strong builder alone

Cost
$3.69
Time
13 min
Hidden
13 / 13
Review
1 blocking · 3 major
Route Z

Designer alone

Cost
$9.47
Time
30 min
Hidden
13 / 13
Review
1 blocking · 3 major

Every route had the same severity profile. The design route gave the smallest production code, and its concurrency protocol looked correct, so the lead picked it to ship. That call was wrong:

  • Repair 1 · $3.56All original findings fixed, plus a rule the lead had missed: a scheduled sync must trust the stored registration.
  • Re-review · $2.91A double run whenever a sync outlasts its cadence. The "correct" protocol was not correct.
  • Repair 2 · $2.28A timestamp guard, plus a lead fix to when a run's start time is recorded.
  • Final review · $4.85Reproduced two more double runs with real processes. Timestamps can't fix ordering.
  • Repair 3 · $1.91Lead redesign: decide under the lock every sync already takes, by attempt id.
  • Final review 2 · $3.64One last clock-ordering edge case. A 5-line lead fix, verified with the reviewer's own fault probe.

What it taught

  • Every one of the four reviews ($14.31) found a real defect. Every test stayed green the whole time.
  • The hidden suite checks the contract. Review finds races and hazards. Use both.
  • A design step froze its own mistakes. Review the design before you freeze it.
  • Two timestamp patches in a row on the same race is the signal to redesign.
  • Shipping cost $19 after a $7 build. Budget for repairs, not just the build.
  • Write down where you were wrong. The bake-off report now carries a correction.
VI
Pitfalls

Common mistakes

MistakeInstead
The most expensive model as the default builderCheap model for narrow cards, a strong builder for risky ones, the designer only for design
A card stops at its time limitSplit it. Don't just raise the timeout.
A review brief that says what you think is wrongGive the reviewer the code and the contracts only
Freezing a design nobody reviewedReview the design note and its tests first. A frozen flaw survives the build.
Racing actions "fixed" with timestamps, round after roundDecide under the serializing lock, by identity. Redesign after the second finding.
Trusting the harness's cost numberPrice runs from token counts. Cost follows turns × context size, so small cards with a fixed design cost less on any model.
Editing a task while its run is liveTask ids are single-use. Write a new task.
Closing a gate on a worker's "all green"Rerun it yourself from a fresh clone
VII
When

When it's worth it

Use the lead-and-workers loop for 3 or more cards where correctness or security matters: permissions, data integrity, state machines, money.

Use a single native session for 1–2 cards, exploratory work or UI tweaking. For a risky change, still send out one cross-family review. That gets most of the value for a fraction of the cost.

Still open: whether design → design review → cheap build beats a strong builder alone once the design's own mistakes are caught before the freeze. Also, whether shorter prompt-cache retention cuts about 10% of cost, since workers send turns seconds apart.