--- name: pi-swarm description: Spawns parallel pi agents to work on multiple GitHub issues or PRs using git worktrees. Use when asked to process multiple items in parallel, perform bulk reviews\/fixes, or orchestrate entire projects. --- # Pi Swarm Orchestrates parallel headless pi agents across isolated git worktrees to process GitHub issues, PRs, epics, and entire projects. ## Command Hierarchy ``` Commander (Project\/Milestone level) │ ├─► Captain (Epic level) │ ├─► swarm.sh (Issue wave 1) │ ├─► pr-swarm.sh (Review PRs) │ ├─► swarm.sh (Issue wave 2) │ └─► ... │ └─► Captain (Another Epic) └─► ... ``` ## Scripts ### Issue Swarm Process multiple issues in parallel: ```bash scripts\/swarm.sh 48 50 52 ``` ### PR Swarm Review and fix multiple PRs in parallel: ```bash scripts\/pr-swarm.sh 101 105 ``` ### Captain (Epic Orchestrator) Orchestrate an entire epic with dependency-aware wave execution: ```bash scripts\/captain.sh --epic 151 ``` ### Commander (Project\/Milestone Orchestrator) Orchestrate multiple epics or generate a project from scratch: ```bash # From a milestone issue scripts\/commander.sh --milestone 200 # From specific epics scripts\/commander.sh --epics 151 160 175 # Generate new project from description scripts\/commander.sh --project "Build a CLI todo app with SQLite backend" ``` ## What Each Script Does ### swarm.sh For each issue: 1. **Fetches** details from GitHub API 2. **Creates** isolated git worktree 3. **Spawns** headless pi agent 4. **Commits** and creates PR ### pr-swarm.sh For each PR: 1. **Fetches** PR and checks out branch 2. **Reviews** with pi agent 3. **Fixes** issues directly 4. **Pushes** and posts comment ### captain.sh For an epic: 1. **Parses** epic → extracts issues & dependencies 2. **Plans** execution waves 3. **Dispatches** swarm.sh per wave 4. **Reviews** PRs with pr-swarm.sh 5. **Validates** success criteria 6. **Reports** to epic issue ### commander.sh For a project\/milestone: 1. **Parses** milestone OR **generates** project plan 2. **Creates** GitHub issues (if --project mode) 3. **Plans** epic waves with dependencies 4. **Dispatches** captain.sh per epic 5. **Monitors** cross-epic progress 6. **Reports** final status ## Options ### swarm.sh \/ pr-swarm.sh | Flag | Description | Default | |------|-------------|---------| | `--model ` | Model to use | (default) | | `--push` \/ `--no-push` | Push changes | enabled | | `--pr` \/ `--no-pr` | Create PRs | enabled | | `--cleanup` \/ `--no-cleanup` | Delete worktrees | enabled | | `-j, --jobs ` | Max parallel jobs | unlimited | | `--timeout ` | Timeout per task | no timeout | | `--dry-run` | Preview only | disabled | ### captain.sh | Flag | Description | Default | |------|-------------|---------| | `--epic ` | Epic issue number | required | | `--model ` | Model for agents | (default) | | `--max-retries ` | Retries per task | 2 | | `--wave-timeout ` | Timeout per wave | 60 min | | `--resume` | Resume from state | disabled | | `--force` | Force start (override stale lock) | disabled | | `-j, --jobs ` | Jobs per wave | unlimited | | `--dry-run` | Plan only | disabled | ### commander.sh | Flag | Description | Default | |------|-------------|---------| | `--milestone ` | Milestone issue | - | | `--epics ...` | Epic numbers | - | | `--project ` | Project description | - | | `--model ` | Model for agents | (default) | | `--max-parallel ` | Parallel captains | 2 | | `--max-retries ` | Retries per epic | 1 | | `--epic-timeout ` | Timeout per epic | 120 min | | `--resume` | Resume from state | disabled | | `--force` | Force start (override stale lock) | disabled | | `-j, --jobs ` | Jobs per captain | unlimited | | `--dry-run` | Plan only | disabled | ## Monitoring ```bash # Swarm logs tail -f .worktrees\/*.log # Captain state cat .captain\/epic-151.json | jq . # Commander state cat .commander\/milestone-200.json | jq . # Watch all logs tail -f .worktrees\/*.log .captain\/*.log .commander\/*.log ``` ## Output Structure ``` .worktrees\/ ├── issue-48\/ # Worktree ├── issue-48.log # Log ├── issue-48.jsonl # Agent JSON log └── issue-48.pr # PR URL .captain\/ ├── epic-151.json # State ├── epic-151-plan.json # Plan └── epic-151.log # Log .commander\/ ├── milestone-200.json # State ├── milestone-200-plan.json # Plan ├── epic-151.log # Captain logs └── epic-160.log ``` ## Full Workflow ``` commander.sh --project "Todo CLI app" │ ▼ ┌─────────────────────┐ │ Generate Plan │ ← Pi creates epics & issues └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ Create GH Issues │ ← Creates epic + sub-issues └──────────┬──────────┘ │ ┌──────┴──────┐ ▼ ▼ ┌────────┐ ┌────────┐ │Captain │ │Captain │ ← Parallel epics │Epic #1 │ │Epic #2 │ └───┬────┘ └───┬────┘ │ │ ▼ ▼ ┌────────┐ ┌────────┐ │ Waves │ │ Waves │ ← swarm.sh + pr-swarm.sh └───┬────┘ └───┬────┘ │ │ └─────┬──────┘ ▼ ┌─────────────────────┐ │ Final Report │ ← Posted to milestone\/project └─────────────────────┘ ``` ## Error Handling The scripts detect and handle various error types: | Error Type | Detection | Behavior | |------------|-----------|----------| | **Rate Limit (429)** | "rate limit", "too many requests" | Retry with exponential backoff | | **Auth (401\/403)** | "unauthorized", "forbidden" | **Fatal** - stop immediately | | **Quota Exceeded** | "quota", "billing", "insufficient" | **Fatal** - stop immediately | | **Timeout** | Exit code 124 | Retry with backoff | | **Network** | "connection", "ECONNREFUSED" | Retry with backoff | | **API Error (5xx)** | "500", "502", "503" | Retry with backoff | ### Fatal Errors When quota\/auth errors are detected: 1. Task marked as `fatal` (won't retry) 2. Error recorded in state file 3. Execution stops after current wave 4. Summary includes error details ### Resuming After Errors ```bash # Fix the issue (add credits, update API key, etc.) # Then resume: scripts\/captain.sh --epic 151 --resume # Force restart if lock is stale: scripts\/captain.sh --epic 151 --resume --force ``` ### Process Liveness - Lock files prevent duplicate runs - Heartbeat files detect stale processes - `--force` overrides stale locks ## Examples ```bash # Process issues with timeout scripts\/swarm.sh --timeout 30 -j 2 48 50 52 # Review PRs (no push) scripts\/pr-swarm.sh --no-push 101 102 # Dry run captain scripts\/captain.sh --epic 151 --dry-run # Execute epic with opus scripts\/captain.sh --epic 151 --model opus -j 3 # Resume interrupted epic scripts\/captain.sh --epic 151 --resume # Force resume if lock is stale scripts\/captain.sh --epic 151 --resume --force # Execute milestone with 3 parallel captains scripts\/commander.sh --milestone 200 --max-parallel 3 # Execute specific epics scripts\/commander.sh --epics 151 160 175 # Generate and execute new project scripts\/commander.sh --project "Build REST API for user management with JWT auth" # Dry run project generation (shows plan + creates issues) scripts\/commander.sh --project "CLI todo app" --dry-run # Run cleanup after completion scripts\/commander.sh --milestone 200 --cleanup # Merge PRs after completion scripts\/commander.sh --epics 151 160 --merge-prs ```