# https://github.com/ruvnet/ruflo Project Manual Generated at: 2026-06-23 11:31:45 UTC ## Table of Contents - [Ruflo Overview and Core Architecture](#page-1) - [Memory, Learning, and Intelligence Subsystem](#page-2) - [Multi-Agent Coordination, Federation, and Security](#page-3) - [Plugin Ecosystem and Operational Concerns](#page-4) ## Ruflo Overview and Core Architecture ### Related Pages Related topics: [Memory, Learning, and Intelligence Subsystem](#page-2), [Multi-Agent Coordination, Federation, and Security](#page-3), [Plugin Ecosystem and Operational Concerns](#page-4)
Related Source Files The following source files were used to generate this page: - [plugins/ruflo-core/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-core/README.md) - [plugins/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/README.md) - [v3/@claude-flow/cli/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/cli/package.json) - [plugins/ruflo-intelligence/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-intelligence/README.md) - [plugins/ruflo-docs/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-docs/README.md) - [plugins/ruflo-sparc/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-sparc/README.md) - [plugins/ruflo-knowledge-graph/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-knowledge-graph/README.md) - [plugins/ruflo-adr/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-adr/README.md) - [plugins/ruflo-ddd/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-ddd/README.md) - [plugins/ruflo-loop-workers/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-loop-workers/README.md) - [v3/@claude-flow/codex/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/codex/README.md) - [v3/goal_ui/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/goal_ui/README.md) - [package.json](https://github.com/ruvnet/ruflo/blob/main/package.json) - [v3/implementation/adrs/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/adrs/README.md)
# 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 `, 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: ```mermaid flowchart TB UI["Goal UI / Dashboard
(v3/goal_ui)"] CLI["CLI surface
(v3/@claude-flow/cli)"] MCP["MCP server
(ruflo-core, 300+ tools)"] Plugins["30+ plugins
(ruflo-swarm, ruflo-rag-memory,
ruflo-testgen, ruflo-adr, ...)"] Sub["Substrate: AgentDB + ONNX embeddings
(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`](https://npmjs.com/package/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//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-core.md) - [ruflo-intelligence — Self-learning pipeline](ruflo-intelligence.md) - [ruflo-sparc — Five-phase methodology](ruflo-sparc.md) - [ruflo-adr — Architecture Decision Records](ruflo-adr.md) - [Plugin catalog (plugins/README.md)](https://github.com/ruvnet/ruflo/blob/main/plugins/README.md) - [CLI reference (v3/@claude-flow/cli)](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/cli) --- ## Memory, Learning, and Intelligence Subsystem ### Related Pages Related topics: [Ruflo Overview and Core Architecture](#page-1), [Multi-Agent Coordination, Federation, and Security](#page-3)
Related Source Files The following source files were used to generate this page: - [v3/implementation/adrs/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/adrs/README.md) - [v3/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/README.md) - [v3/@claude-flow/cli/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/cli/package.json) - [v3/@claude-flow/codex/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/codex/README.md) - [plugins/ruflo-rag-memory/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-rag-memory/README.md) - [plugins/ruflo-knowledge-graph/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-knowledge-graph/README.md) - [v3/plugins/hyperbolic-reasoning/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/hyperbolic-reasoning/README.md) - [plugins/ruflo-metaharness/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-metaharness/README.md) - [v3/plugins/prime-radiant/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/prime-radiant/README.md) - [plugins/ruflo-ruvector/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-ruvector/README.md)
# 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](). ```mermaid 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](https://github.com/ruvnet/ruflo/issues/2395), [v3.12.3 release notes](https://github.com/ruvnet/ruflo/releases/tag/v3.12.3). 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](https://github.com/ruvnet/ruflo/issues/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](https://github.com/ruvnet/ruflo/issues/2409). ## Known Failure Modes | Symptom | Root Cause | Fix / Tracking | |---------|------------|----------------| | `memory_store` returns 128-dim vectors | AgentDB `vectorBackend` stays `enabled: false` | Fixed in v3.12.3 | | `--version` hangs >60s on cold install | ONNX model downloaded on every startup | Issue #2286 | | `security cve` prints "No CVE database configured" | Stub subcommand never wired to `npm audit` | Issue #2403 | | Bi-temporal HNSW regression on LongMemEval | Engram gap of +10.4pp vs. prior cycle | Dream Cycle 2026-06-18 (#2410) | Source: [community issues #2395, #2286, #2403, #2410](https://github.com/ruvnet/ruflo/issues). ## 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 --- ## Multi-Agent Coordination, Federation, and Security ### Related Pages Related topics: [Ruflo Overview and Core Architecture](#page-1), [Memory, Learning, and Intelligence Subsystem](#page-2), [Plugin Ecosystem and Operational Concerns](#page-4)
Related Source Files The following source files were used to generate this page: - [v3/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/README.md) - [v3/implementation/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/README.md) - [v3/implementation/adrs/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/adrs/README.md) - [v3/implementation/plugins/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/plugins/README.md) - [v3/@claude-flow/browser/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/browser/README.md) - [v3/@claude-flow/cli/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/cli/package.json) - [v3/@claude-flow/plugins/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/plugins/package.json) - [v3/@claude-flow/codex/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/codex/README.md) - [plugins/ruflo-cost-tracker/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-cost-tracker/README.md) - [v3/goal_ui/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/goal_ui/README.md) - [v3/plugins/hyperbolic-reasoning/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/hyperbolic-reasoning/README.md) - [v3/plugins/legal-contracts/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/legal-contracts/README.md) - [ruflo/package.json](https://github.com/ruvnet/ruflo/blob/main/ruflo/package.json)
# 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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/plugins/README.md)). The plugin contract exposes extension points for custom agent types, task types, MCP tools, CLI commands, and memory backends. ```mermaid 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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/issues/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/blob/main/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](https://github.com/ruvnet/ruflo/releases/tag/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](https://github.com/ruvnet/ruflo/issues/2395), [v3.12.3](https://github.com/ruvnet/ruflo/releases/tag/v3.12.3)). The `v3-ci.yml` supply-chain audit job is also being tracked as a verification regression ([community: #2412](https://github.com/ruvnet/ruflo/issues/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](https://github.com/ruvnet/ruflo/blob/main/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)](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/plugins/README.md) - [Memory, Embeddings, and HNSW Vector Search](https://github.com/ruvnet/ruflo/blob/main/v3/README.md) - [Browser Automation and Trajectory Learning](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/browser/README.md) - [GOAP Research UI and Live Agent Dashboard](https://github.com/ruvnet/ruflo/blob/main/v3/goal_ui/README.md) - [Cost Tracking, Budgets, and Federation Spend](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-cost-tracker/README.md) - [Codex Integration and MCP Auto-Registration](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/codex/README.md) --- ## Plugin Ecosystem and Operational Concerns ### Related Pages Related topics: [Ruflo Overview and Core Architecture](#page-1), [Multi-Agent Coordination, Federation, and Security](#page-3)
Related Source Files The following source files were used to generate this page: - [v3/implementation/plugins/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/plugins/README.md) - [v3/implementation/adrs/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/adrs/README.md) - [v3/@claude-flow/cli/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/cli/package.json) - [v3/@claude-flow/plugins/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/plugins/package.json) - [v3/plugins/code-intelligence/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/code-intelligence/README.md) - [v3/plugins/prime-radiant/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/prime-radiant/README.md) - [v3/plugins/hyperbolic-reasoning/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/hyperbolic-reasoning/README.md) - [plugins/ruflo-sparc/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-sparc/README.md) - [plugins/ruflo-knowledge-graph/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-knowledge-graph/README.md) - [plugins/ruflo-metaharness/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-metaharness/README.md) - [plugins/ruflo-docs/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-docs/README.md) - [v3/@claude-flow/deployment/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/deployment/README.md) - [package.json](https://github.com/ruvnet/ruflo/blob/main/package.json) - [v3/@claude-flow/codex/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/codex/README.md)
# 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]() ```mermaid graph TB L["Plugin Loader
Dependency resolution
Lifecycle management
Health checks"] --> R["Plugin Registry
Plugin tracking
Extension-point registration
Status / metrics"] R --> P1["Plugin A
(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. | Plugin / Package | Primary Surface | Notes / Source | |---|---|---| | `@claude-flow/plugin-code-intelligence` | Semantic search, AST analysis, refactoring impact | WASM-backed via `micro-hnsw-wasm`, `ruvector-gnn-wasm`, `ruvector-mincut-wasm`; pairs with `plugin-test-intelligence` and `plugin-perf-optimizer`. Source: [v3/plugins/code-intelligence/README.md:1-40](), [v3/plugins/code-intelligence/package.json:1-30]() | | `prime-radiant` | Coherence / spectral / causal / quantum / category / HoTT reasoning | 6 reasoning engines; auto-hooks fire before `memory-store`, `consensus`, `swarm-task`, `rag-retrieval`. Source: [v3/plugins/prime-radiant/README.md:1-60]() | | `hyperbolic-reasoning` | Hierarchy-aware embeddings (Poincaré ball) | Adaptive curvature; recommended alongside `plugin-neural-coordination` and `plugin-cognitive-kernel`. Source: [v3/plugins/hyperbolic-reasoning/README.md:1-40]() | | `plugin-healthcare-clinical` | Clinical / healthcare domain scaffolding | Optional WASM deps for sparse inference, hyperbolic HNSW, and GNN. Source: [v3/plugins/healthcare-clinical/package.json:30-50]() | | `plugin-gastown-bridge` | Federation bridge to the Gastown multi-agent runtime | Peer-depends on `@claude-flow/memory` (optional); bundle-sized via `size-limit`. Source: [v3/plugins/gastown-bridge/package.json:25-55]() | | `plugin-codex` | Dual-platform (Claude Code + Codex) integration | Auto-registers MCP; exposes 137+ `$skill-name` skills and HNSW-backed vector memory. Source: [v3/@claude-flow/codex/README.md:1-30]() | | `ruflo-sparc` | 5-phase SPARC methodology (spec → pseudo → arch → refine → complete) | 5 commands, 5 memory namespaces (`sparc-state`, `sparc-phases`, `sparc-gates`, `patterns`); pinned to `@claude-flow/cli` major+minor. Source: [plugins/ruflo-sparc/README.md:1-40]() | | `ruflo-knowledge-graph` | Entity / relation extraction + pathfinder traversal | Single `graph-navigator` agent; commands `extract`, `traverse`, `relations`, `visualize`, `search`. Source: [plugins/ruflo-knowledge-graph/README.md:1-40]() | | `ruflo-metaharness` | Population-based harness self-improvement | All skills shell out to `npx metaharness` via shared `_harness.mjs`; 60s hard timeout; emits degraded JSON on `MODULE_NOT_FOUND`. Source: [plugins/ruflo-metaharness/README.md:1-50]() | | `ruflo-docs` | Auto-documentation + drift detection + API reference | Drives the `document` background worker (one of 12 in `CLAUDE.md`); requires `ruflo-core` for MCP. Source: [plugins/ruflo-docs/README.md:1-40]() | | `@claude-flow/deployment` | Release, publish, validate lifecycle | `ReleaseManager.prepareRelease`, `publishToNpm`, `validate`; dry-run supported. Source: [v3/@claude-flow/deployment/README.md:1-40]() | 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](https://github.com/ruvnet/ruflo/issues/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](https://github.com/ruvnet/ruflo/releases/tag/v3.12.2) and community evidence for [Issue #2407](https://github.com/ruvnet/ruflo/issues/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](https://github.com/ruvnet/ruflo/releases/tag/v3.12.3) and [Issue #2395](https://github.com/ruvnet/ruflo/issues/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](https://github.com/ruvnet/ruflo/issues/2047) and [Issue #2391](https://github.com/ruvnet/ruflo/issues/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](https://github.com/ruvnet/ruflo/issues/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](https://github.com/ruvnet/ruflo/issues/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//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](https://github.com/ruvnet/ruflo/issues/2286) ## See Also - [ADR-004 — Plugin Microkernel Architecture](https://github.com/ruvnet/ruflo/blob/main/v3/docs/adr/ADR-004-plugin-microkernel.md) - [ADR-150 — Metaharness Integration Surfaces](https://github.com/ruvnet/ruflo/blob/main/v3/docs/adr/ADR-150-metaharness-integration-surfaces.md) - [ADR-153 — Darwin Mode Integration](https://github.com/ruvnet/ruflo/blob/main/v3/docs/adr/ADR-153-metaharness-darwin-mode-integration.md) - [CLI Reference](https://github.com/ruvnet/ruflo/wiki/CLI-Reference) - [Memory & Embeddings Subsystem](https://github.com/ruvnet/ruflo/wiki/Memory-and-Embeddings) --- --- ## Pitfall Log Project: ruvnet/ruflo Summary: 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 - Evidence strength: source_linked - 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 - 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 - Evidence strength: source_linked - 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) - 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 - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2286 ## 4. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2412 ## 5. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2047 ## 6. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2313 ## 7. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - 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) - Evidence: failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2286 ## 8. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - 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) - Evidence: failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2391 ## 9. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - 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 - Evidence: failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2047 ## 10. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - 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 - Evidence: failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2395 ## 11. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - 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 - 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 - Evidence strength: source_linked - 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 - Evidence: failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.10.44 ## 13. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v3.10.45 — hive-mind --dangerously-skip-permissions deny clause - User impact: Upgrade or migration may change expected behavior: v3.10.45 — hive-mind --dangerously-skip-permissions deny clause - Evidence: failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.10.45 ## 14. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v3.10.46 — stale claude-flow@v3alpha references swept (@dskarasev community batch) - User impact: Upgrade or migration may change expected behavior: v3.10.46 — stale claude-flow@v3alpha references swept (@dskarasev community batch) - Evidence: failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.10.46 ## 15. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v3.11.0 — router ADR-148/149 + cost-tracker observability + fleet audits - User impact: Upgrade or migration may change expected behavior: v3.11.0 — router ADR-148/149 + cost-tracker observability + fleet audits - Evidence: failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.11.0 ## 16. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v3.12.0 — ADR-150 metaharness deep integration - User impact: Upgrade or migration may change expected behavior: v3.12.0 — ADR-150 metaharness deep integration - Evidence: failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.12.0 ## 17. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v3.12.1 — bundle metaharness plugin scripts - User impact: Upgrade or migration may change expected behavior: v3.12.1 — bundle metaharness plugin scripts - Evidence: failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.12.1 ## 18. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v3.12.2 — kernel-panic fix + cve subcommand fix + hooks hardening - User impact: Upgrade or migration may change expected behavior: v3.12.2 — kernel-panic fix + cve subcommand fix + hooks hardening - Evidence: failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.12.2 ## 19. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v3.12.3 — #2395 fix: MCP no longer emits 128-dim mock embeddings - User impact: Upgrade or migration may change expected behavior: v3.12.3 — #2395 fix: MCP no longer emits 128-dim mock embeddings - Evidence: failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.12.3 ## 20. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2409 ## 21. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2448 ## 22. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2426 ## 23. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2431 ## 24. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2432 ## 25. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2391 ## 26. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2412 ## 27. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2437 ## 28. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2395 ## 29. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/ruvnet/ruflo ## 30. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: [BUG] daemon proliferation: `init.ts:424` spawns `daemon start &` racing the PID-file dedup → kernel panic on macOS - User impact: Developers may misconfigure credentials, environment, or host setup: [BUG] daemon proliferation: `init.ts:424` spawns `daemon start &` racing the PID-file dedup → kernel panic on macOS - Evidence: failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2407 ## 31. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2450 ## 32. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/ruvnet/ruflo ## 33. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/ruvnet/ruflo ## 34. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/ruvnet/ruflo ## 35. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/ruvnet/ruflo ## 36. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2410 ## 37. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - 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. - Evidence: community_evidence:github | https://github.com/ruvnet/ruflo/issues/2452 ## 38. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/ruvnet/ruflo ## 39. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/ruvnet/ruflo