mirror of https://github.com/ruvnet/ruflo.git synced 2026-09-14 14:01:28 +08:00

Files

T

Reuven 714f501f78 feat(ruflo-swarm): v0.2.0 — adopt plugin contract + 12-tool MCP surface (ADR-0001)

Plugin already had 2 agents + 2 skills + 2 commands at v0.1.0. The
contract pieces were missing.

Surface inventory (now contractually documented):
- 4 swarm_* tools: init, status, shutdown, health
- 8 agent_* tools: spawn, execute, terminate, status, list, pool,
  health, update
- 6 topologies: hierarchical, mesh, hierarchical-mesh, ring, star,
  adaptive
- Pairs with Claude Code's built-in Task / SendMessage / Monitor /
  EnterWorktree primitives (not MCP, but documented as the integration
  surface)

Anti-drift defaults from CLAUDE.md are now smoke-checked: hierarchical
topology, maxAgents 6-8, specialized strategy, raft consensus.

- ADR-0001 (Proposed) at docs/adrs/0001-swarm-contract.md
- README adds Compatibility (pin v3.6), 12-tool MCP surface table
  (4 swarm_* + 8 agent_*), Built-in Claude Code coordination tools
  table (Task/SendMessage/Monitor/EnterWorktree), Anti-drift defaults
  table (hierarchical/specialized/raft/6-8), Namespace coordination
  (claims swarm-state; defers to ruflo-agentdb ADR-0001),
  Verification + Architecture Decisions
- plugin.json bumps 0.1.0 → 0.2.0; description names the 4+8 = 12
  tool count + 6 topologies; keywords add mcp, topologies,
  worktree-isolation, monitor-stream
- scripts/smoke.sh — 11 structural checks: version + keywords, both
  skills + 2 agents + 2 commands present, all 4 swarm_* tools
  referenced, all 8 agent_* tools referenced, v3.6 pin, namespace
  coordination, swarm-state claimed, anti-drift defaults present,
  6 topologies documented, ADR Proposed, no wildcard tools

Verification: bash plugins/ruflo-swarm/scripts/smoke.sh → 11/11

Co-Authored-By: RuFlo <ruv@ruv.net>

2026-05-04 20:42:24 -04:00

3.5 KiB

Raw Blame History

ruflo-swarm

Agent teams, swarm coordination, Monitor streams, and worktree isolation.

Install

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-swarm@ruflo

What's Included

Agent Teams: TeamCreate, SendMessage, and Task tool integration for multi-agent coordination
Topologies: hierarchical, mesh, hierarchical-mesh, ring, star, adaptive
Monitor Streams: Real-time swarm status via Monitor("npx @claude-flow/cli@latest swarm watch --stream")
Worktree Isolation: Each agent works in its own git worktree to avoid conflicts
Hive-Mind Consensus: Byzantine, Raft, Gossip, CRDT, and Quorum strategies
Anti-Drift: hierarchical topology with specialized strategy for tight coordination

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"). 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 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)

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

3.5 KiB Raw Blame History Unescape Escape