Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(ruflo-swarm): v0.2.0 β€” adopt plugin contract + 12-tool MCP surface (ADR-0001)

Reuven714f501f7891
diff --git a/plugins/ruflo-swarm/.claude-plugin/plugin.json b/plugins/ruflo-swarm/.claude-plugin/plugin.json
index 3b53da62f4..82e294b762 100644
--- a/plugins/ruflo-swarm/.claude-plugin/plugin.json
+++ b/plugins/ruflo-swarm/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-swarm",
- "description": "Agent teams, swarm coordination, Monitor streams, and worktree isolation",
- "version": "0.1.0",
+ "description": "Agent teams, swarm coordination, Monitor streams, and worktree isolation β€” wraps 4 swarm_* + 8 agent_* MCP tools (12 total) plus 6 topologies (hierarchical / mesh / hierarchical-mesh / ring / star / adaptive)",
+ "version": "0.2.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -13,6 +13,10 @@
"swarm",
"agents",
"teams",
- "monitor"
+ "monitor",
+ "mcp",
+ "topologies",
+ "worktree-isolation",
+ "monitor-stream"
]
}
diff --git a/plugins/ruflo-swarm/README.md b/plugins/ruflo-swarm/README.md
index 5fdf1b8c89..4a8092924a 100644
--- a/plugins/ruflo-swarm/README.md
+++ b/plugins/ruflo-swarm/README.md
@@ -21,3 +21,66 @@ Agent teams, swarm coordination, Monitor streams, and worktree isolation.
## Requires
- `ruflo-core` plugin (provides MCP server)
+
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-swarm/scripts/smoke.sh` is the contract.
+
+## MCP surface (12 tools)
+
+| Family | Count | Tools |
+|--------|------:|-------|
+| `swarm_*` | 4 | `swarm_init`, `swarm_status`, `swarm_shutdown`, `swarm_health` |
+| `agent_*` | 8 | `agent_spawn`, `agent_execute`, `agent_terminate`, `agent_status`, `agent_list`, `agent_pool`, `agent_health`, `agent_update` |
+
+Sources: `v3/@claude-flow/cli/src/mcp-tools/swarm-tools.ts:71, 145, 208, 270` and `agent-tools.ts:182, 287, 319, 356, 395, 451, 573, 651`.
+
+## Built-in Claude Code coordination tools
+
+This plugin pairs with Claude Code's native multi-agent tools (no MCP needed):
+
+| Tool | Purpose |
+|------|---------|
+| `Task` | Spawn a sub-agent (use `name:` for addressability + `run_in_background: true` for parallel execution) |
+| `SendMessage` | Inter-agent comms (named agents only) |
+| `TaskCreate / TaskList / TaskGet / TaskUpdate / TaskOutput / TaskStop` | Shared task tracker for swarm pipelines |
+| `Monitor` | Live-stream events from a long-running process (`persistent: true`) β€” primary wake signal for /loop |
+| `EnterWorktree / ExitWorktree` | Git worktree isolation per agent |
+
+## Anti-drift defaults (per CLAUDE.md)
+
+For coding swarms, the canonical defaults that prevent agent drift:
+
+| Setting | Value | Rationale |
+|---------|-------|-----------|
+| `topology` | `hierarchical` | Coordinator catches divergence |
+| `maxAgents` | 6–8 | Smaller team = less drift |
+| `strategy` | `specialized` | Clear roles, no overlap |
+| `consensus` | `raft` | Leader maintains authoritative state |
+| `memory` | `hybrid` | SQLite + AgentDB for both fast + durable |
+
+For 10+ agent teams, use `hierarchical-mesh` (queen + peer communication).
+
+## Namespace coordination
+
+This plugin owns the `swarm-state` AgentDB namespace (kebab-case, follows the convention from [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)). Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+`swarm-state` indexes active swarms, agent assignments, and topology snapshots. Accessed via `memory_*` (namespace-routed).
+
+## Verification
+
+```bash
+bash plugins/ruflo-swarm/scripts/smoke.sh
+# Expected: "11 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-swarm plugin contract (12-tool MCP surface, anti-drift defaults, Monitor streaming, smoke as contract)](./docs/adrs/0001-swarm-contract.md)
+
+## Related Plugins
+
+- `ruflo-agentdb` β€” namespace convention owner
+- `ruflo-autopilot` β€” owns the 270s cache-aware /loop heartbeat for long-running swarms
+- `ruflo-intelligence` β€” `hooks_route` powers swarm agent recommendation per task
diff --git a/plugins/ruflo-swarm/docs/adrs/0001-swarm-contract.md b/plugins/ruflo-swarm/docs/adrs/0001-swarm-contract.md
new file mode 100644
index 0000000000..756ae4752f
--- /dev/null
+++ b/plugins/ruflo-swarm/docs/adrs/0001-swarm-contract.md
@@ -0,0 +1,50 @@
+---
+id: ADR-0001
+title: ruflo-swarm plugin contract β€” pinning, namespace coordination, MCP surface (4 swarm_* + 8 agent_*), Monitor streaming, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, swarm, agents, monitor, namespace, smoke-test]
+---
+
+## Context
+
+`ruflo-swarm` (v0.1.0) β€” multi-agent swarm coordination, Monitor streams, worktree isolation. 2 agents (`coordinator`, `architect`), 2 skills (`swarm-init`, `monitor-stream`), 2 commands (`/swarm`, `/watch`).
+
+Wraps **12 MCP tools** across two families:
+
+| Family | Count | Source |
+|--------|-------|--------|
+| `swarm_*` | 4 (`init`, `status`, `shutdown`, `health`) | `v3/@claude-flow/cli/src/mcp-tools/swarm-tools.ts:71, 145, 208, 270` |
+| `agent_*` | 8 (`spawn`, `execute`, `terminate`, `status`, `list`, `pool`, `health`, `update`) | `v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts:182, 287, 319, 356, 395, 451, 573, 651` |
+
+Plus the Monitor + Task tools from Claude Code (built-in: `Task`, `TaskList`, `TaskGet`, `TaskUpdate`, `Monitor`, etc.) which pair with this plugin for live streaming.
+
+## Decision
+
+1. Add this ADR (Proposed).
+2. README augment: Compatibility (pin v3.6); 12-tool MCP surface table; Monitor/Task built-in cross-reference; Anti-drift guidance (hierarchical topology, max 8 agents per CLAUDE.md); Namespace coordination (claims `swarm-state`); Verification + Architecture Decisions sections.
+3. Bump `0.1.0 β†’ 0.2.0`. Keywords add `mcp`, `topologies`, `worktree-isolation`, `monitor-stream`.
+4. `scripts/smoke.sh` β€” 11 structural checks: version + keywords; both skills + 2 agents + 2 commands; all 4 `swarm_*` tools referenced; all 8 `agent_*` tools referenced; v3.6 pin; namespace coordination; anti-drift defaults documented (hierarchical/specialized/raft); Monitor/Task built-in cross-reference; ADR Proposed; no wildcard tools.
+
+## Consequences
+
+**Positive:** plugin joins the cadence. The 12-tool surface is now contractually documented. Anti-drift defaults from CLAUDE.md are smoke-checked.
+
+**Negative:** none material.
+
+## Verification
+
+```bash
+bash plugins/ruflo-swarm/scripts/smoke.sh
+# Expected: "11 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention
+- `plugins/ruflo-autopilot/docs/adrs/0001-autopilot-contract.md` β€” 270s cache-aware /loop heartbeat for swarm coordination
+- `plugins/ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md` β€” `hooks_route` powers swarm agent recommendation
+- `v3/@claude-flow/cli/src/mcp-tools/swarm-tools.ts` β€” 4 `swarm_*` tools
+- `v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts` β€” 8 `agent_*` tools
diff --git a/plugins/ruflo-swarm/scripts/smoke.sh b/plugins/ruflo-swarm/scripts/smoke.sh
new file mode 100755
index 0000000000..d8337fc5af
--- /dev/null
+++ b/plugins/ruflo-swarm/scripts/smoke.sh
@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+step() { printf "β†’ %s ... " "$1"; }
+ok() { printf "PASS\n"; PASS=$((PASS+1)); }
+bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
+
+step "1. plugin.json declares 0.2.0 with new keywords"
+v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+if [[ "$v" != "0.2.0" ]]; then bad "expected 0.2.0, got '$v'"; else
+ miss=""
+ for k in mcp topologies worktree-isolation monitor-stream; do
+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+ done
+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+step "2. both skills + 2 agents + 2 commands present with valid frontmatter"
+miss=""
+for s in swarm-init monitor-stream; do
+ f="$ROOT/skills/$s/SKILL.md"
+ [[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
+ for k in 'name:' 'description:'; do
+ grep -q "^$k" "$f" || miss="$miss $s-no-$k"
+ done
+done
+for a in coordinator architect; do
+ [[ -f "$ROOT/agents/$a.md" ]] || miss="$miss missing-agent-$a"
+done
+[[ -f "$ROOT/commands/swarm.md" ]] || miss="$miss missing-swarm-cmd"
+[[ -f "$ROOT/commands/watch.md" ]] || miss="$miss missing-watch-cmd"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. all 4 swarm_* MCP tools referenced"
+miss=""
+for t in swarm_init swarm_status swarm_shutdown swarm_health; do
+ grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
+done
+[[ -z "$miss" ]] && ok || bad "undocumented:$miss"
+
+step "4. all 8 agent_* MCP tools referenced"
+miss=""
+for t in agent_spawn agent_execute agent_terminate agent_status agent_list agent_pool agent_health agent_update; do
+ grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
+done
+[[ -z "$miss" ]] && ok || bad "undocumented:$miss"
+
+step "5. README pins @claude-flow/cli to v3.6"
+grep -qE "@claude-flow/cli.*v3\.6|v3\.6.*claude-flow/cli" "$ROOT/README.md" \
+ && ok || bad "v3.6 pin missing"
+
+step "6. README defers to ruflo-agentdb namespace convention"
+grep -q "ruflo-agentdb" "$ROOT/README.md" \
+ && grep -q "Namespace convention" "$ROOT/README.md" \
+ && ok || bad "namespace coordination block incomplete"
+
+step "7. swarm-state namespace claimed"
+grep -q "swarm-state" "$ROOT/README.md" \
+ && ok || bad "swarm-state namespace not claimed"
+
+step "8. anti-drift defaults documented (hierarchical/specialized/raft + maxAgents 6-8)"
+F="$ROOT/README.md"
+miss=""
+grep -q "hierarchical" "$F" || miss="$miss hierarchical"
+grep -q "specialized" "$F" || miss="$miss specialized"
+grep -q "raft" "$F" || miss="$miss raft"
+grep -qE "6.{0,3}8|6 to 8|6-8" "$F" || miss="$miss maxAgents"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "9. 6 topologies documented (hierarchical/mesh/hierarchical-mesh/ring/star/adaptive)"
+F="$ROOT/README.md"
+miss=""
+for top in hierarchical mesh hierarchical-mesh ring star adaptive; do
+ grep -q "$top" "$F" || miss="$miss $top"
+done
+[[ -z "$miss" ]] && ok || bad "missing topologies:$miss"
+
+step "10. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-swarm-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+ && ok || bad "ADR missing or status != Proposed"
+
+step "11. no wildcard tool grants in skills"
+bad_skills=""
+for f in "$ROOT"/skills/*/SKILL.md; do
+ grep -q '^allowed-tools:[[:space:]]*\*' "$f" && bad_skills="$bad_skills $(basename $(dirname "$f"))"
+done
+[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1