Swarm Protocol v2

Turn complex projects into parallel agent swarms. One command to go from idea to merged PR.

Orchestrates specialized subagents across planning, implementation, and review phases with worktree isolation for conflict-free parallelization, progressive status tracking for real-time monitoring, and a 5-agent parallel review team that catches bugs, silent failures, type design issues, stale comments, and unnecessary complexity — all before you merge.

Why Swarm Protocol?

• One command — /swarm-protocol <name> creates docs, branches, worktree, and starts planning
• Specialized agents — Each role maps to the right subagent type (architect, explorer, reviewer, etc.)
• Maximum parallelism — Agents run concurrently with worktree isolation to prevent file conflicts
• 5-agent review team — Code reviewer, silent failure hunter, type analyzer, comment checker, code simplifier — all in parallel
• Real-time monitoring — swarm-status.json with progressive auto-updates for ScopeTUI integration
• Smart resumption — Pick up where you left off with --resume, retry single agents with --agent=N.M
• Plan conversion — Already have a plan? Convert it directly with --from-plan=<name>

Commands

/swarm-protocol (No Arguments)

Smart detection: Check branch (feature/<name>) → docs/projects/ → ~/.claude/plans/ → prompt user.

Detection priority:

1. Current branch feature/<name> → match project in docs/projects/<name>/
2. List recent projects by modified date with status from CHANGELOG.md
3. List plans from ~/.claude/plans/ available for conversion
4. Offer new project with random name suggestions

Project names: Random from Barcelona region pool (rubi, sitges, mura, tiana, etc.)

Plan conversion: Parse plan → auto-populate PROJECT_PLAN.md, IMPLEMENTATION_PLAN.md, AGENT_SWARM_SPEC.md → review before execution.

/swarm-protocol <project-name>

Initialize and execute a multi-agent development project.

Phase 0: Project Setup

1. Create docs/projects/<name>/ with: PROJECT_PLAN.md, IMPLEMENTATION_PLAN.md, AGENT_SWARM_SPEC.md, CODE_REVIEW.md, CHANGELOG.md
2. Create worktree: git worktree add ../<repo>-<name> -b feature/<name>
3. Supabase preview (if DB changes): supabase branches create <name>

swarm-status.json — Progressive Auto-Update System (MANDATORY)

CRITICAL: swarm-status.json MUST be created at Phase 0 and updated automatically at every action. The ScopeTUI Swarm Monitor (scopetui --swarm) depends on this file being accurate. Stale status = broken monitoring.

Location: docs/projects/<name>/swarm-status.json inside the worktree (not master).

Full schema + progressive update protocol: See references/swarm-status-schema.md.

The Anti-Lag Rule

Update BEFORE and AFTER every Agent dispatch — never batch updates.

BEFORE dispatching agent → set agent "running" + write file
AFTER agent returns      → set agent "completed"/"failed" + write file
BEFORE phase transition  → advance currentPhaseId + write file

Quick Update Helper

# Atomic status update via jq (define once, use throughout)
swarm_update() {
  local file="$1" agent_id="$2" new_status="$3" now
  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
  jq --arg aid "$agent_id" --arg st "$new_status" --arg now "$now" '
    (.phases[].agents[] | select(.id == $aid)) |= (
      .status = $st |
      if $st == "running" then .startedAt = $now
      elif $st == "completed" then .completedAt = $now
      else . end
    ) | .updatedAt = $now
  ' "$file" > "${file}.tmp" && mv "${file}.tmp" "$file"
}

# Usage: swarm_update docs/projects/<name>/swarm-status.json "2.1" "running"

Orchestrator Owns Status

The main session (orchestrator) writes all status updates. Subagents NEVER touch swarm-status.json. This prevents race conditions and ensures consistent state.

Minimum viable format (TUI validates only phases array):

{
  "project": "<name>",
  "branch": "feature/<name>",
  "currentPhaseId": "<active-phase-id>",
  "phases": [
    {
      "id": "1", "name": "Setup", "status": "completed",
      "agents": [{ "id": "1.1", "name": "Types", "status": "completed", "subagentType": "general-purpose" }]
    }
  ],
  "updatedAt": "<ISO 8601>"
}

Phase 1: Planning (Sequential — use feature-dev:code-architect)

Generate all planning documents before implementation. See references/templates.md for document templates.

Dispatch: Use Agent tool with subagent_type: "feature-dev:code-architect" for architecture design, and subagent_type: "feature-dev:code-explorer" for codebase analysis.

Planning sequence:

1. Explore — Dispatch feature-dev:code-explorer agent to analyze existing codebase patterns, trace execution paths, map dependencies
2. Architect — Dispatch feature-dev:code-architect agent to design implementation blueprint based on exploration results
3. PROJECT_PLAN.md → Goals, success criteria, dependencies, risks
4. IMPLEMENTATION_PLAN.md → Architecture, file changes, migrations, API endpoints
5. AGENT_SWARM_SPEC.md → Phase breakdown, agent definitions with subagent_type assignments, parallelization strategy

Phase 2-N: Execution

FULL EXECUTION, MAXIMUM PARALLELIZATION

Agent dispatch: Use the Agent tool for all agent invocations. See references/agent-dispatch.md for the centralized dispatch protocol mapping roles → subagent_types.

Worktree isolation: For parallel agents that touch overlapping directories, use isolation: "worktree" on the Agent tool call. This gives each agent an isolated repo copy, eliminating file conflicts and enabling more aggressive parallelization.

Parallelization rules:

• Agents within a phase run parallel when no file conflicts exist (or use worktree isolation)
• Phases with dependencies wait for blockers to complete
• Launch all independent agents in a single message with multiple Agent tool calls
• Use run_in_background: true for agents whose results aren't needed immediately

Progress display: See references/templates.md for colored box format, ANSI codes, and ASCII art variants.

Status symbols: ● (green/complete), ◐ (yellow/in-progress), ○ (dim gray/pending)

Milestone commits (after each phase):

git add -A
git commit -m "feat(<project>): complete phase N - <description>

- Agent N.1: <summary>
- Agent N.2: <summary>

Co-Authored-By: Claude Code <noreply@anthropic.com>"

Quality gates (invoke after relevant phases):

• After UI phases → invoke react-doctor skill if React project
• After implementation → invoke smart-test skill for intelligent test selection
• After test writing → invoke full-test-coverage skill to verify pyramid coverage

Phase Review & Repair: Review Team + Repair

Review Team: Dispatch a parallel team of specialized reviewers instead of a single review pass. This is the core improvement — each reviewer is a specialized subagent that catches different classes of issues.

In swarm-status.json, this is a single phase with id "review-repair" and name "Review Team & Repair", containing review agents + repair agent.

Review Team (Parallel — launch ALL in a single message)

Dispatch all 5 in parallel:

Agent(subagent_type="feature-dev:code-reviewer", prompt="Review all changes in <diff>...")
Agent(subagent_type="pr-review-toolkit:silent-failure-hunter", prompt="Analyze error handling in <diff>...")
Agent(subagent_type="pr-review-toolkit:type-design-analyzer", prompt="Review types introduced in <diff>...")
Agent(subagent_type="pr-review-toolkit:comment-analyzer", prompt="Check comment accuracy in <diff>...")
Agent(subagent_type="pr-review-toolkit:code-simplifier", prompt="Simplify recently modified code in <diff>...")

After all reviewers complete: Consolidate findings into CODE_REVIEW.md with issues categorized by severity (High/Medium/Low), source reviewer, and recommendations.

Repair (Sequential — after Review Team completes)

Repair steps:

1. High-severity issues: Fix all critical bugs, security vulnerabilities, and breaking issues
2. Medium-severity issues: Resolve performance problems, missing validation, incomplete error handling
3. Low-severity issues: Fix code style violations, naming inconsistencies, minor improvements
4. Recommendations (Immediate): Implement all "Before Merge" recommendations from CODE_REVIEW.md
5. Simplifications: Apply code-simplifier suggestions — reduce complexity while preserving functionality
6. Suggestions & nits: Apply code suggestions, improve readability, clean up dead code
7. Enhancements: Add small enhancements identified during review (better types, missing edge cases, improved UX)
8. Update CODE_REVIEW.md — mark all resolved issues with resolution details
9. Commit all repair changes

Repair rules:

• Work through issues by severity: High → Medium → Low → Recommendations → Simplifications → Nits → Enhancements
• Each fix must not introduce new issues
• Update the Resolution column in CODE_REVIEW.md for every addressed item
• If a fix requires significant refactoring, document the trade-off and proceed

Phase Verify: Final Verification

Validate that all repairs are correct and the project is ready for merge.

Verification steps:

1. npm run test && npm run typecheck && npm run lint
2. Dispatch feature-dev:code-reviewer on repair diff to confirm no regressions introduced
3. Verify all CODE_REVIEW.md issues marked as resolved
4. Update project CLAUDE.md
5. If Supabase preview used: Execute database deployment workflow (see below)
6. Final commit with verification summary

Options

Supabase Database Deployment

If project uses Supabase preview branches, see references/supabase-deployment.md for the full deployment workflow including migration validation loops, advisor checks, and production deployment steps.

Quick ref: supabase db push --linked → fix errors → run advisors → consolidate → deploy to production.

Agent Dispatch Protocol

CRITICAL: Always use the correct subagent_type when dispatching agents. See references/agent-dispatch.md for the complete mapping.

Quick reference:

Dispatch rules:

1. Single message, multiple agents: Launch all independent agents in ONE message with multiple Agent tool calls
2. Background when possible: Use run_in_background: true for agents whose output isn't needed to proceed
3. Worktree isolation: Use isolation: "worktree" when parallel agents may touch overlapping files
4. Resume capability: Store agent IDs to resume failed/interrupted agents via the resume parameter

Agent Design Principles

Parallelization: Safe when different files/dirs, independent features, tests for completed work. Sequential for dependency chains (Schema→Types→API), base→composite components, core→integration. Use isolation: "worktree" to unlock parallelism when agents share directories.

Agent scope: Single responsibility, own specific files (no overlap), define completion criteria, include validation.

Communication: IMPLEMENTATION_PLAN.md + type definitions (shared context), file system (deliverables), CHANGELOG.md (progress).

Agent Failure Protocol

Recovery: /swarm-protocol --resume (auto-resume) | /swarm-protocol-protocol --agent=2.3 --retry | /swarm-protocol-protocol --skip-agent=2.3

Project Archival

After merge: move docs to docs/archive/, remove worktree, delete feature branch, clean Supabase preview if used.

mv docs/projects/<name> docs/archive/<name>
git worktree remove ../<repo>-<name>
git branch -d feature/<name>
supabase branches delete <name>  # if applicable

Best Practices

Plan thoroughly → Use specialized subagent types → Keep agents focused → Define interfaces first → Launch parallel agents in single messages → Commit per phase → Review with full team → Repair all issues → Verify before merge → Document decisions in CODE_REVIEW.md

Reference Files