Swarm

---
description: Multi-agent team planner for feature or phase implementation
argument-hint: [task description]
allowed-tools:
  - Read
  - Edit
  - Write
  - Glob
  - Grep
  - Task
  - AskUserQuestion
  - EnterPlanMode
  - ExitPlanMode
  - Bash(ls:*)
  - Bash(mkdir:*)
model: inherit
context: inherit
user-invocable: true
---

# Team Plan

Design a multi-agent team plan for an implementation task. Enters plan mode, explores the codebase, selects agent roles, writes task breakdowns with prompts, and exits for user approval.

## Input

- **$ARGUMENTS** — Task description (e.g., "build phase 4 of user-vaults", "implement auth middleware")

## Agent Roster

Available agent types for teammates. Choose based on what each task requires:

| Agent Type | Tools | Best For |
|-----------|-------|----------|
| `orc:orc-executor` | Read, Write, Edit, Bash, Glob, Grep, Task, Skill, SendMessage, TaskCreate, TaskUpdate, TaskList | Sequential task implementation with per-task commits |
| `orc:orc-impl-verifier` | Read, Write, Glob, Grep, Bash, Task, Skill, SendMessage, TaskCreate, TaskUpdate, TaskList | Verifying must_haves, running tsc/build, code review |
| `orc:frontend-verifier` | All tools | Browser testing (Agent Browser), visual QA, UI polish, CSS fixes |
| `general-purpose` | All tools | Flexible — anything that doesn't fit a specialized type |
| `orc:build-error-resolver` | Read, Write, Edit, Bash, Grep, Glob | Fixing tsc/build errors with minimal diffs |

**Selection heuristics:**
- Implementation work → `orc:orc-executor` (commits per task, follows PLAN.md)
- Verification gate → `orc:orc-impl-verifier` (3-level checks against spec)
- Frontend with UI → add `orc:frontend-verifier` after verification passes
- Default model: `opus` for all teammates (strongest reasoning)

## Execution

### Step 1: Enter Plan Mode

Call `EnterPlanMode`. All subsequent work happens in plan mode (read-only except the plan file).

### Step 2: Explore

Launch 1-3 Explore agents in parallel to understand:

1. **Scope**: What files exist, what needs to be created, what needs to be modified
2. **Patterns**: Existing code to mirror (find the closest analog for each new file)
3. **Spec**: Read any existing plan/spec docs referenced in the task description
4. **Constraints**: ABI signatures, type definitions, pitfall docs, test patterns

Each Explore agent should return:
- File inventory (exists vs. needs creation)
- Mirror patterns (existing file → new file mapping)
- Key constraints and gotchas
- Data flow (what hooks/components already provide)

### Step 3: Design Team

Based on exploration results, decide:

1. **How many executor+verifier pairs?**

   Parse PLAN.md tasks and their `depends_on` attributes. Build dependency DAG: each task is a node, depends_on edges point to prerequisites. Find independent chains: tasks connected by dependency edges form one chain (one executor). Tasks with no shared dependencies are independent chains (run in parallel).

   **Example:**
   - Tasks: 1.1, 1.2(→1.1), 1.3, 1.4(→1.2,1.3)
   - Chains: [1.1→1.2→1.4], [1.3→1.4] — but 1.4 deps on both, so merge: [1.1→1.2], [1.3], both feed [1.4]

   **Wave model (simpler):**
   - Wave 1: tasks with no depends_on → spawn all in parallel (one executor each, or group if tiny)
   - Wave 2: tasks whose deps are all in wave 1 → spawn after wave 1 verifiers pass
   - Repeat until all tasks assigned

   **Minimum viable team (no parallelism):**
   - If all tasks are sequential (one chain): 1 executor + 1 verifier (same as before)
   - If independent tasks exist: N executors + N verifiers (one pair per chain)

   **Cap at 4 executor+verifier pairs.** Beyond 4, group small independent tasks together into one executor.

   Also add:
   - 1 ui-tester (`orc:frontend-verifier`) — only if frontend work involved
   - Add more only if tasks are truly parallelizable

2. **How many tasks per executor?** Group by dependency chain, then cap:
   - Tasks within a chain are sequential (executor does them in order)
   - Independent chains get separate executors
   - **Max 3 tasks per executor.** If a chain exceeds 3, split it: executor A takes the first 3, executor B takes the rest (depends_on: executor-A's verifier passes first)
   - Verification is a separate task (verifier runs after executor tasks)
   - UAT is a separate task (ui-tester runs after verification passes)

3. **What prompts?** Each teammate needs:
   - Working directory (absolute path)
   - Files to read first (spec, contracts, pitfalls — absolute paths)
   - Files to mirror (existing patterns → new files)
   - Hard rules (constraints that MUST be followed)
   - Task IDs for executor (which tasks to execute)
   - Wave number for executor (which wave this runs in)
   - Executor dependencies (which executors must complete before this one starts)
   - `executor_name` for executor (e.g., `executor-1`) — used for PROGRESS/SUMMARY/VERIFIED file names
   - `verifier_name` for executor (e.g., `verifier-1`) — used as SendMessage recipient
   - `paired_executor` for verifier (e.g., `executor-1`) — used as SendMessage recipient and VERIFIED file name
   - `verifier_name` for verifier (e.g., `verifier-1`) — used in sentinel file content and internal messaging

### Step 4: Write Plan

Write the team plan to the plan file using the template structure from [templates/TEAM-PLAN.md](templates/TEAM-PLAN.md).

**Plan file sections (all required):**

1. **Context** — Why, what, current state, scope summary
2. **Team Structure** — Table: role, agent type, model, purpose, wave if applicable
3. **Task Breakdown** — Per executor: assigned task_ids, wave, dependencies, detailed spec per task
4. **Workflow** — Numbered execution steps with decision points (PASS/FAIL branches); if multi-wave, show sequential wave gates
5. **Agent Prompts** — Complete prompts for each teammate role (copy-pasteable)
6. **Key References** — Table of files the team needs, with absolute paths
7. **Critical Constraints** — Non-negotiable rules with rationale

**Executor prompts must include:**
- `task_ids`: [N.M, N.K, ...] — the tasks this executor is responsible for
- `wave`: N — which wave this executor runs in (if applicable)
- `depends_on_executors`: [executor-2, ...] — which executors must complete before this one starts (if applicable)
- `executor_name`: executor-N — used for PROGRESS/SUMMARY/VERIFIED file names
- `verifier_name`: verifier-N — used as SendMessage recipient when notifying verifier

**Quality gates for the plan:**
- Every new file has a mirror pattern identified (existing file to copy from)
- Every agent prompt includes absolute paths (not relative)
- Every executor prompt includes task_ids list
- Every constraint explains WHY (not just what)
- Workflow has explicit FAIL → fix → re-verify branches
- If multi-executor: workflow shows wave gates and executor dependency order
- Task breakdown matches 1:1 with TaskCreate calls the lead will make

### Step 5: Exit Plan Mode

Call `ExitPlanMode` for user approval. The user will review the team plan and either approve or request changes.

## Example

Input: `/orc-swarm build phase 4 of user-vaults`

Output (written to plan file):

```markdown
# Team Plan: Build Phase 4 — Withdraw Flow

## Context
The user-vaults app has phases 1-3 complete. Phase 4 adds the withdraw flow...

## Team Structure
| Role | Agent Type | Model | Purpose |
|------|-----------|-------|---------|
| Lead (me) | — | — | Coordinate |
| `builder` | `orc:orc-executor` | opus | Implement tasks with commits |
| `verifier` | `orc:orc-impl-verifier` | opus | tsc + build + code review |
| `ui-tester` | `orc:frontend-verifier` | opus | Browser UAT + UI polish |

## Task Breakdown
### Task 1 — Add redeem hooks
...
### Task 2 — Add WithdrawForm
...
### Task 3 — Verify
...
### Task 4 — Browser UAT
...

## Workflow
1. Create team → 2. Assign task 1 → builder → ... → 9. Shutdown

## Agent Prompts
### builder prompt
...
### verifier prompt
...

## Key References
| File | Path | Role |
...

## Critical Constraints
- 4-arg redeem only: ...
```

## Rules

1. **Always enter plan mode** — This skill produces a plan, not code
2. **Explore before designing** — Never guess at file paths or patterns
3. **Absolute paths in prompts** — Teammates don't share your working directory context
4. **Mirror existing code** — Every new file should have an identified analog
5. **Minimum viable team** — Don't add agents that won't be used
6. **ui-tester spawns late** — After static verification passes (saves cycles on broken code)
7. **Group by dependency chain, cap length** — Tasks linked by depends_on stay with one executor (preserves context). Independent chains get separate executors (enables parallelism). Max 3 tasks per executor — split longer chains into sequential executor pairs. Cap total executor+verifier pairs at 4.
8. **Explicit fail branches** — Every verification step needs a FAIL → fix path