SKILL.md

/migrate - Migration Workflow

Safe migrations for frameworks, languages, and infrastructure.

When to Use

"Migrate to X"

"Upgrade framework"

"Move from X to Y"

"Upgrade Python/Node/etc."

"Migrate database"

Framework version upgrades

Language migrations

Infrastructure changes

Workflow Overview

┌──────────┐    ┌──────────┐    ┌────────────┐    ┌──────────┐    ┌───────────┐

│  oracle  │───▶│ phoenix  │───▶│   plan-    │───▶│  kraken  │───▶│ surveyor  │

│          │    │          │    │   agent    │    │          │    │           │

└──────────┘    └──────────┘    └────────────┘    └──────────┘    └───────────┘

  Research       Analyze          Plan             Implement       Review

  target         current          migration        changes         migration

Agent Sequence

Agent

Role

Output

oracle

Research target framework/version

Research report

phoenix

Analyze current codebase for migration impact

Impact analysis

plan-agent

Create phased migration plan

Migration plan

kraken

Implement migration changes

Code changes

surveyor

Review migration for completeness

Migration review

Why Extra Gates?

Migrations are high-risk:

Breaking changes between versions

Dependency conflicts

Data format changes

API deprecations

The extra research and review phases catch issues early.

Execution

Phase 1: Research Target

Task(

  subagent_type="oracle",

  prompt="""

  Research migration target: [TARGET]

  Investigate:

  - Breaking changes from current version

  - New APIs and patterns

  - Deprecated features we use

  - Migration guides from official docs

  - Common pitfalls and solutions

  Output: Migration research report

  """

)

Phase 2: Analyze Current State

Task(

  subagent_type="phoenix",

  prompt="""

  Analyze codebase for migration: [FROM] → [TO]

  Identify:

  - Files using deprecated APIs

  - Dependency conflicts

  - Patterns that need updating

  - Test coverage of affected areas

  - Risk areas (critical paths)

  Output: Impact analysis with affected files

  """

)

Phase 3: Plan Migration

Task(

  subagent_type="plan-agent",

  prompt="""

  Create migration plan: [FROM] → [TO]

  Research: [from oracle]

  Impact: [from phoenix]

  Plan should:

  - Be phased (incremental if possible)

  - Each phase independently testable

  - Include rollback strategy

  - Prioritize critical path stability

  Output: Phased migration plan

  """

)

Phase 4: Implement

Task(

  subagent_type="kraken",

  prompt="""

  Implement migration phase: [PHASE_N]

  Plan: [from plan-agent]

  Requirements:

  - Follow plan exactly

  - Run tests after each change

  - Document any deviations

  - Stop if tests fail

  Output: Completed phase with test results

  """

)

Phase 5: Review Migration

Task(

  subagent_type="surveyor",

  prompt="""

  Review migration: [FROM] → [TO]

  Check:

  - All deprecated APIs replaced

  - No remaining compatibility shims

  - Tests passing

  - Performance acceptable

  - No security regressions

  Output: Migration review report

  """

)

Migration Types

Framework Upgrade

User: /migrate React 17 → 18

→ Full workflow with hooks/concurrent mode changes

Language Version

User: /migrate Python 3.9 → 3.12

→ Focus on new syntax, removed features

Database Migration

User: /migrate MongoDB → PostgreSQL

→ Schema design, data transformation, query rewrite

Infrastructure

User: /migrate AWS → GCP

→ Service mapping, config translation

Example

User: /migrate from Express to Fastify

Claude: Starting /migrate workflow: Express → Fastify

Phase 1: Researching Fastify...

[Spawns oracle]

Key differences:

- Schema-based validation (vs middleware)

- Plugin architecture

- Async/await native

- Different middleware pattern

Phase 2: Analyzing current Express usage...

[Spawns phoenix]

Impact analysis:

- 23 route files to update

- 8 middleware to convert

- 3 plugins need Fastify equivalents

- Test coverage: 78%

Phase 3: Creating migration plan...

[Spawns plan-agent]

Migration Plan: Express → Fastify

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 1: Setup &#x26; Core

- Add Fastify alongside Express

- Migrate core server setup

- Run both in parallel

Phase 2: Routes (by domain)

- Migrate auth routes

- Migrate user routes

- Migrate product routes

- ...

Phase 3: Middleware

- Convert error handler

- Convert auth middleware

- Convert logging

Phase 4: Cleanup

- Remove Express

- Remove compatibility layer

- Final testing

Rollback: Keep Express until Phase 4 complete

Phase 4: Implementing Phase 1...

[Spawns kraken]

✅ Fastify server running alongside Express

✅ Core routes migrated

✅ Tests passing

[Continues through phases...]

Phase 5: Reviewing migration...

[Spawns surveyor]

✅ All Express code removed

✅ 23/23 routes migrated

✅ Performance improved (2.1x faster)

✅ No security regressions

Migration complete! Express → Fastify

Incremental Migration

For large codebases, run one phase at a time:

User: /migrate React 17 → 18 --phase 1

[Runs only Phase 1]

User: /migrate React 17 → 18 --phase 2

[Runs Phase 2, reads previous handoff]

Flags

--phase N: Run specific phase only

--dry-run: Plan without implementing

--rollback: Execute rollback plan

--parallel: Run new alongside old (strangler fig)

migrate