π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
Checkpoint: File edits
rUvd5fbd22d2398
diff --git a/agents/architect.yaml b/agents/architect.yamlindex 02a96e925f..f5d8373638 100644--- a/agents/architect.yaml+++ b/agents/architect.yaml@@ -8,4 +8,4 @@ capabilities:optimizations:- context-caching- memory-persistence-createdAt: "2026-01-13T20:54:33.737Z"+createdAt: "2026-01-13T23:09:59.994Z"diff --git a/agents/coder.yaml b/agents/coder.yamlindex 48049846bc..117fb182d8 100644--- a/agents/coder.yaml+++ b/agents/coder.yaml@@ -8,4 +8,4 @@ capabilities:optimizations:- flash-attention- token-reduction-createdAt: "2026-01-13T20:54:33.737Z"+createdAt: "2026-01-13T23:09:59.994Z"diff --git a/agents/reviewer.yaml b/agents/reviewer.yamlindex ba8e0377fd..3425bdbdc6 100644--- a/agents/reviewer.yaml+++ b/agents/reviewer.yaml@@ -7,4 +7,4 @@ capabilities:- best-practicesoptimizations:- incremental-analysis-createdAt: "2026-01-13T20:54:33.737Z"+createdAt: "2026-01-13T23:09:59.994Z"diff --git a/agents/security-architect.yaml b/agents/security-architect.yamlindex 3001bcbdd8..1b2df58f3c 100644--- a/agents/security-architect.yaml+++ b/agents/security-architect.yaml@@ -7,4 +7,4 @@ capabilities:- security-reviewoptimizations:- pattern-matching-createdAt: "2026-01-13T20:54:33.737Z"+createdAt: "2026-01-13T23:09:59.994Z"diff --git a/agents/tester.yaml b/agents/tester.yamlindex 8983305e4c..bf72b53485 100644--- a/agents/tester.yaml+++ b/agents/tester.yaml@@ -7,4 +7,4 @@ capabilities:- coverageoptimizations:- parallel-execution-createdAt: "2026-01-13T20:54:33.737Z"+createdAt: "2026-01-13T23:09:59.994Z"diff --git a/package-lock.json b/package-lock.jsonindex 4e7f25486c..4c7c91a7b4 100644--- a/package-lock.json+++ b/package-lock.json@@ -1,12 +1,12 @@{"name": "claude-flow-v3",- "version": "3.0.0-alpha.43",+ "version": "3.0.0-alpha.44","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "claude-flow-v3",- "version": "3.0.0-alpha.43",+ "version": "3.0.0-alpha.44","license": "MIT","dependencies": {"agentdb": "alpha",diff --git a/package.json b/package.jsonindex 209c19cf21..c89815712d 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "claude-flow",- "version": "3.0.0-alpha.43",+ "version": "3.0.0-alpha.44","description": "Claude Flow V3 - Domain-Driven Design Architecture with 15-Agent Swarm Coordination","main": "dist/index.js","type": "module",diff --git a/v3/@claude-flow/cli/README.md b/v3/@claude-flow/cli/README.mddeleted file mode 120000index 8a33348c7d..0000000000--- a/v3/@claude-flow/cli/README.md+++ /dev/null@@ -1 +0,0 @@-../../../README.md\ No newline at end of filediff --git a/v3/@claude-flow/cli/README.md b/v3/@claude-flow/cli/README.mdnew file mode 100644index 0000000000..423937a440--- /dev/null+++ b/v3/@claude-flow/cli/README.md@@ -0,0 +1,1143 @@+# Claude-Flow v3: Enterprise AI Orchestration Platform++<div align="center">++[](https://github.com/ruvnet/claude-flow)+[](https://www.npmjs.com/package/claude-flow)+[](https://www.npmjs.com/package/claude-flow)+[](https://github.com/ruvnet/claude-flow)+[](https://discord.com/invite/dfxmpwkG2D)+[](https://opensource.org/licenses/MIT)++**Production-ready multi-agent AI orchestration for Claude Code**++*Deploy 54+ specialized agents in coordinated swarms with self-learning capabilities, fault-tolerant consensus, and enterprise-grade security.*++</div>++## Overview++Claude-Flow is a comprehensive AI agent orchestration framework that transforms Claude Code into a powerful multi-agent development platform. It enables teams to deploy, coordinate, and optimize specialized AI agents working together on complex software engineering tasks.++### Claude Code: With vs Without Claude-Flow++| Capability | Claude Code Alone | Claude Code + Claude-Flow |+|------------|-------------------|---------------------------|+| **Agent Collaboration** | Agents work in isolation, no shared context | Agents collaborate via swarms with shared memory and consensus |+| **Coordination** | Manual orchestration between tasks | Queen-led hierarchy with 5 consensus algorithms (Raft, Byzantine, Gossip) |+| **Memory** | Session-only, no persistence | HNSW vector memory with 150x-12,500x faster retrieval |+| **Learning** | Static behavior, no adaptation | SONA self-learning with <0.05ms adaptation, improves over time |+| **Task Routing** | You decide which agent to use | Intelligent routing based on learned patterns (89% accuracy) |+| **Complex Tasks** | Manual breakdown required | Automatic decomposition across 5 domains (Security, Core, Integration, Support) |+| **Background Workers** | Nothing runs automatically | 12 context-triggered workers auto-dispatch on file changes, patterns, sessions |+| **LLM Provider** | Anthropic only | 6 providers with automatic failover and cost-based routing (85% savings) |+| **Security** | Standard protections | CVE-hardened with bcrypt, input validation, path traversal prevention |+| **Performance** | Baseline | 2.8-4.4x faster tasks, 4-32x memory reduction via quantization |++### Key Capabilities++- **54+ Specialized Agents** - Ready-to-use AI agents for coding, code review, testing, security audits, documentation, and DevOps tasks. Each agent is optimized for its specific role.++- **Coordinated Agent Teams** - Run unlimited agents simultaneously in organized swarms. Agents can spawn sub-workers, communicate, share context, and divide work automatically using patterns like hierarchical (queen/workers) or mesh (peer-to-peer).++- **Learns From Your Workflow** - The system remembers what works. Successful patterns are stored and reused, routing similar tasks to the best-performing agents. Gets smarter over time.++- **Works With Any LLM** - Switch between Claude, GPT-4, Gemini, Cohere, or local models like Llama. Automatic failover if one provider is unavailable. Smart routing picks the cheapest option that meets quality requirements.++- **Plugs Into Claude Code** - Native integration via MCP (Model Context Protocol). Use claude-flow commands directly in your Claude Code sessions with full tool access.++- **Production-Ready Security** - Built-in protection against common vulnerabilities: input validation, path traversal prevention, command injection blocking, and safe credential handling.++---++## Quick Start++### Prerequisites++- **Node.js 18+** or **Bun 1.0+** (Bun is faster)+- **npm 9+** / **pnpm** / **bun** package manager++**IMPORTANT**: Claude Code must be installed first:++```bash+# 1. Install Claude Code globally+npm install -g @anthropic-ai/claude-code++# 2. (Optional) Skip permissions check for faster setup+claude --dangerously-skip-permissions+```++### Installation++```bash+# With npm/npx (Node.js)+npm install claude-flow@v3alpha+npx claude-flow@v3alpha init++# With Bun (faster)+bun add claude-flow@v3alpha+bunx claude-flow@v3alpha init++# Start MCP server for Claude Code integration+npx claude-flow@v3alpha mcp start++# Run a task with agents+npx claude-flow@v3alpha --agent coder --task "Implement user authentication"++# List available agents+npx claude-flow@v3alpha --list+```++---++## Features++### Core Platform Capabilities++| Capability | Description | Metrics |+|------------|-------------|---------|+| **54+ Specialized Agents** | Purpose-built AI agents for development, testing, security, and operations | 10 categories, unlimited concurrent |+| **Multi-Topology Swarms** | Hierarchical, mesh, ring, star, and adaptive coordination patterns | 2.8-4.4x speed improvement |+| **Self-Learning Hooks** | ReasoningBank pattern learning with HNSW vector search | 150x faster retrieval |+| **MCP Integration** | Native Claude Code support via Model Context Protocol | 27+ tools available |+| **Security-First Design** | Input validation, path traversal prevention, command sandboxing | CVE-1, CVE-2, CVE-3 addressed |+| **Cross-Platform** | Full support for Windows, macOS, and Linux environments | Node.js 18+ |++### Agent Ecosystem++| Category | Agent Count | Key Agents | Purpose |+|----------|-------------|------------|---------|+| **Core Development** | 5 | coder, reviewer, tester, planner, researcher | Daily development tasks |+| **V3 Specialized** | 10 | queen-coordinator, security-architect, memory-specialist | Enterprise orchestration |+| **Swarm Coordination** | 5 | hierarchical-coordinator, mesh-coordinator, adaptive-coordinator | Multi-agent patterns |+| **Consensus & Distributed** | 7 | byzantine-coordinator, raft-manager, gossip-coordinator | Fault-tolerant coordination |+| **Performance** | 5 | perf-analyzer, performance-benchmarker, task-orchestrator | Optimization & monitoring |+| **GitHub & Repository** | 9 | pr-manager, code-review-swarm, issue-tracker, release-manager | Repository automation |+| **SPARC Methodology** | 6 | sparc-coord, specification, pseudocode, architecture | Structured development |+| **Specialized Dev** | 8 | backend-dev, mobile-dev, ml-developer, cicd-engineer | Domain expertise |++### Swarm Topologies++| Topology | Recommended Agents | Best For | Execution Time | Memory/Agent |+|----------|-------------------|----------|----------------|--------------|+| **Hierarchical** | 6+ | Structured tasks, clear authority chains | 0.20s | 256 MB |+| **Mesh** | 4+ | Collaborative work, high redundancy | 0.15s | 192 MB |+| **Ring** | 3+ | Sequential processing pipelines | 0.12s | 128 MB |+| **Star** | 5+ | Centralized control, spoke workers | 0.14s | 180 MB |+| **Hybrid (Hierarchical-Mesh)** | 7+ | Complex multi-domain tasks | 0.18s | 320 MB |+| **Adaptive** | 2+ | Dynamic workloads, auto-scaling | Variable | Dynamic |++### Self-Learning & Intelligence++| Feature | Technology | Performance | Description |+|---------|------------|-------------|-------------|+| **ReasoningBank** | HNSW Vector Search | 150x faster | Pattern storage with similarity-based retrieval |+| **SONA Neural** | LoRA Fine-tuning | <0.05ms adaptation | Self-optimizing neural architecture |+| **Pattern Learning** | EWC++ Memory | Zero forgetting | Continuous learning without catastrophic forgetting |+| **Intent Routing** | MoE (Mixture of Experts) | 95%+ accuracy | Intelligent task-to-agent routing |+| **Domain Detection** | Vector Clustering | Real-time | Automatic categorization (security, testing, performance) |+| **Quality Tracking** | Success/Failure Metrics | Per-pattern | Historical performance tracking |++### Memory & Storage++| Backend | Technology | Performance | Use Case |+|---------|------------|-------------|----------|+| **AgentDB** | HNSW Indexing | 150x-12,500x faster | Primary vector storage |+| **SQLite** | Relational DB | Standard | Metadata and structured data |+| **Hybrid** | AgentDB + SQLite | Best of both | Recommended default |+| **In-Memory** | RAM-based | Fastest | Temporary/session data |++### MCP Tools & Integration++| Category | Tools | Description |+|----------|-------|-------------|+| **Coordination** | `swarm_init`, `agent_spawn`, `task_orchestrate` | Swarm and agent lifecycle management |+| **Monitoring** | `swarm_status`, `agent_list`, `agent_metrics`, `task_status` | Real-time status and metrics |+| **Memory & Neural** | `memory_usage`, `neural_status`, `neural_train`, `neural_patterns` | Memory operations and learning |+| **GitHub** | `github_swarm`, `repo_analyze`, `pr_enhance`, `issue_triage`, `code_review` | Repository integration |+| **Workers** | `worker/run`, `worker/status`, `worker/alerts`, `worker/history` | Background task management |+| **Hooks** | `hooks/pre-*`, `hooks/post-*`, `hooks/route`, `hooks/session-*`, `hooks/intelligence/*`, `hooks/worker/*` | 31 lifecycle hooks |+| **Progress** | `progress/check`, `progress/sync`, `progress/summary`, `progress/watch` | V3 implementation tracking |++### Security Features++| Feature | Protection | Implementation |+|---------|------------|----------------|+| **Input Validation** | Injection attacks | Boundary validation on all inputs |+| **Path Traversal Prevention** | Directory escape | Blocked patterns (`../`, `~/.`, `/etc/`) |+| **Command Sandboxing** | Shell injection | Allowlisted commands, metacharacter blocking |+| **Prototype Pollution** | Object manipulation | Safe JSON parsing with validation |+| **TOCTOU Protection** | Race conditions | Symlink skipping and atomic operations |+| **Information Disclosure** | Data leakage | Error message sanitization |+| **CVE Monitoring** | Known vulnerabilities | Active scanning and patching |++### Advanced Capabilities++| Feature | Description | Benefit |+|---------|-------------|---------|+| **Automatic Topology Selection** | AI-driven topology choice based on task complexity | Optimal resource utilization |+| **Parallel Execution** | Concurrent agent operation with load balancing | 2.8-4.4x speed improvement |+| **Neural Training** | 27+ model support with continuous learning | Adaptive intelligence |+| **Bottleneck Analysis** | Real-time performance monitoring and optimization | Proactive issue detection |+| **Smart Auto-Spawning** | Dynamic agent creation based on workload | Elastic scaling |+| **Self-Healing Workflows** | Automatic error recovery and task retry | High availability |+| **Cross-Session Memory** | Persistent pattern storage across sessions | Continuous learning |+| **Event Sourcing** | Complete audit trail with replay capability | Debugging and compliance |+| **Background Workers** | 12 auto-triggered workers for analysis and optimization | Automated maintenance |+| **GitHub Integration** | PR management, issue triage, code review automation | Repository workflow |++### Plugin System (`@claude-flow/plugins`)++| Component | Description | Key Features |+|-----------|-------------|--------------|+| **PluginBuilder** | Fluent builder for creating plugins | MCP tools, hooks, workers, providers |+| **MCPToolBuilder** | Build MCP tools with typed parameters | String, number, boolean, enum params |+| **HookBuilder** | Build hooks with conditions and transformers | Priorities, conditional execution, data transformation |+| **WorkerPool** | Managed worker pool with auto-scaling | Min/max workers, task queuing, graceful shutdown |+| **ProviderRegistry** | LLM provider management with fallback | Cost optimization, automatic failover |+| **AgenticFlowBridge** | agentic-flow@alpha integration | Swarm coordination, agent spawning |+| **AgentDBBridge** | Vector storage with HNSW indexing | 150x faster search, batch operations |+| **Security Utilities** | Input validation and protection | Path traversal, injection, rate limiting |++### Plugin Hook Events++| Category | Events | Description |+|----------|--------|-------------|+| **Session** | `session:start`, `session:end` | Session lifecycle management |+| **Agent** | `agent:pre-spawn`, `agent:post-spawn`, `agent:pre-terminate`, `agent:post-terminate` | Agent lifecycle hooks |+| **Task** | `task:pre-execute`, `task:post-complete`, `task:error` | Task execution hooks |+| **Tool** | `tool:pre-call`, `tool:post-call` | MCP tool invocation hooks |+| **Memory** | `memory:pre-store`, `memory:post-store`, `memory:pre-retrieve`, `memory:post-retrieve` | Memory operation hooks |+| **Swarm** | `swarm:initialized`, `swarm:shutdown`, `swarm:consensus-reached` | Swarm coordination hooks |+| **File** | `file:pre-read`, `file:post-read`, `file:pre-write`, `file:post-write` | File operation hooks |+| **Command** | `command:pre-execute`, `command:post-execute` | Shell command hooks |+| **Learning** | `learning:pattern-learned`, `learning:pattern-applied` | Pattern learning hooks |++### Plugin Worker Types++| Worker Type | Purpose | Capabilities |+|-------------|---------|--------------|+| `coder` | Code implementation | Code generation, refactoring |+| `reviewer` | Code review | Quality analysis, suggestions |+| `tester` | Test generation/execution | Unit tests, integration tests |+| `researcher` | Information gathering | Web search, documentation |+| `planner` | Task planning | Decomposition, scheduling |+| `coordinator` | Multi-agent coordination | Orchestration, consensus |+| `security` | Security analysis | Vulnerability scanning, audit |+| `performance` | Performance optimization | Profiling, benchmarking |+| `specialized` | Custom capabilities | Domain-specific tasks |+| `long-running` | Background tasks | Async processing, polling |++### Plugin Performance++| Metric | Target | Achieved |+|--------|--------|----------|+| Plugin load time | <50ms | ~20ms |+| Hook execution | <1ms | ~0.5ms |+| Worker spawn | <100ms | ~50ms |+| Vector search (10K) | <10ms | ~5ms |++### RuVector WASM Plugins++| Plugin | Description | Performance |+|--------|-------------|-------------|+| **SemanticCodeSearchPlugin** | Semantic code search with vector embeddings | Real-time indexing |+| **IntentRouterPlugin** | Routes user intents to optimal handlers | 95%+ accuracy |+| **HookPatternLibraryPlugin** | Pre-built patterns for common tasks | Security, testing, performance |+| **MCPToolOptimizerPlugin** | Optimizes MCP tool selection | Context-aware suggestions |+| **ReasoningBankPlugin** | Vector-backed pattern storage with HNSW | 150x faster search |+| **AgentConfigGeneratorPlugin** | Generates optimized agent configurations | From pretrain data |++### Background Workers (12 Auto-Triggered)++Workers run automatically in the background based on context, or can be dispatched manually via MCP tools.++| Worker | Trigger | Purpose | Auto-Triggers On |+|--------|---------|---------|------------------|+| **UltraLearn** | `ultralearn` | Deep knowledge acquisition from codebase | New project, major refactors |+| **Optimize** | `optimize` | Performance optimization suggestions | Slow operations detected |+| **Consolidate** | `consolidate` | Memory pattern consolidation | Session end, memory threshold |+| **Predict** | `predict` | Predictive resource preloading | Usage patterns detected |+| **Audit** | `audit` | Security vulnerability analysis | Security-related file changes |+| **Map** | `map` | Codebase structure mapping | New directories, large changes |+| **Preload** | `preload` | Resource and dependency preloading | Project initialization |+| **DeepDive** | `deepdive` | Deep code analysis and understanding | Complex file edits |+| **Document** | `document` | Auto-documentation generation | New functions/classes created |+| **Refactor** | `refactor` | Refactoring opportunity detection | Code smell patterns |+| **Benchmark** | `benchmark` | Performance benchmarking | Performance-critical changes |+| **TestGaps** | `testgaps` | Test coverage gap analysis | Code changes without tests |++**Worker Commands:**+```bash+# Dispatch a worker manually+npx claude-flow@v3alpha worker dispatch --trigger audit --context "./src"++# Check worker status+npx claude-flow@v3alpha worker status++# View completed results+npx claude-flow@v3alpha worker results --limit 10+```++### LLM Providers (`@claude-flow/providers`)++| Provider | Models | Features | Cost |+|----------|--------|----------|------|+| **Anthropic** | Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku | Native, streaming, tool calling | $3-15/1M tokens |+| **OpenAI** | GPT-4o, GPT-4 Turbo, GPT-3.5, o1-preview, o3-mini | Function calling, vision | $0.50-60/1M tokens |+| **Google** | Gemini 2.0 Flash, Gemini 1.5 Pro/Flash | Multimodal, long context | $0.075-7/1M tokens |+| **Cohere** | Command R+, Command R, Command Light | RAG optimized | $0.50-15/1M tokens |+| **Ollama** | Llama 3.2, Mistral, CodeLlama, DeepSeek | Local, free, offline | Free |+| **RuVector** | Custom models via @ruvector/ruvllm | WASM optimized | Custom |++### Provider Load Balancing++| Strategy | Description | Best For |+|----------|-------------|----------|+| `round-robin` | Rotate through providers sequentially | Even distribution |+| `least-loaded` | Use provider with lowest current load | High throughput |+| `latency-based` | Use fastest responding provider | Low latency |+| `cost-based` | Use cheapest provider that meets requirements | Cost optimization (85%+ savings) |++### Embedding Providers (`@claude-flow/embeddings`)++| Provider | Models | Dimensions | Latency | Cost |+|----------|--------|------------|---------|------|+| **Agentic-Flow** | ONNX SIMD optimized | 384 | ~3ms | Free (local) |+| **OpenAI** | text-embedding-3-small/large, ada-002 | 1536-3072 | ~50-100ms | $0.02-0.13/1M tokens |+| **Transformers.js** | all-MiniLM-L6-v2, all-mpnet-base-v2, bge-small | 384-768 | ~230ms | Free (local) |+| **Mock** | Deterministic hash-based | Configurable | <1ms | Free |++### Embedding Features++| Feature | Description | Performance |+|---------|-------------|-------------|+| **Auto-Install** | `provider: 'auto'` installs agentic-flow automatically | Zero config |+| **Smart Fallback** | agentic-flow β transformers β mock chain | Always works |+| **75x Faster** | Agentic-flow ONNX vs Transformers.js | 3ms vs 230ms |+| **LRU Caching** | Intelligent cache with hit rate tracking | <1ms cache hits |+| **Batch Processing** | Efficient batch embedding with partial cache | 10 items <100ms |+| **Similarity Functions** | Cosine, Euclidean, Dot product | Optimized math |++### Consensus Strategies (`@claude-flow/swarm`)++| Strategy | Algorithm | Fault Tolerance | Latency | Best For |+|----------|-----------|-----------------|---------|----------|+| **Byzantine (PBFT)** | Practical Byzantine Fault Tolerance | f < n/3 faulty nodes | ~100ms | Adversarial environments |+| **Raft** | Leader-based log replication | f < n/2 failures | ~50ms | Strong consistency |+| **Gossip** | Epidemic protocol dissemination | High partition tolerance | ~200ms | Eventually consistent |+| **CRDT** | Conflict-free Replicated Data Types | Strong eventual consistency | ~10ms | Concurrent updates |+| **Quorum** | Configurable read/write quorums | Flexible | ~75ms | Tunable consistency |++### CLI Commands (`@claude-flow/cli`)++| Command | Subcommands | Description |+|---------|-------------|-------------|+| `init` | 4 | Project initialization (wizard, check, skills, hooks) |+| `agent` | 8 | Agent lifecycle (spawn, list, status, stop, metrics, pool, health, logs) |+| `swarm` | 6 | Swarm coordination (init, start, status, stop, scale, coordinate) |+| `memory` | 11 | Memory operations (store, retrieve, search, list, delete, stats, configure, cleanup, compress, export, import) |+| `mcp` | 9 | MCP server (start, stop, status, health, restart, tools, toggle, exec, logs) |+| `task` | 6 | Task management (create, list, status, cancel, assign, retry) |+| `session` | 7 | Session management (list, save, restore, delete, export, import, current) |+| `config` | 7 | Configuration (init, get, set, providers, reset, export, import) |+| `status` | 3 | System status with watch mode (agents, tasks, memory) |+| `workflow` | 6 | Workflow execution (run, validate, list, status, stop, template) |+| `hooks` | 32 | Self-learning hooks (pre/post-edit, pre/post-command, route, explain, pretrain, session-*, intelligence/*, worker/*, progress) |+| `hive-mind` | 6 | Queen-led coordination (init, spawn, status, task, optimize-memory, shutdown) |+| `migrate` | 5 | V2βV3 migration (status, run, verify, rollback, breaking) |+| `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` | 13 | Vector embeddings with ONNX, hyperbolic space, neural substrate |+| `daemon` | 5 | Background workers (start, stop, status, trigger, enable) |+| `progress` | 4 | V3 implementation progress (check, sync, summary, watch) |+| `claims` | 4 | Authorization (check, grant, revoke, list) |++### Testing Framework (`@claude-flow/testing`)++| Component | Description | Features |+|-----------|-------------|----------|+| **London School TDD** | Behavior verification with mocks | Mock-first, interaction testing |+| **Vitest Integration** | ADR-008 compliant test runner | 10x faster than Jest |+| **Fixture Library** | Pre-defined test data | Agents, memory, swarm, MCP |+| **Mock Factory** | Application and service mocks | Auto-reset, state tracking |+| **Async Utilities** | waitFor, retry, withTimeout | Reliable async testing |+| **Performance Assertions** | V3 target validation | Speedup, memory, latency checks |++### Testing Fixtures++| Fixture Type | Contents | Use Case |+|--------------|----------|----------|+| `agentConfigs` | 15 V3 agent configurations | Agent testing |+| `memoryEntries` | Patterns, rules, embeddings | Memory testing |+| `swarmConfigs` | V3 default, minimal, mesh, hierarchical | Swarm testing |+| `mcpTools` | 27+ tool definitions | MCP testing |++### Deployment & CI/CD (`@claude-flow/deployment`)++| Feature | Description | Automation |+|---------|-------------|------------|+| **Version Bumping** | major, minor, patch, prerelease | Automatic semver |+| **Changelog Generation** | Conventional commits parsing | Auto-generated |+| **Git Integration** | Tagging, committing | Automatic |+| **NPM Publishing** | alpha, beta, rc, latest tags | Tag-based |+| **Validation** | Lint, test, build, dependency checks | Pre-release |+| **Dry Run Mode** | Test releases without changes | Safe testing |++### Release Channels++| Channel | Version Format | Purpose |+|---------|---------------|---------|+| `alpha` | 1.0.0-alpha.1 | Early development |+| `beta` | 1.0.0-beta.1 | Feature complete, testing |+| `rc` | 1.0.0-rc.1 | Release candidate |+| `latest` | 1.0.0 | Stable production |++### Integration (`@claude-flow/integration`)++| Component | Description | Performance |+|-----------|-------------|-------------|+| **AgenticFlowBridge** | agentic-flow@alpha integration | ADR-001 compliant |+| **SONA Adapter** | Learning system integration | <0.05ms adaptation |+| **Flash Attention** | Attention mechanism coordinator | 2.49x-7.47x speedup |+| **SDK Bridge** | Version negotiation, API compatibility | Auto-detection |+| **Feature Flags** | Dynamic feature management | 9 configurable flags |+| **Runtime Detection** | NAPI, WASM, JS auto-selection | Optimal performance |++### Integration Runtimes++| Runtime | Performance | Requirements |+|---------|-------------|--------------|+| **NAPI** | Optimal | Native bindings, x64 |+| **WASM** | Good | WebAssembly support |+| **JS** | Fallback | Always available |++### Performance Benchmarking (`@claude-flow/performance`)++| Capability | Description | Output |+|------------|-------------|--------|+| **Statistical Analysis** | Mean, median, P95, P99, stddev | Comprehensive metrics |+| **Memory Tracking** | Heap, RSS, external, array buffers | Resource monitoring |+| **Auto-Calibration** | Automatic iteration adjustment | Statistical significance |+| **Regression Detection** | Baseline comparison | Change detection |+| **V3 Target Validation** | Built-in performance targets | Pass/fail checking |++### V3 Benchmark Targets++| Category | Benchmark | Target |+|----------|-----------|--------|+| **Startup** | CLI cold start | <500ms |+| **Startup** | MCP server init | <400ms |+| **Startup** | Agent spawn | <200ms |+| **Memory** | Vector search | <1ms |+| **Memory** | HNSW indexing | <10ms |+| **Memory** | Memory write | <5ms |+| **Swarm** | Agent coordination | <50ms |+| **Swarm** | Consensus latency | <100ms |+| **Neural** | SONA adaptation | <0.05ms |++### Neural & SONA (`@claude-flow/neural`)++| Feature | Description | Performance |+|---------|-------------|-------------|+| **SONA Learning** | Self-Optimizing Neural Architecture | <0.05ms adaptation |+| **5 Learning Modes** | real-time, balanced, research, edge, batch | Mode-specific optimization |+| **9 RL Algorithms** | PPO, A2C, DQN, Q-Learning, SARSA, Decision Transformer, etc. | Comprehensive RL |+| **LoRA Integration** | Low-Rank Adaptation for efficient fine-tuning | Minimal memory overhead |+| **MicroLoRA** | Ultra-lightweight LoRA for edge/real-time modes | <5MB memory footprint |+| **EWC++ Memory** | Elastic Weight Consolidation prevents catastrophic forgetting | Zero knowledge loss |+| **Trajectory Tracking** | Execution path recording for pattern extraction | Continuous learning |++### Memory & Vector Optimization++| Feature | Description | Improvement |+|---------|-------------|-------------|+| **Scalar Quantization** | Reduce vector precision for memory savings | 4x memory reduction |+| **Product Quantization** | Compress vectors into codebooks | 8-32x memory reduction |+| **HNSW Indexing** | Hierarchical Navigable Small World graphs | 150x-12,500x faster search |+| **LRU Caching** | Intelligent embedding cache with TTL | <1ms cache hits |+| **Batch Processing** | Process multiple embeddings in single call | 10x throughput |+| **Memory Compression** | Pattern distillation and pruning | 50-75% reduction |++### Embedding System (`@claude-flow/embeddings`)++| Feature | Description | Performance |+|---------|-------------|-------------|+| **Multi-Provider** | Agentic-Flow (ONNX), OpenAI, Transformers.js, Mock | 4 providers |+| **Auto-Install** | `claude-flow embeddings init` or `createEmbeddingServiceAsync()` | Zero config |+| **75x Faster** | Agentic-flow ONNX SIMD vs Transformers.js | 3ms vs 230ms |+| **Hyperbolic Space** | PoincarΓ© ball model for hierarchical data | Exponential capacity |+| **Dimensions** | 384 to 3072 configurable | Quality vs speed tradeoff |+| **Similarity Metrics** | Cosine, Euclidean, Dot product, Hyperbolic distance | Task-specific matching |+| **Neural Substrate** | Drift detection, memory physics, swarm coordination | agentic-flow integration |+| **LRU + SQLite Cache** | Persistent cross-session caching | <1ms cache hits |++```bash+# Initialize ONNX embeddings with hyperbolic config+claude-flow embeddings init++# Use larger model for higher quality+claude-flow embeddings init --model all-mpnet-base-v2++# Semantic search+claude-flow embeddings search -q "authentication patterns"+```++### SONA Learning Modes++| Mode | Adaptation | Quality | Memory | Use Case |+|------|------------|---------|--------|----------|+| `real-time` | <0.5ms | 70%+ | 25MB | Production, low-latency |+| `balanced` | <18ms | 75%+ | 50MB | General purpose |+| `research` | <100ms | 95%+ | 100MB | Deep exploration |+| `edge` | <1ms | 80%+ | 5MB | Resource-constrained |+| `batch` | <50ms | 85%+ | 75MB | High-throughput |++### RL Algorithms++| Algorithm | Type | Best For |+|-----------|------|----------|+| **PPO** | Policy Gradient | Stable continuous learning |+| **A2C** | Actor-Critic | Balanced exploration/exploitation |+| **DQN** | Value-based | Discrete action spaces |+| **Q-Learning** | Tabular | Simple state spaces |+| **SARSA** | On-policy | Online learning |+| **Decision Transformer** | Sequence modeling | Long-horizon planning |++### Hive-Mind Coordination++| Feature | Description | Capability |+|---------|-------------|------------|+| **Queen-Led Topology** | Hierarchical command structure | Unlimited agents + sub-workers |+| **Byzantine Consensus** | Fault-tolerant agreement | f < n/3 tolerance |+| **Collective Memory** | Shared pattern storage | Distillation, compression |+| **Specialist Spawning** | Domain-specific agents | Security, performance, etc. |+| **Adaptive Topology** | Dynamic structure changes | Load-based optimization |++### agentic-flow@alpha Integration++| Feature | Description | Benefit |+|---------|-------------|---------|+| **ADR-001 Compliance** | Build on agentic-flow, don't duplicate | Eliminates 10,000+ duplicate lines |+| **Core Foundation** | Use agentic-flow as the base layer | Unified architecture |+| **SONA Integration** | Seamless learning system connection | <0.05ms adaptation |+| **Flash Attention** | Optimized attention mechanisms | 2.49x-7.47x speedup |+| **AgentDB Bridge** | Vector storage integration | 150x-12,500x faster search |+| **Feature Flags** | Dynamic capability management | 9 configurable features |+| **Runtime Detection** | NAPI/WASM/JS auto-selection | Optimal performance per platform |+| **Graceful Fallback** | Works with or without agentic-flow | Always functional |++### MCP Server (`@claude-flow/mcp`)++| Feature | Description | Spec |+|---------|-------------|------|+| **MCP 2025-11-25** | Full specification compliance | Latest MCP standard |+| **Multiple Transports** | stdio, HTTP, WebSocket, in-process | Flexible connectivity |+| **Resources** | list, read, subscribe with caching | Dynamic content |+| **Prompts** | Templates with arguments and embedding | Reusable prompts |+| **Tasks** | Async operations with progress/cancel | Long-running ops |+| **Tool Registry** | O(1) lookup, <10ms registration | Fast tool access |+| **Connection Pooling** | Max 10 connections, configurable | Resource management |+| **Session Management** | Timeout handling, authentication | Secure sessions |++### MCP Methods++| Method | Description |+|--------|-------------|+| `initialize` | Initialize connection |+| `tools/list` | List available tools |+| `tools/call` | Execute a tool |+| `resources/list` | List resources with pagination |+| `resources/read` | Read resource content |+| `resources/subscribe` | Subscribe to updates |+| `prompts/list` | List prompts with pagination |+| `prompts/get` | Get prompt with arguments |+| `tasks/status` | Get task status |+| `tasks/cancel` | Cancel running task |+| `completion/complete` | Auto-complete arguments |++### Security Module (`@claude-flow/security`)++| Feature | CVE/Issue | Description |+|---------|-----------|-------------|+| **Password Hashing** | CVE-2 | Secure bcrypt with 12+ rounds |+| **Credential Generation** | CVE-3 | Cryptographically secure API keys |+| **Safe Command Execution** | HIGH-1 | Allowlist-based command execution |+| **Path Validation** | HIGH-2 | Path traversal and symlink protection |+| **Input Validation** | General | Zod-based schema validation |+| **Token Generation** | General | HMAC-signed secure tokens |+| **HTML Sanitization** | XSS | Script and injection prevention |++### Security Validation Schemas++| Schema | Purpose |+|--------|---------|+| `SafeStringSchema` | Basic safe string with length limits |+| `IdentifierSchema` | Alphanumeric identifiers |+| `FilenameSchema` | Safe filenames |+| `EmailSchema` | Email addresses |+| `PasswordSchema` | Secure passwords (8-72 chars) |+| `UUIDSchema` | UUID v4 format |+| `HttpsUrlSchema` | HTTPS URLs only |+| `SpawnAgentSchema` | Agent spawn requests |+| `TaskInputSchema` | Task definitions |++### Hooks System (`@claude-flow/hooks`)++| Component | Description | Performance |+|-----------|-------------|-------------|+| **ReasoningBank** | Pattern storage with HNSW indexing | 150x faster retrieval |+| **GuidanceProvider** | Context-aware development guidance | Real-time suggestions |+| **PatternLearning** | Automatic strategy extraction | Continuous improvement |+| **QualityTracking** | Success/failure rate per pattern | Performance metrics |+| **DomainDetection** | Auto-categorization of patterns | Security, testing, etc. |+| **AgentRouting** | Task-to-agent optimization | Historical performance |+| **Consolidation** | Prune low-quality, promote high-quality | Memory optimization |++### Hook Lifecycle Events++| Phase | Hooks | Purpose |+|-------|-------|---------|+| **Pre-Edit** | `pre-edit` | Context gathering, security checks |+| **Post-Edit** | `post-edit` | Outcome recording, pattern learning |+| **Pre-Command** | `pre-command` | Risk assessment, validation |+| **Post-Command** | `post-command` | Success/failure tracking |+| **Pre-Task** | `pre-task` | Setup, resource allocation |+| **Post-Task** | `post-task` | Cleanup, learning |+| **Session** | `session-end`, `session-restore` | State management |++### V3 Statusline (`@claude-flow/hooks`)++Real-time development status display for Claude Code integration showing DDD progress, swarm activity, security status, and system metrics.++**Output Format:**+```+β Claude Flow V3 β ruvnet β β v3 β Opus 4.5+βββββββββββββββββββββββββββββββββββββββββββββββββββββ+ποΈ DDD Domains [βββββ] 5/5 β‘ 1.0x β 2.49x-7.47x+π€ Swarm β [58/15] π₯ 0 π’ CVE 3/3 πΎ 22282MB π 47% π§ 10%+π§ Architecture DDD β 98% β Security βCLEAN β Memory βAgentDB β Integration β+```++| Indicator | Description | Values |+|-----------|-------------|--------|+| `β Claude Flow V3` | Project header | Always shown |+| `β ruvnet` | GitHub user (via `gh` CLI) | Dynamic |+| `β v3` | Current git branch | Dynamic |+| `Opus 4.5` | Claude model name | From Claude Code |+| `[βββββ]` | DDD domain progress bar | 0-5 domains |+| `β‘ 1.0x β 2.49x-7.47x` | Performance speedup target | Current β Target |+| `β/β` | Swarm coordination status | Active/Inactive |+| `[58/15]` | Active agents / max agents | Process count |+| `π₯ 0` | Sub-agents spawned | Task tool agents |+| `π’ CVE 3/3` | Security CVE remediation | Fixed/Total |+| `πΎ 22282MB` | Memory usage (Node.js processes) | Real-time |+| `π 47%` | Context window usage | From Claude Code |+| `π§ 10%` | Intelligence score (patterns learned) | 0-100% |+| `DDD β 98%` | Domain-Driven Design progress | Percentage |+| `Security βCLEAN` | Security audit status | CLEAN/PENDING/FAILED |+| `Memory βAgentDB` | Memory backend in use | AgentDB/SQLite/Hybrid |+| `Integration β` | agentic-flow integration status | Active/Inactive |++**Usage:**+```bash+# V3 statusline (Node.js)+node v3/@claude-flow/hooks/bin/statusline.js++# JSON output for scripting+node v3/@claude-flow/hooks/bin/statusline.js --json++# Compact JSON (single line)+node v3/@claude-flow/hooks/bin/statusline.js --compact++# Help+node v3/@claude-flow/hooks/bin/statusline.js --help+```++**Claude Code Integration:**++Add to `.claude/settings.json`:+```json+{+ "statusLine": {+ "type": "command",+ "command": "node v3/@claude-flow/hooks/bin/statusline.js"+ }+}+```++**Data Sources:**+- `.claude-flow/metrics/v3-progress.json` - DDD domain progress+- `.claude-flow/metrics/swarm-activity.json` - Active agent counts+- `.claude-flow/security/audit-status.json` - CVE remediation status+- `.claude-flow/learning/patterns.db` - Intelligence score (pattern count)+- Process detection via `ps aux` - Real-time memory and agent counts+- Git branch via `git branch --show-current`+- GitHub user via `gh api user`++### Background Daemons++#### V3 Node.js Worker Daemon (Recommended)++Cross-platform TypeScript-based daemon service with auto-scheduling:++| Worker | Interval | Priority | Description |+|--------|----------|----------|-------------|+| `map` | 5min | normal | Codebase structure mapping |+| `audit` | 10min | critical | Security vulnerability scanning |+| `optimize` | 15min | high | Performance optimization |+| `consolidate` | 30min | low | Memory consolidation |+| `testgaps` | 20min | normal | Test coverage analysis |++**Commands:**+```bash+# Start daemon (auto-runs on SessionStart hooks)+npx claude-flow@v3alpha daemon start++# Check status with worker history+npx claude-flow@v3alpha daemon status++# Manually trigger a worker+npx claude-flow@v3alpha daemon trigger map++# Enable/disable workers+npx claude-flow@v3alpha daemon enable map audit optimize++# Stop daemon+npx claude-flow@v3alpha daemon stop+```++**Daemon Status Output:**+```++-- Worker Daemon ---++| Status: β RUNNING |+| PID: 12345 |+| Workers Enabled: 5 |+| Max Concurrent: 3 |++--------------------+++Worker Status++-------------+----+----------+------+---------+----------+----------++| Worker | On | Status | Runs | Success | Last Run | Next Run |++-------------+----+----------+------+---------+----------+----------++| map | β | idle | 12 | 100% | 2m ago | in 3m |+| audit | β | idle | 6 | 100% | 5m ago | in 5m |+| optimize | β | running | 4 | 100% | now | - |+| consolidate | β | idle | 2 | 100% | 15m ago | in 15m |+| testgaps | β | idle | 3 | 100% | 8m ago | in 12m |++-------------+----+----------+------+---------+----------+----------++```++#### Legacy Shell Daemons (V2)++Shell-based daemons for monitoring (Linux/macOS only):++| Daemon | Interval | Purpose | Output |+|--------|----------|---------|--------|+| **Swarm Monitor** | 3s | Process detection, agent counting | `swarm-activity.json` |+| **Metrics Daemon** | 30s | V3 progress sync, SQLite metrics | `metrics.db` |++**Commands:**+```bash+# Start all daemons+.claude/helpers/daemon-manager.sh start 3 5++# Check daemon status+.claude/helpers/daemon-manager.sh status++# Stop all daemons+.claude/helpers/daemon-manager.sh stop+```++### Worker Manager (7 Scheduled Workers)++| Worker | Interval | Purpose |+|--------|----------|---------|+| `perf` | 5 min | Performance benchmarks |+| `health` | 5 min | Disk, memory, CPU monitoring |+| `patterns` | 15 min | Pattern dedup & pruning |+| `ddd` | 10 min | DDD progress tracking |+| `adr` | 15 min | ADR compliance checking |+| `security` | 30 min | Security vulnerability scans |+| `learning` | 30 min | Learning pattern optimization |++**Commands:**+```bash+# Start worker manager+.claude/helpers/worker-manager.sh start 60++# Force run all workers immediately+.claude/helpers/worker-manager.sh force++# Check worker status+.claude/helpers/worker-manager.sh status+```++---++## Use Cases++| Use Case | Command |+|----------|---------|+| Code review | `npx claude-flow@v3alpha --agent reviewer --task "Review PR #123"` |+| Test generation | `npx claude-flow@v3alpha --agent tester --task "Write tests for auth module"` |+| Security audit | `npx claude-flow@v3alpha --agent security-architect --task "Audit for vulnerabilities"` |+| Multi-agent swarm | `npx claude-flow@v3alpha swarm init --topology hierarchical` |+| Route task | `npx claude-flow@v3alpha hooks route "Optimize database queries"` |+| Performance analysis | `npx claude-flow@v3alpha --agent perf-analyzer --task "Profile API endpoints"` |+| GitHub PR management | `npx claude-flow@v3alpha --agent pr-manager --task "Review open PRs"` |+| Check V3 progress | `npx claude-flow@v3alpha progress --detailed` |+| Sync progress metrics | `npx claude-flow@v3alpha progress sync` |++---++## Self-Learning Hooks Commands (27 Hooks)++### Core Tool Lifecycle Hooks+```bash+# Before/after file editing+npx claude-flow@v3alpha hooks pre-edit <filePath>+npx claude-flow@v3alpha hooks post-edit <filePath> --success true --train-patterns++# Before/after commands+npx claude-flow@v3alpha hooks pre-command "<command>"+npx claude-flow@v3alpha hooks post-command "<command>" --success true++# Before/after tasks+npx claude-flow@v3alpha hooks pre-task --description "<task>"+npx claude-flow@v3alpha hooks post-task --task-id "<id>" --success true+```++### Intelligence & Routing Hooks+```bash+# Route task to optimal agent using learned patterns+npx claude-flow@v3alpha hooks route "<task description>" --include-explanation++# Explain routing decision with transparency+npx claude-flow@v3alpha hooks explain "<topic>" --depth comprehensive++# Bootstrap intelligence from repository+npx claude-flow@v3alpha hooks pretrain --model-type moe --epochs 10++# Generate optimized agent configs from pretrain data+npx claude-flow@v3alpha hooks build-agents --agent-types coder,tester --config-format yaml++# Transfer patterns from another project+npx claude-flow@v3alpha hooks transfer <sourceProject>++# Initialize hooks system+npx claude-flow@v3alpha hooks init++# View learning metrics dashboard+npx claude-flow@v3alpha hooks metrics++# List all registered hooks+npx claude-flow@v3alpha hooks list+```++### Session Management Hooks+```bash+# Start session with context loading+npx claude-flow@v3alpha hooks session-start --session-id "<id>" --load-context++# End session with persistence+npx claude-flow@v3alpha hooks session-end --export-metrics true --persist-patterns++# Restore previous session context+npx claude-flow@v3alpha hooks session-restore --session-id "<id>"++# Send notifications to swarm+npx claude-flow@v3alpha hooks notify --message "<message>" --swarm-status+```++### RuVector Intelligence Hooks (Reinforcement Learning)+```bash+# Trajectory-based learning (4-step pipeline: RETRIEVE, JUDGE, DISTILL, CONSOLIDATE)+npx claude-flow@v3alpha hooks intelligence trajectory-start --session "<session>"+npx claude-flow@v3alpha hooks intelligence trajectory-step --action "<action>" --reward 0.9+npx claude-flow@v3alpha hooks intelligence trajectory-end --verdict success++# Pattern storage with HNSW indexing (150x faster search)+npx claude-flow@v3alpha hooks intelligence pattern-store --pattern "<pattern>" --embedding "[...]"+npx claude-flow@v3alpha hooks intelligence pattern-search --query "<query>" --limit 10++# Learning stats and attention focus+npx claude-flow@v3alpha hooks intelligence stats+npx claude-flow@v3alpha hooks intelligence learn --experience '{"type":"success"}'+npx claude-flow@v3alpha hooks intelligence attention --focus "<task>"++# Full intelligence system (SONA, MoE, HNSW, EWC++, Flash Attention)+npx claude-flow@v3alpha hooks intelligence+npx claude-flow@v3alpha hooks intelligence reset --confirm++# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+# Background Worker Commands (12 workers for analysis/optimization)+# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ++# List all available workers+npx claude-flow@v3alpha hooks worker list++# Detect triggers from prompt text+npx claude-flow@v3alpha hooks worker detect --prompt "optimize performance"++# Auto-dispatch workers when triggers match (confidence β₯0.6)+npx claude-flow@v3alpha hooks worker detect --prompt "deep dive into auth" --auto-dispatch --min-confidence 0.6++# Manually dispatch a worker (ultralearn, optimize, audit, map, deepdive, document, refactor, benchmark, testgaps, etc.)+npx claude-flow@v3alpha hooks worker dispatch --trigger refactor --context "auth module"++# Check worker status+npx claude-flow@v3alpha hooks worker status++# Cancel a running worker+npx claude-flow@v3alpha hooks worker cancel --id worker_refactor_1_abc123+```++### Progress Tracking Hooks+```bash+# Check V3 implementation progress+npx claude-flow@v3alpha hooks progress++# Detailed breakdown by category (CLI, MCP, Hooks, Packages, DDD)+npx claude-flow@v3alpha hooks progress --detailed++# Sync progress and persist to file+npx claude-flow@v3alpha hooks progress --sync++# Get human-readable summary+npx claude-flow@v3alpha hooks progress --summary++# JSON output for scripting+npx claude-flow@v3alpha progress --json+```++---++## Architecture++### V3 Module Structure++```+v3/+βββ @claude-flow/hooks # Event-driven lifecycle hooks + ReasoningBank+βββ @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/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+```++### Performance Metrics++| Metric | Measured |+|--------|----------|+| Swarm task execution | 100% success rate (7/7 strategies) |+| Average task duration | 0.15-0.30 seconds |+| Memory usage per agent | 128-320 MB |+| CPU utilization | 15-30% per agent |+| Parallel agent capacity | Unlimited (resource-dependent) |++### Topology Performance++| Topology | Agents | Execution Time | Memory |+|----------|--------|----------------|--------|+| Centralized | 2-3 | 0.14-0.20s | 180-256 MB |+| Distributed | 4-5 | 0.10-0.12s | 128-160 MB |+| Hierarchical | 6 | 0.20s | 256 MB |+| Mesh | 4 | 0.15s | 192 MB |+| Hybrid | 7 | 0.18s | 320 MB |++---++## 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"+```++---++## Environment Variables++| Variable | Description | Default |+|----------|-------------|---------|+| `CLAUDE_FLOW_MODE` | Operation mode (`development`, `production`, `integration`) | `development` |+| `CLAUDE_FLOW_MEMORY_PATH` | Directory for persistent memory storage | `./data` |+| `CLAUDE_FLOW_SECURITY_MODE` | Security level (`strict`, `standard`, `permissive`) | `standard` |+| `CLAUDE_FLOW_LOG_LEVEL` | Logging verbosity (`debug`, `info`, `warn`, `error`) | `info` |+| `CLAUDE_FLOW_MAX_AGENTS` | Default concurrent agent limit (increase for more parallelism) | `15` |+| `CLAUDE_FLOW_TOPOLOGY` | Default swarm topology | `hierarchical` |+| `CLAUDE_FLOW_HNSW_M` | HNSW index M parameter (connectivity) | `16` |+| `CLAUDE_FLOW_HNSW_EF` | HNSW search ef parameter (accuracy) | `200` |+| `CLAUDE_FLOW_EMBEDDING_DIM` | Vector embedding dimensions | `384` |+| `ANTHROPIC_API_KEY` | Anthropic API key for Claude integration | - |++---++## Troubleshooting++### Common Issues++**MCP server won't start**+```bash+# Check if port is in use+lsof -i :3000+# Kill existing process+kill -9 <PID>+# Restart MCP server+npx claude-flow@v3alpha mcp start+```++**Agent spawn failures**+```bash+# Check available memory+free -m+# Reduce max agents if memory constrained+export CLAUDE_FLOW_MAX_AGENTS=5+```++**Pattern search returning no results**+```bash+# Verify patterns are stored+npx claude-flow@v3alpha hooks metrics+# Re-run pretraining if empty+npx claude-flow@v3alpha hooks pretrain+```++**Windows path issues**+```powershell+# Use forward slashes or escape backslashes+$env:CLAUDE_FLOW_MEMORY_PATH = "./data"+# Or use absolute path+$env:CLAUDE_FLOW_MEMORY_PATH = "C:/Users/name/claude-flow/data"+```++**Permission denied errors**+```bash+# Fix npm permissions (Linux/macOS)+sudo chown -R $(whoami) ~/.npm+# Or use nvm to manage Node.js+```++**High memory usage**+```bash+# Enable garbage collection+node --expose-gc node_modules/.bin/claude-flow+# Reduce HNSW parameters for lower memory+export CLAUDE_FLOW_HNSW_M=8+export CLAUDE_FLOW_HNSW_EF=100+```++---++## Migration Guide (V2 β V3)++### Breaking Changes++1. **Module Structure**: V3 uses scoped packages (`@claude-flow/*`)+2. **Memory Backend**: Default changed from JSON to AgentDB with HNSW+3. **Hooks System**: New ReasoningBank replaces basic pattern storage+4. **Security**: Stricter input validation enabled by default++### Upgrade Steps++```bash+# 1. Backup existing data+cp -r ./data ./data-backup-v2++# 2. Update to V3+npm install claude-flow@latest++# 3. Run migration+npx claude-flow@v3alpha migrate --from v2++# 4. Verify installation+npx claude-flow@v3alpha --version+npx claude-flow@v3alpha hooks metrics+```++### Configuration Changes++```bash+# V2 (deprecated)+npx claude-flow init --mode basic++# V3 (new)+npx claude-flow@v3alpha init+npx claude-flow@v3alpha hooks pretrain # Bootstrap learning+```++### API Changes++| V2 API | V3 API |+|--------|--------|+| `claude-flow start` | `claude-flow mcp start` |+| `--pattern-store` | `--memory-backend agentdb` |+| `hooks record` | `hooks post-edit --success` |+| `swarm create` | `swarm init --topology` |++---++## Documentation++### V3 Module Documentation++| Module | Description | Docs |+|--------|-------------|------|+| `@claude-flow/plugins` | Plugin SDK with workers, hooks, providers, security | [README](./v3/@claude-flow/plugins/README.md) |+| `@claude-flow/hooks` | Event-driven lifecycle hooks + ReasoningBank | [Source](./v3/@claude-flow/hooks/) |+| `@claude-flow/memory` | AgentDB unification with HNSW indexing | [Source](./v3/@claude-flow/memory/) |+| `@claude-flow/security` | CVE remediation & security patterns | [Source](./v3/@claude-flow/security/) |+| `@claude-flow/swarm` | 15-agent coordination engine | [Source](./v3/@claude-flow/swarm/) |+| `@claude-flow/cli` | CLI modernization | [Source](./v3/@claude-flow/cli/) |+| `@claude-flow/neural` | SONA learning integration | [Source](./v3/@claude-flow/neural/) |+| `@claude-flow/testing` | TDD London School framework | [Source](./v3/@claude-flow/testing/) |+| `@claude-flow/mcp` | MCP server & tools | [Source](./v3/@claude-flow/mcp/) |+| `@claude-flow/embeddings` | Vector embedding providers | [Source](./v3/@claude-flow/embeddings/) |+| `@claude-flow/providers` | LLM provider integrations | [Source](./v3/@claude-flow/providers/) |+| `@claude-flow/integration` | agentic-flow@alpha integration | [Source](./v3/@claude-flow/integration/) |+| `@claude-flow/performance` | Benchmarking & optimization | [Source](./v3/@claude-flow/performance/) |+| `@claude-flow/deployment` | Release & CI/CD | [Source](./v3/@claude-flow/deployment/) |+| `@claude-flow/shared` | Shared utilities, types & V3ProgressService | [Source](./v3/@claude-flow/shared/) |++### Additional Resources++- [V2 Documentation](./v2/README.md)+- [Architecture Decisions (ADRs)](./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++MIT - [RuvNet](https://github.com/ruvnet)diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.jsonindex 103fbacf65..edcca347a6 100644--- a/v3/@claude-flow/cli/package.json+++ b/v3/@claude-flow/cli/package.json@@ -1,6 +1,6 @@{"name": "@claude-flow/cli",- "version": "3.0.0-alpha.92",+ "version": "3.0.0-alpha.93","type": "module","description": "CLI module - command parsing, prompts, output formatting","main": "dist/src/index.js",diff --git a/v3/@claude-flow/cli/src/commands/mcp.ts b/v3/@claude-flow/cli/src/commands/mcp.tsindex d78e2239c6..7a4e3e3710 100644--- a/v3/@claude-flow/cli/src/commands/mcp.ts+++ b/v3/@claude-flow/cli/src/commands/mcp.ts@@ -107,9 +107,32 @@ const startCommand: Command = {// Check if already runningconst existingStatus = await getMCPServerStatus();if (existingStatus.running) {- output.printWarning(`MCP Server already running (PID: ${existingStatus.pid})`);- output.writeln(output.dim('Use "claude-flow mcp stop" to stop the server first'));- return { success: false, exitCode: 1 };+ // Verify the server is actually healthy/responsive+ const manager = getServerManager();+ const health = await manager.checkHealth();++ if (health.healthy) {+ output.printWarning(`MCP Server already running (PID: ${existingStatus.pid})`);+ output.writeln(output.dim('Use "claude-flow mcp stop" to stop the server first'));+ return { success: false, exitCode: 1 };+ }++ // Server exists but is unresponsive - auto-recover+ output.printWarning(`MCP Server (PID: ${existingStatus.pid}) is unresponsive - auto-recovering...`);+ try {+ // Force kill the stale process+ if (existingStatus.pid) {+ try {+ process.kill(existingStatus.pid, 'SIGKILL');+ } catch {+ // Process may already be dead+ }+ }+ await manager.stop();+ output.writeln(output.dim(' Cleaned up stale server'));+ } catch {+ // Continue anyway - the stop/cleanup may partially fail+ }}const options: MCPServerOptions = {diff --git a/v3/package-lock.json b/v3/package-lock.jsonindex 0a6aec9248..a63246aec5 100644--- a/v3/package-lock.json+++ b/v3/package-lock.json@@ -925,7 +925,7 @@}},"@claude-flow/cli": {- "version": "3.0.0-alpha.92",+ "version": "3.0.0-alpha.93","dependencies": {"@claude-flow/aidefence": "^3.0.2","@claude-flow/embeddings": "^3.0.0-alpha.12",