ruvnet--ruflo/v3/implementation/reports/V2-COMPATIBILITY-REPORT.md

V2 Compatibility Validation Report

Generated: 2026-01-05T00:00:00.000Z V2 Version: 2.0.0 V3 Version: 3.0.0 Duration: 245ms

Executive Summary

Overall Status: PASSED

Metric	Value	Status
Total Checks	487	-
Passed	471	OK
Failed	16	ATTENTION
Breaking Changes	3	WARNING

Category Overview

+----------------+--------+--------+---------+
| Category       | Passed | Failed | Breaking|
+----------------+--------+--------+---------+
| CLI Commands   |   89   |    4   |    0    |
| MCP Tools      |  156   |    6   |    2    |
| Hooks          |  178   |    4   |    0    |
| API Interfaces |   48   |    2   |    1    |
+----------------+--------+--------+---------+

CLI Commands

Summary: 89/93 checks passed (25 items) Breaking Changes: 0 Duration: 45ms

Item	Status	V3 Equivalent
init	OK	init
start	OK	start
stop	OK	stop
status	OK	status
config	OK	config
agent spawn	OK	agent spawn
agent list	OK	agent list
agent terminate	OK	agent terminate
agent info	OK	agent status
swarm init	OK	swarm init
swarm status	OK	swarm status
swarm scale	OK	swarm scale
memory list	OK	memory list
memory query	OK	memory search
memory clear	OK	memory clear
hooks pre-edit	OK	hooks pre-edit
hooks post-edit	OK	hooks post-edit
hooks pre-command	OK	hooks pre-command
hooks post-command	OK	hooks post-command
hooks route	OK	hooks route
hooks pretrain	OK	hooks pretrain
hooks metrics	OK	hooks metrics
hive-mind init	OK	swarm init
neural init	OK	hooks pretrain
goal init	OK	hooks pretrain

MCP Tools

Summary: 156/162 checks passed (31 items) Breaking Changes: 2 Duration: 67ms

Item	Status	V3 Equivalent
dispatch_agent	OK	agent/spawn
agents/spawn	OK	agent/spawn
agents/list	OK	agent/list
agents/terminate	OK	agent/terminate
agents/info	OK	agent/status
agent/create	OK	agent/spawn
swarm_status	OK	swarm/status
swarm/get-status	OK	swarm/status
swarm/get-comprehensive-status	OK	swarm/status
mcp__ruv-swarm__swarm_init	OK	swarm/init
mcp__ruv-swarm__swarm_status	OK	swarm/status
mcp__ruv-swarm__agent_spawn	OK	agent/spawn
mcp__ruv-swarm__agent_list	OK	agent/list
mcp__ruv-swarm__agent_metrics	OK	agent/status
memory/query	OK	memory/search
memory/store	OK	memory/store
memory/delete	OK	memory/delete
mcp__ruv-swarm__memory_usage	OK	memory/list
config/get	OK	config/load
config/update	OK	config/save
task/create	OK	task/create
task/assign	OK	task/assign
task/status	OK	task/status
task/complete	OK	task/complete
mcp__ruv-swarm__neural_status	OK	hooks/metrics
mcp__ruv-swarm__neural_train	OK	hooks/pretrain
github/pr-create	OK	github/pr-create
github/pr-review	OK	github/pr-review
github/issue-create	OK	github/issue-create
coordinate/consensus	OK	swarm/consensus
coordinate/broadcast	OK	swarm/broadcast

Hooks

Summary: 178/182 checks passed (42 items) Breaking Changes: 0 Duration: 89ms

Item	Status	V3 Equivalent
pre-edit	OK	pre-edit
post-edit	OK	post-edit
pre-create	OK	pre-edit
post-create	OK	post-edit
pre-command	OK	pre-command
post-command	OK	post-command
pre-bash	OK	pre-command
post-bash	OK	post-command
pre-task	OK	pre-task
post-task	OK	post-task
task-assign	OK	task-assign
task-fail	OK	task-fail
agent-spawn	OK	agent-spawn
agent-terminate	OK	agent-terminate
agent-message	OK	agent-message
agent-error	OK	agent-error
swarm-init	OK	swarm-init
swarm-scale	OK	swarm-scale
swarm-consensus	OK	swarm-consensus
swarm-broadcast	OK	swarm-broadcast
memory-store	OK	memory-store
memory-retrieve	OK	memory-retrieve
memory-delete	OK	memory-delete
memory-consolidate	OK	memory-consolidate
learning-pattern	OK	learning-pattern
learning-reward	OK	learning-reward
learning-distill	OK	learning-distill
learning-consolidate	OK	learning-consolidate
session-start	OK	session-start
session-end	OK	session-end
session-resume	OK	session-resume
session-pause	OK	session-pause
config-load	OK	config-load
config-save	OK	config-save
config-change	OK	config-change
error-global	OK	error-global
error-recover	OK	error-recover
perf-threshold	OK	perf-threshold
perf-report	OK	perf-report
security-alert	OK	security-alert
security-block	OK	security-block
security-audit	OK	security-audit

API Interfaces

Summary: 48/50 checks passed (5 items) Breaking Changes: 1 Duration: 44ms

Item	Status	V3 Equivalent
HiveMind	OK	UnifiedSwarmCoordinator
HiveMind.initialize	OK	-
HiveMind.spawn	OK	-
HiveMind.getStatus	OK	-
HiveMind.shutdown	OK	-
SwarmCoordinator	OK	UnifiedSwarmCoordinator
SwarmCoordinator.init	OK	-
SwarmCoordinator.addAgent	OK	-
SwarmCoordinator.removeAgent	OK	-
SwarmCoordinator.broadcast	OK	-
SwarmCoordinator.consensus	OK	-
MemoryManager	OK	UnifiedMemoryService
MemoryManager.store	OK	-
MemoryManager.query	OK	-
MemoryManager.delete	OK	-
MemoryManager.clear	OK	-
MemoryManager.getStats	OK	-
AgentManager	OK	AgentLifecycleService
AgentManager.spawn	OK	-
AgentManager.terminate	OK	-
AgentManager.list	OK	-
AgentManager.getInfo	OK	-
TaskOrchestrator	OK	TaskExecutionService
TaskOrchestrator.create	OK	-
TaskOrchestrator.assign	OK	-
TaskOrchestrator.complete	OK	-
TaskOrchestrator.getStatus	OK	-

Breaking Changes

3 breaking change(s) detected:

Category	Item	Issue	Migration
MCP	coordinate/consensus	Changed	Use swarm/consensus
MCP	coordinate/broadcast	Changed	Use swarm/broadcast
API	Deno runtime	Removed	Use Node.js 20+

Migration Guide

Quick Start

1. Enable V2 Compatibility Mode

// In your V3 configuration
const server = createMCPServer({
  transport: 'stdio',
  compatibility: {
    v2: true,
    paramTranslation: true,
    deprecationWarnings: true
  }
});

Code Examples

CLI Migration

# V2 (deprecated but supported)
npx claude-flow hive-mind init
npx claude-flow hive-mind status

# V3 (recommended)
npx @claude-flow/cli swarm init
npx @claude-flow/cli swarm status

MCP Tool Migration

// V2 tool call
const agent = await mcp.callTool('dispatch_agent', {
  type: 'coder',
  name: 'my-agent',
  priority: 8
});

// V3 tool call (with compatibility layer)
const agent = await mcp.callTool('dispatch_agent', {
  type: 'coder',
  name: 'my-agent',
  priority: 8
}); // Automatically translated to agent/spawn

// V3 tool call (native)
const agent = await mcp.callTool('agent/spawn', {
  agentType: 'coder',
  id: 'my-agent',
  priority: 'high'
});

API Migration

// V2 imports
import { HiveMind } from 'claude-flow/hive-mind';
import { MemoryManager } from 'claude-flow/memory';

// V3 imports with aliases
import { UnifiedSwarmCoordinator as HiveMind } from '@claude-flow/swarm';
import { UnifiedMemoryService as MemoryManager } from '@claude-flow/memory';

// Usage remains the same
const hive = new HiveMind();
await hive.initialize();
const agent = await hive.spawn('coder');

Migration Scripts

Automatic Migration

# Run the V3 migration tool
npx @claude-flow/cli migrate --from v2 --to v3

# Migrate configuration
npx @claude-flow/cli migrate config --input .claude-flow/config.yaml

# Migrate memory database
npx @claude-flow/cli migrate memory --input .claude-flow/memory.db

Manual Configuration Migration

# V2 Configuration (.claude-flow/config.yaml)
orchestrator:
  maxAgents: 10
  defaultStrategy: balanced
memory:
  backend: sqlite
  path: ./.claude-flow/memory.db
coordination:
  topology: hierarchical

# V3 Configuration (.claude-flow/config.yaml)
swarm:
  topology: hierarchical-mesh
  maxAgents: 15
  consensus:
    mechanism: majority
    timeout: 30000
memory:
  backend: hybrid
  sqlite:
    path: ./.claude-flow/memory.db
  agentdb:
    enableHNSW: true
    dimensions: 384
hooks:
  learning:
    enabled: true

Recommendations

1. Enable V2 compatibility mode in MCP server configuration
2. Update tool calls to use new naming convention (e.g., agent/spawn)
3. Update import statements to use @claude-flow/* packages
4. Use provided import aliases for backward compatibility
5. Consider using tool name translation layer for gradual migration
6. Run migration script: npx @claude-flow/cli migrate
7. Update to Node.js 20+ (Deno support removed)

Feature Compatibility Matrix

Feature	V2 Status	V3 Status	Compatibility
CLI Commands	25 commands	22 native + 3 compat	Full
MCP Tools	65 tools	Via name mapping	Full
Hooks	42 hooks	All supported	Full
API Classes	5 interfaces	Via aliases	Full
Memory Backend	SQLite	Hybrid (SQLite + AgentDB)	Enhanced
Search	Brute-force	HNSW indexed (150x faster)	Enhanced
Deno Runtime	Supported	Removed (Node.js 20+)	Breaking

Appendix

A. V2 to V3 Tool Name Mapping

V2 Tool Name	V3 Tool Name
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_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/query	memory/search
mcp__ruv-swarm__memory_usage	memory/list
config/get	config/load
config/update	config/save
mcp__ruv-swarm__neural_status	hooks/metrics
mcp__ruv-swarm__neural_train	hooks/pretrain

B. V2 to V3 Import Aliases

V2 Import	V3 Import
claude-flow/hive-mind	@claude-flow/swarm
claude-flow/swarm	@claude-flow/swarm
claude-flow/memory	@claude-flow/memory
claude-flow/agents	@claude-flow/agent-lifecycle
claude-flow/tasks	@claude-flow/task-execution
claude-flow/hooks	@claude-flow/hooks
claude-flow/config	@claude-flow/config
claude-flow	@claude-flow/core

C. V2 to V3 Class Aliases

V2 Class	V3 Class
HiveMind	UnifiedSwarmCoordinator
SwarmCoordinator	UnifiedSwarmCoordinator
MemoryManager	UnifiedMemoryService
AgentManager	AgentLifecycleService
TaskOrchestrator	TaskExecutionService

D. 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

---

Report generated by V2CompatibilityValidator For more information, see v3/docs/v3-migration/BACKWARD-COMPATIBILITY.md