From senior-dev-squad
Safely upgrades project dependencies: audit, changelog review, one-at-a-time bumps, tests green between each, lockfile pinning, rollback plan. Use when updating outdated or vulnerable packages.
How this skill is triggered — by the user, by Claude, or both
Slash command
/senior-dev-squad:dependency-upgraderThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Upgrading dependencies is not a bulk operation performed with a single command. It is a deliberate, sequenced process: audit current state, read the changelog, bump one dependency (or one safe group), verify tests are green, then move to the next. The lockfile is the source of truth. Every upgrade must leave the project in a provably working state before the next begins.
Upgrading dependencies is not a bulk operation performed with a single command. It is a deliberate, sequenced process: audit current state, read the changelog, bump one dependency (or one safe group), verify tests are green, then move to the next. The lockfile is the source of truth. Every upgrade must leave the project in a provably working state before the next begins.
Core principle: ONE dependency (or one safe patch/minor group) at a time, tests green between each — majors always individually with a migration guide in hand.
NEVER BUMP A MAJOR WITHOUT READING ITS MIGRATION GUIDE.
NEVER UPGRADE MORE THAN ONE LOGICAL UNIT AT A TIME WITHOUT GREEN TESTS IN BETWEEN.
Use this when:
npm outdated, pip list --outdated, bundle outdated, or cargo outdated reveals stale packagesnpm audit) flags a vulnerable versionUse this ESPECIALLY when:
Never skip when:
test-engineer first, then return here| Version bump | Expected risk | Approach |
|---|---|---|
| Patch (x.y.Z) | Low — bug fix, no API change | Safe to group same-package patch bumps; run tests once |
| Minor (x.Y.0) | Medium — new API surface, deprecations possible | Group same-package minor bumps cautiously; read changelog |
| Major (X.0.0) | High — breaking changes, API removals | Always individual; read migration guide before touching lockfile |
Before touching any version number:
Capture the outdated inventory — run the appropriate audit command for your ecosystem (see REFERENCE.md for full command list per ecosystem).
npm outdated && npm audit # Node / npm
Categorise every outdated package — open a scratch list:
Confirm the test baseline is green. If CI is red before you start, stop. Fix existing failures first.
npm test # or: pytest / bundle exec rspec / cargo test / go test ./...
Start from a clean branch and clean working tree.
git checkout -b deps/upgrade-$(date +%Y-%m-%d)
For every dependency on your list, before touching the version:
CHANGELOG.md in the repo, the GitHub Releases page, or the npm/PyPI release notes.Output: annotated list with "safe to bump", "needs migration work", or "defer — too large" for each package.
A "unit" is a single package at any bump level, or a group of patch-only bumps for unrelated packages when you are confident tests cover each.
Never bundle a major with anything else in one commit.
After each unit — if tests are green, commit immediately:
git add package.json package-lock.json # or lockfile equivalent
git commit -m "deps: upgrade <package> <old> → <new>"
One commit per unit. Granular commits are your rollback path. See REFERENCE.md for per-ecosystem upgrade commands (npm, pip, Cargo, Go, Bundler).
npm test && npx tsc --noEmitpackage-lock.json, yarn.lock, Cargo.lock, poetry.lock, Gemfile.lock).npm ci / yarn install --frozen-lockfile in CI, never npm install — the latter silently upgrades transitives and breaks reproducibility.Configure Renovate or Dependabot to surface upgrades weekly on a schedule. Set majors to require human review; allow patch/minor to automerge on green CI. See REFERENCE.md for starter configs.
Automation handles scheduling. You still own reviewing changelogs and merging majors.
git revert <sha> restores the exact lockfile.npm ci && npm test, confirm green.If you catch yourself thinking:
npm update and see what happens"ALL of these mean: STOP. Return to the relevant phase.
Watch for these redirections:
When you see these: STOP. Return to Phase 1 and rebuild the upgrade plan.
| Excuse | Reality |
|---|---|
| "It's just a patch, nothing can break" | Patches fix bugs that your code may depend on. Tests exist precisely for this. |
| "I'll update everything at once and deal with failures" | You lose the ability to attribute any failure to a specific package. Debugging becomes archaeology. |
| "The lockfile is autogenerated, no need to commit it" | Without a committed lockfile, npm install resolves differently on every machine and in every CI run. |
| "I don't need to read the changelog for a minor bump" | Minor bumps carry deprecations. Today's deprecation is next major's breakage. |
| "Renovate/Dependabot handles this automatically" | Automation handles scheduling. You still own reviewing changelogs and merging majors. |
| "There are no tests, so I can't verify anything" | That is a blocker, not an excuse. Add tests first or explicitly accept and document the unverified risk. |
npm outdated (or equivalent) re-run — remaining deferrals are intentional and documentednpm audit (or equivalent) shows no new advisories introduced by this sessionnpx tsc --noEmitgit log --oneline shows granular, revertible commitsnpx claudepluginhub haj1t/senior-dev-squad-skills --plugin senior-dev-squadGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.