claude-plugins/plugins/code-modernization/commands/modernize-transform.md

---

description: Transform one legacy module to the target stack — idiomatic rewrite with behavior-equivalence tests

argument-hint:

Transform legacy/$1 module $2 into $3, with proof of behavioral equivalence.

This is a surgical, single-module transformation — one vertical slice of the strangler fig. Output goes to modernized/$1/$2/.

Step 0a — Toolchain check (fail fast on target, adapt on legacy)

Verify the build environment before planning, not when the tests first run:

• Target stack ($3) — required. Runtime, package manager, and test framework all respond (java -version + mvn -v, node -v + npm -v, python3 -V + pytest --version, …). If any are missing, stop and report what to install — the new code and its tests cannot run without them, so a plan gate now would just defer the failure an hour. Suggest /modernize-preflight $1 $3 for the full readiness report.
• Legacy stack — advisory, never a blocker. Try a syntax-only compile of the module being transformed (e.g. cobc -fsyntax-only). Legacy code often cannot build locally by nature, not by misconfiguration — CICS/IMS programs have no local translator, and the real runtime may be a mainframe you don't have. A failed or impossible legacy compile does not stop the transform; it changes the equivalence strategy:
  • dual-execution proof is off the table — characterization tests assert against recorded traces / golden-master fixtures (real production outputs, captured reports/screens, SME-confirmed examples) instead of live legacy runs
  • say so explicitly in the Step 0b plan and later in TRANSFORMATION_NOTES.md ("equivalence is trace-based; legacy was not executable in this environment"), so reviewers know the strength of the proof they're approving

Step 0b — Plan (HITL gate)

Read the source module and any business rules in analysis/$1/BUSINESS_RULES.md that reference it. Then present the plan and stop — write no code until the user explicitly approves (use plan mode if the session supports it):

• Which source files are in scope
• The target module structure (packages/classes/files you'll create)
• Which business rules / behaviors this module implements
• How you'll prove equivalence (test strategy)
• Anything ambiguous that needs a human decision NOW

Wait for approval before writing any code.

Step 1 — Characterization tests FIRST

Before writing target code, spawn the test-engineer subagent:

"Write characterization tests for legacy/$1 module $2. Read the source, identify every observable behavior, and encode each as a test case with concrete input → expected output pairs derived from the legacy logic. Target framework: . Write to modernized/$1/$2/src/test/. These tests define 'done' — the new code must pass all of them. Follow your secret-handling rules: no credential literal from legacy code becomes a fixture; substitute fake same-shape values and read anything genuinely live from environment variables."

Show the user the test file. Get a 👍 before proceeding.

Step 2 — Idiomatic transformation

Write the target implementation in modernized/$1/$2/src/main/.

Critical: Write code a senior $3 engineer would write from the specification, not from the legacy structure. Do NOT mirror COBOL paragraphs as methods, do NOT preserve legacy variable names like WS-TEMP-AMT-X. Use the target language's idioms: records/dataclasses, streams, dependency injection, proper error types, etc.

Include: domain model, service logic, API surface (REST controller or equivalent), and configuration. Add concise Javadoc/docstrings linking each class back to the rule IDs it implements.

Step 3 — Prove it

Run the characterization tests:

cd modernized/$1/$2 && <appropriate test command for $3>

Show the output. If anything fails, fix and re-run until green.

Step 4 — Side-by-side review

Generate modernized/$1/$2/TRANSFORMATION_NOTES.md:

• Mapping table: legacy file:lines → target file:lines, per behavior
• Deliberate deviations from legacy behavior (with rationale)
• What was NOT migrated (dead code, unreachable branches) and why
• Follow-ups for the next module that depends on this one

Then show a visual diff of one representative behavior, legacy vs modern:

delta --side-by-side <(sed -n '<lines>p' legacy/$1/<file>) modernized/$1/$2/src/main/<file>

(Fall back to diff -y --width=160 if delta isn't installed.) Never pick a credential-bearing line range for this diff, and mask any credential-like literal quoted in TRANSFORMATION_NOTES.md — the notes live in modernized/ and get committed.

Step 5 — Architecture review

Spawn the architecture-critic subagent to review the transformed code against $3 best practices. Apply any HIGH-severity feedback; list the rest in TRANSFORMATION_NOTES.md.

Report: tests passing, lines of legacy retired, location of artifacts.