qe-aqe-v2-v3-migration

AQE v2 to v3 Migration Skill

<default_to_action> When migrating from v2 to v3:

1. ANALYZE current v2 installation
2. BACKUP all data before any changes
3. MIGRATE configuration, memory, and patterns
4. VALIDATE migration success
5. PROVIDE rollback instructions

Never delete v2 data without explicit user confirmation. </default_to_action>

Quick Reference

Migration Command

# When v3 becomes main release, just update the package
npm install agentic-qe@latest

# Run migration
aqe migrate

# Or use this skill
/aqe-v2-v3-migration

What Gets Migrated

Component	v2 Location	v3 Location	Auto-Migrate
Memory DB	.agentic-qe/memory.db	.aqe/agentdb/	Yes
Config	.agentic-qe/config.json	.aqe/config.json	Yes
Patterns	.agentic-qe/patterns/	.aqe/reasoning-bank/	Yes
Cache	.agentic-qe/cache/	.aqe/cache/	Optional
Logs	.agentic-qe/logs/	.aqe/logs/	No (fresh start)

---

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

v2 API	v3 API	Notes
aqe init	aqe init	Different binary
aqe.generateTests()	testGeneration.generate()	Domain-based
aqe.analyzeGaps()	coverageAnalysis.findGaps()	O(log n) now
memory.store()	agentDB.store()	HNSW-indexed
patterns.learn()	reasoningBank.record()	With verdicts

---

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

Issue	Cause	Solution
"Cannot find .agentic-qe/"	No v2 installation	Run aqe init first
"Memory migration failed"	Corrupted SQLite	Use backup: npm run backup:restore
"HNSW index error"	Dimension mismatch	Set dimensions: 128 in config
"Pattern not found"	Not migrated	Re-run: aqe migrate --patterns

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

v2 Version	v3 Version	Migration Support
2.8.x	3.0.x	Full
2.7.x	3.0.x	Full
2.6.x	3.0.x	Partial (config only)
2.5.x and below	3.0.x	Manual migration

---

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