swarm-work

name	swarm-work
description	Use when an implementation plan with tasks, dependencies, and acceptance criteria exists and needs to be executed — dispatches parallel worker agents in worktree isolation, tests after each batch, retries failures once.
argument-hint	[path to plan file]

Swarm Work

Dispatches parallel worker agents in dependency order with worktree isolation. Tests gate every batch.

Batch Execution Flow

┌────────────────────┐
│  Parse plan        │
│  Build dep graph   │
└─────────┬──────────┘
          ▼
┌────────────────────┐
│  Find ready tasks  │◄─────────────────┐
│  (no unmet deps)   │                  │
└─────────┬──────────┘                  │
          ▼                             │
┌────────────────────┐                  │
│  Dispatch batch    │                  │
│  (≤5 workers,      │                  │
│   worktree each)   │                  │
└─────────┬──────────┘                  │
          ▼                             │
┌────────────────────┐  ┌────────────┐  │
│  Worker failed?    ├─►│ Retry once │  │
└─────────┬──────────┘  │ w/ err ctx │  │
          │ all ok      └─────┬──────┘  │
          ▼                   ▼ fail    │
┌────────────────────┐  ┌────────────┐  │
│  Merge worktrees   │  │ STOP       │  │
│  (--no-ff each)    │  └────────────┘  │
└─────────┬──────────┘                  │
          │ conflict → STOP             │
          ▼                             │
┌────────────────────┐                  │
│  Run tests         │                  │
└─────────┬──────────┘                  │
          ▼                             │
┌────────────────────┐  ┌────────────┐  │
│  Tests pass?       ├─►│ Fix agent  │  │
└─────────┬──────────┘  └─────┬──────┘  │
          │ yes               ▼ fail    │
          ▼              ┌────────────┐  │
┌────────────────────┐   │ STOP       │  │
│  Mark batch done   │   └────────────┘  │
│  More? ────────────┼───────────────────┘
└─────────┬──────────┘
          ▼ all done
┌────────────────────┐
│  Final report      │
└────────────────────┘

Process

1. Parse Plan

Read from $ARGUMENTS, or find the most recent *.md in docs/plans/. Parse every ## Task N: section, extracting: description + steps, file paths, dependencies (**Depends on:**), and acceptance criteria. Build a dep graph. A task is ready when all deps are complete.

2. Execute in Batches

Collect ready tasks (max 5 per batch). Read ${CLAUDE_SKILL_DIR}/../../prompts/worker-agent.md once.

Dispatch ALL batch agents in ONE message (parallel). Each Agent call:

• subagent_type: "general-purpose"
• isolation: "worktree"
• mode: "bypassPermissions"
• prompt: worker template with placeholders filled:
  • {{TASK_TEXT}} — task description + steps
  • {{ACCEPTANCE_CRITERIA}} — checkbox list
  • {{PROJECT_CONTEXT}} — plan Goal / Architecture / Tech Stack
  • {{WORKING_DIR}} — project root

After all agents return:

1. Failed worker? Retry ONCE with error output as context. Second failure → STOP.
2. Merge worktree changes (see 2.5 below).
3. Run tests (see below). Fail → dispatch fix agent. Fix fails too → STOP.
4. Pass → mark batch done, update dep graph, loop.

2.5 Merge Worktree Changes

After each batch completes (all workers succeeded or retried) and BEFORE running tests:

1. Collect worktree branch names from each completed worker's result (returned by EnterWorktree).
2. For each branch, sequentially in the main worktree:

   git merge <worktree-branch> --no-ff -m "feat: <task name>"
   

3. Merge conflict → STOP. Report which branches conflict and which files. Do not attempt auto-resolution.
4. After all branches merged successfully → proceed to tests.

3. Detecting Test Command

Check in order, use first match:

Indicator	Command
package.json "test" script	npm test
Makefile test target	make test
Cargo.toml	cargo test
go.mod	go test ./...
Package.swift	swift test
pytest.ini / pyproject.toml	pytest

None found → skip test gate, warn user.

4. Report

## Swarm Work Complete
- **Tasks:** N/N completed
- **Files changed:** (list)
- **Tests:** all passing / N failures
- **Issues:** (concerns from workers, or "none")

Error Handling

• Worker fails — retry once with error context. Second failure → stop.
• Tests fail after fix agent — stop and report. Never force through red.
• Circular dependency — stop, report the cycle.