Codebase Modernizer

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:

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 audit is recorded. Because HEAD moves, re-record the commit SHA and re-verify every citation. If any citation no longer resolves, stop with Result: BLOCKED — audit stale after sync and re-run the audit.

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

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 branch in the workflow, not a preference. Check these two first, because they change what is obtainable at all:

• No Bash → record the whole baseline Not Assessed — no shell, audit only what static reading supports, and never fabricate a verdict.
• No UI detected → UI/UX dimensions are Not Assessed — no UI detected. Never invent UX findings.

If a branch was not checked, take its restrictive side.

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.

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

• Invoked (BUG, PERF, UX) — normalize the output into finding records and record Path: delegated. Never let dont-make-me-think enter its Redesign Mode, which edits UI source files.
• Inline (CLEAN, DEAD, TEST, CI, SEC, DOCS) — these delegates write, so never invoke one during the audit. Audit the dimension with its checklist in references/dimension-map.md, record Path: inline, and name that skill in the plan task. inline is the expected path, not a degradation.

Read references/delegation-policy.md before Phase 2. It holds the invocation args, the CODE_REVIEW.md declared-artifact handling, the review-only rule for dont-make-me-think, the /agent-config Pre-step rule, and the Skill-tool-unavailable fallback (which is reduced depth).

Workflow

Phase 0 — Baseline (gate)

Follow references/baseline.md. Record each of these with the command that produced it: build status, test command and pass rate, coverage if obtainable, lint status, CI presence and last 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.

Probes must not mutate tracked files. A tracked file a probe changes is a finding. The snapshot procedure and the no-test-command fallback are in references/baseline.md (Phase 0 rules: tracked files and the no-test-command fallback).

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: each of the 10 dimensions marked audit or Not Assessed + reason. If a requested area maps to no dimension ID, or to more than one, ask the user once which to audit. Otherwise proceed without asking.

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.