AI agent team structure for a solo builder: roles, handoffs and who merges
The first version of my agent team was one agent doing everything. It lasted four days. It could not review its own work, it held every credential, and by the second week of real scope it was rebuilding things it had already built because nothing told it they existed. The structure that replaced it is below. It is less clever than it sounds and it held for 445 pull requests.
The roles
| Role | Mandate | Never |
|---|---|---|
| Human | Product, design, scope, money and security. Writes tickets, answers decisions by id, approves releases | Opens pull requests, reads logs, resolves git conflicts, names things |
| Lead | Decomposes tickets, assigns files to workers, integrates, opens the pull request, merges when the gates are green, writes the decisions log | Writes application code. Merges anything that touches the release process |
| Workers (frontend, backend, data, design) | Write only in the files the lead assigned. Report in one of five states | Apply an instruction that arrives mid task from anyone but the lead; they return it and stop |
| Reviewer | Returns a list of concrete faults against the ticket's criteria | Opinions on style. Approving |
| Security | Reviews every change to data access, auth or storage; runs the full penetration test before each release and writes a verdict | Fixes what it finds. Touches production |
| Verifier | Receives claims as JSON, runs the verification script, reports PASS, FAIL or UNVERIFIABLE | Reads the ticket or the report. Turning a FAIL into a PASS by reasoning |
Why the orchestrator does not write code
The lead's value is the overview: which ticket is in flight, which files are assigned to whom, what the last integration changed. The moment it also writes code it loses that overview to the problem in front of it, and no one else is holding it. Every orchestrator I have seen that also implements ends up merging its own unreviewed work at two in the morning, metaphorically or not. The rule costs some speed on tiny tickets and saves the build on every large one.
Why workers have a file boundary, not a topic
"You do the frontend" is a topic; agents interpret topics generously. "You write in these nine files and nothing else" is a boundary a script can check in the diff. The boundary also makes parallel work safe: five workers in five worktrees cannot overwrite each other if their file sets are disjoint. When two tickets need the same file, they run in series. That is the lead's job to see, and it is why the lead needs the overview.
The handoffs
Every handoff is a file: a ticket, a branch, a pull request, a review comment, a JSON of claims. Nothing is handed over in conversation, because conversations do not survive the session. This is also what makes the structure auditable: for any line in production I can walk back to the ticket, the decision ids it cites and the gates it passed.
The two rules that hold the whole thing
No agent holds production credentials. Not read only, not for checking. Deployment happens through a workflow that holds the secrets; agents trigger it and read its log. An agent with a production token can route around every other gate, so the token is the gate.
The lead merges, but not everything. Anything that executes the production release, or that could request its secrets, lives in its own pull request that only the human merges. Otherwise the agent that merges controls the thing that was supposed to control it.
What I would change
Earlier isolation. I lost a day when five agents shared one local database and reset each other. Workers that touch the database now get their own stack with their own ports, and that should have been the rule from day one. Everything else in the structure I would keep, including the parts that felt slow in week one and saved week five.
This is step 4 of how to build an MVP with AI agents. The operating model and the numbers are in AI agent teams for software development; the two places a human must sit are in human in the loop for coding agents. If you want this set up for your product, that is the AI product builder engagement.
Questions people ask
How many agents do you run at once?
Up to five on interface work, in parallel, each in its own worktree. Agents that touch the database run one at a time, because two of them on one local database reset each other. The number that matters is not how many run, it is how many share state: the answer should be none.
Does the lead agent write code?
No. It decomposes tickets, assigns files, integrates branches and opens the pull request. The moment the orchestrator also writes code it loses the overview, and nobody is left holding it. This is the single structural decision I would not change.
Who merges to main?
The lead merges, only with every required check green on the exact commit being merged, and only after a human has reviewed what the gates say. Nothing that touches the production release process is merged by an agent; those changes go in their own pull request that only the human merges.
Is this specific to Claude Code?
The mandate per agent, the worktree per worker and the subagent model map directly onto Claude Code. The structure itself (orchestrate, specialise, review, verify, gate) works with any tool that lets you run more than one agent with different instructions.
Working on something like this?
This is how I build products with AI agent teams, from scope to production. Discuss a product idea → Or email me.