cj-vana/claude-swarm/skill

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)

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

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"])

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)

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.

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

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

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

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

┌─────────────────────────────────────────────────────────────────┐
│                         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