| name | code-migration |
| description | Run a large-scale language migration with the six-step process: create the map and the rules, stress-test the rules, translate everything, compile, run it, match behavior. Use when the user wants to migrate, port, or rewrite a codebase from one language to another ("migrate this to Rust", "port our Python CLI to TypeScript", "should we rewrite this in Go?"), or asks for a migration feasibility assessment. Not for incremental JS→TS adoption — that needs no machinery — or single-file conversions.
|
Code migration (six-step process)
You are orchestrating a language migration using the Claude Code Migration
Kit. [kit path]/README.md defines the process; [kit path]/CLAUDE.md defines
your standing rules — read both before acting (set [kit path] when installing
this skill). The standing rules override
convenience: queues live on disk, sign-off gates end workflows, the rulebook
is read-only inside loops, reviewers are adversarial and separate.
Routing
- No migration artifacts exist yet (
migration/ absent): run
prompts/00-feasibility.md. Produce the report, deliver the verdict, STOP.
Do not begin Step 1 in the same session, even if the verdict is "migrate
now" — the human kicks off each phase.
1b. Feasibility signed off, no judge yet: before Step 1, confirm a judge
exists that runs against both old and new code through the public surface.
If the existing suite is public-surface (or already in a third language),
it's the judge — carry it to Step 6. If it imports internals, run
prompts/00b-judge-setup.md to build and validate a portable parity harness
(validated against the original AND deliberately broken code) and STOP at its
gate. Never start Step 1 without a judge — there's no exit condition without
one.
- Feasibility and judge signed off, no map/rules: run Step 1 — adapt a
scripts/depmap_* for the source ecosystem (prompts/01), copy
templates/RULEBOOK.md to migration/RULEBOOK.md and draft it with the
human (the policy decisions are theirs; survey the codebase for the facts),
then prompts/02 for the gap inventory. Each ends at its own gate.
- Step 1 signed off: confirm the HUMAN has installed
.claude/settings.json from templates/settings.json — prompt 03
verifies it; never install it yourself — then run
prompts/03-stress-test.md. But FIRST check the rulebook's §0 posture:
if this is a redesign migration, the bakeoff is invalid; substitute
adversarial design-doc review and tell the human why.
- Stress test signed off: confirm
migration/manifest.tsv exists
(prompt 01's closing action generates it), then run
prompts/04-translation-kickoff.md with scripts/queue_runner.mjs as the
queue — first check the referee price: if the target's typecheck is cheap,
the dissolve edit is the human's act at the gate — ask them to remove
those denies from settings.json; never edit it yourself (README Step 4
dissolves into Step 3).
- Translation queue empty: Step 4 via
prompts/05-survey-build.md
(survey build → machine queue → fixers without compiler access; skip it
entirely if Step 4 dissolved into Step 3), then Step 5 (hello world,
smoke), then Step 6 (inherited suite burndown, or parity referee against
the old code).
- Step 6 done-gate passed (both counts documented — README Step 6): run
prompts/06-post-parity.md — collect the port markers, classify fix-now
vs document-and-close, ship each fix as its own flagged change proved by a
parity re-run. Ends at its own gate.
Constant behaviors
- Report progress as burndown numbers (
queue_runner.mjs status), not prose.
- A failure seen three times is a rule bug: stop fixing instances, queue the
amendment, propose regenerating the slice.
- "Don't migrate" and "stop here" are valid recommendations at every gate.
