Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

fix(ruflo): correct relative asset/doc paths in the published README (#4325)

rUvf8b432f18f0e
diff --git a/ruflo/README.md b/ruflo/README.md
index 0023469eb3..db3c92b507 100644
--- a/ruflo/README.md
+++ b/ruflo/README.md
@@ -1,6 +1,6 @@
<div align="center">
-[![Ruflo Banner](ruflo/assets/ruflo-small.jpeg)](https://cognitum.one/agentic-engineering)
+[![Ruflo Banner](assets/ruflo-small.jpeg)](https://cognitum.one/agentic-engineering)
<!-- Try Ruflo β€” the 3 badges first-time visitors actually act on -->
[![npm version (ruflo)](https://img.shields.io/npm/v/ruflo?label=npx%20ruflo&style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/ruflo)
@@ -18,9 +18,9 @@
**An agent meta-harness for Claude Code and Codex.**
-[![RuFlo Explained β€” build an AI team that plans, remembers, tests, and improves](docs/assets/ruflo-explained/ch14.jpg)](docs/ruflo-explained.md)
+[![RuFlo Explained β€” build an AI team that plans, remembers, tests, and improves](../docs/assets/ruflo-explained/ch14.jpg)](../docs/ruflo-explained.md)
-**[πŸ“– RuFlo Explained β€” Build an AI Team That Plans, Remembers, Tests, and Improves](docs/ruflo-explained.md)**
+**[πŸ“– RuFlo Explained β€” Build an AI Team That Plans, Remembers, Tests, and Improves](../docs/ruflo-explained.md)**
A 14-chapter guide: from the basic idea to a first useful task, then memory, agent teams, plugins, cost and verification.
</div>
@@ -48,7 +48,7 @@ User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Prov
---
-![Ruflo Plugins](./ruflo-plugins.gif)
+![Ruflo Plugins](../ruflo-plugins.gif)
## Quick Start
@@ -84,81 +84,81 @@ This adds slash commands and agent definitions. `ruflo-core` (installed above) d
| Plugin | What it does |
|--------|-------------|
-| [**ruflo-core**](plugins/ruflo-core/README.md) | Foundation β€” server, health checks, plugin discovery |
-| [**ruflo-swarm**](plugins/ruflo-swarm/README.md) | Coordinate multiple agents as a team |
-| [**ruflo-autopilot**](plugins/ruflo-autopilot/README.md) | Let agents run autonomously in a loop |
-| [**ruflo-loop-workers**](plugins/ruflo-loop-workers/README.md) | Schedule background tasks on a timer |
-| [**ruflo-workflows**](plugins/ruflo-workflows/README.md) | Reusable multi-step task templates |
-| [**ruflo-federation**](plugins/ruflo-federation/README.md) | Agents on different machines collaborate securely |
+| [**ruflo-core**](../plugins/ruflo-core/README.md) | Foundation β€” server, health checks, plugin discovery |
+| [**ruflo-swarm**](../plugins/ruflo-swarm/README.md) | Coordinate multiple agents as a team |
+| [**ruflo-autopilot**](../plugins/ruflo-autopilot/README.md) | Let agents run autonomously in a loop |
+| [**ruflo-loop-workers**](../plugins/ruflo-loop-workers/README.md) | Schedule background tasks on a timer |
+| [**ruflo-workflows**](../plugins/ruflo-workflows/README.md) | Reusable multi-step task templates |
+| [**ruflo-federation**](../plugins/ruflo-federation/README.md) | Agents on different machines collaborate securely |
#### Memory & Knowledge
| Plugin | What it does |
|--------|-------------|
-| [**ruflo-agentdb**](plugins/ruflo-agentdb/README.md) | Fast vector database for agent memory |
-| [**ruflo-rag-memory**](plugins/ruflo-rag-memory/README.md) | Smart retrieval β€” hybrid search, graph hops, diversity ranking |
-| [**ruflo-rvf**](plugins/ruflo-rvf/README.md) | Save and restore agent memory across sessions |
-| [**ruflo-ruvector**](plugins/ruflo-ruvector/README.md) | [`ruvector`](https://npmjs.com/package/ruvector) β€” GPU-accelerated search, Graph RAG, 103 tools |
-| [**ruflo-knowledge-graph**](plugins/ruflo-knowledge-graph/README.md) | Build and traverse entity relationship maps |
+| [**ruflo-agentdb**](../plugins/ruflo-agentdb/README.md) | Fast vector database for agent memory |
+| [**ruflo-rag-memory**](../plugins/ruflo-rag-memory/README.md) | Smart retrieval β€” hybrid search, graph hops, diversity ranking |
+| [**ruflo-rvf**](../plugins/ruflo-rvf/README.md) | Save and restore agent memory across sessions |
+| [**ruflo-ruvector**](../plugins/ruflo-ruvector/README.md) | [`ruvector`](https://npmjs.com/package/ruvector) β€” GPU-accelerated search, Graph RAG, 103 tools |
+| [**ruflo-knowledge-graph**](../plugins/ruflo-knowledge-graph/README.md) | Build and traverse entity relationship maps |
#### Intelligence & Learning
| Plugin | What it does |
|--------|-------------|
-| [**ruflo-intelligence**](plugins/ruflo-intelligence/README.md) | Agents learn from past successes and get smarter |
-| [**ruflo-graph-intelligence**](plugins/ruflo-graph-intelligence/) | Sublinear graph reasoning β€” PageRank, delta updates, complexity-aware execution (ADR-123) |
-| [**ruflo-daa**](plugins/ruflo-daa/README.md) | Dynamic agent behavior and cognitive patterns |
-| [**ruflo-ruvllm**](plugins/ruflo-ruvllm/README.md) | Run local LLMs (Ollama, etc.) with smart routing |
-| [**ruflo-goals**](plugins/ruflo-goals/README.md) | Break big goals into plans and track progress |
+| [**ruflo-intelligence**](../plugins/ruflo-intelligence/README.md) | Agents learn from past successes and get smarter |
+| [**ruflo-graph-intelligence**](../plugins/ruflo-graph-intelligence/) | Sublinear graph reasoning β€” PageRank, delta updates, complexity-aware execution (ADR-123) |
+| [**ruflo-daa**](../plugins/ruflo-daa/README.md) | Dynamic agent behavior and cognitive patterns |
+| [**ruflo-ruvllm**](../plugins/ruflo-ruvllm/README.md) | Run local LLMs (Ollama, etc.) with smart routing |
+| [**ruflo-goals**](../plugins/ruflo-goals/README.md) | Break big goals into plans and track progress |
#### Code Quality & Testing
| Plugin | What it does |
|--------|-------------|
-| [**ruflo-testgen**](plugins/ruflo-testgen/README.md) | Find missing tests and generate them automatically |
-| [**ruflo-browser**](plugins/ruflo-browser/README.md) | Automate browser testing with Playwright |
-| [**ruflo-jujutsu**](plugins/ruflo-jujutsu/README.md) | Analyze git diffs, score risk, suggest reviewers |
-| [**ruflo-docs**](plugins/ruflo-docs/README.md) | Generate and maintain documentation automatically |
+| [**ruflo-testgen**](../plugins/ruflo-testgen/README.md) | Find missing tests and generate them automatically |
+| [**ruflo-browser**](../plugins/ruflo-browser/README.md) | Automate browser testing with Playwright |
+| [**ruflo-jujutsu**](../plugins/ruflo-jujutsu/README.md) | Analyze git diffs, score risk, suggest reviewers |
+| [**ruflo-docs**](../plugins/ruflo-docs/README.md) | Generate and maintain documentation automatically |
#### Security & Compliance
| Plugin | What it does |
|--------|-------------|
-| [**ruflo-security-audit**](plugins/ruflo-security-audit/README.md) | Scan for vulnerabilities and CVEs |
-| [**ruflo-aidefence**](plugins/ruflo-aidefence/README.md) | Block prompt injection, detect PII, safety scanning |
+| [**ruflo-security-audit**](../plugins/ruflo-security-audit/README.md) | Scan for vulnerabilities and CVEs |
+| [**ruflo-aidefence**](../plugins/ruflo-aidefence/README.md) | Block prompt injection, detect PII, safety scanning |
#### Architecture & Methodology
| Plugin | What it does |
|--------|-------------|
-| [**ruflo-adr**](plugins/ruflo-adr/README.md) | Track architecture decisions with a living record |
-| [**ruflo-ddd**](plugins/ruflo-ddd/README.md) | Scaffold domain-driven design β€” contexts, aggregates, events |
-| [**ruflo-sparc**](plugins/ruflo-sparc/README.md) | Guided 5-phase development methodology with quality gates |
-| [**ruflo-metaharness**](plugins/ruflo-metaharness/README.md) | Grade your agent setup, scan tool configs for security risks, and track changes over time ([guide](docs/metaharness-user-guide.md)) |
-| [**ruflo-arena**](plugins/ruflo-arena/README.md) | Competitive ruliology β€” pit agent strategies against each other in tournaments, hill-climb and co-evolve the winners (ADR-147/148) |
+| [**ruflo-adr**](../plugins/ruflo-adr/README.md) | Track architecture decisions with a living record |
+| [**ruflo-ddd**](../plugins/ruflo-ddd/README.md) | Scaffold domain-driven design β€” contexts, aggregates, events |
+| [**ruflo-sparc**](../plugins/ruflo-sparc/README.md) | Guided 5-phase development methodology with quality gates |
+| [**ruflo-metaharness**](../plugins/ruflo-metaharness/README.md) | Grade your agent setup, scan tool configs for security risks, and track changes over time ([guide](../docs/metaharness-user-guide.md)) |
+| [**ruflo-arena**](../plugins/ruflo-arena/README.md) | Competitive ruliology β€” pit agent strategies against each other in tournaments, hill-climb and co-evolve the winners (ADR-147/148) |
#### DevOps & Observability
| Plugin | What it does |
|--------|-------------|
-| [**ruflo-migrations**](plugins/ruflo-migrations/README.md) | Manage database schema changes safely |
-| [**ruflo-observability**](plugins/ruflo-observability/README.md) | Structured logs, traces, and metrics in one place |
-| [**ruflo-cost-tracker**](plugins/ruflo-cost-tracker/README.md) | Track token usage, set budgets, get cost alerts |
+| [**ruflo-migrations**](../plugins/ruflo-migrations/README.md) | Manage database schema changes safely |
+| [**ruflo-observability**](../plugins/ruflo-observability/README.md) | Structured logs, traces, and metrics in one place |
+| [**ruflo-cost-tracker**](../plugins/ruflo-cost-tracker/README.md) | Track token usage, set budgets, get cost alerts |
#### Extensibility
| Plugin | What it does |
|--------|-------------|
-| [**ruflo-agent**](plugins/ruflo-agent/README.md) | Run agents β€” local WASM sandbox (rvagent) + Anthropic Claude Managed Agents (cloud) |
-| [**ruflo-plugin-creator**](plugins/ruflo-plugin-creator/README.md) | Scaffold, validate, and publish your own plugins |
+| [**ruflo-agent**](../plugins/ruflo-agent/README.md) | Run agents β€” local WASM sandbox (rvagent) + Anthropic Claude Managed Agents (cloud) |
+| [**ruflo-plugin-creator**](../plugins/ruflo-plugin-creator/README.md) | Scaffold, validate, and publish your own plugins |
#### Domain-Specific
| Plugin | What it does |
|--------|-------------|
-| [**ruflo-iot-cognitum**](plugins/ruflo-iot-cognitum/README.md) | IoT device management β€” trust scoring, anomaly detection, fleets |
-| [**ruflo-neural-trader**](plugins/ruflo-neural-trader/README.md) | [`neural-trader`](https://npmjs.com/package/neural-trader) β€” AI trading with 4 agents, backtesting, 112+ tools |
-| [**ruflo-market-data**](plugins/ruflo-market-data/README.md) | Ingest market data, vectorize OHLCV, detect patterns |
+| [**ruflo-iot-cognitum**](../plugins/ruflo-iot-cognitum/README.md) | IoT device management β€” trust scoring, anomaly detection, fleets |
+| [**ruflo-neural-trader**](../plugins/ruflo-neural-trader/README.md) | [`neural-trader`](https://npmjs.com/package/neural-trader) β€” AI trading with 4 agents, backtesting, 112+ tools |
+| [**ruflo-market-data**](../plugins/ruflo-market-data/README.md) | Ingest market data, vectorize OHLCV, detect patterns |
</details>
@@ -203,13 +203,13 @@ claude mcp add claude-flow -- npx ruflo@latest mcp start
| πŸ“‘ **Comms Layer** | Zero-trust federation β€” agents across machines/orgs discover, authenticate, and exchange work securely |
| 🐝 **Swarm Coordination** | Hierarchical, mesh, and adaptive topologies with consensus |
| 🧠 **Self-Learning** | SONA neural patterns, ReasoningBank, trajectory learning |
-| πŸ’Ύ **Vector Memory** | HNSW-indexed AgentDB β€” measured ~1.9x faster at N=20k, ~3.2x–4.7x at N=5k vs brute force (recall@10 ~0.99); ANN wins above the crossover, ties/loses at small N. See [audit](docs/reviews/intelligence-system-audit-2026-05-29.md) + [`scripts/benchmark-intelligence.mjs`](scripts/benchmark-intelligence.mjs) |
+| πŸ’Ύ **Vector Memory** | HNSW-indexed AgentDB β€” measured ~1.9x faster at N=20k, ~3.2x–4.7x at N=5k vs brute force (recall@10 ~0.99); ANN wins above the crossover, ties/loses at small N. See [audit](../docs/reviews/intelligence-system-audit-2026-05-29.md) + [`scripts/benchmark-intelligence.mjs`](../scripts/benchmark-intelligence.mjs) |
| ⚑ **Background Workers** | 12 auto-triggered workers (audit, optimize, testgaps, etc.) |
| 🧩 **Plugin Marketplace** | 33 native Claude Code plugins + 21 npm plugins |
| πŸ”Œ **Multi-Provider** | Claude, GPT, Gemini, Cohere, Ollama with smart routing |
| πŸ›‘οΈ **Security** | AIDefence, input validation, CVE remediation, path traversal prevention |
| 🌐 **Agent Federation** | Cross-installation agent collaboration with zero-trust security |
-| πŸ”¬ **[MetaHarness](docs/metaharness-user-guide.md)** | Audit your AI agent setup before you ship. Grade readiness (1-100), scan tool configs for security issues, snapshot the whole project to catch regressions over time, and find templates that match your repo. `ruflo eject` turns a ruflo project into a standalone agent toolkit with its own name. [Full guide](docs/metaharness-user-guide.md). |
+| πŸ”¬ **[MetaHarness](../docs/metaharness-user-guide.md)** | Audit your AI agent setup before you ship. Grade readiness (1-100), scan tool configs for security issues, snapshot the whole project to catch regressions over time, and find templates that match your repo. `ruflo eject` turns a ruflo project into a standalone agent toolkit with its own name. [Full guide](../docs/metaharness-user-guide.md). |
### Agent Federation β€” Slack for Agents
@@ -233,7 +233,7 @@ The difference: some channels are trusted, some aren't. [`@claude-flow/plugin-ag
You don't configure handshakes or manage certificates. You `federation init`, `federation join`, and your agents start talking. The protocol handles identity, the PII pipeline handles data safety, and the audit trail handles compliance.
-> **πŸ“˜ Full user guide:** [`docs/federation/`](./docs/federation/) β€” setup, MCP tools, trust levels, circuit breaker, and the (opt-in) WireGuard mesh layer that ties packet-layer reachability to federation trust. ADR-111 deep-dive at [`docs/federation/phase7-mesh-bringup.md`](./docs/federation/phase7-mesh-bringup.md).
+> **πŸ“˜ Full user guide:** [`docs/federation/`](../docs/federation/) β€” setup, MCP tools, trust levels, circuit breaker, and the (opt-in) WireGuard mesh layer that ties packet-layer reachability to federation trust. ADR-111 deep-dive at [`docs/federation/phase7-mesh-bringup.md`](../docs/federation/phase7-mesh-bringup.md).
<details>
<summary><strong>Federation capabilities</strong></summary>
@@ -331,12 +331,12 @@ Four docs for four audiences:
| Doc | When to read it |
|-----|-----------------|
-| **[Status](docs/STATUS.md)** | See what currently works β€” capability counts, test baselines, recent fixes, what's next. The *is-it-ready* doc. |
-| **[User Guide](docs/USERGUIDE.md)** | Daily reference β€” every command, every config flag, every plugin. The *how-do-I* doc. |
-| **[MetaHarness Guide](docs/metaharness-user-guide.md)** | How to grade your agent setup, scan tool configs for security, detect changes between runs, and eject a project into a standalone agent toolkit. The *audit-my-setup* doc. |
+| **[Status](../docs/STATUS.md)** | See what currently works β€” capability counts, test baselines, recent fixes, what's next. The *is-it-ready* doc. |
+| **[User Guide](../docs/USERGUIDE.md)** | Daily reference β€” every command, every config flag, every plugin. The *how-do-I* doc. |
+| **[MetaHarness Guide](../docs/metaharness-user-guide.md)** | How to grade your agent setup, scan tool configs for security, detect changes between runs, and eject a project into a standalone agent toolkit. The *audit-my-setup* doc. |
| **[Benchmarks](https://gist.github.com/ruvnet/298f8c668c8859b369f91734a0e9cbbe)** | v3.8.0 SOTA matrix vs LangGraph / AutoGen / CrewAI on darwin-arm64 + linux-x64. ruflo wins cold start, single turn, RSS by 1.3×–1953Γ—. The *is-it-fast* doc. |
-| **[Verification](verification.md)** | Cryptographically prove your installed bytes match the signed witness β€” `ruflo verify`. The *trust-but-verify* doc. |
-| **[Team Gateway Checklist](docs/TEAM-GATEWAY-CHECKLIST.md)** | Before-merge gates, dual-mode handoff, memory namespace sharing, and witness manifest entry per merge. The *safer-team-workflows* doc. |
+| **[Verification](../verification/README.md)** | Cryptographically prove your installed bytes match the signed witness β€” `ruflo verify`. The *trust-but-verify* doc. |
+| **[Team Gateway Checklist](../docs/TEAM-GATEWAY-CHECKLIST.md)** | Before-merge gates, dual-mode handoff, memory namespace sharing, and witness manifest entry per merge. The *safer-team-workflows* doc. |
Benchmark internals (for reproduction): [`sota-workload-spec.md`](https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/sota-workload-spec.md) Β· [`SOTA-PROGRESS.md`](https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/SOTA-PROGRESS.md) Β· [raw matrix JSON: darwin](https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/sota-matrix.json) Β· [linux](https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/sota-matrix-linux.json)
@@ -344,13 +344,13 @@ User Guide section index:
| Section | Topics |
|---------|--------|
-| [Quick Start](docs/USERGUIDE.md#quick-start) | Installation, prerequisites, install profiles |
-| [Core Features](docs/USERGUIDE.md#-core-features) | MCP tools, agents, memory, neural learning |
-| [Intelligence & Learning](docs/USERGUIDE.md#-intelligence--learning) | Hooks, workers, SONA, model routing |
-| [Swarm & Coordination](docs/USERGUIDE.md#-swarm--coordination) | Topologies, consensus, hive mind |
-| [Security](docs/USERGUIDE.md#%EF%B8%8F-security) | AIDefence, CVE remediation, validation |
-| [Ecosystem](docs/USERGUIDE.md#-ecosystem--integrations) | RuVector, agentic-flow, Flow Nexus |
-| [Configuration](docs/USERGUIDE.md#%EF%B8%8F-configuration--reference) | Environment variables, config schema |
+| [Quick Start](../docs/USERGUIDE.md#quick-start) | Installation, prerequisites, install profiles |
+| [Core Features](../docs/USERGUIDE.md#-core-features) | MCP tools, agents, memory, neural learning |
+| [Intelligence & Learning](../docs/USERGUIDE.md#-intelligence--learning) | Hooks, workers, SONA, model routing |
+| [Swarm & Coordination](../docs/USERGUIDE.md#-swarm--coordination) | Topologies, consensus, hive mind |
+| [Security](../docs/USERGUIDE.md#%EF%B8%8F-security) | AIDefence, CVE remediation, validation |
+| [Ecosystem](../docs/USERGUIDE.md#-ecosystem--integrations) | RuVector, agentic-flow, Flow Nexus |
+| [Configuration](../docs/USERGUIDE.md#%EF%B8%8F-configuration--reference) | Environment variables, config schema |
| [Plugin Marketplace](https://ruvnet.github.io/ruflo) | Browse and install plugins |
---
@@ -359,7 +359,7 @@ User Guide section index:
| Resource | Link |
|----------|------|
-| Documentation | [User Guide](docs/USERGUIDE.md) |
+| Documentation | [User Guide](../docs/USERGUIDE.md) |
| Issues & Bugs | [GitHub Issues](https://github.com/ruvnet/claude-flow/issues) |
| Enterprise | [ruv.io](https://ruv.io) |
| Community | [Agentics Foundation Discord](https://discord.com/invite/dfxmpwkG2D) |