Swarm

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:

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

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)