Agent teams — an exercise

The subagents lesson and the "what landed recently" lesson together describe every piece you need to run a small team of agents from one main session. This lesson is the honest, worked shape of putting those pieces together — the coordinator pattern, the kind of task that earns multi-agent treatment, and the kind that doesn't.

The shape: coordinator plus specialists

The useful mental picture isn't "a swarm of agents." It's one coordinator (the main session, with the user's conversation) and a handful of specialists, each with a scoped job. The coordinator decides what to delegate, writes the briefing (or, for a fork, doesn't need to), merges the returned conclusions, and talks to the user.

Three honest points about this picture:

• Only the coordinator talks to the user. A delegated agent's output comes back to the coordinator, and the coordinator decides what the user should see.
• Each delegation has a clearly-scoped job. "Do some stuff" is the wrong prompt; "look at X files, answer Y, under 200 words" is the right one.
• The coordinator is the audit trail. If the user later asks "why did we conclude Z?", the answer has to be in the coordinator's history, not scattered across half a dozen terminated forks.

A worked exercise

Pretend the user has just said: "We're trying to ship this branch. Audit what's left, and then start fixing what you can."

Here's a plausible team-of-agents decomposition.

1. Fork — the audit

The audit is a research question grounded in the current session (the branch, its commits, what you've both been working on). Send a fork:

Agent({
  subagent_type: "fork",
  name: "ship-audit",
  description: "Branch ship-readiness audit",
  prompt:
    "Audit what's left before this branch can ship. Check: uncommitted " +
    "changes, commits ahead of main, whether tests exist, whether CI-relevant " +
    "files changed, whether the GrowthBook gate is wired up. Report a punch " +
    "list — done vs. missing. Under 200 words.",
});

Why a fork, not a subagent: the fork already knows what branch, what the recent work has been, what the user cares about. A plain subagent would need all of that explained.

Return value: a 200-word punch list. Not a transcript of file reads; not twenty tool outputs. A punch list.

2. Workflow — the parallel fixes

The punch list lands. Say it has three independent issues, each scoped to different files. This is exactly the shape a Workflow fits — each fix is independent, so do them in parallel; each fix should be reviewed before merging, so run a verify pass.

export const meta = {
  name: "branch-fixes",
  description: "Apply the audit's fixes in parallel, verify each",
  phases: [{ title: "Fix" }, { title: "Verify" }],
};
 
const FIXES = args.punchList; // from the fork's audit
 
const applied = await pipeline(
  FIXES,
  (fix) => agent(fix.prompt, {
    label: `fix:${fix.key}`,
    phase: "Fix",
    isolation: "worktree",
  }),
  (result) => agent(`Adversarially verify: ${result.summary}`, {
    label: `verify:${result.key}`,
    phase: "Verify",
  }),
);
 
return { verified: applied.flat().filter((r) => r.verdict?.isSafe) };

Each fix runs in its own worktree (isolation: "worktree"), so three parallel changes don't fight over the same working tree. Each is verified by an independent adversarial agent. The coordinator gets back a set of verified branches it can review and merge.

3. Plain subagent — the summary for the user

The coordinator now has three verified branches and a stack of decisions. The user asked "ship the branch"; they don't want to read three worktree diffs. A subagent with a constrained tool list (Read, Grep, Glob — no editing) writes a one-paragraph summary of what was fixed and what's still open:

Agent({
  name: "ship-summary",
  description: "Summarize the audit + fix results for the user",
  subagent_type: "general-purpose",
  prompt:
    "Summarize the branch-fix workflow's output (attached below) as one " +
    "paragraph for the user. Include: what was fixed, what was left open " +
    "and why, what the recommended next step is. Max 150 words.\n\n" +
    "<workflow-output>" + JSON.stringify(workflowOutput) + "</workflow-output>",
});

The coordinator shows this paragraph to the user. The user sees one clear message instead of three worktree diffs and a workflow log.

The rules that keep a team of agents honest

Three rules that separate a working team from a demo:

• Never predict a delegated agent's result. If the user asks while a fork or a workflow is in flight, the right answer is "still running." The second you start guessing results to look responsive, the coordinator stops being trustworthy.
• Only the coordinator talks to the user. If you find yourself surfacing a subagent's raw output verbatim, that's a sign the delegation didn't produce a conclusion — fix the briefing, don't dump the transcript.
• Delegate only when delegation is cheaper than the work. A single bash command does not need a subagent. The useful test: "would I have to brief this agent for longer than it'd take to do the work myself?" If yes, do it yourself.

When not to reach for a team

Three shapes where "team of agents" is the wrong tool:

• Single-threaded conversations with the user. The user is iterating, redirecting, learning. A team of background agents adds latency and merge-logic to something that was already working as a conversation.
• Tasks whose intermediate output matters. If you need to course-correct partway through — "wait, don't do that, do this instead" — a fork or workflow that already left is no longer steerable. Keep it in the main conversation.
• Tasks whose scope is small. Two or three tool calls is faster done directly than orchestrated.

The useful heuristic is: team-of-agents is good at broad fan-out that can be done in parallel, and independent conclusions whose intermediate work is noisy. It is bad at tight, iterative back-and-forth, which is what a conversation is best at.

A note on size guidelines

Most sessions carry a default workflow size guideline — "keep under 10 agents" is common. This isn't a hard limit; it's a default for ambiguous requests. If the user explicitly asked for 30 agents (they said "fan out across every changed file," they typed "ultracode," they invoked a specific saved workflow), run with 30. If the user asked a question that only incidentally benefits from fan-out, stay inside the default.

The rule is to match the scale the user actually asked for. Not the largest you could justify.

What to remember

• The honest multi-agent shape is a coordinator plus specialists. The main session coordinates, holds the user's conversation, and merges results. Each delegation has a scoped job.
• Reach for a fork when the task is grounded in the current session; reach for a plain subagent when it isn't; reach for a Workflow when the shape is fan-out + fan-in (or pipeline) and you want deterministic orchestration.
• Rules that keep a team honest: never predict a delegated result, only the coordinator talks to the user, delegate only when delegation is cheaper than the work.
• Don't team-up single-threaded conversations, iterative tasks that need course-correction, or small tasks. Multi-agent is good at broad fan-out and independent conclusions, not at tight iteration.
• The size guideline (e.g. "under 10 agents") is a default for ambiguous requests. Match the scale the user actually asked for — not the maximum you could justify.
• Use isolation: "worktree" on parallel edit agents so they don't fight over the working tree. Review the returned diffs on your own terms.