Agent Team Orchestration

Adding agents to a task is like adding people to a project: it pays off only when the work splits along clean seams, and it costs coordination the moment it does not. This skill plans multi-agent work as an explicit organization design — roles with briefs, handoff contracts, isolated write surfaces, and a verification step that treats every subagent's output as a claim to check rather than a fact to merge.

When to use this skill

A task decomposes into parts that touch disjoint files, systems, or questions
Research or review work that benefits from independent, unanchored passes
A long task where exploration would flood a single agent's context
You are about to spawn a second agent and have not written down who owns what
Not for tightly coupled edits to shared state — sequence those inside one agent instead

Workflow

Justify the split. Name the seam: independent files, independent questions, or independent judgment (as in adversarial review). If two agents would need to edit the same file or share evolving state, do not parallelize that part.
Write a role brief per agent — the brief is the interface:
- Goal: one sentence, an outcome rather than an activity
- Inputs: exactly the context it receives — paths, data, constraints; assume it knows nothing else
- Boundaries: what it must not touch or decide; where its authority ends
- Output contract: format, required fields, and a "cannot complete" escape hatch
- The standard: a stranger could execute the brief without asking questions. A vague brief multiplies work instead of dividing it.
Choose the topology from the dependency shape: fan-out/fan-in for independent shards; a pipeline when each stage transforms the last; a red-team pair when the goal is judgment quality. Keep depth shallow — orchestrators orchestrating orchestrators is where accountability goes to die.
Isolate write surfaces. Each agent owns its own files or workspace; two writers on one path is a merge conflict you scheduled on purpose. Readers may overlap freely.
Size the work units so a failed agent costs minutes, not the afternoon — and so each result fits comfortably back into the orchestrator's context when it reports.
Verify before merging. Spot-check every result against its contract and against reality: does the file exist, does the test pass, does the cited source actually say that. Contradictions between agents are findings to surface, never noise to average away.
Merge with attribution. The synthesis records which agent produced what, so a wrong conclusion can be traced to its source and re-run narrowly instead of redoing everything.
Write the retry policy down: on a contract violation, re-brief and re-run once with the failure named; on the second violation, the orchestrator takes the work back inline.

Output format

An orchestration plan, written before any agent launches:

Task: <outcome>
Seam: <why this splits cleanly>     Topology: <fan-out | pipeline | red-team>

| Agent | Goal | Owns (writes) | Reads | Output contract |
|-------|------|---------------|-------|-----------------|

Merge step: <who verifies what, and how conflicts get resolved>
Abort rule: <the signal that says stop parallelizing and do it inline>

Guardrails

The orchestrator never rubber-stamps: every subagent claim gets at least a spot check before it reaches the user
Subagents never get more authority than the orchestrator has; permissions do not widen downstream
Independent judgment requires independent inputs — a red-team agent must not be told the answer is "probably fine" before checking it
Parallelism multiplies cost; three agents should be buying speed or independence, not company
If writing the briefs takes longer than doing the task alone, that is the answer: do it alone

Failure smells

Two agents editing one file "carefully"
A subagent returning an essay when the contract said a table
Merged output nobody can attribute to a source agent
Nesting deeper than three levels
An orchestrator whose only contribution is concatenation