Swarm Protocol

Swarm Protocol

Multi-agent orchestration framework for complex software development projects. Coordinates parallel workstreams, manages project documentation, and automates milestone commits.

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>

Phase 1: Planning (Sequential)

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

Planning sequence:

1. PROJECT_PLAN.md → Goals, success criteria, dependencies, risks
2. IMPLEMENTATION_PLAN.md → Architecture, file changes, migrations, API endpoints
3. AGENT_SWARM_SPEC.md → Phase breakdown, agent definitions, parallelization strategy

Phase 2-N: Execution

Parallelization rules:

• Agents within a phase run parallel when no file conflicts exist
• Phases with dependencies wait for blockers to complete
• Use Task tool for parallel agent invocations

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 <[email protected]>"

Phase Final: Review

Generate CODE_REVIEW.md with quality metrics, issues found, optimizations applied.

Final steps:

1. npm run test && npm run typecheck && npm run lint
2. Update project CLAUDE.md
3. If Supabase preview used: Execute database deployment workflow (see below)
4. Final commit with review 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 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.

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 → Keep agents focused → Define interfaces first → Commit per phase → Validate continuously → Document decisions in CODE_REVIEW.md

Reference Files