Aqe V2 V3 Migration

Migration Checklist

Pre-Migration

• Verify v2 installation exists (.agentic-qe/ directory)
• Check v2 version: aqe --version (should be 2.x.x)
• Backup current data: npm run backup (in v2 project)
• Note any custom configurations
• Document current test counts and coverage

During Migration

• Update to v3: npm install agentic-qe@latest
• Run migration: aqe migrate
• Review migration report
• Verify data transferred correctly

Post-Migration

• Run v3 tests: aqe test
• Check coverage: aqe coverage
• Verify patterns loaded: aqe patterns list
• Test MCP integration with Claude Code

Architecture Changes (v2 → v3)

From Monolithic to DDD

v2 Structure:                    v3 Structure:
├── src/mcp/tools/              ├── src/domains/
│   ├── test-*.ts (40+ tools)   │   ├── test-generation/
│   └── ...                     │   ├── test-execution/
├── src/core/agents/            │   ├── coverage-analysis/
│   ├── mixed agents            │   ├── quality-assessment/
│   └── ...                     │   ├── defect-intelligence/
└── src/core/memory/            │   ├── requirements-validation/
    └── scattered impls         │   ├── code-intelligence/
                                │   ├── security-compliance/
                                │   ├── contract-testing/
                                │   ├── visual-accessibility/
                                │   ├── chaos-resilience/
                                │   └── learning-optimization/
                                ├── src/kernel/
                                │   ├── event-bus.ts
                                │   └── coordinator.ts
                                └── src/mcp/
                                    └── domain-handlers.ts

Key API Changes

Configuration Migration

v2 Config Format

{
  "version": "2.8.2",
  "memory": {
    "path": ".agentic-qe/memory.db",
    "type": "sqlite"
  },
  "agents": {
    "enabled": ["test-generator", "coverage-analyzer"]
  }
}

v3 Config Format

{
  "version": "3.0.0",
  "kernel": {
    "eventBus": "in-memory",
    "coordinator": "queen"
  },
  "domains": {
    "test-generation": { "enabled": true },
    "test-execution": { "enabled": true },
    "coverage-analysis": {
      "enabled": true,
      "algorithm": "hnsw",
      "dimensions": 128
    }
  },
  "memory": {
    "backend": "agentdb",
    "path": ".aqe/agentdb/",
    "hnsw": {
      "M": 16,
      "efConstruction": 200
    }
  },
  "learning": {
    "reasoningBank": true,
    "sona": true
  }
}

Memory Migration

SQLite to AgentDB

// v2: Direct SQLite access
import Database from 'better-sqlite3';
const db = new Database('.agentic-qe/memory.db');
const patterns = db.prepare('SELECT * FROM patterns').all();

// v3: AgentDB with HNSW
import { AgentDB } from 'agentic-qe';
const db = new AgentDB('.aqe/agentdb/');
await db.initialize({ dimensions: 128, M: 16 });

// Migration script transfers and indexes
for (const pattern of v2Patterns) {
  await db.store({
    key: pattern.id,
    value: pattern.data,
    embedding: await generateEmbedding(pattern.data),
    metadata: { migratedFrom: 'v2', originalId: pattern.id }
  });
}

Breaking Changes

Must Update

1. Import Paths

   // v2
   import { AgenticQE } from 'agentic-qe';
   
   // v3 (when v3 becomes main release, package name is still 'agentic-qe')
   import { TestGenerationDomain } from 'agentic-qe/domains';
   

2. CLI Commands

   # v2
   aqe test --parallel
   
   # v3
   aqe test --workers=4 --topology=mesh
   

3. MCP Server

   # v2
   claude mcp add aqe -- npx aqe-mcp
   
   # v3 (same CLI name, enhanced capabilities)
   claude mcp add aqe -- npx aqe mcp
   

Deprecated (Will Warn)

• aqe.runTests() → Use domain-specific methods
• Direct memory access → Use AgentDB API
• Flat agent list → Use domain coordinators

Rollback Instructions

If migration fails or you need to revert:

# 1. v3 does NOT modify v2 data
# Your .agentic-qe/ folder is untouched

# 2. Downgrade to v2
npm install [email protected]
rm -rf .aqe/

# 3. Continue using v2
aqe --version  # Should show 2.x.x

Agent Coordination Examples

Spawning Migration Agents

// Use Task tool to spawn migration agents in parallel
Task({
  prompt: "Analyze v2 memory.db and extract all patterns",
  subagent_type: "researcher",
  description: "Analyze v2 patterns"
});

Task({
  prompt: "Convert v2 config to v3 format",
  subagent_type: "coder",
  description: "Convert config"
});

Task({
  prompt: "Validate migration results",
  subagent_type: "tester",
  description: "Validate migration"
});

Troubleshooting

Common Issues

Debug Mode

# Run migration with debug output
DEBUG=aqe:migrate aqe migrate

# Check migration logs
cat .aqe/logs/migration.log

Support

• Migration Issues: Open issue with [v2-v3-migration] tag
• Documentation: Migration Guide
• Discord: #v3-migration channel

Version Compatibility Matrix

Skill Version: 1.0.0 | Last Updated: 2026-01-11