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 edit:

rUv0f289f5b147b
diff --git a/README.md b/README.md
index 60f8e8513f..9cc28733a6 100644
--- a/README.md
+++ b/README.md
@@ -47,19 +47,75 @@ npx claude-flow mcp start
# Run a task with agents
npx claude-flow --agent coder --task "Implement user authentication"
+
+# List available agents
+npx claude-flow --list
```
---
## Features
-- **54+ Specialized Agents** - Coder, reviewer, tester, security-architect, performance-engineer, and more
+### Core Capabilities
+
+- **54+ Specialized Agents** - Purpose-built agents for every development task
- **Swarm Coordination** - Hierarchical, mesh, and adaptive topologies for parallel execution
-- **Self-Learning Hooks** - ReasoningBank pattern learning with 150x faster HNSW search
+- **Self-Learning Hooks** - ReasoningBank pattern learning with HNSW vector search
- **MCP Integration** - Native Claude Code support via Model Context Protocol
- **Security-First** - Input validation, path traversal prevention, safe command execution
- **Cross-Platform** - Windows, macOS, and Linux support
+### Advanced Features
+
+- Automatic Topology Selection
+- Parallel Execution (2.8-4.4x speed improvement)
+- Neural Training with 27+ models
+- Bottleneck Analysis
+- Smart Auto-Spawning
+- Self-Healing Workflows
+- Cross-Session Memory
+- GitHub Integration
+
+---
+
+## Available Agents (54+)
+
+### V3 Specialized Swarm Agents (15-Agent Concurrent)
+
+| Agent | Purpose |
+|-------|---------|
+| `queen-coordinator` | V3 orchestration & GitHub issue management |
+| `security-architect` | Security architecture & threat modeling |
+| `security-auditor` | CVE remediation & security testing |
+| `memory-specialist` | AgentDB unification (150x-12,500x faster) |
+| `swarm-specialist` | Unified coordination engine |
+| `integration-architect` | agentic-flow@alpha deep integration |
+| `performance-engineer` | 2.49x-7.47x optimization targets |
+| `core-architect` | Domain-driven design restructure |
+| `test-architect` | TDD London School methodology |
+| `project-coordinator` | Cross-domain coordination |
+
+### Core Development
+`coder`, `reviewer`, `tester`, `planner`, `researcher`
+
+### 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`
+
---
## Use Cases
@@ -71,26 +127,182 @@ npx claude-flow --agent coder --task "Implement user authentication"
| Security audit | `npx claude-flow --agent security-architect --task "Audit for vulnerabilities"` |
| Multi-agent swarm | `npx claude-flow swarm init --topology hierarchical` |
| Route task | `npx claude-flow hooks route "Optimize database queries"` |
+| Performance analysis | `npx claude-flow --agent perf-analyzer --task "Profile API endpoints"` |
+| GitHub PR management | `npx claude-flow --agent pr-manager --task "Review open PRs"` |
+
+---
+
+## Self-Learning Hooks System
+
+### Available Commands
+
+```bash
+# Before editing - get context and agent suggestions
+npx claude-flow hooks pre-edit <filePath>
+
+# After editing - record outcome for learning
+npx claude-flow hooks post-edit <filePath> --success true
+
+# Before commands - assess risk
+npx claude-flow hooks pre-command "<command>"
+
+# After commands - record outcome
+npx claude-flow hooks post-command "<command>" --success true
+
+# Route task to optimal agent using learned patterns
+npx claude-flow hooks route "<task description>"
+
+# Explain routing decision with transparency
+npx claude-flow hooks explain "<task description>"
+
+# Bootstrap intelligence from repository
+npx claude-flow hooks pretrain
+
+# Generate optimized agent configs from pretrain data
+npx claude-flow hooks build-agents
+
+# View learning metrics dashboard
+npx claude-flow hooks metrics
+
+# Transfer patterns from another project
+npx claude-flow hooks transfer <sourceProject>
+
+# RuVector intelligence (SONA, MoE, HNSW 150x faster)
+npx claude-flow hooks intelligence
+```
+
+### Pretraining Pipeline
+
+1. **RETRIEVE** - Top-k memory injection with MMR diversity
+2. **JUDGE** - LLM-as-judge trajectory evaluation
+3. **DISTILL** - Extract strategy memories from trajectories
+4. **CONSOLIDATE** - Dedup, detect contradictions, prune old patterns
+
+---
+
+## MCP Tools
+
+### Coordination
+`swarm_init`, `agent_spawn`, `task_orchestrate`
+
+### Monitoring
+`swarm_status`, `agent_list`, `agent_metrics`, `task_status`, `task_results`
+
+### Memory & Neural
+`memory_usage`, `neural_status`, `neural_train`, `neural_patterns`
+
+### GitHub Integration
+`github_swarm`, `repo_analyze`, `pr_enhance`, `issue_triage`, `code_review`
---
## Architecture
+### V3 Module Structure
+
```
v3/
β”œβ”€β”€ @claude-flow/hooks # Event-driven lifecycle hooks
-β”œβ”€β”€ @claude-flow/memory # AgentDB vector storage
+β”œβ”€β”€ @claude-flow/memory # AgentDB unification module
β”œβ”€β”€ @claude-flow/security # CVE remediation & patterns
β”œβ”€β”€ @claude-flow/swarm # 15-agent coordination
-└── @claude-flow/plugins # RuVector WASM plugins
+β”œβ”€β”€ @claude-flow/plugins # RuVector WASM plugins
+β”œβ”€β”€ @claude-flow/cli # CLI modernization
+β”œβ”€β”€ @claude-flow/neural # SONA learning integration
+β”œβ”€β”€ @claude-flow/testing # TDD London School framework
+β”œβ”€β”€ @claude-flow/deployment # Release & CI/CD
+└── @claude-flow/shared # Shared utilities & types
+```
+
+### Domain-Driven Design Structure
+
```
+src/
+β”œβ”€β”€ agent-lifecycle/ # Bounded Context 1
+β”‚ β”œβ”€β”€ domain/ # Business logic
+β”‚ β”œβ”€β”€ application/ # Use cases
+β”‚ β”œβ”€β”€ infrastructure/ # Persistence
+β”‚ └── api/ # CLI, MCP interfaces
+β”œβ”€β”€ task-execution/ # Bounded Context 2
+β”œβ”€β”€ memory-management/ # Bounded Context 3
+β”œβ”€β”€ coordination/ # Bounded Context 4
+β”œβ”€β”€ shared-kernel/ # Shared utilities
+└── infrastructure/ # Cross-cutting concerns
+```
+
+### Architecture Decision Records (ADRs)
+
+| ADR | Decision |
+|-----|----------|
+| ADR-001 | Adopt agentic-flow as core foundation (eliminate 10,000+ duplicate lines) |
+| ADR-002 | Domain-Driven Design structure (bounded contexts) |
+| ADR-003 | Single coordination engine (unified SwarmCoordinator) |
+| ADR-004 | Plugin-based architecture (microkernel pattern) |
+| ADR-005 | MCP-first API design (consistent interfaces) |
+| ADR-006 | Unified memory service (AgentDB integration) |
+| ADR-007 | Event sourcing for state changes (audit trail) |
+| ADR-008 | Vitest over Jest (10x faster testing) |
+| ADR-009 | Hybrid memory backend default (SQLite + AgentDB) |
+| ADR-010 | Remove Deno support (Node.js 20+ focus) |
+
+---
## Performance
-- **84.8%** SWE-Bench solve rate
-- **2.8-4.4x** speed improvement with parallel execution
-- **150x-12,500x** faster vector search with HNSW indexing
-- **32.3%** token reduction through pattern learning
+### Benchmarks
+
+| Metric | Result |
+|--------|--------|
+| SWE-Bench solve rate | **84.8%** |
+| Speed improvement | **2.8-4.4x** with parallel execution |
+| Token reduction | **32.3%** through pattern learning |
+| Neural models | **27+** available |
+
+### V3 Performance Targets
+
+| Target | Improvement |
+|--------|-------------|
+| Flash Attention | 2.49x-7.47x speedup |
+| AgentDB Search | 150x-12,500x faster |
+| Memory Reduction | 50-75% |
+| Code Reduction | <5,000 lines (vs 15,000+) |
+| Startup Time | <500ms |
+| SONA Learning | <0.05ms adaptation |
+
+---
+
+## Cross-Platform Support
+
+### Windows (PowerShell)
+
+```powershell
+npx @claude-flow/security@latest audit --platform windows
+$env:CLAUDE_FLOW_MODE = "integration"
+```
+
+### macOS (Bash/Zsh)
+
+```bash
+npx @claude-flow/security@latest audit --platform darwin
+export CLAUDE_FLOW_SECURITY_MODE="strict"
+```
+
+### Linux (Bash)
+
+```bash
+npx @claude-flow/security@latest audit --platform linux
+export CLAUDE_FLOW_MEMORY_PATH="./data"
+```
+
+---
+
+## Security
+
+- **Input Validation** - All inputs validated at boundaries
+- **Path Traversal Prevention** - Safe path handling
+- **Command Injection Protection** - Allowlisted commands only
+- **Prototype Pollution Prevention** - Safe JSON parsing
+- **CVE Remediation** - Active security monitoring
---
@@ -99,6 +311,13 @@ v3/
- [V2 Documentation](./v2/README.md)
- [Architecture Decisions](./v3/docs/adr/)
- [API Reference](./v2/docs/technical/)
+- [Examples](./v2/examples/)
+
+## Support
+
+- Documentation: https://github.com/ruvnet/claude-flow
+- Issues: https://github.com/ruvnet/claude-flow/issues
+- Discord: [Agentics Foundation](https://discord.com/invite/dfxmpwkG2D)
## License