π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.jsonindex 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.mdindex 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 taskdiff --git a/plugins/ruflo-swarm/docs/adrs/0001-swarm-contract.md b/plugins/ruflo-swarm/docs/adrs/0001-swarm-contract.mdnew file mode 100644index 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_*` toolsdiff --git a/plugins/ruflo-swarm/scripts/smoke.sh b/plugins/ruflo-swarm/scripts/smoke.shnew file mode 100755index 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