/gaia-migrate

user-facing
Category:
Getting Started
Lifecycle phase:
Any (one-time migration)
Arguments:
dry-run or apply

What it does

/gaia-migrate automates the upgrade from GAIA v1 (workflow engine) to GAIA v2 (Claude Code native plugin). It backs up v1 directories, migrates templates, memory, and configuration to the v2 layout, validates the result, and cleans up the v1 directories.

When to use it

  • You have an existing GAIA v1 installation (identified by the presence of _gaia/, _memory/, and custom/ directories) and want to move to the v2 plugin.
  • You have already installed the v2 plugin via /plugin marketplace add.

Always run with dry-run first to preview the plan before applying.

Prerequisites

  • v2 plugin installed. Run /plugin marketplace add gaia-framework first. The migration cannot install plugins.
  • v1 markers present. The project root must contain _gaia/, _memory/, and custom/ directories.

How to invoke

/gaia-migrate dry-run

Preview the migration plan without making changes.

/gaia-migrate apply

Execute the migration (backs up first, then migrates).

What it does step by step

  1. Confirm intent Asks whether to run a dry-run preview or apply directly. Defaults to dry-run.
  2. Dry-run preview Shows the planned operations: which files will be backed up, migrated, and removed. Highlights any conditions that would halt the migration.
  3. Apply migration If you approve the dry-run, the migration runs: backup, config split, template migration, memory migration, validation, and v1 directory removal. A full backup is stored at .gaia-migrate-backup/{timestamp}/.
  4. Report result Shows a SUCCESS or FAILED banner. On failure, prints the exact restore command. On success, lists any manual follow-up items.
  5. Post-migration smoke test Instructs you to run /gaia-help to confirm that the v2 plugin is fully operational and that no legacy stubs are interfering.

Safety

A full backup is created before any write operation. Both SUCCESS and FAILED results include the exact restore command. The migration does not auto-restore on failure -- you decide when and whether to roll back.

Inputs

Input Source Description
mode Command argument dry-run (preview) or apply (execute).

Outputs

Output Location Description
Backup .gaia-migrate-backup/{timestamp}/ Full backup of v1 directories before migration.
Migrated config .gaia/config/project-config.yaml v1 config fields split into the v2 config location.

Example session

> /gaia-migrate dry-run

DRY-RUN: Migration plan for ./
  Backup destination: .gaia-migrate-backup/2026-05-07T10-30-00/
  Steps:
    1. Backup _gaia/, _memory/, custom/ (87 MB)
    2. Split _gaia/_config/global.yaml into .gaia/config/project-config.yaml
    3. Migrate custom templates to custom/templates/
    4. Migrate memory sidecars to _memory/ (v2 layout)
    5. Validate config against schema
    6. Remove v1 directories (_gaia/, _memory/v1, custom/v1)

  No HALT conditions detected.

Apply this migration? (y/n)
> y

Backing up... done.
Migrating config... done.
Migrating templates... done.
Migrating memory... done.
Validating... PASS.
Removing v1 directories... done.

SUCCESS -- Migration complete.
  Backup: .gaia-migrate-backup/2026-05-07T10-30-00/
  Restore: cp -a ".gaia-migrate-backup/2026-05-07T10-30-00/" "./"

Next: run /gaia-help to confirm the v2 plugin is working.

What to run next

Troubleshooting

"Nothing to migrate -- already on v2"

The project has no v1 directories and already has a v2 config. No action needed.

Migration FAILED

The migration printed a restore command. Run it to revert to the pre-migration state, inspect the error, and re-try after fixing the issue.

Duplicate /gaia-help entries in the command palette

Legacy .claude/commands/gaia-*.md stubs were not removed. Delete them manually with rm .claude/commands/gaia-*.md. If the stubs are in your global config (~/.claude/commands/), remove them there as well.