Imported from cj-vana/claude-swarm (skill/SKILL.md). Install upstream with npx skills add cj-vana/claude-swarm --skill skill. Copyright stays with the author.

Claude Swarm Skill

This skill enables autonomous, multi-hour coding sessions using the claude-swarm MCP server with protocol-based behavioral governance.

Overview

The orchestrator pattern separates concerns:

• Orchestrator (you): Plans work, monitors progress, handles decisions
• Workers: Focused Claude Code sessions that implement individual features
• Protocols: Behavioral constraints that govern what workers can/cannot do

Complete Workflow (Step-by-Step)

Follow these phases in order for every swarm session:

Phase 0: Repository Readiness Check

Before starting any feature work, ensure the repository is ready:

1. ENSURE GITIGNORE (CRITICAL - always do this first):
   Check if .gitignore contains swarm state files. If not, add them:

   Required entries:
   .claude/
   claude-progress.txt
   init.sh

   Run this to add missing entries:
   grep -q "^\.claude/" .gitignore 2>/dev/null || echo ".claude/" >> .gitignore
   grep -q "^claude-progress.txt" .gitignore 2>/dev/null || echo "claude-progress.txt" >> .gitignore
   grep -q "^init.sh" .gitignore 2>/dev/null || echo "init.sh" >> .gitignore

   **Why:** Swarm state files must NEVER be committed. They contain session-specific
   data, absolute paths, worker logs, and will cause merge conflicts.

2. ANALYZE the repository:
   → setup_analyze(projectDir)

3. IF freshness score >= 50 (missing configurations):
   → setup_init(projectDir)
   → Monitor: setup_status(projectDir)
   → Wait for all setup workers to complete

4. IF freshness score < 50:
   → Proceed to Phase 1 (repo already configured)

Why: Ensures repos have CLAUDE.md, CI, and other essentials before feature work begins.

Phase 0.5: Session Recovery Check

Before starting a new session, check if a previous session crashed:

1. CHECK for crashed session:
   → resume_session(projectDir)
   - If crash detected: auto-recovers from checkpoint
   - If paused: resumes with pending features listed
   - If no session: proceed to Phase 1

2. IF recovered:
   → orchestrator_status(projectDir)
   → Decide: continue existing session or orchestrator_reset to start fresh

Phase 1: Session Setup

1. DECOMPOSE the task into 15-60 minute features
   - Each feature should be independently testable
   - Order by dependency (foundations first)

2. INITIALIZE the session:
   → orchestrator_init(projectDir, taskDescription, existingFeatures)

3. ANALYZE COMPLEXITY for all features (mandatory):
   → FOR EACH feature:
      get_feature_complexity(featureId)
   - Records complexity score and recommendation for each feature
   - Features with score >= 60 are flagged for competitive planning
   - Use these results to inform Phase 3 execution strategy

4. PLAN MODE DECISION:
   Ask user: "Enable worker plan mode? Workers will analyze the codebase
   and produce a plan before implementing. Orchestrator auto-approves plans."
   - If yes: → configure_plan_mode(projectDir, { enabled: true, complexityThreshold: 30 })
   - If no: skip (workers implement directly, current behavior)

5. EXECUTION MODE DECISION:
   Ask user: "Enable Ralph Loop for long-running autonomy? Workers get fresh
   context each iteration and persist progress to files. Best for hours/days-long sessions."
   - If yes: → configure_ralph_loop(projectDir, { enabled: true })
   - If no: Workers use standard single-run execution

6. OPTIONAL - Set up behavioral constraints:
   → protocol_register(protocol JSON)
   → protocol_activate(protocolId)

7. OPTIONAL - Configure pre-completion verification:
   → configure_verification(commands: ["npm test", "tsc --noEmit"])

8. OPTIONAL - Set feature dependencies:
   → set_dependencies(featureId, dependsOn: ["feature-1", "feature-2"])

Phase 2: Pre-Work Preparation (Per Feature)

Before starting each feature, prepare as needed based on Phase 1 complexity analysis:

1. IF feature complexity >= 60 (from Phase 1 analysis):
   → start_competitive_planning(featureId)
   → sleep 300  (wait 5 minutes for planners)

   REVIEW PLANS (recommended for critical features):
   → check_worker(plannerSessionA)  # View Planner A's output
   → check_worker(plannerSessionB)  # View Planner B's output

   EVALUATE AND SELECT:
   → evaluate_plans(featureId)  # Automatic selection based on scoring
   OR for manual override:
   → evaluate_plans(featureId, manualSelection: "A", selectionReason: "...")

2. OPTIONAL - Enrich with context:
   Option A: Automatic discovery
   → enrich_feature(featureId)  # Auto-finds relevant docs/code

   Option B: Manual/precise context
   → set_feature_context(featureId, documentation: [...])

3. OPTIONAL - Validate against protocols:
   → validate_feature_protocols(featureId)

When to enrich: Use for complex features touching unfamiliar code areas. Skip for simple, isolated changes.

Phase 3: Execution

Choose your execution strategy:

OPTION A: Manual Orchestration (Default)

FOR INDEPENDENT FEATURES (can run simultaneously):
   → validate_workers(featureIds)  # Check for conflicts
   → start_parallel_workers(featureIds)  # Up to 10 workers

FOR DEPENDENT/SEQUENTIAL FEATURES:
   → start_worker(featureId)

FOR LONG-RUNNING FEATURES (Ralph Loop enabled):
   → start_ralph_loop(featureId)  # Fresh context per iteration

---

OPTION B: Hands-Free Orchestration

For fully autonomous execution until completion:
   → auto_orchestrate(projectDir, strategy: "adaptive", maxConcurrent: 5)

Strategies:
- breadth-first: Parallelize independent features first
- depth-first: Focus on unblocking dependent features
- adaptive: Let the system decide based on dependencies

When plan mode is enabled, auto_orchestrate automatically:
- Runs plan phase for features with complexity >= threshold
- Auto-approves plans that score >= 50
- Re-plans up to 2x if rejected, then falls back to direct implementation

When Ralph Loop is enabled, auto_orchestrate automatically:
- Uses fresh-context iteration for each worker
- Tracks progress via filesystem (no context rot)
- Creates periodic checkpoints for crash recovery

Note: auto_orchestrate handles Phases 3-5 automatically, returning when all features complete.

Phase 4: Monitoring Loop

IMPORTANT: Workers take 5-10 minutes. Do NOT check immediately.

1. WAIT before first check:
   → sleep 180  (3 minutes)

2. CHECK status (lightweight):
   → check_worker(featureId, heartbeat: true)
   OR
   → check_all_workers(heartbeat: true)

3. IF worker seems stuck (low confidence):
   → get_worker_confidence(featureId)
   → send_worker_message(featureId, "guidance here")

4. IF still running:
   → sleep 120  (wait 2 more minutes)
   → Repeat from step 2

5. IF completed:
   → Proceed to Phase 5

Phase 5: Completion (Per Feature)

1. VERIFY the work:
   → run_verification(command: "npm test")

2. MARK completion:
   → mark_complete(featureId, success: true/false)
   - If failed: auto-retry enabled (3 attempts by default)
   - If retries exhausted: retry_feature(featureId) to reset

3. CHECKPOINT (on success):
   → commit_progress("feat: description of work")

4. REPEAT Phases 2-5 for next pending feature

Phase 6: Post-Completion Reviews

After ALL features complete, reviews run automatically:

1. MONITOR review progress:
   → check_reviews()

2. GET findings when complete:
   → get_review_results()

3. OPTIONAL - Create follow-up features from issues:
   → implement_review_suggestions(autoSelect: true, minSeverity: "warning")

4. IF new features added:
   → Repeat from Phase 2

Recovery Points

LOST CONTEXT (after compaction)?
   → orchestrator_status(projectDir)  # Restores full state

NEED TO PAUSE?
   → pause_session()   # Stops all workers
   → resume_session()  # Continue later

NEED TO SHUT DOWN (laptop closing, end of day)?
   → shutdown_session(projectDir)  # Checkpoints + graceful stop
   → resume_session(projectDir)    # Recover next time (auto-detects crash)

SESSION CRASHED (machine sleep, tmux died)?
   → resume_session(projectDir)  # Auto-detects crash, recovers from checkpoint
   → resume_session(projectDir, fromCheckpoint: "latest")  # Explicit checkpoint recovery

NEED TO ABORT?
   → orchestrator_reset(confirm: true)  # Nuclear option

FEATURE FAILED REPEATEDLY?
   → retry_feature(featureId)     # Reset attempt counter and try again

FEATURE FAILED AND NEEDS ROLLBACK?
   → check_rollback_conflicts(featureId)  # Check for conflicts with parallel workers
   → rollback_feature(featureId)  # Restore files to pre-worker state
   → retry_feature(featureId)     # Reset attempt counter

Rollback Warning: In parallel environments, rolling back can affect files modified by other concurrent workers. Always run check_rollback_conflicts first to see which files would be affected.

Quick Reference Flowchart

┌─────────────────────────────────────────────────────────────────┐
│                         SESSION START                            │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│  Phase 0: Ensure .gitignore has swarm files (.claude/, etc.)     │
│           → setup_analyze → IF score >= 50: setup_init           │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│  Phase 1: orchestrator_init + get_feature_complexity (all)       │
│           └─ Optional: protocols, verification, dependencies     │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│  Phase 2: IF complexity >= 60: competitive_planning → evaluate   │
│           └─ Optional: enrich_feature, validate_feature_protocols│
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│  Phase 3: start_worker OR start_parallel_workers                 │
│           └─ OR: auto_orchestrate (hands-free execution)         │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│  Phase 4: sleep 180 → check_worker → (loop until complete)       │
│           └─ IF stuck: get_worker_confidence, send_worker_message│
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│  Phase 5: run_verification → mark_complete → commit_progress     │
│           └─ Repeat Phase 2-5 for remaining features             │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│  Phase 6: check_reviews → get_review_results                     │
│           └─ Optional: implement_review_suggestions              │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
                            SESSION END

Protocol-Based Governance

Protocols define behavioral constraints that govern worker actions. This enables safe autonomous operation with clear boundaries.

Constraint Types

Using Protocols

1. protocol_register - Register a new protocol (JSON definition)
2. protocol_activate - Activate for enforcement
3. start_worker - Workers are validated against active protocols
4. get_violations - Review any constraint violations
5. protocol_deactivate - Deactivate when done

Example Protocol

{
  "id": "safe-refactoring-v1",
  "name": "Safe Refactoring Protocol",
  "version": "1.0.0",
  "priority": 100,
  "constraints": [
    {
      "id": "no-secrets",
      "type": "file_access",
      "rule": {
        "type": "file_access",
        "deniedPaths": ["**/.env", "**/secrets.*"]
      },
      "severity": "error",
      "message": "Cannot access files that may contain secrets"
    }
  ],
  "enforcement": {
    "mode": "strict",
    "preExecution": true,
    "postExecution": true,
    "onViolation": "block"
  }
}

LLM-Generated Protocols

Workers can propose new protocols validated against immutable base constraints:

1. get_base_constraints - View immutable security rules
2. propose_protocol - Worker submits proposal
3. review_proposals - See pending proposals with risk scores
4. approve_protocol / reject_protocol - Human review for high-risk

Sharing Protocols Across Projects

Protocols can be exported, shared, and synchronized across MCP instances:

EXPORT protocols from current project:
   → export_protocols(projectDir, protocolIds: [...])
   - Creates a shareable bundle file
   - Optionally sign for integrity verification

IMPORT protocols from bundle:
   → import_protocols(projectDir, bundlePath: "path/to/bundle.json")
   - Validates against base constraints
   - Conflict strategies: skip, replace, rename, merge

SYNC with peer instances:
   → discover_protocols(projectDir)  # Find available peers
   → sync_protocols(projectDir, direction: "pull")  # Get protocols from peers

Best Practices

Feature Decomposition

• Each feature should be completable in 15-60 minutes
• Features should be independently testable
• Order features by dependency (foundations first)
• Use set_dependencies to enforce ordering when needed

Parallel Execution

• Identify features that can run in parallel (no shared dependencies)
• Use start_parallel_workers to launch up to 10 workers at once
• Monitor all workers with check_all_workers
• Independent features complete faster when parallelized

Monitoring Workers

• Wait 2-3 minutes after starting before first check
• Use sleep 120 or sleep 180 between starting and checking
• Workers typically complete features in 5-10 minutes
• If stuck after 10+ minutes, review output carefully
• Use send_worker_message to provide guidance without restarting

Efficient Monitoring with Heartbeat Mode

Use check_worker with heartbeat: true for lightweight status checks:

check_worker(featureId, heartbeat: true)
-> Returns: status, lastToolUsed, lastFile, lastActivity, runningFor

Competitive Planning for Complex Features

For complex features (score >= 60), use competitive planning:

1. get_feature_complexity(featureId) - Analyze complexity
2. start_competitive_planning(featureId) - Spawn 2 planners
3. Wait for planners to complete (3-5 minutes)
4. evaluate_plans(featureId) - Compare and pick winner
5. start_worker with the winning plan as context

Evaluating Competing Plans (Detailed Guide)

After planners complete, use evaluate_plans to compare their approaches. Understanding the evaluation helps you decide when to accept automatic selection vs. override manually.

Step 1: Review Planner Outputs

Before evaluation, review what each planner produced:

# Quick status check
check_worker(featureId, heartbeat: true)

# Full output review (recommended for critical features)
check_worker(plannerSessionA)  # View full Planner A output
check_worker(plannerSessionB)  # View full Planner B output

Planners have different approaches by design:

• Planner A: Focuses on incremental, low-risk changes using established patterns
• Planner B: Explores alternative or more elegant approaches, looking for architectural improvements

Step 2: Understand the Scoring System

The automatic evaluation scores plans against five criteria (100 points total):

Step 3: Interpret the Results

The evaluation output shows scores and a winner recommendation:

Winner: Plan A
Margin: 12 points
Reason: Plan A selected with moderate advantage. Key strength: Includes risk mitigation strategies

--- Plan A (78/100) ---
  Completeness: 22/25
  Feasibility: 20/25
  Risk Awareness: 18/20
  Clarity: 10/15
  Efficiency: 8/15
  Strengths: Well-structured multi-step approach; Identifies 3 potential risks
  Concerns: Large number of files may indicate scope creep

--- Plan B (66/100) ---
  ...

Margin of Victory Interpretation:

Step 4: When to Use Manual Override

Override automatic selection when:

1. Domain knowledge trumps metrics: You know codebase constraints the evaluator cannot detect
2. Security-critical features: One plan has better security considerations despite lower score
3. Team conventions: One plan follows your team's established patterns better
4. Risk tolerance: Your project needs the conservative approach even if it scores slightly lower
5. Close margins with red flags: Plans nearly equal but one has concerning "Concerns" in output

Step 5: Making Manual Selections

To override, provide both the selection and reasoning:

evaluate_plans(
  featureId,
  manualSelection: "B",
  selectionReason: "Plan B's approach aligns with our event-driven architecture migration"
)

Good selection reasons include:

• Alignment with architectural direction
• Better handling of specific edge cases
• Consistency with recent team decisions
• Risk considerations for production systems

Example Override Scenarios:

Confidence-Based Monitoring

Track worker confidence to detect issues early:

1. set_confidence_threshold(35) - Configure alert threshold
2. get_worker_confidence(featureId) - Get detailed breakdown

Confidence levels:

• High (80-100): On track
• Medium (50-79): Normal operation
• Low (25-49): May need guidance
• Critical (0-24): Immediate attention

Post-Completion Reviews

After all workers complete, automated reviews run automatically:

1. All workers complete -> session transitions to "reviewing" status
2. Code review worker analyzes: bugs, security, style, test coverage
3. Architecture review worker analyzes: coupling, patterns, scalability
4. Findings aggregated into progress log
5. Use get_review_results for detailed findings
6. Use implement_review_suggestions to convert findings into new features

Review configuration:

• configure_reviews(enabled: false) - Disable automatic reviews
• run_review(reviewTypes: ["code"]) - Manually run specific reviews

Acting on Review Findings

Convert review issues into actionable features:

# View available issues from reviews
implement_review_suggestions(projectDir)

# Create features from specific issues by index
implement_review_suggestions(projectDir, issueIndices: [0, 2, 5])

# Auto-select warnings and errors
implement_review_suggestions(projectDir, autoSelect: true, minSeverity: "warning")

Error Recovery

• Auto-retry is enabled by default (3 attempts) via mark_complete
• Use retry_feature to manually reset after fixing issues
• Use add_feature if you discover missing work

Session Management

• Use pause_session to gracefully stop work
• Use resume_session to continue where you left off
• Use get_session_stats for success rates and timing

Git Checkpoints

• Commit after each successful feature with commit_progress
• Use descriptive commit messages
• Enables easy rollback if needed

When to Use Protocol Governance

Protocol governance adds behavioral constraints to workers. Use it when you need:

Security Enforcement:

• Restrict dangerous file operations during bulk refactoring
• Prevent accidental production data modification
• Block execution of certain shell commands

Team Policies:

• Enforce code style checking before file writes
• Limit iteration counts on long-running tasks
• Rate limit API calls in multi-worker scenarios

Compliance & Audit:

• Track constraint violations for compliance reports
• Enforce approval workflows for sensitive changes

When NOT to Use:

• Single-feature tasks (overhead not justified)
• Rapid experimentation (approval slows iteration)
• When base constraints are already sufficient

How Workers Can Propose Protocols

Workers can dynamically propose new protocols, validated against immutable base constraints before human review.

Step 1: Check Base Constraints

Before proposing, understand what cannot be overridden:

get_base_constraints(projectDir)

Base constraints include:

• Prohibited tools: rm -rf, sudo, chmod 777, etc.
• Protected paths: ~/.ssh, .env.production, /etc/passwd
• Required enforcement: Pre/post validation always enabled, 30-day audit retention

Step 2: Design the Protocol

propose_protocol(
  projectDir,
  protocol: {
    id: "my-protocol-v1",
    version: "1.0.0",
    name: "My Protocol Name",
    description: "What this protocol does",
    constraints: [
      {
        id: "constraint-1",
        type: "file_access",        // or: tool_restriction, behavioral, temporal, etc.
        severity: "error",          // or: warning, info
        message: "Human-readable explanation",
        rule: {
          type: "file_access",
          deniedPaths: [".env.production", "config/prod/**"]
        }
      }
    ],
    enforcement: {
      mode: "strict",               // or: permissive, audit, learning
      preExecutionValidation: true, // REQUIRED by base constraints
      postExecutionValidation: true,// REQUIRED by base constraints
      onViolation: "block",         // or: warn, log, notify
      logLevel: "standard"
    }
  },
  description: "Why this protocol is needed",
  rationale: "Design decisions and tradeoffs"
)

Step 3: Review Validation Results

The proposal is immediately validated. Check:

• isValid: Whether it passes all checks
• riskAssessment.overallScore: Risk score (0-100, lower is better)
• recommendations: Suggestions for improvement
• proposedFixes: Auto-fixable issues

Risk Level Thresholds:

Step 4: Review and Approve

# List pending proposals
review_proposals(projectDir, status: "pending")

# View specific proposal details
review_proposals(projectDir, proposalId: "prop-xxx")

# Approve and optionally activate immediately
approve_protocol(
  projectDir,
  proposalId: "prop-xxx",
  reason: "Needed for parallel refactoring safety",
  activate: true
)

# Or reject with explanation
reject_protocol(
  projectDir,
  proposalId: "prop-xxx",
  reason: "Too permissive, needs stricter file patterns"
)

Step 5: Activate and Monitor

# If not activated during approval
protocol_activate(protocolId)

# Monitor violations during work
get_violations(projectDir)

# Resolve false positives
resolve_violation(violationId, resolution: "False positive - file is test fixture")

# Deactivate when done
protocol_deactivate(protocolId)

Example Protocol Scenarios

Scenario 1: Production Protection

{
  "id": "prod-protection",
  "name": "Production Config Protection",
  "constraints": [{
    "id": "block-prod-env",
    "type": "file_access",
    "severity": "error",
    "message": "Cannot modify production config",
    "rule": {
      "type": "file_access",
      "deniedPaths": [".env.production", "config/production/**"]
    }
  }]
}

Scenario 2: API Rate Limiting

{
  "id": "api-rate-limit",
  "name": "API Rate Limiting",
  "constraints": [{
    "id": "limit-requests",
    "type": "temporal",
    "severity": "warning",
    "message": "Rate limit exceeded",
    "rule": {
      "type": "temporal",
      "rateLimitPerMinute": 10,
      "burstLimit": 3
    }
  }]
}

Scenario 3: Safe Refactoring Mode

{
  "id": "safe-refactor",
  "name": "Safe Refactoring Protocol",
  "constraints": [{
    "id": "read-first",
    "type": "behavioral",
    "severity": "warning",
    "message": "Analyze code before modifying",
    "rule": {
      "type": "behavioral",
      "maxIterations": 10,
      "requireConfirmation": true
    }
  }]
}

Web Dashboard

A real-time web dashboard is available at http://localhost:3456:

• Live updates via Server-Sent Events
• Session overview with progress bar
• Feature cards with status and dependencies
• Worker terminal output streaming with ANSI color support
• Review worker progress visibility
• Dark mode support

Tools Reference

Core Orchestration

Worker Management

Competitive Planning

Confidence Monitoring

Feature Management

Session & Progress

Post-Completion Reviews

Protocol Management

Protocol Enforcement

LLM Protocol Generation

Protocol Proposal Workflow:

1. get_base_constraints - View what cannot be overridden
2. propose_protocol - Submit proposal (validated immediately)
3. review_proposals - See pending with risk scores
4. approve_protocol / reject_protocol - Human decision
5. protocol_activate - Enable enforcement

Protocol Networking

Setup & Analysis

Context Management

Rollback

Automation

Example Session

User: "Build a REST API for a todo app with CRUD operations"

═══════════════════════════════════════════════════════════════════
PHASE 0: REPOSITORY READINESS CHECK
═══════════════════════════════════════════════════════════════════

Me: Let me check if this repository needs setup first.

[setup_analyze(projectDir)]
→ Freshness score: 75 (missing CLAUDE.md and CI workflow)

Since score >= 50, running setup...

[setup_init(projectDir)]
→ Setup workers started for CLAUDE.md, GitHub CI...

[setup_status(projectDir)]
→ All setup workers complete. Repo is now configured.

═══════════════════════════════════════════════════════════════════
PHASE 1: SESSION SETUP
═══════════════════════════════════════════════════════════════════

Me: Now I'll decompose the task and initialize the session.

[orchestrator_init with features:
1. Set up Express server with basic middleware
2. Create Todo model with Mongoose
3. Implement POST /todos endpoint
4. Implement GET /todos endpoint
5. Implement PUT /todos/:id endpoint
6. Implement DELETE /todos/:id endpoint
7. Add input validation middleware
8. Add error handling middleware
9. Write integration tests]

Session initialized with 9 features.

Now analyzing complexity for all features...

[get_feature_complexity for each feature-1 through feature-9]

Results:
- feature-1 (Express setup): score 35, recommendation: simple
- feature-2 (Mongoose model): score 25, recommendation: simple
- feature-3 through feature-6 (CRUD): scores 20-30, recommendation: simple
- feature-7 (validation): score 45, recommendation: manual_review
- feature-8 (error handling): score 50, recommendation: manual_review
- feature-9 (integration tests): score 65, recommendation: competitive_planning ← FLAG

One feature (tests) flagged for competitive planning.

═══════════════════════════════════════════════════════════════════
PHASE 2: PRE-WORK PREPARATION (for feature-9)
═══════════════════════════════════════════════════════════════════

Since feature-9 has complexity >= 60, using competitive planning:

[start_competitive_planning(feature-9)]
→ Planners A and B started...

[sleep 300]  # Wait 5 minutes for planners

[evaluate_plans(feature-9)]
→ Plan A selected: comprehensive Jest test suite with mocking strategy

═══════════════════════════════════════════════════════════════════
PHASE 3: EXECUTION
═══════════════════════════════════════════════════════════════════

Starting with simple features in parallel:

[validate_workers([feature-1, feature-2, feature-3, feature-4])]
→ No conflicts detected.

[start_parallel_workers([feature-1, feature-2, feature-3, feature-4])]
→ 4 workers started in parallel.

═══════════════════════════════════════════════════════════════════
PHASE 4: MONITORING
═══════════════════════════════════════════════════════════════════

[sleep 180]  # Wait 3 minutes before first check

[check_all_workers(heartbeat: true)]
→ All 4 workers still running...

[sleep 120]

[check_all_workers(heartbeat: true)]
→ Workers completed: feature-1, feature-2, feature-3, feature-4

═══════════════════════════════════════════════════════════════════
PHASE 5: COMPLETION
═══════════════════════════════════════════════════════════════════

[run_verification("npm run build")]
→ Build passed!

[mark_complete(feature-1, success: true)]
[mark_complete(feature-2, success: true)]
[mark_complete(feature-3, success: true)]
[mark_complete(feature-4, success: true)]

[commit_progress("feat: add Express server, Mongoose model, and basic CRUD endpoints")]

═══════════════════════════════════════════════════════════════════
CONTINUE WITH REMAINING FEATURES
═══════════════════════════════════════════════════════════════════

[start_parallel_workers([feature-5, feature-6, feature-7, feature-8])]
... (monitoring and completion cycle)

[start_worker(feature-9)]  # Uses winning plan from competitive planning
... (monitoring and completion cycle)

═══════════════════════════════════════════════════════════════════
PHASE 6: POST-COMPLETION REVIEWS
═══════════════════════════════════════════════════════════════════

All features complete. Automatic reviews starting...

[check_reviews()]
→ Reviews in progress: code-review, architecture-review

[sleep 180]

[get_review_results()]
→ Code review: 2 warnings (missing error handling in 2 places)
→ Architecture review: 1 suggestion (consider middleware consolidation)

[implement_review_suggestions(autoSelect: true, minSeverity: "warning")]
→ Created feature-10: Add missing error handling
→ Created feature-11: Consolidate middleware

[Continue from Phase 2 with new features...]

Repo Setup

Use the Repo Setup feature to configure new or existing repositories with development best practices. The swarm can set up CLAUDE.md files, CI/CD workflows, issue templates, and more—all in parallel with smart defaults based on your project type.

When to Use

• Fresh projects: Initialize a new repo with complete development infrastructure
• Adding CI to existing projects: Add GitHub Actions, Dependabot, or Release Please to a mature codebase
• Standardizing repos: Apply consistent configuration across multiple repositories
• Upgrading configs: Update outdated CI workflows or templates to current best practices

Quick Setup Workflow

User: "Set up this new TypeScript project with CI, issue templates, and release automation"

[Analyze project: detect package.json, tsconfig.json, src/ structure]

Me: I'll configure this repo with appropriate settings. Let me initialize the setup swarm.

[Call orchestrator_init with features:
1. Create CLAUDE.md with project-specific guidance
2. Add GitHub Actions CI workflow for TypeScript
3. Configure Dependabot for npm dependencies
4. Add Release Please for automated releases
5. Create issue templates (bug report, feature request)
6. Add pull request template
7. Create CONTRIBUTING.md with guidelines
8. Add SECURITY.md with vulnerability policy]

Session initialized with 8 features.

[start_parallel_workers for features 1-8]  # All independent, run in parallel
Workers started for all configuration features...

[Run: sleep 120]  # Wait 2 minutes

[check_all_workers]
All workers completed successfully.

[run_verification: "npm run build && npm test"]
Build and tests pass with new configuration!

[commit_progress: "chore: add repo configuration and CI"]

Configuration Types

Customization Options

Control which configurations are applied using these options in your task description or worker prompts:

Skip specific configs - Use skipConfigs to exclude certain configuration types:

"Set up CI and issue templates, but skip Release Please and Dependabot"
-> skipConfigs: ["release-please", "dependabot"]

Force overwrite - Use force: true to replace existing configurations:

"Update all CI workflows to latest patterns, replacing existing ones"
-> force: true (overwrites existing .github/workflows/)

Merge mode (default) - Without force, existing configs are preserved and merged:

• Existing CLAUDE.md sections are kept, new guidance is appended
• Workflow files are only created if they don't exist
• Issue templates add to existing templates rather than replacing

Project Type Detection

The setup swarm auto-detects your project type and applies appropriate defaults:

Example: Adding CI to Existing Project

User: "Add GitHub Actions CI to this Python project, keep existing issue templates"

[Detect: pyproject.toml, pytest in dependencies, existing .github/ISSUE_TEMPLATE/]

Me: I'll add Python CI while preserving your existing templates.

[Call orchestrator_init with features:
1. Create GitHub Actions CI for Python with pytest
2. Configure Dependabot for pip dependencies
3. Update CLAUDE.md with CI information]

[start_parallel_workers]
...

[Workers complete, merge with existing .github/ structure]
[Existing issue templates preserved, new CI workflow added]

[commit_progress: "ci: add GitHub Actions workflow for Python"]

Security Considerations

Protocol Safety

Protocols are validated against immutable base constraints that cannot be overridden:

• Prohibited tools: Dangerous system commands (rm -rf, sudo, etc.)
• Protected paths: System directories, SSH keys, credentials
• Privilege ceiling: Maximum permissions any protocol can grant

Worker Isolation

Workers operate with limited capabilities:

• Implementation workers: Bash, Read, Write, Edit, Glob, Grep only
• Review workers: Read-only (no Bash access)
• Planner workers: Read-only tools for analysis

Safe Pattern Matching

The orchestrator uses safe regex handling:

• Dangerous patterns (ReDoS) are detected and fall back to literal matching
• User input is never passed directly to regex engines
• Glob patterns are safely converted with proper escaping

Troubleshooting

"No active session"

Run orchestrator_status to check state, or orchestrator_init to start fresh.

Worker seems stuck

1. check_worker to see current output
2. Try send_worker_message to give guidance
3. If truly stuck, mark_complete with success=false (will auto-retry)
4. If retries exhausted, use retry_feature to reset

Feature has unmet dependencies

1. Check dependencies with orchestrator_status
2. Complete dependency features first
3. Or use set_dependencies to modify the chain

Lost context after compaction

Call orchestrator_status - the MCP server maintains all state.

Need to pause temporarily

Use pause_session to stop workers, then resume_session when ready.

Need to abort

Use orchestrator_reset with confirm=true to kill all workers and clear state.

Protocol violations blocking work

1. get_violations to see what was violated
2. Fix the issue or resolve_violation if false positive
3. Adjust protocol constraints if too strict

Memory issues

If the orchestrator seems slow or unresponsive:

1. Check active session size: orchestrator_status
2. Clear old violations: resolve_violation for old entries
3. Reset if necessary: orchestrator_reset

Pattern matching issues

If protocol patterns aren't matching as expected:

1. Patterns use regex syntax (not glob by default)
2. Very complex patterns may fall back to literal matching for safety
3. Use simpler patterns if exact matching fails

Monitor not running

If workers aren't being tracked:

1. The monitor auto-stops after 5 consecutive errors
2. Check MCP server logs for error messages
3. Restart the MCP server if needed