Fix code-modernization plugin: align README with commands, fix pipeline gaps

- modernize-brief: read TOPOLOGY.html (what modernize-map actually
  produces) instead of nonexistent TOPOLOGY.md, and tell the user which
  command produces each missing input.
- README: rewrite the Commands section to match actual command behavior —
  correct output filenames, ordering (brief is the synthesis/approval gate
  after discovery, not the first step), agent attributions, and required
  args. Add a workspace-layout note and an explicit callout that
  modernize-harden edits legacy/, which conflicts with the recommended
  deny rule. Reconcile the Overview and Typical Workflow sequences.
- modernize-assess: generalize the production-runtime overlay step so it
  no longer assumes a specific MCP server/tool; mark it optional. Fix
  app/jcl/ -> legacy/$1/jcl/ for layout consistency.
- modernize-map: make TOPOLOGY.html self-contained (load Mermaid from a
  CDN) so it renders in any browser; drop assumptions about an external
  artifact renderer. Generalize the telemetry annotation note.
- business-rules-extractor agent: fix command cross-reference to the
  actual command name.
- plugin.json: include the brief step in the workflow description.

plugins/code-modernization/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-modernization",
-  "description": "Modernize legacy codebases (COBOL, legacy Java/C++, monolith web apps) with a structured assess → map → extract-rules → reimagine → transform → harden workflow and specialist review agents",
+  "description": "Modernize legacy codebases (COBOL, legacy Java/C++, monolith web apps) with a structured assess → map → extract-rules → brief → reimagine/transform → harden workflow and specialist review agents",
   "author": {
     "name": "Anthropic",
     "email": "support@anthropic.com"

plugins/code-modernization/README.md

@@ -7,43 +7,49 @@ A structured workflow and set of specialist agents for modernizing legacy codeba
 Legacy modernization fails most often not because the target technology is wrong, but because teams skip steps: they transform code before understanding it, reimagine architecture before extracting business rules, or ship without a harness that would catch behavior drift. This plugin enforces a sequence:
 
 ```
-assess → map → extract-rules → reimagine → transform → harden
+assess → map → extract-rules → brief → reimagine | transform → harden
 ```
 
-Each step has a dedicated slash command. Specialist agents (legacy analyst, business rules extractor, architecture critic, security auditor, test engineer) are invoked from within those commands — or directly — to keep the work honest.
+The discovery commands (`assess`, `map`, `extract-rules`) build artifacts under `analysis/<system>/`. The `brief` command synthesizes them into an approval gate. The build commands (`reimagine`, `transform`) write new code under `modernized/`. The `harden` command audits and patches the legacy system. Each step has a dedicated slash command, and specialist agents (legacy analyst, business rules extractor, architecture critic, security auditor, test engineer) are invoked from within those commands — or directly — to keep the work honest.
+
+## Expected layout
+
+Commands assume the system being modernized lives at `legacy/<system-dir>/`. Discovery artifacts go to `analysis/<system-dir>/`, transformed code to `modernized/<system-dir>/…`. Adjust the paths in the commands or symlink if your layout differs.
 
 ## Commands
 
 The commands are designed to be run in order, but each produces a standalone artifact so you can stop, review, and resume.
 
-### `/modernize-brief`
-Capture the modernization brief: what's being modernized, why now, constraints (regulatory, data, runtime), non-goals, and success criteria. Produces `analysis/brief.md`. Run this first.
+### `/modernize-assess <system-dir>`  — or — `/modernize-assess --portfolio <parent-dir>`
+Inventory the legacy codebase: languages, line counts, complexity, build system, integrations, technical debt, security posture, documentation gaps, and a COCOMO-derived effort estimate. Produces `analysis/<system>/ASSESSMENT.md` and `analysis/<system>/ARCHITECTURE.mmd`. Spawns `legacy-analyst` (×2) and `security-auditor` in parallel for deep reads. With `--portfolio`, sweeps every subdirectory of a parent directory and writes a sequencing heat-map to `analysis/portfolio.html`.
 
-### `/modernize-assess`
-Inventory the legacy codebase: languages, line counts, module boundaries, external integrations, build system, test coverage, known pain points. Produces `analysis/assessment.md`. Uses the `legacy-analyst` agent for deep reads on unfamiliar dialects.
+### `/modernize-map <system-dir>`
+Build a dependency and topology map of the **legacy** system: program/module call graph, data lineage (programs ↔ data stores), entry points, dead-end candidates, and one traced critical-path business flow. Writes a re-runnable extraction script and produces `analysis/<system>/TOPOLOGY.html` (rendered Mermaid + architect observations) plus standalone `call-graph.mmd`, `data-lineage.mmd`, and `critical-path.mmd`.
 
-### `/modernize-map`
-Map the legacy structure onto a target architecture: which legacy modules become which target services/packages, data-flow diagrams, migration sequencing. Produces `analysis/map.md`. Uses the `architecture-critic` agent to pressure-test the design.
+### `/modernize-extract-rules <system-dir> [module-pattern]`
+Mine the business rules embedded in the legacy code — calculations, validations, eligibility, state transitions, policies — into Given/When/Then "Rule Cards" with `file:line` citations and confidence ratings. Spawns three `business-rules-extractor` agents in parallel (calculations, validations, lifecycle). Produces `analysis/<system>/BUSINESS_RULES.md` and `analysis/<system>/DATA_OBJECTS.md`.
 
-### `/modernize-extract-rules`
-Extract business rules from the legacy code — the rules that are encoded in procedural logic, COBOL copybooks, stored procedures, or config files — into human-readable form with citations back to source. Produces `analysis/rules.md`. Uses the `business-rules-extractor` agent.
+### `/modernize-brief <system-dir> [target-stack]`
+Synthesize the discovery artifacts into a phased **Modernization Brief** — the single document a steering committee approves and engineering executes: target architecture, strangler-fig phase plan with entry/exit criteria, behavior contract, validation strategy, open questions, and an approval block. Reads `ASSESSMENT.md`, `TOPOLOGY.html`, and `BUSINESS_RULES.md` and **stops if any are missing** — run the discovery commands first. Produces `analysis/<system>/MODERNIZATION_BRIEF.md` and enters plan mode as a human-in-the-loop gate.
 
-### `/modernize-reimagine`
-Propose the target design: APIs, data model, runtime. Explicitly list what changes from legacy and what stays identical. Produces `analysis/design.md`. Uses the `architecture-critic` agent to challenge over-engineering.
+### `/modernize-reimagine <system-dir> <target-vision>`
+Greenfield rebuild from extracted intent rather than a structural port. Mines a spec (`analysis/<system>/AI_NATIVE_SPEC.md`), designs a target architecture and has it adversarially reviewed (`analysis/<system>/REIMAGINED_ARCHITECTURE.md`), then **scaffolds services with executable acceptance tests** under `modernized/<system>-reimagined/` and writes a `CLAUDE.md` knowledge handoff for the new system. Two human-in-the-loop checkpoints. Spawns `business-rules-extractor`, `legacy-analyst` (×2), `architecture-critic`, and general-purpose scaffolding agents.
 
-### `/modernize-transform`
-Do the actual code transformation — module by module. Writes to `modernized/`. Pairs each transformed module with a test suite that pins the pre-transform behavior.
+### `/modernize-transform <system-dir> <module> <target-stack>`
+Surgical, single-module strangler-fig rewrite. Plans first (HITL gate), then writes characterization tests via `test-engineer`, then an idiomatic target implementation under `modernized/<system>/<module>/`, proves equivalence by running the tests, and produces `TRANSFORMATION_NOTES.md` mapping legacy → modern with deliberate deviations called out. Reviewed by `architecture-critic`.
 
-### `/modernize-harden`
-Post-transform review pass: security audit, test coverage, error handling, observability. Uses `security-auditor` and `test-engineer` agents. Produces a findings report ranked Blocker / High / Medium / Nit.
+### `/modernize-harden <system-dir>`
+Security hardening pass on the **legacy** system: OWASP/CWE scan, dependency CVEs, secrets, injection. Spawns `security-auditor`. Produces `analysis/<system>/SECURITY_FINDINGS.md` ranked Critical / High / Medium / Low, then **patches Critical and High findings directly in `legacy/<system>/`** and re-scans to verify. Useful as a pre-modernization step when the legacy system will keep running in production during the migration.
+
+> **Note:** `/modernize-harden` is the one command that edits `legacy/`. If you adopt the `deny: Edit(legacy/**)` workspace setting below, relax it for this command — or run hardening as a separate workstream against its own checkout.
 
 ## Agents
 
-- **`legacy-analyst`** — Reads legacy code (COBOL, legacy Java/C++, procedural PHP, classic ASP) and produces structured summaries. Good at spotting implicit dependencies, copybook inheritance, and "JOBOL" patterns (procedural code wearing a modern syntax).
-- **`business-rules-extractor`** — Extracts business rules from procedural code with source citations. Each rule includes: what, where it's implemented, which conditions fire it, and any corner cases hidden in data.
-- **`architecture-critic`** — Adversarial reviewer for target architectures and transformed code. Default stance is skeptical: asks "do we actually need this?" Flags microservices-for-the-resume, ceremonial error handling, abstractions with one implementation.
-- **`security-auditor`** — Reviews transformed code for auth, input validation, secret handling, and dependency CVEs. Tuned for the kinds of issues that appear when translating security primitives across stacks (e.g., session handling from servlet to stateless JWT).
-- **`test-engineer`** — Audits test suites for behavior-pinning vs. coverage-theater. Flags tests that exercise code paths without asserting outcomes.
+- **`legacy-analyst`** — Reads legacy code (COBOL, legacy Java/C++, procedural PHP, classic ASP) and produces structured summaries. Good at spotting implicit dependencies, copybook inheritance, and "JOBOL" patterns (procedural code wearing a modern syntax). Used by `assess` and `reimagine`.
+- **`business-rules-extractor`** — Extracts business rules from procedural code with source citations. Each rule includes: what, where it's implemented, which conditions fire it, and any corner cases hidden in data. Used by `extract-rules` and `reimagine`.
+- **`architecture-critic`** — Adversarial reviewer for target architectures and transformed code. Default stance is skeptical: asks "do we actually need this?" Flags microservices-for-the-resume, ceremonial error handling, abstractions with one implementation. Used by `reimagine` and `transform`.
+- **`security-auditor`** — Reviews code for auth, input validation, secret handling, and dependency CVEs. Tuned for the kinds of issues that appear when translating security primitives across stacks (e.g., session handling from servlet to stateless JWT). Used by `assess` and `harden`.
+- **`test-engineer`** — Writes characterization, contract, and equivalence tests that pin legacy behavior so transformation can be proven correct. Flags tests that exercise code paths without asserting outcomes. Used by `transform`.
 
 ## Installation
 
@@ -75,31 +81,31 @@ This plugin ships commands and agents, but modernization projects benefit from a
 }
 ```
 
-Adjust `legacy/` and `modernized/` to match your actual layout. The key invariants: `Edit` under `legacy/` is denied, and writes are scoped to `analysis/` (for documents) and `modernized/` (for the new code).
+Adjust `legacy/` and `modernized/` to match your actual layout. The key invariants: `Edit` under `legacy/` is denied, and writes are scoped to `analysis/` (for documents) and `modernized/` (for the new code). The exception is `/modernize-harden`, which intentionally patches `legacy/` — see its note above.
 
 ## Typical Workflow
 
 ```bash
-# 1. Write the brief — what are we modernizing and why?
-/modernize-brief
+# 1. Inventory the legacy system (or sweep a portfolio of them)
+/modernize-assess billing
 
-# 2. Inventory the legacy code
-/modernize-assess
+# 2. Map call graph, data lineage, and the critical path
+/modernize-map billing
 
-# 3. Extract business rules before touching the code
-/modernize-extract-rules
+# 3. Extract business rules into testable Rule Cards
+/modernize-extract-rules billing
 
-# 4. Map legacy structure to target
-/modernize-map
+# 4. Synthesize the approved Modernization Brief (human-in-the-loop gate)
+/modernize-brief billing java-spring
 
-# 5. Propose the target design and review it
-/modernize-reimagine
+# 5a. Greenfield rebuild from the extracted spec…
+/modernize-reimagine billing "event-driven services on Java 21 / Spring Boot"
 
-# 6. Transform module by module
-/modernize-transform
+# 5b. …or transform module by module (strangler fig)
+/modernize-transform billing interest-calc java-spring
 
-# 7. Harden: security, tests, observability
-/modernize-harden
+# 6. Security-harden the legacy system that's still in production
+/modernize-harden billing
 ```
 
 ## License

plugins/code-modernization/agents/business-rules-extractor.md

@@ -42,5 +42,5 @@ of the technology, skip it.
 
 ## Output format
 
-One "Rule Card" per rule (see the format in the modernize:extract-rules
+One "Rule Card" per rule (see the format in the `/modernize-extract-rules`
 command). Group by category. Lead with a summary table.

plugins/code-modernization/commands/modernize-assess.md

@@ -99,20 +99,21 @@ Spawn three subagents **concurrently** using the Task tool:
 
 Wait for all three. Synthesize their findings.
 
-## Step 4 — Production runtime overlay (observability)
+## Step 4 — Production runtime overlay (optional)
 
-If the system has batch jobs (e.g. JCL members under `app/jcl/`), call the
-`observability` MCP tool `get_batch_runtimes` for each business-relevant
-job name (interest, posting, statement, reporting). Use the returned
-p50/p95/p99 and 90-day series to:
+If production telemetry is available — an observability/APM MCP server, batch
+job logs, or runtime exports the user can supply — gather p50/p95/p99
+wall-clock for the system's key jobs/transactions (e.g. JCL members under
+`legacy/$1/jcl/`, scheduled batches, top API routes). Use it to:
 
 - Tag each functional domain from Step 3 with its production wall-clock
   cost and **p99 variance** (p99/p50 ratio).
 - Flag the highest-variance domain as the highest operational risk —
   this is telemetry-grounded, not a static-analysis opinion.
 
-Include a small **Batch Runtime** table (Job · Domain · p50 · p95 · p99 ·
-p99/p50) in the assessment.
+Include a small **Runtime Profile** table (Job/Route · Domain · p50 · p95 ·
+p99 · p99/p50) in the assessment. If no telemetry is available, skip this
+step and note the gap in the assessment.
 
 ## Step 5 — Documentation gap analysis
 
@@ -126,7 +127,7 @@ Create `analysis/$1/ASSESSMENT.md` with these sections:
 - **Executive Summary** (3-4 sentences: what it is, how big, how risky, headline recommendation)
 - **System Inventory** (the scc table + tech fingerprint)
 - **Architecture-at-a-Glance** (the domain table; reference the diagram)
-- **Production Runtime Profile** (the batch-runtime table from Step 4, with the highest-variance domain called out)
+- **Production Runtime Profile** (the runtime table from Step 4 with the highest-variance domain called out — or "no telemetry available")
 - **Technical Debt** (top 10, ranked)
 - **Security Findings** (CWE table)
 - **Documentation Gaps** (top 5)

plugins/code-modernization/commands/modernize-brief.md

@@ -8,8 +8,10 @@ single document a steering committee approves and engineering executes.
 
 Target stack: `$2` (if blank, recommend one based on the assessment findings).
 
-Read `analysis/$1/ASSESSMENT.md`, `TOPOLOGY.md`, and `BUSINESS_RULES.md` first.
-If any are missing, say so and stop.
+Read `analysis/$1/ASSESSMENT.md`, `analysis/$1/TOPOLOGY.html` (and the `.mmd`
+files alongside it), and `analysis/$1/BUSINESS_RULES.md` first. If any are
+missing, say so and stop — they come from `/modernize-assess`, `/modernize-map`,
+and `/modernize-extract-rules` respectively. Run those first.
 
 ## The Brief
 

plugins/code-modernization/commands/modernize-map.md

@@ -28,14 +28,22 @@ re-run and audited. Run it. Show the raw output.
 ## Render
 
 From the extracted data, generate **three Mermaid diagrams** and write them
-to `analysis/$1/TOPOLOGY.html` so the artifact pane renders them live.
+to `analysis/$1/TOPOLOGY.html` as a self-contained page that renders in any
+browser.
 
 The HTML page must use: dark `#1e1e1e` background, `#d4d4d4` text,
 `#cc785c` for `<h2>`/accents, `system-ui` font, all CSS **inline** (no
-external stylesheets). Each diagram goes in a
-`<pre class="mermaid">...</pre>` block — the artifact server loads
-mermaid.js and renders client-side. Do **not** wrap diagrams in
-markdown ` ``` ` fences inside the HTML.
+external stylesheets). Load Mermaid from a CDN in `<head>`:
+
+```html
+<script type="module">
+  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+  mermaid.initialize({ startOnLoad: true, theme: 'dark' });
+</script>
+```
+
+Each diagram goes in a `<pre class="mermaid">...</pre>` block. Do **not**
+wrap diagrams in markdown ` ``` ` fences inside the HTML.
 
 1. **`graph TD` — Module call graph.** Cluster by domain (use `subgraph`).
    Highlight entry points in a distinct style. Cap at ~40 nodes — if larger,
@@ -46,9 +54,9 @@ markdown ` ``` ` fences inside the HTML.
 
 3. **`flowchart TD` — Critical path.** Trace ONE end-to-end business flow
    (e.g., "monthly billing run" or "process payment") through every program
-   and data store it touches, in execution order. If the `observability`
-   MCP server is connected, annotate each batch step with its p50/p99
-   wall-clock from `get_batch_runtimes`.
+   and data store it touches, in execution order. If production telemetry is
+   available (see `/modernize-assess` Step 4), annotate each step with its
+   p50/p99 wall-clock.
 
 Also export the three diagrams as standalone `.mmd` files for re-use:
 `analysis/$1/call-graph.mmd`, `analysis/$1/data-lineage.mmd`,
@@ -63,4 +71,4 @@ touched by too many writers.
 
 ## Present
 
-Tell the user to open `analysis/$1/TOPOLOGY.html` in the artifact pane.
+Tell the user to open `analysis/$1/TOPOLOGY.html` in a browser.