Stack Modernization
Keep a project on current, minimal, idiomatic dependencies. Three jobs: upgrade what
is behind, delete what is unused, and migrate patterns a major upgrade left stranded
(the v3 config still sitting in a v4 repo). Edits package.json and source, so it
runs behind a confirmation gate and verifies before it upgrades.
Never trust training data for a version number — the current latest is looked up, not recalled.
Authorized Scope
Apply this engine only within the user's requested task and existing explicit authorization. Loading or delegating to it grants no additional authority. Preserve report-only restrictions and the caller's target, host, provider, and cost limits. Existing approval satisfies a gate only for the same actions and scope; obtain approval before expanding them. Forward these limits to delegates.
Contract
Inputs:
- A repo; optional focus (
deps/dead/patterns/all, defaultall).
Outputs:
- A modernization plan (per package: current → latest, risk, migration notes), then applied upgrades with tests passing between steps.
Creates/Modifies:
- Edits
package.json, lockfile, and source during pattern migration. Only after the plan is approved.
External Side Effects:
buninstall/upgrade commands;WebSearchto confirm latest versions. No deploys.
Confirmation Required:
- Before applying any upgrade or removal. Show the plan first.
- Before a major-version bump with a migration cost — call it out explicitly.
Delegates To:
refactor-codewhen a migration is a real code refactor, not a mechanical swap.dependency-auditfor the security/CVE angle (this skill is about currency, that one about vulnerability).
Step 1 — Inventory
bun outdated # what is behind, and by how much (patch / minor / major)
bun pm ls # installed tree
# Dead/unused packages: run knip or depcheck if present; else grep imports per dep.
Also flag framework-pattern drift — a stale lockfile or config alongside a newer major:
npm/yarn/pnpmlockfiles or install commands in a Bun project.- A
tailwind.config.{js,ts}or@apply/@tailwinddirectives in a Tailwind v4 project (v4 configures in the CSS@themeblock). middleware.tswhere the framework's current major expectsproxy.ts.- Deprecated APIs the installed major has replaced (check the package's migration guide).
Step 2 — Verify latest before proposing
For each candidate upgrade, confirm the current latest with WebSearch (npm/GitHub
releases) — do not use a version from memory. Note the target major and whether the
package publishes a breaking-change / migration guide.
Step 3 — Plan
## Stack Modernization Plan — <repo>
### Upgrade
| Package | Current | Latest | Jump | Migration |
|---------|---------|--------|------|-----------|
| <name> | x.y.z | a.b.c | major/minor/patch | <link or "none"> |
### Remove (unused)
- <package> — no imports found
### Pattern migration
- <stale pattern> → <current pattern>
Order the work: security/patch and minor upgrades first (low risk), then majors with migrations one at a time, then dead-package removal, then pattern migration.
Step 4 — Apply incrementally
One change at a time; tests between each so a regression is attributable:
bun add <pkg>@<verified-latest> # or `bun remove <pkg>` for dead deps
bun run type-check || bunx tsc --noEmit
bun run test <affected-area>
Commit each successful step so any failure rolls back cleanly. For a major with a migration guide, follow it explicitly rather than guessing the new API.
Anti-Patterns
- Upgrading to a version from memory. Always verify the current latest first — training data is stale for version numbers.
- A big-bang upgrade of everything at once. One package (or one coherent group) at a time, tests between, so a break is traceable.
- Bumping a major without reading its migration guide — the breaking changes are the whole point of the major.
- Removing a package on a missing import alone — check for dynamic imports, config references, and peer-dependency roles before deleting.
- Reintroducing npm/yarn — this project uses Bun; upgrades go through
bun add.