How to Migrate from AIOS V2 to V3 Format (Epic 2): Complete Guide

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, 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 – Scans .aios-core/development/agents/ and produces a JSON inventory of all agents, tasks, and templates with their current version status.
• path-analyzer.js – Walks the dependency graph to identify which tasks or templates reference each agent, calculating migration impact.
• 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 – JSON Schema definition used by validate-v3-schema.js (imported within migrate-agent.js) to ensure output validity.
• 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, 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.

# 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.

*analyze-paths --agent <agent-id>

The 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.

*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:

*migrate-agent dev --backup

The 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 via validate-v3-schema.js

4. Execute Batch Migration

For repositories with numerous agents, use the batch wrapper:

# 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 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:

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:

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	Core migration logic – reads V2 markdown, generates autoClaude via generateAutoClaudeSection, validates against schema
.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	Computes dependency graph to identify migration impact and orphan detection
.aios-core/infrastructure/schemas/agent-v3-schema.json	JSON Schema defining required V3 structure including autoClaude capabilities
docs/pt/architecture/ADE-EPIC2-HANDOFF.md	Epic 2 hand-off documentation enumerating assets, commands, and rollback procedures
.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 <id> --dry-run to inspect the generated autoClaude block before applying changes.
• Validation is mandatory – every migrated agent is checked against 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) 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, 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 <id> --backup, the script stores the original V2 file as <id>.md.bak in .aios/migration-backup/. To rollback, simply restore the backup file to .aios-core/development/agents/<id>.md and remove the V3 version. The ADE-EPIC2-HANDOFF.md document provides detailed rollback procedures for bulk operations.

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