
vp-deps-shift
Dependency upgrade and library migration with breaking change detection and test-first verification
Install
/plugin install vp-deps-shift@vdustrRun it inside Claude Code after adding the marketplace with /plugin marketplace add VdustR/vp-claude-code-marketplace.
Contents
Discovered from sourceSkills 2
Dependency Migration
Replace one library with another, or migrate deprecated API patterns within the same library.
Quick Start
Replace moment.js with date-fns
Migrate from webpack to vite
Remove deprecated forwardRef usage (React 19)
Switch from lodash to es-toolkit
Migrate Vue Options API to Composition API
Scope
| Type | Example | Trigger |
|---|---|---|
| Library replacement | moment.js → date-fns | "replace X with Y" |
| API pattern migration | React 19 forwardRef removal | "remove deprecated X", "migrate to new Y API" |
Both types follow the same test-first workflow below.
Workflow
Non-linear execution: Phases are numbered for reference, not strict order. If findings in any phase invalidate earlier assumptions, restart from the affected phase.
Phase 1: Environment Analysis
- Detect package manager from lockfile (see package-managers.md)
- Detect monorepo structure
- Detect CI, hooks, changeset config (see repo-conventions.md)
- Detect test infrastructure (test runner, tsconfig.json, linter)
Phase 2: Identify Migration Target
For library replacement:
- Parse source library (to remove) and target library (to add)
- Detect current usage scope: grep for imports/requires of source library
- Count affected files and usage patterns
For API pattern migration:
- Identify deprecated/removed API pattern
- Scan all occurrences in codebase
- Identify the replacement pattern from docs
Phase 3: Documentation & Compatibility Analysis
Consult all sources (use subagents for parallel lookup when possible; see context7-integration.md):
- Context7 → Query both libraries for API comparison, migration guides
- Community resources → Search for known migration guides
- Code analysis → Map source API usage to target equivalents
Conflict resolution: If sources disagree on API equivalence or behavior, use the most conservative conclusion and flag the discrepancy.
Build an API mapping table:
| Source | Target | Notes |
|---|---|---|
moment().format('YYYY') | format(date, 'yyyy') | Different format tokens |
React.forwardRef((props, ref) => ...) | function Component({ ref, ...props }) | ref is now a regular prop |
See migration-patterns.md for methodology and common patterns.
Phase 3.5: Official Tools & Compat Layer Detection
Check for official/community migration tools before writing custom migrations:
For library replacement:
- Compat layer — e.g.,
es-toolkit/compatfor lodash- Ask user: "Use compat for gradual migration, or full replacement?"
- Compat-first: swap import paths → verify → optionally migrate to native API later
- Codemods — e.g.,
jscodeshifttransforms from library authors
For API pattern migration:
- Official codemods — e.g.,
npx react-codemod rename-unsafe-lifecycles - Framework CLI migration — e.g.,
npx @angular/cli update,npx storybook automigrate
Decision flow:
- Codemod exists → run codemod first, handle remaining manually
- Compat layer available → ask user preference (gradual vs full)
- Neither → proceed to Phase 4
Phase 3.7: Related Package Detection
For library replacement:
- Check if
@types/<source>exists → should be removed (scoped:@scope/pkg→@types/scope__pkg) - Check if target requires
@types/<target>or companion packages - For each related package found, also check for its
@types/counterpart (e.g., react-dom → @types/react-dom) - Check for related plugins/adapters referencing the source library
For API pattern migration:
- Usually no related packages needed, but check for community wrappers
Present findings and ask user whether to include.
Phase 4: Test-First Verification
Validate the migration approach before batch execution.
- Scan all usage — comprehensive grep for all patterns to migrate
- Write test diffs in /tmp — pick representative examples (not all files):
- Select 2-3 diverse usage patterns (simple, complex, edge case). If more than 10 distinct patterns exist, sample at least 30% and reflect actual coverage in the confidence index
- Create migrated versions in /tmp
- Run type check + tests against migrated snippets
Environment setup: Create a minimal/tmp/deps-shift-verify-<package>-<timestamp>/ ├── package.json # Minimal deps (target package only) ├── tsconfig.json # Copied from project, paths/aliases adjusted for /tmp ├── original/ # Copy of affected code snippets ├── migrated/ # Proposed migration applied └── test-runner.sh # Must run tsc --noEmit at minimum, must NOT be just exit 0package.json, install only the target package version fresh. Copy project'stsconfig.json; removepaths,baseUrl, andreferencesfields that point to project-specific locations — /tmp resolves modules through its ownnode_modulesonly. Never mutate the project's actualnode_modules. - Verify approach works before committing to full migration
- Pass → proceed to Phase 5
- Fail → iterate (max 3 attempts), then present failure analysis
Fallback: When tests can't be written → subagent 3-pass review loop:
- Pass 1 (Direct): correctness of API mapping, import resolution
- Pass 2 (Best Practice): idiomatic target library usage
- Pass 3 (Critical Think): edge cases, behavioral differences, risks
- Fix + loop until all passes clean
Phase 5: Migration Plan & Confidence Index
Present structured plan with confidence index:
- File-by-file change summary
- API mapping table (validated by Phase 4)
- Potential issues / no direct equivalent
- Confidence index with factor breakdown and boost options
- Repo convention actions
Always get user confirmation before executing.
Phase 6: Execute Migration
- Install target library (if library replacement)
- Apply transformations file by file using validated mapping
- Checkpoint: Verify all files have been transformed — grep for remaining source library imports. If any remain, do NOT proceed to removal
- Check for peer dependency conflicts — present options if found
- Clean up unused imports/types
- Clean up /tmp verification files
Note: Source library removal happens in Phase 8 after final verification passes. Do NOT remove it here — keeping it installed during verification ensures rollback is possible if issues are found.
Phase 7: Repo Convention Compliance
Detect and follow project conventions (see repo-conventions.md):
- Changesets → create changeset file
- Conventional commits → follow format
- CI checks → run matching local commands
- Pre-commit hooks → ensure hooks pass
- Custom scripts → run test, lint, typecheck
Phase 8: Final Verification
- Type check → 2. Lint → 3. Test suite → 4. Build
- For complex migrations: run subagent Pass 3 (Critical Think) as final quality gate
- After all checks pass: Remove source library from
package.json(if library replacement). If source is a transitive dep of other packages, it stays in lockfile — only remove the direct dependency - Run install to update lockfile after removal
- All pass → report success
- Failures → analyze if migration-related, attempt fix, present remaining to user (source library is still installed, so rollback is straightforward)
Guidelines
DO
- Build a complete API mapping table — map every source API to target equivalent before migrating
- Check for official codemods first — search npm registry and migration guides before writing custom transforms
- Offer compat layers when available — ask user preference (gradual vs full), never assume
- Test migration approach in /tmp first — validate on representative samples before batch
- Use Context7 for both libraries — query source and target library docs in parallel
- Handle "no equivalent" cases — ask user, implement custom wrapper, or document manual step
- Always confirm before execution — present migration plan, get user approval
- Follow repo conventions — detect and comply with changesets, commit format, CI checks
DON'T
- Skip codemod detection — always check for official tools first
- Skip test-first verification — never execute batch migration without validating approach
- Remove source library prematurely — verify all usage migrated before removing
- Assume API equivalence — subtle behavioral differences exist (async vs sync, shallow vs deep copy)
- Force migration when tests fail — present failure analysis, let user decide
- Assume compat layer preference — always ask user (gradual vs clean break)
- Migrate test files last — migrate tests alongside implementation to catch issues early
Error Handling
| Error | Action |
|---|---|
| No direct API equivalent found | Document gap, ask user for custom wrapper or alternative approach |
| Codemod crashes partway | Report progress, show transformed files, suggest manual completion |
| Context7 MCP tool not found | Suggest installation, continue with community guides + code analysis |
| Type errors after migration | Analyze if source/target type mismatch, suggest type assertion or wrapper |
| Behavioral difference detected | Flag to user with before/after examples, get approval |
| Tests still fail after 3 iterations | Present failure analysis, ask user how to proceed |
| /tmp write fails | Fall back to subagent review |
Reference Files
- package-managers.md — Detection matrix and commands
- repo-conventions.md — Convention detection and compliance
- confidence-index.md — Confidence index specification
- context7-integration.md — Context7 MCP detection and usage
- migration-patterns.md — Methodology and common patterns
Notes
- Requirements:
ghCLI (for releases API), package manager CLI - Context7: Optional but recommended; install through the current agent's plugin or MCP setup flow.
- Supported ecosystems: npm, pnpm, yarn, bun, cargo, pip/uv/poetry, go, bundler, composer
- Limitations: Private registry auth requires manual setup; no auto-handling of 2FA prompts
- Monorepos: Detected automatically, but user may need to specify target package for large workspaces
- Boundary: Use this skill when replacing one library with another or migrating API patterns. For version bumps (A v1 → A v2), use
deps-upgradeinstead.
Dependency Upgrade
Upgrade dependencies with breaking change detection, test-first verification, and repo convention compliance.
Quick Start
Upgrade react to v19
Handle the dependabot PR #42
Check for outdated dependencies
Auto-resolve the renovate PR https://github.com/owner/repo/pull/99
Workflow
Non-linear execution: Phases are numbered for reference, not strict order. If findings in any phase invalidate earlier assumptions, restart from the affected phase.
Phase 1: Environment Analysis
- Detect package manager from lockfile (see package-managers.md)
- Detect monorepo structure (workspaces, pnpm-workspace.yaml)
- Detect CI, hooks, changeset config (see repo-conventions.md)
Phase 2: Identify Upgrade Target
Three entry paths:
- A) User specifies package + version
- B) Bot PR → parse from PR title/body/diff (see deps-bot-handling.md)
- C) Bulk scan → run outdated command, present results
Determine update type:
| Type | Detection | Risk |
|---|---|---|
| Lockfile-only | New version within existing range | Low |
| Range update (minor) | Range change required, minor bump | Medium |
| Range update (major) | Range change required, major bump | High |
Phase 3: Documentation & Breaking Changes Analysis
Consult all sources (use subagents for parallel lookup when possible, not a fallback chain):
- Context7 →
resolve-library-id+query-docsfor migration guides (see context7-integration.md) - Changelog/releases → Parse CHANGELOG.md +
gh api repos/{owner}/{repo}/releases - Code changes → Analyze source code diffs for hidden breaking changes
Combine into a breaking changes report: High/Medium/Low impact, affected files (grep for deprecated APIs), migration action for each change. Conflict resolution: If sources disagree, use the most conservative (highest risk) conclusion and flag the discrepancy in the report.
Phase 3.5: Official Tools & Compat Layer Detection
Check for official/community migration tools before writing custom migrations:
| Source | What to look for | Example |
|---|---|---|
| Migration guide | Codemod CLI commands | npx react-codemod rename-unsafe-lifecycles |
| npm registry | *-codemod packages | @next/codemod, react-codemod |
| Target docs | Compat layer | es-toolkit/compat (lodash compatible) |
| Framework CLI | Auto-migration scripts | npx @angular/cli update |
Decision flow:
- Codemod exists → run codemod first, handle remaining manually
- Compat layer available → ask user: gradual (compat) or full replacement?
- Neither → proceed to Phase 4 (manual migration)
Phase 3.7: Related Package Detection
Detect packages that must be co-upgraded:
| Pattern | Detection | Example |
|---|---|---|
@types/ packages | Check devDeps for @types/<pkg> | react → @types/react |
Scoped @types/ | @scope/pkg → @types/scope__pkg | @babel/core → @types/babel__core |
| Peer dep ecosystem | Parse peerDependencies | react → react-dom |
| Peer dep types | For each peer dep found above, also check for @types/<peer> | react-dom → @types/react-dom |
| Framework integration | Known ecosystem groups | next requires compatible react |
| Workspace refs | workspace:* — skip (local) | — |
Present related packages to user and ask whether to include in upgrade plan.
Phase 4: Test-First Verification
Validate the migration approach before batch execution.
Quick feasibility check: If migration is config-only (e.g., ESLint flat config) or requires extensive project context, skip /tmp and go directly to subagent review.
If /tmp verification is feasible:
- Scan all usage — grep/glob for all imports, API calls, type references
- Write test diffs in /tmp — create isolated test files:
Environment setup: Create a minimal/tmp/deps-shift-verify-<package>-<timestamp>/ ├── package.json # Minimal deps (target package only) ├── tsconfig.json # Copied from project, paths/aliases adjusted for /tmp ├── original/ # Copy of affected code snippets ├── migrated/ # Proposed migration applied └── test-runner.sh # Must run tsc --noEmit at minimum, must NOT be just exit 0package.json, install only the target package version fresh. Copy project'stsconfig.json; removepaths,baseUrl, andreferencesfields that point to project-specific locations — /tmp resolves modules through its ownnode_modulesonly. Never mutate the project's actualnode_modules. - Run verification — type check + unit tests on migrated snippets
- Pass → proceed to Phase 5
- Fail → iterate (max 3 attempts), then present failure analysis to user
Fallback: When tests can't be written → subagent 3-pass review loop:
- Pass 1 (Direct): correctness — syntax, imports, types
- Pass 2 (Best Practice): idiomatic usage, recommended patterns
- Pass 3 (Critical Think): edge cases, hidden behavioral changes
- Fix + loop until all passes clean
Phase 5: Migration Plan & Confidence Index
Present structured plan with confidence index:
- Steps to execute (informed by Phase 4 results)
- Estimated impact (files, breaking changes count)
- Confidence index with factor breakdown and boost options
- Repo convention actions (changeset, commit format)
Always get user confirmation before executing.
Phase 6: Execute Migration
- Update dependency versions via package manager (including related packages from Phase 3.7)
- Install (update lockfile)
- Check for peer dependency conflicts — if install warns, present options in priority order: (a) upgrade conflicting package — preferred, (b) abort — if no compatible version exists yet, (c)
--legacy-peer-deps— last resort; warn user this bypasses peer validation and may cause runtime issues - Apply code migrations (using verified approach from Phase 4)
- For bot PRs: checkout PR branch, apply migrations, push
- Clean up /tmp verification files
Phase 7: Repo Convention Compliance
Detect and follow project conventions (see repo-conventions.md):
- Changesets → create changeset file
- Conventional commits → follow format
- CI checks → run matching local commands
- Pre-commit hooks → ensure hooks pass
- Custom scripts → run test, lint, typecheck
Phase 8: Final Verification
- Type check → 2. Lint → 3. Test suite → 4. Build
- For complex migrations: run subagent Pass 3 (Critical Think) as final quality gate
- All pass → report success
- Failures → analyze if upgrade-related, attempt fix, present remaining to user
- Bot PR → push + check CI via
gh pr checks
Guidelines
DO
- Check for official codemods first — search npm registry and migration guides before writing custom transforms
- Offer compat layers when available — ask user preference (gradual vs full), never assume
- Test migration approach in /tmp first — validate on representative samples before batch execution
- Use Context7 + changelog in parallel — combine multiple doc sources for complete picture
- Analyze code changes for hidden breaks — don't rely solely on changelogs; grep for deprecated API usage
- Always confirm before execution — present migration plan, get user approval
- Follow repo conventions — detect and comply with changesets, commit format, CI checks
DON'T
- Skip codemod detection — always check for official tools first
- Skip test-first verification — never execute batch migration without validating approach
- Auto-merge without checking — even if CI passes, verify breaking changes are addressed
- Assume changelog is complete — hidden breaking changes exist; analyze code diffs too
- Force upgrade when tests fail — present failure analysis, let user decide
- Assume compat layer preference — always ask user (gradual vs clean break)
Error Handling
| Error | Action |
|---|---|
| Package manager command fails | Check lockfile integrity, suggest rm -rf node_modules && install |
| Changelog/releases API 404 | Fall back to source code diff analysis |
| Codemod crashes partway | Report progress, show which files were transformed, suggest manual completion |
| Context7 MCP tool not found | Suggest installation, continue with changelog + releases + code analysis |
| Monorepo workspace resolution fails | Ask user to specify target package(s) |
| Tests still fail after 3 iterations | Present failure analysis, ask user how to proceed |
| /tmp write fails | Fall back to subagent review |
Reference Files
- package-managers.md — Detection matrix and commands
- repo-conventions.md — Convention detection and compliance
- confidence-index.md — Confidence index specification
- context7-integration.md — Context7 MCP detection and usage
- deps-bot-handling.md — Dependabot and Renovate PR handling
Notes
- Requirements:
ghCLI (for bot PRs, releases API), package manager CLI - Context7: Optional but recommended; install through the current agent's plugin or MCP setup flow.
- Supported ecosystems: npm, pnpm, yarn, bun, cargo, pip/uv/poetry, go, bundler, composer
- Limitations: Private registry auth requires manual setup; no auto-handling of 2FA prompts
- Monorepos: Detected automatically, but user may need to specify target package for large workspaces
- Boundary: When a major upgrade (e.g., React 18→19) requires API migration, this skill handles it. Use
deps-migrateonly when the primary intent is replacing one library with another.
Sponsors
Details
- Marketplace
- VdustR/vp-claude-code-marketplace
- Source
- plugins/vp-deps-shift
- Category
- Community
- License
- MIT
- Keywords
- dependencies, upgrade, migration, breaking-changes, codemod, dependabot, renovate, context7