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. MAXIMIZE: Actively split actions further — find every opportunity to parallelize. Each independent action = its own subagent. Challenge: can any action be split into two?
4. CONFLICT CHECK: Two independent actions editing the same file → make those sequential; all others remain parallel.
5. DISPATCH: Default is Pattern E — TeamCreate with nested subagent waves per teammate. Pre-approve permissions before spawning. Use bare subagent waves only when single domain, no coordination, no context pressure. Single session only when there is literally 1 action.
6. 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.

Transition heuristic: Subagent waves hitting context limits or agents need to share findings → upgrade to Pattern E (teams + nested waves).

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

• Default policy: opus for every subagent, teammate, and wave.
• GitHub Copilot CLI override: gpt-5.3-codex with xhigh effort for every subagent, teammate, wave, and /fleet member.
• When both policies are present, apply the environment-specific override for the active runtime.

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

• Scale teammates to match the work — no artificial cap. Use as many as needed for maximum parallelism (up to ~50 agents total including nested subagents). Token budget is not a constraint.
• Pre-approve common permissions before spawning teammates to reduce friction.
• Assign each teammate a distinct domain and non-overlapping file ownership.
• Assign as many tasks per teammate as the domain requires — no artificial limit.
• Include all task-specific context in spawn prompts: file paths, architecture decisions, acceptance criteria. Teammates do not inherit conversation history.
• Use delegate mode to prevent the lead from implementing work itself.
• Task claiming uses file locking — no race conditions when multiple teammates claim simultaneously.
• 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.

Plan approval workflow

• For risky changes, include "Require plan approval before making changes" in the spawn prompt.
• Teammate enters read-only plan mode, sends plan_approval_request to lead when ready.
• Lead approves or rejects with feedback. Teammate revises if rejected.
• Influence approval criteria in spawn prompt: "only approve plans that include test coverage."

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.
• Display modes: in-process (Shift+Down to cycle) is default; split panes require tmux or iTerm2.
• Teammate interaction: Enter to view session, Escape to interrupt, Ctrl+T for task list.

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. Never downgrade.
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.