Epic Ai Swarm Orchestration

Multi-agent AI swarm orchestration system for parallel coding tasks. Use when spawning multiple AI coding agents (Claude, Codex, Gemini) to work in parallel...

Security Scan

The skill's declared metadata is plausible for a multi-agent orchestrator, but the runtime instructions and included scripts require external CLIs, credentials, and powerful repo-changing actions (auto-merge, cleanup, notifications) that are not declared in the skill metadata — this mismatch and the lack of explicit credential requirements warrants caution.

Purpose & Capability

The name/description match the repository contents: many orchestration scripts (spawn, monitor, integrate, notify) are present and consistent with a swarm orchestrator. However, the registry metadata declares no required binaries or environment variables while SKILL.md explicitly requires tmux, git, gh CLI, coding-agent CLIs (claude/codex/gemini), python3, and optionally OpenClaw for Telegram/Discord. That omission is an incoherence: a user installing this skill would need those external tools and credentials for it to function, but the skill did not declare them.

Instruction Scope

SKILL.md instructs the agent/user to run scripts that create git worktrees/branches, run tmux sessions, auto-spawn multiple model CLIs, auto-merge branches into main, delete branches/worktrees, and send notifications to Telegram/Discord. These are all within the stated purpose, but they involve sensitive operations (git push/merge, branch deletion, network notifications, invoking external model CLIs) and the instructions also reference /tmp paths and writing/reading local files (worklogs, blocker files, queue files). There are no instructions that obviously read unrelated system secrets, but because the scripts can call gh and notification tooling, they will rely on credentials that are not declared — giving them access to repositories and messaging channels. The skill's runtime text also encourages embedding prompt files and absolute project paths, which increases the risk that sensitive repository data could be pushed or transmitted if misused.

Install Mechanism

No install spec is present (instruction-only install), so nothing is downloaded or executed by an installer. The code files are bundled in the skill archive and are shell scripts / docs. This is lower install risk than a remote download/install step. Still, the scripts themselves will be copied/run by the user/agent when invoked, so their contents should be audited before execution.

Credentials

The skill requests no environment variables or primary credential in the registry metadata, yet the SKILL.md and references clearly expect configured credentials and signals: gh CLI authorization for PR/merge/push, API keys / CLI tokens for coding agents (claude/codex/gemini), and SWARM_NOTIFY_TARGET / SWARM_NOTIFY_CHANNEL / openclaw configuration for Telegram/Discord notifications. This mismatch is significant: the orchestrator needs access to external services and potentially to repository write permissions, but it does not declare or surface these requirements. Required credentials are disproportionate to the metadata and could lead to unexpected credential use if the user assumes no secrets are needed.

Persistence & Privilege

always:false and disable-model-invocation:false (normal). The skill will run autonomously when invoked and will run scripts that can mutate local repositories (create/merge/delete branches) and create background watchers (queue-watcher, integration-watcher). There is no declaration that it modifies other skills or system-wide agent settings. The combination of autonomous invocation plus repository-write operations and notification endpoints raises the blast radius if the scripts are run with privileged credentials, but autonomous invocation by itself is an expected default.

What to consider before installing

What to consider before installing/using this skill: - Trust and provenance: The package has no homepage and an unknown source. Only install/run if you trust the publisher and have reviewed the scripts. - Missing metadata vs real requirements: Although the registry lists no required binaries or env vars, the SKILL.md (and scripts) need tmux, git, gh CLI, python3, and coding-agent CLIs plus optional OpenClaw/Telegram config. Treat the registry metadata as incomplete; plan to supply and audit credentials yourself. - Credential scope and secrets: If you grant gh CLI or git credentials in the environment or authorize the GH CLI on the machine, these scripts can create branches, open/merge PRs, and push changes. Use least-privilege credentials (a deploy key or bot account with limited repo access) and avoid using admin tokens. Similarly, agent CLIs (Claude/Codex/Gemini) require API tokens; do not reuse high-privilege tokens. - Test in isolation first: Run the scripts in a disposable repository or container. Use dry-run modes where available, and verify behavior (bash -n on scripts, run with --dry-run options). Confirm that auto-merge paths behave as expected before pointing them at important repos. - Audit scripts thoroughly: Inspect spawn-*/integration*/notify* scripts for network endpoints, hardcoded URLs, or unexpected commands that would exfiltrate files. Search for any use of curl/wget/ssh/http endpoints or long-lived background jobs that post data. - Notifications and external endpoints: Configure notification targets to a test channel/account. Avoid pointing to production messaging groups until you are confident the end-to-end flow is correct. - Limit automation privileges: If you want automation, create a service account with only the permissions you need (e.g., only push to a specific branch namespace, or only create PRs without auto-merge). Consider disabling auto-merge until you have validated the pipeline. - When in doubt, treat as untrusted code and run in an isolated environment. If you want more assurance, provide the full contents of the key scripts (spawn-batch.sh, spawn-agent.sh, integration-watcher.sh, notify-on-complete.sh, pulse-check.sh, and any files that call remote services) so they can be inspected line-by-line; that would raise confidence and could change the verdict.

Epic AI Swarm Orchestration v3.1

Multi-agent coding orchestration: plan → endorse → spawn → monitor → review → integrate → ship.

Core Workflow

1. Plan — Break work into parallel tasks, present plan to user for endorsement
2. Endorse — endorse-task.sh <task-id> (or auto-endorsed via spawn-batch.sh)
3. Spawn — spawn-batch.sh (multi) or spawn-agent.sh (single)
4. Monitor — Auto: tmux sessions, notify-on-complete.sh watchers, pulse-check.sh
5. Review — Auto: reviewer agent spawns on completion, max 3 fix rounds
6. Integrate — Auto: integration-watcher.sh merges all branches, resolves conflicts
7. Ship — Auto-merge to main, cleanup worktrees, notify user

Script Reference

Primary (use these)

Script	Purpose	When
spawn-batch.sh	Spawn N agents + auto-integration	Multi-agent work
spawn-agent.sh	Spawn single agent	Single tasks
endorse-task.sh	Endorse a task	Before spawning
check-agents.sh	Check tmux status	Quick status
cleanup.sh	Remove worktrees + branches	Post-merge

Usage

# 1. Write prompts
cat > /tmp/prompt-task1.md << 'EOF'
... task description ...
EOF

# 2. Create tasks JSON
cat > /tmp/tasks.json << 'EOF'
[
  {"id": "task-1", "description": "/tmp/prompt-task1.md", "agent": "claude", "model": "claude-sonnet-4-6"},
  {"id": "task-2", "description": "/tmp/prompt-task2.md", "agent": "claude", "model": "claude-sonnet-4-6"}
]
EOF

# 3. Endorse + spawn
cd path/to/swarm/scripts
bash endorse-task.sh task-1
bash endorse-task.sh task-2
bash spawn-batch.sh "/path/to/project" "batch-id" "Description" /tmp/tasks.json

spawn-agent.sh

spawn-agent.sh <project-dir> <task-id> <description-or-prompt-file> [agent] [model] [reasoning]

• project-dir: Absolute path to project root
• task-id: Unique ID (used for branch name + tmux session)
• description: Task prompt text or path to .md prompt file
• agent: claude | codex | gemini (default: claude)
• model: Model override (default: per duty table)
• reasoning: low | medium | high (default: high)

Supporting Scripts

Script	Purpose
integration-watcher.sh	Poll + auto-merge (called by spawn-batch)
notify-on-complete.sh	Per-agent watcher (called by spawn-agent)
start-integration.sh	Manual integration start
pulse-check.sh	Detect stuck agents
queue-watcher.sh	Process inbox queue
inbox-add.sh	Add task to inbox
inbox-list.sh	List queued tasks
assess-models.sh	Weekly model rotation
deploy-notify.sh	CI/CD build notifications
esr-log.sh	Log to ESR/work history
daily-standup.sh	Generate standup summary
cleanup.sh	Post-merge cleanup

Setup

1. Copy scripts/ to your workspace (e.g., ~/workspace/swarm/)
2. Copy duty-table.template.json → duty-table.json and customize
3. Ensure tmux, git, gh CLI, and at least one coding agent CLI are installed
4. For notifications: configure OpenClaw with Telegram/Discord

Dependencies

• bash 4+ (macOS: install via Homebrew, ships with Linux)
• tmux (all platforms: brew install tmux / apt install tmux)
• git + gh CLI (for PR creation and merging)
• jq (JSON processing: brew install jq / apt install jq)
• At least one coding agent: claude (Claude Code), codex, or gemini
• Optional: openclaw (for Telegram/Discord notifications)

macOS Notes

• macOS ships with bash 3.x; install bash 5+ via brew install bash
• Use brew install gnu-sed and alias sed=gsed if scripts use GNU sed features
• tmux works identically on macOS and Linux

Configuration

duty-table.json

Maps roles to agents/models:

{
  "dutyTable": {
    "architect": {"agent": "claude", "model": "claude-opus-4-6"},
    "builder":   {"agent": "claude", "model": "claude-sonnet-4-6"},
    "reviewer":  {"agent": "claude", "model": "claude-sonnet-4-6"},
    "integrator":{"agent": "claude", "model": "claude-opus-4-6"}
  }
}

Endorsement System

Every task requires endorsement before spawning (safety gate):

• spawn-batch.sh auto-endorses all tasks in the batch
• Manual: bash endorse-task.sh <task-id>
• 30-second cooldown between endorsement and spawn

Hard Rules

1. Always endorse before spawning — no endorsement = no spawn
2. Use spawn-batch.sh for 2+ tasks — it starts the integration watcher
3. Never use bare claude --print in background — bypasses tmux, notifications, everything
4. Let notify-on-complete.sh handle notifications — don't add openclaw system event to prompts