V3 Architecture Decision Records (ADRs)

This directory contains all Architecture Decision Records for Claude-Flow v3.

Status: ✅ BETA READY (22 ADRs Complete) Version: 3.0.0-alpha.84 Last Updated: 2026-01-13

ADR Index

Core Architecture (ADR-001 to ADR-010)

Providers & Security (ADR-011 to ADR-017)

Advanced Features (ADR-018 to ADR-025)

Neural & Integration (ADR-026 to ADR-031)

Packaging & Branding (ADR-042 to ADR-048)

RuVector WASM Plugin Architecture (ADR-032 to ADR-041)

Implementation Progress

Last Updated: 2026-01-13 (Beta Ready Audit) Status: ✅ READY FOR 3.0.0-beta.1

Overall V3 Implementation: 100% Complete

Beta Readiness Checklist

Quick Summary

Core Decisions

1. ADR-001: Build on agentic-flow@alpha instead of duplicating (eliminates 10,000+ lines)
2. ADR-002: Domain-Driven Design with bounded contexts for clean architecture
3. ADR-003: Single UnifiedSwarmCoordinator as canonical coordination engine
4. ADR-004: Microkernel with plugins for optional features (HiveMind, Neural, etc.)
5. ADR-005: MCP tools as primary API, CLI as thin wrapper

Technical Decisions

6. ADR-006: Single MemoryService with SQLite, AgentDB, or Hybrid backends
7. ADR-007: Event sourcing for audit trail and state reconstruction
8. ADR-008: Vitest for 10x faster testing with native ESM
9. ADR-009: Hybrid backend (SQLite + AgentDB) as default for best performance
10. ADR-010: Node.js 20+ only, removing Deno complexity

Additional Files

• v3-adrs.md - Complete ADR master document with all decisions
• ADR-003-implementation-status.md - Detailed implementation tracking

Performance Targets (from ADRs)

Security Improvements

All ADRs consider security:

• CVE-1: Command injection prevention (ADR-005 input validation)
• CVE-2: Path traversal prevention (ADR-006 memory sandboxing)
• CVE-3: Credential generation (secure random with rejection sampling)

Last Updated: 2026-01-13 Project: Claude-Flow V3 Version: 3.0.0-alpha.84 (Beta Ready)

Recent Updates (2026-01-13)

Release: @claude-flow/[email protected] (Beta Ready)

All Audit Issues Resolved:

Auto-Update System (ADR-025):

npx claude-flow update check      # Check for updates
npx claude-flow update all        # Update all packages
npx claude-flow update history    # View update history
npx claude-flow update rollback   # Rollback last update

Previous Updates (2026-01-07)

Release: @claude-flow/[email protected] (Latest)

Doctor Command Enhancements:

• Claude Code CLI Check: Verifies @anthropic-ai/claude-code installation
• Auto-Install: --install flag to auto-install missing Claude Code CLI
• Fixed Package Paths: Corrected dist/src/ paths for proper npm resolution

# Check system health including Claude Code CLI
npx claude-flow@v3alpha doctor

# Auto-install Claude Code CLI if missing
npx claude-flow@v3alpha doctor --install

# Check only Claude Code CLI
npx claude-flow@v3alpha doctor -c claude

Package Resolution Fix: Fixed Windows module resolution issue where @claude-flow/cli exports pointed to wrong paths (dist/index.js → dist/src/index.js).

Release: @claude-flow/[email protected]

• Hive-Mind CLI: All MCP tools now exposed via CLI subcommands:
  • hive-mind join <agent-id> - Join agent to hive
  • hive-mind leave <agent-id> - Remove agent from hive
  • hive-mind consensus - Manage consensus proposals and voting
  • hive-mind broadcast -m <msg> - Broadcast messages to workers
  • hive-mind memory - Access shared memory (get/set/delete/list)
• Bug Fix: Fixed positional argument parsing for subcommands in CLI parser
• File Persistence: All MCP tools use file-based persistence in .claude-flow/ directories
• ADR-014: Node.js Worker Daemon - cross-platform TypeScript daemon replaces shell helpers
• CLI: daemon command with start/stop/status/trigger/enable subcommands
• Session Integration: Auto-start daemon on SessionStart, auto-stop on SessionEnd

CLI MCP Tool Coverage

Install

npx @claude-flow/cli@v3alpha --help

Release: @claude-flow/[email protected] (2026-01-07)

New V3 Advanced CLI Commands

All commands include subcommand help and "Created with ❤️ by ruv.io" branding.

P0 Features Completed (alpha.12)

Smart Error Suggestions: Typo detection with Levenshtein distance

$ claude-flow swram
[ERROR] Unknown command: swram
  Did you mean one of these?
  - swarm
  - neural
  - start

$ claude-flow memroy
[ERROR] Unknown command: memroy
  Did you mean "memory"?

Doctor Command: System health diagnostics

$ claude-flow doctor
Claude Flow Doctor
──────────────────────────────────────────────────
✓ Node.js Version: v22.21.1 (>= 20 required)
✓ npm Version: v10.9.4
✓ Git: v2.52.0
✓ Git Repository: In a git repository
⚠ Config File: No config file (using defaults)
⚠ Daemon Status: Not running
⚠ Memory Database: Not initialized
⚠ API Keys: No API keys found
⚠ MCP Servers: No MCP config found
✓ Disk Space: 73G available
✓ TypeScript: v5.9.3
──────────────────────────────────────────────────
Summary: 6 passed, 5 warnings

Shell Completions: Tab completion for all shells

# Install bash completions
claude-flow completions bash > ~/.bash_completion.d/claude-flow

# Install zsh completions
claude-flow completions zsh > ~/.zfunc/_claude-flow

# Install fish completions
claude-flow completions fish > ~/.config/fish/completions/claude-flow.fish

# Install PowerShell completions
claude-flow completions powershell >> $PROFILE

CLI Roadmap

Priority Recommendations

Implementation Plan

P0 - Critical (Next Release)

# Doctor command - diagnose system health
claude-flow doctor              # Full system check
claude-flow doctor --fix        # Auto-fix issues where possible
claude-flow doctor --component mcp  # Check specific component

# Shell completions
claude-flow completions bash > ~/.bash_completion.d/claude-flow
claude-flow completions zsh > ~/.zfunc/_claude-flow
claude-flow completions fish > ~/.config/fish/completions/claude-flow.fish

P1 - High Priority

# Unified logs command
claude-flow logs                # All logs
claude-flow logs --follow       # Tail logs
claude-flow logs --component daemon
claude-flow logs --level error

P2 - Nice to Have

# Self-update
claude-flow upgrade             # Upgrade to latest
claude-flow upgrade --check     # Check for updates
claude-flow upgrade --version 3.1.0

# Interactive shell
claude-flow shell               # Enter REPL
> swarm init mesh
> agent spawn coder
> memory search "patterns"

agentic-flow vs claude-flow Feature Comparison

Feature Matrix

High-Value Integration Opportunities

🔴 Tier 1: Highest Impact (Unique to agentic-flow)

1. QUIC Transport (50-70% faster)

# Integration target:
claude-flow transport quic --port 4433
claude-flow swarm start --transport quic  # 50-70% faster agent comms

2. Federation Hub (Ephemeral Agents)

# Integration target:
claude-flow federation start --port 9443
claude-flow federation spawn --tenant acme --lifetime 600

Value: Agents die but memories persist → learning across agent generations

3. Model Optimization (85% cost savings)

# Integration target:
claude-flow agent spawn -t coder --optimize --priority cost
claude-flow providers optimize --task "Build API" --budget 0.01

4. Provider Fallback (Enterprise resilience)

# Integration target:
claude-flow providers fallback configure --primary anthropic --fallback openrouter,onnx

5. ReasoningBank (WASM Learning Memory)

# Integration target:
claude-flow reasoningbank store "pattern" --reasoning "..."
claude-flow reasoningbank search "authentication patterns"

Value: 10-100x faster reasoning pattern storage vs JSON

🟡 Tier 2: Medium Impact

Integration Roadmap

Phase 1: Quick Wins (1 week) → 9.3 → 9.5

# After Phase 1:
claude-flow agent spawn -t coder --optimize --priority cost
claude-flow providers fallback configure --primary anthropic --fallback openrouter,onnx
claude-flow embeddings download all-MiniLM-L6-v2

Phase 2: Core Integration (2-3 weeks) → 9.5 → 9.7

# After Phase 2:
claude-flow federation start --port 9443
claude-flow federation spawn --lifetime 300 --task "Quick analysis"
claude-flow proxy start --provider openrouter
claude-flow daemon dispatch security-audit

Phase 3: Advanced (4-6 weeks) → 9.7 → 9.9

# After Phase 3:
claude-flow swarm start --transport quic  # 50-70% faster
claude-flow reasoningbank store "pattern" --reasoning "..."
claude-flow agent spawn -t security-analyst  # One of 66 types

Recommended Integration Approach

Option A: Dependency Approach (Fastest)

// claude-flow/package.json
{
  "dependencies": {
    "agentic-flow": "^2.0.3"
  }
}

Option B: Port Code (More Control)

# Copy specific modules:
- agentic-flow/src/transport/quic.ts → claude-flow/src/transport/
- agentic-flow/src/federation/ → claude-flow/src/federation/
- agentic-flow/src/reasoningbank/ → claude-flow/src/reasoningbank/

Option C: Unified Package (Long-term)

@claude-flow/core      # Shared primitives
@claude-flow/cli       # CLI (current)
@claude-flow/agents    # From agentic-flow's 66 agents
@claude-flow/transport # QUIC + HTTP + WebSocket

ruvector Integration Analysis

Package Overview

Feature Overlap Analysis

claude-flow ALREADY HAS (via @claude-flow/embeddings):

Unique ruvector Features (Integration Candidates)

🔴 Tier 1: High Value (claude-flow lacks these)

🟡 Tier 2: Medium Value

🟢 Tier 3: Nice to Have

Note: Flash Attention, SONA Learning, HNSW, and ONNX embeddings are already in claude-flow via agentic-flow.

MCP Tools from ruvector (Unique Only)

# Add ruvector MCP server (for unique features)
claude mcp add ruvector-mcp -- npx ruvector mcp-server

Unique Tools Worth Integrating:

• hooks_route, hooks_route_enhanced — Q-Learning agent routing (80%+ accuracy) ✅
• hooks_ast_analyze, hooks_ast_complexity — Code structure analysis ✅
• hooks_diff_analyze, hooks_diff_classify — Change classification ✅
• hooks_coverage_route, hooks_coverage_suggest — Test-aware routing ✅
• hooks_graph_mincut, hooks_graph_cluster — Code boundaries ✅

Already in claude-flow (skip):

• hooks_rag_context — Use @claude-flow/memory instead
• hooks_attention_info — Use @claude-flow/neural instead
• Embeddings tools — Use @claude-flow/embeddings instead

Integration Approach

Recommended: Option A - Add as Optional Dependency (for unique features only)

// @claude-flow/cli/package.json
{
  "optionalDependencies": {
    "ruvector": "^0.1.95"
  }
}

CLI Wrappers (unique ruvector features):

# Q-Learning agent routing (unique to ruvector)
claude-flow route "task" --q-learning          # Uses hooks_route

# AST analysis (unique to ruvector)
claude-flow analyze ast src/                   # Uses hooks_ast_analyze

# Diff classification (unique to ruvector)
claude-flow analyze diff --risk                # Uses hooks_diff_analyze

# Coverage-aware routing (unique to ruvector)
claude-flow route "task" --coverage-aware      # Uses hooks_coverage_route

Already in claude-flow (DO NOT import from ruvector):

claude-flow embeddings generate --local        # Uses @claude-flow/embeddings (ONNX)
claude-flow memory search --semantic "query"   # Uses @claude-flow/memory (HNSW)

ruvector Integration Roadmap

Phase 1: Q-Learning Router (1-2 days)

• Add ruvector as optional dependency
• Implement hooks route --q-learning wrapper
• Add info --ruvector command for capability detection

Phase 2: Code Intelligence (1 week)

• Integrate AST analysis commands (analyze ast)
• Implement diff classification (analyze diff --risk)
• Add coverage-aware routing (route --coverage-aware)

Phase 3: Graph Analysis (2 weeks)

• Implement MinCut boundaries (analyze --boundaries)
• Add Louvain community detection (analyze --modules)
• Integrate GNN layers for dependency graphs

Note: SONA, Flash Attention, HNSW already in claude-flow - no need to import.