One agent doing everything is a solo founder doing every job. It holds up until it does not. The fix is not a bigger agent, it is more agents, each doing less, each handing clean work to the next.
3.8.1Signs one agent isn't enough
You feel it before you can name it. The agent starts strong and loses the thread on a long task. It plans, builds, and reviews in one breath, and the review is soft because the same mind that wrote the code is grading it.
Its context fills up, and quality sags on anything with more than a few moving parts. Those are the signals that the work has outgrown a single seat.
3.8.2Planner, builder, reviewer
The first and strongest split is by phase. One agent plans the work, another builds it, a third reviews it with fresh eyes.
This mirrors how real teams work, and for the same reason: the reviewer catches what the builder cannot see, precisely because it did not write the thing. Separation of roles is separation of blind spots.
3.8.3Specialized agents
Beyond the phases, you spin up specialists: a security reviewer, a test writer, a researcher. Each is a role file of its own, with its own skills and its own narrow standard of good.
A specialist beats a generalist on its home turf, because its whole configuration is bent toward one kind of excellence. You assemble a team, not a hero.
3.8.4Handoffs between them
A team is only as good as its handoffs. One agent's output has to become the next one's input with nothing lost in the gap. The cleanest handoff is a file: agent A writes it, agent B reads it.
---
source: error-report
verdict: needs-fix
handled_by: null
---
Checkout throws on empty cart. Repro + fix below.
The builder writes that, the reviewer reads it and stamps handled_by so it is never picked up twice. The file is the contract between agents, so no context lives only in one agent's head.
Someone has to run the team, and it is simpler than it sounds: one lead agent spawns the others with a clear brief each, waits, and reads back their summaries to decide what happens next. The children do not talk to each other. Reads fan out freely; writes to the same file stay with one agent, so two never edit it at once and clobber each other.
3.8.5Split your first team
This prompt turns your one agent into a small team:
Act as a senior engineer setting up a two-agent workflow.
Give me a builder role and a separate reviewer role in my
tool's format, and a simple file-based handoff: the builder
writes what it changed to a file, the reviewer reads that
file and reports issues before I commit. Keep both short.
My tool and project:
Do this now: paste the prompt, set up the builder and reviewer, and run one change through both so you see the reviewer catch what the builder missed.
