Parallel Swarm

Native Claude Code primitives do the heavy lifting; we provide the content (briefs, state files, handoff format).

Topology

COORDINATOR SESSION (foreground, you)
        │
        ├── claude --bg -w feat-001 --agent feature-stream    [streamId 1]
        ├── claude --bg -w feat-002 --agent feature-stream    [streamId 2]
        ├── claude --bg -w feat-003 --agent feature-stream    [streamId 3]
        ├── claude --bg -w feat-004 --agent feature-stream    [streamId 4]
        └── claude --bg -w feat-005 --agent feature-stream    [streamId 5]

Each --bg is a native daemon-supervised background session. Each -w feat-<N> creates a native git worktree at .claude/worktrees/feat-<N>/. Coordinator monitors via claude agents --json.

State files

Everything lives under .swarms/:

.swarms/
├── coordinator/
│   ├── plan.md                # Overall plan
│   ├── fleet.json             # {streamId: {sessionId, worktree, status, branch, taskIds}}
│   └── decisions.log          # Append-only
└── streams/
    └── <stream-id>/
        ├── brief.md           # Loaded into the background session via --append-system-prompt-file
        ├── task.json          # ccg-workflow schema
        ├── analysis.md        # ccpm-style: scope, files-owned, files-shared-with-owner
        ├── progress.md        # Updated by stream
        ├── context.jsonl      # Spec refs auto-injected into subagents
        └── handoff-<ts>.yaml  # NEXUS v1.0

Process

1. Plan (coordinator)

• Read tasks/TASKS.md. Identify independent streams (tasks with parallel: yes and no cross-deps).
• Group tasks into 5-10 streams. Each stream owns a coherent feature area.
• For each stream, write analysis.md:
  • Scope (1 paragraph)
  • Files owned (this stream is the only writer)
  • Files shared (one designated owner per file — see CCPM)
  • Acceptance commands (machine-verifiable)
• Write brief.md for each stream (this becomes the system-prompt extension for the background session).

2. Dispatch (coordinator)

• For each stream:

  sid=$(claude --bg -w feat-<N> \
       --agent feature-stream \
       --append-system-prompt-file .swarms/streams/<N>/brief.md \
       --max-turns 200 \
       --max-budget-usd 5 \
       --output-format stream-json \
       -p "Begin stream <N>. Read .swarms/streams/<N>/brief.md and execute.")
  echo "Spawned stream <N>: $sid"

• Update .swarms/coordinator/fleet.json with each session ID.

3. Monitor (coordinator, interactive)

• Use claude agents (TUI) or claude agents --json (scriptable).
• Watch for handoff files appearing in .swarms/streams/<N>/.
• If a stream hits QA-FAIL 3x, mark it for escalation; consider re-dispatching with refined brief.

4. Merge (coordinator)

• When a stream reports QA-PASS and writes its final handoff:
  • Coordinator: use pr-body to compose all applicable evidence and open from the stream's branch with gh pr create --body-file <complete-body-file>; read back the published body.
  • Wait for CI (claude-review + claude-security + ci + e2e-preview)
  • Squash-merge once green
  • Delete the worktree: git worktree remove .claude/worktrees/feat-<N>

5. Conflict resolution (coordinator)

• Streams should not collide because each owns its file set.
• If two streams need to write to the same file: only the designated owner writes; other streams git pull --rebase after the owner commits.
• If conflicts arise anyway: coordinator merges manually with the human in the loop (do not auto-resolve code conflicts).

Hard rules

• One implementer per file at a time. Worktree isolation isn't enough — if two streams need file X, designate an owner.
• tasks/TASKS.md is coordinator-owned. Feature-streams report task completion via their NEXUS handoff; only the coordinator marks [x] / [!] / [s] in the live tasks/TASKS.md. This prevents merge conflicts when multiple streams finish tasks concurrently.
• No nested swarms. A feature stream never spawns its own swarm. Spawn subagents in-stream, not streams-in-streams.
• Budget per stream. --max-budget-usd is mandatory. Default 5 USD per stream.
• Resumable. Streams write WIP checkpoints continuously (per wip-checkpoint skill). If a stream session crashes, claude respawn <id> brings it back.
• Coordinator never edits code. It only orchestrates, monitors, merges. Code edits happen inside the streams.

Commands

• /swarm-plan <N> — plan N independent streams from the backlog
• /swarm-dispatch — spawn the planned streams as --bg sessions
• /swarm-status — pretty-print claude agents --json + fleet.json
• /swarm-merge — for each PASS stream, open PR and merge
• /swarm-stop <stream> — stop one stream cleanly
• /swarm-respawn <stream> — restart a crashed stream

References

• Native Claude Code v2.1.144+ CLI (--bg, -w, agents, attach/logs/stop/respawn, --teammate-mode)
• automazeio/ccpm (stream-analysis schema, designated owner for shared files)
• ccg-workflow/templates (task.json schema, hooks)
• obra/superpowers/skills/using-git-worktrees (native-first principle)
• obra/superpowers/skills/dispatching-parallel-agents (when to fan out, when not to)
• msitarzewski/agency-agents (NEXUS handoff format)