Subagents & orchestration
Subagents fix two problems at once: long sessions polluting your main context, and serial work that could run in parallel. The orchestrator pattern is how you wire them — and the briefing rule is how you keep them useful.
Two reasons subagents matter
1 · Parallel work
Three independent tasks run at once — researching a library, writing tests, refactoring a module. Same wall-clock time, three results. The classic case for any kind of parallelism.
2 · Context isolation (often the bigger win)
Each subagent runs its own context window. The orchestrator stays clean. The subagent fills its own context with the search noise, the file-reading detours, the dead-end attempts — then throws the whole context away when it returns its result.
For long sessions, this is what keeps the main agent sharp. A 50-turn investigation that would have polluted the main context becomes 10 small clean ones.
When to spawn a subagent
The simple test: would this task fill up the main agent's context with noise that the rest of the work doesn't need?
- Yes: exploring an unfamiliar codebase, researching a library's API, running 20 grep searches to find one symbol, debugging a flaky test.
- No: a small edit, a focused change you already understand, anything where the main agent's context already has what it needs.
The orchestrator pattern
The main agent is a tech lead. Subagents are contractors with narrow scopes.
- Orchestrator — holds the plan, routes work, integrates results into the main thread.
- Subagent A — researches X, returns a 200-word summary.
- Subagent B — writes tests for Y, returns the test file.
- Subagent C — refactors Z, returns the diff.
The orchestrator never sees the subagent's working context — only its final result. That's the whole point.
Briefing template for subagents
You are a subagent. The orchestrator has handed you this task:
## Goal
<1 sentence — what you're producing>
## Context
<3–5 bullets — only what's needed for this task>
## What to do
1. <step>
2. <step>
3. <step>
## What NOT to do
- Don't expand scope beyond <explicit limits>
- Don't make assumptions about <ambiguity> — ask in the result if unclear
## Output format
<Markdown? JSON? A diff? A 200-word summary? Be specific.>
## What done looks like
<Concrete acceptance criterion the orchestrator can verify>Common mistakes
Spawning subagents for trivial work
Subagents have spin-up cost. For a 30-second task, just do it inline. The rule of thumb: if the task is <2 minutes for the main agent, don't bother spawning. The cost of briefing exceeds the savings.
Briefing too thinly
"Look up how X works" is not a brief — it's a wish. The subagent needs the goal, the context, what good looks like, and what bad looks like. A thin brief produces shallow work.
Letting the subagent do too much
A subagent should have one clear deliverable. If you find yourself listing 5 unrelated things in one brief, split it into 5 subagents.
Treating subagent output as ground truth
The subagent could have hallucinated, just like the main agent. Spot-check critical results before integrating. The reviewer mindset applies here too — you're reviewing the subagent's work, not just accepting it.