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

- Expose `/craft-migrate` as a workflow entrypoint, not a CLI call. Treat the invoking message as arguments, substitute `$ARGUMENTS`, and follow this protocol in the current Codex harness.
- Resolve canonical `plugins/<name>/...` paths under that plugin's host-selected coherent installed bundle, not the consumer repository. Read nested SKILL.md files there and follow them inline when no generic Skill tool exists.
- Workflow-specific dispatch takes priority: use required model-router role-dispatch and retain its outputs and receipts. Use native subagents only when that workflow explicitly permits them.
- Do not launch another harness solely for its source or cache format. Explicit cross-harness requests and router-selected participant transports remain supported.
- Translate Claude tools when needed (`TodoWrite` to `update_plan`; `AskUserQuestion` to `request_user_input` or chat). Report the exact missing path/tool and preserve completed evidence; never manual-substitute required lanes or fabricate receipts.

## Command Workflow

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