modernize-transform

---

description: Rewrite one legacy module in the target stack, with tests that prove it behaves the same argument-hint: [module] [target-stack] arguments: system module target_stack

Transform module $module of $system into $target_stack, with proof of behavioral equivalence. This is one vertical slice of the strangler fig; output goes to modernized/$system/$module/.

The code is legacy/$system, often a symlink to where it really lives: say where it points (readlink legacy/$system) in one line before you start. If legacy/$system does not exist, stop and say so: nothing can run without the code, so the fix is /code-modernization:modernize $system --source <path to the code>. Run every subagent in the foreground and wait for its result: never end your turn while one is still running. Stop any server or other process you started (a legacy app on a local port, a watcher) before you finish, and say you did. If $module or $target_stack is empty, read analysis/$system/MODERNIZATION_BRIEF.md: take the target stack it names, and the first module of the earliest phase whose Command: is transform that has no modernized/$system/<module>/TRANSFORMATION_NOTES.md yet (with no brief, the target in INTENT.md). Say which you picked.

Step 0 — Toolchain, then the plan (human gate)

Target stack (required). The runtime, package manager and test framework must respond (java -version and mvn -v, node -v and npm -v, python3 -V and pytest --version). If not, stop and say what to install: a plan gate now would only defer the failure an hour. Point to /code-modernization:modernize-preflight $system $target_stack.

Legacy stack (advisory, never a blocker). Try a syntax-only compile of the module. Legacy code often cannot build locally by nature (CICS and IMS programs have no local translator; the real runtime is a mainframe you do not have). If it cannot, dual execution is off the table: the tests assert against recorded traces and golden-master fixtures (real production outputs, captured reports, SME-confirmed examples). Say so in the plan and in TRANSFORMATION_NOTES.md ("equivalence is trace-based; legacy was not executable here"), so reviewers know how strong the proof is.

Run the old system only where it is safe. Record baselines from the legacy code running on this machine, or against a test environment the person named. Never call a production or third-party service, register an account, or send or change real data to record a baseline unless the person approved that exact target in the plan (say which calls, and which of them write). A token, password or session cookie in a recorded response is a secret: replace it with a fixed fake value before anything is saved, and never print it.

The brief is binding. If MODERNIZATION_BRIEF.md exists, find the phase whose Command: is this one and whose Modules: include $module, and treat its scope, entry criteria, exit criteria and any edits the user made as binding. An unmet entry criterion is the next step: meet it, never re-plan around it. If no phase covers $module, stop and ask which phase this is.

Read the module's source and the rules in BUSINESS_RULES.md that reference it, and any verdicts on them in analysis/$system/RULE_REVIEWS.json: a rule marked wrong is not pinned as the oracle (use the reviewer's note for what is right, and if the note does not say, ask), and a P0 rule marked discuss is a question to settle at this plan gate before any code. Then present the plan and stop: write no code until the user explicitly approves (plan mode if available): which source files are in scope, the target structure, which rules and behaviors it implements, how you will prove equivalence, and anything ambiguous that needs a human decision now.

Step 1 — Characterization tests first

Spawn the test-engineer subagent: "Write characterization tests for module $module of legacy/$system. Read the source, identify every observable behavior and encode each as a test with concrete input and expected output derived from the legacy logic. Target framework: <right for $target_stack>. Write to modernized/$system/$module/src/test/. These tests define 'done'. Name the RULE-NNN id(s) each test pins (from analysis/$system/BUSINESS_RULES.md) in its name or a one-line comment, so the trace can find it. Follow your secret-handling rules: no credential from legacy code becomes a fixture; use fake same-shape values and read anything live from environment variables." Show the user the test file and get a yes before going on.

Step 2 — Idiomatic transformation

Write the implementation in modernized/$system/$module/src/main/. Write what a senior $target_stack engineer would write from the specification, not from the legacy structure: do not mirror COBOL paragraphs as methods or keep names like WS-TEMP-AMT-X; use the target's idioms (records, streams, injection, proper error types). Include the domain model, service logic, API surface and configuration, and link each class to the rule IDs it implements in a short comment.

Step 3 — Prove it, and prove the proof can fail

While iterating, run only this module's tests; run the whole suite once before Step 4.

1. Run the tests (cd modernized/$system/$module and the stack's test command) and show the output. Fix and rerun until green.
2. Count what ran. Report equivalence cases executed: N. A run that executed zero cases proved nothing, and a comparison test must fail, never skip, when its legacy oracle or fixture is missing: a suite that is green because everything skipped is not green. If the oracle was unreachable, fix that; do not report the suite as passing.
3. Show the tests can fail. Temporarily break the new code in one small way that matters (change a rounding mode, shift a threshold by one, flip a comparison), confirm at least one test goes red, restore it, and record Canary: <the change> → <N> tests failed in the notes. If nothing failed, the tests do not pin the behavior: strengthen them before going on.
4. When the legacy code can run here, also run both systems on the same inputs, save each output under analysis/$system/equivalence/legacy/ and .../new/, list the pairs in analysis/$system/equivalence/cases.json (paths relative to that folder; the schema is at the top of scripts/compare.py), and run python3 "${CLAUDE_PLUGIN_ROOT}/scripts/compare.py" analysis/$system/equivalence/cases.json --out analysis/$system/EQUIVALENCE.json. That script, not your judgment, decides same or different. Mask only fields that legitimately vary (timestamps, generated ids) and say what each mask hides. A difference you accept is recorded with a reason in the case's approvedDifference, and only a person accepts it. Floating-point numbers that another compiler or math library prints slightly differently are not a mask: give that case a tolerance (rel or abs, and a why), which compares numbers written with a decimal point or exponent within it, every other byte exactly, and is listed in the result.

Step 4 — Notes and a side-by-side

Write modernized/$system/$module/TRANSFORMATION_NOTES.md: a mapping table (legacy file:lines to target file:lines, per behavior); deliberate deviations with rationale; what was NOT migrated (dead code, unreachable branches) and why; the canary result and the executed-case count; follow-ups for the next dependent module. Show one representative behavior side by side (diff -y --width=160 <(sed -n '<lines>p' <legacy file>) <target file>). Never pick a credential-bearing range, and mask any credential-like literal in the notes: they live in modernized/ and get committed. This is your own evidence: /code-modernization:modernize-verify $system $module is the independent re-check (it re-runs the tests and the comparison, tries new inputs, and gives one verdict).

Step 5 — Architecture review

Spawn the architecture-critic subagent to review the code against $target_stack best practice. Apply HIGH-severity feedback and list the rest in the notes.

Report: tests passing, cases executed, lines of legacy retired, where the artifacts are. Refresh the report (python3 "${CLAUDE_PLUGIN_ROOT}/scripts/build_report.py" $system, a convenience: if it fails or python3 is missing, say so in one line and carry on). The next step is the brief's next module, or /code-modernization:modernize-harden $system when the phase is done.