claude-plugins-official/modernize-preflight.md at 1c4a5cfded2cb2e4c8c5420ebd2f3974eb3fdd51

mirror of https://github.com/anthropics/claude-plugins-official.git synced 2026-06-13 22:26:03 -03:00

code-modernization: interactive topology map, preflight command, persona flows

modernize-map previously rendered the call graph and data lineage as
static Mermaid diagrams, which become unreadable once a node has ~10+
edges — exactly the shape of real legacy systems. It now builds an
interactive viewer from a shipped template (assets/topology-viewer.html):
a zoomable circle-pack of domains/modules sized by LOC, rendered to
canvas with level-of-detail reveal, dependency edges with per-kind
toggles, search with fly-to, a per-node detail sidebar, and a flow
walkthrough mode. Small domain-level .mmd exports remain for docs.

- topology.json now has a documented schema (hierarchy + edges + entry
  points + observations + flows) consumed by the viewer
- map traces 2-4 business flows anchored to personas (claimant,
  operator, auditor), each step in plain business language mapped to
  the modules that implement it; the viewer plays them as numbered
  paths
- brief gains a Business Walkthroughs section connecting each persona
  flow to the phase that replaces it
- new modernize-preflight command: detects the stack, checks analysis
  tooling, smoke-compiles a real source file with the legacy toolchain,
  inventories missing copybooks/descriptors/binary-only artifacts, and
  writes a per-command readiness verdict
- transform now verifies legacy + target toolchains before its plan
  gate instead of failing at test time
- README: commands updated, optional-tooling section reframed as 'what
  to give Claude'

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

4.1 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

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.

4.1 KiB Raw Blame History Unescape Escape