---
name: swarm
description: Launch an agent team from an openteams topology template. Creates a native Claude Code team and spawns all agents directly.
user_invocable: true
argument: optional
---

# /swarm — Launch a Team Topology

You are the **swarm orchestrator** for the claude-code-swarm plugin. Your job is to launch and coordinate an agent team from an openteams YAML topology template using Claude Code's native team features.

**Important**: Only the main agent (you) can spawn teammates. Spawned teammates cannot spawn other teammates — this is a Claude Code limitation. You must act as the orchestrator: spawn all agents, create tasks, and coordinate the team directly.

## What to do

Follow these steps in order. Be efficient — do not debug or retry failed commands, just proceed to the next step.

### Step 1: Locate team artifacts

Check the session init context for **"Team artifacts ready"** — the bootstrap hook pre-loads the configured template and outputs the artifact paths (SKILL.md and agent prompts directory).

If the artifact paths are already shown in the init context, skip to **Step 2** using those paths.

If no artifacts are shown (e.g. the user specified a different template via `$ARGUMENTS`, or no template was configured), generate them:

1. Find the plugin directory from the system init message under `plugins` (look for `claude-code-swarm` and use its `path`). Fallback:
   ```bash
   find ~/.claude/plugins -name "plugin.json" -path "*/claude-code-swarm/*" -exec dirname {} \; 2>/dev/null | head -1 | xargs dirname 2>/dev/null
   ```

2. The template name comes from `$ARGUMENTS` (e.g. `gsd`). If none provided, ask the user. Templates available via openteams: **gsd**, **bmad-method**, **bug-fix-pipeline**, **docs-sync**, **security-audit** (and more).

3. Run the team-loader:
   ```bash
   node "$PLUGIN_DIR/scripts/team-loader.mjs" "<template-name>"
   ```
   The output contains the artifact paths.

### Step 2: Read the generated artifacts

1. Read the **SKILL.md** from the artifact path — this is the team catalog overview (topology, roles, relationships)
2. Read agent prompts from the `agents/` subdirectory (e.g. `agents/<role>.md`) as needed before spawning each role

Use the SKILL.md to understand the topology: which roles exist, the root role, companions, and spawn rules. You don't need to read every agent prompt upfront — read them as needed before spawning each agent.

### Step 3: Create the native team

```
TeamCreate(
  team_name="<template-name>",
  description="<description from SKILL.md>"
)
```

### Step 4: Create tasks based on the user's goal

Break down the user's goal into tasks using `TaskCreate`. Consider the topology's structure:
- Which roles are needed for this goal?
- What's the logical order of work (dependencies)?
- Which tasks can run in parallel?

Create tasks with clear descriptions and set up dependencies with `addBlockedBy` where needed.

### Step 5: Spawn agents and assign tasks

For each role needed, read its agent prompt and spawn it as a teammate:

```
Agent(
  name="<role-name>",
  team_name="<template-name>",
  prompt="<agent prompt content + assigned task context>"
)
```

Spawn agents in parallel where possible (multiple Agent calls in one message). Include in each agent's prompt:
- The content from their `.md` agent file
- Which task(s) they should work on
- Any relevant context from the user's goal

After spawning, assign tasks to agents via `TaskUpdate(owner="<role-name>")`.

### Step 6: Coordinate the team

As the orchestrator, you are responsible for:
- **Monitoring progress** via `TaskList` — check what's completed, what's blocked
- **Spawning additional agents** on demand as new work is identified
- **Relaying information** between agents via `SendMessage` when needed
- **Unblocking work** — if a task is blocked, check if the dependency is met and update accordingly
- **Synthesizing results** — when all tasks are complete, summarize outcomes for the user

Respond to teammate messages as they come in. When teammates finish and go idle, check if there's more work to assign or if the team's goal is met.

### Step 7: Clean up

When all work is complete:
1. Send shutdown requests to all teammates
2. Clean up the team with `TeamDelete`
3. Summarize the results to the user

## Important Notes

- **You are the only agent that can spawn teammates** — do not instruct agents to spawn other agents
- **openteams is config-only** — used only for artifact generation, NOT for runtime coordination
- All agents must be spawned with `team_name` so they share the team's task list
- Start with the most critical roles first — you don't need to spawn all roles from the topology at once
- Keep team size manageable (3-5 agents) — spawn more only when genuinely needed

## Capabilities

Refer to the **Swarm Capabilities** section in the session init context for which tools and integrations are active (task management, memory, communication, observability). The capabilities context is also embedded in each spawned agent's prompt — all agents share the same understanding of available tools.

When creating tasks and coordinating agents, use the task tools described in Swarm Capabilities (opentasks MCP tools if opentasks is enabled, native TaskCreate/TaskUpdate otherwise).

### When minimem is enabled

If memory is active (check init context for "Memory: ready"):
- **Before spawning agents**: Search memory for prior context on the user's goal (`minimem__memory_search`). Include relevant findings in agent prompts when spawning.
- **After team completion**: Store key decisions and outcomes in memory files (`MEMORY.md` for decisions, `memory/<topic>.md` for topic context).
- Tag stored memories with observation types (`<!-- type: decision -->`) and use domain tags relevant to the template (e.g., "gsd", "backend").
- Memory is shared team-wide — all agents can search the same store during execution.

### When skill-tree is enabled

If skills are active (check init context for "Per-Role Skills"):
- Each spawned agent automatically receives a **skill loadout** compiled for their role, embedded in their AGENT.md.
- Loadouts are configured via the `skilltree:` block in team.yaml, or **auto-inferred** from role names (e.g., "executor" → implementation profile, "debugger" → debugging profile).
- You don't need to manage skills — they're baked into agent prompts at generation time.
- Available built-in profiles: code-review, implementation, debugging, security, testing, refactoring, documentation, devops.