flow-swarm

What this skill does

# FlowSwarm v2.1

Multi-agent swarm orchestration for Claude Code via RuFlo. One prompt, coordinated agents, production results.

## What Changed in v2.1

Critical fix: **MCP tools were disabled** (`autoStart: false`). This prevented Claude Code from calling `mcp__claude-flow__swarm_init`, `memory_store`, `agent_spawn`, etc. during every swarm run we'd done so far. Fixed.

Also fixed: `--print` mode **does not** auto-discover `.mcp.json`. You must pass `--mcp-config .mcp.json` explicitly.

| Change | Why |
|---|---|
| `autoStart: true` in `.mcp.json` | Was `false` — all 150+ MCP tools were disabled in every prior run |
| `--mcp-config .mcp.json` flag added to exec pattern | `--print` doesn't auto-load project MCP config |
| MCP tool reference table added | 150+ tools now documented: swarm_init, agent_spawn, memory_store, etc. |
| Prompt templates updated to call MCP tools | Without explicit instructions, Claude may not use them |
| Setup script auto-fixes autoStart | `ruflo init` defaults to false; setup script corrects it |

## What Changed in v2.0

v1.0 was theory. v2.0 is battle-tested across 5 production runs (355 tests, 5/5 green, 4/5 zero-iteration).

| Change | Why |
|---|---|
| Tiered task routing replaces one-size-fits-all | Pure-data modules don't need GenServer test isolation advice |
| Target selection protocol added | Picking the RIGHT module matters more than swarm config |
| Pre-flight context injection | Feeding the swarm grep output of public functions = dramatically better coverage |
| Daemon reality check | Workers timeout/fail often (20-50% success); swarm value comes from prompt orchestration, not daemon workers |
| Removed WASM Booster claims | Never observed in practice; hooks + prompt patterns drive all real value |
| Real performance data | Actual timing, test counts, iteration rates from production runs |

## Architecture

Two layers working together:

**Layer 1: MCP Tools (150+ tools via @claude-flow/cli)**
When `autoStart: true` in `.mcp.json`, Claude Code gets access to real coordination tools:
- `swarm_init` — creates swarm with topology, persists to `.claude-flow/swarm/swarm-state.json`
- `agent_spawn` — registers agents with model routing (haiku/sonnet/opus/inherit)
- `memory_store` / `memory_search` — sql.js + HNSW vector embeddings for semantic recall
- `task_create` / `task_complete` — tracks task state with assignment
- `session_save` / `session_restore` — persists session state between runs
- `claims_claim` / `claims_release` — prevents agents from editing same files
- `coordination_consensus` — multi-agent agreement on decisions

**Layer 2: Prompt Orchestration (our FlowSwarm patterns)**
The SWARM MODE prefix causes Claude Code to think in roles (architect/coder/reviewer). Combined with pre-flight context injection (grepping public APIs), this produces 80% zero-iteration success.

**Both layers matter.** v1.0 had Layer 2 only (autoStart was false, MCP tools never loaded). v2.0 enables both.

```
OpenClaw → exec (background) → Claude Code
                                    ↓
                    MCP Server starts (autoStart: true)
                    150+ tools available via @claude-flow/cli
                                    ↓
                    SWARM MODE prompt → swarm_init tool called
                    agent_spawn × N → task_create → execute
                                    ↓
                    memory_store (findings) → task_complete
                                    ↓
                              Output + persisted state
```

## Prerequisites

```bash
ruflo --version    # 3.5.x+
claude --version   # Claude Code CLI
```

## Setup (One-Time Per Machine)

```bash
# Full setup: install RuFlo + register MCP + init project
./scripts/setup-flow-swarm.sh /path/to/project

# Verify
./scripts/setup-flow-swarm.sh --verify /path/to/project
```

Or manually:
```bash
npm install -g ruflo@latest
claude mcp add ruflo -- npx -y ruflo@latest mcp start
cd /path/to/project && ruflo init && ruflo memory init && ruflo daemon start
```

## CRITICAL: Enable MCP Server

After `ruflo init`, the `.mcp.json` file defaults to `autoStart: false`. This disables ALL 150+ MCP tools during Claude Code sessions. Fix it:

```bash
# Check current state
python3 -c "import json; d=json.load(open('.mcp.json')); print('autoStart:', d['mcpServers']['claude-flow'].get('autoStart'))"

# Enable (REQUIRED for full swarm functionality)
python3 -c "
import json
with open('.mcp.json') as f: d = json.load(f)
d['mcpServers']['claude-flow']['autoStart'] = True
with open('.mcp.json', 'w') as f: json.dump(d, f, indent=2)
print('MCP autoStart enabled')
"
```

Without this, Claude Code runs without swarm tools. The prompt patterns still work (v1.0 proved this), but you lose: persistent swarm state, agent memory, task tracking, session persistence, and inter-agent coordination.

## The FlowSwarm Protocol (3 Steps)

### Step 1: Select Your Target

**This is the highest-leverage decision.** Pick wrong and you waste a swarm run.

Best targets (in order):
1. **Large modules with zero tests** — highest ROI, swarm excels here
2. **Pure data/logic modules** — no IO mocking needed, near-100% first-pass success
3. **Modules with thin test coverage** — swarm fills gaps the original author skipped
4. **Feature builds with clear specs** — architect/coder/reviewer shines on greenfield

Find targets fast:
```bash
# List untested modules by size (biggest = best target)
for f in lib/**/*.ex; do
  base=$(basename "$f" .ex)
  count=$(find test/ -name "${base}_test.exs" 2>/dev/null | wc -l | tr -d ' ')
  [ "$count" = "0" ] && echo "$(wc -l < "$f")L $f"
done | sort -rn | head -10
```

### Step 2: Build the Prompt (Context-Rich)

The secret sauce: **feed the swarm a pre-flight scan** of the module. Don't just say "test this file" — tell it exactly what functions exist, what patterns the project uses, what edge cases matter.

```bash
# Pre-flight: scan public API
grep -n "^  def " lib/your_module.ex
# Pre-flight: check existing test patterns
head -30 test/some_existing_test.exs
```

Then build the prompt with that intel baked in.

### Step 3: Launch and Verify

```bash
# Launch (ALWAYS background, NEVER nohup)
exec(
  command='cd /project && claude --permission-mode bypassPermissions --mcp-config .mcp.json --print "SWARM MODE: ... TASK: ..."',
  background=True,
  timeout=300
)

# Poll for completion
process(action="poll", sessionId="xxx", timeout=120000)

# Verify the output actually compiles/passes
mix test test/path/to/new_test.exs
```

**Critical exec rules:**
- `--print` buffers ALL output until exit. Use `background: true` + poll.
- NEVER use `nohup` — Node.js stdout capture breaks silently (empty files).
- Timeout 300s minimum for complex tasks. Simple test gen: 60-120s.
- Always run `mix test` (or equivalent) on swarm output before committing.

## Prompt Templates (Battle-Tested)

### Test Generation — Pure Data Module
**Proven: 147/147, 66/66, 41/41 zero-iteration**

Best for: static catalogs, type definitions, translation modules, config builders.

```
SWARM MODE: Initialize hierarchical swarm with MCP tools.

COORDINATION:
1. Call swarm_init with topology "hierarchical", maxAgents 4, strategy "specialized"
2. Call agent_spawn for: architect (analyze module), coder (write tests), reviewer (verify)
3. Call task_create for the test generation task
4. After completion: call memory_store with key findings and task_complete

TASK: Write comprehensive ExUnit tests for [MODULE_PATH] ([LINE_COUNT] lines, [DESCRIPTION]).

Public API:
[PASTE grep -n "^  def " output here]

Key data to validate:
- [List specific assertions: required struct keys, value ranges, URL formats, etc.]
- [List known edge cases: unknown inputs, nil, empty string, integer where string expected]

Requirements:
- File: test/[matching_path]_test.exs
- Use async: true (pure functions, no state)
- Group tests by function (describe blocks)
- Test ALL variants, not just a sample (e.g., all 8 hotels, not jus