Swarm Orchestrator — Parallel Agent Execution at Scale

The "team-of-specialists" pattern. Where /devil-mode is a fixed adversarial sweep with 4–8 specific agents, swarm is the generalized form: pick any task, pick any agents (or let ECC pick from task signals), get N parallel worktrees + a tmux session ready to attach.

> Phase 2.7 of the Devil Roadmap. Promotes the existing tmux-worktree-orchestrator infrastructure to a first-class CLI surface.

When to invoke

Trigger this skill when:

• A task is too cross-cutting for one specialist (touches security AND perf AND API AND tests).
• The user asks for "parallel review", "multi-agent sweep", "parallel agents", or "team review".
• A change is high-stakes and you want defense-in-depth (security audit + UX + perf + arch in 15 min instead of 60).
• The user has 4+ cores and wants throughput.

• The task is genuinely single-axis (just security → use security-reviewer directly).
• The repo is tiny enough that worktree overhead exceeds review time.
• The user is on a machine without tmux/git worktree support.

CLI surface

# Auto-pick agents from task signals.
npx kodelyth-ecc swarm --task "audit the new oauth flow for security regressions" --agents 4
Explicit agent list.
npx kodelyth-ecc swarm --task "ship v2.0" \
  --agents release-captain,security-reviewer,e2e-runner,code-reviewer \
  --execute
Different harness (codex / opencode / windsurf).
npx kodelyth-ecc swarm --task "refactor payment module" --agents 6 --harness codex --execute
Power-user: hand-written plan.
npx kodelyth-ecc swarm --plan plan.json --execute

Three execution modes:

| Mode | Effect | |---|---| | (default) dry-run | Prints the plan. Doesn't spawn anything. Safe to inspect. | | --write-only | Materializes coordination files (task.md, handoff.md, status.md) but doesn't spawn worktrees or tmux. | | --execute | Creates git worktrees, spawns tmux session, launches each agent in its own pane. |

Smart agent picking

When you pass --agents N (a number), the swarm picks specialists in this priority order:

• Signal-driven — task keywords match agent specialties (security → security-reviewer, perf → performance-optimizer, API → api-guardian, etc.). 14 signal classes.
• Baseline anchors — code-reviewer and pair-programmer are added if not already picked (every task benefits from generalist eyes).
• Rotation fill — fills remaining slots from a 4 / 6 / 8-agent default rotation tuned for breadth.

Harness adapters

| --harness | Launcher | Notes | |---|---|---| | claude | claude --print --dangerously-skip-permissions ... | Default. Works with Claude Code. | | codex | bash scripts/orchestrate-codex-worker.sh ... | Codex CLI worker with full status tracking. | | opencode | opencode run --task-file ... | OpenCode harness. | | windsurf | windsurf-cli run --task-file ... | Windsurf agent. | | echo | trivial echo | For dry-run validation only. |

Use --launcher-cmd "" to plug a custom harness. Available placeholders:

{worker_name} {worker_slug} {session_name} {repo_root}
{worktree_path} {branch_name} {task_file} {handoff_file} {status_file}

Add _sh suffix for shell-quoted variants ({task_file_sh}, etc.).

Coordination protocol

Every worker gets three files in the coordination dir:

• task.md — agent-shaped task with required handoff sections (Summary, Files Changed, Validation, Remaining Risks). Generated automatically.
• handoff.md — where the worker writes its output. Watched by the launcher.
• status.md — running / completed / failed marker for monitoring scripts and the future dashboard.

Pairing with the rest of ECC

| Pairs with | How | |---|---| | /devil-mode | Devil-mode is a hardcoded swarm of adversarial agents. Swarm generalizes it to arbitrary specialists. | | Phase 2.4 cost router | Each worker gets the same model-tier recommendation; security/incident workers force hard tier. | | Phase 2.10 token-budget hook | Each worker has its own session token-budget — one rogue worker can't burn the whole budget. | | Phase 2.5 MCP client mode | Workers can call registered external MCP servers (github, postgres, brave). | | kodelyth-memory | Capture the merged handoff bundle as a memory: kodelyth-ecc remember "swarm 2026-05-10 oauth audit" --approach "...". | | release-captain | After a swarm, run release-captain to merge the best work and ship. |

Examples

Pre-launch full sweep (8 agents, parallel)

npx kodelyth-ecc swarm \
  --task "Pre-launch sweep for v2.0 — security, perf, UX, API contracts, docs, tests, release readiness" \
  --agents 8 \
  --replace \
  --execute
Attach when ready:
tmux attach -t swarm-2026-05-10-8a

Production incident: 3-agent parallel triage

npx kodelyth-ecc swarm \
  --task "Production is down. Auth service throwing 502s. Triage and propose fixes." \
  --agents incident-commander,debug-detective,silent-failure-hunter \
  --base-ref main \
  --execute

Refactor sprint with seeded files

npx kodelyth-ecc swarm \
  --task "Refactor the payments module for testability without changing behavior" \
  --agents refactor-cleaner,code-simplifier,type-design-analyzer,tdd-guide \
  --seed src/payments \
  --seed tests/payments \
  --execute

Hard rules

• Never run --execute without inspecting the dry-run first. Worktree creation mutates the repo; bad plans waste disk.
• Don't mix incompatible agents in one swarm. Putting release-captain and migration-guide in the same swarm produces conflicting handoffs.
• Cap N at 8 for a single repo. Worktree contention + tmux pane crowding hurts past 8.
• Never share tmux sessions across swarms. Use --session NAME explicitly when running multiple swarms.
• Always merge handoffs through human review — don't auto-apply changes from N parallel agents without a human pass.

Implementation

• Plan builder: scripts/swarm/build-plan.js (pure function, fully tested).
• Orchestrator: scripts/lib/tmux-worktree-orchestrator.js (the existing infrastructure).
• Worker (codex): scripts/orchestrate-codex-worker.sh.
• CLI: npx kodelyth-ecc swarm.
• Slash command: /swarm.
• Full reference: docs/swarm.md.

Built into Kodelyth ECC. MIT licensed.