Orchestration: Subagents, Agent Teams & Parallel Execution

These rules govern ALL parallelization decisions. Apply them on every task.

Not for single-action requests, simple file edits, or sequential-only workflows.

Dispatch

Canonical Vocabulary

0. Decomposition Gate (MANDATORY before any work)

Before executing any request that involves tool-mediated work:

1. DECOMPOSE: List the actions needed (file reads, edits, searches, commands, analyses).
2. CLASSIFY: Which actions are independent (no data dependency)? Which are dependent?
3. DISPATCH: 2+ independent streams → default to TeamCreate with subagent waves per teammate (Pattern E). Single domain only, no coordination needed → parallel Task calls. Exactly 1 action → single session.
4. CONFLICT CHECK: Two independent actions editing the same file → make those sequential; all others remain parallel.
5. TRACK: For orchestrated work, create TaskCreate entries before dispatch (see Section 7).

Fast path: Single-action requests skip directly to single session.

Explore-first path: Cannot decompose without exploration → spawn parallel exploration team first (Pattern F Wave 1), then re-enter this gate.

User override: Explicit user requests for a specific execution approach take precedence.

Common rationalizations (all invalid)

• “It’s faster to do it myself” — Parallel subagents complete N tasks in time of the slowest 1.
• “The task is too simple” — If it has 2+ independent actions, parallelize them.
• “I’ll just do this one thing first” — Decompose BEFORE doing anything.

Mode constraints

• Plan mode: Read-only subagents only. No teams, no write-capable agents.
• Implementation mode: All tiers available. Default to highest applicable tier.
• Delegate mode: Lead orchestrates only. All implementation via teammates/subagents.

Skill integration

When a superpowers skill is active, the gate operates WITHIN the skill’s execution structure:

• Phase-gated skills: Parallelize within each phase. Do not parallelize across phase boundaries.
• Per-task review loop skills: The skill’s sequential structure takes precedence. Parallelize exploration within each task, not across tasks.
• Dispatch-precondition skills: The skill’s “Don’t use when” conditions remain valid. The gate does not override skill-level safety guards.

1. Tier Selection (mandatory — highest applicable tier wins)

Select the highest tier whose criteria are met. Never select a lower tier to reduce cost.

2. Subagent Best Practices

Spawning

• One response, multiple Task calls. All independent subagents MUST be dispatched in the same message.
• Use run_in_background: true for subagents whose results are not needed immediately.
• N independent actions = N parallel subagents. Merge only when they share file/directory scope.

Prompt-tuning

• Give every subagent a detailed, self-contained prompt with exact file paths, expected output format, and domain context.
• Do NOT rely on the subagent inheriting conversation history — it does not.

Model selection

• opus — the ONLY model. Every subagent, every teammate, every wave. No exceptions. Never downgrade.

Context management

• Delegate verbose operations (test suites, log parsing, doc fetching) to subagents.
• Use subagent resumption (agent ID) for multi-phase work rather than spawning fresh.
• After a wave completes, apply the Accounting Rule (Section 4) before synthesizing.

3. Agent Team Best Practices

• Start with 2-4 teammates. Scale up only when justified.
• Assign each teammate a distinct domain and non-overlapping file ownership.
• Aim for 5-6 tasks per teammate — productive yet manageable for check-ins.
• Include all task-specific context in spawn prompts: file paths, architecture decisions, acceptance criteria.
• Use delegate mode to prevent the lead from implementing work itself.
• Never assign two teammates overlapping file ownership.
• The lead must not proceed to synthesis until all teammate tasks are accounted for (Section 4).

4. Quality Gates & Failure Recovery

The Accounting Rule (MANDATORY after every parallel dispatch)

When N agents are dispatched, all N must be accounted for before proceeding:

1. COLLECT: Wait for all N agents to return. Poll with TaskOutput block=false for timeout detection.
2. TALLY: Results received vs dispatched. Missing = unresolved.
3. RESOLVE all non-successes via the Recovery Ladder (see references/patterns.md).
4. GATE: Do NOT advance until every agent has SUCCESS or explicit SKIP.
5. REPORT: Summarize all agent outcomes via TaskUpdate before proceeding.

Hooks for automated enforcement

• TeammateIdle hook: prevent teammates from idling before work is verified.
• TaskCompleted hook: prevent tasks from closing before tests pass.
• Both use exit code 2 to send feedback and keep the teammate/task active.

5. Orchestration Patterns

6. Limitations

• No session resumption for teammates (/resume and /rewind won’t restore them).
• No nested teams (teammates can use subagents but cannot spawn teams).
• One team per session. Clean up before starting a new one.
• Lead is fixed — cannot transfer leadership.
• All teammates inherit the lead’s permission mode at spawn.
• Subagent resumption may not recover from all failure modes (re-spawn instead).
• No built-in timeout detection — orchestrator must poll with TaskOutput manually.
• Recovery re-spawns count toward the session’s agent budget.

Critical Rules

1. Never dispatch independent actions sequentially — all independent Task calls MUST appear in one response.
2. Always run the Decomposition Gate before any tool-mediated work; skipping it is never acceptable.
3. Never reduce parallelism, tier, or model quality for any reason — always use opus, no exceptions.
4. Never silently drop a failed subagent — N dispatched = N accounted for; apply the Accounting Rule after every wave.
5. Never advance to Wave N+1 with unresolved agents — resolve all agents in Wave N first.
6. Always create TaskCreate entries before dispatching subagent waves or agent teams — silent orchestration is forbidden.
7. Never assign two teammates overlapping file ownership — overlapping edits cause lost work.
8. Always include full context in subagent and teammate prompts — they do not inherit conversation history.

Reference File Index

7. Progress Visibility (MANDATORY for orchestrated work)

All orchestrated work must produce structured progress indicators via TaskCreate/TaskUpdate.

Rules

• Create tasks before execution begins, not retroactively.
• Each task MUST have a descriptive activeForm in present continuous tense naming the specific action and target.
• Update tasks to in_progress before starting, completed immediately after.
• After wave completion + accounting, summarize all agent outcomes before dispatching the next wave.