---
name: craft-migrate
description: Codex skill alias for /craft-migrate. Plan and execute Craft CMS migrations (especially Craft 4 to 5)
---

# Codex Command Alias: /craft-migrate

<!-- Generated by tools/generate-codex-command-skills.py; edit the source command instead. -->

- This generated skill exposes the Claude slash command `/craft-migrate` to Codex.
- Treat the user's message that invoked this skill as the command arguments.
- When the embedded command body says `$ARGUMENTS`, substitute those user-supplied arguments.
- Follow the embedded command body as the workflow source of truth.
- Translate Claude-only tool names to Codex equivalents when needed: use `update_plan` for TodoWrite-style ledgers, `request_user_input` for AskUserQuestion-style gates when available, and normal chat questions when that tool is not available.
- If the command body says to launch an agent and Codex exposes `multi_agent_v1.spawn_agent`, use that tool with a role-appropriate agent type and a self-contained prompt.
- If the command body requires a nested `Skill(...)` call but Codex exposes no generic Skill tool, execute the referenced skill's documented protocol inline from its SKILL.md and clearly record the adapter mode.
- If neither native tool invocation nor a documented Codex adapter can preserve the workflow's gates, stop and report the missing capability instead of manually approximating the workflow.

## Embedded Claude Command

# Migration Planner

Help plan and execute Craft CMS migrations, especially Craft 4 to Craft 5 upgrades.

## Migration Types

### Craft 4 -> Craft 5

Major changes to understand:

**Matrix Fields**
- "Blocks" are now "nested entries"
- Entry types exist independently
- Nesting is now possible
- GraphQL types changed

**Empty Array Behavior**
- Craft 4: Empty `relatedTo` arrays return all results
- Craft 5: Empty arrays return NO results
- Fix: Check array length before passing

**GraphQL Type Names**
- Craft 4: `news_article_Entry`
- Craft 5: `article_Entry` (section prefix removed)

**Categories/Tags/Globals**
- Being phased out in favor of entries
- Build as entry types in sections instead

### Content Model Changes

When restructuring an existing content model:

1. **Audit current state** -- Document sections, fields, entry types
2. **Identify changes** -- What's being added, removed, restructured?
3. **Plan data migration** -- How will existing content transform?
4. **Test in staging** -- Never migrate production first
5. **Execute with backups** -- Always have a rollback plan

## MCP Integration

If the Craft MCP server is available:

- `get_system_info` -- Check Craft/PHP versions
- `list_sections` -- Audit current sections
- `list_fields` -- Audit current fields
- `list_plugins` -- Check plugin compatibility
- `get_deprecations` -- Find deprecated code
- `get_project_config_diff` -- See pending changes
- `create_backup` -- Backup before changes
- `list_backups` -- Verify backups exist

## Process

1. **Assess** -- Understand current state and target state
2. **Document** -- Create migration checklist
3. **Test** -- Run migration in development/staging
4. **Fix** -- Address issues found in testing
5. **Execute** -- Run migration on production
6. **Verify** -- Confirm everything works

## Output

Provide clear migration plans with step-by-step instructions. Highlight breaking changes and required code updates. Include rollback strategies.