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

Checkpoint: File edits

rUv378d5464d0d2
diff --git a/v3/CLAUDE.md b/v3/CLAUDE.md
index 682072b706..6a5c02c45b 100644
--- a/v3/CLAUDE.md
+++ b/v3/CLAUDE.md
@@ -1,405 +1,40 @@
-# Claude Code Configuration - Claude Flow V3
+# V3 Module Development
-## 🚨 AUTOMATIC SWARM ORCHESTRATION
+This directory contains the V3 monorepo packages. Root CLAUDE.md rules apply here.
-**When starting work on complex tasks, Claude Code MUST automatically:**
-
-1. **Initialize the swarm** using CLI tools via Bash
-2. **Spawn concurrent agents** using Claude Code's Task tool
-3. **Coordinate via hooks** and memory
-
-### 🚨 CRITICAL: CLI + Task Tool in SAME Message
-
-**When user says "spawn swarm" or requests complex work, Claude Code MUST in ONE message:**
-1. Call CLI tools via Bash to initialize coordination
-2. **IMMEDIATELY** call Task tool to spawn REAL working agents
-3. Both CLI and Task calls must be in the SAME response
-
-**CLI coordinates, Task tool agents do the actual work!**
-
-### πŸ”„ Auto-Start Swarm Protocol
-
-When the user requests a complex task (multi-file changes, feature implementation, refactoring), **immediately execute this pattern in a SINGLE message:**
-
-```bash
-# STEP 1: Initialize swarm coordination via CLI tool (in parallel with agent spawning)
-Bash("npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 15 --strategy adaptive")
-
-# STEP 2: Spawn agents concurrently using Claude Code's Task tool
-# ALL Task calls MUST be in the SAME message for parallel execution
-Task("Coordinator", "You are the swarm coordinator. Initialize session, coordinate other agents via memory. Run: npx @claude-flow/cli@latest hooks session-start", "hierarchical-coordinator")
-Task("Researcher", "Analyze requirements and existing code patterns. Store findings in memory via hooks.", "researcher")
-Task("Architect", "Design implementation approach based on research. Document decisions in memory.", "system-architect")
-Task("Coder", "Implement the solution following architect's design. Coordinate via hooks.", "coder")
-Task("Tester", "Write tests for the implementation. Report coverage via hooks.", "tester")
-Task("Reviewer", "Review code quality and security. Document findings.", "reviewer")
-
-# STEP 3: Batch all todos
-TodoWrite({ todos: [
- {content: "Initialize swarm coordination", status: "in_progress", activeForm: "Initializing swarm"},
- {content: "Research and analyze requirements", status: "in_progress", activeForm: "Researching requirements"},
- {content: "Design architecture", status: "pending", activeForm: "Designing architecture"},
- {content: "Implement solution", status: "pending", activeForm: "Implementing solution"},
- {content: "Write tests", status: "pending", activeForm: "Writing tests"},
- {content: "Review and finalize", status: "pending", activeForm: "Reviewing code"}
-]})
-
-# STEP 4: Store swarm state in memory via CLI
-Bash("npx @claude-flow/cli@latest memory store --namespace swarm --key current-session --value '{\"task\": \"[user task]\", \"agents\": 6}'")
-```
-
-### πŸ“‹ Agent Routing by Task Type
-
-| Task Type | Required Agents | Topology |
-|-----------|-----------------|----------|
-| Bug Fix | researcher, coder, tester | mesh |
-| New Feature | coordinator, architect, coder, tester, reviewer | hierarchical |
-| Refactoring | architect, coder, reviewer | mesh |
-| Performance | researcher, performance-engineer, coder | hierarchical |
-| Security Audit | security-architect, security-auditor, reviewer | hierarchical |
-| Memory Optimization | memory-specialist, performance-engineer | mesh |
-| Documentation | researcher, api-docs | mesh |
-
-### 🎯 Task Complexity Detection
-
-**AUTO-INVOKE SWARM when task involves:**
-- Multiple files (3+)
-- New feature implementation
-- Refactoring across modules
-- API changes with tests
-- Security-related changes
-- Performance optimization
-- Database schema changes
-
-**SKIP SWARM for:**
-- Single file edits
-- Simple bug fixes (1-2 lines)
-- Documentation updates
-- Configuration changes
-- Quick questions/exploration
-
-## 🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT
-
-**ABSOLUTE RULES**:
-1. ALL operations MUST be concurrent/parallel in a single message
-2. **NEVER save working files, text/mds and tests to the root folder**
-3. ALWAYS organize files in appropriate subdirectories
-4. **USE CLAUDE CODE'S TASK TOOL** for spawning agents concurrently, not just MCP
-
-### ⚑ GOLDEN RULE: "1 MESSAGE = ALL RELATED OPERATIONS"
-
-**MANDATORY PATTERNS:**
-- **TodoWrite**: ALWAYS batch ALL todos in ONE call (5-10+ todos minimum)
-- **Task tool (Claude Code)**: ALWAYS spawn ALL agents in ONE message with full instructions
-- **File operations**: ALWAYS batch ALL reads/writes/edits in ONE message
-- **Bash commands**: ALWAYS batch ALL terminal operations in ONE message
-- **Memory operations**: ALWAYS batch ALL memory store/retrieve in ONE message
-
-### πŸ“ File Organization Rules
-
-**NEVER save to root folder. Use these directories:**
-- `/src` - Source code files
-- `/tests` - Test files
-- `/docs` - Documentation and markdown files
-- `/config` - Configuration files
-- `/scripts` - Utility scripts
-- `/examples` - Example code
-
-## Project Configuration
-
-This project is configured with Claude Flow V3:
-- **Topology**: hierarchical
-- **Max Agents**: 15
-- **Memory Backend**: hybrid (SQLite + AgentDB)
-- **HNSW Indexing**: Enabled (150x-12,500x faster)
-- **Neural Learning**: Enabled (SONA)
-
-## πŸš€ V3 CLI Commands (26 Commands, 140+ Subcommands)
-
-### Core Commands
-
-| Command | Subcommands | 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 vector search (150x-12,500x faster) |
-| `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 |
-
-### Advanced Commands
-
-| Command | Subcommands | Description |
-|---------|-------------|-------------|
-| `daemon` | 5 | Background worker daemon (start, stop, status, trigger, enable) |
-| `neural` | 5 | Neural pattern training (train, status, patterns, predict, optimize) |
-| `security` | 6 | Security scanning (scan, audit, cve, threats, validate, report) |
-| `performance` | 5 | Performance profiling (benchmark, profile, metrics, optimize, report) |
-| `providers` | 5 | AI providers (list, add, remove, test, configure) |
-| `plugins` | 5 | Plugin management (list, install, uninstall, enable, disable) |
-| `deployment` | 5 | Deployment management (deploy, rollback, status, environments, release) |
-| `embeddings` | 4 | Vector embeddings (embed, batch, search, init) - 75x faster with agentic-flow |
-| `claims` | 4 | Claims-based authorization (check, grant, revoke, list) |
-| `migrate` | 5 | V2 to V3 migration with rollback support |
-| `process` | 4 | Background process management |
-| `doctor` | 1 | System diagnostics with health checks |
-| `completions` | 4 | Shell completions (bash, zsh, fish, powershell) |
-
-### Quick CLI Examples
+## Build & Test
```bash
-# Initialize project
-npx @claude-flow/cli@latest init --wizard
-
-# Start daemon with background workers
-npx @claude-flow/cli@latest daemon start
-
-# Spawn an agent
-npx @claude-flow/cli@latest agent spawn -t coder --name my-coder
-
-# Initialize swarm
-npx @claude-flow/cli@latest swarm init --v3-mode
-
-# Search memory (HNSW-indexed)
-npx @claude-flow/cli@latest memory search -q "authentication patterns"
-
-# System diagnostics
-npx @claude-flow/cli@latest doctor --fix
-
-# Security scan
-npx @claude-flow/cli@latest security scan --depth full
-
-# Performance benchmark
-npx @claude-flow/cli@latest performance benchmark --suite all
+# From v3/@claude-flow/<package>
+npm install && npm run build && npm test
```
-## πŸš€ Available Agents (60+ Types)
-
-### Core Development
-`coder`, `reviewer`, `tester`, `planner`, `researcher`
-
-### V3 Specialized Agents
-`security-architect`, `security-auditor`, `memory-specialist`, `performance-engineer`
-
-### Swarm Coordination
-`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator`, `collective-intelligence-coordinator`, `swarm-memory-manager`
-
-### Consensus & Distributed
-`byzantine-coordinator`, `raft-manager`, `gossip-coordinator`, `consensus-builder`, `crdt-synchronizer`, `quorum-manager`, `security-manager`
-
-### Performance & Optimization
-`perf-analyzer`, `performance-benchmarker`, `task-orchestrator`, `memory-coordinator`, `smart-agent`
-
-### GitHub & Repository
-`github-modes`, `pr-manager`, `code-review-swarm`, `issue-tracker`, `release-manager`, `workflow-automation`, `project-board-sync`, `repo-architect`, `multi-repo-swarm`
-
-### SPARC Methodology
-`sparc-coord`, `sparc-coder`, `specification`, `pseudocode`, `architecture`, `refinement`
-
-### Specialized Development
-`backend-dev`, `mobile-dev`, `ml-developer`, `cicd-engineer`, `api-docs`, `system-architect`, `code-analyzer`, `base-template-generator`
-
-### Testing & Validation
-`tdd-london-swarm`, `production-validator`
-
-## πŸͺ V3 Hooks System (17 Hooks + 12 Workers)
-
-### Hook Categories
-
-| Category | Hooks | Purpose |
-|----------|-------|---------|
-| **Core** | `pre-edit`, `post-edit`, `pre-command`, `post-command`, `pre-task`, `post-task` | Tool lifecycle |
-| **Session** | `session-start`, `session-end`, `session-restore`, `notify` | Context management |
-| **Intelligence** | `route`, `explain`, `pretrain`, `build-agents`, `transfer` | Neural learning |
-| **Learning** | `intelligence` (trajectory-start/step/end, pattern-store/search, stats, attention) | Reinforcement |
-
-### 12 Background Workers
-
-| Worker | Priority | Description |
-|--------|----------|-------------|
-| `ultralearn` | normal | Deep knowledge acquisition |
-| `optimize` | high | Performance optimization |
-| `consolidate` | low | Memory consolidation |
-| `predict` | normal | Predictive preloading |
-| `audit` | critical | Security analysis |
-| `map` | normal | Codebase mapping |
-| `preload` | low | Resource preloading |
-| `deepdive` | normal | Deep code analysis |
-| `document` | normal | Auto-documentation |
-| `refactor` | normal | Refactoring suggestions |
-| `benchmark` | normal | Performance benchmarking |
-| `testgaps` | normal | Test coverage analysis |
-
-### Essential Hook Commands
-
-```bash
-# Core hooks
-npx @claude-flow/cli@latest hooks pre-task --description "[task]"
-npx @claude-flow/cli@latest hooks post-task --task-id "[id]" --success true
-npx @claude-flow/cli@latest hooks post-edit --file "[file]" --train-patterns
-
-# Session management
-npx @claude-flow/cli@latest hooks session-start --session-id "[id]"
-npx @claude-flow/cli@latest hooks session-end --export-metrics true
-npx @claude-flow/cli@latest hooks session-restore --session-id "[id]"
-
-# Intelligence routing
-npx @claude-flow/cli@latest hooks route --task "[task]"
-npx @claude-flow/cli@latest hooks explain --topic "[topic]"
-
-# Neural learning
-npx @claude-flow/cli@latest hooks pretrain --model-type moe --epochs 10
-npx @claude-flow/cli@latest hooks build-agents --agent-types coder,tester
-
-# Background workers
-npx @claude-flow/cli@latest hooks worker list
-npx @claude-flow/cli@latest hooks worker dispatch --trigger audit
-npx @claude-flow/cli@latest hooks worker status
-```
-
-## 🧠 Intelligence System (RuVector)
-
-V3 includes the RuVector Intelligence System:
-- **SONA**: Self-Optimizing Neural Architecture (<0.05ms adaptation)
-- **MoE**: Mixture of Experts for specialized routing
-- **HNSW**: 150x-12,500x faster pattern search
-- **EWC++**: Elastic Weight Consolidation (prevents forgetting)
-- **Flash Attention**: 2.49x-7.47x speedup
-
-The 4-step intelligence pipeline:
-1. **RETRIEVE** - Fetch relevant patterns via HNSW
-2. **JUDGE** - Evaluate with verdicts (success/failure)
-3. **DISTILL** - Extract key learnings via LoRA
-4. **CONSOLIDATE** - Prevent catastrophic forgetting via EWC++
-
-## πŸ“¦ Embeddings Package (v3.0.0-alpha.12)
-
-Features:
-- **sql.js**: Cross-platform SQLite persistent cache (WASM, no native compilation)
-- **Document chunking**: Configurable overlap and size
-- **Normalization**: L2, L1, min-max, z-score
-- **Hyperbolic embeddings**: PoincarΓ© ball model for hierarchical data
-- **75x faster**: With agentic-flow ONNX integration
-- **Neural substrate**: Integration with RuVector
-
-## 🐝 Hive-Mind Consensus
-
-### Topologies
-- `hierarchical` - Queen controls workers directly
-- `mesh` - Fully connected peer network
-- `hierarchical-mesh` - Hybrid (recommended)
-- `adaptive` - Dynamic based on load
-
-### Consensus Strategies
-- `byzantine` - BFT (tolerates f < n/3 faulty)
-- `raft` - Leader-based (tolerates f < n/2)
-- `gossip` - Epidemic for eventual consistency
-- `crdt` - Conflict-free replicated data types
-- `quorum` - Configurable quorum-based
-
-## V3 Performance Targets
-
-| Metric | Target |
-|--------|--------|
-| Flash Attention | 2.49x-7.47x speedup |
-| HNSW Search | 150x-12,500x faster |
-| Memory Reduction | 50-75% with quantization |
-| MCP Response | <100ms |
-| CLI Startup | <500ms |
-| SONA Adaptation | <0.05ms |
-
-## πŸ”§ Environment Variables
-
-```bash
-# Configuration
-CLAUDE_FLOW_CONFIG=./claude-flow.config.json
-CLAUDE_FLOW_LOG_LEVEL=info
-
-# Provider API Keys
-ANTHROPIC_API_KEY=sk-ant-...
-OPENAI_API_KEY=sk-...
-GOOGLE_API_KEY=...
-
-# MCP Server
-CLAUDE_FLOW_MCP_PORT=3000
-CLAUDE_FLOW_MCP_HOST=localhost
-CLAUDE_FLOW_MCP_TRANSPORT=stdio
-
-# Memory
-CLAUDE_FLOW_MEMORY_BACKEND=hybrid
-CLAUDE_FLOW_MEMORY_PATH=./data/memory
-```
-
-## πŸ” Doctor Health Checks
-
-Run `npx @claude-flow/cli@latest doctor` to check:
-- Node.js version (20+)
-- npm version (9+)
-- Git installation
-- Config file validity
-- Daemon status
-- Memory database
-- API keys
-- MCP servers
-- Disk space
-- TypeScript installation
-
-## πŸš€ Quick Setup
-
-```bash
-# Add MCP servers (auto-detects MCP mode when stdin is piped)
-claude mcp add claude-flow -- npx -y @claude-flow/cli@alpha
-claude mcp add ruv-swarm -- npx -y ruv-swarm mcp start # Optional
-claude mcp add flow-nexus -- npx -y flow-nexus@latest mcp start # Optional
-
-# Start daemon
-npx @claude-flow/cli@latest daemon start
-
-# Run doctor
-npx @claude-flow/cli@latest doctor --fix
-```
-
-## 🎯 Claude Code vs CLI Tools
-
-### Claude Code Handles ALL EXECUTION:
-- **Task tool**: Spawn and run agents concurrently
-- File operations (Read, Write, Edit, MultiEdit, Glob, Grep)
-- Code generation and programming
-- Bash commands and system operations
-- TodoWrite and task management
-- Git operations
-
-### CLI Tools Handle Coordination (via Bash):
-- **Swarm init**: `npx @claude-flow/cli@latest swarm init --topology <type>`
-- **Swarm status**: `npx @claude-flow/cli@latest swarm status`
-- **Agent spawn**: `npx @claude-flow/cli@latest agent spawn -t <type> --name <name>`
-- **Memory store**: `npx @claude-flow/cli@latest memory store --namespace <ns> --key <k> --value <v>`
-- **Memory search**: `npx @claude-flow/cli@latest memory search -q "<query>"`
-- **Hooks**: `npx @claude-flow/cli@latest hooks <hook-name> [options]`
-
-**KEY**: CLI coordinates the strategy via Bash, Claude Code's Task tool executes with real agents.
-
-## Support
-
-- Documentation: https://github.com/ruvnet/claude-flow
-- Issues: https://github.com/ruvnet/claude-flow/issues
-
----
-
-Remember: **Claude Flow CLI coordinates, Claude Code Task tool creates!**
-
-# important-instruction-reminders
-Do what has been asked; nothing more, nothing less.
-NEVER create files unless they're absolutely necessary for achieving your goal.
-ALWAYS prefer editing an existing file to creating a new one.
-NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
-Never save working files, text/mds and tests to the root folder.
-After spawning a swarm, wait, don't continuously check status.
-
+## Packages
+
+| Package | Path | Purpose |
+|---------|------|---------|
+| `@claude-flow/cli` | `@claude-flow/cli/` | CLI entry point (26 commands, 140+ subcommands) |
+| `@claude-flow/guidance` | `@claude-flow/guidance/` | Governance control plane (compile, enforce, prove, evolve) |
+| `@claude-flow/hooks` | `@claude-flow/hooks/` | 17 hooks + 12 background workers |
+| `@claude-flow/memory` | `@claude-flow/memory/` | AgentDB + HNSW vector search |
+| `@claude-flow/shared` | `@claude-flow/shared/` | Shared types and utilities |
+| `@claude-flow/security` | `@claude-flow/security/` | Input validation, path security, CVE remediation |
+
+## Code Quality
+
+- Files under 500 lines
+- No hardcoded secrets
+- Input validation at system boundaries
+- Typed interfaces for all public APIs
+- TDD London School (mock-first) preferred
+- Event sourcing for state changes
+
+## Performance Targets
+
+| Metric | Target | Status |
+|--------|--------|--------|
+| HNSW Search | 150x-12,500x faster | Implemented |
+| Memory Reduction | 50-75% (Int8 quantization) | Implemented |
+| MCP Response | <100ms | Achieved |
+| CLI Startup | <500ms | Achieved |
+| Flash Attention | 2.49x-7.47x speedup | In progress |