Swarm — Parallel Coding Sprints

Parallel multi-agent coding sprints using git worktree isolation.

When to Use

• 2+ tasks touching different parts of the codebase → use swarm
• 1 task → do it directly, no swarm needed
• 2+ tasks ALL touching schema/auth → serialize them (swarm handles this automatically)

Trigger phrases: "Run a swarm sprint", "Parallel sprint on [repo]", "Use swarm for these tasks"

The Golden Rule — Always Plan First

Before spawning any agents, run the conflict analyzer:

node <skill-dir>/scripts/swarm.js --repo <repo_path> --tasks tasks.json --plan-only

Read the output:

• ✓ No conflicts → all tasks run in parallel
• ⚠ HIGH conflict → affected tasks auto-serialized into separate groups
• LOW conflict → runs parallel, watch the merge

Never skip this step. Two agents modifying the same file = merge conflict = wasted work.

Workflow

1. Write tasks.json

[
  {
    "id": "short-unique-id",
    "description": "Exactly what to build — be specific",
    "role": "coder",
    "successCriteria": ["Specific outcome", "TypeScript compiles clean"]
  }
]

2. Run conflict analysis (mandatory)

node <skill-dir>/scripts/swarm.js --repo <repo_path> --tasks tasks.json --plan-only

3. Create worktrees

node <skill-dir>/scripts/swarm.js --repo <repo_path> --tasks tasks.json

Creates isolated git worktree + branch per task. Writes swarm-packages.json.

4. Spawn subagents

Read swarm-packages.json. For each package, spawn a subagent with:

• Working directory = worktreePath
• Task prompt = instructions field
• Instruction to stay inside that directory only
• Instruction to git add -A && git commit before reporting back

5. Review each agent's output

git diff main..swarm/<branch-name>

6. Merge passing work

git merge swarm/<branch-name>

Merge one at a time. Verify TypeScript clean after each.

7. Cleanup (always, no exceptions)

node <skill-dir>/scripts/swarm.js --repo <repo_path> --cleanup swarm-packages.json

Deletes all worktrees and branches. Always run this.

Agent Roles

High-Conflict Areas (Auto-Serialized)

• schema.prisma, migration SQL
• Auth/session middleware
• Main router or index registration
• Shared config/env files

Rules

• Planning step is mandatory
• Worktrees always deleted after sprint
• Never push from a worktree — coordinator handles git
• Reviewer role should use cheaper model (Haiku); coder uses Sonnet
• Max 5 parallel agents
• Sprint log written to memory/swarm-log.md

Dry Run

node <skill-dir>/scripts/swarm.js --repo <repo_path> --tasks tasks.json --dry-run