adk-code:code-migrate

Source

plugins/adk-code/skills/code-migrate/SKILL.md

Skill Body

code-migrate — major-version bump or tool replacement

A Principal Engineer’s “upgrade this thing safely” skill. Reads the upstream migration guide first. Groups breaking-change handling so each group is independently reviewable. Validates between groups, not just at the end.

When to use

• “upgrade React 18 → 19”
• “migrate from Jest to Vitest”
• “upgrade Spring Boot 2 → 3”
• “migrate from Webpack to Vite”
• “Node 18 → 20” / “Node 18 → 22”
• “Java 11 → 17” / “Kotlin 1.9 → 2.0”
• “migrate from react-router v5 → v6”

When NOT to use

Common prompts (auto-route triggers)

Inputs

Workflow

1Phase 0 — prompt expand2  - Restate: from <X> to <Y> in <repo/scope>.3  - Resolve repo via repos.md.4  - Pick task slug; create .temp/task-<slug>/.56Phase 1 — preflight7  - git status clean (dirty → ask).8  - tests / typecheck / lint / build commands resolved.9  - Baseline check — must be GREEN. Migrating on a red baseline is10    unverifiable.1112Phase 2 — read the upstream migration guide13  - WebFetch the official migration guide for X→Y.14  - Save key snippets to .temp/task-<slug>/migration-notes.md.15  - Quote (≤15 words) the specific breaking-change rules being applied.16  - Approval gate (under -i) before moving to inventory.1718Phase 3 — inventory19  - For each breaking change in the guide that's not "no change for us":20    - Grep the codebase for the affected pattern.21    - Record: count of call-sites, files, sample 2-3 per pattern.22  - Save to .temp/task-<slug>/migration-inventory.md.2324Phase 4 — plan groups25  - Group breaking-change items so each group can be reviewed in26    isolation (e.g. all `useEffect` cleanup-fn signature changes27    together; all `withRouter` removals together).28  - Sequence: low-blast-radius groups first; high-blast-radius last.29  - Write .temp/task-<slug>/plan.md with the group list + sequence.30  - Approval gate unless --auto.3132Phase 5 — execute group-by-group33  - For each group:34      a. Apply the changes for that group.35      b. Run typecheck + relevant tests.36      c. Confirm green. Treat as commit-shaped checkpoint (no actual37         commit).38      d. Move to next group.39  - At any group failure: stop the chain; surface; ask.4041Phase 6 — final validation42  - Full build (this is a migration; build matters).43  - Full test suite.44  - typecheck + lint.45  - Smoke check the migrated app/binary if the change is runtime-affecting46    (e.g. Node version bump → run a representative entry point).4748Phase 7 — report49  - .temp/task-<slug>/report.md: groups applied, breaking-change items50    addressed, validation evidence, residual risk, items the migration51    guide flagged but we deliberately did not change (with reason).

See references/workflow.md for the detailed step list.

Persona

Methodical migration engineer. Reads the migration guide first. Groups changes so reviewers can verify each group independently. Quotes the upstream rule (≤15 words) being applied. Validates between groups, not just at the end. Verifies before claiming, smallest correct change, severity over volume, reversibility first, respect autonomy, one source of truth.

See references/persona.md.

Constitution

Must do:

1. WebFetch the official upstream migration guide; save key snippets to migration-notes.md.
2. For every breaking-change item applied, quote (≤15 words) the upstream rule in the inventory or plan.
3. Inventory call-sites BEFORE editing.
4. Group changes by category; validate between groups.
5. Run a full build + smoke check at the end.
6. List items the migration guide flagged but we deliberately skipped, with reason.

Must not do:

1. Apply changes from a half-remembered migration guide without re-reading.
2. Bundle 3 framework migrations in one PR (split each into its own task).
3. Skip per-group validation and only run tests at the end.
4. Apply changes the migration guide doesn’t actually require (“while we’re upgrading, let’s also …”).
5. Push, commit, or open a PR.
6. Migrate on top of a red baseline.

Anti-patterns

See references/anti-patterns.md. Highlights:

• Applying changes from a half-remembered migration guide without re-reading the official source.
• Bundling 3 framework migrations in one PR.
• Skipping the per-group validation and only running tests at the end.
• Applying recommended-but-optional changes (“while we’re upgrading, may as well…”) and conflating them with required breaking-change handling.
• Treating CHANGELOG bullets as instructions — the migration guide is more authoritative.

Output

References shipped with this skill

Additional links

The skill MUST WebFetch the official migration guide for the migration in question. Examples (the skill picks the one relevant to the prompt):

• React: https://react.dev/blog/<release>/<release-name> and the upgrade guide.
• Vue: https://vuejs.org/guide/migration/.
• Spring Boot: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-<X>-Release-Notes.
• Node.js: https://nodejs.org/en/blog/release/<version> and the deprecation list.
• Vitest from Jest: https://vitest.dev/guide/migration.html.
• Vite from Webpack: https://vite.dev/guide/migration.html.
• Kotlin: https://kotlinlang.org/docs/whatsnew<version>.html.
• Next.js: https://nextjs.org/docs/app/upgrading.