# How to Migrate from AIOS V2 to V3 Format (Epic 2): Complete Guide > Easily migrate from AIOS V2 to V3 format using the Epic 2 migration toolkit. Inject the autoClaude section automatically to declare autonomous capabilities. Get the complete guide. - Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core) - Tags: migration-guide - Published: 2026-02-16 --- **Migrating from AIOS V2 to V3 requires injecting an `autoClaude` section into each agent markdown file to declare autonomous capabilities, a process automated by the Epic 2 migration toolkit in the SynkraAI/aios-core repository.** The AIOS framework has evolved from static YAML-based agent definitions to a dynamic, autonomous architecture. Epic 2 delivers the infrastructure to bridge this gap, providing scripts that scan your codebase, analyze dependencies, and safely transform legacy V2 agents into V3-compliant formats without breaking existing workflows. ## Understanding the V2 to V3 Format Changes AIOS V2 agents rely solely on a legacy YAML block inside their markdown files, typically defining `agent`, `commands`, and `dependencies` fields. This static structure limits agents to predefined instruction sets. AIOS V3 introduces the **`autoClaude`** section, a declarative block that specifies autonomous capabilities across six domains: **spec-pipeline**, **execution**, **recovery**, **QA**, **memory**, and **worktree**. Each capability is boolean-flagged (e.g., `canExecute`, `canRecover`) based on the agent's role, allowing the framework to dynamically orchestrate agent behavior. The migration enforces compliance through **[`agent-v3-schema.json`](https://github.com/SynkraAI/aios-core/blob/main/agent-v3-schema.json)**, which validates that every migrated agent contains the required `autoClaude` structure and valid capability flags. ## Prerequisites and Migration Components Before initiating migration, ensure you have Node.js installed and repository access to **SynkraAI/aios-core**. The Epic 2 migration suite consists of five core components: - **[`asset-inventory.js`](https://github.com/SynkraAI/aios-core/blob/main/asset-inventory.js)** – Scans `.aios-core/development/agents/` and produces a JSON inventory of all agents, tasks, and templates with their current version status. - **[`path-analyzer.js`](https://github.com/SynkraAI/aios-core/blob/main/path-analyzer.js)** – Walks the dependency graph to identify which tasks or templates reference each agent, calculating migration impact. - **[`migrate-agent.js`](https://github.com/SynkraAI/aios-core/blob/main/migrate-agent.js)** – Core engine that reads a V2 agent file, generates the `autoClaude` section via `generateAutoClaudeSection`, and writes the V3-compliant markdown. - **[`agent-v3-schema.json`](https://github.com/SynkraAI/aios-core/blob/main/agent-v3-schema.json)** – JSON Schema definition used by [`validate-v3-schema.js`](https://github.com/SynkraAI/aios-core/blob/main/validate-v3-schema.js) (imported within [`migrate-agent.js`](https://github.com/SynkraAI/aios-core/blob/main/migrate-agent.js)) to ensure output validity. - **[`ADE-EPIC2-HANDOFF.md`](https://github.com/SynkraAI/aios-core/blob/main/ADE-EPIC2-HANDOFF.md)** – High-level documentation enumerating assets, commands, and rollback procedures. These scripts are exposed through the **DevOps agent** commands defined in [`.github/agents/devops.md`](https://github.com/SynkraAI/aios-core/blob/main/.github/agents/devops.md), providing a consistent CLI interface. ## Step-by-Step Migration Workflow ### 1. Generate an Asset Inventory Begin by cataloging your current AIOS assets to identify which agents require migration. ```bash # Via DevOps agent command *inventory-assets # Or invoke directly node .aios-core/infrastructure/scripts/migrate-agent.js --list ``` This produces a JSON report listing every agent in `.aios-core/development/agents/` with a `version` field indicating `v2` or `v3` status. ### 2. Analyze Migration Impact Before modifying files, determine which tasks and templates depend on your target agents. ```bash *analyze-paths --agent ``` The [`path-analyzer.js`](https://github.com/SynkraAI/aios-core/blob/main/path-analyzer.js) script outputs a dependency graph showing reference counts. Agents with high downstream usage should be migrated during low-activity windows or tested more rigorously. ### 3. Migrate Individual Agents (Dry-Run and Live) Always perform a dry-run first to inspect the generated `autoClaude` block. ```bash *migrate-agent dev --dry-run ``` **Expected output excerpt:** ``` + Added autoClaude section: autoClaude: version: '3.0' migratedAt: '2026-02-16T03:12:45.123Z' specPipeline: canGather: false canAssess: false canResearch: false canWrite: false canCritique: false execution: canCreatePlan: false canCreateContext: false canExecute: true canVerify: true ``` Once verified, execute the live migration with backup creation: ```bash *migrate-agent dev --backup ``` The [`migrate-agent.js`](https://github.com/SynkraAI/aios-core/blob/main/migrate-agent.js) script: 1. Creates a `.aios/migration-backup/dev.md.bak` file 2. Generates the `autoClaude` section using the static `AGENT_CAPABILITIES` role map 3. Injects the YAML block into the markdown 4. Validates against [`agent-v3-schema.json`](https://github.com/SynkraAI/aios-core/blob/main/agent-v3-schema.json) via [`validate-v3-schema.js`](https://github.com/SynkraAI/aios-core/blob/main/validate-v3-schema.js) ### 4. Execute Batch Migration For repositories with numerous agents, use the batch wrapper: ```bash # Review the execution plan first *migrate-batch --dry-run # Execute on all remaining V2 agents *migrate-batch ``` This command iterates over the inventory produced by [`asset-inventory.js`](https://github.com/SynkraAI/aios-core/blob/main/asset-inventory.js) and runs the individual migration logic on every agent still flagged as V2. ### 5. Validate and Verify After migration, run the AIOS verification suite to ensure runtime compatibility: ```bash aios verify --agents npm test ``` These commands check that: - All agents parse correctly under the V3 schema - No broken references exist in the dependency graph - Autonomous capability flags are consistent with agent roles Only after passing these quality gates should you commit changes. ## Programmatic Migration API For custom CI/CD pipelines or advanced use cases, import the migration engine directly: ```javascript const { migrateAgent } = require('./.aios-core/infrastructure/scripts/migrate-agent'); (async () => { const root = process.cwd(); // project root const result = await migrateAgent(root, 'dev', { dryRun: false, backup: true, force: false, }); console.log(result); // { success: true, agentId: 'dev', backupPath: '...', validation: 'PASSED' } })(); ``` The `migrateAgent` function accepts: - `root`: Absolute path to repository root - `agentId`: The agent identifier (filename without `.md`) - `options`: Configuration object supporting `dryRun`, `backup`, and `force` flags ## Key Migration Files and Architecture | File | Purpose | |------|---------| | [`.aios-core/infrastructure/scripts/migrate-agent.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/scripts/migrate-agent.js) | Core migration logic – reads V2 markdown, generates `autoClaude` via `generateAutoClaudeSection`, validates against schema | | [`.aios-core/infrastructure/scripts/asset-inventory.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/scripts/asset-inventory.js) | Scans repository to build JSON inventory of agents, tasks, and templates with version status | | [`.aios-core/infrastructure/scripts/path-analyzer.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/scripts/path-analyzer.js) | Computes dependency graph to identify migration impact and orphan detection | | [`.aios-core/infrastructure/schemas/agent-v3-schema.json`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/schemas/agent-v3-schema.json) | JSON Schema defining required V3 structure including `autoClaude` capabilities | | [`docs/pt/architecture/ADE-EPIC2-HANDOFF.md`](https://github.com/SynkraAI/aios-core/blob/main/docs/pt/architecture/ADE-EPIC2-HANDOFF.md) | Epic 2 hand-off documentation enumerating assets, commands, and rollback procedures | | [`.github/agents/devops.md`](https://github.com/SynkraAI/aios-core/blob/main/.github/agents/devops.md) | DevOps agent definition exposing `*inventory-assets`, `*analyze-paths`, `*migrate-agent`, and `*migrate-batch` commands | ## Summary - **AIOS V3** requires an `autoClaude` section declaring autonomous capabilities (spec-pipeline, execution, recovery, QA, memory, worktree) that V2 agents lack. - **Epic 2** provides a fully automated migration path via scripts in `.aios-core/infrastructure/scripts/`, including inventory generation, impact analysis, and batch processing. - **Always dry-run first** using `*migrate-agent --dry-run` to inspect the generated `autoClaude` block before applying changes. - **Validation is mandatory** – every migrated agent is checked against [`agent-v3-schema.json`](https://github.com/SynkraAI/aios-core/blob/main/agent-v3-schema.json), and post-migration verification requires running `aios verify --agents` and `npm test`. - **Backups are automatic** when using the `--backup` flag, storing original V2 files in `.aios/migration-backup/` for rollback safety. ## Frequently Asked Questions ### What is the main difference between AIOS V2 and V3 agent formats? AIOS V2 agents rely solely on a static YAML block defining basic metadata, commands, and dependencies. AIOS V3 introduces the **`autoClaude`** section, a declarative configuration that specifies autonomous capabilities across six domains: spec-pipeline, execution, recovery, QA, memory, and worktree. This allows the framework to dynamically orchestrate agent behavior based on role-specific flags like `canExecute` and `canRecover`. ### Can I migrate multiple agents at once? Yes. The Epic 2 migration suite provides the `*migrate-batch` command (backed by [`asset-inventory.js`](https://github.com/SynkraAI/aios-core/blob/main/asset-inventory.js)) that iterates over every V2 agent detected in the repository. Always run `*migrate-batch --dry-run` first to review the execution plan and generated diffs before applying the changes to all agents simultaneously. ### What happens if the migration fails validation? If the generated V3 structure fails validation against [`agent-v3-schema.json`](https://github.com/SynkraAI/aios-core/blob/main/agent-v3-schema.json), the migration script aborts the write operation and reports the specific schema violations in the console. When using the `--backup` flag, the original V2 file remains untouched in its backup location at `.aios/migration-backup/`, allowing you to rollback or correct the agent definition and retry the migration. ### Is there a way to rollback a migration? Yes. The migration scripts support rollback through the automatic backup system. When you run `*migrate-agent --backup`, the script stores the original V2 file as `.md.bak` in `.aios/migration-backup/`. To rollback, simply restore the backup file to `.aios-core/development/agents/.md` and remove the V3 version. The [`ADE-EPIC2-HANDOFF.md`](https://github.com/SynkraAI/aios-core/blob/main/ADE-EPIC2-HANDOFF.md) document provides detailed rollback procedures for bulk operations.