<!-- Multi-agent swarm coordination — init, start, status, stop, scale, and coordinate agent teams -->

# Monomind Swarm Coordination

Multi-agent swarm coordination with hierarchical topology, distributed memory, and load balancing.

## Subcommands

| Subcommand | Description |
|---|---|
| `init` | Initialize a new swarm (topology + strategy) |
| `start` | Start swarm execution with an objective |
| `status` | Show current swarm status and progress |
| `stop` | Stop swarm execution |
| `scale` | Scale swarm agent count up or down |

## init — Initialize a Swarm

```bash
# Default (hierarchical, 15 agents)
npx monomind monoswarm init

# Anti-drift configuration (recommended)
npx monomind monoswarm init --topology hierarchical --max-agents 8 --strategy specialized

# v1 15-agent hierarchical-mesh
npx monomind monoswarm init --v1-mode
npx monomind monoswarm init --topology hierarchical-mesh --max-agents 15 --strategy specialized
```

**Flags:**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--topology` | `-t` | `hierarchical` | Swarm topology (see table below) |
| `--max-agents` | `-m` | `15` | Maximum concurrent agents |
| `--strategy` | `-s` | — | Coordination strategy |
| `--auto-scale` | — | `true` | Enable automatic scaling |
| `--v1-mode` | — | `false` | Enable v1 hierarchical-mesh with 15 agents |

## Topologies

| Topology | Use When |
|---|---|
| `hierarchical` | Feature dev, bug fixes — anti-drift, tight control |
| `hierarchical-mesh` | Large teams 10-15 agents — v1 queen + peer communication |
| `mesh` | Research, analysis — broad coverage |
| `star` | Parallel testing, parallel maintenance |
| `ring` | Sequential pipeline processing |
| `hybrid` | Topology label recorded in swarm state; coordination behavior is chosen by the caller — no automatic reconfiguration |

## Strategies

`specialized` (anti-drift, clear roles), `balanced`, `adaptive`, `development`, `research`, `testing`, `optimization`, `maintenance`, `analysis`

## start — Start Swarm Execution

```bash
# Start a development swarm
npx monomind monoswarm start -o "Build REST API with authentication" -s development

# Parallel research swarm
npx monomind monoswarm start -o "Analyze performance bottlenecks" -s research --parallel
```

**Flags:**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--objective` | `-o` | — | Swarm objective/task (required) |
| `--strategy` | `-s` | `development` | Execution strategy |
| `--parallel` | `-p` | `true` | Enable parallel execution |
| `--monitor` | — | `true` | Enable real-time monitoring |

## status — Check Swarm Progress

```bash
# Overall status
npx monomind monoswarm status

# Status for a specific swarm ID
npx monomind monoswarm status swarm-abc123
```

## stop — Stop a Swarm

```bash
# Graceful stop (saves state by default)
npx monomind monoswarm stop swarm-abc123

# Force immediate stop
npx monomind monoswarm stop swarm-abc123 --force
```

**Flags:**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--force` | `-f` | `false` | Force immediate stop |
| `--save-state` | — | `true` | Save state for potential resume |

## scale — Adjust Agent Count

```bash
# Scale to 12 agents
npx monomind monoswarm scale swarm-abc123 --agents 12

# Scale a specific agent type
npx monomind monoswarm scale swarm-abc123 --agents 8 --type coder
```

## MCP Tools

```javascript
// Initialize swarm
mcp__monomind__swarm_init({ topology: "hierarchical", maxAgents: 8, strategy: "specialized" })

// Check status
mcp__monomind__swarm_status({})

// Health check
mcp__monomind__swarm_health({})

// Shutdown swarm
mcp__monomind__swarm_shutdown({})
```

## Agent Team Routing

| Task Type | Agents | Topology |
|---|---|---|
| Bug Fix | coordinator, researcher, coder, tester | hierarchical |
| Feature | coordinator, architect, coder, tester, reviewer | hierarchical |
| Refactor | coordinator, architect, coder, reviewer | hierarchical |
| Performance | coordinator, perf-engineer, coder | hierarchical |
| Security | coordinator, security-architect, auditor | hierarchical |
| Research | coordinator, researcher x4, analyst x2 | mesh |

## See Also

- `npx monomind agent spawn` — Spawn individual agents
- `npx monomind hive-mind init` — Byzantine fault-tolerant consensus
- `/mastermind` — Interactive swarm topology selection

Documentation: https://github.com/monoes/monomind