Team Orchestration

Orchestration

Patterns for deciding when to delegate, what to delegate to, and how to verify the result. Every session has an implicit team: spawn named subagents with the Agent tool, message them with SendMessage, share work through the task list. There is no separate team lifecycle to manage.

First decision: delegate at all?

Work directly when the task is within reach in a handful of files and tool calls — you have a 1M-token context and delegation costs tokens, latency, and context transfer. Delegate when it buys something real:

The multiplier is real: multi-agent runs cost many times a single session, and most of the benefit comes from context isolation, not conversation between agents. If the work doesn't decompose into independent pieces, a team burns tokens without earning them.

Subagents vs Workflow

• Subagents (Agent tool) — judgment-shaped work: exploration, review, research, an independent implementation track. Named agents persist and can be continued via SendMessage; prefer long-lived named agents over fresh spawns for related follow-ups.
• Workflow — structure-shaped work: fan out N items through find → verify → synthesize stages with deterministic control flow and schema-validated results. Reach for it for review councils, migration sweeps, and multi-lens audits. Requires explicit user opt-in for large orchestrations; keep under the session's size guideline.
• Not usable headless in CI — Workflow invocations hit an interactive approval gate; in CI, keep delegation to flat, one-level Task subagents (see /agent-team:dev's unattended-ci reference).

Parallel writes

No two writers on one file, ever. Give each implementer subagent an explicit file-ownership list; define shared contracts (types, API shapes) yourself before splitting the work; use worktree isolation when writers run concurrently. A file that seems to need two owners gets one owner and one consumer.

Coordination

• Task list — TaskCreate/TaskUpdate with dependency chains when coordinating multiple agents or sweeping phases; skip the bookkeeping for direct single-pass work. On Opus 4.8+/Claude 5-era models these tools exist only with CLAUDE_CODE_ENABLE_TODO_TOOLS=1 (set in this repo's settings.json); without them, coordinate through briefs and messages. Task descriptions carry the context a clean-context agent needs: goal, files, acceptance criteria, patterns to follow.
• Briefs — role + full task spec + what to return. Project context (CLAUDE.md, rules, skills, memory) loads automatically; don't paste it. Have subagents return summaries in their <*-result> block (<explorer-result>, <implementer-result>, <reviewer-result>, <qa-result> — defined in each agent file) — findings and paths, not transcripts.
• Messaging — SendMessage to steer a running agent or continue a finished one. Intervene when a subagent is off track or missing context rather than waiting for a bad result.

Verification topology

• Fresh-context verifiers outperform self-critique: the reviewer must not be the context that wrote the code. Don't add "double-check your work" instructions on top of current models — they self-verify; the external gate exists to catch what a saturated context misses.
• Brief reviewers for coverage, then filter: report every issue with severity and confidence; ranking happens downstream. "Only report high-severity issues" suppresses real findings.
• Escalate to a parallel multi-lens council (correctness, security, architecture, test coverage) only for risk-triggered scope — auth, payments, data, migrations, public contracts.

Tiering

• Model: strong model for the orchestrating/implementing context; cheaper models for scouts, QA runs, and mechanical stages (set in agent frontmatter model:).
• Effort: low for mechanical subagent work, high where correctness is capability-sensitive. Hold the session's own effort constant; vary it across agents, not mid-conversation.

Red flags