/shift

Framework Migration Reference

Purpose: Execute a major framework version jump or cross-framework port with preserved behavior, measurable progress, and reversible phases. The recipe applies to front-end frameworks (Vue 2 → 3, React CRA → Next.js, Angular major), back-end frameworks (Express → Fastify / Hono, Spring Boot major), and full-stack stacks (Rails major, NestJS major).

Scope Boundary

• Shift framework: executes a specific framework migration with a feature-parity checklist, incremental adapter pattern, and dual-run validation.
• Shift migrate (default): general migration planning — picks Strangler Fig vs Branch by Abstraction at an architectural level, no framework-specific gotchas.
• detect Recipe: detects deprecated libraries/frameworks and suggests replacements — it produces the input for framework; it does not execute the migration.
• Zen: refactor within a framework — does not cross versions.
• Launch: plans the release where the migrated code ships; framework owns the code transition.

If the request is "what should we move off?" → detect. If it is "we have chosen Vue 3, now move us" → framework.

Framework-Specific Gotchas

Record anything you hit that is not on this list in .agents/shift.md for future reuse.

Codemod-First Posture (2026 default)

For every row above, check the framework's official codemod set before hand-writing a transform:

• React: reactjs/react-codemod (also distributed via Codemod.com migrations) — covers Context.Provider, forwardRef, useContext → use, and the legacy class-component path. The React team co-published React 19 codemods with codemod.com.
• Vue: vuejs/vue-codemod — Vue 2 → 3 API rewrites, jscodeshift-based.
• Next.js: npx @next/codemod upgrade <version> (e.g., upgrade 16) — version-pinned transforms shipped with the framework; also covers upgrading async APIs, cache changes, and metadata rewrites.
• Svelte: npx sv migrate svelte-5 — official whole-app migrator; or VS Code Svelte extension for per-component migration. Svelte 5 supports mixing old and new syntax.
• Spring Boot (Java/Kotlin): OpenRewrite with UpgradeSpringBoot_3_x / UpgradeSpringBoot_4_0 recipes — operates on Lossless Semantic Trees (LST), not raw ASTs, for higher-fidelity Java transforms. Run via ./mvnw -U rewrite:run or Gradle equivalent.
• Codemod.com Studio + Hypermod: visual / managed codemod runners that sit on top of ast-grep (jssg) and jscodeshift; use when the official codemods do not cover the delta.

A codemod cannot replace the semantic verification column above. Treat the codemod output as a starting diff and run the dual-run validation regardless.

Workflow (overlays ASSESS → ... → COMPLETE)

ASSESS   →  pin current + target minor/patch versions exactly
         →  inventory: entry points, framework-coupled modules, plugin/middleware list
         →  capture `detect` findings if present (what forced this migration?)
         →  measure test coverage per surface; flag surfaces with <40% as high-risk

PLAN     →  feature-parity checklist (one row per framework feature in use)
         →  adapter strategy: shim, compat build, or dual-entry
         →  dual-run plan: run old + new against the same request set, diff responses
         →  deprecation-warning triage policy (fix now / defer with ticket / accept)
         →  rollback point per phase

PREPARE  →  pin lockfile; snapshot current behavior (golden fixtures, HAR, SQL trace)
         →  scaffold adapter / compat layer
         →  generate codemods for mechanical rewrites (ast-grep/jscodeshift)
         →  wire feature flags for per-route / per-module cutover

EXECUTE  →  migrate one bounded context at a time
         →  keep old adapter live behind flag
         →  turn on dual-run in staging; diff until delta is understood (expected vs regression)
         →  triage deprecation warnings after each phase — do not let them stack

VERIFY   →  feature-parity checklist: every row green
         →  dual-run delta: zero unexplained diffs
         →  perf benchmark within agreed envelope (default ≤±10% latency)
         →  dependent services (observability, auth, cache) still healthy

COMPLETE →  remove adapter/shim, remove feature flags, drop old framework deps
         →  delete dual-run harness
         →  document residual deprecation-warning budget for next cycle

Feature-Parity Checklist Template

One row per feature surface. Do not shortcut the matrix.

"Diff" status requires a diff explanation (expected change vs regression).

Dual-Run Validation Pattern

1. Route a shadow copy of real traffic (or a captured request set) to the new stack.
2. Compare responses field-by-field — normalize timestamps and IDs before diff.
3. Classify each diff: expected (e.g., new error shape is intentional), regression (must fix), or benign (log format, header ordering).
4. Promote only when regression count is zero and expected diffs are documented.

Tools: diffy for JSON, framework-specific shadow-proxy (e.g., GoReplay, Envoy mirror filter), or a test harness replaying fixture requests.

Deprecation-Warning Triage

• Capture warnings per phase (stderr, framework logger, browser console).
• Classify: fix-now (removed next minor), defer (file ticket, set expiry date), accept (third-party, pinned).
• A deferred warning without an expiry date is not deferred — it is ignored. Block COMPLETE if any warning lacks classification.

LLM-Assisted Migration (2025–2026)

For large Java / .NET modernization tasks, AI-assisted tooling can accelerate the assessment and fix phases:

• GitHub Copilot App Modernization (VS Code extension): agent-mode workflow that runs assessment → solution recommendation → code fixes → validation in a guided loop. Includes automatic CVE scanning on changed dependencies and proposes safe version replacements when vulnerabilities are detected. Source: GitHub Blog — Modernizing Java projects with Copilot agent mode; Microsoft Learn — Copilot modernization overview.
• Sourcegraph Cody: context-aware AI assistant that uses Code Graph to understand the full repository; useful for surfacing cross-cutting migration touchpoints in large monorepos. Note: as of June 2025, Cody Free/Pro new signups closed — enterprise-only for new customers.
• Research note: arXiv 2025 study on Copilot Agent Mode for library migration (2510.26699) found meaningful automation rates for dependency-level mechanical changes; semantic verification still requires human review and test harnesses.

Guardrail: LLM-generated transforms must pass the same dual-run validation as codemod output — treat them as a draft diff, not a complete migration.

LaunchDarkly Migration Flags Pattern

For data/infrastructure migrations that need staged, independently-controllable read/write cutover (beyond simple boolean rollout):

LaunchDarkly Migration Flags offer 2, 4, or 6 stages. The 6-stage variant controls reads and writes independently:

Stage 1 (off)        → read old / write old
Stage 2 (dualWrite)  → read old / write old+new
Stage 3 (shadow)     → read old / write old+new, compare reads
Stage 4 (live)       → read new / write old+new
Stage 5 (rampDown)   → read new / write new (old passthrough)
Stage 6 (complete)   → read new / write new

The SDK's migrator helper runs the validation function automatically in shadow stages and emits migration metrics to LaunchDarkly. Use this pattern instead of hand-rolled dual-write code when the team already uses LaunchDarkly. Source: LaunchDarkly migration flags docs.

Anti-Patterns

• Migrating in a single branch for 6+ weeks without landing to main. Ship adapter-first so partial progress is always merge-able.
• Treating codemod output as complete — mechanical rewrites cover shape, not semantics.
• Upgrading the framework and a major dependency (ORM, state lib) in the same phase. Split.
• Skipping dual-run because "tests pass" — tests cover known cases; dual-run catches unknown-unknowns.
• Leaving the compat shim in place after COMPLETE "just in case" — it becomes a second framework to maintain.

Handoff

• → Builder: implementation tasks per phase, with codemod + adapter touchpoints called out.
• → Radar: dual-run harness as a regression test; feature-parity rows as acceptance tests.
• → Gear: CI pipeline needs the new framework's build tooling and may need parallel test lanes during dual-run.
• → Launch: cutover release plan, flag flip schedule, rollback runbook.
• ← detect: consumes "framework is deprecated" findings as the trigger for this recipe.