How to Migrate from AIOX V2 to V3 Format: Step-by-Step Guide

Migrate from AIOX V2 to V3 format by detecting your current version with detectV2Structure(), building a migration plan with analyzeMigrationPlan(), converting agent markdown files to include the autoClaude YAML section, and validating against V3 JSON schemas.

The SynkraAI/aiox-core repository provides built-in CLI tooling to migrate from AIOX V2 to V3 format, transforming flat directory structures into modular sub-folders and adding structured metadata to agent definitions. This migration moves your project from legacy flat layouts to the modern V3 architecture with automated validation and backup capabilities.

Understanding V2 vs V3 Structure

AIOX V2 stores all artifacts in a flat .aiox-core layout with folders like agents/, tasks/, and registry/ at the root level. V3 introduces a modular organization and structured agent metadata.

Directory Layout Changes

V3 organizes content into modular sub-folders—core/, development/, product/, and infrastructure/—according to the module mapping defined in .aiox-core/cli/commands/migrate/analyze.js (lines 19-65). The analyzeMigrationPlan() function uses this mapping to classify every file and determine its target location in the new structure.

Agent Definition Changes

V2 agents use simple YAML frontmatter without structured metadata. V3 requires an autoClaude top-level key in each agent's markdown file, describing capabilities, version, and migration metadata. The migration logic in .aiox-core/infrastructure/scripts/migrate-agent.js (lines 59-112) generates this section automatically based on AGENT_CAPABILITIES mappings.

Step 1: Detect Your Current Version

Before migrating, determine whether your project uses the legacy flat layout or the newer modular structure:

const { detectV2Structure } = require('.aiox-core/cli/commands/migrate/analyze');

detectV2Structure(process.cwd()).then(console.log);

A result of isV2: true indicates a flat V2 project ready for migration. If you see isV21: true, your project already uses the modular V2.1 baseline that forms the foundation for V3.

Step 2: Build a Migration Plan

Generate a complete migration plan that catalogs every file under .aiox-core, classifies it by module, records file sizes, and identifies potential conflicts:

const {
  analyzeMigrationPlan,
  formatMigrationPlan,
} = require('.aiox-core/cli/commands/migrate/analyze');

analyzeMigrationPlan(process.cwd()).then((plan) => {
  console.log(formatMigrationPlan(plan));
});

The output shows the number of files moving to each module and flags uncategorized files that will fall back to core/. Review this plan to identify any custom files that may need manual relocation.

Step 3: List and Assess Agents

Before converting individual agents, audit which ones are still V2 versus already V3:

const { listAgents, formatListOutput } = require('.aiox-core/infrastructure/scripts/migrate-agent');

listAgents(process.cwd()).then((agents) => {
  console.log(formatListOutput(agents));
});

This list displays status badges (🆕 for V3, 📦 for V2) alongside capability-mapping verification. The checkmark indicates whether the agent's role appears in the AGENT_CAPABILITIES registry.

Step 4: Migrate Individual Agents

The core migration logic lives in .aiox-core/infrastructure/scripts/migrate-agent.js. This script:

1. Parses the YAML block from the agent's markdown file using extractYamlFromMarkdown()
2. Detects existing V3 structure with isAlreadyV3()
3. Generates role-specific autoClaude objects from the AGENT_CAPABILITIES registry
4. Inserts the new YAML block before the closing delimiter using insertAutoClaudeSection()
5. Validates the result against V3 schemas using validateFile()

CLI Migration Commands

Goal	Command
Preview changes without writing	node .aiox-core/infrastructure/scripts/migrate-agent.js dev --dry-run
Migrate with automatic backup	node .aiox-core/infrastructure/scripts/migrate-agent.js dev --backup
Force re-migration of V3 agent	node .aiox-core/infrastructure/scripts/migrate-agent.js dev --force
List all agents with status	node .aiox-core/infrastructure/scripts/migrate-agent.js --list

After execution, the script prints Validation: PASSED if the file conforms to schemas/agent-v3-schema.json. If validation fails, the errors and warnings arrays provide exact schema violations referencing .aiox-core/schemas/validate-v3-schema.js.

Step 5: Validate and Clean Up

Run the V3 schema validation against all migrated files to ensure compliance:

node .aiox-core/schemas/validate-v3-schema.js

After successful validation:

• Commit the newly modular layout and updated agent markdown files
• Remove empty legacy directories (e.g., top-level agents/ or tasks/)
• Run npm test and npm run typecheck to verify the project builds against V3 expectations

Summary

• Detect your version using detectV2Structure() from .aiox-core/cli/commands/migrate/analyze.js before modifying any files
• Plan the modular reorganization with analyzeMigrationPlan(), which uses MODULE_MAPPING to distribute files across core/, development/, product/, and infrastructure/
• Convert agents using migrate-agent.js to inject the autoClaude YAML section with version and capability metadata
• Validate all files against V3 JSON schemas (agent-v3-schema.json, task-v3-schema.json) using .aiox-core/schemas/validate-v3-schema.js
• Clean up legacy directories and verify build integrity with your test suite after migration

Frequently Asked Questions

How do I know if my project is AIOX V2 or V3?

Run the detection helper from .aiox-core/cli/commands/migrate/analyze.js. If detectV2Structure() returns isV2: true, you have a flat V2 layout. If it returns isV21: true, your project already uses the modular structure introduced in V2.1, which is the baseline for V3.

What happens to my agent markdown files during migration?

The migration script in .aiox-core/infrastructure/scripts/migrate-agent.js parses each agent's YAML frontmatter and inserts an autoClaude section containing version, capabilities, and metadata. It preserves your existing content while adding the structured metadata required for V3 validation schemas.

Can I preview changes before committing them?

Yes. Use the --dry-run flag when running migrate-agent.js to see a diff of what would change without writing to disk. For analyzing file moves, use formatMigrationPlan() to preview the modular directory structure before execution.

What should I do if validation fails after migration?

Check the errors and warnings arrays output by .aiox-core/schemas/validate-v3-schema.js. These indicate specific schema violations against agent-v3-schema.json or task-v3-schema.json. Fix the YAML syntax or missing autoClaude fields, then re-run validation. Use --force with migrate-agent.js to re-process agents that need updates.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}