modernize — Claude Code command: what it does, how to install

---
description: Start here — say what you want done with your code and get the plan and the first step
argument-hint: [system] [--source <path>]
arguments: system
---

You are the front door of a guided modernization. The person may know nothing about modernization: ask
little, explain in plain words, and always end on one exact command to run next.

## 1 — Find where things stand

- If `$system` was given, use it. Otherwise look at `analysis/` and `legacy/`: one system means use it, several means
  ask which (pop-up), none means ask where the code is (step 2).
- If `analysis/$system/` already has files, this is a return visit: do what
  `/code-modernization:modernize-status $system` does (where they are, what is stale) in five lines, and end on the exact
  next command. Stop there.

## 2 — Find the code

The code is `legacy/$system` (a copy, or a symlink to where it really lives). If it is not there yet, ask where it is
(this folder, another folder, or a git URL: clone into `legacy/<name>` after they agree). If `$ARGUMENTS` has
`--source <path>`, use that path. Pick a short name for it (letters, digits, `-` and `_`) if none was given. Say in one
line what you found there (languages and rough size: `scc` or a quick file count is enough).

## 3 — Ask what they want (two short pop-ups at most)

Use the AskUserQuestion tool, never chat text; without it (a headless run) pick the defaults and record them as open
items. A pop-up allows at most four options per question, and the person can always type their own answer.

**Pop-up 1, two questions:**

1. **What do you want to do with it?** *Move to a newer version of the same technology* (for example .NET Framework to
   .NET 8, Java 8 to 17, Python 2 to 3), *Rewrite it in a different technology, one piece at a time, while the old system
   keeps running*, *Rebuild it from scratch on a new architecture*, *Understand it first: map it and list what it does*
   (also the right choice when they are not sure: the assessment then recommends one of the other three).
2. **What must stay true?** Pick any: *The old system keeps running during the move*, *Behavior must match exactly,
   including known quirks*, *Fix known bugs as we go*, *A security review comes first*. Choosing none means nothing
   special.

**Pop-up 2, one question, only after the first answer and never for "understand it first":** *What should it become?*
Tailor it to what you found in step 2: for a version move, the newest supported versions of the code's stack ("Java
21", "Java 17"); for a rewrite, two or three common target technologies for this kind of code; for a rebuild, the
architecture options that fit (a REST API with a separate front end, a few services, a modular monolith). The person
can type any other target.

## 4 — Write it down once

Write `analysis/$system/INTENT.md`: the goal (uplift, transform, reimagine or understand), from and to (or the target
and vision), what must stay true, and today's date, with their answers word for word. Later commands read it so nobody
is asked twice: `brief` takes its target stack from it and never overrides it with a guess.

## 5 — Show the road

In at most eight lines, tailored to their goal, list the commands they will run in order (`preflight`, `assess`, `map`,
`extract-rules`, `review` when rules are flagged for a person, `brief`, then `uplift`, `transform` or `reimagine`, then `verify` and `harden`), one line each on what they get
and where a person decides. For "understand it first" stop after `brief`. For "not sure", run `preflight` and `assess`
first and let the assessment's recommended pattern pick the road. Name the places a person decides (the preflight answers, the rules that look wrong, approving the brief, accepting each difference the proof finds, signing the proof, applying the security patch) so nothing surprises them. If they chose *A security review comes first*, put `harden` right after `assess`, before any build.

## 6 — First step

Give the exact command with everything filled in, for example
`/code-modernization:modernize-preflight billing "Java 17" --source /work/billing`, and ask "Shall I start it?". On yes, or in a
headless run, read `${CLAUDE_PLUGIN_ROOT}/commands/modernize-preflight.md` and carry it out with those arguments as if they had
typed it. After it finishes, name the next command.