# Swarm Orchestration

> Swarm Orchestration

- Skill: `elophanto/swarm-orchestration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add elophanto/swarm-orchestration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/elophanto/swarm-orchestration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: elophanto (https://skillmd.com/u/elophanto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/elophanto/swarm-orchestration

---

# Swarm Orchestration

## Description
Best practices for spawning, monitoring, and managing external coding agents
(Claude Code, Codex, Gemini CLI) through conversation.

## Triggers
- swarm
- spawn
- agent
- delegate
- parallel
- coding agent
- claude code
- codex
- gemini cli

## Instructions

### Swarm vs Organization
EloPhanto has two delegation systems. Use the right one:
- **Swarm** (this skill) — for **coding tasks**. Spawns external agents (Claude Code, Codex, Gemini CLI) in isolated git worktrees. One-way communication, ephemeral. Use `swarm_spawn`.
- **Organization** — for **domain work** (marketing, research, design, anything non-coding). Spawns persistent EloPhanto clones with their own identity, knowledge, and autonomous mind. Bidirectional communication, learning from feedback. Use `organization_spawn`.

If the task is code → swarm. If the task is domain expertise → organization.

### When to Spawn Agents
1. **Independent coding tasks** — features, bug fixes, refactors that can be
   described as self-contained assignments with clear acceptance criteria
2. **Parallel work** — multiple tasks that don't depend on each other
3. **Tasks the user wants to delegate** — "have an agent work on X"

### When NOT to Spawn
- Tasks you can do directly with your tools in < 5 steps
- Tasks requiring real-time user interaction or browser access
- Tasks that depend on another agent's output (wait for the first to finish)
- Non-coding domain work (marketing, research, design) — use organization instead

### Writing Good Task Descriptions
The task description is the most important input. A good task:
- States the **what** clearly: "Add pagination to the /api/users endpoint"
- Includes **acceptance criteria**: "Must pass existing tests, add new test for page_size param"
- References **specific files** when possible: "Modify src/routes/users.ts and src/tests/users.test.ts"
- Mentions **constraints**: "Do not change the database schema"

Bad: "Fix the API"
Good: "Fix the 500 error on GET /api/users when page > total_pages. Return empty array instead. Add test case."

### Profile Selection
- Let EloPhanto auto-select unless you have a strong preference
- Auto-selection uses keyword matching against profile `strengths`
- Override with `profile` param when you know which agent is best

### Monitoring Strategy
- Use `swarm_status` to check on agents periodically
- The background monitor handles routine checks (tmux alive, PR created, CI status)
- Check manually when the user asks "how are my agents doing?"

### Redirection
- Use `swarm_redirect` early — don't wait for the agent to go far off track
- Be specific: "Use the existing ConfigSnapshot type from src/types/config.ts"
- Don't redirect for style preferences — save it for the code review

### Anti-Patterns
- **Too many agents at once** — respect max_concurrent_agents, each needs ~3GB RAM
- **Vague tasks** — "improve the codebase" will waste time and tokens
- **Micro-managing** — don't redirect every 2 minutes, let agents work
- **Ignoring failures** — if an agent fails, read the reason before respawning
- **Skipping review** — always review PRs before merging, even if CI passes

## Verify

- The intended other agent / tool / channel actually received the message; an ack, message ID, or response payload is captured
- Identity, scopes, and permissions used by the call were the minimum required; over-permissioned tokens are called out
- Failure handling was exercised: at least one retry/timeout/permission-denied path is shown to behave as designed
- Hand-off context passed to the next actor is complete enough that the receiver could act without a follow-up question
- Any state mutated (config, memory, queue, file) is listed with before/after values, not just 'updated'
- Sensitive material (keys, tokens, PII) was redacted from logs/transcripts shared in the verification evidence