name: plan-swarm
description: "Execute a plan file with parallel agent swarm (dependency-aware)"
argument-hint: " [--workers N] [--model MODEL]"
allowed-tools: ["Read", "TaskCreate", "TaskUpdate", "TaskList", "TaskGet", "Task", "Bash"]
model: opus
skills: ["test-driven-development"]

Plan Swarm Command

Execute a plan file using parallel worker agents. Requires a plan file. All workers complete → done.

Note: Loop and swarm are interchangeable - swarm is just faster when tasks can run in parallel. Both enforce exit criteria and sync state.

Uses Claude Code's built-in Task Management System for dependency tracking and visual progress (ctrl+t).

Supported Plan Types

This command works with plans from:
- /plan-creator - Implementation plans
- /bug-plan-creator - Bug fix plans
- /code-quality-plan-creator - LSP-powered quality plans

Arguments

• <plan_path> (required): Path to the plan file
• --workers N (optional): Max concurrent workers (default: 3)
• --model MODEL (optional): Model for workers: haiku, sonnet, opus (default: sonnet)

Instructions

Step 1: Read the Plan (Only)

The user invoked this skill with arguments: $ARGUMENTS

The first argument is the plan file path. Read it and extract tasks. DO NOT read other files, grep, or explore the codebase - just parse the plan:
1. Files to Edit - existing files that need modification
2. Files to Create - new files to create
3. Implementation Plan - per-file implementation instructions
4. Requirements - acceptance criteria
5. Exit Criteria - verification script and success conditions
6. Dependency Graph - file dependency phases for execution ordering

Step 2: Create Task Graph

Create a task for each work item and build an ID map as you go:

TaskCreate({ "subject": "Create auth types", ... })        // → task "1"
TaskCreate({ "subject": "Implement auth middleware", ... }) // → task "2"
TaskCreate({ "subject": "Add route protection", ... })     // → task "3"
TaskCreate({ "subject": "Run exit criteria", ... })        // → task "4"

Full TaskCreate per item:

TaskCreate({
  "subject": "Implement auth middleware",
  "description": "Full implementation details from plan - self-contained",
  "activeForm": "Implementing auth middleware"
})

Translate the plan's ## Dependency Graph table to addBlockedBy. The plan contains a table mapping files to phases and dependencies — use it to set up the task graph:

Plan's Dependency Graph:
| Phase | File                    | Action | Depends On                |
|-------|-------------------------|--------|---------------------------|
| 1     | `src/types/auth.ts`     | create | —                         |
| 2     | `src/middleware/auth.ts` | create | `src/types/auth.ts`       |
| 3     | `src/routes/auth.ts`    | edit   | `src/middleware/auth.ts`   |

File→Task map: types→"1", middleware→"2", routes→"3", exit criteria→"4"

// Phase 1: no deps (task "1" is ready immediately)
// Phase 2: middleware depends on types
TaskUpdate({ "taskId": "2", "addBlockedBy": ["1"] })
// Phase 3: routes depends on middleware
TaskUpdate({ "taskId": "3", "addBlockedBy": ["2"] })
// Exit criteria blocked by all implementation tasks
TaskUpdate({ "taskId": "4", "addBlockedBy": ["1", "2", "3"] })

If the plan has no ## Dependency Graph section (older plans), infer dependencies from per-file Dependencies/Provides fields.

A task with non-empty blockedBy shows as blocked in ctrl+t. When a blocking task is marked completed, it's automatically removed from the blocked list. A task becomes ready when its blockedBy list is empty.

Task types:
- File edits/creates → one task per file
- Major requirements → one task each
- Exit criteria verification → final task, blocked by all others

Step 3: Spawn Workers

Worker limit N = --workers value from arguments or 3 if not specified. This is a queue — spawn up to N, then wait for completions before spawning more.

Mark each task in_progress before spawning its worker. Spawn up to N background workers in a SINGLE message (all Task calls in one response).

TDD in worker prompts: Workers must follow red-green-refactor. Include TDD instructions in every worker prompt:

Task({
  "description": "Task-1: Implement auth middleware",
  "subagent_type": "general-purpose",
  "model": "sonnet",
  "run_in_background": true,
  "allowed_tools": ["Read", "Edit", "Write", "Bash", "Glob", "Grep"],
  "prompt": "Execute this ONE task using TDD then exit:\n\nTask ID: 1\nSubject: Implement auth middleware\nDescription: <full details from plan>\n\nTDD Protocol:\n- If this is a TEST FILE task: Write the tests, then run them and verify they FAIL (RED). Tests must fail because the feature is missing, not because of syntax errors.\n- If this is a PRODUCTION CODE task: Implement the code, then run the corresponding tests and verify they PASS (GREEN). Write only the minimum code needed to pass.\n- If this is a non-code task (config, types, docs): Execute directly.\n\nSteps:\n1. Execute the task following TDD protocol above\n2. Commit the changed files: git add <changed-files> && git commit -m \"<brief description of what was done>\"\n3. Output ONLY a one-line summary\n4. Exit immediately"
})

After all Task() calls return, output a status message like "3 workers launched. Waiting for completions." and end your turn. The system wakes you when a worker finishes.

Step 4: Process Completions

When a worker finishes, you are automatically woken. Then:

1. TaskUpdate — mark the finished worker's task as completed
2. TaskList() — see overall progress and find newly unblocked tasks
3. Find ready tasks: A task is ready when its status is pending AND its blockedBy list is empty. Completing a task automatically removes it from other tasks' blockedBy lists, potentially unblocking them.
4. Mark ready tasks in_progress and spawn new workers if slots available (respect worker limit N)
5. Output status and end your turn — you will be woken on the next completion

Task lifecycle: pending → (blocked until deps complete) → in_progress → completed

Repeat until all tasks completed → say "Swarm complete"

Visual Progress

Press ctrl+t to see task progress:

Tasks (2 done, 2 in progress, 3 open)
■ #3 Implement auth (Worker-1)
■ #4 Add routes (Worker-2)
□ #5 Integration tests > blocked by #3, #4

Error Handling

Stopping

• Workers self-terminate when no work remains
• Use /cancel-swarm to halt early

Example Usage

/plan-swarm docs/plans/add-user-auth.md              # Default: 3 workers
/plan-swarm docs/plans/refactor.md --workers 5       # Override: force 5 workers
/plan-swarm docs/plans/docs.md --model haiku         # Cheaper workers