Multi-Agent Coding Teams: A Field Guide That Skips the Hype

Field guide

Let's start with the sentence every multi-agent thread on the internet is missing: multi-agent is not always better. One agent with a clear spec beats five agents with a vague one, every time, and it isn't close. If your single-agent sessions are producing mush, adding four more agents produces mush in parallel — faster mush, at five times the token cost.

We run agent teams daily and have shipped real product with them, so this isn't a takedown. It's a field guide: when teams actually win, when they lose, the roles that survived contact with reality, and the collision rules that keep a team from becoming an expensive way to generate merge conflicts.

When teams win, when they lose

Teams win under three conditions, and you want at least two before spinning one up:

• Parallelizable scope. The work splits into chunks that don't touch the same files. API endpoints plus a frontend plus a test suite: parallel. One tangled function: not parallel, no matter how much you want it to be.
• Review independence matters. A second agent that didn't write the code, checking the code, catches a class of errors the author-agent structurally cannot — because the author already believes its own work.
• Long jobs. A big migration or a large feature build benefits from a coordinator holding the plan while workers grind, because no single context window survives the whole job anyway.

Teams lose under three conditions, and any one of them is disqualifying:

• Tiny tasks. Coordination overhead is fixed; a task under an hour of single-agent work gets slower with a team, not faster.
• Overlapping files. Two agents editing the same module will overwrite each other and both will report success. This is the number-one team killer.
• No verification. Without an external check, a team is a machine for laundering one agent's unverified claim through four other agents until it sounds like consensus.

Quick gut check before you spin up a team: can you write down each agent's scope such that no two scopes share a file, and can a script tell you whether the job is done? If either answer is no, use one agent.

The roles that survived contact with reality

We've tried a lot of org charts. Most collapse. Four roles keep earning their tokens.

The Coordinator

Plans and delegates. Never edits code. The moment your coordinator starts writing files, you've lost the plan-holder and gained a mediocre builder with delusions of oversight.

The Coordinator's real job is producing decision-complete handoffs. Every task it delegates must contain, in writing:

1. Goal — what done looks like, one paragraph.
2. Files in scope — an explicit list. Not "the auth module," but app/Auth/LoginController.php and routes/auth.php.
3. Constraints — patterns to follow, dependencies not to add, code not to touch.
4. Definition of done — the exact command that proves it: php artisan test --filter=Login, not "make sure it works."
5. Out of scope — named explicitly, because agents expand into any ambiguity like gas into a vacuum.

If a worker has to come back with a clarifying question, the handoff failed. Decision-complete means every decision the worker might face is already made.

The Builder

Implements. One task at a time, smallest correct change that satisfies the definition of done. The Builder's standing orders are short: don't refactor adjacent code, don't upgrade dependencies, don't "improve" anything you weren't asked to touch, end every task by actually running the done-check command and pasting the real output. A Builder that reports "this should work now" instead of pasted test output is a Builder that hasn't finished.

The Scout

Read-only, and this is enforced, not suggested. The Scout maps the codebase before anyone edits it: where does the feature live, what patterns does this repo use, what will this change break. Every claim comes with a citation in path:line form — "rate limiting is configured in app/Http/Kernel.php:41" — so downstream agents can verify instead of trusting.

Scouts are cheap insurance. A twenty-minute scout pass before a build routinely saves the Builder from reimplementing something that already exists two directories over. On unfamiliar codebases, we never skip this role.

The Reviewer

The most misunderstood role. A Reviewer is not a second opinion — it's an independent re-verifier. It checks out the Builder's work fresh, re-runs the build and the tests itself, reads the diff against the original handoff, and rejects anything it can't verify firsthand. "The Builder says tests pass" is precisely the claim the Reviewer exists to distrust.

Standing orders: reject any "done" claim that doesn't come with reproducible evidence, and never accept a diff wider than the files-in-scope list without an explanation.

Collision rules

Roles are half the system. These three rules are the other half, and they're where teams actually die.

Never two agents in the same files

Not "coordinate carefully." Never. The mechanical fix is git worktrees: each agent works in its own checked-out copy of the repo on its own branch.

git worktree add ../project-builder-a  feature/api-endpoints
git worktree add ../project-builder-b  feature/frontend
git worktree add ../project-reviewer   review/integration

Each agent gets pointed at its own directory. Merges happen at the end, deliberately, by you or the Reviewer — not implicitly, mid-flight, by two agents saving over each other. Worktrees are free, undo is per-branch, and the failure mode changes from "silent corruption" to "a merge conflict you can see."

A shared task board file beats agents chatting

Agent-to-agent conversation sounds great and works badly: messages get summarized, context decays, and nobody can audit who said what. What works is boring: a single TASKS.md in the repo that every agent reads and updates.

## TASK-003: Password reset endpoint
Status: IN_PROGRESS (builder-a)
Scope: app/Http/Controllers/PasswordResetController.php, routes/auth.php
Done-when: php artisan test --filter=PasswordReset passes
Out of scope: email templates (TASK-005)
Notes: token table already exists — see migration 2026_07_02

Every state change goes through the file. It's persistent, auditable, survives any individual session's death, and — unlike a chat log — a human can read it in thirty seconds and know exactly where the job stands.

Verification is external

The definition of done is never "the agent says so." It's a command that exits zero: your test suite, your build, your linter, a smoke-test script. Models are trained to be agreeable, and an agreeable worker plus an agreeable reviewer converges on shared delusion. Tests don't want to be liked. This is the exact principle behind our AutoVibe gate — the harness independently runs your build and your tests and only passes on a genuine green — but you can enforce it with nothing fancier than a make verify target that every role must run and quote.

Different models for different roles

Here's the part single-vendor tools can't offer you: the roles have different job requirements, so they should get different models. Planning rewards the strongest reasoner you can afford, because a bad plan poisons everything downstream. Building rewards speed and cost, because builders burn the most tokens on the most mechanical work. And reviewing rewards something subtler — a different lab than the builder. A model reviewing its own family's output shares its training, its blind spots, and its stylistic instincts; a rival lab's model has no loyalty to the mistake. We've caught real bugs purely because the reviewer "thought differently" than the builder. The gaps between labs are real and they move month to month — our shootout post has the current lay of the land.

A starter lineup that works:

You can run this entire setup by hand: four terminal tabs, four worktrees, one TASKS.md, one make verify. It's clunky but it works, and the clunkiness is instructive — you'll feel exactly which parts deserve automation. That feeling is why we keep saying the harness is the product; The Vibe Father's VibeSwarm is essentially this playbook with the friction removed, different models per role included.

The failure modes, so you recognize them early

• The consensus mirage: three agents "agree" the code works; none of them ran it. External verification is the only cure.
• Coordinator drift: the planner starts editing files "just to speed things up." Revoke and restart.
• Scope osmosis: a Builder's diff quietly grows beyond its file list. The Reviewer's job is to bounce it, not to be understanding about it.
• Chat entropy: coordination moved from the task board into ad-hoc messages, and now nobody — including you — knows the actual state. Freeze, rewrite TASKS.md from reality, resume.

Start with one agent and a sharp spec. Add a Scout when the codebase is unfamiliar, a Reviewer when correctness matters, parallel Builders only when the scopes genuinely don't touch. A team is a force multiplier, and force multipliers multiply whatever you feed them — including confusion. Feed them clarity.