swarm

name	swarm
description	Execute implementation plans with parallel worker agents in git worktrees. Spawns agents, monitors progress, coordinates merges. Use after /skill:plan completes.

Swarm Skill

Unified execution engine for the implementation phase. Loads validated plans from /skill:plan, spawns parallel worker agents in git worktrees, monitors progress, and coordinates merges. Second step in the three-prong workflow: Plan → Implement → Validate.

Workflow

/skill:swarm {feature-name}
    ↓
Phase 1: Load & validate plan artifacts
    ↓
Phase 2: Initialize feature branch
    ↓
Phase 3: Execute batches (spawn → monitor → merge)
    ↓
Phase 4: Create PR → Complete

Usage

/skill:swarm <feature-name>             # Execute implementation plan
/skill:swarm <feature-name> --status    # Check orchestration status only
/skill:swarm <feature-name> --resume    # Resume interrupted orchestration
/skill:swarm <feature-name> --dry-run   # Preview execution without spawning
/skill:swarm <feature-name> --max-parallel 3  # Limit concurrent agents

Prerequisites

• Planning complete: /skill:plan {feature-name} must have run
• Plan file: docs/plans/{feature-name}.md
• Task files: docs/tasks/{feature-name}-phase-*.md
• Spec file: docs/specs/{feature-name}-spec.md
• Worktrunk CLI: Configured for worktree management
• Clean working directory: No uncommitted changes

Missing Artifacts Check

If planning artifacts are missing:

❌ Planning artifacts not found!

Missing:
- docs/plans/{feature-name}.md
- docs/tasks/{feature-name}-*.md

Run the planning phase first:
  /skill:plan {feature-name}

Phase 1: Load & Validate Plan

1. Read plan from docs/plans/{feature-name}.md
2. Verify all referenced task files exist in docs/tasks/
3. For each phase, extract these fields (used to construct agent_spawn calls):
   • Branch → agent_spawn.branch
   • Tasks → agent_spawn.task_file
   • Agent → agent_spawn.agent (default: worker)
   • Base → agent_spawn.base (always the feature branch)
4. Extract execution batches and dependency order
5. Check plan status is not "completed"

Phase 2: Initialize Feature Branch Worktree

Tool: orchestration_init
  feature_branch: feat/{feature-name}
  base: dev

Creates a worktree for the feature branch at .worktrees/feat-{feature-name}/. The main repository stays on dev, enabling parallel work in other terminal sessions.

Returns:

• worktree_path: Path to the feature worktree (e.g., .worktrees/feat-user-avatar/)
• feature_branch: The branch name

The orchestrator should note the worktree_path — all subsequent operations happen within worktrees, not the main repo.

Phase 3: Execute Batches

Before starting execution, read the Orchestration Guide.

For each batch defined in the plan:

Determine Current State

Check existing worktrees and agent status to determine where we are:

State	Condition	Action
Fresh start	No phase worktrees	Start from Batch 1
In progress	Agents running	Resume monitoring
Batch complete	All agents done	Proceed to merge
Blocked/failed	Agent error	Pause for user input

Execute Batch Loop

1. Spawn agents for each phase in the batch. Read the Agent and Tasks fields from the plan file to populate the call:

   Tool: agent_spawn
     branch: feat/{feature}-phase-{n}            ← from plan: Phase.Branch
     task_file: docs/tasks/{feature}-phase-{n}.md ← from plan: Phase.Tasks
     agent: researcher | worker | reviewer        ← from plan: Phase.Agent (default: worker)
     base: feat/{feature}                         ← CRITICAL: always the feature branch, not dev
   

   The task_file gives the agent structured acceptance criteria, file lists, and instructions. Always pass it in orchestrated flows.

2. Monitor — poll agent_status every 30s until batch completes:

   Batch 2 of 3:
     feat/{feature}-phase-2a  🤖 60% - Implementing API endpoints
     feat/{feature}-phase-2b  🤖 45% - Building UI components
   

3. Handle events — completion (✅), failure (❌, offer retry/skip), timeout (30min alert)

4. Pre-merge validation — lint, test, build in each completed worktree

5. Merge to feature branch in dependency order:

   Tool: worktree_merge
     branch: feat/{feature}-phase-{n}
     target: feat/{feature}
   

6. Update plan status with merge commit hash and timestamp

7. Next batch — wait for all merges before spawning next batch

Feature Branch Strategy (Worktree-Based)

All work happens in worktrees inside .worktrees/. The main repo stays on dev:

Directory Structure:

/repo/                                    # Main repo — ALWAYS on dev
  .worktrees/                             # Gitignored worktree directory
    feat-user-avatar/                     # Feature branch worktree (orchestrator)
    feat-user-avatar-phase-1/             # Phase 1 worktree (worker agent)
    feat-user-avatar-phase-2a/            # Phase 2a worktree (worker agent)
    feat-user-avatar-phase-2b/            # Phase 2b worktree (worker agent)

Branch Flow:

dev ──────────────────────────────────────────► dev (unchanged until PR)
  │                                                ▲
  └─► feat/{feature} ─────────────────────────────┘ (single PR)
        ├─► phase-0 (researcher) ─► merge ──┐
        ├─► phase-1 (worker) ─────► merge ──┤
        ├─► phase-2a (worker) ────► merge ──┤
        ├─► phase-2b (worker) ────► merge ──┤
        ├─► phase-3 (worker) ─────► merge ──┤
        └─► review (reviewer) ────► merge ──┘

Benefits:

• New terminal sessions in /repo start on dev — can work on other features
• Multiple swarms can run in parallel (different feature worktrees)
• Clean separation between orchestrator and main codebase

Phase 4: Completion

Generate Summary

✅ Orchestration Complete: {feature}

| Phase | Files | Tests | Duration |
|-------|-------|-------|----------|
| 1     | 3     | 12    | 15m      |
| 2a    | 5     | 18    | 22m      |
| 2b    | 4     | 15    | 18m      |
| 3     | 2     | 8     | 12m      |

All phases merged to feat/{feature}.

Create Pull Request

gh pr create --base dev --head feat/{feature} \
  --title "feat({feature}): {description}"

Next Steps

Orchestration complete! Next:
  /skill:validate-plan {feature-name}    # Verify spec compliance

Context Management

The swarm-context extension automatically:

• Loads plan summary from planning phase
• Creates clean session branch for orchestration context
• Saves state to .swarm-{feature}.json for resume

Session Tree

main
├── planning-{feature}       (Planning conversation)
└── orchestration-{feature}  (Clean execution context)

Resume Mode

/skill:swarm {feature} --resume skips spawning and goes directly to monitoring:

• Checks existing worktrees and agent states
• Resumes monitoring from current batch
• Useful after disconnect or crash

Dry Run Mode

/skill:swarm {feature} --dry-run shows execution plan without spawning:

[DRY RUN] Would execute:

Batch 1 (1 agent):
  → feat/{feature}-phase-1 with docs/tasks/{feature}-phase-1.md

Batch 2 (2 agents, parallel):
  → feat/{feature}-phase-2a with docs/tasks/{feature}-phase-2a.md
  → feat/{feature}-phase-2b with docs/tasks/{feature}-phase-2b.md

Merge order: phase-1 → phase-2a → phase-2b → phase-3

Error Handling

Error	Resolution
Plan not found	"Run /skill:plan {feature} first"
Task file missing	"Regenerate tasks with /skill:plan {feature}"
Agent failure	Offer: retry, skip, terminate
Merge conflict	Pause, guide manual resolution
Timeout (30min)	Alert, offer: extend, check, terminate
Dirty working dir	Auto-commit before orchestration

Complete Development Lifecycle

/skill:plan feature-name       # Plan: PRD → Spec → Tasks
/skill:swarm feature-name      # Implement: Spawn → Monitor → Merge → PR
/skill:validate-plan feature-name   # Validate: Tests + spec compliance

Related Skills

• /skill:plan — Planning workflow that produces execution artifacts (prerequisite)
• /skill:validate-plan — Spec compliance verification (next step)
• /skill:feature — Single-phase implementation (simpler alternative)