Ruflo v3.5.0

<div align="center">

# Ruflo v3.5.0

### From Alpha to Production — The First Major Stable Release

[![npm](https://img.shields.io/badge/npm-v3.5.0-blue?style=flat-square&logo=npm)](https://www.npmjs.com/package/ruflo)
[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-445%20passing-brightgreen?style=flat-square)](https://github.com/ruvnet/claude-flow)
[![Vulnerabilities](https://img.shields.io/badge/vulnerabilities-0-brightgreen?style=flat-square)](https://github.com/ruvnet/claude-flow)

</div>

---

After **10 months**, **5,800+ commits**, and **55 alpha iterations**, Ruflo graduates from alpha to its first production-ready release. Formerly known as **Claude Flow**, Ruflo is an enterprise AI agent orchestration platform that turns [Claude Code](https://docs.anthropic.com/en/docs/claude-code) into a full multi-agent development environment — coordinating 60+ specialized agents across swarms, with self-learning memory, fault-tolerant consensus, and 215 MCP tools.

**v3.5 brings three major advances:**

**1. Deep agentic-flow v3 Integration** — The upstream coordination engine is now wired into every layer: ReasoningBank WASM for embeddings, intelligent 3-tier model routing that saves up to 75% on API costs, and a unified lazy-loading bridge that handles graceful degradation across 10 module exports.

**2. AgentDB v3 with 8 New Controllers** — HierarchicalMemory, MemoryConsolidation, SemanticRouter, GNNService, RVFOptimizer, MutationGuard (cryptographic proof-verified writes), AttestationLog, and GuardedVectorBackend — plus 6 new MCP tools for managing them.

**3. Security Hardening** — Critical command injection fix, TOCTOU race condition elimination, hardcoded HMAC key removal, and timing attack mitigations. The result: **zero production vulnerabilities** across all packages.

> **Release PR:** #1239

---

## Quickstart

Get running in under 60 seconds:

### Option A: MCP Server for Claude Code

One command adds Ruflo's 215 tools to your Claude Code environment:

```bash
claude mcp add ruflo -- npx -y ruflo@latest
```

That's it. Claude Code now has access to swarm coordination, vector memory, self-learning hooks, neural training, security scanning, and more — all via MCP.

### Option B: Standalone CLI

```bash
# Initialize a new project with the interactive wizard
npx ruflo@latest init --wizard

# Check system health (auto-fixes common issues)
npx ruflo doctor --fix

# Start background learning workers
npx ruflo daemon start
```

### Your First Swarm

```bash
# 1. Initialize a hierarchical swarm (anti-drift)
npx ruflo swarm init --topology hierarchical --max-agents 8 --strategy specialized

# 2. Spawn specialized agents
npx ruflo agent spawn -t coder --name my-coder
npx ruflo agent spawn -t tester --name my-tester
npx ruflo agent spawn -t reviewer --name my-reviewer
```

### Memory & Learning

```bash
# Store a pattern for future recall
npx ruflo memory store --key "auth-pattern" --value "JWT with refresh tokens" --namespace patterns

# Semantic search across all stored knowledge (HNSW-indexed, 150x-12,500x faster)
npx ruflo memory search --query "authentication best practices" --limit 5

# Let the router pick the optimal agent for a task
npx ruflo hooks route --task "implement OAuth2 login flow"

# After completing work, train on the success
npx ruflo hooks post-task --task-id "t1" --success true --store-results true
```

### Package Aliases

All three names resolve to the same CLI:

```bash
npx ruflo@latest             # recommended
npx claude-flow@latest       # legacy alias
npx @claude-flow/cli@latest  # scoped package
```

---

<details>
<summary><h2>What's New in v3.5.0</h2></summary>

### Rebranding: Claude Flow → Ruflo

All three npm packages have been unified under the Ruflo brand:

| Package | Version | Install |
|---------|---------|---------|
| `ruflo` | 3.5.0 | `npx ruflo@latest` (recommended) |
| `claude-flow` | 3.5.0 | `npx claude-flow@latest` (legacy alias) |
| `@claude-flow/cli` | 3.5.0 | `npx @claude-flow/cli@latest` (scoped) |

`ruflo` is now the primary package name. Publish tags switched from `alpha`/`v3alpha` to `latest`.

### agentic-flow v3.0.0-alpha.1 Deep Integration

Full integration with 10 subpath exports from the agentic-flow coordination engine:

| Export | Purpose | Integration Point |
|--------|---------|-------------------|
| `agentic-flow/reasoningbank` | WASM-accelerated pattern learning | Embeddings (Tier 1), hooks, neural tools |
| `agentic-flow/router` | Intelligent model routing | Enhanced model router |
| `agentic-flow/orchestration` | Multi-agent orchestration | Bridge, doctor check |
| `agentic-flow/agent-booster` | Zero-cost code transforms (<1ms) | Enhanced model router (local import) |
| `agentic-flow/sdk` | Core SDK | Type declarations |
| `agentic-flow/security` | Security primitives | Type declarations |
| `agentic-flow/transport/quic` | QUIC network transport | Doctor check, bridge |
| `agentic-flow/intelligence/*` | Enhanced intelligence modules | Fallback agent-booster path |

**New: Unified Bridge** (`agentic-flow-bridge.ts`) — Promise-based lazy-loading singleton for all agentic-flow modules with TOCTOU-safe concurrent access.

**New: Tiered Embedding Resolution**
```
Tier 1: ReasoningBank WASM (fastest, 768-dim) → 
Tier 2: @claude-flow/embeddings (384-dim) → 
Tier 3: Hash-based mock fallback
```

### AgentDB v3.0.0-alpha.9 — 8 New Controllers

| Controller | Purpose | MCP Tools |
|------------|---------|-----------|
| `HierarchicalMemory` | Multi-level memory hierarchies | `agentdb_hierarchical_store`, `agentdb_hierarchical_retrieve` |
| `MemoryConsolidation` | Cross-session memory merging | `agentdb_consolidation_run`, `agentdb_consolidation_status` |
| `SemanticRouter` | Intent-based query routing | `agentdb_semantic_route`, `agentdb_semantic_classify` |
| `GNNService` | Graph neural network inference | — |
| `RVFOptimizer` | RuVector field optimization | — |
| `MutationGuard` | Proof-verified write protection | — |
| `AttestationLog` | Cryptographic audit trail | — |
| `GuardedVectorBackend` | Verified vector operations | — |

MutationGuard runs with native proof engine and WASM fallback.

### Security Hardening

| Vulnerability | Fix | Severity |
|--------------|-----|----------|
| Command injection in agent-booster | `SAFE_LANGUAGES` whitelist for `execSync` | **Critical** |
| TOCTOU race in bridge singleton | Promise-based caching (concurrent callers share same Promise) | **Moderate** |
| Hardcoded HMAC keys | Eliminated across codebase | **High** |
| Timing attacks | Constant-time comparison functions | **High** |
| Stale version references | 22 agent/skill files updated v2→v3 | **Low** |

**Result:** 0 production vulnerabilities (`npm audit` clean)

### Doctor Health Check

New `agentic-flow` diagnostic added to `npx ruflo doctor`:

```
$ npx ruflo doctor

  ✓ node:          v22.14.0
  ✓ npm:           10.9.2
  ✓ git:           2.47.1
  ✓ config:        ruflo.config.json found
  ✓ daemon:        Running (PID 12345)
  ✓ memory:        AgentDB initialized (sql.js + HNSW)
  ✓ agentic-flow:  v3.0.0-alpha.1 (ReasoningBank, Router, QUIC)   ← NEW
  ...
```

Uses filesystem-based detection (ESM-compatible, avoids WASM/DB initialization overhead).

</details>

<details>
<summary><h2>Platform at a Glance</h2></summary>

### By the Numbers

| Metric | Value |
|--------|-------|
| Total commits | 5,800+ |
| Alpha iterations | 55 |
| MCP tools | 215 |
| CLI commands | 26 (140+ subcommands) |
| Agent types | 60+ |
| Hooks | 17 + 12 background workers |
| Plugins | 20 (8 official + 12 community) |
| Tests passing | 445 |
| Production vulnerabilities | 0 |
| Supported platforms | Linux, macOS, Windows |

### Architecture

```
User → Ruflo CLI/MCP → Router → Swarm → Agents → Memory → LLM Providers
                      ↑                           ↓
                      └──── Learning Loop ←───────┘
```

### Package Ecosystem

| Package | Purpose |
|---------|---------|
| `@claude-flow/cli` | CLI entry point (26 commands) |
| `@claude-flow/memory` | AgentDB + HNSW vector search |
| `@claude-flow/guidance` | Governance control plane |
| `@claude-flow/hooks` | 17 hooks + 12 workers |
| `@claude-flow/security` | Input validation, CVE remediation |
| `@claude-flow/codex` | Dual-mode Claude + Codex collaboration |
| `@claude-flow/shared` | Shared types and utilities |
| `@claude-flow/embeddings` | Vector embeddings with sql.js |
| `@claude-flow/aidefence` | AI defense layer |

</details>

<details>
<summary><h2>Performance Benchmarks</h2></summary>

### v3.5 vs v2.7 Comparison

| Metric | v2.7 | v3.5 | Improvement |
|--------|------|------|-------------|
| Memory search | SQLite FTS | HNSW indexed | **150x-12,500x faster** |
| Embedding generation | External API | ReasoningBank WASM | **75x faster** |
| Agent Booster transforms | npx shell-out | Local import | **352x faster** |
| Memory footprint | Full float32 | Int8 quantization | **3.92x reduction** |
| CLI startup | ~2s | <500ms | **4x faster** |
| MCP response | ~500ms | <100ms | **5x faster** |
| SONA adaptation | N/A | <0.05ms | New capability |

### Intelligence Pipeline

```
RETRIEVE (HNSW, 150x faster) →
JUDGE (verdicts, success/failure) →
DISTILL (LoRA fine-tuning) →
CONSOLIDATE (EWC++, prevents forgetting)
```

### 3-Tier Model Routing (ADR-026)

| Tier | Handler | Latency | Cost | Use Cases |
|------|---------|---------|------|-----------|
| 1 | Agent Booster (WASM) | <1ms | $0 | Simple transforms — skip LLM entirely |
| 2 | Haiku | ~500ms | $0.0002 | Simple tasks, low complexity |
| 3 | Sonnet/Opus | 2-5s | $0.003-0.015 | Complex reasoning, architecture |

**Result:** Up to 75% cost reduction via intelligent routing.

</details>

<details>
<summary><h2>Agent & Swarm Capabilities</h2></summary>

### 60+ Specialized Agent Types

| Category | Agents | Purpose |
|----------|--------|---------|
| **Core** | coder, reviewer, tester, planner, researcher | General development |
| **SPARC** | specification, pseudocode, architecture, refinement, sparc-coord | Methodology |
| **Swarm** | hierarchical-coordinator, mesh-coordinator, adaptive-coordinator | Multi-agent coordination |
| **Consensus** | byzantine-coordinator, raft-manager, gossip-coordinator, crdt-synchronizer | Distributed agreement |
| **GitHub** | pr-manager, issue-tracker, release-manager, code-review-swarm, workflow-automation | Repository management |
| **Security** | security-architect, security-auditor, security-manager | Threat modeling & audit |
| **Performance** | perf-analyzer, performance-benchmarker, performance-optimizer | Optimization |
| **Specialized** | backend-dev, mobile-dev, ml-developer, cicd-engineer, api-docs | Domain-specific |

### Swarm Topologies

| Topology | Best For | Drift Risk |
|----------|----------|------------|
| `hierarchical` | Small teams (6-8) | Low — central control |
| `hierarchical-mesh` | Large teams (10-15) | Low — queen + peer |
| `mesh` | Peer collaboration | Medium |
| `adaptive` | Dynamic workloads | Auto-adjusted |

### Consensus Strategies

| Strategy | Fault Tolerance | Use Case |
|----------|----------------|----------|
| `byzantine` | f < n/3 faulty | Untrusted environments |
| `raft` | f < n/2 | Leader-based coordination |
| `gossip` | Eventual consistency | Large-scale propagation |
| `crdt` | Conflict-free | Concurrent state updates |
| `quorum` | Configurable | Flexible agreement |

### Hive-Mind Consensus

Queen-led Byzantine fault-tolerant consensus with configurable topology:
```bash
npx ruflo hive-mind init --topology hierarchical-mesh --consensus byzantine
npx ruflo hive-mind spawn --agents 8 --strategy specialized
```

</details>

<details>
<summary><h2>CLI Commands Reference</h2></summary>

### Core Commands (26 total, 140+ subcommands)

| Command | Sub | Description |
|---------|-----|-------------|
| `init` | 4 | Project initialization with wizard, presets, skills, hooks |
| `agent` | 8 | Agent lifecycle (spawn, list, status, stop, metrics, pool, health, logs) |
| `swarm` | 6 | Multi-agent swarm coordination and orchestration |
| `memory` | 11 | AgentDB memory with HNSW vector search |
| `mcp` | 9 | MCP server management and tool execution |
| `task` | 6 | Task creation, assignment, and lifecycle |
| `session` | 7 | Session state management and persistence |
| `config` | 7 | Configuration management and provider setup |
| `status` | 3 | System status monitoring with watch mode |
| `start` | 3 | Service startup and quick launch |
| `workflow` | 6 | Workflow execution and template management |
| `hooks` | 17 | Self-learning hooks + 12 background workers |
| `hive-mind` | 6 | Queen-led Byzantine fault-tolerant consensus |
| `daemon` | 5 | Background worker daemon management |
| `neural` | 5 | Neural pattern training (SONA, MoE, EWC++) |
| `security` | 6 | Security scanning and vulnerability detection |
| `performance` | 5 | Performance profiling and benchmarking |
| `providers` | 5 | AI provider management |
| `plugins` | 5 | Plugin system (20 available) |
| `deployment` | 5 | Deployment and release management |
| `embeddings` | 4 | Vector embeddings (75x faster) |
| `claims` | 4 | Claims-based authorization |
| `migrate` | 5 | V2 → V3 migration with rollback |
| `process` | 4 | Background process management |
| `doctor` | 1 | System diagnostics with auto-fix |
| `completions` | 4 | Shell completions (bash, zsh, fish, powershell) |

### Quick Examples

```bash
# Initialize a new project
npx ruflo init --wizard

# Spawn a coding swarm
npx ruflo swarm init --topology hierarchical --max-agents 8
npx ruflo agent spawn -t coder --name my-coder

# Memory operations (HNSW-indexed)
npx ruflo memory store --key "pattern" --value "JWT auth" --namespace patterns
npx ruflo memory search --query "authentication" --limit 5

# Self-learning hooks
npx ruflo hooks route --task "implement OAuth login"
npx ruflo hooks post-task --task-id "t1" --success true --store-results true

# System health
npx ruflo doctor --fix

# Security scan
npx ruflo security scan --depth full
```

</details>

<details>
<summary><h2>Hooks & Learning System</h2></summary>

### 17 Hooks + 12 Background Workers

| Hook | Trigger | Purpose |
|------|---------|---------|
| `pre-edit` / `post-edit` | File editing | Context loading, pattern training |
| `pre-command` / `post-command` | Shell commands | Risk assessment, metric tracking |
| `pre-task` / `post-task` | Task lifecycle | Agent suggestions, result storage |
| `session-start` / `session-end` / `session-restore` | Sessions | State management, persistence |
| `route` | Task assignment | Optimal agent selection |
| `explain` | Routing decisions | Decision transparency |
| `pretrain` | Bootstrap | Intelligence initialization |
| `build-agents` | Agent creation | Optimized configurations |
| `intelligence` | RuVector | Trajectory learning, pattern search |
| `transfer` | Cross-project | Pattern sharing via IPFS |
| `teammate-idle` / `task-completed` | Agent Teams | Auto-assignment, pattern training |

### 12 Background Workers

| Worker | Priority | Trigger |
|--------|----------|---------|
| `audit` | Critical | Security changes |
| `optimize` | High | Performance work |
| `ultralearn` | Normal | Deep knowledge acquisition |
| `predict` | Normal | Predictive preloading |
| `map` | Normal | Codebase mapping |
| `deepdive` | Normal | Deep code analysis |
| `document` | Normal | Auto-documentation |
| `refactor` | Normal | Refactoring suggestions |
| `benchmark` | Normal | Performance benchmarking |
| `testgaps` | Normal | Test coverage analysis |
| `consolidate` | Low | Memory consolidation |
| `preload` | Low | Resource preloading |

### Intelligence System (RuVector)

| Component | Performance |
|-----------|-------------|
| SONA (Self-Optimizing Neural Architecture) | <0.05ms adaptation |
| MoE (Mixture of Experts) | 8 specialized experts |
| HNSW (Hierarchical Navigable Small World) | 150x-12,500x faster search |
| EWC++ (Elastic Weight Consolidation) | Prevents catastrophic forgetting |
| Flash Attention | 2.49x-7.47x speedup |

</details>

<details>
<summary><h2>MCP Server (215 Tools)</h2></summary>

### Tool Categories

| Category | Tools | Examples |
|----------|-------|---------|
| Memory | 11 | `memory_store`, `memory_search`, `memory_retrieve`, `memory_list` |
| AgentDB | 6 | `agentdb_hierarchical_store`, `agentdb_semantic_route`, `agentdb_consolidation_run` |
| Agent | 8 | `agent_spawn`, `agent_list`, `agent_status`, `agent_stop` |
| Swarm | 6 | `swarm_init`, `swarm_status`, `swarm_stop` |
| Task | 6 | `task_create`, `task_assign`, `task_status` |
| Hooks | 17 | `hooks_pre_task`, `hooks_post_task`, `hooks_route` |
| Neural | 5 | `neural_train`, `neural_predict`, `neural_patterns` |
| Security | 6 | `security_scan`, `security_audit`, `security_cve` |
| Performance | 5 | `performance_benchmark`, `performance_profile` |
| Session | 7 | `session_start`, `session_end`, `session_restore` |
| Plugins | 5 | `plugins_list`, `plugins_install`, `plugins_enable` |
| + more | 133 | Workflow, deployment, claims, embeddings, providers, hive-mind... |

### MCP Setup

```bash
# Add to Claude Code
claude mcp add ruflo -- npx -y ruflo@latest

# Or add to Claude Desktop (settings.json)
{
  "mcpServers": {
    "ruflo": {
      "command": "npx",
      "args": ["-y", "ruflo@latest"]
    }
  }
}
```

</details>

<details>
<summary><h2>Plugin Ecosystem (20 Plugins)</h2></summary>

### Official Plugins

| Plugin | Description |
|--------|-------------|
| `@claude-flow/embeddings` | Vector embeddings with sql.js, HNSW, hyperbolic |
| `@claude-flow/security` | Input validation, path security, CVE remediation |
| `@claude-flow/claims` | Claims-based authorization |
| `@claude-flow/neural` | Neural pattern training (SONA, MoE, EWC++) |
| `@claude-flow/plugins` | Plugin system core |
| `@claude-flow/performance` | Performance profiling and benchmarking |

### Integration Plugins

| Plugin | Description |
|--------|-------------|
| `@claude-flow/plugin-agentic-qe` | Agentic quality engineering |
| `@claude-flow/plugin-prime-radiant` | Prime Radiant intelligence |
| `@claude-flow/plugin-gastown-bridge` | WASM-accelerated orchestrator |
| `@claude-flow/teammate-plugin` | Multi-agent teammate coordination |
| `@claude-flow/plugin-code-intelligence` | Advanced code analysis |
| `@claude-flow/plugin-test-intelligence` | Intelligent test generation |
| `@claude-flow/plugin-perf-optimizer` | Performance optimization |
| `@claude-flow/plugin-neural-coordinator` | Neural network coordination |

### Domain-Specific Plugins

| Plugin | Description |
|--------|-------------|
| `@claude-flow/plugin-healthcare-clinical` | Healthcare clinical workflows |
| `@claude-flow/plugin-financial-risk` | Financial risk assessment |
| `@claude-flow/plugin-legal-contracts` | Legal contract analysis |

### Install & Manage

```bash
npx ruflo plugins list                              # Browse available
npx ruflo plugins install @claude-flow/neural       # Install
npx ruflo plugins enable @claude-flow/neural        # Enable
```

Registry distributed via IPFS (Pinata) for decentralized, immutable distribution.

</details>

<details>
<summary><h2>Advanced Usage Guide</h2></summary>

### Session Persistence

```bash
# Restore previous session context
npx ruflo session restore --latest

# End session and persist everything learned
npx ruflo hooks session-end --generate-summary true --persist-state true --export-metrics true
```

### Neural Training

```bash
# Train on successful code patterns
npx ruflo neural train --pattern-type coordination --epochs 10

# Predict optimal approach for new tasks
npx ruflo neural predict --input "implement caching layer for API"

# View all learned patterns
npx ruflo neural patterns --list
```

### Security Scanning

```bash
# Full security audit
npx ruflo security scan --depth full

# Check specific CVEs
npx ruflo security cve --check

# Validate input handling
npx ruflo security validate --target ./src
```

### Dual-Mode Collaboration (Claude + Codex)

Run Claude Code and OpenAI Codex workers in parallel with shared memory:

```bash
# Use a pre-built collaboration template
npx ruflo codex dual run feature --task "Add OAuth authentication"

# Custom multi-platform swarm
npx ruflo codex dual run \
  --worker "claude:architect:Design the API structure" \
  --worker "codex:coder:Implement REST endpoints" \
  --worker "claude:tester:Write integration tests"
```

### Headless Background Instances

```bash
# Spawn parallel headless Claude instances
claude -p "Analyze src/auth/ for vulnerabilities" &
claude -p "Write tests for src/api/endpoints.ts" &
claude -p "Review src/models/ for performance issues" &
wait

# With budget limits
claude -p --max-budget-usd 0.50 "Run comprehensive security audit"
```

</details>

<details>
<summary><h2>Migration from v2.x / v3.0-alpha</h2></summary>

### Upgrading from Claude Flow v2.x

```bash
# Check migration status
npx ruflo migrate status

# Run migration with backup
npx ruflo migrate run --backup

# Validate
npx ruflo migrate validate

# Rollback if needed
npx ruflo migrate rollback
```

### Key Breaking Changes

| v2.x | v3.5 | Migration |
|------|------|-----------|
| `better-sqlite3` (native) | `sql.js` (WASM) | Automatic — no native compilation needed |
| `npx claude-flow@v3alpha` | `npx ruflo@latest` | Update scripts and MCP config (legacy aliases still work) |
| Mock implementations | Real functionality | No action — mocks replaced |
| `agentdb@2.x` | `agentdb@3.0.0-alpha.9` | Automatic schema migration |
| `agentic-flow@2.x` | `agentic-flow@3.0.0-alpha.1` | New subpath imports (bridge handles fallback) |

### Upgrading from v3.0-alpha

If already on `3.0.0-alpha.x` or `3.1.0-alpha.x`:

```bash
# Simply update — fully backward compatible
npx ruflo@latest doctor --fix

# Update MCP server to use ruflo
claude mcp remove claude-flow
claude mcp add ruflo -- npx -y ruflo@latest
```

Legacy aliases (`npx claude-flow@latest`, `npx claude-flow@alpha`) continue to work.

</details>

<details>
<summary><h2>Milestone Timeline</h2></summary>

| Version | Date | Milestone | Key Feature |
|---------|------|-----------|-------------|
| v1.0.1 | 2025-01 | Initial Release | AI agent orchestration system |
| v1.0.28 | 2025-02 | Project Management | CLI commands, SPARC templates |
| v1.0.50 | 2025-03 | Swarm & SPARC | Parallel execution, background tasks |
| v1.0.71 | 2025-04 | Final v1 | npm compatibility, cross-platform |
| v2.0.0-alpha.33 | 2025-05 | V2 Alpha | Hook safety, Neural Link System |
| v2.0.0-alpha.128 | 2025-07 | V2 Maturity | Hive-mind optimization, auto-rebuild |
| v2.7.0 | 2025-08 | agentic-flow | Coordination engine integration |
| v2.7.34 | 2025-09 | PostgreSQL | GNN, hyperbolic embeddings, CI/CD |
| v3.0.0-alpha.1 | 2025-10 | V3 Foundation | Monorepo, 215 MCP tools, RuVector |
| v3.0.0-alpha.50 | 2025-10 | Core V3 | All ADRs, hooks, claims, daemon |
| v3.0.0-alpha.100 | 2025-11 | Guidance | WASM policy kernel, ContinueGate |
| v3.0.0-alpha.150 | 2025-11 | SONA | SemanticRouter, WASM integration |
| v3.0.0-alpha.170 | 2025-12 | Plugins | Marketplace, 8 official + IPFS registry |
| v3.0.0-alpha.184 | 2025-12 | CLI Polish | Help categorization, installer script |
| v3.1.0-alpha.29 | 2026-02 | Agent Teams | Security fixes, team hooks |
| v3.1.0-alpha.55 | 2026-02 | AgentDB v3 | 8 controllers, MutationGuard |
| **v3.5.0** | **2026-02-27** | **Ruflo** | **First stable release** |

### Commit Velocity

```
2025 Q1:  ~800 commits  (v1.0 → v1.0.71)
2025 Q2:  ~1,200 commits (v2.0-alpha series)
2025 Q3:  ~1,500 commits (v2.7 + v3 planning)
2025 Q4:  ~1,800 commits (v3.0-alpha.1 → alpha.184)
2026 Q1:  ~500 commits  (v3.1 → v3.5.0 stable)
```

</details>

<details>
<summary><h2>Publishing Checklist</h2></summary>

- [ ] Merge PR #1239
- [ ] Merge PR #1239
- [ ] Build CLI: `cd v3/@claude-flow/cli && npm run build`
- [ ] Publish `ruflo@3.5.0` to npm (primary)
- [ ] Publish `claude-flow@3.5.0` to npm (legacy alias)
- [ ] Publish `@claude-flow/cli@3.5.0` to npm (scoped)
- [ ] Update dist-tags: `ruflo` (alpha, latest)
- [ ] Update dist-tags: `claude-flow` (alpha, latest, v3alpha)
- [ ] Update dist-tags: `@claude-flow/cli` (alpha, latest, v3alpha)
- [ ] Verify: `npx ruflo@latest --version` → 3.5.0
- [ ] Verify: `npx claude-flow@latest --version` → 3.5.0
- [ ] Verify: `npx @claude-flow/cli@latest --version` → 3.5.0
- [ ] Create GitHub Release with tag `v3.5.0`
- [ ] Update IPFS plugin registry with new version references

</details>

---

<div align="center">

**[Documentation](https://github.com/ruvnet/claude-flow)** | **[Issues](https://github.com/ruvnet/claude-flow/issues)** | **[Discord](https://discord.com/invite/dfxmpwkG2D)** | **[npm](https://www.npmjs.com/package/ruflo)**

*Built with love by [RuvNet](https://ruv.io) and the [Agentics Foundation](https://discord.com/invite/dfxmpwkG2D)*

</div>




Package	Version	Install
`ruflo`	3.5.0	`npx ruflo@latest` (recommended)
`claude-flow`	3.5.0	`npx claude-flow@latest` (legacy alias)
`@claude-flow/cli`	3.5.0	`npx @claude-flow/cli@latest` (scoped)

Export	Purpose	Integration Point
`agentic-flow/reasoningbank`	WASM-accelerated pattern learning	Embeddings (Tier 1), hooks, neural tools
`agentic-flow/router`	Intelligent model routing	Enhanced model router
`agentic-flow/orchestration`	Multi-agent orchestration	Bridge, doctor check
`agentic-flow/agent-booster`	Zero-cost code transforms (<1ms)	Enhanced model router (local import)
`agentic-flow/sdk`	Core SDK	Type declarations
`agentic-flow/security`	Security primitives	Type declarations
`agentic-flow/transport/quic`	QUIC network transport	Doctor check, bridge
`agentic-flow/intelligence/*`	Enhanced intelligence modules	Fallback agent-booster path

Controller	Purpose	MCP Tools
`HierarchicalMemory`	Multi-level memory hierarchies	`agentdb_hierarchical_store`, `agentdb_hierarchical_retrieve`
`MemoryConsolidation`	Cross-session memory merging	`agentdb_consolidation_run`, `agentdb_consolidation_status`
`SemanticRouter`	Intent-based query routing	`agentdb_semantic_route`, `agentdb_semantic_classify`
`GNNService`	Graph neural network inference	—
`RVFOptimizer`	RuVector field optimization	—
`MutationGuard`	Proof-verified write protection	—
`AttestationLog`	Cryptographic audit trail	—
`GuardedVectorBackend`	Verified vector operations	—

Vulnerability	Fix	Severity
Command injection in agent-booster	`SAFE_LANGUAGES` whitelist for `execSync`	Critical
TOCTOU race in bridge singleton	Promise-based caching (concurrent callers share same Promise)	Moderate
Hardcoded HMAC keys	Eliminated across codebase	High
Timing attacks	Constant-time comparison functions	High
Stale version references	22 agent/skill files updated v2→v3	Low

Metric	Value
Total commits	5,800+
Alpha iterations	55
MCP tools	215
CLI commands	26 (140+ subcommands)
Agent types	60+
Hooks	17 + 12 background workers
Plugins	20 (8 official + 12 community)
Tests passing	445
Production vulnerabilities	0
Supported platforms	Linux, macOS, Windows

Package	Purpose
`@claude-flow/cli`	CLI entry point (26 commands)
`@claude-flow/memory`	AgentDB + HNSW vector search
`@claude-flow/guidance`	Governance control plane
`@claude-flow/hooks`	17 hooks + 12 workers
`@claude-flow/security`	Input validation, CVE remediation
`@claude-flow/codex`	Dual-mode Claude + Codex collaboration
`@claude-flow/shared`	Shared types and utilities
`@claude-flow/embeddings`	Vector embeddings with sql.js
`@claude-flow/aidefence`	AI defense layer

Metric	v2.7	v3.5	Improvement
Memory search	SQLite FTS	HNSW indexed	150x-12,500x faster
Embedding generation	External API	ReasoningBank WASM	75x faster
Agent Booster transforms	npx shell-out	Local import	352x faster
Memory footprint	Full float32	Int8 quantization	3.92x reduction
CLI startup	~2s	<500ms	4x faster
MCP response	~500ms	<100ms	5x faster
SONA adaptation	N/A	<0.05ms	New capability

Tier	Handler	Latency	Cost	Use Cases
1	Agent Booster (WASM)	<1ms	$0	Simple transforms — skip LLM entirely
2	Haiku	~500ms	$0.0002	Simple tasks, low complexity
3	Sonnet/Opus	2-5s	$0.003-0.015	Complex reasoning, architecture

Category	Agents	Purpose
Core	coder, reviewer, tester, planner, researcher	General development
SPARC	specification, pseudocode, architecture, refinement, sparc-coord	Methodology
Swarm	hierarchical-coordinator, mesh-coordinator, adaptive-coordinator	Multi-agent coordination
Consensus	byzantine-coordinator, raft-manager, gossip-coordinator, crdt-synchronizer	Distributed agreement
GitHub	pr-manager, issue-tracker, release-manager, code-review-swarm, workflow-automation	Repository management
Security	security-architect, security-auditor, security-manager	Threat modeling & audit
Performance	perf-analyzer, performance-benchmarker, performance-optimizer	Optimization
Specialized	backend-dev, mobile-dev, ml-developer, cicd-engineer, api-docs	Domain-specific

Topology	Best For	Drift Risk
`hierarchical`	Small teams (6-8)	Low — central control
`hierarchical-mesh`	Large teams (10-15)	Low — queen + peer
`mesh`	Peer collaboration	Medium
`adaptive`	Dynamic workloads	Auto-adjusted

Category	Tools	Examples
Memory	11	`memory_store`, `memory_search`, `memory_retrieve`, `memory_list`
AgentDB	6	`agentdb_hierarchical_store`, `agentdb_semantic_route`, `agentdb_consolidation_run`
Agent	8	`agent_spawn`, `agent_list`, `agent_status`, `agent_stop`
Swarm	6	`swarm_init`, `swarm_status`, `swarm_stop`
Task	6	`task_create`, `task_assign`, `task_status`
Hooks	17	`hooks_pre_task`, `hooks_post_task`, `hooks_route`
Neural	5	`neural_train`, `neural_predict`, `neural_patterns`
Security	6	`security_scan`, `security_audit`, `security_cve`
Performance	5	`performance_benchmark`, `performance_profile`
Session	7	`session_start`, `session_end`, `session_restore`
Plugins	5	`plugins_list`, `plugins_install`, `plugins_enable`
+ more	133	Workflow, deployment, claims, embeddings, providers, hive-mind...

Strategy	Fault Tolerance	Use Case
`byzantine`	f < n/3 faulty	Untrusted environments
`raft`	f < n/2	Leader-based coordination
`gossip`	Eventual consistency	Large-scale propagation
`crdt`	Conflict-free	Concurrent state updates
`quorum`	Configurable	Flexible agreement

Command	Sub	Description
`init`	4	Project initialization with wizard, presets, skills, hooks
`agent`	8	Agent lifecycle (spawn, list, status, stop, metrics, pool, health, logs)
`swarm`	6	Multi-agent swarm coordination and orchestration
`memory`	11	AgentDB memory with HNSW vector search
`mcp`	9	MCP server management and tool execution
`task`	6	Task creation, assignment, and lifecycle
`session`	7	Session state management and persistence
`config`	7	Configuration management and provider setup
`status`	3	System status monitoring with watch mode
`start`	3	Service startup and quick launch
`workflow`	6	Workflow execution and template management
`hooks`	17	Self-learning hooks + 12 background workers
`hive-mind`	6	Queen-led Byzantine fault-tolerant consensus
`daemon`	5	Background worker daemon management
`neural`	5	Neural pattern training (SONA, MoE, EWC++)
`security`	6	Security scanning and vulnerability detection
`performance`	5	Performance profiling and benchmarking
`providers`	5	AI provider management
`plugins`	5	Plugin system (20 available)
`deployment`	5	Deployment and release management
`embeddings`	4	Vector embeddings (75x faster)
`claims`	4	Claims-based authorization
`migrate`	5	V2 → V3 migration with rollback
`process`	4	Background process management
`doctor`	1	System diagnostics with auto-fix
`completions`	4	Shell completions (bash, zsh, fish, powershell)

Hook	Trigger	Purpose
`pre-edit` / `post-edit`	File editing	Context loading, pattern training
`pre-command` / `post-command`	Shell commands	Risk assessment, metric tracking
`pre-task` / `post-task`	Task lifecycle	Agent suggestions, result storage
`session-start` / `session-end` / `session-restore`	Sessions	State management, persistence
`route`	Task assignment	Optimal agent selection
`explain`	Routing decisions	Decision transparency
`pretrain`	Bootstrap	Intelligence initialization
`build-agents`	Agent creation	Optimized configurations
`intelligence`	RuVector	Trajectory learning, pattern search
`transfer`	Cross-project	Pattern sharing via IPFS
`teammate-idle` / `task-completed`	Agent Teams	Auto-assignment, pattern training

Worker	Priority	Trigger
`audit`	Critical	Security changes
`optimize`	High	Performance work
`ultralearn`	Normal	Deep knowledge acquisition
`predict`	Normal	Predictive preloading
`map`	Normal	Codebase mapping
`deepdive`	Normal	Deep code analysis
`document`	Normal	Auto-documentation
`refactor`	Normal	Refactoring suggestions
`benchmark`	Normal	Performance benchmarking
`testgaps`	Normal	Test coverage analysis
`consolidate`	Low	Memory consolidation
`preload`	Low	Resource preloading

Component	Performance
SONA (Self-Optimizing Neural Architecture)	<0.05ms adaptation
MoE (Mixture of Experts)	8 specialized experts
HNSW (Hierarchical Navigable Small World)	150x-12,500x faster search
EWC++ (Elastic Weight Consolidation)	Prevents catastrophic forgetting
Flash Attention	2.49x-7.47x speedup

Plugin	Description
`@claude-flow/embeddings`	Vector embeddings with sql.js, HNSW, hyperbolic
`@claude-flow/security`	Input validation, path security, CVE remediation
`@claude-flow/claims`	Claims-based authorization
`@claude-flow/neural`	Neural pattern training (SONA, MoE, EWC++)
`@claude-flow/plugins`	Plugin system core
`@claude-flow/performance`	Performance profiling and benchmarking

Plugin	Description
`@claude-flow/plugin-agentic-qe`	Agentic quality engineering
`@claude-flow/plugin-prime-radiant`	Prime Radiant intelligence
`@claude-flow/plugin-gastown-bridge`	WASM-accelerated orchestrator
`@claude-flow/teammate-plugin`	Multi-agent teammate coordination
`@claude-flow/plugin-code-intelligence`	Advanced code analysis
`@claude-flow/plugin-test-intelligence`	Intelligent test generation
`@claude-flow/plugin-perf-optimizer`	Performance optimization
`@claude-flow/plugin-neural-coordinator`	Neural network coordination

Plugin	Description
`@claude-flow/plugin-healthcare-clinical`	Healthcare clinical workflows
`@claude-flow/plugin-financial-risk`	Financial risk assessment
`@claude-flow/plugin-legal-contracts`	Legal contract analysis

v2.x	v3.5	Migration
`better-sqlite3` (native)	`sql.js` (WASM)	Automatic — no native compilation needed
`npx claude-flow@v3alpha`	`npx ruflo@latest`	Update scripts and MCP config (legacy aliases still work)
Mock implementations	Real functionality	No action — mocks replaced
`agentdb@2.x`	`agentdb@3.0.0-alpha.9`	Automatic schema migration
`agentic-flow@2.x`	`agentic-flow@3.0.0-alpha.1`	New subpath imports (bridge handles fallback)

Version	Date	Milestone	Key Feature
v1.0.1	2025-01	Initial Release	AI agent orchestration system
v1.0.28	2025-02	Project Management	CLI commands, SPARC templates
v1.0.50	2025-03	Swarm & SPARC	Parallel execution, background tasks
v1.0.71	2025-04	Final v1	npm compatibility, cross-platform
v2.0.0-alpha.33	2025-05	V2 Alpha	Hook safety, Neural Link System
v2.0.0-alpha.128	2025-07	V2 Maturity	Hive-mind optimization, auto-rebuild
v2.7.0	2025-08	agentic-flow	Coordination engine integration
v2.7.34	2025-09	PostgreSQL	GNN, hyperbolic embeddings, CI/CD
v3.0.0-alpha.1	2025-10	V3 Foundation	Monorepo, 215 MCP tools, RuVector
v3.0.0-alpha.50	2025-10	Core V3	All ADRs, hooks, claims, daemon
v3.0.0-alpha.100	2025-11	Guidance	WASM policy kernel, ContinueGate
v3.0.0-alpha.150	2025-11	SONA	SemanticRouter, WASM integration
v3.0.0-alpha.170	2025-12	Plugins	Marketplace, 8 official + IPFS registry
v3.0.0-alpha.184	2025-12	CLI Polish	Help categorization, installer script
v3.1.0-alpha.29	2026-02	Agent Teams	Security fixes, team hooks
v3.1.0-alpha.55	2026-02	AgentDB v3	8 controllers, MutationGuard
v3.5.0	2026-02-27	Ruflo	First stable release

Ruflo v3.5.0 — Release Overview #1240

Description

From Alpha to Production — The First Major Stable Release

Quickstart

Option A: MCP Server for Claude Code

Option B: Standalone CLI

Your First Swarm

Memory & Learning

Package Aliases

What's New in v3.5.0

Rebranding: Claude Flow → Ruflo

agentic-flow v3.0.0-alpha.1 Deep Integration

AgentDB v3.0.0-alpha.9 — 8 New Controllers

Security Hardening

Doctor Health Check

Platform at a Glance

By the Numbers

Architecture

Package Ecosystem

Performance Benchmarks

v3.5 vs v2.7 Comparison

Intelligence Pipeline

3-Tier Model Routing (ADR-026)

Agent & Swarm Capabilities

60+ Specialized Agent Types

Swarm Topologies

Consensus Strategies

Hive-Mind Consensus

CLI Commands Reference

Core Commands (26 total, 140+ subcommands)

Quick Examples

Hooks & Learning System

17 Hooks + 12 Background Workers

12 Background Workers

Intelligence System (RuVector)

MCP Server (215 Tools)

Tool Categories

MCP Setup

Plugin Ecosystem (20 Plugins)

Official Plugins

Integration Plugins

Domain-Specific Plugins

Install & Manage

Advanced Usage Guide

Session Persistence

Neural Training

Security Scanning

Dual-Mode Collaboration (Claude + Codex)

Headless Background Instances

Migration from v2.x / v3.0-alpha

Upgrading from Claude Flow v2.x

Key Breaking Changes

Upgrading from v3.0-alpha

Milestone Timeline

Commit Velocity

Publishing Checklist

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions