From nexus-agents
Plans and executes removal of deprecated APIs without breaking consumers, via inventory, checklists, grep audits, and batched semver migrations.
npx claudepluginhub williamzujkowski/nexus-agentsThis skill is limited to using the following tools:
<!--
Guides deprecation and migration of systems, APIs, features, and code. Use when removing old implementations, migrating users, or deciding to maintain or sunset.
Plans and executes deprecation lifecycle for design system components, tokens, patterns: audits usage via grep, sets timelines, migration paths, communication plans, multi-phase removal.
Refactors code by removing backward compatibility shims, legacy layers, and feature flags. Use for modernizing APIs, clearing migration debt, or cleanup.
Share bugs, ideas, or general feedback.
@deprecated-marked APIsSkip when:
@deprecated marker has been in at least one published release for ≥ 1 minor version. Multi-month bake is preferred for typed APIs.CLAUDE.md / docs/.grep -rn for the deprecated symbol outside the package; check src/exports/*.ts to know if it's truly public or internal-only.List every surface touched by the removal — types, schemas, classes, function names, internal callers, public re-exports, test fixtures, doc references.
# Symbol reach
grep -rn "DeprecatedName" src/ --include="*.ts" | wc -l
# Public-barrel check
grep -rn "DeprecatedName" src/exports/*.ts src/index.ts
# Doc references
grep -rn "DeprecatedName" docs/ skills/
A deprecation removal touching > ~10 files should be split into batches by blast radius:
| Batch | Scope | Semver |
|---|---|---|
| A — Internal-only | Fields/methods never on a public barrel; runtime semantics unchanged | patch |
| B — Typed string-unions | Public union member removal; runtime unchanged | minor |
| C — Public type aliases | Public-barrel type removal; runtime unchanged | minor |
| D — Runtime API | Method/function/return-type changes consumers observe at runtime | major |
Each batch is its own PR. Never bundle batches — the failure mode (one CI gate flake or revert) is much easier when batches are isolated.
main. Confirm git status is clean.pnpm typecheck — let the type errors guide you to every internal consumer.pnpm lint && pnpm typecheck && pnpm test..changeset/<issue>-batch-<X>-<name>.md with semver and migration recipe.docs/ for stale references (auto-regenerated docs like TypeDoc HTML refresh on next build).consensus_vote QA before merge per the standard protocol.npm view <pkg> version against package.json version.| Excuse | Counter |
|---|---|
| "It's deprecated, so just delete it" | Deprecation is a contract with consumers. The marker says "this still works, but plan to migrate." Removal needs replacement + bake + migration recipe. |
| "Nobody uses it" | Verify with grep and npm view <pkg> dist.shasum-then-search-on-sourcegraph if you must be sure. "Nobody uses it" without evidence is a guess. |
| "I'll fix the broken consumers later" | Internal callers should be migrated in the same PR as the removal. Deferring it puts you in a state where main doesn't compile. |
| "It's just a rename" | Renames of public types are TypeScript-typed-only breaks. Minor version. Migration recipe required. |
| "v3.0 will fix it" | (Per nexus-agents experience with epic #2368: this is often a way to indefinitely defer work. Re-evaluate the v-gate periodically — many v3-gated cleanups can ship as typed-only minor breaks once they bake.) |
| "The CHANGELOG will explain" | The CHANGELOG is read by maybe 5% of consumers. Migration recipes need to be self-discoverable from a TypeScript compile error pointing at the new symbol. |
.changeset/*.md file@deprecated bakesrc/exports/*.ts for public reach@deprecated usages of the symbol are migrated in the same PRgrep -rn confirms no remaining references in src/ (excluding the symbol's own definition file, which is being removed)src/exports/*.ts if it was exported there.changeset/<issue>-batch-<X>-<name>.md exists with correct semver bumppnpm typecheck, pnpm lint, pnpm test passconsensus_vote QA approved (architect + security at minimum)package.json version@deprecated doc references swept from docs/ (auto-regen handles docs/api/)Epic #2368 (2026-05-04) retired the v3.0 deprecation gate by shipping all 31 @deprecated markers in 2.x as 5 batches:
tech_lead AgentRole removal → minorLessons from that cycle informed this skill — including the publish-race that produced version-skip publishes (docs/ops/release-changeset-race.md).