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

> Learn how to migrate from AIOX V2 to V3 format with our step-by-step guide. Discover how to detect your version, plan your migration, convert agent files, and validate against V3 schemas for a smooth transition.

- Repository: [SynkraAI/aiox-core](https://github.com/synkraai/aiox-core)
- Tags: migration-guide
- Published: 2026-03-15

---

**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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/.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:

```javascript
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:

```javascript
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:

```javascript
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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.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:

```bash
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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/agent-v3-schema.json), [`task-v3-schema.json`](https://github.com/SynkraAI/aiox-core/blob/main/task-v3-schema.json)) using [`.aiox-core/schemas/validate-v3-schema.js`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/schemas/validate-v3-schema.js). These indicate specific schema violations against [`agent-v3-schema.json`](https://github.com/SynkraAI/aiox-core/blob/main/agent-v3-schema.json) or [`task-v3-schema.json`](https://github.com/SynkraAI/aiox-core/blob/main/task-v3-schema.json). Fix the YAML syntax or missing `autoClaude` fields, then re-run validation. Use `--force` with [`migrate-agent.js`](https://github.com/SynkraAI/aiox-core/blob/main/migrate-agent.js) to re-process agents that need updates.