Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

docs(v3): Add comprehensive V2β†’V3 migration documentation

rUvfec376255d79
diff --git a/v3/docs/v3-migration/BACKWARD-COMPATIBILITY.md b/v3/docs/v3-migration/BACKWARD-COMPATIBILITY.md
new file mode 100644
index 0000000000..39a6901859
--- /dev/null
+++ b/v3/docs/v3-migration/BACKWARD-COMPATIBILITY.md
@@ -0,0 +1,436 @@
+# Backward Compatibility Guide
+
+> Ensuring V2 code works with V3 architecture
+
+## Overview
+
+V3 introduces breaking changes per ADR-001 through ADR-010. This document outlines compatibility layers and migration paths.
+
+## Breaking Changes Summary
+
+### Architecture (ADR-001, ADR-002, ADR-003)
+
+| Change | V2 | V3 | Migration |
+|--------|----|----|-----------|
+| Core Foundation | Custom implementation | agentic-flow@alpha | Update imports |
+| Structure | Flat modules | DDD bounded contexts | Restructure code |
+| Coordination | Multiple orchestrators | UnifiedSwarmCoordinator | Consolidate |
+
+### API Changes (ADR-005)
+
+| Change | V2 | V3 | Migration |
+|--------|----|----|-----------|
+| Tool Naming | Mixed (`dispatch_agent`, `swarm_status`) | Consistent (`agent/spawn`, `swarm/status`) | Update tool calls |
+| Parameters | Inconsistent | Zod-validated schemas | Update params |
+
+### Memory (ADR-006, ADR-009)
+
+| Change | V2 | V3 | Migration |
+|--------|----|----|-----------|
+| Backend | SQLite only | Hybrid SQLite+AgentDB | Configure backend |
+| Search | Brute-force | HNSW indexed | No changes needed |
+
+### Runtime (ADR-010)
+
+| Change | V2 | V3 | Migration |
+|--------|----|----|-----------|
+| Deno | Supported | Removed | Node.js only |
+| Node.js | >=16 | >=20 | Update runtime |
+
+## Compatibility Layers
+
+### Import Aliases
+
+```typescript
+// v3/@claude-flow/shared/src/compat/v2-aliases.ts
+// Provides V2-compatible imports
+
+// V2 imports
+import { HiveMind } from 'claude-flow/hive-mind';
+import { SwarmCoordinator } from 'claude-flow/swarm';
+import { MemoryManager } from 'claude-flow/memory';
+
+// V3 compatibility layer
+export { UnifiedSwarmCoordinator as HiveMind } from '@claude-flow/swarm';
+export { UnifiedSwarmCoordinator as SwarmCoordinator } from '@claude-flow/swarm';
+export { UnifiedMemoryService as MemoryManager } from '@claude-flow/memory';
+```
+
+### Tool Name Mapping
+
+```typescript
+// v3/mcp/tools/compat/v2-tool-names.ts
+// Maps V2 tool names to V3 equivalents
+
+export const toolNameMapping: Record<string, string> = {
+ // Agent tools
+ 'dispatch_agent': 'agent/spawn',
+ 'agents/spawn': 'agent/spawn',
+ 'agents/list': 'agent/list',
+ 'agents/terminate': 'agent/terminate',
+ 'agents/info': 'agent/status',
+ 'agent/create': 'agent/spawn',
+
+ // Swarm tools
+ 'swarm_status': 'swarm/status',
+ 'swarm/get-status': 'swarm/status',
+ 'swarm/get-comprehensive-status': 'swarm/status',
+ 'mcp__ruv-swarm__swarm_init': 'swarm/init',
+ 'mcp__ruv-swarm__swarm_status': 'swarm/status',
+ 'mcp__ruv-swarm__agent_spawn': 'agent/spawn',
+ 'mcp__ruv-swarm__agent_list': 'agent/list',
+ 'mcp__ruv-swarm__agent_metrics': 'agent/status',
+
+ // Memory tools
+ 'memory/query': 'memory/search',
+ 'mcp__ruv-swarm__memory_usage': 'memory/list',
+
+ // Config tools
+ 'config/get': 'config/load',
+ 'config/update': 'config/save',
+
+ // Neural tools (hooks-based in V3)
+ 'mcp__ruv-swarm__neural_status': 'hooks/metrics',
+ 'mcp__ruv-swarm__neural_train': 'hooks/pretrain'
+};
+
+export function translateToolName(v2Name: string): string {
+ return toolNameMapping[v2Name] || v2Name;
+}
+```
+
+### Parameter Translation
+
+```typescript
+// v3/mcp/tools/compat/v2-params.ts
+// Translates V2 parameters to V3 format
+
+export function translateAgentSpawnParams(v2Params: any): any {
+ return {
+ agentType: v2Params.type,
+ id: v2Params.name,
+ config: {
+ capabilities: v2Params.capabilities,
+ systemPrompt: v2Params.systemPrompt,
+ maxConcurrentTasks: v2Params.maxConcurrentTasks
+ },
+ priority: v2Params.priority > 5 ? 'high' : v2Params.priority < 5 ? 'low' : 'normal',
+ metadata: {
+ environment: v2Params.environment,
+ workingDirectory: v2Params.workingDirectory
+ }
+ };
+}
+
+export function translateSwarmInitParams(v2Params: any): any {
+ return {
+ topology: v2Params.topology || 'hierarchical-mesh',
+ maxAgents: v2Params.maxAgents || 15,
+ config: {
+ consensusMechanism: v2Params.consensus || 'majority',
+ loadBalancing: v2Params.strategy === 'balanced'
+ }
+ };
+}
+
+export function translateMemoryQueryParams(v2Params: any): any {
+ return {
+ query: v2Params.search || '',
+ searchType: 'hybrid',
+ type: v2Params.type || 'all',
+ tags: v2Params.tags,
+ limit: v2Params.limit || 10,
+ includeMetadata: true
+ };
+}
+```
+
+### CLI Command Mapping
+
+```typescript
+// v3/@claude-flow/cli/src/compat/v2-commands.ts
+// Provides V2 command aliases
+
+export const commandMapping: Record<string, string[]> = {
+ // Hive commands -> swarm
+ 'hive-mind init': ['swarm', 'init'],
+ 'hive-mind status': ['swarm', 'status'],
+ 'hive-mind spawn': ['agent', 'spawn'],
+
+ // Hook commands
+ 'hooks pre-task': ['hooks', 'pre-edit'], // Closest equivalent
+ 'hooks post-task': ['hooks', 'post-edit'],
+
+ // Deprecated commands
+ 'neural init': ['hooks', 'pretrain'],
+ 'goal init': ['hooks', 'pretrain']
+};
+```
+
+## Configuration Migration
+
+### V2 Configuration
+```yaml
+# v2/.claude-flow/config.yaml
+orchestrator:
+ maxAgents: 10
+ defaultStrategy: balanced
+memory:
+ backend: sqlite
+ path: ./.claude-flow/memory.db
+coordination:
+ topology: hierarchical
+ consensus: quorum
+```
+
+### V3 Configuration
+```yaml
+# v3/.claude-flow/config.yaml
+swarm:
+ topology: hierarchical-mesh
+ maxAgents: 15
+ consensus:
+ mechanism: majority
+ timeout: 30000
+memory:
+ backend: hybrid # SQLite + AgentDB
+ sqlite:
+ path: ./.claude-flow/memory.db
+ agentdb:
+ enableHNSW: true
+ dimensions: 384
+hooks:
+ learning:
+ enabled: true
+ pretrainOnInit: false
+```
+
+### Migration Script
+
+```typescript
+// v3/@claude-flow/cli/src/commands/migrate.ts
+export async function migrateConfig(v2ConfigPath: string): Promise<void> {
+ const v2Config = await loadYaml(v2ConfigPath);
+
+ const v3Config = {
+ swarm: {
+ topology: mapTopology(v2Config.coordination?.topology),
+ maxAgents: v2Config.orchestrator?.maxAgents || 15,
+ consensus: {
+ mechanism: mapConsensus(v2Config.coordination?.consensus),
+ timeout: 30000
+ }
+ },
+ memory: {
+ backend: 'hybrid',
+ sqlite: {
+ path: v2Config.memory?.path || './.claude-flow/memory.db'
+ },
+ agentdb: {
+ enableHNSW: true,
+ dimensions: 384
+ }
+ },
+ hooks: {
+ learning: {
+ enabled: true,
+ pretrainOnInit: false
+ }
+ }
+ };
+
+ await saveYaml('.claude-flow/config.yaml', v3Config);
+}
+
+function mapTopology(v2Topology: string): string {
+ const mapping = {
+ 'hierarchical': 'hierarchical-mesh',
+ 'mesh': 'mesh',
+ 'ring': 'mesh', // Ring deprecated
+ 'star': 'hierarchical' // Star deprecated
+ };
+ return mapping[v2Topology] || 'hierarchical-mesh';
+}
+
+function mapConsensus(v2Consensus: string): string {
+ const mapping = {
+ 'quorum': 'majority',
+ 'unanimous': 'unanimous',
+ 'weighted': 'qualified', // Needs implementation
+ 'leader': 'raft'
+ };
+ return mapping[v2Consensus] || 'majority';
+}
+```
+
+## Memory Data Migration
+
+### Schema Changes
+
+```sql
+-- V2 Schema
+CREATE TABLE memory_entries (
+ id TEXT PRIMARY KEY,
+ namespace TEXT,
+ session_id TEXT,
+ agent_id TEXT,
+ type TEXT,
+ content TEXT,
+ metadata TEXT,
+ tags TEXT,
+ created_at INTEGER,
+ updated_at INTEGER
+);
+
+-- V3 Schema (additional columns)
+ALTER TABLE memory_entries ADD COLUMN embedding BLOB;
+ALTER TABLE memory_entries ADD COLUMN importance REAL DEFAULT 0.5;
+ALTER TABLE memory_entries ADD COLUMN ttl INTEGER;
+ALTER TABLE memory_entries ADD COLUMN access_count INTEGER DEFAULT 0;
+```
+
+### Migration Script
+
+```typescript
+// v3/@claude-flow/memory/src/migration.ts
+export async function migrateMemoryData(v2DbPath: string, v3DbPath: string): Promise<void> {
+ const v2Db = new Database(v2DbPath);
+ const v3Db = new Database(v3DbPath);
+
+ // Create V3 schema
+ v3Db.exec(`
+ CREATE TABLE IF NOT EXISTS memory_entries (
+ id TEXT PRIMARY KEY,
+ namespace TEXT,
+ session_id TEXT,
+ agent_id TEXT,
+ type TEXT,
+ content TEXT,
+ metadata TEXT,
+ tags TEXT,
+ embedding BLOB,
+ importance REAL DEFAULT 0.5,
+ ttl INTEGER,
+ access_count INTEGER DEFAULT 0,
+ created_at INTEGER,
+ updated_at INTEGER
+ )
+ `);
+
+ // Migrate entries
+ const entries = v2Db.prepare('SELECT * FROM memory_entries').all();
+ const insert = v3Db.prepare(`
+ INSERT INTO memory_entries
+ (id, namespace, session_id, agent_id, type, content, metadata, tags, importance, created_at, updated_at)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ `);
+
+ for (const entry of entries) {
+ insert.run(
+ entry.id,
+ entry.namespace,
+ entry.session_id,
+ entry.agent_id,
+ entry.type,
+ entry.content,
+ entry.metadata,
+ entry.tags,
+ 0.5, // Default importance
+ entry.created_at,
+ entry.updated_at
+ );
+ }
+
+ // Generate embeddings for semantic search (async)
+ await generateEmbeddings(v3Db);
+}
+```
+
+## API Compatibility Mode
+
+### Enabling Compatibility Mode
+
+```typescript
+// v3/mcp/server.ts
+import { enableV2Compatibility } from './compat/v2-mode';
+
+const server = createMCPServer({
+ transport: 'stdio',
+ compatibility: {
+ v2: true, // Enable V2 tool name mapping
+ paramTranslation: true, // Enable param translation
+ deprecationWarnings: true // Log deprecation warnings
+ }
+});
+
+if (server.config.compatibility?.v2) {
+ enableV2Compatibility(server);
+}
+```
+
+### Deprecation Warnings
+
+```typescript
+// v3/mcp/tools/compat/deprecation.ts
+export function warnDeprecated(v2Name: string, v3Name: string): void {
+ console.warn(
+ `[DEPRECATION] Tool "${v2Name}" is deprecated. ` +
+ `Use "${v3Name}" instead. ` +
+ `V2 compatibility will be removed in v4.0.0`
+ );
+}
+
+export const deprecatedTools = [
+ { v2: 'dispatch_agent', v3: 'agent/spawn', removed: '4.0.0' },
+ { v2: 'swarm_status', v3: 'swarm/status', removed: '4.0.0' },
+ { v2: 'memory/query', v3: 'memory/search', removed: '4.0.0' },
+ { v2: 'config/get', v3: 'config/load', removed: '4.0.0' },
+ { v2: 'config/update', v3: 'config/save', removed: '4.0.0' }
+];
+```
+
+## Testing Compatibility
+
+```typescript
+// v3/__tests__/compat/v2-compatibility.test.ts
+import { describe, it, expect } from 'vitest';
+import { translateToolName, translateAgentSpawnParams } from '../compat';
+
+describe('V2 Compatibility', () => {
+ describe('Tool Name Translation', () => {
+ it('should translate dispatch_agent to agent/spawn', () => {
+ expect(translateToolName('dispatch_agent')).toBe('agent/spawn');
+ });
+
+ it('should translate swarm_status to swarm/status', () => {
+ expect(translateToolName('swarm_status')).toBe('swarm/status');
+ });
+ });
+
+ describe('Parameter Translation', () => {
+ it('should translate V2 agent spawn params', () => {
+ const v2Params = {
+ type: 'coder',
+ name: 'my-coder',
+ capabilities: ['coding'],
+ priority: 8
+ };
+
+ const v3Params = translateAgentSpawnParams(v2Params);
+
+ expect(v3Params.agentType).toBe('coder');
+ expect(v3Params.id).toBe('my-coder');
+ expect(v3Params.priority).toBe('high');
+ });
+ });
+});
+```
+
+## Deprecation Timeline
+
+| Version | Changes |
+|---------|---------|
+| **v3.0.0** | Compatibility mode enabled by default |
+| **v3.1.0** | Deprecation warnings added |
+| **v3.2.0** | Compatibility mode opt-in |
+| **v4.0.0** | V2 compatibility removed |
diff --git a/v3/docs/v3-migration/CAPABILITY-GAP-ANALYSIS.md b/v3/docs/v3-migration/CAPABILITY-GAP-ANALYSIS.md
new file mode 100644
index 0000000000..bd00dd6634
--- /dev/null
+++ b/v3/docs/v3-migration/CAPABILITY-GAP-ANALYSIS.md
@@ -0,0 +1,352 @@
+# V3 Capability Gap Analysis
+
+> Complete analysis of features present in V2 but missing or changed in V3
+
+## Executive Summary
+
+V3 represents a major architectural overhaul with significant improvements in memory (150x faster search) and neural systems (+11 new features), but has gaps in operational capabilities like task management, session handling, and monitoring.
+
+**Overall Status:**
+- βœ… Memory: Enhanced (20 features vs 14)
+- βœ… Neural: Significantly enhanced (14 features vs 3)
+- ⚠️ Hive-Mind: Partially implemented (12/18)
+- ❌ Hooks: Major gaps (13/42)
+- ❌ MCP Tools: Major gaps (22/65)
+- ❌ CLI: Major gaps (7/25)
+
+---
+
+## 1. Hive-Mind & Swarm Coordination
+
+### Implemented in V3 βœ…
+
+| Feature | V2 Location | V3 Location |
+|---------|-------------|-------------|
+| UnifiedSwarmCoordinator | `v2/src/swarm/coordinator.ts` | `v3/@claude-flow/swarm/src/unified-coordinator.ts` |
+| Topology Manager | `v2/src/core/TopologyManager.ts` | `v3/@claude-flow/swarm/src/topology-manager.ts` |
+| Agent Base Class | `v2/src/hive-mind/core/Agent.ts` | `v3/@claude-flow/swarm/src/domain/entities/` |
+| Event-based Communication | `v2/src/hive-mind/core/Communication.ts` | `v3/@claude-flow/shared/src/events/` |
+| Consensus Engine | `v2/src/hive-mind/integration/ConsensusEngine.ts` | `v3/@claude-flow/swarm/src/consensus/` |
+
+### Missing in V3 ❌
+
+| Feature | V2 Location | Priority | Recommendation |
+|---------|-------------|----------|----------------|
+| **Queen Coordinator** | `v2/src/hive-mind/core/Queen.ts` | HIGH | Implement as specialized agent in swarm module |
+| **HiveMind Core** | `v2/src/hive-mind/core/HiveMind.ts` | HIGH | Integrate into UnifiedSwarmCoordinator |
+| **Collective Memory** | `v2/src/hive-mind/core/Memory.ts` | MEDIUM | Already have better implementation in @claude-flow/memory |
+| **SwarmOrchestrator** | `v2/src/hive-mind/integration/SwarmOrchestrator.ts` | MEDIUM | Merge into UnifiedSwarmCoordinator |
+| **Hive Agent Types** | `v2/src/cli/agents/hive-agents.ts` | MEDIUM | Add QueenAgent, WorkerAgent, ScoutAgent, GuardianAgent |
+| **Maestro Integration** | `v2/src/maestro/maestro-swarm-coordinator.ts` | LOW | Specs-driven workflow support |
+
+### Topology Support
+
+| Topology | V2 | V3 | Notes |
+|----------|----|----|-------|
+| Mesh | βœ… | βœ… | Full support |
+| Hierarchical | βœ… | βœ… | Full support |
+| Ring | βœ… | ⚠️ | Basic support |
+| Star | βœ… | ⚠️ | Basic support |
+| Hierarchical-Mesh | N/A | βœ… | V3 only |
+| Specs-Driven (Maestro) | βœ… | ❌ | Missing |
+
+### Consensus Algorithms
+
+| Algorithm | V2 | V3 | Notes |
+|-----------|----|----|-------|
+| Raft | βœ… | βœ… | Leader-based |
+| Byzantine | βœ… | βœ… | Fault-tolerant |
+| Gossip | βœ… | ⚠️ | Basic support |
+| Proof-of-Learning | βœ… | ❌ | Missing |
+| Simple Majority | βœ… | βœ… | Voting |
+| Supermajority | βœ… | βœ… | 66%+ |
+| Unanimous | βœ… | βœ… | 100% |
+| Qualified Majority | βœ… | ❌ | Expertise-weighted |
+
+---
+
+## 2. Hooks System
+
+### Implemented in V3 βœ…
+
+| Hook | Category | V3 Location |
+|------|----------|-------------|
+| pre-edit | edit | `v3/mcp/tools/hooks-tools.ts` |
+| post-edit | edit | `v3/mcp/tools/hooks-tools.ts` |
+| pre-command | command | `v3/mcp/tools/hooks-tools.ts` |
+| post-command | command | `v3/mcp/tools/hooks-tools.ts` |
+| route | routing | `v3/mcp/tools/hooks-tools.ts` |
+| explain | routing | `v3/mcp/tools/hooks-tools.ts` |
+| pretrain | learning | `v3/mcp/tools/hooks-tools.ts` |
+| metrics | monitoring | `v3/mcp/tools/hooks-tools.ts` |
+| list | utility | `v3/mcp/tools/hooks-tools.ts` |
+
+### Missing in V3 ❌
+
+#### CLI Hooks (14 missing)
+
+| Hook | Priority | V2 Location |
+|------|----------|-------------|
+| **pre-task** | HIGH | `v2/bin/hooks.js` |
+| **post-task** | HIGH | `v2/bin/hooks.js` |
+| **session-end** | HIGH | `v2/bin/hooks.js` |
+| **session-restore** | HIGH | `v2/bin/hooks.js` |
+| post-search | MEDIUM | `v2/bin/hooks.js` |
+| mcp-initialized | MEDIUM | `v2/bin/hooks.js` |
+| agent-spawned | MEDIUM | `v2/bin/hooks.js` |
+| task-orchestrated | MEDIUM | `v2/bin/hooks.js` |
+| neural-trained | MEDIUM | `v2/bin/hooks.js` |
+| notify | LOW | `v2/bin/hooks.js` |
+
+#### Shell Hooks (3 missing)
+
+| Hook | Priority | V2 Location |
+|------|----------|-------------|
+| **bash-hook.sh** | HIGH | `v2/hooks/bash-hook.sh` |
+| **file-hook.sh** | HIGH | `v2/hooks/file-hook.sh` |
+| **git-commit-hook.sh** | MEDIUM | `v2/hooks/git-commit-hook.sh` |
+
+**Recommendation:** Convert shell hooks to TypeScript implementations.
+
+#### Agentic Flow Hooks (20 missing)
+
+| Category | Hooks | Priority |
+|----------|-------|----------|
+| **LLM** | pre-llm-call, post-llm-call, llm-error, llm-retry, llm-fallback | HIGH |
+| **Memory** | pre-memory-store, post-memory-store, memory-sync, memory-persist | MEDIUM |
+| **Neural** | pre-neural-train, post-neural-train, pattern-detected | MEDIUM |
+| **Performance** | performance-optimization, performance-threshold | MEDIUM |
+| **Workflow** | workflow-start, workflow-step, workflow-decision, workflow-complete, workflow-error | HIGH |
+
+#### Verification Hooks (5 missing)
+
+| Hook | Priority | Description |
+|------|----------|-------------|
+| **verification-pre-task** | HIGH | Environment validation |
+| **verification-post-task** | HIGH | Accuracy checking |
+| **verification-integration-test** | MEDIUM | Test suite execution |
+| **verification-truth-telemetry** | MEDIUM | Data consistency |
+| **verification-rollback-trigger** | MEDIUM | Error recovery |
+
+---
+
+## 3. MCP Tools
+
+### Implemented in V3 βœ… (22 tools)
+
+| Category | Tools |
+|----------|-------|
+| Agent | spawn, list, terminate, status |
+| Swarm | init, status, scale |
+| Memory | store, search, list |
+| Config | load, save, validate |
+| Hooks | pre-edit, post-edit, pre-command, post-command, route, explain, pretrain, metrics, list |
+
+### Missing in V3 ❌ (43 tools)
+
+#### Task Management (5 missing) - HIGH PRIORITY
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `tasks/create` | type, description, priority, dependencies | Create new task |
+| `tasks/list` | status, agentId, limit | List tasks |
+| `tasks/status` | taskId | Get task status |
+| `tasks/cancel` | taskId, reason | Cancel task |
+| `tasks/assign` | taskId, agentId | Assign to agent |
+
+#### System Tools (7 missing) - MEDIUM PRIORITY
+
+| Tool | Description |
+|------|-------------|
+| `system/status` | Comprehensive status |
+| `system/metrics` | Performance metrics |
+| `system/health` | Health check |
+| `system/info` | System information |
+| `tools/list` | List all tools |
+| `tools/schema` | Get tool schema |
+
+#### Query Control (2 missing)
+
+| Tool | Description |
+|------|-------------|
+| `query/control` | Pause/resume/terminate queries |
+| `query/list` | List active queries |
+
+#### Workflow (3 missing)
+
+| Tool | Description |
+|------|-------------|
+| `workflow/execute` | Execute workflow |
+| `workflow/create` | Create workflow |
+| `workflow/list` | List workflows |
+
+#### Terminal (3 missing)
+
+| Tool | Description |
+|------|-------------|
+| `terminal/execute` | Execute command |
+| `terminal/list` | List sessions |
+| `terminal/create` | Create session |
+
+#### Swarm (5 missing)
+
+| Tool | Description |
+|------|-------------|
+| `swarm/execute-objective` | Execute objective |
+| `swarm/emergency-stop` | Emergency stop |
+| `agents/spawn_parallel` | Parallel spawn (10-20x faster) |
+| `swarm/monitor` | Real-time monitoring |
+| `task_orchestrate` | Task orchestration |
+
+#### Memory (3 missing)
+
+| Tool | Description |
+|------|-------------|
+| `memory/delete` | Delete entry |
+| `memory/export` | Export to file |
+| `memory/import` | Import from file |
+
+#### Resource & Message (4 missing)
+
+| Tool | Description |
+|------|-------------|
+| `resource/register` | Register resource |
+| `resource/get-statistics` | Resource stats |
+| `message/send` | Send message |
+| `message/get-metrics` | Message metrics |
+
+#### Monitor (2 missing)
+
+| Tool | Description |
+|------|-------------|
+| `monitor/get-metrics` | System metrics |
+| `monitor/get-alerts` | Active alerts |
+
+#### Neural (3 missing)
+
+| Tool | Description |
+|------|-------------|
+| `neural_status` | Neural status |
+| `neural_patterns` | Cognitive patterns |
+| `benchmark_run` | Run benchmarks |
+
+---
+
+## 4. CLI Commands
+
+### Implemented in V3 βœ… (7 commands)
+
+| Command | V3 Location |
+|---------|-------------|
+| agent | `v3/@claude-flow/cli/src/commands/agent.ts` |
+| memory | `v3/@claude-flow/cli/src/commands/memory.ts` |
+| swarm | `v3/@claude-flow/cli/src/commands/swarm.ts` |
+| hooks | `v3/@claude-flow/cli/src/commands/hooks.ts` |
+| mcp | `v3/@claude-flow/cli/src/commands/mcp.ts` |
+| config | `v3/@claude-flow/cli/src/commands/config.ts` |
+| migrate | `v3/@claude-flow/cli/src/commands/migrate.ts` |
+
+### Missing in V3 ❌ (18 commands)
+
+#### Priority 1 - Core
+
+| Command | Subcommands | Description |
+|---------|-------------|-------------|
+| **init** | - | Initialize project |
+| **start** | - | Start orchestrator |
+| **status** | - | System status |
+| **task** | create, list, status, cancel, assign | Task management |
+| **session** | list, save, restore, delete, export | Session management |
+
+#### Priority 2 - Features
+
+| Command | Description |
+|---------|-------------|
+| **hive** | Hive-mind coordination |
+| **sparc** | SPARC methodology |
+| **monitor** | Live dashboard |
+| **github** | GitHub integration |
+| **workflow** | Workflow management |
+
+#### Priority 3 - Utilities
+
+| Command | Description |
+|---------|-------------|
+| neural | Neural module init |
+| goal | GOAP module init |
+| claude | Claude instance spawn |
+| repl | Interactive mode |
+| version | Version info |
+| completion | Shell completion |
+| help | Help system |
+| enterprise | Enterprise features |
+
+---
+
+## 5. Memory System
+
+### V3 Improvements βœ…
+
+| Feature | Improvement |
+|---------|-------------|
+| **HNSW Index** | 150x-12,500x faster vector search |
+| **AgentDB Backend** | Native hnswlib or WASM fallback |
+| **Hybrid Backend** | SQLite + AgentDB per ADR-009 |
+| **SQL.js Backend** | Cross-platform WASM SQLite |
+| **Query Builder** | Fluent API for queries |
+| **Quantization** | 4-32x memory reduction |
+
+### Missing in V3 ❌
+
+| Feature | Priority | Description |
+|---------|----------|-------------|
+| **Markdown Backend** | LOW | Human-readable storage |
+| **Distributed Memory** | MEDIUM | CRDT-based multi-node sync |
+
+---
+
+## 6. Neural System
+
+### V3 Improvements βœ… (+11 new features)
+
+| Feature | Description |
+|---------|-------------|
+| **SONA Manager** | 5 learning modes |
+| **ReasoningBank** | 4-step pipeline |
+| **RL Algorithms** | PPO, DQN, A2C, DT, Q-Learning, SARSA, Curiosity |
+| **Pattern Learner** | Trajectory-based extraction |
+| **LoRA/EWC** | Continual learning |
+
+### Missing in V3 ❌
+
+| Feature | Priority | Description |
+|---------|----------|-------------|
+| **Neural Domain Mapper** | MEDIUM | GNN-based domain mapping |
+
+---
+
+## Recommendations
+
+### Immediate (Week 1-2)
+
+1. Implement task management MCP tools
+2. Add session management CLI commands
+3. Convert shell hooks to TypeScript
+
+### Short-term (Week 3-6)
+
+1. Implement Queen coordinator in swarm module
+2. Add GitHub integration commands
+3. Restore workflow execution
+
+### Medium-term (Week 7-12)
+
+1. Complete verification hooks
+2. Add monitoring dashboard
+3. Implement distributed memory
+
+### Long-term (Week 13+)
+
+1. SPARC methodology
+2. Enterprise features
+3. Markdown backend (optional)
diff --git a/v3/docs/v3-migration/CLI-MIGRATION.md b/v3/docs/v3-migration/CLI-MIGRATION.md
new file mode 100644
index 0000000000..84d6223b1f
--- /dev/null
+++ b/v3/docs/v3-migration/CLI-MIGRATION.md
@@ -0,0 +1,487 @@
+# CLI Commands Migration Guide
+
+> Migrating from V2 CLI (25 commands) to V3 CLI (7 commands)
+
+## Overview
+
+V3 CLI is streamlined with 7 core commands. Many V2 commands need migration or have been consolidated.
+
+## Command Coverage
+
+| Status | V2 Commands | V3 Commands |
+|--------|-------------|-------------|
+| βœ… Implemented | 7 | 7 |
+| ❌ Missing | 18 | - |
+| **Total** | 25 | 7 |
+
+## Implemented Commands βœ…
+
+### agent
+```bash
+# V2
+npx claude-flow agent spawn --type coder --name my-coder
+npx claude-flow agent list --detailed
+npx claude-flow agent info <agentId>
+npx claude-flow agent terminate <agentId>
+
+# V3 (same)
+npx claude-flow agent spawn --type coder --id my-coder
+npx claude-flow agent list --detailed
+npx claude-flow agent status <agentId>
+npx claude-flow agent terminate <agentId>
+```
+
+### memory
+```bash
+# V2
+npx claude-flow memory store --namespace default --content "data"
+npx claude-flow memory query --search "keyword" --limit 10
+npx claude-flow memory list --namespace default
+
+# V3 (enhanced)
+npx claude-flow memory store --type episodic --content "data"
+npx claude-flow memory search --query "keyword" --search-type hybrid
+npx claude-flow memory list --type all --sort-by relevance
+```
+
+### swarm
+```bash
+# V2
+npx claude-flow swarm --strategy auto --max-agents 5
+
+# V3 (enhanced)
+npx claude-flow swarm init --topology hierarchical-mesh --max-agents 15
+npx claude-flow swarm status --include-metrics
+npx claude-flow swarm scale --target 10 --strategy gradual
+```
+
+### hooks
+```bash
+# V2
+npx claude-flow hooks pre-edit --file src/app.ts
+npx claude-flow hooks post-edit --file src/app.ts --success true
+
+# V3 (enhanced with learning)
+npx claude-flow hooks pre-edit src/app.ts
+npx claude-flow hooks post-edit src/app.ts --success true
+npx claude-flow hooks route "implement feature X"
+npx claude-flow hooks explain "implement feature X"
+npx claude-flow hooks pretrain
+npx claude-flow hooks metrics
+```
+
+### mcp
+```bash
+# V2
+npx claude-flow mcp start --port 3000 --transport stdio
+npx claude-flow mcp stop
+npx claude-flow mcp status
+
+# V3 (same)
+npx claude-flow mcp start --port 3000 --transport stdio
+npx claude-flow mcp stop
+npx claude-flow mcp status
+```
+
+### config
+```bash
+# V2
+npx claude-flow config get orchestrator
+npx claude-flow config set orchestrator.maxAgents 10
+
+# V3
+npx claude-flow config load --scope project
+npx claude-flow config save --create-backup
+npx claude-flow config validate --strict
+```
+
+### migrate
+```bash
+# V3 only
+npx claude-flow migrate status
+npx claude-flow migrate run --target all --backup
+npx claude-flow migrate verify
+npx claude-flow migrate rollback --backup-id <id>
+```
+
+## Missing Commands ❌
+
+### Priority 1 - HIGH
+
+#### init
+```bash
+# V2
+npx claude-flow init
+npx claude-flow init --minimal
+npx claude-flow init --flow-nexus
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/init.ts
+export const initCommand = {
+ command: 'init',
+ description: 'Initialize Claude Code integration files',
+ options: [
+ { flags: '-f, --force', description: 'Overwrite existing files' },
+ { flags: '-m, --minimal', description: 'Create minimal configuration' },
+ { flags: '--flow-nexus', description: 'Initialize with Flow Nexus' }
+ ],
+ action: async (options) => {
+ await createClaudeFlowConfig(options);
+ await createDefaultAgents(options);
+ if (!options.minimal) {
+ await createHooksConfig(options);
+ await createWorkflowTemplates(options);
+ }
+ }
+};
+```
+
+#### start
+```bash
+# V2
+npx claude-flow start
+npx claude-flow start --daemon
+npx claude-flow start --port 3000
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/start.ts
+export const startCommand = {
+ command: 'start',
+ description: 'Start the orchestration system',
+ options: [
+ { flags: '-d, --daemon', description: 'Run as daemon' },
+ { flags: '-p, --port <port>', description: 'MCP server port' }
+ ],
+ action: async (options) => {
+ const swarm = await initializeV3Swarm();
+ await swarm.spawnAllAgents();
+ if (options.port) {
+ await startMCPServer({ port: options.port });
+ }
+ }
+};
+```
+
+#### status
+```bash
+# V2
+npx claude-flow status
+npx claude-flow status --watch
+npx claude-flow status --json
+npx claude-flow status --health-check
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/status.ts
+export const statusCommand = {
+ command: 'status',
+ description: 'Show enhanced system status',
+ options: [
+ { flags: '-w, --watch', description: 'Watch mode' },
+ { flags: '-i, --interval <seconds>', description: 'Update interval' },
+ { flags: '--json', description: 'Output in JSON format' },
+ { flags: '--health-check', description: 'Perform health checks' }
+ ],
+ action: async (options) => {
+ const status = await getSystemStatus();
+ if (options.healthCheck) {
+ status.health = await performHealthChecks();
+ }
+ if (options.watch) {
+ await watchStatus(status, options.interval);
+ } else {
+ displayStatus(status, options.json);
+ }
+ }
+};
+```
+
+#### task
+```bash
+# V2
+npx claude-flow task create --type implementation --description "Build feature"
+npx claude-flow task list --status running
+npx claude-flow task status <taskId>
+npx claude-flow task cancel <taskId>
+npx claude-flow task assign <taskId> --agent <agentId>
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/task.ts
+export const taskCommand = {
+ command: 'task',
+ description: 'Manage tasks',
+ subcommands: [
+ {
+ command: 'create',
+ options: [
+ { flags: '-t, --type <type>', description: 'Task type' },
+ { flags: '-d, --description <desc>', description: 'Task description' },
+ { flags: '-p, --priority <priority>', description: 'Task priority' },
+ { flags: '-a, --assign <agentId>', description: 'Assign to agent' }
+ ]
+ },
+ { command: 'list', options: [{ flags: '-s, --status <status>' }] },
+ { command: 'status', args: '<taskId>' },
+ { command: 'cancel', args: '<taskId>' },
+ { command: 'assign', args: '<taskId>', options: [{ flags: '--agent <agentId>' }] }
+ ]
+};
+```
+
+#### session
+```bash
+# V2
+npx claude-flow session list
+npx claude-flow session save --description "Checkpoint"
+npx claude-flow session restore <sessionId>
+npx claude-flow session delete <sessionId>
+npx claude-flow session export --include-memory
+npx claude-flow session import <file>
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/session.ts
+export const sessionCommand = {
+ command: 'session',
+ description: 'Manage Claude-Flow sessions',
+ subcommands: [
+ { command: 'list', options: [{ flags: '-a, --active' }] },
+ { command: 'save', options: [{ flags: '-d, --description <desc>' }] },
+ { command: 'restore', args: '<sessionId>' },
+ { command: 'delete', args: '<sessionId>' },
+ { command: 'export', options: [{ flags: '--include-memory' }] },
+ { command: 'import', args: '<file>' }
+ ]
+};
+```
+
+### Priority 2 - MEDIUM
+
+#### hive
+```bash
+# V2
+npx claude-flow hive --topology mesh --consensus quorum --max-agents 8
+npx claude-flow hive-mind init
+npx claude-flow hive-mind status
+npx claude-flow hive-mind spawn --type queen
+npx claude-flow hive-mind task --description "Task"
+npx claude-flow hive-mind wizard
+npx claude-flow hive-mind pause
+npx claude-flow hive-mind resume
+npx claude-flow hive-mind stop
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/hive.ts
+export const hiveCommand = {
+ command: 'hive',
+ description: 'Hive Mind multi-agent coordination',
+ options: [
+ { flags: '--topology <type>', description: 'Topology: mesh, hierarchical, ring, star' },
+ { flags: '--consensus <type>', description: 'Consensus: quorum, unanimous, weighted' },
+ { flags: '--max-agents <n>', description: 'Maximum agents' }
+ ],
+ subcommands: [
+ { command: 'init' },
+ { command: 'status' },
+ { command: 'spawn', options: [{ flags: '-t, --type <type>' }] },
+ { command: 'task', options: [{ flags: '-d, --description <desc>' }] },
+ { command: 'wizard' },
+ { command: 'pause' },
+ { command: 'resume' },
+ { command: 'stop' }
+ ]
+};
+```
+
+#### sparc
+```bash
+# V2
+npx claude-flow sparc modes
+npx claude-flow sparc info <mode>
+npx claude-flow sparc run --mode specification
+npx claude-flow sparc tdd --sequential
+npx claude-flow sparc workflow --dry-run
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/sparc.ts
+export const sparcCommand = {
+ command: 'sparc',
+ description: 'SPARC methodology commands',
+ subcommands: [
+ { command: 'modes', description: 'List SPARC modes' },
+ { command: 'info', args: '<mode>' },
+ { command: 'run', options: [{ flags: '-m, --mode <mode>' }] },
+ { command: 'tdd', options: [{ flags: '--sequential' }] },
+ { command: 'workflow', options: [{ flags: '--dry-run' }] }
+ ]
+};
+```
+
+#### monitor
+```bash
+# V2
+npx claude-flow monitor
+npx claude-flow monitor --interval 2
+npx claude-flow monitor --compact
+npx claude-flow monitor --focus agents
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/monitor.ts
+export const monitorCommand = {
+ command: 'monitor',
+ description: 'Start live monitoring dashboard',
+ options: [
+ { flags: '-i, --interval <seconds>', description: 'Update interval' },
+ { flags: '-c, --compact', description: 'Compact view' },
+ { flags: '--focus <component>', description: 'Focus on component' }
+ ],
+ action: async (options) => {
+ const dashboard = createDashboard(options);
+ await dashboard.start();
+ }
+};
+```
+
+#### github
+```bash
+# V2
+npx claude-flow github init
+npx claude-flow github gh-coordinator
+npx claude-flow github pr-manager
+npx claude-flow github issue-tracker
+npx claude-flow github release-manager
+npx claude-flow github repo-architect
+npx claude-flow github sync-coordinator
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/github.ts
+export const githubCommand = {
+ command: 'github',
+ description: 'GitHub workflow automation',
+ subcommands: [
+ { command: 'init' },
+ { command: 'gh-coordinator' },
+ { command: 'pr-manager' },
+ { command: 'issue-tracker' },
+ { command: 'release-manager' },
+ { command: 'repo-architect' },
+ { command: 'sync-coordinator' }
+ ],
+ options: [
+ { flags: '--auto-approve', description: 'Auto-approve permissions' },
+ { flags: '--dry-run', description: 'Preview only' }
+ ]
+};
+```
+
+### Priority 3 - LOW
+
+#### neural
+```bash
+# V2
+npx claude-flow neural init
+npx claude-flow neural init --force --target .claude/agents/neural
+
+# V3: Replaced by hooks pretrain
+npx claude-flow hooks pretrain
+```
+
+#### goal
+```bash
+# V2
+npx claude-flow goal init
+
+# V3: Replaced by hooks system
+npx claude-flow hooks pretrain --include-goap
+```
+
+#### claude
+```bash
+# V2
+npx claude-flow claude spawn --tools View,Edit,Bash --mode full
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/claude.ts
+export const claudeCommand = {
+ command: 'claude',
+ description: 'Spawn Claude instances',
+ subcommands: [
+ {
+ command: 'spawn',
+ options: [
+ { flags: '-t, --tools <tools>', description: 'Allowed tools' },
+ { flags: '-m, --mode <mode>', description: 'Dev mode' },
+ { flags: '--parallel', description: 'Enable parallel execution' }
+ ]
+ }
+ ]
+};
+```
+
+#### workflow
+```bash
+# V2
+npx claude-flow workflow create --name "my-workflow"
+npx claude-flow workflow execute <workflow>
+npx claude-flow workflow list
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/workflow.ts
+```
+
+#### repl
+```bash
+# V2
+npx claude-flow repl
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/repl.ts
+export const replCommand = {
+ command: 'repl',
+ description: 'Start interactive REPL mode',
+ action: async () => {
+ const rl = createInterface({ input: stdin, output: stdout });
+ // REPL loop
+ }
+};
+```
+
+#### version
+```bash
+# V2
+npx claude-flow version
+npx claude-flow version --short
+
+# V3 Migration needed:
+# Add version flag to CLI root
+```
+
+#### completion
+```bash
+# V2
+npx claude-flow completion bash
+npx claude-flow completion --install
+
+# V3 Migration needed:
+# Add to v3/@claude-flow/cli/src/commands/completion.ts
+```
+
+## Implementation Plan
+
+### Phase 1 (Week 1-2): Core Commands
+1. `init` - Project initialization
+2. `start` - System startup
+3. `status` - System status
+4. `task` - Task management
+5. `session` - Session management
+
+### Phase 2 (Week 3-4): Feature Commands
+1. `hive` - Hive-mind mode
+2. `sparc` - SPARC methodology
+3. `monitor` - Live dashboard
+4. `github` - GitHub integration
+
+### Phase 3 (Week 5-6): Utilities
+1. `workflow` - Workflow management
+2. `claude` - Claude spawning
+3. `repl` - Interactive mode
+4. `version` - Version info
+5. `completion` - Shell completion
diff --git a/v3/docs/v3-migration/HIVE-MIND-MIGRATION.md b/v3/docs/v3-migration/HIVE-MIND-MIGRATION.md
new file mode 100644
index 0000000000..0d0bacded9
--- /dev/null
+++ b/v3/docs/v3-migration/HIVE-MIND-MIGRATION.md
@@ -0,0 +1,365 @@
+# Hive-Mind Migration Guide
+
+> Migrating from V2 Hive-Mind to V3 Swarm Coordination
+
+## Overview
+
+V2's Hive-Mind system is a comprehensive multi-agent coordination framework. V3 consolidates this into the `@claude-flow/swarm` module with a unified `SwarmCoordinator` per ADR-003.
+
+## Architecture Comparison
+
+### V2 Hive-Mind Structure
+```
+v2/src/hive-mind/
+β”œβ”€β”€ core/
+β”‚ β”œβ”€β”€ HiveMind.ts # Main orchestrator
+β”‚ β”œβ”€β”€ Queen.ts # Strategic coordinator
+β”‚ β”œβ”€β”€ Agent.ts # Agent base class
+β”‚ β”œβ”€β”€ Memory.ts # Collective memory
+β”‚ └── Communication.ts # Inter-agent messaging
+β”œβ”€β”€ integration/
+β”‚ β”œβ”€β”€ ConsensusEngine.ts # Voting & consensus
+β”‚ β”œβ”€β”€ SwarmOrchestrator.ts
+β”‚ └── MCPToolWrapper.ts
+└── types.ts
+```
+
+### V3 Swarm Structure
+```
+v3/@claude-flow/swarm/
+β”œβ”€β”€ src/
+β”‚ β”œβ”€β”€ unified-coordinator.ts # Main coordinator (ADR-003)
+β”‚ β”œβ”€β”€ topology-manager.ts # Topology handling
+β”‚ β”œβ”€β”€ types.ts
+β”‚ β”œβ”€β”€ consensus/
+β”‚ β”‚ └── consensus-engine.ts
+β”‚ β”œβ”€β”€ coordination/
+β”‚ β”‚ └── coordinator.ts
+β”‚ β”œβ”€β”€ domain/
+β”‚ β”‚ β”œβ”€β”€ entities/
+β”‚ β”‚ β”œβ”€β”€ repositories/
+β”‚ β”‚ └── services/
+β”‚ └── application/
+β”‚ β”œβ”€β”€ commands/
+β”‚ └── services/
+```
+
+## Feature Migration Map
+
+### Core Components
+
+| V2 Component | V3 Equivalent | Status |
+|--------------|---------------|--------|
+| `HiveMind.ts` | `unified-coordinator.ts` | ⚠️ Partial |
+| `Queen.ts` | Missing | ❌ Needs implementation |
+| `Agent.ts` | `domain/entities/agent.ts` | βœ… Complete |
+| `Memory.ts` | `@claude-flow/memory` | βœ… Enhanced |
+| `Communication.ts` | `@claude-flow/shared/events` | βœ… Complete |
+
+### Queen Coordinator - MISSING
+
+The V2 Queen provides:
+- Strategic decision-making with MCP neural analysis
+- Agent capability scoring for task assignment
+- Coordination strategies per topology
+- Consensus initiation for critical tasks
+- Performance pattern training
+- Task stall detection and recovery
+
+**Migration Path:**
+```typescript
+// V3 Implementation needed in @claude-flow/swarm/src/queen-coordinator.ts
+export class QueenCoordinator {
+ private swarm: UnifiedSwarmCoordinator;
+ private neural: NeuralLearningSystem;
+
+ async analyzeTask(task: Task): Promise<TaskAnalysis> {
+ // Use ReasoningBank for pattern analysis
+ const patterns = await this.neural.retrievePatterns(task.description);
+ return this.scoreAgents(task, patterns);
+ }
+
+ async selectStrategy(topology: TopologyType): Promise<CoordinationStrategy> {
+ const strategies = {
+ 'hierarchical': 'hierarchical-cascade',
+ 'mesh': 'mesh-consensus',
+ 'hierarchical-mesh': 'adaptive-default'
+ };
+ return strategies[topology] || 'adaptive-default';
+ }
+
+ async initiateConsensus(proposal: ConsensusProposal): Promise<ConsensusResult> {
+ return this.swarm.consensus.propose(proposal);
+ }
+}
+```
+
+## Topologies
+
+### Supported Topologies
+
+| Topology | V2 | V3 | Migration Notes |
+|----------|----|----|-----------------|
+| **mesh** | βœ… All-to-all | βœ… All-to-all | Direct migration |
+| **hierarchical** | βœ… Tree structure | βœ… Tree structure | Direct migration |
+| **ring** | βœ… Circular | ⚠️ Basic | Enhance circular handling |
+| **star** | βœ… Central hub | ⚠️ Basic | Enhance hub management |
+| **hierarchical-mesh** | ❌ | βœ… V3 only | New hybrid topology |
+| **specs-driven** | βœ… Maestro | ❌ Missing | Implement workflow pattern |
+
+### V2 Topology Configuration
+```typescript
+// V2: v2/src/core/TopologyManager.ts
+const topologyConfigs = {
+ mesh: {
+ connectionType: 'direct',
+ reliability: 0.95,
+ latencyMs: 50
+ },
+ hierarchical: {
+ connectionType: 'direct+relay',
+ reliability: 0.85,
+ latencyMs: 100
+ },
+ ring: {
+ connectionType: 'direct',
+ reliability: 0.75,
+ latencyMs: 75
+ },
+ star: {
+ connectionType: 'direct',
+ reliability: 0.70,
+ latencyMs: 60
+ }
+};
+```
+
+### V3 Topology Configuration
+```typescript
+// V3: v3/@claude-flow/swarm/src/topology-manager.ts
+const topologyConfigs = {
+ mesh: { /* similar */ },
+ hierarchical: { /* similar */ },
+ 'hierarchical-mesh': {
+ connectionType: 'hybrid',
+ reliability: 0.92,
+ latencyMs: 70,
+ queenCoordination: true
+ }
+};
+```
+
+## Consensus Algorithms
+
+### Implemented in V3 βœ…
+
+```typescript
+// V3: v3/@claude-flow/swarm/src/consensus/consensus-engine.ts
+export class ConsensusEngine {
+ async raft(proposal: Proposal): Promise<ConsensusResult>;
+ async byzantine(proposal: Proposal): Promise<ConsensusResult>;
+ async simpleMajority(proposal: Proposal): Promise<ConsensusResult>;
+ async supermajority(proposal: Proposal): Promise<ConsensusResult>;
+ async unanimous(proposal: Proposal): Promise<ConsensusResult>;
+}
+```
+
+### Missing in V3 ❌
+
+```typescript
+// Need to implement:
+export class ConsensusEngine {
+ // Missing: Performance-weighted voting
+ async proofOfLearning(proposal: Proposal): Promise<ConsensusResult> {
+ const votes = await this.collectWeightedVotes(proposal);
+ const weighted = votes.map(v => ({
+ ...v,
+ weight: v.agent.performanceScore * v.agent.learningScore
+ }));
+ return this.tallyWeighted(weighted);
+ }
+
+ // Missing: Expertise-weighted
+ async qualifiedMajority(proposal: Proposal, expertiseWeights: Map<string, number>): Promise<ConsensusResult>;
+
+ // Missing: Eventually consistent
+ async gossip(proposal: Proposal): Promise<ConsensusResult>;
+}
+```
+
+## Agent Types
+
+### V2 Hive Agent Types
+```typescript
+// v2/src/cli/agents/hive-agents.ts
+const hiveAgentTypes = {
+ queen: {
+ role: 'Orchestrator and Decision Maker',
+ capabilities: ['orchestration', 'consensus', 'decision-making', 'delegation'],
+ reliability: 0.95
+ },
+ worker: {
+ role: 'Implementation Specialist',
+ capabilities: ['implementation', 'coding', 'testing', 'debugging'],
+ reliability: 0.90
+ },
+ scout: {
+ role: 'Research and Exploration',
+ capabilities: ['research', 'exploration', 'analysis', 'discovery'],
+ reliability: 0.85
+ },
+ guardian: {
+ role: 'Quality Assurance',
+ capabilities: ['validation', 'security', 'quality', 'review'],
+ reliability: 0.98
+ },
+ architect: {
+ role: 'System Design',
+ capabilities: ['design', 'planning', 'architecture', 'patterns'],
+ reliability: 0.92
+ }
+};
+```
+
+### V3 Agent Types
+```typescript
+// v3/@claude-flow/swarm/src/types.ts
+// V3 has 15-agent hierarchical mesh but missing hive-specific types
+// Need to add hive agent type definitions for backward compatibility
+```
+
+**Migration Action:** Add hive agent types to V3 agent type registry.
+
+## CLI Migration
+
+### V2 Hive Commands
+```bash
+# V2 Commands
+npx claude-flow hive --topology mesh --consensus quorum --max-agents 8
+npx claude-flow hive-mind init
+npx claude-flow hive-mind status
+npx claude-flow hive-mind spawn --type queen
+npx claude-flow hive-mind task --description "Implement feature"
+npx claude-flow hive-mind wizard
+npx claude-flow hive-mind pause
+npx claude-flow hive-mind resume
+npx claude-flow hive-mind stop
+npx claude-flow hive-mind ps
+npx claude-flow hive-mind optimize-memory
+```
+
+### V3 Equivalent Commands
+```bash
+# V3 Commands (partial coverage)
+npx claude-flow swarm init --topology hierarchical-mesh --max-agents 15
+npx claude-flow swarm status
+npx claude-flow agent spawn --type queen-coordinator
+
+# Missing V3 commands:
+# - hive (dedicated hive mode)
+# - hive-mind task
+# - hive-mind wizard
+# - hive-mind pause/resume/stop
+# - hive-mind ps
+# - hive-mind optimize-memory
+```
+
+## MCP Tool Migration
+
+### V2 Hive-Mind MCP Tools
+```typescript
+// V2 tools from v2/src/mcp/swarm-tools.ts
+const hiveMindTools = [
+ 'dispatch_agent', // Legacy agent spawn
+ 'swarm_status', // Swarm status
+ 'swarm/create-objective',
+ 'swarm/execute-objective', // Missing in V3
+ 'swarm/get-status',
+ 'swarm/emergency-stop' // Missing in V3
+];
+```
+
+### V3 Swarm MCP Tools
+```typescript
+// V3 tools from v3/mcp/tools/swarm-tools.ts
+const swarmTools = [
+ 'swarm/init',
+ 'swarm/status',
+ 'swarm/scale' // New in V3
+];
+
+// Missing: execute-objective, emergency-stop
+```
+
+## Migration Steps
+
+### Step 1: Update Imports
+```typescript
+// V2
+import { HiveMind } from 'claude-flow/hive-mind';
+import { Queen } from 'claude-flow/hive-mind/core/Queen';
+
+// V3
+import { UnifiedSwarmCoordinator } from '@claude-flow/swarm';
+// Queen needs to be implemented
+```
+
+### Step 2: Initialize Swarm
+```typescript
+// V2
+const hive = new HiveMind({
+ topology: 'hierarchical',
+ consensus: 'quorum',
+ maxAgents: 8
+});
+await hive.initialize();
+await hive.spawnQueen();
+
+// V3
+const swarm = new UnifiedSwarmCoordinator({
+ topology: 'hierarchical-mesh',
+ maxAgents: 15,
+ consensus: 'majority'
+});
+await swarm.initialize();
+// Queen spawn needs implementation
+```
+
+### Step 3: Submit Tasks
+```typescript
+// V2
+const task = await hive.submitTask({
+ type: 'implementation',
+ description: 'Implement feature X',
+ priority: 'high',
+ consensus: true
+});
+
+// V3
+const task = await swarm.submitTask({
+ type: 'implementation',
+ title: 'Implement feature X',
+ description: 'Details...',
+ priority: 'high'
+ // consensus not yet supported
+});
+```
+
+## Implementation Priorities
+
+### Priority 1 - HIGH
+1. **Queen Coordinator** - Strategic decision-making
+2. **Proof-of-Learning Consensus** - Performance-weighted voting
+3. **Execute Objective** - MCP tool
+4. **Emergency Stop** - MCP tool
+
+### Priority 2 - MEDIUM
+1. **Specs-Driven Topology** - Maestro workflow
+2. **Hive CLI Command** - Full hive mode
+3. **Task Wizard** - Interactive task creation
+4. **Qualified Majority** - Expertise-weighted consensus
+
+### Priority 3 - LOW
+1. **Gossip Consensus** - Eventually consistent
+2. **PS Command** - Process listing
+3. **Optimize Memory** - Memory optimization command
diff --git a/v3/docs/v3-migration/HOOKS-MIGRATION.md b/v3/docs/v3-migration/HOOKS-MIGRATION.md
new file mode 100644
index 0000000000..1e0889eaa3
--- /dev/null
+++ b/v3/docs/v3-migration/HOOKS-MIGRATION.md
@@ -0,0 +1,467 @@
+# Hooks System Migration Guide
+
+> Migrating from V2 Self-Learning Hooks to V3 ReasoningBank-Based Hooks
+
+## Overview
+
+V2 has an extensive hooks system with 42+ hook types across CLI, shell scripts, and agentic-flow integrations. V3 consolidates this into a ReasoningBank-based system with 13 core hooks, but many V2 hooks need migration.
+
+## Architecture Comparison
+
+### V2 Hooks Architecture
+```
+v2/
+β”œβ”€β”€ hooks/ # Shell hooks
+β”‚ β”œβ”€β”€ bash-hook.sh # Bash safety
+β”‚ β”œβ”€β”€ file-hook.sh # File operations
+β”‚ └── git-commit-hook.sh # Git formatting
+β”œβ”€β”€ bin/hooks.js # CLI hooks (14 types)
+└── src/
+ β”œβ”€β”€ hooks/
+ β”‚ β”œβ”€β”€ hook-matchers.ts # Pattern matching
+ β”‚ └── redaction-hook.ts # Secret redaction
+ β”œβ”€β”€ services/agentic-flow-hooks/
+ β”‚ β”œβ”€β”€ hook-manager.ts # Hook orchestration
+ β”‚ β”œβ”€β”€ llm-hooks.ts # LLM operations
+ β”‚ β”œβ”€β”€ memory-hooks.ts # Memory operations
+ β”‚ β”œβ”€β”€ neural-hooks.ts # Neural training
+ β”‚ β”œβ”€β”€ performance-hooks.ts # Performance
+ β”‚ └── workflow-hooks.ts # Workflow lifecycle
+ └── verification/hooks.ts # Verification
+```
+
+### V3 Hooks Architecture
+```
+v3/
+β”œβ”€β”€ @claude-flow/shared/src/hooks/
+β”‚ β”œβ”€β”€ registry.ts # Hook registration
+β”‚ └── executor.ts # Hook execution
+β”œβ”€β”€ @claude-flow/cli/src/commands/
+β”‚ └── hooks.ts # CLI commands
+└── mcp/tools/hooks-tools.ts # MCP tools (9 hooks)
+```
+
+## Hook Migration Status
+
+### Core Hooks - Implemented βœ…
+
+| Hook | V2 | V3 | Notes |
+|------|----|----|-------|
+| pre-edit | `bin/hooks.js` | `hooks-tools.ts` | ReasoningBank integration |
+| post-edit | `bin/hooks.js` | `hooks-tools.ts` | Trajectory recording |
+| pre-command | `bin/hooks.js` | `hooks-tools.ts` | Risk assessment |
+| post-command | `bin/hooks.js` | `hooks-tools.ts` | Outcome learning |
+| route | New in V3 | `hooks-tools.ts` | Pattern-based routing |
+| explain | New in V3 | `hooks-tools.ts` | Decision transparency |
+| pretrain | CLAUDE.md | `hooks-tools.ts` | Repository bootstrap |
+| metrics | CLAUDE.md | `hooks-tools.ts` | Learning dashboard |
+| list | New in V3 | `hooks-tools.ts` | Hook listing |
+
+### CLI Hooks - Missing ❌
+
+| Hook | V2 Location | Priority | V3 Migration Path |
+|------|-------------|----------|-------------------|
+| **pre-task** | `bin/hooks.js` | HIGH | Add to hooks-tools.ts |
+| **post-task** | `bin/hooks.js` | HIGH | Add to hooks-tools.ts |
+| **session-end** | `bin/hooks.js` | HIGH | Add session management |
+| **session-restore** | `bin/hooks.js` | HIGH | Add session management |
+| post-search | `bin/hooks.js` | MEDIUM | Add search caching |
+| mcp-initialized | `bin/hooks.js` | LOW | MCP internal |
+| agent-spawned | `bin/hooks.js` | LOW | Event-based |
+| task-orchestrated | `bin/hooks.js` | LOW | Event-based |
+| neural-trained | `bin/hooks.js` | MEDIUM | Add to neural module |
+| notify | `bin/hooks.js` | LOW | Add notification system |
+
+### Shell Hooks - Missing ❌
+
+These need TypeScript conversions:
+
+#### bash-hook.sh β†’ bash-safety.ts
+```typescript
+// V2: hooks/bash-hook.sh
+// Features:
+// - Add -i flag to rm commands
+// - Alias ll -> ls -lah
+// - Redirect test files to /tmp
+// - Warn about secrets in commands
+// - Warn about missing dependencies
+
+// V3 Migration:
+export class BashSafetyHook {
+ private dangerousPatterns = [
+ /rm\s+-rf\s+\//,
+ /dd\s+if=/,
+ /mkfs\./,
+ />\s*\/dev\/sd/
+ ];
+
+ private secretPatterns = [
+ /password\s*=/i,
+ /api[_-]?key\s*=/i,
+ /secret\s*=/i,
+ /token\s*=/i
+ ];
+
+ async preCommand(command: string): Promise<HookResult> {
+ // Check for dangerous commands
+ for (const pattern of this.dangerousPatterns) {
+ if (pattern.test(command)) {
+ return { blocked: true, reason: 'Dangerous command detected' };
+ }
+ }
+
+ // Check for secrets
+ for (const pattern of this.secretPatterns) {
+ if (pattern.test(command)) {
+ return { warning: 'Potential secret in command', redacted: this.redact(command) };
+ }
+ }
+
+ // Add safety flags
+ let modified = command;
+ if (command.includes('rm ') && !command.includes('-i')) {
+ modified = command.replace(/rm\s+/, 'rm -i ');
+ }
+
+ return { modified, warnings: [] };
+ }
+}
+```
+
+#### file-hook.sh β†’ file-organization.ts
+```typescript
+// V2: hooks/file-hook.sh
+// Features:
+// - Block writes to root folder
+// - Move test files to /tests/
+// - Move source to /src/
+// - Suggest formatters (Prettier, Black, gofmt)
+// - Suggest linter configs
+
+// V3 Migration:
+export class FileOrganizationHook {
+ private rootBlockedPatterns = [
+ /^[^\/]+\.(ts|js|py|go|rs)$/, // Source files
+ /^[^\/]+\.test\.(ts|js)$/, // Test files
+ /^[^\/]+\.spec\.(ts|js)$/ // Spec files
+ ];
+
+ private directoryMappings = {
+ 'test': 'tests/',
+ 'spec': 'tests/',
+ 'src': 'src/'
+ };
+
+ async preEdit(filePath: string, operation: string): Promise<HookResult> {
+ const fileName = path.basename(filePath);
+ const dirName = path.dirname(filePath);
+
+ // Block root folder writes
+ if (dirName === '.' || dirName === '') {
+ for (const pattern of this.rootBlockedPatterns) {
+ if (pattern.test(fileName)) {
+ const suggested = this.suggestDirectory(fileName);
+ return {
+ blocked: true,
+ reason: `Don't write to root. Suggested: ${suggested}`
+ };
+ }
+ }
+ }
+
+ // Suggest formatters
+ const formatter = this.suggestFormatter(filePath);
+
+ return {
+ warnings: formatter ? [`Consider running ${formatter}`] : []
+ };
+ }
+
+ private suggestFormatter(filePath: string): string | null {
+ const ext = path.extname(filePath);
+ const formatters = {
+ '.ts': 'prettier --write',
+ '.js': 'prettier --write',
+ '.py': 'black',
+ '.go': 'gofmt -w',
+ '.rs': 'rustfmt'
+ };
+ return formatters[ext] || null;
+ }
+}
+```
+
+#### git-commit-hook.sh β†’ git-commit.ts
+```typescript
+// V2: hooks/git-commit-hook.sh
+// Features:
+// - Conventional commit prefixes
+// - JIRA ticket extraction from branch
+// - Co-Authored-By addition
+// - Heredoc formatting
+
+// V3 Migration:
+export class GitCommitHook {
+ private commitTypes = {
+ feat: /^(add|implement|create|new)/i,
+ fix: /^(fix|resolve|repair|patch)/i,
+ docs: /^(doc|readme|comment)/i,
+ refactor: /^(refactor|restructure|reorganize)/i,
+ test: /^(test|spec|coverage)/i,
+ chore: /^(chore|update|upgrade|bump)/i
+ };
+
+ async preCommit(message: string, branchName: string): Promise<HookResult> {
+ let modified = message;
+
+ // Detect commit type
+ const type = this.detectType(message);
+ if (type && !message.startsWith(`${type}:`)) {
+ modified = `${type}: ${message}`;
+ }
+
+ // Extract JIRA ticket
+ const ticket = this.extractTicket(branchName);
+ if (ticket && !modified.includes(ticket)) {
+ modified = `${modified}\n\nRefs: ${ticket}`;
+ }
+
+ // Add co-author
+ modified += '\n\nπŸ€– Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude <[email protected]>';
+
+ return { modified };
+ }
+
+ private detectType(message: string): string | null {
+ for (const [type, pattern] of Object.entries(this.commitTypes)) {
+ if (pattern.test(message)) return type;
+ }
+ return null;
+ }
+
+ private extractTicket(branch: string): string | null {
+ const match = branch.match(/([A-Z]+-\d+)/);
+ return match ? match[1] : null;
+ }
+}
+```
+
+### Agentic Flow Hooks - Missing ❌
+
+#### LLM Hooks (5 missing)
+```typescript
+// V2: src/services/agentic-flow-hooks/llm-hooks.ts
+// Need to implement:
+export interface LLMHooks {
+ preLLMCall(request: LLMRequest): Promise<LLMRequest>;
+ postLLMCall(response: LLMResponse): Promise<LLMResponse>;
+ llmError(error: Error): Promise<ErrorHandler>;
+ llmRetry(attempt: number): Promise<RetryConfig>;
+ llmFallback(provider: string): Promise<string>;
+}
+```
+
+#### Memory Hooks (5 missing)
+```typescript
+// V2: src/services/agentic-flow-hooks/memory-hooks.ts
+// Need to implement:
+export interface MemoryHooks {
+ preMemoryStore(entry: MemoryEntry): Promise<MemoryEntry>;
+ postMemoryStore(entry: MemoryEntry): Promise<void>;
+ memorySync(entries: MemoryEntry[]): Promise<SyncResult>;
+ memoryPersist(): Promise<PersistResult>;
+ memoryExpire(expired: MemoryEntry[]): Promise<void>;
+}
+```
+
+#### Neural Hooks (3 missing)
+```typescript
+// V2: src/services/agentic-flow-hooks/neural-hooks.ts
+// Need to implement:
+export interface NeuralHooks {
+ preNeuralTrain(data: TrainingData): Promise<TrainingData>;
+ postNeuralTrain(result: TrainingResult): Promise<void>;
+ patternDetected(pattern: Pattern): Promise<void>;
+}
+```
+
+#### Performance Hooks (4 missing)
+```typescript
+// V2: src/services/agentic-flow-hooks/performance-hooks.ts
+// Need to implement:
+export interface PerformanceHooks {
+ performanceMetric(metric: Metric): Promise<void>;
+ performanceBottleneck(bottleneck: Bottleneck): Promise<Optimization[]>;
+ performanceOptimization(optimization: Optimization): Promise<ApplyResult>;
+ performanceThreshold(threshold: Threshold): Promise<ThresholdAdjustment>;
+}
+```
+
+#### Workflow Hooks (5 missing)
+```typescript
+// V2: src/services/agentic-flow-hooks/workflow-hooks.ts
+// Need to implement:
+export interface WorkflowHooks {
+ workflowStart(workflow: Workflow): Promise<void>;
+ workflowStep(step: WorkflowStep): Promise<StepOptimization>;
+ workflowDecision(decision: Decision): Promise<DecisionEnhancement>;
+ workflowComplete(workflow: Workflow): Promise<LearningExtraction>;
+ workflowError(error: WorkflowError): Promise<RecoveryStrategy>;
+}
+```
+
+### Verification Hooks - Missing ❌
+
+```typescript
+// V2: src/verification/hooks.ts
+// Need to implement:
+export interface VerificationHooks {
+ verificationPreTask(task: Task): Promise<VerificationResult>;
+ verificationPostTask(task: Task, result: TaskResult): Promise<ValidationResult>;
+ verificationIntegrationTest(suite: TestSuite): Promise<TestResult>;
+ verificationTruthTelemetry(data: any): Promise<TruthScore>;
+ verificationRollbackTrigger(error: Error): Promise<RollbackPlan>;
+}
+```
+
+## Hook Registration
+
+### V2 Hook Manager
+```typescript
+// V2: src/services/agentic-flow-hooks/hook-manager.ts
+class AgenticHookManager {
+ private hooks: Map<HookType, HookRegistration[]>;
+
+ register(type: HookType, hook: Hook, options: HookOptions): void;
+ execute(type: HookType, context: HookContext): Promise<HookResult>;
+ unregister(type: HookType, hookId: string): void;
+}
+```
+
+### V3 Hook Registry
+```typescript
+// V3: @claude-flow/shared/src/hooks/registry.ts
+class HookRegistry {
+ register(hook: HookDefinition): void;
+ getHook(name: string): HookDefinition | undefined;
+ listHooks(): HookDefinition[];
+ enable(name: string): void;
+ disable(name: string): void;
+}
+```
+
+### Migration Path
+```typescript
+// Migration: Adapt V2 hook manager to V3 registry
+import { HookRegistry } from '@claude-flow/shared/hooks';
+
+const registry = new HookRegistry();
+
+// Register V2-style hooks
+registry.register({
+ name: 'pre-task',
+ type: 'pre',
+ category: 'task',
+ priority: 'high',
+ handler: async (context) => {
+ // V2 pre-task logic
+ await storeTaskData(context.taskId, context.description);
+ if (context.autoSpawnAgents) {
+ await spawnRequiredAgents(context);
+ }
+ return { proceed: true };
+ }
+});
+```
+
+## CLI Commands
+
+### V2 Hooks CLI
+```bash
+# V2 Commands
+npx claude-flow hooks pre-task --description "Task" --task-id ID
+npx claude-flow hooks post-task --task-id ID
+npx claude-flow hooks pre-edit --file path
+npx claude-flow hooks post-edit --file path --success true
+npx claude-flow hooks pre-command --command "npm test"
+npx claude-flow hooks post-command --command "npm test" --success true
+npx claude-flow hooks session-end
+npx claude-flow hooks session-restore --session-id latest
+npx claude-flow hooks notify --message "Done" --level success
+```
+
+### V3 Hooks CLI
+```bash
+# V3 Commands (implemented)
+npx claude-flow hooks pre-edit <filePath>
+npx claude-flow hooks post-edit <filePath> --success true
+npx claude-flow hooks pre-command "<command>"
+npx claude-flow hooks post-command "<command>" --success true
+npx claude-flow hooks route "<task description>"
+npx claude-flow hooks explain "<task description>"
+npx claude-flow hooks pretrain
+npx claude-flow hooks metrics
+
+# Missing V3 commands:
+# - hooks pre-task
+# - hooks post-task
+# - hooks session-end
+# - hooks session-restore
+# - hooks notify
+# - hooks build-agents
+# - hooks transfer
+# - hooks intelligence
+```
+
+## MCP Tools
+
+### V3 Hooks MCP Tools (Implemented)
+```typescript
+// v3/mcp/tools/hooks-tools.ts
+const hooksTools = [
+ 'hooks/pre-edit',
+ 'hooks/post-edit',
+ 'hooks/pre-command',
+ 'hooks/post-command',
+ 'hooks/route',
+ 'hooks/explain',
+ 'hooks/pretrain',
+ 'hooks/metrics',
+ 'hooks/list'
+];
+```
+
+### Missing MCP Tools
+```typescript
+// Need to add:
+const missingTools = [
+ 'hooks/pre-task',
+ 'hooks/post-task',
+ 'hooks/session-start',
+ 'hooks/session-end',
+ 'hooks/session-restore',
+ 'hooks/build-agents',
+ 'hooks/transfer',
+ 'hooks/intelligence'
+];
+```
+
+## Implementation Priorities
+
+### Priority 1 - HIGH (Week 1-2)
+1. **pre-task / post-task** - Task lifecycle hooks
+2. **session-end / session-restore** - Session management
+3. **bash-safety.ts** - Convert bash-hook.sh
+4. **file-organization.ts** - Convert file-hook.sh
+
+### Priority 2 - MEDIUM (Week 3-4)
+1. **workflow hooks** - Workflow lifecycle
+2. **git-commit.ts** - Convert git-commit-hook.sh
+3. **verification hooks** - Task verification
+4. **build-agents** - Agent config generation
+
+### Priority 3 - LOW (Week 5+)
+1. **LLM hooks** - LLM integration
+2. **memory hooks** - Memory lifecycle
+3. **neural hooks** - Neural training
+4. **performance hooks** - Performance optimization
diff --git a/v3/docs/v3-migration/MCP-TOOLS-MIGRATION.md b/v3/docs/v3-migration/MCP-TOOLS-MIGRATION.md
new file mode 100644
index 0000000000..c7bd795db6
--- /dev/null
+++ b/v3/docs/v3-migration/MCP-TOOLS-MIGRATION.md
@@ -0,0 +1,626 @@
+# MCP Tools Migration Guide
+
+> Migrating from V2 MCP Tools (65) to V3 MCP Tools (22)
+
+## Overview
+
+V3 has streamlined the MCP tools from 65 to 22, with a focus on core operations and the new hooks-based learning system. Many V2 tools need migration.
+
+## Tool Count Summary
+
+| Category | V2 Tools | V3 Tools | Gap |
+|----------|----------|----------|-----|
+| Agent | 11 | 4 | -7 |
+| Task | 8 | 0 | -8 |
+| Memory | 6 | 3 | -3 |
+| System | 7 | 0 | -7 |
+| Config | 3 | 3 | 0 |
+| Swarm | 8 | 3 | -5 |
+| Workflow | 3 | 0 | -3 |
+| Terminal | 3 | 0 | -3 |
+| Resource | 2 | 0 | -2 |
+| Message | 2 | 0 | -2 |
+| Monitor | 2 | 0 | -2 |
+| Neural | 3 | 0 | -3 |
+| Benchmark | 2 | 0 | -2 |
+| Query | 2 | 0 | -2 |
+| **Hooks** | 0 | 9 | +9 |
+| **Total** | 65 | 22 | -43 |
+
+## Implemented Tools βœ…
+
+### Agent Tools (4)
+```typescript
+// v3/mcp/tools/agent-tools.ts
+'agent/spawn' // Spawn agent with type, config, priority
+'agent/list' // List agents with filtering
+'agent/terminate' // Terminate agent
+'agent/status' // Get agent status
+```
+
+### Swarm Tools (3)
+```typescript
+// v3/mcp/tools/swarm-tools.ts
+'swarm/init' // Initialize swarm with topology
+'swarm/status' // Get swarm status
+'swarm/scale' // Scale swarm up/down (NEW)
+```
+
+### Memory Tools (3)
+```typescript
+// v3/mcp/tools/memory-tools.ts
+'memory/store' // Store memory entry
+'memory/search' // Semantic/keyword search
+'memory/list' // List with filtering
+```
+
+### Config Tools (3)
+```typescript
+// v3/mcp/tools/config-tools.ts
+'config/load' // Load configuration
+'config/save' // Save configuration
+'config/validate' // Validate configuration
+```
+
+### Hooks Tools (9) - NEW
+```typescript
+// v3/mcp/tools/hooks-tools.ts
+'hooks/pre-edit' // Pre-edit context
+'hooks/post-edit' // Post-edit learning
+'hooks/pre-command' // Pre-command risk
+'hooks/post-command' // Post-command learning
+'hooks/route' // Task routing
+'hooks/explain' // Routing explanation
+'hooks/pretrain' // Repository bootstrap
+'hooks/metrics' // Learning metrics
+'hooks/list' // List hooks
+```
+
+## Missing Tools ❌
+
+### Task Management (8 missing) - HIGH PRIORITY
+
+```typescript
+// Need to add to v3/mcp/tools/task-tools.ts
+export const taskTools = [
+ {
+ name: 'tasks/create',
+ description: 'Create a new task for execution',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ type: { type: 'string', description: 'Task type' },
+ description: { type: 'string', description: 'Task description' },
+ priority: { type: 'number', default: 5 },
+ dependencies: { type: 'array', items: { type: 'string' } },
+ assignToAgent: { type: 'string' },
+ assignToAgentType: { type: 'string' },
+ input: { type: 'object' },
+ timeout: { type: 'number' }
+ },
+ required: ['type', 'description']
+ }
+ },
+ {
+ name: 'tasks/list',
+ description: 'List tasks with optional filtering',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ status: { type: 'string', enum: ['pending', 'queued', 'assigned', 'running', 'completed', 'failed', 'cancelled'] },
+ agentId: { type: 'string' },
+ type: { type: 'string' },
+ limit: { type: 'number', default: 50 },
+ offset: { type: 'number', default: 0 }
+ }
+ }
+ },
+ {
+ name: 'tasks/status',
+ description: 'Get detailed status of a specific task',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ taskId: { type: 'string' }
+ },
+ required: ['taskId']
+ }
+ },
+ {
+ name: 'tasks/cancel',
+ description: 'Cancel a pending or running task',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ taskId: { type: 'string' },
+ reason: { type: 'string' }
+ },
+ required: ['taskId']
+ }
+ },
+ {
+ name: 'tasks/assign',
+ description: 'Assign a task to a specific agent',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ taskId: { type: 'string' },
+ agentId: { type: 'string' }
+ },
+ required: ['taskId', 'agentId']
+ }
+ },
+ {
+ name: 'task_orchestrate',
+ description: 'Orchestrate task across the swarm',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ task: { type: 'string' },
+ strategy: { type: 'string', enum: ['parallel', 'sequential', 'adaptive'] },
+ priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
+ maxAgents: { type: 'number', min: 1, max: 10 }
+ },
+ required: ['task']
+ }
+ },
+ {
+ name: 'task_status',
+ description: 'Check progress of running tasks',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ taskId: { type: 'string' },
+ detailed: { type: 'boolean', default: false }
+ }
+ }
+ },
+ {
+ name: 'task_results',
+ description: 'Retrieve results from completed tasks',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ taskId: { type: 'string' },
+ format: { type: 'string', enum: ['summary', 'detailed', 'raw'] }
+ },
+ required: ['taskId']
+ }
+ }
+];
+```
+
+### System Tools (7 missing) - MEDIUM PRIORITY
+
+```typescript
+// Need to add to v3/mcp/tools/system-tools.ts
+export const systemTools = [
+ {
+ name: 'system/status',
+ description: 'Get comprehensive system status',
+ inputSchema: { type: 'object', properties: {} }
+ },
+ {
+ name: 'system/metrics',
+ description: 'Get system performance metrics',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ timeRange: { type: 'string', enum: ['1h', '6h', '24h', '7d'], default: '1h' }
+ }
+ }
+ },
+ {
+ name: 'system/health',
+ description: 'Perform comprehensive health check',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ deep: { type: 'boolean', default: false }
+ }
+ }
+ },
+ {
+ name: 'system/info',
+ description: 'Get system information',
+ inputSchema: { type: 'object', properties: {} }
+ },
+ {
+ name: 'tools/list',
+ description: 'List all available tools',
+ inputSchema: { type: 'object', properties: {} }
+ },
+ {
+ name: 'tools/schema',
+ description: 'Get schema for a specific tool',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ name: { type: 'string' }
+ },
+ required: ['name']
+ }
+ }
+];
+```
+
+### Swarm Tools (5 missing)
+
+```typescript
+// Need to add to v3/mcp/tools/swarm-tools.ts
+const missingSwarmTools = [
+ {
+ name: 'swarm/create-objective',
+ description: 'Create a new swarm objective',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ title: { type: 'string' },
+ description: { type: 'string' },
+ tasks: { type: 'array' },
+ strategy: { type: 'string', enum: ['parallel', 'sequential', 'adaptive'] },
+ timeout: { type: 'number' }
+ },
+ required: ['title', 'description', 'tasks']
+ }
+ },
+ {
+ name: 'swarm/execute-objective',
+ description: 'Execute a swarm objective',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ objectiveId: { type: 'string' }
+ },
+ required: ['objectiveId']
+ }
+ },
+ {
+ name: 'swarm/emergency-stop',
+ description: 'Emergency stop all swarm operations',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ reason: { type: 'string' },
+ force: { type: 'boolean', default: false }
+ },
+ required: ['reason']
+ }
+ },
+ {
+ name: 'swarm/monitor',
+ description: 'Monitor swarm activity in real-time',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ duration: { type: 'number', default: 10 },
+ interval: { type: 'number', default: 1 }
+ }
+ }
+ },
+ {
+ name: 'agents/spawn_parallel',
+ description: 'Spawn multiple agents in parallel (10-20x faster)',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ agents: { type: 'array' },
+ maxConcurrency: { type: 'number', default: 5 },
+ batchSize: { type: 'number', default: 3 }
+ },
+ required: ['agents']
+ }
+ }
+];
+```
+
+### Memory Tools (3 missing)
+
+```typescript
+// Need to add to v3/mcp/tools/memory-tools.ts
+const missingMemoryTools = [
+ {
+ name: 'memory/delete',
+ description: 'Delete a memory entry',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ entryId: { type: 'string' }
+ },
+ required: ['entryId']
+ }
+ },
+ {
+ name: 'memory/export',
+ description: 'Export memory entries to file',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ format: { type: 'string', enum: ['json', 'csv', 'markdown'], default: 'json' },
+ agentId: { type: 'string' },
+ sessionId: { type: 'string' },
+ startTime: { type: 'string', format: 'date-time' },
+ endTime: { type: 'string', format: 'date-time' }
+ }
+ }
+ },
+ {
+ name: 'memory/import',
+ description: 'Import memory entries from file',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ filePath: { type: 'string' },
+ format: { type: 'string', enum: ['json', 'csv'], default: 'json' },
+ mergeStrategy: { type: 'string', enum: ['skip', 'overwrite', 'version'], default: 'skip' }
+ },
+ required: ['filePath']
+ }
+ }
+];
+```
+
+### Workflow Tools (3 missing)
+
+```typescript
+// Need to create v3/mcp/tools/workflow-tools.ts
+export const workflowTools = [
+ {
+ name: 'workflow/execute',
+ description: 'Execute a workflow from file or definition',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ filePath: { type: 'string' },
+ workflow: { type: 'object' },
+ parameters: { type: 'object' }
+ }
+ }
+ },
+ {
+ name: 'workflow/create',
+ description: 'Create a new workflow definition',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ name: { type: 'string' },
+ description: { type: 'string' },
+ tasks: { type: 'array' },
+ savePath: { type: 'string' }
+ },
+ required: ['name', 'tasks']
+ }
+ },
+ {
+ name: 'workflow/list',
+ description: 'List available workflows',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ directory: { type: 'string' }
+ }
+ }
+ }
+];
+```
+
+### Terminal Tools (3 missing)
+
+```typescript
+// Need to create v3/mcp/tools/terminal-tools.ts
+export const terminalTools = [
+ {
+ name: 'terminal/execute',
+ description: 'Execute command in terminal session',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ command: { type: 'string' },
+ args: { type: 'array' },
+ cwd: { type: 'string' },
+ env: { type: 'object' },
+ timeout: { type: 'number', default: 30000 },
+ terminalId: { type: 'string' }
+ },
+ required: ['command']
+ }
+ },
+ {
+ name: 'terminal/list',
+ description: 'List all terminal sessions',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ includeIdle: { type: 'boolean', default: true }
+ }
+ }
+ },
+ {
+ name: 'terminal/create',
+ description: 'Create new terminal session',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ cwd: { type: 'string' },
+ env: { type: 'object' },
+ shell: { type: 'string' }
+ }
+ }
+ }
+];
+```
+
+### Query Control (2 missing)
+
+```typescript
+// Need to create v3/mcp/tools/query-tools.ts
+export const queryTools = [
+ {
+ name: 'query/control',
+ description: 'Control running queries',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ action: { type: 'string', enum: ['pause', 'resume', 'terminate', 'change_model'] },
+ queryId: { type: 'string' },
+ model: { type: 'string' }
+ },
+ required: ['action', 'queryId']
+ }
+ },
+ {
+ name: 'query/list',
+ description: 'List active queries',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ includeHistory: { type: 'boolean', default: false }
+ }
+ }
+ }
+];
+```
+
+### Resource & Message (4 missing)
+
+```typescript
+// Need to create v3/mcp/tools/resource-tools.ts
+export const resourceTools = [
+ {
+ name: 'resource/register',
+ description: 'Register a new resource',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ type: { type: 'string', enum: ['compute', 'storage', 'network', 'memory', 'gpu', 'custom'] },
+ name: { type: 'string' },
+ capacity: { type: 'object' },
+ metadata: { type: 'object' }
+ },
+ required: ['type', 'name', 'capacity']
+ }
+ },
+ {
+ name: 'resource/get-statistics',
+ description: 'Get resource statistics',
+ inputSchema: { type: 'object', properties: {} }
+ }
+];
+
+// Need to create v3/mcp/tools/message-tools.ts
+export const messageTools = [
+ {
+ name: 'message/send',
+ description: 'Send message through bus',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ type: { type: 'string' },
+ content: { type: 'object' },
+ sender: { type: 'string' },
+ receivers: { type: 'array' },
+ priority: { type: 'string', enum: ['low', 'normal', 'high', 'critical'] },
+ channel: { type: 'string' }
+ },
+ required: ['type', 'content', 'sender', 'receivers']
+ }
+ },
+ {
+ name: 'message/get-metrics',
+ description: 'Get message bus metrics',
+ inputSchema: { type: 'object', properties: {} }
+ }
+];
+```
+
+### Monitor Tools (2 missing)
+
+```typescript
+// Need to add to v3/mcp/tools/monitor-tools.ts
+export const monitorTools = [
+ {
+ name: 'monitor/get-metrics',
+ description: 'Get system monitoring metrics',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ type: { type: 'string', enum: ['system', 'swarm', 'agents', 'all'], default: 'all' }
+ }
+ }
+ },
+ {
+ name: 'monitor/get-alerts',
+ description: 'Get active alerts',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ level: { type: 'string', enum: ['info', 'warning', 'critical', 'all'], default: 'all' },
+ limit: { type: 'number', default: 50 }
+ }
+ }
+ }
+];
+```
+
+### Neural Tools (3 missing)
+
+```typescript
+// Need to add to v3/mcp/tools/neural-tools.ts
+export const neuralTools = [
+ {
+ name: 'neural/status',
+ description: 'Get neural agent status',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ agentId: { type: 'string' }
+ }
+ }
+ },
+ {
+ name: 'neural/train',
+ description: 'Train neural agents',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ agentId: { type: 'string' },
+ iterations: { type: 'number', min: 1, max: 100, default: 10 }
+ }
+ }
+ },
+ {
+ name: 'neural/patterns',
+ description: 'Get cognitive patterns',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ pattern: { type: 'string', enum: ['all', 'convergent', 'divergent', 'lateral', 'systems', 'critical', 'abstract'], default: 'all' }
+ }
+ }
+ }
+];
+```
+
+## Implementation Plan
+
+### Phase 1: Core Tools (Week 1-2)
+1. Task management tools (8 tools)
+2. System status tools (4 tools)
+3. Emergency stop tool
+
+### Phase 2: Operational Tools (Week 3-4)
+1. Workflow tools (3 tools)
+2. Terminal tools (3 tools)
+3. Memory import/export (2 tools)
+
+### Phase 3: Advanced Tools (Week 5-6)
+1. Query control (2 tools)
+2. Resource management (2 tools)
+3. Message bus (2 tools)
+4. Monitor/alerts (2 tools)
+5. Neural tools (3 tools)
+
+### Phase 4: Optimization (Week 7-8)
+1. Parallel agent spawn
+2. Swarm monitoring
+3. Benchmark tools
diff --git a/v3/docs/v3-migration/MEMORY-NEURAL-MIGRATION.md b/v3/docs/v3-migration/MEMORY-NEURAL-MIGRATION.md
new file mode 100644
index 0000000000..59acd34ece
--- /dev/null
+++ b/v3/docs/v3-migration/MEMORY-NEURAL-MIGRATION.md
@@ -0,0 +1,471 @@
+# Memory & Neural System Migration Guide
+
+> Migrating from V2 Memory/Neural to V3 Enhanced Systems
+
+## Overview
+
+V3 significantly enhances both memory and neural systems:
+- **Memory**: +6 new features (20 total vs 14)
+- **Neural**: +11 new features (14 total vs 3)
+
+## Memory System Comparison
+
+### V2 Memory Architecture
+```
+v2/src/memory/
+β”œβ”€β”€ backends/
+β”‚ β”œβ”€β”€ base.ts # IMemoryBackend interface
+β”‚ β”œβ”€β”€ sqlite.ts # SQLite backend
+β”‚ └── markdown.ts # Markdown backend
+β”œβ”€β”€ manager.ts # Memory Manager
+β”œβ”€β”€ advanced-memory-manager.ts
+β”œβ”€β”€ indexer.ts # Search indexing
+β”œβ”€β”€ cache.ts # LRU cache
+β”œβ”€β”€ swarm-memory.ts # Multi-agent memory
+└── distributed-memory.ts # CRDT sync
+```
+
+### V3 Memory Architecture
+```
+v3/@claude-flow/memory/
+β”œβ”€β”€ src/
+β”‚ β”œβ”€β”€ types.ts # Type definitions
+β”‚ β”œβ”€β”€ index.ts # UnifiedMemoryService
+β”‚ β”œβ”€β”€ sqlite-backend.ts # SQLite (secured)
+β”‚ β”œβ”€β”€ sqljs-backend.ts # WASM SQLite (NEW)
+β”‚ β”œβ”€β”€ agentdb-backend.ts # AgentDB (NEW)
+β”‚ β”œβ”€β”€ hybrid-backend.ts # SQLite+AgentDB (NEW)
+β”‚ β”œβ”€β”€ database-provider.ts # Cross-platform (NEW)
+β”‚ β”œβ”€β”€ hnsw-index.ts # HNSW vector index (NEW)
+β”‚ β”œβ”€β”€ cache-manager.ts # Enhanced cache
+β”‚ β”œβ”€β”€ query-builder.ts # Fluent queries (NEW)
+β”‚ β”œβ”€β”€ migration.ts # Data migration (NEW)
+β”‚ β”œβ”€β”€ agentdb-adapter.ts # AgentDB adapter
+β”‚ └── domain/ # DDD structure (NEW)
+β”‚ β”œβ”€β”€ entities/
+β”‚ β”œβ”€β”€ repositories/
+β”‚ └── services/
+```
+
+## Memory Feature Migration
+
+### Implemented in V3 βœ…
+
+| V2 Feature | V3 Equivalent | Enhancement |
+|------------|---------------|-------------|
+| SQLite Backend | `sqlite-backend.ts` | SQL injection protection |
+| Memory Manager | `UnifiedMemoryService` | DDD architecture |
+| Indexer | `hnsw-index.ts` | 150x-12,500x faster |
+| Cache | `cache-manager.ts` | TTL, importance-based eviction |
+| Swarm Memory | `shareWith()/getSharedWith()` | Simplified API |
+
+### New in V3 βœ…
+
+| Feature | File | Description |
+|---------|------|-------------|
+| **HNSW Index** | `hnsw-index.ts` | Approximate nearest neighbor search |
+| **AgentDB Backend** | `agentdb-backend.ts` | Native vector database |
+| **Hybrid Backend** | `hybrid-backend.ts` | SQLite + AgentDB combo |
+| **SQL.js Backend** | `sqljs-backend.ts` | WASM for cross-platform |
+| **Database Provider** | `database-provider.ts` | Auto-selects best backend |
+| **Query Builder** | `query-builder.ts` | Fluent API for queries |
+| **Quantization** | `hnsw-index.ts` | 4-32x memory reduction |
+| **DDD Domain** | `domain/` | Clean architecture |
+
+### Missing in V3 ❌
+
+| V2 Feature | Priority | Migration Path |
+|------------|----------|----------------|
+| **Markdown Backend** | LOW | Optional human-readable export |
+| **Distributed Memory** | MEDIUM | Add CRDT sync for multi-node |
+
+## Memory Migration Code
+
+### Backend Migration
+
+```typescript
+// V2: Initialize memory
+import { MemoryManager } from 'claude-flow/memory';
+const memory = new MemoryManager({
+ backend: 'sqlite',
+ path: './.claude-flow/memory.db'
+});
+
+// V3: Initialize memory
+import { UnifiedMemoryService } from '@claude-flow/memory';
+const memory = new UnifiedMemoryService({
+ backend: 'hybrid', // SQLite + AgentDB
+ sqlite: {
+ path: './.claude-flow/memory.db'
+ },
+ agentdb: {
+ enableHNSW: true,
+ dimensions: 384
+ }
+});
+await memory.initialize();
+```
+
+### Store Migration
+
+```typescript
+// V2: Store entry
+await memory.store({
+ namespace: 'default',
+ sessionId: 'session-1',
+ agentId: 'agent-1',
+ type: 'observation',
+ content: 'User requested feature X',
+ tags: ['feature', 'request'],
+ metadata: { priority: 'high' }
+});
+
+// V3: Store entry (enhanced)
+await memory.store({
+ content: 'User requested feature X',
+ type: 'episodic',
+ category: 'observations',
+ tags: ['feature', 'request'],
+ metadata: {
+ priority: 'high',
+ sessionId: 'session-1',
+ agentId: 'agent-1'
+ },
+ importance: 0.8,
+ ttl: 86400000 // 24 hours
+});
+```
+
+### Query Migration
+
+```typescript
+// V2: Query entries
+const results = await memory.query({
+ namespace: 'default',
+ search: 'feature request',
+ type: 'observation',
+ limit: 10
+});
+
+// V3: Query entries (enhanced with semantic search)
+const results = await memory.search({
+ query: 'feature request',
+ searchType: 'hybrid', // semantic + keyword
+ type: 'episodic',
+ limit: 10,
+ minRelevance: 0.7
+});
+
+// V3: Fluent query builder
+import { QueryBuilder } from '@claude-flow/memory';
+const results = await new QueryBuilder(memory)
+ .semantic('feature request')
+ .type('episodic')
+ .tags(['feature'])
+ .minRelevance(0.7)
+ .limit(10)
+ .execute();
+```
+
+### Vector Search (V3 Only)
+
+```typescript
+// V3: HNSW vector search
+import { HNSWIndex } from '@claude-flow/memory';
+
+const index = new HNSWIndex({
+ dimensions: 384,
+ maxElements: 100000,
+ efConstruction: 200,
+ M: 16
+});
+
+// Add vectors
+await index.add(vectorId, embedding);
+
+// Search
+const results = await index.search(queryEmbedding, k: 10);
+// Returns: [{ id, distance, similarity }]
+```
+
+### Data Migration Script
+
+```typescript
+// Migrate V2 data to V3
+import { migrateMemoryData } from '@claude-flow/memory/migration';
+
+await migrateMemoryData({
+ source: {
+ type: 'v2-sqlite',
+ path: './.claude-flow/memory.db'
+ },
+ target: {
+ type: 'v3-hybrid',
+ sqlitePath: './.claude-flow/v3-memory.db',
+ agentdbPath: './.claude-flow/v3-vectors'
+ },
+ options: {
+ generateEmbeddings: true,
+ preserveTimestamps: true,
+ batchSize: 1000
+ }
+});
+```
+
+## Neural System Comparison
+
+### V2 Neural Architecture
+```
+v2/src/
+β”œβ”€β”€ neural/
+β”‚ β”œβ”€β”€ NeuralDomainMapper.ts # GNN domain mapping
+β”‚ └── integration.ts # Hooks integration
+β”œβ”€β”€ services/agentic-flow-hooks/
+β”‚ └── neural-hooks.ts # Training hooks
+└── reasoningbank/
+ └── reasoningbank-adapter.js # Via agentic-flow
+```
+
+### V3 Neural Architecture
+```
+v3/@claude-flow/neural/
+β”œβ”€β”€ src/
+β”‚ β”œβ”€β”€ index.ts # NeuralLearningSystem
+β”‚ β”œβ”€β”€ sona-manager.ts # SONA modes
+β”‚ β”œβ”€β”€ sona-integration.ts # @ruvector/sona
+β”‚ β”œβ”€β”€ reasoning-bank.ts # Native ReasoningBank
+β”‚ β”œβ”€β”€ pattern-learner.ts # Pattern extraction
+β”‚ β”œβ”€β”€ types.ts
+β”‚ β”œβ”€β”€ algorithms/ # RL algorithms
+β”‚ β”‚ β”œβ”€β”€ ppo.ts
+β”‚ β”‚ β”œβ”€β”€ dqn.ts
+β”‚ β”‚ β”œβ”€β”€ a2c.ts
+β”‚ β”‚ β”œβ”€β”€ decision-transformer.ts
+β”‚ β”‚ β”œβ”€β”€ q-learning.ts
+β”‚ β”‚ β”œβ”€β”€ sarsa.ts
+β”‚ β”‚ └── curiosity.ts
+β”‚ β”œβ”€β”€ modes/ # Learning modes
+β”‚ β”‚ β”œβ”€β”€ real-time.ts
+β”‚ β”‚ β”œβ”€β”€ balanced.ts
+β”‚ β”‚ β”œβ”€β”€ research.ts
+β”‚ β”‚ β”œβ”€β”€ edge.ts
+β”‚ β”‚ └── batch.ts
+β”‚ └── domain/ # DDD structure
+β”‚ β”œβ”€β”€ entities/
+β”‚ └── services/
+```
+
+## Neural Feature Migration
+
+### V2 Features
+
+| Feature | File | Status in V3 |
+|---------|------|--------------|
+| Neural Domain Mapper | `NeuralDomainMapper.ts` | ⚠️ Partial (pattern-learner) |
+| Neural Hooks | `neural-hooks.ts` | βœ… `sona-manager.ts` |
+| ReasoningBank Adapter | `reasoningbank-adapter.js` | βœ… Native `reasoning-bank.ts` |
+
+### V3 New Features βœ…
+
+| Feature | File | Description |
+|---------|------|-------------|
+| **SONA Manager** | `sona-manager.ts` | 5 learning modes |
+| **Learning Modes** | `modes/*.ts` | Real-time, Balanced, Research, Edge, Batch |
+| **Native ReasoningBank** | `reasoning-bank.ts` | 4-step pipeline |
+| **Pattern Learner** | `pattern-learner.ts` | Trajectory extraction |
+| **PPO Algorithm** | `algorithms/ppo.ts` | Proximal Policy Optimization |
+| **DQN Algorithm** | `algorithms/dqn.ts` | Deep Q-Network |
+| **A2C Algorithm** | `algorithms/a2c.ts` | Advantage Actor-Critic |
+| **Decision Transformer** | `algorithms/decision-transformer.ts` | Transformer RL |
+| **Q-Learning** | `algorithms/q-learning.ts` | Classic Q-Learning |
+| **SARSA** | `algorithms/sarsa.ts` | On-policy TD |
+| **Curiosity Module** | `algorithms/curiosity.ts` | Intrinsic motivation |
+| **LoRA Weights** | `sona-manager.ts` | Low-rank adaptation |
+| **EWC** | `sona-manager.ts` | Elastic weight consolidation |
+
+## Neural Migration Code
+
+### Initialize Neural System
+
+```typescript
+// V2: Neural integration
+import { NeuralDomainMapper } from 'claude-flow/neural';
+import { registerNeuralHooks } from 'claude-flow/neural/integration';
+
+const mapper = new NeuralDomainMapper();
+registerNeuralHooks(mapper);
+
+// V3: Neural learning system
+import { NeuralLearningSystem } from '@claude-flow/neural';
+
+const neural = new NeuralLearningSystem({
+ mode: 'balanced', // real-time | balanced | research | edge | batch
+ reasoningBank: {
+ maxPatterns: 10000,
+ retrievalK: 5
+ },
+ sona: {
+ enableLoRA: true,
+ enableEWC: true
+ }
+});
+await neural.initialize();
+```
+
+### Pattern Learning
+
+```typescript
+// V2: Train patterns
+await mapper.train(domainGraph, {
+ optimizer: 'adam',
+ learningRate: 0.001,
+ epochs: 100
+});
+
+// V3: Learn from trajectories
+const trajectory = neural.startTrajectory('implement-feature');
+trajectory.addStep({
+ action: 'analyze',
+ context: { files: ['src/app.ts'] },
+ result: { success: true }
+});
+trajectory.addStep({
+ action: 'implement',
+ context: { changes: 5 },
+ result: { success: true }
+});
+await trajectory.complete({ quality: 0.9 });
+
+// Patterns automatically extracted and stored
+```
+
+### ReasoningBank
+
+```typescript
+// V2: Via agentic-flow adapter
+import { ReasoningBankAdapter } from 'claude-flow/reasoningbank';
+const rb = new ReasoningBankAdapter();
+await rb.store(memory);
+const patterns = await rb.retrieve(query);
+
+// V3: Native implementation
+import { ReasoningBank } from '@claude-flow/neural';
+
+const rb = new ReasoningBank({
+ memory: agentDbBackend, // Uses AgentDB for 150x faster search
+ maxPatterns: 10000
+});
+
+// Store trajectory
+await rb.store(trajectory);
+
+// 4-step pipeline
+const patterns = await rb.retrieve(query, { k: 5 }); // RETRIEVE
+const judged = await rb.judge(trajectory); // JUDGE
+const distilled = await rb.distill(trajectories); // DISTILL
+await rb.consolidate(); // CONSOLIDATE
+```
+
+### SONA Learning Modes
+
+```typescript
+// V3 only: Configure learning modes
+import { SONAManager, LearningMode } from '@claude-flow/neural';
+
+const sona = new SONAManager();
+
+// Real-time mode: 2200 ops/sec, micro-LoRA
+sona.setMode(LearningMode.REAL_TIME);
+
+// Balanced mode: +25% quality, standard LoRA
+sona.setMode(LearningMode.BALANCED);
+
+// Research mode: +55% quality, full fine-tuning
+sona.setMode(LearningMode.RESEARCH);
+
+// Edge mode: <5MB, aggressive quantization
+sona.setMode(LearningMode.EDGE);
+
+// Batch mode: High throughput, async processing
+sona.setMode(LearningMode.BATCH);
+```
+
+### RL Algorithms
+
+```typescript
+// V3 only: Use RL algorithms
+import { createPPO, createDQN, createA2C } from '@claude-flow/neural/algorithms';
+
+// PPO for continuous action spaces
+const ppo = createPPO({
+ actor: { hiddenLayers: [64, 64] },
+ critic: { hiddenLayers: [64, 64] },
+ clipRatio: 0.2,
+ gamma: 0.99
+});
+
+// DQN for discrete actions
+const dqn = createDQN({
+ hiddenLayers: [64, 64],
+ epsilon: 0.1,
+ targetUpdateFreq: 100
+});
+
+// A2C for parallel environments
+const a2c = createA2C({
+ numWorkers: 4,
+ entropyCoeff: 0.01
+});
+```
+
+### Continual Learning
+
+```typescript
+// V3 only: LoRA and EWC
+import { SONAManager } from '@claude-flow/neural';
+
+const sona = new SONAManager({
+ enableLoRA: true,
+ loraConfig: {
+ rank: 8,
+ alpha: 16,
+ dropout: 0.1
+ },
+ enableEWC: true,
+ ewcConfig: {
+ lambda: 1000,
+ decay: 0.99
+ }
+});
+
+// LoRA adapts quickly, EWC prevents forgetting
+await sona.train(newTask);
+```
+
+## Performance Comparison
+
+| Operation | V2 | V3 | Improvement |
+|-----------|----|----|-------------|
+| Vector Search | Brute-force O(n) | HNSW O(log n) | 150x-12,500x |
+| Memory Store | SQLite only | Hybrid | Optimized routing |
+| Pattern Retrieval | Via adapter | Native | ~10x faster |
+| Learning Adaptation | Manual | SONA | <0.05ms |
+| Memory Usage | Full vectors | Quantized | 4-32x reduction |
+
+## Migration Checklist
+
+### Memory Migration
+- [ ] Update imports to `@claude-flow/memory`
+- [ ] Configure hybrid backend
+- [ ] Run data migration script
+- [ ] Generate embeddings for existing entries
+- [ ] Update query code to use semantic search
+- [ ] Test HNSW index performance
+
+### Neural Migration
+- [ ] Update imports to `@claude-flow/neural`
+- [ ] Initialize NeuralLearningSystem
+- [ ] Configure SONA mode
+- [ ] Migrate training code to trajectories
+- [ ] Update pattern retrieval to ReasoningBank
+- [ ] Enable LoRA/EWC if needed
diff --git a/v3/docs/v3-migration/README.md b/v3/docs/v3-migration/README.md
new file mode 100644
index 0000000000..d6e898c5bb
--- /dev/null
+++ b/v3/docs/v3-migration/README.md
@@ -0,0 +1,111 @@
+# V3 Migration Documentation
+
+> Comprehensive guide for migrating from Claude Flow V2 to V3
+
+## Overview
+
+This directory contains detailed analysis of capabilities, gaps, and migration paths from V2 to V3. The migration involves significant architectural changes based on 10 Architecture Decision Records (ADRs).
+
+## Migration Coverage Summary
+
+| Category | V2 Features | V3 Implemented | Gap |
+|----------|-------------|----------------|-----|
+| **Hive-Mind/Swarm** | 18 | 12 | 6 MISSING |
+| **Hooks** | 42 | 13 | 29 MISSING |
+| **MCP Tools** | 65 | 22 | 43 MISSING |
+| **CLI Commands** | 25 | 7 | 18 MISSING |
+| **Memory** | 14 | 20 | +6 NEW |
+| **Neural** | 3 | 14 | +11 NEW |
+
+## Documents
+
+### Core Analysis
+
+| Document | Description |
+|----------|-------------|
+| [CAPABILITY-GAP-ANALYSIS.md](./CAPABILITY-GAP-ANALYSIS.md) | Complete gap analysis across all systems |
+| [BACKWARD-COMPATIBILITY.md](./BACKWARD-COMPATIBILITY.md) | Backward compatibility requirements |
+
+### System-Specific Migration
+
+| Document | Description |
+|----------|-------------|
+| [HIVE-MIND-MIGRATION.md](./HIVE-MIND-MIGRATION.md) | Hive-mind, topologies, consensus migration |
+| [HOOKS-MIGRATION.md](./HOOKS-MIGRATION.md) | Self-learning hooks system migration |
+| [MCP-TOOLS-MIGRATION.md](./MCP-TOOLS-MIGRATION.md) | MCP tool definitions and handlers |
+| [CLI-MIGRATION.md](./CLI-MIGRATION.md) | CLI commands and options |
+| [MEMORY-NEURAL-MIGRATION.md](./MEMORY-NEURAL-MIGRATION.md) | Memory backends and neural systems |
+
+## Key Architectural Changes
+
+### ADR Summary
+
+| ADR | Decision | Impact |
+|-----|----------|--------|
+| ADR-001 | Adopt agentic-flow@alpha as core | Eliminates 10,000+ duplicate lines |
+| ADR-002 | Domain-Driven Design | Bounded contexts for modularity |
+| ADR-003 | Single coordination engine | UnifiedSwarmCoordinator replaces multiple |
+| ADR-004 | Plugin architecture | Microkernel for extensibility |
+| ADR-005 | MCP-first API | Consistent tool interfaces |
+| ADR-006 | Unified memory service | AgentDB integration |
+| ADR-007 | Event sourcing | Full audit trail |
+| ADR-008 | Vitest over Jest | 10x faster testing |
+| ADR-009 | Hybrid memory backend | SQLite + AgentDB |
+| ADR-010 | Remove Deno support | Node.js 20+ only |
+
+## Critical Missing Capabilities
+
+### Priority 1 - Core Functionality
+
+1. **Hive-Mind System** - Queen coordination, consensus algorithms
+2. **Task Management** - Task create/assign/cancel/status
+3. **Session Management** - Session save/restore/export
+4. **Workflow Execution** - Workflow create/execute/list
+
+### Priority 2 - Integration
+
+1. **GitHub Integration** - PR manager, issue tracker, release manager
+2. **Terminal Management** - Terminal create/execute/list
+3. **SPARC Methodology** - TDD workflow commands
+
+### Priority 3 - Monitoring
+
+1. **System Status** - Comprehensive status reporting
+2. **Live Monitor** - Real-time dashboard
+3. **Alert System** - monitor/get-alerts
+
+## Migration Strategy
+
+### Phase 1: Core (Weeks 1-4)
+- Implement missing hive-mind capabilities
+- Add task management MCP tools
+- Restore session management
+
+### Phase 2: Integration (Weeks 5-8)
+- GitHub integration commands
+- Terminal management
+- SPARC methodology
+
+### Phase 3: Polish (Weeks 9-12)
+- System monitoring
+- Shell hooks (TypeScript conversion)
+- Verification system
+
+## Quick Start
+
+```bash
+# Check migration status
+npx claude-flow migrate status
+
+# Run automatic migration
+npx claude-flow migrate run --target all --backup
+
+# Verify migration
+npx claude-flow migrate verify
+```
+
+## Related Documentation
+
+- [V3 README](../README.md) - V3 architecture overview
+- [ADRs](../docs/adrs/) - Architecture Decision Records
+- [Implementation Guide](../docs/guides/) - V3 implementation guides