Related Pages

Related topics: Memory, Learning, and Intelligence Subsystem, Multi-Agent Coordination, Federation, and Security, Plugin Ecosystem and Operational Concerns

Ruflo Overview and Core Architecture

Purpose and Scope

Ruflo is an AI agent orchestration platform distributed as a marketplace of Claude Code plugins under the @claude-flow namespace. Its purpose is to give Claude Code (and the related Codex CLI) a persistent, self-learning substrate — vector memory, an MCP server with 300+ tools, hooks for tool routing, and a catalog of 30+ specialized plugins spanning goal planning, SPARC methodology, security, trading, and IoT. Source: plugins/ruflo-core/README.md:1-15

The project is shipped under the @alpha npm tag, which the maintainers use as an explicit signal that the codebase is being built publicly in real time rather than as a stable release. Package metadata records the author as RuvNet <[email protected]>, license MIT, and engines requiring node >= 20.0.0. Source: v3/@claude-flow/cli/package.json:1-30, package.json

Layered Architecture

Ruflo is organized as four logical layers, each backed by concrete files in the repository:

flowchart TB
    UI["Goal UI / Dashboard<br/>(v3/goal_ui)"]
    CLI["CLI surface<br/>(v3/@claude-flow/cli)"]
    MCP["MCP server<br/>(ruflo-core, 300+ tools)"]
    Plugins["30+ plugins<br/>(ruflo-swarm, ruflo-rag-memory,<br/>ruflo-testgen, ruflo-adr, ...)"]
    Sub["Substrate: AgentDB + ONNX embeddings<br/>(ruflo-agentdb, ruflo-ruvector)"]
    UI --> CLI --> MCP --> Plugins --> Sub

1. CLI layer. The @claude-flow/cli package is the executable surface (bin entry, dist/src/index.js) and exports sub-paths for ruvector, mcp-tools, memory, and intelligence modules. Source: v3/@claude-flow/cli/package.json:25-65
2. MCP server. The ruflo-core plugin registers the MCP server that exposes memory, agentdb, embeddings, hooks, neural, autopilot, browser, aidefence, agent, swarm, system, terminal, github, daa, coordination, performance, and workflow tools. Source: plugins/ruflo-core/README.md:5-25
3. Plugin layer. Each plugin follows the same shape: a manifest plus agents, skills, and subcommands. Examples include ruflo-sparc (5-phase lifecycle), ruflo-ddd (bounded contexts), ruflo-adr (decision records), ruflo-knowledge-graph (entity extraction), and ruflo-loop-workers (12 background workers). Source: plugins/ruflo-sparc/README.md, plugins/ruflo-ddd/README.md, plugins/ruflo-adr/README.md, plugins/ruflo-knowledge-graph/README.md, plugins/ruflo-loop-workers/README.md
4. Substrate. AgentDB and the @ruvector family provide vector storage, HNSW search, and embeddings. The neural_*, hooks_intelligence_*, and routing families wrap 29 intelligence tools into the RETRIEVE → JUDGE → DISTILL → CONSOLIDATE pipeline. Source: plugins/ruflo-intelligence/README.md

The Codex path mirrors the Claude Code path: init --codex auto-registers the claude-flow MCP server, and 137+ skills are invokable with $skill-name syntax. Source: v3/@claude-flow/codex/README.md

Core Plugin Contract

ruflo-core is the foundation: it provides the MCP server, three generalist agents (coder, researcher, reviewer), the init-project, ruflo-doctor, and discover-plugins helpers, plus the per-plugin hook loader at plugins/ruflo-core/hooks/hooks.json. The per-plugin layout is what fixed the legacy marketplace-root loading issue #1748. Source: plugins/ruflo-core/README.md:5-30

Plugin Ecosystem

The repository ships 30+ plugins. The catalog in plugins/README.md groups them into broad categories: foundation (ruflo-core), workflow (ruflo-sparc, ruflo-adr, ruflo-ddd, ruflo-swarm, ruflo-testgen), memory and RAG (ruflo-rag-memory, ruflo-agentdb, ruflo-ruvector, ruflo-knowledge-graph), and domain-specific (ruflo-goals, ruflo-iot-cognitum, ruflo-neural-trader, ruflo-market-data). Several plugins wrap standalone npm packages for deeper functionality — for example, ruflo-neural-trader wraps neural-trader and exposes 112+ MCP tools. Source: plugins/README.md:30-90

The catalog publishes curated "Recommended Stacks" so users do not need to assemble combinations from scratch: feature development is served by ruflo-core + ruflo-swarm + ruflo-testgen + ruflo-ddd; security audits by ruflo-core + ruflo-security-audit + ruflo-aidefence; architecture work by ruflo-core + ruflo-adr + ruflo-ddd + ruflo-sparc; deep research by ruflo-core + ruflo-goals + ruflo-rag-memory + ruflo-intelligence; and vector search by ruflo-core + ruflo-ruvector + ruflo-rag-memory + ruflo-knowledge-graph. Source: plugins/README.md:60-90

Every plugin uses the same contract: pinned to @claude-flow/cli v3.6 major+minor, with bash plugins/<name>/scripts/smoke.sh as the verification step. Source: plugins/ruflo-docs/README.md, plugins/ruflo-intelligence/README.md

Known Operational Issues and Architecture Pressure Points

The community has surfaced a number of issues that are best understood as architecture-level signals, not one-off bugs:

• Daemons and process lifecycle. A long-running macOS session accumulated 39 zombie node … daemon start processes spawned by init.ts:424 racing the PID-file dedup; fixed in v3.12.2 with an atomic O_EXCL lockfile. Source: issue #2407, release v3.12.2.
• Embeddings and the MCP path. The MCP memory_store tool emitted 128-dim mock embeddings because the AgentDB vectorBackend controller never flipped to enabled: true; fixed in v3.12.3. The issue is a useful reminder that the standalone CLI and the in-session MCP path share code unevenly. Source: issue #2395, release v3.12.3.
• Cold-start latency. The CLI initialized the ONNX embedder unconditionally on every startup, so even --version could hang >60s on a cold install. Source: issue #2286.
• Subcommand stubs. security cve is a stub that prints "No CVE database configured" regardless of project state, while security scan (which uses npm audit) does return real data. Prefer scan until the stub is implemented. Source: issue #2403.
• Witness manifests and supply chain. The 12-hour verification run reports missing=95 drift=2 across all three platforms because the compiled dist/ artifacts are not present in the source tree; Ed25519 signatures are valid but the artifacts themselves are missing. The v3-ci.yml "Run supply-chain audit" job on main is currently failing. Source: issues #2047, #2391, #2412.
• Dream-cycle ADR drift. The Dream Cycle scheduled tasking tracks new architectural decisions in real time — ADR-153 (@metaharness/darwin integration), bi-temporal HNSW gap analysis (Engram +10.4pp on LongMemEval_S), and an OPD-Evolver vs ReasoningBank result (+11.5%). Source: issue #2410, ADR-153 (issue #2409).

For contributors, the recommended entry points are ruflo-core (foundation), ruflo-swarm (multi-agent orchestration), ruflo-adr (governance), and ruflo-testgen (the v3.14.0 release adds test-driven repair via headless claude -p). Source: release v3.14.0.

See Also

• ruflo-core — Foundation plugin and MCP server
• ruflo-intelligence — Self-learning pipeline
• ruflo-sparc — Five-phase methodology
• ruflo-adr — Architecture Decision Records
• Plugin catalog (plugins/README.md)
• CLI reference (v3/@claude-flow/cli)

Related Pages

Related topics: Ruflo Overview and Core Architecture, Multi-Agent Coordination, Federation, and Security

Memory, Learning, and Intelligence Subsystem

The Memory, Learning, and Intelligence (MLI) Subsystem is the cognitive core of ruflo (Claude Flow v3). It is responsible for persistent storage of agent state, semantic retrieval over historical patterns, online learning from observed outcomes, and cross-domain reasoning across code, knowledge graphs, and hyperbolic hierarchies. The subsystem is exposed as both MCP tools and CLI subcommands, and is composed of multiple pluggable backends coordinated through the shared @claude-flow/memory module.

Architecture and Storage Backends

The subsystem is organized around a single canonical MemoryService (ADR-006) that abstracts three backends selected at runtime: SQLite for transactional durability, AgentDB for vector-first workloads, and a Hybrid mode that combines both. The default deployment is Hybrid, which is treated as the production baseline. Source: v3/implementation/adrs/README.md:45-55.

The package layout follows Domain-Driven Design (ADR-002) with the v3/@claude-flow/memory workspace exposing dedicated entry points for memory-initializer, intelligence, and shared types. The CLI re-exports these as ./memory and ./intelligence subpath exports so that downstream consumers can import the same modules used by the daemon. Source: v3/@claude-flow/cli/package.json:60-78.

flowchart LR
  A[Agent / CLI / MCP] --> B[MemoryService]
  B --> C[SQLite Backend]
  B --> D[AgentDB Backend]
  B --> E[Hybrid Backend]
  D --> F[HNSW Index]
  D --> G[ONNX Embedder 384-dim]
  B --> H[Smart Retrieval ADR-090]
  H --> I[RRF + MMR + Recency]
  B --> J[SONA / Neural Learning]
  B --> K[Event Sourcing ADR-007]

Vector Embeddings and Semantic Search

All semantic operations rely on a 384-dimensional embedding space produced by an ONNX model (all-MiniLM-L6-v2 family). HNSW indexes accelerate approximate nearest-neighbor search by 150x to 12,500x versus brute force. Source: v3/@claude-flow/codex/README.md:8-16.

When the ONNX embedder cannot be initialized, the system falls back to a 128-dimensional hash-derived mock embedding. This fallback path is the source of a known data-quality regression: the MCP memory_store tool persisted 128-dim mock vectors instead of the real 384-dim vectors because the AgentDB vectorBackend controller never flipped to enabled: true. The issue was fixed in v3.12.3 by routing MCP traffic through the same initializer the standalone CLI uses. Source: community issue #2395, v3.12.3 release notes.

A related cold-start performance issue (#2286) showed that the ONNX model was downloaded unconditionally on every CLI startup, causing npx @claude-flow/cli@alpha --version to hang for more than 60 seconds. The fix is to defer model initialization until the first embedding request rather than the first command parse. Source: community issue #2286.

Smart Retrieval and Learning Loops

The flagship retrieval pipeline, SmartRetrieval (ADR-090), runs a five-phase sequence over every memory query:

1. Query expansion via template variants (no LLM call)
2. Multi-query fan-out fused with Reciprocal Rank Fusion
3. Recency boost using exponential decay on metadata timestamps
4. Maximal Marginal Relevance re-ranking with token-Jaccard diversity
5. Session round-robin interleaving so results span distinct sessions

It is invoked through memory_search --smart or mcp__claude-flow__memory_search({ smart: true }). Source: plugins/ruflo-rag-memory/README.md:46-66.

The intelligence layer adds pattern learning on top of retrieval. It persists successful strategies under the patterns namespace and bridges Claude Code's native ~/.claude/projects/*/memory/*.md files into the same store with ONNX vectors, attributing each entry to claude-code, auto-memory, or agentdb. Source: plugins/ruflo-rag-memory/README.md:18-44.

Online adaptation is driven by SONA (Self-Optimizing Network Architecture), referenced in both the code-intelligence plugin and the Codex integration. SONA consumes task outcomes to retrain LoRA adapters and to refine the routing policy used by the UnifiedSwarmCoordinator. Source: v3/plugins/code-intelligence/README.md:23-31, v3/@claude-flow/codex/README.md:8-16.

Cross-Domain Reasoning Plugins

The MLI subsystem is intentionally extensible through plugins. The knowledge-graph plugin (graph-navigator agent) extracts entities and relations from source code and runs pathfinder traversal scored by edge weight and semantic similarity. Source: plugins/ruflo-knowledge-graph/README.md:4-12.

The hyperbolic-reasoning plugin models hierarchy with negative-curvature embeddings (curvature -2.0 for taxonomies), enabling efficient traversal of deep tree structures such as ontology navigation, code inheritance, and organizational analysis. It composes with the neural-coordination and cognitive-kernel plugins for hierarchical agent organization. Source: v3/plugins/hyperbolic-reasoning/README.md:1-30.

The prime-radiant plugin adds causal and spectral reasoning on top of stored memories via hooks like pr/pre-memory-store and pr/post-swarm-task, which validate that new entries are coherent with the existing graph. Source: v3/plugins/prime-radiant/README.md:36-54.

Population-based harness self-improvement is delegated to @metaharness/darwin (ADR-153, tracking issue #2409), which evaluates candidate harnesses against a graded rubric (harnessFit, compileConfidence, taskCoverage, risk_score). Each skill shells out via npx metaharness … with a 60-second hard timeout, so a missing package produces degraded JSON rather than a boot failure. Source: plugins/ruflo-metaharness/README.md:22-44, community issue #2409.

Known Failure Modes

Source: community issues #2395, #2286, #2403, #2410.

See Also

• ADR-006 — Single MemoryService with SQLite, AgentDB, or Hybrid backends
• ADR-007 — Event sourcing for audit trail and state reconstruction
• ADR-009 — Hybrid backend as default for best performance
• ADR-090 — SmartRetrieval pipeline
• ADR-153 — @metaharness/darwin integration
• v3.12.2 / v3.12.3 release notes for hotfix lineage

Related Pages

Related topics: Ruflo Overview and Core Architecture, Memory, Learning, and Intelligence Subsystem, Plugin Ecosystem and Operational Concerns

Multi-Agent Coordination, Federation, and Security

Overview

Ruflo (Claude-Flow v3) is an agentic AI orchestration platform whose coordination model, federation surface, and security guarantees are defined in three interlocking layers: a 15-agent hierarchical mesh built around a queen-led coordination pattern, a plugin-based microkernel that exposes federation and claims primitives as first-class extension points, and a defense-in-depth security model spanning the CLI, the MCP surface, and plugin sandboxes. The platform is published as @claude-flow/cli with the v3alpha distribution tag and exposes dedicated entry points for memory, MCP tools, and an intelligence subsystem (v3/@claude-flow/cli/package.json). The top-level ruflo package meta enumerates agent-orchestration, swarm-intelligence, mcp, model-context-protocol, and self-learning as the core capabilities (ruflo/package.json).

This page documents the public, source-visible behavior of these three layers. Where the code is silent, the page is silent too.

Multi-Agent Coordination

The coordination layer is organized as a queen-led hierarchical mesh of 15 specialized worker agents, chosen over a flat mesh in the v3 architecture assessment (v3/README.md). The Queen agent does not perform domain work itself; it brokers tasks, maintains global state, and arbitrates conflicts. Specialized workers carry out bounded, typed tasks. Bounded contexts are isolated using Domain-Driven Design boundaries, and the Plugin Architecture is implemented as a microkernel in which the plugin loader, registry, and lifecycle manager are the only fixed components (v3/implementation/plugins/README.md). The plugin contract exposes extension points for custom agent types, task types, MCP tools, CLI commands, and memory backends.

graph TD
  Q[Queen Coordinator]
  Q --> W1[Worker: researcher]
  Q --> W2[Worker: coder]
  Q --> W3[Worker: tester]
  Q --> W4[Worker: reviewer]
  Q --> W5[Worker: security-review]
  Q --> M[Memory: SQLite + AgentDB]
  Q --> E[Event Bus]
  Q --> MK[Microkernel / Plugin Registry]
  MK --> P1[Plugin: SPARC]
  MK --> P2[Plugin: cost-tracker]
  MK --> P3[Plugin: knowledge-graph]
  MK --> P4[Plugin: hyperbolic-reasoning]
  E --> C[Claims-based Authorization]
  C --> W1
  C --> W2
  C --> W3

Coordination is mediated through an MCP-first API so every agent surface, memory operation, and tool call uses the same wire protocol (v3/README.md). State changes are persisted as an event-sourced audit trail, and a hybrid memory backend combining SQLite and AgentDB backs the worker mesh. The published performance envelope for the v3 event bus is approximately 6 ms for 100k events and a Map lookup budget of ~16 ms per 100k gets, with HNSW-indexed AgentDB search reported at 150x–12,500x speedups (v3/README.md). The plugins package depends on ruvector and agentdb for vector search, and advertises HNSW, LoRA, and neural adaptation as first-class keywords (v3/@claude-flow/plugins/package.json).

A goal-facing UI is layered on top of this mesh in v3/goal_ui/. It applies Goal-Oriented Action Planning (GOAP) as an A* search over actions with explicit preconditions and effects, replans on failure rather than restarting, and exposes a live /agents dashboard plus a collapsible plan tree (v3/goal_ui/README.md). Browser-bound work runs through @claude-flow/browser, which contributes 59 MCP browser tools, AI-optimized snapshots (93% context reduction via element refs), and swarm coordination for parallel multi-session scraping, testing, and validation (v3/@claude-flow/browser/README.md).

Federation

Federation is treated as a first-class runtime concept, not a marketing term. The cost-tracker plugin ships a dedicated cost-federation HTTP endpoint that serves per-peer rolling windows of federation_spend at 1h / 24h / 7d resolution; the endpoint is documented as the ADR-097 Phase 3 consumer (plugins/ruflo-cost-tracker/README.md). The same plugin exposes /cost-summary as a stable JSON contract for inter-plugin consumption, and /cost-compact-context as a retrieval-compacted query interface that degrades gracefully when agentic-flow is not installed.

A second federation surface is the claims-based authorization subsystem surfaced through the claims CLI command group. Its subcommands — list, check, grant, revoke, roles, and policies — provide the policy layer that gates cross-peer work and remote tool invocation (v3/implementation/adrs/README.md). The v3 optimization roadmap describes a port of a Federation Hub, ephemeral agents with finite lifetimes, and a proxy server for provider fan-out as Phase 2 integration work, with federation start --port 9443 and federation spawn --lifetime 300 --task "..." listed as target interfaces (v3/implementation/adrs/README.md). Until those land in a release, the only federation endpoints that are observably wired in source are the cost-tracker ones, plus the claims surface.

The Codex integration adds a platform-portable federation point: when init --codex runs, the MCP server is automatically registered against the host runtime (codex mcp list should show claude-flow as enabled), and the Codex path uses the same memory_search / memory_store MCP tools as the Claude Code path (v3/@claude-flow/codex/README.md). Hyperbolic HNSW reasoning contributes a hierarchical substrate for federation: deep hierarchies are mapped to high-curvature embeddings, flat graphs to low curvature, and the system is used for ontology navigation, code-hierarchy understanding, and organizational analysis (v3/plugins/hyperbolic-reasoning/README.md).

Security Model

The v3 security posture is layered. At the platform boundary, the README states: CVE remediation for known vulnerabilities, Zod-based input validation for typed schemas, cryptographic random IDs, path traversal protection, and parameterized SQL queries for injection prevention (v3/README.md). The security namespace is exposed via a doctor subcommand that audits Node version, config, daemon, memory, API keys, MCP, and disk state, and a security cve subcommand exists; community evidence indicates security cve is currently a stub that prints "No CVE database configured" and exits, while security scan does run npm audit (community: #2403).

The @claude-flow/browser package contributes a security-first adapter in front of every agent-driven browser action. The flow is Agent Request → Security Scan → Browser Adapter → agent-browser CLI → Playwright, and the security scan enforces URL validation, phishing detection, PII scanning, XSS / SQL injection prevention, and a configurable domain block list (v3/@claude-flow/browser/README.md). Sandboxed plugins such as legal-contracts define their own hardening envelope: a 2 GB memory cap, 120-second CPU ceiling, no network access, sandboxed file-system paths, and per-matter isolation to prevent cross-matter data leakage, all enforced alongside per-tool rate limits (v3/plugins/legal-contracts/README.md).

Operational hardening has been a focus of recent releases. The v3.12.2 release notes document a CRITICAL daemon-proliferation fix that introduced an atomic O_EXCL lockfile in daemon.ts and removed the shell & from init.ts:424, with a race test confirming that 5 concurrent daemon start invocations now produce a single surviving daemon rather than 3–5+ (community: v3.12.2). v3.12.3 closed a data-quality regression in which the MCP memory_store path was emitting 128-dim hash-fallback ("mock") embeddings instead of the real 384-dim ONNX vectors, because the AgentDB vectorBackend controller was initializing with enabled: false and never flipping (community: #2395, v3.12.3). The v3-ci.yml supply-chain audit job is also being tracked as a verification regression (community: #2412).

The CLI also includes a smart error-suggestion layer that catches mistyped subcommands (e.g. claude-flow swram) and uses Levenshtein distance to recommend the nearest valid command from swarm, neural, start, etc. (v3/implementation/adrs/README.md). Combined with the doctor command and the claims-based policy engine, this provides a defense-in-depth posture that catches user input, runtime state, and authorization decisions in distinct, auditable subsystems.

See Also

• Plugin System (Microkernel Architecture, ADR-004)
• Memory, Embeddings, and HNSW Vector Search
• Browser Automation and Trajectory Learning
• GOAP Research UI and Live Agent Dashboard
• Cost Tracking, Budgets, and Federation Spend
• Codex Integration and MCP Auto-Registration

Related Pages

Related topics: Ruflo Overview and Core Architecture, Multi-Agent Coordination, Federation, and Security

Plugin Ecosystem and Operational Concerns

Plugin Architecture

The ruflo plugin system implements a microkernel architecture (ADR-004) that exposes modular extension points for custom agent types, task types, MCP tools, CLI commands, and memory backends. Source: v3/implementation/plugins/README.md:1-12

The runtime is decomposed into three cooperating components. The Plugin Loader handles dependency resolution, lifecycle management, and health checks; it delegates to the Plugin Registry, which tracks loaded plugins and publishes their extension points and metrics; and the Registry fans out to individual plugin implementations. Source: v3/implementation/plugins/README.md:14-39

The public contract is the ClaudeFlowPlugin interface and PluginContext exported from @claude-flow/shared. A minimal plugin declares a name, a version, an async initialize(context), and a shutdown() hook — the same shape every shipped plugin follows. Source: v3/implementation/plugins/README.md:18-30

graph TB
    L["Plugin Loader<br/>Dependency resolution<br/>Lifecycle management<br/>Health checks"] --> R["Plugin Registry<br/>Plugin tracking<br/>Extension-point registration<br/>Status / metrics"]
    R --> P1["Plugin A<br/>(agent / skill / MCP tool)"]
    R --> P2["Plugin B"]
    R --> P3["Plugin N"]
    L -. hot-reload / unload .-> R

The CLI package exposes the plugin SDK via the @claude-flow/plugins entry point, and ships a runtime that can be pulled in from any of its exported subpaths (./ruvector, ./mcp-tools, ./memory, ./intelligence). Source: v3/@claude-flow/cli/package.json:35-75 and v3/@claude-flow/plugins/package.json:1-30

Plugin Catalog

The shipped ecosystem spans reasoning, knowledge, infrastructure, and methodology concerns. The following table summarizes the most prominent first- and third-party packages and the surfaces they touch.

The root manifest marks the umbrella package as multi-agent / swarm / orchestration / MCP / vector-database / embeddings / self-learning capable. Source: package.json:1-50

Operational Concerns

Several recurring operational pain points have been documented by community verification runs and issue reports; they cluster around three areas.

Cold-start latency. npx -y @claude-flow/cli@alpha --version has been observed to hang >60s on a cold install because the CLI initializes the ONNX embedder unconditionally on startup — including for trivial metadata commands. Source: community evidence referencing Issue #2286

Daemon proliferation. init.ts:424 historically spawned daemon start & racing the PID-file dedup logic; one macOS session accumulated 39 zombie node … daemon start --foreground --quiet processes and triggered a kernel panic. The shell & was dropped and an atomic O_EXCL lockfile introduced in daemon.ts; a race test of 5 concurrent daemon start invocations now leaves exactly 1 surviving daemon. Source: v3.12.2 release notes and community evidence for Issue #2407

Embedding quality regression. The MCP memory_store tool persistently emitted 128-dim hash-fallback ("mock") embeddings instead of the 384-dim ONNX vectors, because the AgentDB vectorBackend controller initialized as enabled: false and never flipped — silently corrupting similarity results. Fixed in v3.12.3 by routing the in-session MCP path through the real embedder. Source: v3.12.3 release notes and Issue #2395

Witness manifest drift. Scheduled verification runs on macOS, Linux, and Windows have reported missing=95 drift=2 and 95–99 missing dist/ artifacts despite valid Ed25519 signatures — pointing at a build/publish pipeline gap rather than tampering. Source: Issue #2047 and Issue #2391

Stub subcommands. security cve prints No CVE database configured and exits without returning CVE data, while security scan already produces results via npm audit. Source: Issue #2403

Uninstall ergonomics. Multiple community threads (#670, #694, #710) report that npm uninstall -g claude-flow does not remove residual .claude.json entries or hook registrations; users resort to manual cleanup. Source: Issue #670

Mitigations and Best Practices

The release cadence has moved fast on the operational side: v3.12.2 closed the kernel-panic class of bugs, hardened hooks, and shipped the CVE fix; v3.12.3 restored correct 384-dim embeddings for the MCP memory_store tool. The roadmap encoded in the ADRs also schedules Federation Hub, ephemeral agents, and a QUIC transport in Phases 2–3, which the deployment subsystem is positioned to ship. Source: v3/implementation/adrs/README.md:1-50 and v3/@claude-flow/deployment/README.md:20-50

For plugin authors, the supported pattern is therefore: implement ClaudeFlowPlugin, register extension points through the Registry, expose structured commands under commands/, ship skills under skills/<name>/SKILL.md, and gate any heavy native work behind lazy initialization so trivial commands (--version, doctor) do not pull in ONNX or WASM cold. Source: v3/implementation/plugins/README.md:18-30 and community evidence for Issue #2286

See Also

• ADR-004 — Plugin Microkernel Architecture
• ADR-150 — Metaharness Integration Surfaces
• ADR-153 — Darwin Mode Integration
• CLI Reference
• Memory & Embeddings Subsystem

Doramagic Pitfall Log

Found 39 structured pitfall item(s), including 6 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

1. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo
• User impact: Developers may expose sensitive permissions or credentials: ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo. Context: Observed when using node, macos
• Evidence: failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2409

2. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: security cve subcommand is a stub — never returns CVE data (scan already does, via npm audit)
• User impact: Developers may expose sensitive permissions or credentials: security cve subcommand is a stub — never returns CVE data (scan already does, via npm audit)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: security cve subcommand is a stub — never returns CVE data (scan already does, via npm audit). Context: Observed when using node
• Evidence: failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2403

3. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2286

4. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2412

5. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2047

6. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2313

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: [verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold install (ONNX model download on every startup)
• User impact: Developers may fail before the first successful local run: [verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold install (ONNX model download on every startup)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold install (ONNX model download on every startup). Context: Observed when using node, python, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2286

8. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: [verification] HIGH: Witness manifests report 95–99 missing build artifacts (dist/ absent)
• User impact: Developers may fail before the first successful local run: [verification] HIGH: Witness manifests report 95–99 missing build artifacts (dist/ absent)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [verification] HIGH: Witness manifests report 95–99 missing build artifacts (dist/ absent). Context: Observed when using node, python, windows, macos
• Evidence: failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2391

9. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: [verification] HIGH: witness manifests report missing=95 drift=2 on all three platforms
• User impact: Developers may fail before the first successful local run: [verification] HIGH: witness manifests report missing=95 drift=2 on all three platforms
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [verification] HIGH: witness manifests report missing=95 drift=2 on all three platforms. Context: Observed when using node, windows, macos, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2047

10. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: memory_store emits 128-dim mock embeddings — AgentDB vectorBackend controller never enables
• User impact: Developers may fail before the first successful local run: memory_store emits 128-dim mock embeddings — AgentDB vectorBackend controller never enables
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: memory_store emits 128-dim mock embeddings — AgentDB vectorBackend controller never enables. Context: Observed when using node, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2395

11. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v3.10.43 — Fable 5 / Opus 4.x temperature fix, daemon TTL, federation cap
• User impact: Upgrade or migration may change expected behavior: v3.10.43 — Fable 5 / Opus 4.x temperature fix, daemon TTL, federation cap
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v3.10.43 — Fable 5 / Opus 4.x temperature fix, daemon TTL, federation cap. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.10.43

12. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v3.10.44 — CI OOM fix, Windows plugin install
• User impact: Upgrade or migration may change expected behavior: v3.10.44 — CI OOM fix, Windows plugin install
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v3.10.44 — CI OOM fix, Windows plugin install. Context: Observed when using node, windows, linux
• Evidence: failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.10.44

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using ruflo with real data or production workflows.

• [[Dream Cycle 2026-06-23] memory: semantic drift from repeated summarizat](https://github.com/ruvnet/ruflo/issues/2452) - github / github_issue
• [[verification] HIGH: v3-ci.yml on main is FAILURE — supply-chain audit j](https://github.com/ruvnet/ruflo/issues/2412) - github / github_issue
• [[verification] MEDIUM: witness verify blocked — @noble/ed25519 not insta](https://github.com/ruvnet/ruflo/issues/2313) - github / github_issue
• statusLine: hooks statusline loads ONNX model on every call (~1s), cause - github / github_issue
• Default statusline/hooks use npx @claude-flow/cli@latest on high-frequ - github / github_issue
• Unbounded native memory leak: orphaned sql.js MEMFS dbfile_* files (~1 - github / github_issue
• Regression (ADR-130): graph-edge-writer.js sql.js writer corrupts memory - github / github_issue
• [[verification] MEDIUM: doctor reports MetaHarness ADR-150 integration fa](https://github.com/ruvnet/ruflo/issues/2437) - github / github_issue
• MCP stdio tools/list response exceeds macOS 64KB pipe buffer, causing to - github / github_issue
• [[verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold](https://github.com/ruvnet/ruflo/issues/2286) - github / github_issue
• [[verification] HIGH: witness manifests report missing=95 drift=2 on all](https://github.com/ruvnet/ruflo/issues/2047) - github / github_issue
• Security or permission risk requires verification - GitHub / issue