/codebase-modernizer

name: codebase-modernizer
description: "Audit a stale, inherited, or messy codebase — deps, bugs, security, tests, CI, docs, UI/UX — then emit a phased, testable modernization plan. Read-only: plans upgrades, never applies them. Not for single-PR review, PRD-to-tasks, or UX-only audits."
license: MIT
effort: max
dependencies:
  - code-review
  - dont-make-me-think
metadata:
  version: 1.4.1
  author: "Luong NGUYEN <luongnv89@gmail.com>"
  architecture: "orchestrator (baseline gate → parallel dimension audits → evidence report → phased sprint plan → validation)"

Codebase Modernizer

For a codebase you are returning to after a long gap, or one that has drifted through many unoptimized changes. It audits every applicable dimension, then converts the findings into a **phased, sprint-sized, testable plan** for a better, up-to-date version.

Produces exactly two files in the target repo root:

| File | Contents | |---|---| | `MODERNIZATION_REPORT.md` | Baseline evidence + every finding, severity-ranked, each citing `path:line` | | `MODERNIZATION_PLAN.md` | Phases → sprints → tasks → milestones, every task closing named findings |

Read-only contract

This skill **never modifies source code, dependencies, lockfiles, or configuration** — no tracked file's content changes. On a clean tree that is `git diff --stat` empty. On a stale, already-dirty tree, `git status --porcelain` and `git diff` after the run must match a snapshot taken before it (declared artifacts set aside). Beyond the two reports, only two kinds of *new* file may appear, both enumerated in the report's Artifacts section: a **declared delegate artifact** (`CODE_REVIEW.md`, from `code-review` mode `review`) and **probe byproducts** (build dirs such as `obj/`, `.dart_tool/`, `target/`, `.gradle/`). Nothing else.

• Dependency upgrades become **planned tasks with migration steps** — never `npm update`, `ncu -u`,

`cargo update`, `poetry update`, or any equivalent. A blind bulk upgrade on a stale tree produces a broken build and an unreviewable diff, which is exactly what the plan exists to prevent.

• Refactors, dead-code removal, and test generation are **planned**, not applied. Applying them is

the delegate skills' job, run later against the plan.

• Agent environment files (`CLAUDE.md`, `AGENTS.md`) are **planned** via `/agent-config create` or

`/agent-config update` in the plan's Pre step — never created or rewritten during the audit.

• If the user asks mid-run to start fixing, finish the report and plan first, then hand off to the

delegate skill named in that task.

Dependency Preflight (mandatory)

This skill **invokes** the two skills declared in frontmatter `dependencies`: `code-review` (modes `review` and `perf`, for `BUG` and `PERF`) and `dont-make-me-think` (`UX`). Run this before Phase 0, the first phase that probes anything. Discovery acquires nothing:

if command -v asm >/dev/null && asm deps --help >/dev/null 2>&1; then
  asm deps discover codebase-modernizer --json || echo "discover failed; acquire at first use" >&2
  printf 'cm_session=%s\n' "codebase-modernizer-$(date +%s)-$$"   # record it; reuse it verbatim
else
  echo "asm deps unavailable: npm install -g agent-skill-manager@latest" >&2
fi

1. If the block prints `asm deps unavailable`, record every delegated dimension **Not Assessed — skill unavailable**, skip steps 2–5, and continue. 2. When Phase 2 first reaches `BUG` or `PERF`, run `asm deps acquire code-review --session <cm_session> --json`. When it first reaches `UX`, run the same command for `dont-make-me-think`. Never acquire for a dimension that is Not Assessed. 3. If the acquire exits 0, pass its returned `skillMdPath` to the dimension worker as `delegate_skill_md`. Read that path directly. 4. If the acquire exits non-zero, print the install hint in `references/delegation-policy.md` (*Missing dependency*). Record **Not Assessed — skill unavailable** for `BUG` and `PERF` (`code-review`) or `UX` (`dont-make-me-think`), continue, and name it in Limitations. A missing dependency is **fail-soft**, not fatal. 5. **Release in `finally`.** If any acquire ran, run `asm deps release --session <cm_session> --json` once at every terminal outcome (after Phase 5, on a stop, or on an error), before the final report. Put a failed release under `Uncertainty:`.

Lease-owned copies live outside the target repo, so they are not target artifacts. The six *inline* dimensions name their skill in a plan task and never invoke it, so they need no dependency entry.

Leading terms

Used throughout this skill and its references with these exact meanings:

• **baseline-green** — the recorded state where the project builds and its test suite runs to a known

pass rate. Established in Phase 0; every P0–P4 task must assert it still holds. Pre is exempt when the baseline is RED — restore-green stays on P0 / Sprint 0.

• **finding record** — one normalized issue row with a stable **finding ID** (`F-<DIM>-<NNN>`, e.g.

`F-DEP-003`). The report lists them; the plan's tasks close them by ID.

• **Not Assessed** — an explicit report verdict for a dimension that could not be checked (no tool,

no UI, no network). Never replaced by a guess.

• **fail-soft** — probe whether a tool exists before using it; on absence, record **Not Assessed**

with the reason and continue. A missing tool never aborts the run.

• **upgrade wave** — one batch of dependency upgrades that ships and is verified together:

security patches → patch/minor batch → each major on its own.

Repo Sync Before Edits (mandatory)

**Default: do not sync.** This skill merges nothing and commits nothing — it writes two untracked report files. Rebasing mid-audit can pull in a year of upstream commits, invalidating every `path:line` citation and the recorded SHA. Audit the tree as you found it.

**Sync only when the user asks for the reports committed or pushed.** Then sync at the *start* of Phase 3, after the aud