subagent-orchestration

Sub-agent Orchestration

A sub-agent is a fresh context window with its own tools that does one scoped task and returns a single final message. The agent that spawned it (the orchestrator) sees only that final message — never the sub-agent's intermediate reads, greps, or reasoning. That one fact drives almost every decision below, so hold onto it:

The orchestrator pays for the sub-agent's conclusion, not its work.

Harnesses name this primitive differently — a Task tool, an Agent tool, a "subagent", a Workflow step — but the contract is the same everywhere. This skill is written to that contract, not to any one tool. Substitute your harness's spawn mechanism wherever you see "spawn a sub-agent".

Most agents get the balance wrong in both directions: they under-delegate broad searches and parallelizable work (doing serially, inline, what should fan out), and they over-delegate trivial lookups (spawning a whole agent to read one known file). The goal here is to get the balance right.

---

The one-line test

Delegate when the work is large to do but small to report, or independent enough to run in parallel. Keep it inline when you need the details rather than a summary, when the steps depend on each other turn-by-turn, or when it's faster to just do it than to describe it.

Everything below is that test, expanded.

---

When to spawn a sub-agent

1. Fan-out search / exploration. The question can only be answered by sweeping many files, directories, or naming conventions, and you want the conclusion, not the raw material. "Where is auth enforced across this monorepo?" → an explorer reads 40 files and returns a 15-line map. Your context grows by 15 lines, not 40 files.

2. Independent work that can run in parallel. N items with no cross-dependencies — review 8 changed files, research 5 topics, audit 12 endpoints. Spawn them concurrently and wall-clock collapses to the slowest single item instead of the sum.

3. Large-but-disposable intermediate output. Any task whose byproducts are huge but whose payload is small: tailing logs to find the one stack trace, running a test suite to extract the failures, scanning a dataset for outliers. Isolation keeps the noise out of your context.