ContextQMD
Back to Ruflo

V3 Migration Documentation

v3/implementation/v3-migration/README.md

3.6.303.6 KB
Original Source

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

CategoryV2 FeaturesV3 ImplementedGap
Hive-Mind/Swarm18126 MISSING
Hooks421329 MISSING
MCP Tools652243 MISSING
CLI Commands25718 MISSING
Memory1420+6 NEW
Neural314+11 NEW

Documents

Core Analysis

DocumentDescription
CAPABILITY-GAP-ANALYSIS.mdComplete gap analysis across all systems
BACKWARD-COMPATIBILITY.mdBackward compatibility requirements

System-Specific Migration

DocumentDescription
HIVE-MIND-MIGRATION.mdHive-mind, topologies, consensus migration
HOOKS-MIGRATION.mdSelf-learning hooks system migration
MCP-TOOLS-MIGRATION.mdMCP tool definitions and handlers
CLI-MIGRATION.mdCLI commands and options
MEMORY-NEURAL-MIGRATION.mdMemory backends and neural systems

Key Architectural Changes

ADR Summary

ADRDecisionImpact
ADR-001Adopt agentic-flow@alpha as coreEliminates 10,000+ duplicate lines
ADR-002Domain-Driven DesignBounded contexts for modularity
ADR-003Single coordination engineUnifiedSwarmCoordinator replaces multiple
ADR-004Plugin architectureMicrokernel for extensibility
ADR-005MCP-first APIConsistent tool interfaces
ADR-006Unified memory serviceAgentDB integration
ADR-007Event sourcingFull audit trail
ADR-008Vitest over Jest10x faster testing
ADR-009Hybrid memory backendSQLite + AgentDB
ADR-010Remove Deno supportNode.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