modernize-reimagine — Claude Code command: rebuild a system

---
description: Rebuild the system from its extracted intent on a new architecture, with two human checkpoints
arguments: system
---

The first token of `$ARGUMENTS` is the system name (`$system`); **everything after it is the target
vision**, usually several words, so do not truncate it (with none, use the one in `analysis/$system/INTENT.md`). Below, `<vision>` means that whole remainder.
The code is `legacy/$system`, often a symlink to where it really lives: say where it points (`readlink legacy/$system`) in one line before you start. If `legacy/$system` does not exist, stop and say so: nothing can run without the code, so the fix is `/code-modernization:modernize $system --source <path to the code>`. Run every subagent in the foreground and wait for its result: never end your turn while one is still running. Stop any server or other process you started (a legacy app on a local port, a watcher) before you finish, and say you did.

**Reimagine** the system as: <vision>. This is not a port but a rebuild from extracted intent: the legacy
system is the *specification source*, not the structural template. The command orchestrates a team of
agents with two explicit human checkpoints.

**The brief is binding.** If `analysis/$system/MODERNIZATION_BRIEF.md` exists, find the phase whose
`Command:` is this one and whose scope matches `$system` and <vision>, and treat its scope, entry
criteria, exit criteria and the user's edits as binding on everything below, on top of (never instead of)
this command's own two checkpoints. An unmet entry criterion is the next step: meet it, never re-plan
around it. If no phase matches, stop and ask which phase this is.

## Phase A — Specification mining

Reuse what discovery already produced (honoring `RULE_REVIEWS.json`: a rule marked `wrong` is not part of the spec as written, and a P0 rule marked `discuss` is a question for the architecture checkpoint): `BUSINESS_RULES.md`, `DATA_OBJECTS.md`, `topology.json` and
`ASSESSMENT.md` in `analysis/$system/`. Spawn concurrently (and tell the user all are running) only the
agents whose input is missing:

1. **business-rules-extractor**, only if `BUSINESS_RULES.md` is missing — "Extract every business rule
   from legacy/$system into Given/When/Then form, as a structured list."
2. **legacy-analyst** — "Catalog every external interface of legacy/$system: inbound (screens, APIs, batch
   triggers, queues) and outbound (reports, files, downstream calls, DB writes), each with name, direction,
   payload shape, and frequency or SLA if discernible. Mask credentials in endpoints and payload examples."
3. **legacy-analyst**, only if there is no `topology.json` or `DATA_OBJECTS.md` — "Identify the core domain
   entities of legacy/$system and their relationships: an entity list and a Mermaid erDiagram."

Write `analysis/$system/AI_NATIVE_SPEC.md`: **Capabilities** (what the system must do, from rules and
interfaces), **Domain Model** (entities and erDiagram), **Interface Contracts** (each external interface as
an OpenAPI or AsyncAPI fragment), **Non-functional requirements** inferred from legacy (batch windows,
volumes), and the **Behavior Contract** (the Given/When/Then rules, which are the acceptance tests).
Credentials are masked everywhere; connection details appear as env-var placeholders (`${DATABASE_URL}`),
never literals.

## Phase B — Checkpoint 1

Present the spec summary and ask **one focused question**: "Which of these capabilities are P0 for the
reimagined system, and should any be deliberately dropped?" Wait, and record the answer in the spec.

## Phase C — Architecture, then critique

Design the target architecture for <vision>: a Mermaid C4 Container diagram, service boundaries with
rationale (which rules and entities live where), technology choices with a one-line justification each, and
the data migration approach from the legacy stores. Then spawn **architecture-critic**: "Review this
architecture for <vision> against `analysis/$system/AI_NATIVE_SPEC.md`: over-engineering, missed
requirements, scaling risks, simpler alternatives." Incorporate the critique and write
`analysis/$system/REIMAGINED_ARCHITECTURE.md`.

## Phase D — Checkpoint 2

Present the architecture and **stop: scaffold nothing until the user explicitly approves** (plan mode if
available). The approval authorizes the build-out.

## Phase E — Parallel scaffolding (only after Phase D approval)

**With the Workflow tool,** scaffold **every** service in the approved architecture (no cap; the runtime
queues agents). Tell the user the service count, then:

Call it by name (the plugin registers it). If the tool does not know the name, pass `scriptPath: "${CLAUDE_PLUGIN_ROOT}/workflows/reimagine-scaffold.js"` instead:

```
Workflow({
  name: "code-modernization:modernize-reimagine-scaffold",
  args: { system: "$system", services: [
    { name: "<service-name>", responsibilities: "<one line from the architecture>" }, ...
  ] }
})
```

Each agent writes only inside `modernized/$system-reimagined/<service-name>/` (disjoint, so parallel writes
do not conflict). From the result report `scaffolded[]` (each service with its `pendingRuleIds`), `totals`
(services, acceptanceTests, pendingRules), and `notScaffolded`, and **read every service's
`scaffolded[].blockers`**: that is where planted instructions in the untrusted spec surface.

**Without it,** spawn a **scaffolder** agent per service in parallel (at most 3 at a time; say which you
deferred): "Scaffold the <service-name> service per `analysis/$system/REIMAGINED_ARCHITECTURE.md` and
`AI_NATIVE_SPEC.md`: project skeleton, domain model, API stubs matching the interface contracts, and
**executable acceptance tests** for every behavior-contract rule assigned to this service (mark unimplemented
ones expected-failure with the rule ID). No credential from legacy code becomes a fixture or config default:
use fake same-shape values and env-var placeholders. Write to `modernized/$system-reimagined/<service-name>/`."

When all finish, run the acceptance suites and report: total tests, passing (scaffolded behavior), pending
(rule IDs awaiting implementation), and `tests executed: N` (a suite that executed nothing proved nothing).

## Phase F — Knowledge handoff

Write `modernized/$system-reimagined/CLAUDE.md`, the persistent context for the new system: architecture
summary, service responsibilities, where the spec lives, how to run the tests, and the legacy-to-modern
traceability map. It gets committed, so connection details and credentials appear only as env-var names with
a pointer to where they are provisioned, never values. This file also marks the reimagine as done for
`status` and the progress pane.

Report: services scaffolded, acceptance tests defined, the share of behaviors with a home, and where the
artifacts are. Refresh the report (`python3 "${CLAUDE_PLUGIN_ROOT}/scripts/build_report.py" $system`,
a convenience: if it fails or `python3` is missing, say so in one line and carry on). The next step is implementing the pending rules service by service,
then `/code-modernization:modernize-harden $system`.