Swarm Sprint

Parallel multi-agent coding sprints using git worktree isolation. Use when running 2+ coding tasks on a repository that touch different parts of the codebase...

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

Role	Behavior
coder	Implements task. No unrelated refactoring. Runs tsc when done.
reviewer	Reviews diff skeptically. Flags bugs, type errors, missing error handling.
tester	Writes tests following existing patterns.

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