Build and deploy parallel execution via subagent waves, agent teams, and multi-wave pipelines. Use when the Decomposition Gate identifies 2+ independent actions or when spawning teams.
orchestrator1483 wordsMITv1.0.0wyattowalsh
Parallel execution via subagent waves, teams, and pipelines. Use when 2+ independent actions need coordination. NOT for single-action tasks.
These rules govern ALL parallelization decisions. Apply them on every task. The skill provides the Decomposition Gate, tier selection, subagent/team best practices, failure recovery, and 6 orchestration patterns.
Before executing any request that involves tool-mediated work:
DECOMPOSE — List the actions needed (file reads, edits, searches, commands, analyses).
CLASSIFY — Which actions are independent (no data dependency)? Which are dependent?
MAXIMIZE — Actively split actions further — find every opportunity to parallelize. Each independent action = its own subagent. Challenge: can any action be split into two?
CONFLICT CHECK — Two independent actions editing the same file become sequential; all others remain parallel.
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.
TRACK — For orchestrated work, create TaskCreate entries before dispatch.
Fast path: Single-action requests skip directly to single session.
Explore-first path: Cannot decompose without exploration? Dispatch parallel exploration subagents first (Pattern F Wave 1), then re-enter the 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.
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.
The lead must not proceed to synthesis until all teammate tasks are accounted for.
honest-reviewResearch-driven code review at multiple abstraction levels with strengths acknowledgment, creative review lenses, AI code smell detection, and severity calibration by project type.
wargameDomain-agnostic strategic decision analysis and wargaming.
View Full SKILL.md
SKILL.md
---
name: orchestrator
description: >
Parallel execution via subagent waves, teams, and pipelines. Use when 2+
independent actions need coordination. NOT for single-action tasks.
license: MIT
metadata:
author: wyattowalsh
version: "1.0.0"
---
# 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
| $ARGUMENTS | Action |
|------------|--------|
| *(empty)* | Load full orchestration guide; apply Decomposition Gate to current request |
| `pattern <A-F>` | Show the named pattern from `references/patterns.md` |
| `tier` | Display Tier Selection table and model guidance |
| `recovery` | Show the Accounting Rule and Recovery Ladder |
## Canonical Vocabulary
| Canonical Term | Meaning |
|----------------|---------|
| **subagent** | A Task-tool-spawned agent running in parallel within a session |
| **wave** | A batch of parallel subagents dispatched in a single message |
| **team** | A TeamCreate-spawned group of teammates coordinated by a lead |
| **teammate** | A member of an agent team with assigned file ownership |
| **lead** | The orchestrating agent in a team; never implements directly |
| **dispatch** | Send one or more subagents/teammates to execute in parallel |
| **gate** | A mandatory checkpoint that must pass before proceeding |
| **accounting rule** | N dispatched = N resolved; no agent silently dropped |
## 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.
- 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.
- 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
| Pattern | Name | Use When | Details |
|---------|------|----------|---------|
| A | Parallel subagent wave | 2+ independent subtasks in a session | see `references/patterns.md` |
| B | Agent team with file ownership | Cross-domain features, large refactors | see `references/patterns.md` |
| C | Competing hypotheses | Debugging, architecture decisions | see `references/patterns.md` |
| D | Plan-then-swarm | Large tasks needing human approval | see `references/patterns.md` |
| **E** | **Teams of subagent-using teammates (DEFAULT)** | **2+ independent streams — use by default** | see `references/patterns.md` |
| F | Multi-wave pipeline | Explore → implement → verify phases | see `references/patterns.md` |
---
## 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
| File | Content | Read When |
|------|---------|-----------|
| `references/patterns.md` | Detailed patterns A-F with ASCII diagrams, key rules, recovery ladder | Designing parallel execution or selecting a pattern |
---
## 7. Progress Visibility (MANDATORY for orchestrated work)
All orchestrated work must produce structured progress indicators via TaskCreate/TaskUpdate.
| Tier | Requirement | Granularity |
|------|------------|-------------|
| **Subagent wave** | MUST | One task per subagent, created before dispatch |
| **Agent team** | MUST | One task per teammate assignment, created during setup |
| **Single session** (3+ steps) | SHOULD | One task per logical step |
### 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.
