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

---

description: Environment readiness check — analysis tools, build toolchain, source completeness, telemetry access

argument-hint: [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

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
• transform + reimagine — additionally need Check 3 green for both legacy and target stacks
• 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.