🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
πŸ¦€ ClawHub

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...

Versionv3.3.1
Downloads681
TERMINAL
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, push
  • gh β€” 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 table

    Mid-Run Token Failover

    When an agent hits a token/rate limit during execution: 1. Runner detects the error pattern in output 2. Calls model-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.txt

    See 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)

  • Read project context, ESR, codebase
  • Break work into parallel tasks with prompts
  • Present plan to human β†’ HOLD until endorsed
  • Phase 2: BUILD + REVIEW (Builder + Reviewer)

  • spawn-batch.sh deploys agents in tmux + worktrees
  • Each agent codes autonomously with structured work log
  • notify-on-complete.sh auto-spawns reviewer (max 3 fix loops)
  • Token limits trigger automatic model switch mid-run
  • Phase 3: SHIP (Integrator)

  • integration-watcher.sh merges all branches sequentially
  • Conflict resolution, build verification
  • ESR + work log persisted to project history
  • Telegram notification with shipped summary
  • Configuration

    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