swarm-planner

Swarm-Ready Planner

Create implementation plans with explicit task dependencies optimized for parallel agent execution in Claude Code. Plans produced by this skill are executed by the swarm-executor skill.

Announce at start: "I'm using the swarm-skills:swarm-planner skill to create a dependency-aware parallel implementation plan."

CRITICAL CONSTRAINTS

You MUST NOT call `EnterPlanMode` or `ExitPlanMode` during this skill. This skill operates in normal mode and manages its own flow. Plan mode restricts Write/Edit tools and has no clean exit.

Core Principles

1. Explore Codebase: Investigate architecture, patterns, existing implementations, dependencies, and frameworks in use
2. Fresh Documentation First: Use WebSearch for ANY external library, framework, or API before planning tasks
3. Ask Questions: Clarify ambiguities — seek clarification on scope, constraints, or priorities at any point
4. Explicit Dependencies: Every task declares what it depends on, enabling maximum parallelization
5. Atomic Tasks: Each task is independently executable by a single agent in an isolated worktree
6. File Isolation: Tasks in the same wave MUST NOT touch the same files — this is a hard requirement for worktree-based parallel execution
7. Review Before Yield: A subagent reviews the plan for gaps before finalizing

Process

1. Research

Codebase investigation:

• Architecture, patterns, existing implementations
• Dependencies and frameworks in use
• File ownership boundaries (which files belong to which subsystem)

Use the Explore subagent type for broad codebase exploration, or Glob/Grep for targeted searches.

1a. Optional: Stop for Clarification

• If the architecture is unclear or missing, STOP and ask the user for input before moving on. Always offer recommendations with your questions.
• If architecture is clear, skip to step 2.

2. Documentation

Documentation retrieval (REQUIRED for external dependencies):

Use WebSearch to research current docs for any libraries/frameworks/APIs that are or will be used in the project. This ensures version-accurate APIs, correct parameters, and current best practices.

3. STOP and Request User Input

When anything is unclear or could reasonably be done multiple ways:

• Stop and ask clarifying questions immediately
• Do not make assumptions about scope, constraints, or priorities
• Questions should reduce risk and eliminate ambiguity
• Always offer recommendations with your questions
• One question per message — do not overwhelm

4. Create Dependency-Aware Plan

Structure the plan with explicit task dependencies. Critical rules:

Dependency Rules:

• Every task MUST have a depends_on field (empty [] for root tasks)
• Tasks with empty/satisfied dependencies can run in parallel
• Tasks in the same wave MUST operate on different files

File Isolation Rules (CRITICAL for worktree execution):

• Map every task to its exact file paths
• If two tasks need to modify the same file, one MUST depend on the other
• Shared files = forced serialization. Design tasks to minimize shared files.
• When unavoidable, document WHY the dependency exists
• Exception: The plan file itself is always shared (subagents update their own task status). This is expected and handled by the executor's Tier 1 conflict resolution.

5. Save Plan

Save to docs/plans/YYYY-MM-DD-<topic>-swarm.md in the project root.

Create the docs/plans/ directory if it doesn't exist.

6. Save Task Persistence File

Save to docs/plans/YYYY-MM-DD-<topic>-swarm.md.tasks.json alongside the plan:

{
  "planPath": "docs/plans/YYYY-MM-DD-<topic>-swarm.md",
  "tasks": [
    {"id": "T1", "subject": "Task title", "status": "pending", "depends_on": []},
    {"id": "T2", "subject": "Task title", "status": "pending", "depends_on": ["T1"]}
  ],
  "waves": [
    {"wave": 1, "tasks": ["T1", "T3"]},
    {"wave": 2, "tasks": ["T2", "T4"]}
  ],
  "lastUpdated": "<ISO timestamp>"
}

7. Create Native Tasks

REQUIRED FIRST: Load the task tools before using them:

ToolSearch: "select:TaskCreate"
ToolSearch: "select:TaskUpdate"
ToolSearch: "select:TaskList"

For each task in the plan, create a native task. Derive a plan slug from the filename (e.g., 2026-02-25-auth-system-swarm.md → auth-system-swarm) and use it as a subject prefix to scope tasks to this plan. Track the mapping between plan IDs (T1, T2...) and the native task IDs returned by TaskCreate — you need this mapping for setting dependencies.

TaskCreate:
  subject: "[auth-system-swarm] T1: [Task Name]"
  description: |
    [Full task content — files, description, validation, acceptance criteria]
  activeForm: "Implementing [Task Name]"
# Returns a native task ID — record it: T1 → native-id-1

After all tasks created, set dependency relationships using the native task IDs (not plan IDs):

TaskUpdate:
  taskId: [native-id-for-dependent-task]
  addBlockedBy: [native-ids-for-prerequisite-tasks]

Call TaskList to verify the dependency structure looks correct.

8. Subagent Review

Spawn a subagent to review the plan:

Task(subagent_type="general-purpose", prompt="""
Review this implementation plan for:
1. Missing dependencies between tasks
2. File isolation violations — tasks in the same wave editing the same files
3. Ordering issues that would cause failures
4. Missing error handling or edge cases
5. Gaps, holes, gotchas

CRITICAL: Check that no two tasks in the same parallel wave touch the same files.
Tasks will run in isolated git worktrees — file conflicts between parallel tasks
will cause merge failures.

Provide specific, actionable feedback. Do not ask questions.

Plan location: [file path]
Context: [brief context about the task]
""")

If the subagent provides actionable feedback:

1. Revise the plan file
2. Regenerate the .tasks.json persistence file to match
3. Update native tasks: use TaskUpdate to modify descriptions/subjects for existing tasks. If tasks were added or removed, mark stale tasks as completed with a note "canceled — removed from plan" via TaskUpdate, and create new ones as needed.
4. Re-verify with TaskList before yielding

9. Yield to User

Present the completed plan and tell the user:

Plan saved to docs/plans/YYYY-MM-DD-<topic>-swarm.md

To execute: /swarm-skills:swarm-executor docs/plans/YYYY-MM-DD-<topic>-swarm.md
To execute a subset: /swarm-skills:swarm-executor docs/plans/YYYY-MM-DD-<topic>-swarm.md T1 T3 T5

Plan Template

# Swarm Plan: [Task Name]

> **For Claude:** REQUIRED SUB-SKILL: Use swarm-skills:swarm-executor to implement this plan.

**Generated**: [Date]
**Goal**: [One sentence describing what this builds]
**Architecture**: [2-3 sentences about approach]
**Tech Stack**: [Key technologies/libraries]

---

## Overview
[Summary of task and approach]

## Prerequisites
- [Tools, libraries, access needed]

## Dependency Graph

T1 ──┬── T3 ──┐ │ ├── T5 ── T6 ── T7 T2 ──┴── T4 ──┘

## Tasks

### T1: [Name]
- **depends_on**: []
- **files**: [exact file paths — create/modify/test]
- **description**: [what to do, with enough context for an agent with zero codebase knowledge]
- **acceptance_criteria**:
  - [Specific, testable criterion]
  - [Specific, testable criterion]
- **validation**: [exact commands to verify completion]
- **status**: pending
- **log**: []
- **files_edited**: []

### T2: [Name]
- **depends_on**: []
- **files**: [exact file paths]
- **description**: [what to do]
- **acceptance_criteria**:
  - [Criterion]
- **validation**: [how to verify]
- **status**: pending
- **log**: []
- **files_edited**: []

### T3: [Name]
- **depends_on**: [T1]
- **files**: [exact file paths]
- **description**: [what to do]
- **acceptance_criteria**:
  - [Criterion]
- **validation**: [how to verify]
- **status**: pending
- **log**: []
- **files_edited**: []

[... continue for all tasks ...]

## Parallel Execution Waves

| Wave | Tasks | Can Start When | Files Touched |
|------|-------|----------------|---------------|
| 1 | T1, T2 | Immediately | T1: src/a.py, T2: src/b.py |
| 2 | T3, T4 | Wave 1 complete | T3: src/c.py, T4: src/d.py |
| 3 | T5 | T3, T4 complete | src/e.py |

**File isolation verified**: No two tasks in the same wave touch the same files.

## Testing Strategy
- [How to test]
- [What to verify]
- [Full test suite command]

## Risks & Mitigations
- [What could go wrong + how to handle]

Important Reminders

• Every task MUST have explicit depends_on field
• Every task MUST list exact file paths
• Tasks in the same wave MUST NOT share files
• Root tasks (no dependencies) execute in parallel immediately
• Do NOT implement — only create the plan
• Always use WebSearch for external dependencies before finalizing tasks
• Always ask questions where ambiguity exists
• The plan must contain enough context for an agent with zero prior knowledge to implement each task