v1.3.3 to v1.4.0

---

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

metadata:

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)

```bash

fi

```

## 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

When syncing, sync the current branch with remote — stash first if the tree is not clean:

```bash

git stash push -u -m "pre-sync" # only when `git status --porcelain` is non-empty

branch="$(git rev-parse --abbrev-ref HEAD)"

git fetch origin && git pull --rebase origin "$branch"

git stash pop # only if you stashed

```

If `origin` is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user

before continuing. A dirty tree is common on a neglected repo — never discard uncommitted work.

## Scope and branch selection

Resolve all nine branches in `references/scope-detection.md` **before Phase 0**. Each is a real

- **No UI detected** → UI/UX dimensions are **Not Assessed — no UI detected**. Never invent UX

findings.

## What this skill owns, and what it delegates

The finding-generators already exist. This skill's own contribution is **dependency and runtime

currency**, the **baseline gate**, and the **audit → plan bridge**. Everything else is delegated.

| Dim | Dimension | Audited by | Skip when |

|---|---|---|---|

| `DEP` | Dependency + runtime currency | **this skill** — `references/dependency-audit.md`, `scripts/dep_scan.sh` | no manifest found |

| `BUG` | Bugs, security holes, quality | **invoke** `code-review` mode `review` | never |

| `PERF` | Bottlenecks, leaks, algorithmic waste | **invoke** `code-review` mode `perf` | never |

| `UX` | Usability and UI flow | **invoke** `dont-make-me-think` | no UI detected |

| `CLEAN` | Readability vs Clean Code standards | inline — plan task runs `code-review` mode `clean` | never |

| `DEAD` | Dead code, duplication, slop, weak types | inline — plan task runs `code-review` mode `cleanup` | never |

| `TEST` | Untested branches and edge cases | inline — plan task runs `test-coverage` | never — an absent suite is itself a `Critical` finding |

| `CI` | Pipelines, pre-commit, quality gates | inline — plan task runs `devops-pipeline` | never |

| `SEC` | Secrets, dependency vulnerabilities | inline — plan task runs `security-setup` | never |

| `DOCS` | Docs drifted from code | inline — plan task runs `doc-manager` | never |

**Delegation policy — one rule: a delegate is invoked only if it changes no tracked file.**

## Workflow

### Phase 0 — Baseline (gate)

result, runtime/toolchain versions in use.

A **RED** baseline (does not build, tests do not run, there is no suite, or the build could not be

probed at all) does **not** stop the audit. Record `Baseline: RED`, continue, and make restoring

baseline-green the plan's Sprint 0 — nothing downstream is verifiable without it.

**Completion criteria:** every row of the baseline table in `references/baseline.md` holds a recorded

value or an explicit **Not Assessed** with a reason; the overall verdict is `GREEN`, `AMBER`, or

`RED`; every value cites the command that produced it.

### Phase 1 — Inventory and dimension selection

Detect stack, ecosystems, UI presence, repo size, and entry points. Produce the dimension worklist:

**Completion criteria:** all 10 dimensions have a disposition; every ecosystem with a manifest is

listed; repo-size branch and Agent-tool branch are both resolved and stated.

### Phase 2 — Dimension audits

**Read `references/delegation-policy.md` before invoking any delegated dimension.**

Run `DEP` first — its output feeds the plan's upgrade waves and often explains findings in other

- `DEP` uses `agents/dependency-auditor.md` and `references/dependency-audit.md`, one invocation per

ecosystem. All `DEP` findings share the `F-DEP-` prefix, so allocate each ecosystem a distinct

`id_start` (1, 101, 201, …) **before** spawning them; gaps in the numbering are fine, collisions

are not.

- All other dimensions use `agents/dimension-auditor.md` with that dimension's row from

`references/dimension-map.md`. Each has its own prefix and numbers from 1, so they need no ID

coordination.

- **No-fabrication rule:** every finding record cites `path:line` (or a manifest entry and version

for `DEP`), or it is dropped. A dimension that produced nothing citable is **Not Assessed**, not

"no issues found".

**Completion criteria:** every dimension marked *audit* in Phase 1 returned either ≥ 1 finding record

or an explicit "clean — checked X, found nothing" with the checks named; zero finding records lack

evidence; finding IDs are unique and follow `F-<DIM>-<NNN>`.

### Phase 3 — Write MODERNIZATION_REPORT.md

Merge all finding records into `MODERNIZATION_REPORT.md` using `references/report-template.md`.

Rank by severity: `Critical` → `High` → `Medium` → `Low`.

**Completion criteria:** the file exists at the repo root; it contains the baseline table, a

dimension coverage table showing all 10 dispositions, and the full finding table; every finding has

ID, dimension, severity, evidence, and fix direction; the counts in the summary equal the rows in the

table.

### Phase 4 — Write MODERNIZATION_PLAN.md

Spawn `agents/plan-architect.md` with the report path (or run it inline when the Agent tool is

unavailable). It writes `MODERNIZATION_PLAN.md` from `references/plan-template.md`, using the fixed

with that skill, plus a `Closes:` line naming finding IDs.

**Completion criteria:** Pre is present and ordered before P0; every `Critical` and `High` finding

is closed by ≥ 1 task; every task has ≥ 2 testable acceptance criteria; every P0–P4 task asserts

baseline-green still holds; the dependency table references only task IDs that exist and has no

cycles; the critical path is stated explicitly; Pre and each of P0–P4 have a milestone with a

measurable exit condition. `references/plan-template.md` carries the task-ID format, the Pre

create-vs-update rule, and the RED-baseline exemption.

### Phase 5 — Validation pass

**Completion criteria:** the validator has run at least twice when round 1 returned any `must-fix`;

zero unresolved `must-fix` items remain, or each survivor is recorded in Limitations with a reason.

## Step Completion Reports

After each phase, emit:

```text

◆ [Phase Name] (phase N of 5 — [context])

··································································

[Check 1]: √ pass

[Check 2]: × fail — [reason]

[Criteria]: √ N/M met

____________________________

Result: PASS | FAIL | PARTIAL

```

## Acceptance Criteria

artifact** (`CODE_REVIEW.md`), or a probe byproduct listed in the report's Artifacts section.

## Expected Output

```text

```

## Edge Cases

## Reference files

- `references/scope-detection.md` — the nine scope branches, detection, and resolution order.

- `references/delegation-policy.md` — invocation args, artifact handling, fallbacks per path.

- `references/baseline.md` — Phase 0 probe protocol per stack, and the baseline evidence table.

- `references/dependency-audit.md` — per-ecosystem **fail-soft** probes, classification schema,

**upgrade wave** rules, and migration lookup for majors.

- `references/dimension-map.md` — the 10 dimensions: inline checklist, severity rubric, skip rules.

- `references/report-template.md` — report structure and the deduplication rule.

- `references/plan-template.md` — plan structure, task format, task-ID and Pre rules.

- `references/acceptance-criteria.md` — the full run checklist.

- `references/edge-cases.md` — the full edge-case list.

- `scripts/dep_scan.sh` — read-only ecosystem and dependency probe; prints a markdown summary.

Agents (spawn with the Agent tool; run inline if unavailable): `agents/dependency-auditor.md`

(`DEP`), `agents/dimension-auditor.md` (one delegated dimension per invocation),

`agents/plan-architect.md` (report → plan), `agents/plan-validator.md` (fresh-context validation).