Chapter 3: Building an AI team

An AI team is a set of specialised agents with defined roles, a topology that says who hands what to whom, permissions per role, a budget, and a human who owns the outcome. This chapter assembles one, runs it through a real feature, and lists the ways it fails.

Roles

A role is a sub-agent definition (Chapter 2) tuned for one kind of work. Six cover most teams:

Role	Reads	Writes	Tools	Returns
Planner	Intent, codebase	The spec and the task contracts	Read, search; no shell, no edit	A plan: ordered contracts with dependencies
Implementer	One contract, the files it names	Code in its scope	Read, edit, run the named tests	Diff + summary + test output
Test writer	The spec	Tests only	Read, edit under tests/, run tests	Failing tests, one per criterion
Reviewer	Diff + spec	Nothing	Read, grep	Findings with file, line, severity
Security reviewer	Diff + dependency list	Nothing	Read, grep; optionally a scanner	Findings; a hard block if secrets or injection
Integrator	All diffs, full suite	Merge resolution only	Read, edit, run full suite	Green suite or a list of conflicts

Two roles are deliberately absent. There is no "fixer" that takes review findings and patches them - findings go back to the implementer whose scope they fall in, through a new narrow contract. And there is no "approver": approval is the human.

Topologies

How the roles connect depends on the task. Three shapes cover most work.

Pipeline - sequential, each stage's output is the next stage's input. Right for tasks with strict ordering: migration, then model, then endpoint.

Fan-out / fan-in - one planner, several implementers in parallel, one integrator. Right for features with independent parts.

Critic loop - an implementer and a reviewer alternate a bounded number of times before the human sees anything. Right for quality-sensitive pieces (auth, billing, anything touching money). Bound it: two rounds, then human, regardless.

Real features mix them: fan-out for the parallel parts, a critic loop on the sensitive one, a pipeline overall.

Worked example: a feature with five agents and one human

The feature. Export a customer's data as a ZIP (GDPR right of access): a background job that collects the data, a signed download URL, an endpoint to request the export, and an email when it is ready. Out of scope: deletion, admin UI.

Hour 0:00 - Human writes the intent (three sentences, as above) and starts the planner.

0:00-0:10 - Planner. Reads the codebase (read-only). Produces docs/specs/data-export.md with acceptance criteria, and four contracts with a dependency graph:

1. job: the collection job, writes a ZIP to object storage. No dependencies.
2. url: signed-URL helper. No dependencies.
3. endpoint: POST /api/me/export enqueues the job; GET /api/me/export/{id} returns status and, when done, the URL. Depends on 1 and 2 for the interface only - the planner fixes the interface now (function names, return types) and writes it into all three contracts.
4. email: notification on completion. Depends on 1 for the event name - also fixed now.

The planner also writes a fifth contract for the test writer: one failing test per criterion.

0:10 - Human reviews the spec and the contracts. Ten minutes. Adds one criterion the planner missed: an export must not include another user's data if the user ID is tampered with. This is the kind of thing a planner skips and a human who has been on call does not.

0:20-0:30 - Test writer produces fourteen failing tests from the spec. Human skims the test names against the criteria: all present.

0:30-0:50 - Fan-out. Four implementers start in parallel, each with its contract and the tests in its scope. Each returns a diff and a summary. Implementer 3 (endpoint) reports an ambiguity: the spec does not say what GET returns before the job has started. Human answers in the spec file; implementer 3 continues.

0:50-1:00 - Integrator applies the four diffs in dependency order and runs the full suite. One conflict: implementers 1 and 4 both added a StorageClient helper. Integrator sends a narrow contract to implementer 4: "delete your StorageClient; import from app/storage.py." Suite green.

1:00-1:10 - Reviewer and security reviewer read the combined diff, in parallel. Reviewer: two findings (a missing index on exports.user_id; a log line with the full URL). Security reviewer: one hard finding - the signed URL has a 7-day expiry, spec says 24 hours. All three go back as narrow contracts to the implementers whose scope they fall in.

1:10-1:20 - Second integration, suite green, reviewers clean.

1:20 - Human reads the final diff. Not the transcripts: the diff, against the spec, with the review findings as a guide to where to look. Opens the PR. Merges behind a flag.

Eighty minutes. Five agents, roughly twelve agent-sessions, one human for about thirty minutes of attention - at the start (intent, spec review), in the middle (one spec answer) and at the end (final review). Everything else ran while the human did something else.

Permissions per role

The table of roles above is the permission model. Make it literal in the tool configuration:

• Planner, reviewers: no shell, no edit. They produce text.
• Test writer: edit under tests/ only; shell limited to running tests.
• Implementers: edit within the contract's scope; shell limited to the named test command; no git write, no package install.
• Integrator: edit anywhere (it resolves conflicts); full test suite; still no push.
• Nobody: production credentials, CI secrets, merge, deploy. Those are the human's, through the normal branch protection (Module 5).

Any agent that reads untrusted input - a GitHub issue from an external user, a web page, a document - is in the planner/reviewer group: text in, text out, no actions.

Budget

Twelve agent-sessions is twelve times the cost of one. Bound it before you start:

• Per-session turn limit. An implementer that has not passed its tests in forty turns stops and reports; the orchestrator (or human) decides, not the agent.
• Per-feature budget in tokens or currency, enforced by the tool where it supports it, tracked by you where it does not.
• Critic loops bounded at two rounds.
• Measure. Cost per merged feature, next to lead time and change failure rate (Module 6). If the team costs more than it saves, you will know.

Five failure modes

Failure	What it looks like	Control
Echo chamber	Reviewer and implementer share a model and a bias; the review finds nothing wrong because it would have written the same code	Different model or at least a different system prompt for the reviewer; a human review that is not optional
Runaway cost	A worker loops on a failing test; a critic loop never converges	Turn limits, round limits, a budget with a hard stop
Conflicting edits	Two workers touch the same file; the merge is a mess	Planner fixes interfaces and assigns disjoint file scopes; integrator owns the merge; narrow contracts for conflicts
Lost context	The orchestrator summarised a constraint away; a worker never saw it	Constraints live in the spec file and the rules file, not in the orchestrator's memory; every contract links the spec
Diffusion of accountability	"The reviewer agent approved it"	The agents do not approve. A named human merges, and the policy says so (Module 5)

A sixth, quieter one: a team of agents makes vagueness expensive faster. One agent with a weak spec wastes ten minutes. Five agents with a weak spec waste fifty, in parallel, and produce five incompatible interpretations. The team amplifies whatever you give it. Give it a spec.

Starting small

Do not build the five-agent team on day one. A sequence that works:

1. One agent, read its sessions until you recognise the five signals from Chapter 1.
2. Add a reviewer. One implementer, one separate reviewer agent. Notice what the reviewer catches that you would have missed, and what it misses.
3. Add a planner that writes the spec and contracts for you to edit. Notice where you edit it; those edits are the rules-file lines you are missing.
4. Fan out when a feature has genuinely independent parts. Two implementers, then three.
5. Measure cost and review findings at each step. Stop adding agents when the next one does not move the numbers.

Summary

• Roles: planner, implementer, test writer, reviewer, security reviewer, integrator. No fixer, no approver.
• Topologies: pipeline, fan-out / fan-in, bounded critic loop; real features mix them.
• Permissions are the role table made literal. Readers of untrusted input never act.
• Budget turns, rounds and cost before starting; measure cost per merged feature.
• Five failure modes, each with a control; the team amplifies the spec it is given.
• Build up one role at a time, measuring as you go.