swarm

name	swarm
description	Launch a Codex agent team from an openteams YAML topology. Accepts a topology name (e.g. "gsd", "bmad-method") or path to a custom YAML topology, generates role artifacts, and coordinates the team through opentasks (shared task graph) and agent-inbox (inter-agent messaging).

swarm

Use this skill when the user types /swarm or asks to launch a swarm, agent team, or multi-agent workflow.

Usage

/swarm <topology>

<topology> is one of:

• A built-in template name: gsd (Get Shit Done: 12 roles, wave-based parallel) or bmad-method (10 roles, agile phases).
• A path to a custom openteams YAML topology file.

If no argument is given, fall back to the value of template in .swarm/codex-swarm/config.json (or SWARM_TEMPLATE env var).

Procedure

1. Resolve the topology:

   • If the argument matches a built-in name (gsd, bmad-method), pass it through as-is — swarm-codex run resolves built-in names against openteams' template catalog.
   • Otherwise treat the argument as a filesystem path.
   • On miss, list the available built-in topologies and ask the user to pick one.

2. Run swarm-codex run <topology> to launch the full swarm. This:

   • Loads the template and derives a wave execution schedule from spawn_rules.
   • Generates per-role prompt artifacts under .swarm/codex-swarm/tmp/teams/<template>/.
   • Starts the coordination plane (opentasks, agent-inbox, MAP if configured).
   • Spawns a codex mcp-server process and starts roles wave-by-wave via the codex MCP tool.
   • Streams NDJSON progress events to stdout (run.init, wave.start, role.start, role.done, wave.done, run.done, and more).

3. Relay progress events to the user as roles spawn and complete. The NDJSON stream contains event types including:

   • run.init — run started with topology name and runId
   • run.plan — schedule derived: roleCount, waveCount, wave→role mapping
   • run.coord — coordination plane ready (opentasks, inbox, MAP status)
   • wave.start / wave.done — wave lifecycle with role list
   • role.start / role.done — individual role lifecycle
   • role.error — role failure with error message
   • signal.emitted / message.delivered / message.buffered — signal emission and peer-message routing
   • run.terminal — the terminal condition that ended the run
   • run.done — final summary with per-role pass/fail
   • run.error — fatal run error

   The set is not closed — relay any event by its type field rather than assuming a fixed list.

4. On run.done, summarize what each role produced. On error, report which roles failed.

5. Use swarm-codex status [run-id] to check on a previous or in-progress run.

Configuration

Resolution order (highest priority first):

1. Environment variables prefixed SWARM_* (e.g. SWARM_TEMPLATE).
2. Project config at .swarm/codex-swarm/config.json.
3. Global config at ~/.swarm-codex/config.json.

Notes

• Topology format mirrors openteams: top-level keys are roles, root, spawn_rules, communication.
• Generated role artifacts are cached by template name so switching templates is cheap.
• The MAP (Multi-Agent Protocol) integration is optional; when it is disabled the run still emits its full NDJSON event stream and writes a per-run events.jsonl.