Migrate

Purpose

Migrate is the orchestrator for all types of migrations: framework upgrades, language version bumps, architecture shifts, database schema changes, dependency replacements, and technology swaps. It treats every migration as a high-risk operation and applies a disciplined process: plan thoroughly, back up everything, execute incrementally, verify at each step, and always have a rollback plan.

Migrations are inherently dangerous because they touch many files, change fundamental assumptions, and can introduce subtle regressions that only surface later. Migrate exists to make this process as safe and systematic as possible.

Workflow

Phase 1: Assess & Plan

1. Parse the migration scope -- Understand what's being migrated from and to. Identify all affected areas.
2. Invoke scout -- Scan the codebase to build a complete inventory of what needs to change:
   • Files using the old pattern/technology
   • Configuration files that reference it
   • Tests that depend on it
   • Documentation that mentions it
   • Dependencies that relate to it
3. Invoke research -- Look up the migration path:
   • Official migration guides (via Context7)
   • Known breaking changes between versions
   • Community-reported pitfalls
   • Codemods or automated migration tools available
4. Invoke sequential-thinking -- Reason through the migration order:
   • What must change first (foundations) vs last (consumers)
   • Which changes are independent vs dependent
   • Where the risk concentrations are
5. Invoke plan -- Create a phased migration plan:
   • Phase boundaries with clear milestones
   • Per-phase file lists and change descriptions
   • Risk assessment per phase
   • Estimated effort per phase
   • Rollback strategy per phase
6. Invoke plan-validate -- Verify the plan is complete and feasible.
7. Invoke mermaid (if complex) -- Visualize the migration dependency graph.
8. Present the plan -- Show the user the full migration plan. This is a mandatory checkpoint -- no migration proceeds without explicit user approval.

Phase 2: Backup

9. Invoke git-workflow -- Create a migration branch from the current state.
10. Create a pre-migration snapshot -- Tag the current state so rollback is always one command away.
11. Document the current state -- Record:
    • Current versions of all affected dependencies
    • Current test results (baseline)
    • Current build output (baseline)

Phase 3: Execute (Per Phase)

For each phase in the migration plan:

12. Execute the changes -- Apply the transformations for this phase:
    • Use codemods if available
    • Manual code changes following the plan
    • Configuration updates
    • Dependency changes
13. Invoke test -- Run relevant tests after each phase:
    • Tests for directly changed code
    • Tests for code that depends on changed code
    • Full suite at major phase boundaries
14. Handle failures -- If tests fail:
    • Simple fixes: Invoke fix to resolve
    • Complex issues: Invoke debug to investigate root cause
    • Blocking issues: Halt and report. Do not proceed to the next phase.
15. Invoke commit-crafter -- Commit the phase with a descriptive message like migrate(phase-2): convert REST routes to GraphQL resolvers.
16. Phase checkpoint -- Report phase completion, test results, and any concerns before proceeding.

Phase 4: Verify

17. Run full test suite -- After all phases complete, run every test.
18. Invoke code-review -- Review the entire migration diff:
    • Check for incomplete migrations (old patterns still present)
    • Check for regressions
    • Check for unnecessary changes (scope creep)
    • Check for security implications
19. Invoke optimize (if applicable) -- If the migration was a framework upgrade, check that performance hasn't regressed.
20. Invoke scout -- Re-scan for any remaining references to the old pattern. Flag anything left behind.

Phase 5: Rollback Plan

21. Document the rollback procedure -- Create explicit rollback instructions:
    • Git commands to revert to the pre-migration tag
    • Dependency rollback commands
    • Database rollback steps (if applicable)
    • Configuration rollback steps
22. Test the rollback (if high-risk) -- For critical migrations, actually test that the rollback works on a branch.

Phase 6: Complete

23. Invoke docs-writer -- Update documentation to reflect the new state.
24. Invoke plan-archive -- Archive the migration plan for future reference.
25. Present migration summary -- Report:
    • Total files changed
    • Tests before vs after
    • Any remaining TODO items
    • Rollback instructions
    • Recommended next steps (usually ship)

Migration Types

Framework Upgrade

Example: Next.js 14 -> Next.js 15
Phases:
  1. Update dependencies + config
  2. Migrate deprecated APIs
  3. Update routing patterns
  4. Update data fetching patterns
  5. Full test + review

Language Version Bump

Example: Node.js 18 -> Node.js 22
Phases:
  1. Update engine constraints
  2. Replace deprecated APIs
  3. Adopt new language features (optional)
  4. Update CI/CD node version
  5. Full test + review

Technology Swap

Example: Styled-components -> Tailwind CSS
Phases:
  1. Install Tailwind, configure
  2. Convert shared/base components
  3. Convert feature components
  4. Convert page-level components
  5. Remove styled-components
  6. Full test + visual review

Database Migration

Example: MySQL -> PostgreSQL
Phases:
  1. Set up PostgreSQL, schema migration
  2. Update ORM config + queries
  3. Data migration scripts
  4. Update connection handling
  5. Parallel run + data verification
  6. Cutover

Architecture Shift

Example: Monolith -> Microservices
Phases:
  1. Identify service boundaries
  2. Extract shared libraries
  3. Extract first service
  4. Set up inter-service communication
  5. Extract remaining services
  6. Remove monolith routing

Decision Points

Condition	Action
Official migration guide exists	Follow it, supplement with codemod
Codemod available	Use it for bulk changes, review output
Migration affects database	Require explicit backup + rollback test
Test suite is insufficient	Write migration-specific tests before migrating
Phase fails after 3 fix attempts	Halt, report, ask user for direction
Migration is < 10 files	Simplify to single-phase execution
Migration is > 100 files	Mandatory multi-phase with checkpoints

Usage

Use Migrate for any change that transforms the project from one state to another at a foundational level. This is distinct from refactor (which restructures without changing technology) and cook (which adds features).

Best for:

• Framework or library version upgrades
• Technology swaps (one library for another)
• Architecture transformations
• Database migrations
• Language version upgrades
• Build tool migrations

Not ideal for:

• Adding new features (use cook)
• Code restructuring without technology change (use refactor)
• Deploying existing code (use ship)
• Quick dependency updates with no breaking changes (just update and test)

Examples

Example 1: Framework upgrade

User: /migrate Upgrade from React 18 to React 19

Migrate workflow:
1. scout -> Find all React imports, hook usage, deprecated patterns
2. research -> React 19 migration guide, breaking changes list
3. plan -> 4 phases: deps, compiler setup, API updates, new features
4. Backup -> Tag pre-migration, create branch
5. Phase 1 -> Update react, react-dom, types
6. Phase 2 -> Set up React compiler, remove useMemo/useCallback where safe
7. Phase 3 -> Update deprecated APIs (forwardRef removal, etc.)
8. Phase 4 -> Adopt new patterns (use(), Actions)
9. Verify -> Full test suite, code-review, scout for remnants
10. Rollback plan -> Document revert steps

Example 2: ORM migration

User: /migrate Move from Prisma to Drizzle ORM

Migrate workflow:
1. scout -> Inventory all Prisma models, queries, migrations
2. research -> Drizzle schema syntax, query API differences
3. plan -> 5 phases: schema, queries, migrations, middleware, cleanup
4. Backup -> Tag pre-migration
5. Phase 1 -> Convert Prisma schema to Drizzle schema
6. Phase 2 -> Rewrite queries (findMany -> select, etc.)
7. Phase 3 -> Set up Drizzle migration system
8. Phase 4 -> Update middleware and utilities
9. Phase 5 -> Remove Prisma, clean up
10. Verify -> Full test suite, data integrity checks

Guardrails

• Never migrate without a plan. Every migration must be planned and approved by the user.
• Never migrate without backups. A pre-migration git tag is mandatory.
• Always verify per-phase. Run tests after every phase, not just at the end.
• Always have a rollback plan. Document exactly how to undo the migration.
• Never mix migration with feature work. A migration branch changes technology, not behavior.
• Scout before AND after. Check for remnants of the old pattern after migration completes.
• Commit per phase. Each phase gets its own commit for granular rollback capability.
• Halt on unexpected failures. If something breaks that the plan didn't anticipate, stop and reassess.