Ruflo Architecture Tour

One-Line Summary: Ruflo (formerly claude-flow) is the most-adopted open-source multi-agent orchestration platform of 2026; it layers on top of Claude Code with 100+ specialized agents, 314 MCP tools, 27 hooks, 32 plugins, queen-led/mesh/adaptive topologies, AgentDB+ReasoningBank memory, federated zero-trust execution, and a SONA-based learning loop.

Prerequisites: What is an AI harness, claude-code-as-harness

What Is Ruflo?

Ruflo, by ruvnet, is the reference orchestration platform for the rest of this course. It is interesting because it is comprehensive — almost every multi-agent concept the course discusses is implemented, named, and configurable in ruflo. The downside of the comprehensiveness is that ruflo's documentation is dense; this concept gives you the architectural tour so the rest of the course can refer to specific ruflo subsystems without re-explaining each one.

Ruflo's elevator pitch: it adds a "nervous system" to Claude Code. Agents self-organize into swarms, learn from past tasks, and remember across sessions. The user keeps writing code in Claude Code; ruflo handles the coordination.

How It's Architected

The high-level diagram:

User → Claude Code / Codex CLI
         │
         ▼
   Orchestration Layer (MCP Server, Router, 27 Hooks)
         │
         ▼
   Swarm Coordinator (Queen / Topology / Consensus)
         │
         ▼
   100+ Specialized Agents (coder, tester, reviewer, security, …)
         │
         ▼
   Memory & Learning (AgentDB, HNSW, SONA, ReasoningBank)
         │
         ▼
   LLM Providers (Claude, GPT, Gemini, Cohere, Ollama)

Concretely, that decomposes into:

ruflo-core — the orchestration entry point, plus health checks, plugin discovery, foundation utilities.
Router — directs incoming tasks to appropriate agents (claimed 89% routing accuracy).
Swarm Coordinator — manages a swarm, applying a topology and consensus rule.
Memory subsystem — AgentDB (HNSW vector DB) + knowledge graphs.
Learning engine — SONA (self-learning patterns), ReasoningBank, trajectory analysis.
Federation layer — cross-machine collaboration with zero-trust security (mTLS + ed25519 + behavioral trust scoring).
Worker pool — 12 background workers (audit, optimize, testgaps, dependency-scan, …).
Policy / security pipeline — input validation, CVE scanning, PII gating across 14 PII types, prompt-injection defense (AIDefence).

Why It Matters

Two reasons. First, ruflo is the most concrete reference for harness-level multi-agent patterns. Pointing at ruflo-loop-workers or ruflo-aidefence is shorter than hand-waving about hypothetical implementations. Second, ruflo is the pragmatic choice when a team needs orchestration today — it is open-source, packageable as Claude Code plugins, and has a marketplace of pre-built agents and workflows.

Key Technical Details

Plugin model: 32 native plugins (e.g., ruflo-core, ruflo-swarm, ruflo-autopilot, ruflo-loop-workers, ruflo-workflows, ruflo-federation, ruflo-rag-memory, ruflo-knowledge-graph, ruflo-intelligence, ruflo-goals, ruflo-aidefence, ruflo-sparc).
Topologies: Queen-led (one orchestrator, many workers), mesh, hive mind, adaptive (runtime-switched).
Consensus: Raft, Byzantine, gossip — selectable per swarm.
Federation trust pipeline: PII strip → ed25519 sign → mTLS verify → behavioral trust evaluate → privilege adjust.
Background workers: 12 auto-triggered, each with its own goal and budget.
GOAP planner: A* search over annotated actions, with adaptive replanning.
Reported metrics (May 2026): 84.8% solve rate on SWE-bench, 75% claimed cost savings vs raw Claude Code.
Methodology plugins: ruflo-sparc (Specification, Pseudocode, Architecture, Refinement, Code), ruflo-adr, ruflo-ddd — encode whole engineering methodologies as agent workflows.

How Harnesses & Frameworks Implement This

Concern	Ruflo's choice	Closest equivalent in another harness
Topology	Queen-led default, multi-mode	Claude Code: supervisor sub-agents only
Memory	AgentDB + ReasoningBank + SONA	LangGraph: checkpointers; Claude Code: `CLAUDE.md`
Federation	mTLS + ed25519 zero-trust	None standard; mostly DIY
Learning	Trajectory + LoRA adapters	None standard
Background workers	12 first-class workers	Claude Code: DIY via `SessionStart` hooks

Connections to Other Concepts

what-is-an-ai-harness.md — The category. Ruflo is positioned as a harness atop a harness.
queen-led-hierarchy.md, hive-mind-pattern.md, adaptive-topology-switching.md — Ruflo's signature topologies.
reasoning-bank.md, sona-self-learning-neural-patterns.md, agentdb-and-vector-stores-in-harnesses.md — Memory subsystems.
cross-machine-agent-federation.md, mtls-and-ed25519-for-agent-trust.md, behavioral-trust-scoring.md — Federation primitives.
methodology-as-plugin-sparc.md, methodology-as-plugin-adr-and-ddd.md — Methodology plugins.