claude-plugins-official/modernize-preflight.md at 3ca32ef77d232496dd9c199de9d9d952e980a03e

mirror of https://github.com/anthropics/claude-plugins-official.git synced 2026-06-14 06:36:18 -03:00

code-modernization: legacy toolchain is advisory, not a transform blocker

Legacy code often cannot build locally by nature — CICS/IMS programs
have no local translator and the real runtime may be a mainframe the
user doesn't have. Stopping transform on a failed legacy smoke compile
would block exactly those systems.

- transform Step 0a: the target toolchain remains required (its tests
  cannot run without it); a failed or impossible legacy compile no
  longer stops the run — the equivalence strategy switches to recorded
  traces / golden-master fixtures, and that downgrade is stated in the
  plan and in TRANSFORMATION_NOTES.md so reviewers know the strength of
  the proof
- preflight: a red legacy toolchain now yields Ready-with-gaps for
  transform/reimagine instead of Not-ready

2026-06-09 08:48:05 -07:00

4.5 KiB

Raw Blame History

description	argument-hint
Environment readiness check — analysis tools, build toolchain, source completeness, telemetry access	<system-dir> [target-stack]

Check whether this environment is ready to analyze — and eventually transform — legacy/$1, and tell the user exactly what to fix before the other commands run into it. Modernization sessions fail late and confusingly when this isn't done: assessment metrics silently degrade without analysis tools, characterization tests can't run without a build toolchain, and dependency maps come out wrong when half the source isn't in the tree.

Run every check even when an early one fails — the point is one complete readiness report, not the first error.

Check 1 — Detect the stack

Fingerprint legacy/$1 from file extensions and manifests: languages, build system, deployment/config descriptors. This drives which checks below apply. Report what was detected and the rough file split.

Check 2 — Analysis tooling

For each, check availability (command -v) and report version, what it's used for, and what degrades without it:

Tool	Used by	Without it
`scc` (or `cloc`)	assess	LOC/complexity fall back to `find`+`wc`; COCOMO estimate gets coarser
`lizard`	assess --portfolio	complexity estimated from decision-keyword counts
`glow`	all	markdown artifacts render as plain text
`delta`	transform	side-by-side diffs fall back to `diff -y`

Include the platform's install one-liner for anything missing (brew install scc, apt install cloc, pip install lizard, …).

Check 3 — Build toolchain (smoke test, not just presence)

Identify the compiler/interpreter for the detected legacy stack — e.g. GnuCOBOL (cobc) for COBOL, JDK + Maven/Gradle for Java, cc/make for C, dotnet for .NET. Then prove it works on this codebase: pick one representative source file and run a syntax-only compile (cobc -fsyntax-only, javac, gcc -fsyntax-only, …).

A failed smoke test is the most valuable output of this command — report the actual error and diagnose it: missing copybook/include path, missing dialect flag (-std=ibm etc.), fixed vs free format, missing dependency jar. These are the errors that otherwise surface mid-/modernize-transform with much less context.

If the user passed a [target-stack], do the same for it: runtime, package manager, test framework (mvn -v, npm -v, pytest --version, …).

Check 4 — Source completeness

The dependency map is only as good as what's in the tree. Check for the detected stack's equivalents of:

Referenced-but-missing includes — copybooks (COPY X with no X.cpy), headers, imports that resolve nowhere. Count and list the top missing names.
Deployment/config descriptors — JCL for batch COBOL, CICS CSD definitions, web.xml/route configs, cron/scheduler definitions. Without these, entry-point detection and the code↔storage join in /modernize-map are guesswork.
Data definitions — DDL, schemas, copybook record layouts, ORM mappings.
Binary-only artifacts — load modules, jars, DLLs with no matching source. These become unmappable black boxes; flag them now.

Check 5 — Optional context

Production telemetry — is an observability/APM MCP server connected, or are batch job logs / runtime exports available? (Enables the runtime overlay in /modernize-assess Step 4 and timing annotations in /modernize-map.)
Version control history — is legacy/$1 under git with meaningful history? (Change-frequency data sharpens risk ranking.)

Report

Write analysis/$1/PREFLIGHT.md: a status table — one row per check, status ✅ / ⚠️ / ❌, what was found, and the fix for anything not green — followed by a Ready / Ready-with-gaps / Not ready verdict per command:

assess + map + extract-rules — need Checks 1–2 green-ish and Check 4's missing-include count low
brief — needs only the three discovery artifacts; no tooling
transform + reimagine — additionally need Check 3 green for the target stack. A red legacy toolchain downgrades these to Ready-with-gaps, not Not-ready: equivalence testing falls back to recorded traces / golden-master fixtures instead of dual execution (common and expected for CICS/IMS code that has no local runtime)
harden — needs Check 2 plus any stack-specific SAST tooling found

Print the table in the session too, and end with the single most important fix if anything is red.

4.5 KiB Raw Blame History Unescape Escape