Framework Migration Architect

The Problem

You're staring at a Next.js 13 → 14 upgrade, a Django 3.2 → 4.2 jump, or an Express → Fastify rewrite. The official migration guide has 40+ breaking changes. You don't know which ones actually affect your codebase. You start converting files, tests break in unrelated modules, and by Sunday night you're further behind than when you started. The agent you asked to help regenerates entire files, misses edge cases, and can't tell you which third-party packages will break before you discover it in production.

What You Get

• Migration readiness assessment that scans your entire codebase for deprecated APIs, removed features, and changed signatures — producing a compatibility report with severity ratings (blocking vs. advisory) and file-level impact counts
• Phased transformation plan that orders changes by dependency graph — preparation, non-breaking changes, breaking changes, verification, and cleanup — so each phase can be tested and committed independently
• Code transformation patterns with before/after examples for your specific framework pair (Pages → App Router, class → hooks, url() → path(), Express → Fastify, etc.) that handle the actual syntax changes, not abstract advice
• Third-party compatibility map that flags packages in your dependency tree that may not support the target version, with recommended replacements or workarounds
• Rollback instructions per phase — exact git commands, config reversions, and data migration rollback steps for every stage of the migration
• Post-migration verification checklist covering unit tests, integration tests, type checking, linting, build success, runtime behavior, deprecated API cleanup, and performance baseline comparison

Why This Beats Prompting It Yourself

When you ask a generic agent to "upgrade Next.js 14," it starts rewriting files without mapping the full scope of changes. It misses config file format changes, third-party package incompatibilities, and subtle behavioral shifts in new APIs. The result: a half-migrated codebase where half the tests pass and the other half fail for reasons you can't trace. This skill forces a readiness assessment before any code is touched — the #1 failure mode in migrations is starting to transform code before understanding the full blast radius.

Example Session

You: "We need to migrate our Django 3.2 project to Django 4.2. It's a 12-module monolith with about 200 URLs and 15 custom middleware."

Agent output:

COMPATIBILITY REPORT — Django 3.2 → 4.2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Files affected: 34
Total instances: 67

BLOCKING (must fix before upgrade):
  [CRITICAL] 12 files use django.conf.urls.url() — removed in 4.0
  [CRITICAL] 3 files use force_text() — removed in 4.0
  [CRITICAL] 1 file sets USE_L10N = False — setting removed in 4.0

ADVISORY (should fix, won't crash):
  [HIGH] 8 files use deprecated PASSWORD_HASHERS config key
  [MEDIUM] 5 middleware classes inherit from old-style middleware

PHASED PLAN:
  Phase 0 (Prep): Update requirements.txt, run `python -m django check`
  Phase 1 (Non-breaking): Add django.urls.path() imports alongside old url()
  Phase 2 (Breaking): Replace url() → re_path(), force_text() → force_str()
  Phase 3 (Verify): Run full test suite, check deprecation warnings
  Phase 4 (Cleanup): Remove compat imports, update docs

Use Cases

• Upgrading framework major versions (Next.js 13→14, Django 3→4, React 18→19, Vue 2→3)
• Architectural migrations (Pages Router → App Router, class components → hooks, Express → Fastify)
• Python version upgrades (2→3, 3.8→3.12 type hint modernization)
• Spring Boot version jumps with deprecated API removal
• Angular major version upgrades with RxJS migration

Known Limitations

Automated codemods (jscodeshift, libCST, 2to3) are powerful but can produce incorrect transformations for edge cases — always review codemod output manually. The skill does not execute migrations autonomously; it produces plans and patterns that a human or agent applies phase by phase with verification between each step.