DevFlow v3: Enterprise AI Orchestration Platform

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.

Overview

DevFlow 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 DevFlow

| Capability | Claude Code Alone | Claude Code + DevFlow | |------------|-------------------|---------------------------| | 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 devflow 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:

# 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

# With npm/npx (Node.js)
npm install devflow-ai@v3alpha
npx devflow-ai@v3alpha init

# With Bun (faster)
bun add devflow-ai@v3alpha
bunx devflow-ai@v3alpha init

# Start MCP server for Claude Code integration
npx devflow-ai@v3alpha mcp start

# Run a task with agents
npx devflow-ai@v3alpha --agent coder --task "Implement user authentication"

# List available agents
npx devflow-ai@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 (@devflow/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 |

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:

# Dispatch a worker manually
npx devflow-ai@v3alpha worker dispatch --trigger audit --context "./src"

# Check worker status
npx devflow-ai@v3alpha worker status

# View completed results
npx devflow-ai@v3alpha worker results --limit 10

LLM Providers (@devflow/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 (@devflow/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 (@devflow/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 (@devflow/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 (@devflow/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 (@devflow/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 (@devflow/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 (@devflow/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 (@devflow/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 (@devflow/embeddings)

| Feature | Description | Performance | |---------|-------------|-------------| | Multi-Provider | Agentic-Flow (ONNX), OpenAI, Transformers.js, Mock | 4 providers | | Auto-Install | devflow-ai 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 |

# Initialize ONNX embeddings with hyperbolic config
devflow-ai embeddings init

# Use larger model for higher quality
devflow-ai embeddings init --model all-mpnet-base-v2

# Semantic search
devflow-ai 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 (@devflow/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 (@devflow/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 (@devflow/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 (@devflow/hooks)

Real-time development status display for Claude Code integration showing DDD progress, swarm activity, security status, and system metrics.

Output Format:

▊ DevFlow V3 ● user  │  ⎇ 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 | |-----------|-------------|--------| | ▊ DevFlow V3 | Project header | Always shown | | ● user | 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:

# V3 statusline (Node.js)
node v3/@devflow/hooks/bin/statusline.js

# JSON output for scripting
node v3/@devflow/hooks/bin/statusline.js --json

# Compact JSON (single line)
node v3/@devflow/hooks/bin/statusline.js --compact

# Help
node v3/@devflow/hooks/bin/statusline.js --help

Claude Code Integration:

Add to .claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "node v3/@devflow/hooks/bin/statusline.js"
  }
}

Data Sources:

• .devflow/metrics/v3-progress.json - DDD domain progress
• .devflow/metrics/swarm-activity.json - Active agent counts
• .devflow/security/audit-status.json - CVE remediation status
• .devflow/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:

# Start daemon (auto-runs on SessionStart hooks)
npx devflow-ai@v3alpha daemon start

# Check status with worker history
npx devflow-ai@v3alpha daemon status

# Manually trigger a worker
npx devflow-ai@v3alpha daemon trigger map

# Enable/disable workers
npx devflow-ai@v3alpha daemon enable map audit optimize

# Stop daemon
npx devflow-ai@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:

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

# 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 devflow-ai@v3alpha --agent reviewer --task "Review PR #123" | | Test generation | npx devflow-ai@v3alpha --agent tester --task "Write tests for auth module" | | Security audit | npx devflow-ai@v3alpha --agent security-architect --task "Audit for vulnerabilities" | | Multi-agent swarm | npx devflow-ai@v3alpha swarm init --topology hierarchical | | Route task | npx devflow-ai@v3alpha hooks route "Optimize database queries" | | Performance analysis | npx devflow-ai@v3alpha --agent perf-analyzer --task "Profile API endpoints" | | GitHub PR management | npx devflow-ai@v3alpha --agent pr-manager --task "Review open PRs" | | Check V3 progress | npx devflow-ai@v3alpha progress --detailed | | Sync progress metrics | npx devflow-ai@v3alpha progress sync |

Self-Learning Hooks Commands (27 Hooks)

Core Tool Lifecycle Hooks

# Before/after file editing
npx devflow-ai@v3alpha hooks pre-edit <filePath>
npx devflow-ai@v3alpha hooks post-edit <filePath> --success true --train-patterns

# Before/after commands
npx devflow-ai@v3alpha hooks pre-command "<command>"
npx devflow-ai@v3alpha hooks post-command "<command>" --success true

# Before/after tasks
npx devflow-ai@v3alpha hooks pre-task --description "<task>"
npx devflow-ai@v3alpha hooks post-task --task-id "<id>" --success true

Intelligence & Routing Hooks

# Route task to optimal agent using learned patterns
npx devflow-ai@v3alpha hooks route "<task description>" --include-explanation

# Explain routing decision with transparency
npx devflow-ai@v3alpha hooks explain "<topic>" --depth comprehensive

# Bootstrap intelligence from repository
npx devflow-ai@v3alpha hooks pretrain --model-type moe --epochs 10

# Generate optimized agent configs from pretrain data
npx devflow-ai@v3alpha hooks build-agents --agent-types coder,tester --config-format yaml

# Transfer patterns from another project
npx devflow-ai@v3alpha hooks transfer <sourceProject>

# Initialize hooks system
npx devflow-ai@v3alpha hooks init

# View learning metrics dashboard
npx devflow-ai@v3alpha hooks metrics

# List all registered hooks
npx devflow-ai@v3alpha hooks list

Session Management Hooks

# Start session with context loading
npx devflow-ai@v3alpha hooks session-start --session-id "<id>" --load-context

# End session with persistence
npx devflow-ai@v3alpha hooks session-end --export-metrics true --persist-patterns

# Restore previous session context
npx devflow-ai@v3alpha hooks session-restore --session-id "<id>"

# Send notifications to swarm
npx devflow-ai@v3alpha hooks notify --message "<message>" --swarm-status

RuVector Intelligence Hooks (Reinforcement Learning)

# Trajectory-based learning (4-step pipeline: RETRIEVE, JUDGE, DISTILL, CONSOLIDATE)
npx devflow-ai@v3alpha hooks intelligence trajectory-start --session "<session>"
npx devflow-ai@v3alpha hooks intelligence trajectory-step --action "<action>" --reward 0.9
npx devflow-ai@v3alpha hooks intelligence trajectory-end --verdict success

# Pattern storage with HNSW indexing (150x faster search)
npx devflow-ai@v3alpha hooks intelligence pattern-store --pattern "<pattern>" --embedding "[...]"
npx devflow-ai@v3alpha hooks intelligence pattern-search --query "<query>" --limit 10

# Learning stats and attention focus
npx devflow-ai@v3alpha hooks intelligence stats
npx devflow-ai@v3alpha hooks intelligence learn --experience '{"type":"success"}'
npx devflow-ai@v3alpha hooks intelligence attention --focus "<task>"

# Full intelligence system (SONA, MoE, HNSW, EWC++, Flash Attention)
npx devflow-ai@v3alpha hooks intelligence
npx devflow-ai@v3alpha hooks intelligence reset --confirm

# ═══════════════════════════════════════════════════════════════
# Background Worker Commands (12 workers for analysis/optimization)
# ═══════════════════════════════════════════════════════════════

# List all available workers
npx devflow-ai@v3alpha hooks worker list

# Detect triggers from prompt text
npx devflow-ai@v3alpha hooks worker detect --prompt "optimize performance"

# Auto-dispatch workers when triggers match (confidence ≥0.6)
npx devflow-ai@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 devflow-ai@v3alpha hooks worker dispatch --trigger refactor --context "auth module"

# Check worker status
npx devflow-ai@v3alpha hooks worker status

# Cancel a running worker
npx devflow-ai@v3alpha hooks worker cancel --id worker_refactor_1_abc123

Progress Tracking Hooks

# Check V3 implementation progress
npx devflow-ai@v3alpha hooks progress

# Detailed breakdown by category (CLI, MCP, Hooks, Packages, DDD)
npx devflow-ai@v3alpha hooks progress --detailed

# Sync progress and persist to file
npx devflow-ai@v3alpha hooks progress --sync

# Get human-readable summary
npx devflow-ai@v3alpha hooks progress --summary

# JSON output for scripting
npx devflow-ai@v3alpha progress --json

Architecture

V3 Module Structure

v3/
├── @devflow/hooks      # Event-driven lifecycle hooks + ReasoningBank
├── @devflow/memory     # AgentDB unification module
├── @devflow/security   # CVE remediation & patterns
├── @devflow/swarm      # 15-agent coordination
├── @devflow/plugins    # RuVector WASM plugins
├── @devflow/cli        # CLI modernization
├── @devflow/neural     # SONA learning integration
├── @devflow/testing    # TDD London School framework
├── @devflow/deployment # Release & CI/CD
└── @devflow/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)

npx @devflow-ai/security@latest audit --platform windows
$env:DEVFLOW_MODE = "integration"

macOS (Bash/Zsh)

npx @devflow-ai/security@latest audit --platform darwin
export DEVFLOW_SECURITY_MODE="strict"

Linux (Bash)

npx @devflow-ai/security@latest audit --platform linux
export DEVFLOW_MEMORY_PATH="./data"

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | DEVFLOW_MODE | Operation mode (development, production, integration) | development | | DEVFLOW_MEMORY_PATH | Directory for persistent memory storage | ./data | | DEVFLOW_SECURITY_MODE | Security level (strict, standard, permissive) | standard | | DEVFLOW_LOG_LEVEL | Logging verbosity (debug, info, warn, error) | info | | DEVFLOW_MAX_AGENTS | Default concurrent agent limit (increase for more parallelism) | 15 | | DEVFLOW_TOPOLOGY | Default swarm topology | hierarchical | | DEVFLOW_HNSW_M | HNSW index M parameter (connectivity) | 16 | | DEVFLOW_HNSW_EF | HNSW search ef parameter (accuracy) | 200 | | DEVFLOW_EMBEDDING_DIM | Vector embedding dimensions | 384 | | ANTHROPIC_API_KEY | Anthropic API key for Claude integration | - |

Troubleshooting

Common Issues

MCP server won't start

# Check if port is in use
lsof -i :3000
# Kill existing process
kill -9 <PID>
# Restart MCP server
npx devflow-ai@v3alpha mcp start

Agent spawn failures

# Check available memory
free -m
# Reduce max agents if memory constrained
export DEVFLOW_MAX_AGENTS=5

Pattern search returning no results

# Verify patterns are stored
npx devflow-ai@v3alpha hooks metrics
# Re-run pretraining if empty
npx devflow-ai@v3alpha hooks pretrain

Windows path issues

# Use forward slashes or escape backslashes
$env:DEVFLOW_MEMORY_PATH = "./data"
# Or use absolute path
$env:DEVFLOW_MEMORY_PATH = "C:/Users/name/devflow/data"

Permission denied errors

# Fix npm permissions (Linux/macOS)
sudo chown -R $(whoami) ~/.npm
# Or use nvm to manage Node.js

High memory usage

# Enable garbage collection
node --expose-gc node_modules/.bin/devflow-ai
# Reduce HNSW parameters for lower memory
export DEVFLOW_HNSW_M=8
export DEVFLOW_HNSW_EF=100

Migration Guide (V2 → V3)

Breaking Changes

1. Module Structure: V3 uses scoped packages (@devflow/*)
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

# 1. Backup existing data
cp -r ./data ./data-backup-v2

# 2. Update to V3
npm install devflow-ai@latest

# 3. Run migration
npx devflow-ai@v3alpha migrate --from v2

# 4. Verify installation
npx devflow-ai@v3alpha --version
npx devflow-ai@v3alpha hooks metrics

Configuration Changes

# V2 (deprecated)
npx devflow-ai init --mode basic

# V3 (new)
npx devflow-ai@v3alpha init
npx devflow-ai@v3alpha hooks pretrain  # Bootstrap learning

API Changes

| V2 API | V3 API | |--------|--------| | devflow-ai start | devflow-ai 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 | |--------|-------------|------| | @devflow/plugins | Plugin SDK with workers, hooks, providers, security | README | | @devflow/hooks | Event-driven lifecycle hooks + ReasoningBank | Source | | @devflow/memory | AgentDB unification with HNSW indexing | Source | | @devflow/security | CVE remediation & security patterns | Source | | @devflow/swarm | 15-agent coordination engine | Source | | @devflow/cli | CLI modernization | Source | | @devflow/neural | SONA learning integration | Source | | @devflow/testing | TDD London School framework | Source | | @devflow/mcp | MCP server & tools | Source | | @devflow/embeddings | Vector embedding providers | Source | | @devflow/providers | LLM provider integrations | Source | | @devflow/integration | agentic-flow@alpha integration | Source | | @devflow/performance | Benchmarking & optimization | Source | | @devflow/deployment | Release & CI/CD | Source | | @devflow/shared | Shared utilities, types & V3ProgressService | Source |

Additional Resources

• V2 Documentation
• Architecture Decisions (ADRs)
• API Reference
• Examples

Support

• Documentation: https://github.com/samuelmukoti/devflow
• Issues: https://github.com/samuelmukoti/devflow/issues
• Discord: Agentics Foundation

License

MIT - Samuel Mukoti