Epic AI Swarm Orchestration
by @linkbag
Production playbook and portable runtime for parallel AI coding swarms using Codex, Gemini, DeepSeek, and optional Claude. Use when orchestrating multi-agent...
clawhub install epic-ai-swarm-orchestrationπ About This Skill
name: epic-ai-swarm-orchestration description: Production playbook for running parallel AI coding agents (Claude, Codex, Gemini) with automatic model selection via duty table, token-limit auto-fallback, human oversight, quality gates, and automated integration. Use when orchestrating multi-agent coding swarms, spawning parallel builders with review loops, managing model availability/rotation across vendors, or integrating branches from multiple AI agents. Triggers on phrases like "run the swarm", "spawn agents", "AI swarm", "multi-agent build", "duty table", "model rotation", "parallel coding agents".
Epic AI Swarm Orchestration v3.2.1
Production system for running parallel AI coding agents with dynamic model selection, automatic token-limit failover, and quality gates.
Prerequisites
Required CLIs (on PATH)
tmux β agent sandboxing (each agent in its own session)git β worktree creation, branching, commits, pushgh β GitHub CLI (authenticated via gh auth login)python3 β JSON manipulation (no pip packages)openclaw β notification delivery (Telegram/other)Model CLIs (at least one, authenticated)
claude β Anthropic CLI (OAuth or API key)codex β OpenAI Codex CLI (optional)gemini β Google Gemini CLI (optional)Scripts use host-authenticated CLIs β they do not store credentials.
Quick Start
1. Copy scripts/ to ~/workspace/swarm/
2. Edit scripts/swarm.conf with notification target
3. Run scripts/assess-models.sh to initialize the duty table
4. Read references/workflow.md for the 3-phase workflow
5. Read references/duty-table.md for model rotation system
6. Read references/tools.md for spawn commands
v3.2.1 Bookkeeping Fix
This release fixes a critical integration-watcher bookkeeping bug: spawn-batch.sh and queue-watcher.sh now record the actual tmux session emitted by spawn-agent.sh after duty-table/fallback resolution, instead of predicting names from the requested agent. integration-watcher.sh also refuses to treat unknown/misspelled expected sessions as complete.
Architecture Overview
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β DUTY TABLE β
β assess-models.sh β duty-table.json (daily cron) β
β architect=claude/opus, builder=codex, reviewer=gemini β
βββββββββββββ¬ββββββββββββββββββββββββββββββ¬ββββββββββββββββ
β β
βββββββββΌββββββββ βββββββββββΌβββββββββ
β spawn-agent.shβ β spawn-batch.sh β
β (single task) β β (parallel tasks) β
βββββββββ¬ββββββββ ββββββββββ¬ββββββββββ
β Reads role β agent/model β
β from duty-table.json β
βββββββββΌβββββββββββββββββββββββββββββΌββββββββββββ
β RUNNER (in tmux) β
β On token limit β model-fallback.sh β
β Auto-retry up to 2x with next available model β
β Updates duty table for future spawns β
βββββββββ¬ββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββΌββββββββββββββββββββββββ
β notify-on-complete.sh β
β β auto-spawns reviewer β
β β integration-watcher.sh β
β β ESR + work log persistence β
βββββββββββββββββββββββββββββββββ
Duty Table System
The duty table (duty-table.json) maps roles to agents/models:
| Role | Purpose | Default Assignment | |------|---------|-------------------| | architect | Planning, design | Claude Opus (best reasoning) | | builder | Implementation | Codex or Claude Sonnet (fast) | | reviewer | Code review + fixes | Gemini Flash or Sonnet | | integrator | Branch merging | Claude Opus (deep thinking) |
Auto-Assessment
assess-models.sh runs daily (or on-demand) to:
1. Test all models across all 3 vendors (45s timeout each)
2. Assign optimal 3-vendor spread to roles
3. If both Codex + Gemini down β fallback to all-Claude tableMid-Run Token Failover
When an agent hits a token/rate limit during execution: 1. Runner detects the error pattern in output 2. Callsmodel-fallback.sh with the role + failed model
3. Gets the next available model from the per-role fallback chain
4. Retries the task (up to 2 attempts)
5. Updates duty table so future spawns use the working model
6. Logs the switch to pending-notifications.txtSee references/duty-table.md for full details.
Core Scripts
| Script | Purpose |
|--------|---------|
| spawn-agent.sh | Spawn single agent (resolves role from duty table) |
| spawn-batch.sh | Spawn parallel agents with auto-queuing |
| assess-models.sh | Test models, update duty table |
| model-fallback.sh | Find next available model for a role |
| fallback-swap.sh | Pre-spawn primary/fallback test |
| try-model.sh | Quick model health check |
| notify-on-complete.sh | Watcher: auto-review + integration |
| integration-watcher.sh | Merge all branches after batch |
| queue-watcher.sh | Auto-spawn queued overflow tasks |
| pulse-check.sh | Detect stuck agents, auto-kill |
| check-agents.sh | Monitor all active agents |
| endorse-task.sh | Human endorsement gate |
| esr-log.sh | Engineering Status Report logging |
| daily-standup.sh | Daily status summary |
| cleanup.sh | Remove old worktrees + logs |
Workflow
Phase 1: PLAN (Architect)
Phase 2: BUILD + REVIEW (Builder + Reviewer)
spawn-batch.sh deploys agents in tmux + worktreesnotify-on-complete.sh auto-spawns reviewer (max 3 fix loops)Phase 3: SHIP (Integrator)
integration-watcher.sh merges all branches sequentiallyConfiguration
swarm.conf:
SWARM_NOTIFY_TARGET=""
SWARM_NOTIFY_CHANNEL="telegram"
SWARM_MAX_CONCURRENT=8
Endorsement System
Every task requires human approval before agents spawn:
endorse-task.sh # Single task
spawn-batch.sh ... # Batch endorsement (auto per-task)
30-second cooldown between endorsement and spawn prevents accidental double-runs.
π‘ Examples
1. Copy scripts/ to ~/workspace/swarm/
2. Edit scripts/swarm.conf with notification target
3. Run scripts/assess-models.sh to initialize the duty table
4. Read references/workflow.md for the 3-phase workflow
5. Read references/duty-table.md for model rotation system
6. Read references/tools.md for spawn commands
βοΈ Configuration
swarm.conf:
SWARM_NOTIFY_TARGET=""
SWARM_NOTIFY_CHANNEL="telegram"
SWARM_MAX_CONCURRENT=8