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:

bash

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#

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)#

bash

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

3. Create worktrees#

bash

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#

bash

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

6. Merge passing work#

bash

git merge swarm/<branch-name>

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

7. Cleanup (always, no exceptions)#

bash

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

Deletes all worktrees and branches. Always run this.

Agent Roles#

RoleBehaviorcoderImplements task. No unrelated refactoring. Runs tsc when done.reviewerReviews diff skeptically. Flags bugs, type errors, missing error handling.testerWrites 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#

bash

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