From nexus-agents
Plans and executes removal of deprecated APIs without breaking consumers. Includes pre-removal checklist, blast radius decomposition, and step-by-step migration process.
How this skill is triggered — by the user, by Claude, or both
Slash command
/nexus-agents:deprecation-and-migrationThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!--
@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).
npx claudepluginhub nexus-substrate/nexus-agentsManages deprecation and migration of old systems, APIs, or features. Guides removal of legacy code, sunsetting features, consolidating duplicates, and lifecycle planning.
Guides deprecation and migration: removing old systems, APIs, or features and migrating users to new implementations.
Plans and executes deprecation lifecycle for design system components, tokens, patterns: audits usage via grep, sets timelines, migration paths, communication plans, multi-phase removal.