dependency-bump

Dependency Bump

Staged, reviewable dependency upgrades for the detected ecosystem. Patches and minors by default; majors require explicit user sign-off after a changelog review.

The value of this skill is staging. Bundling every update into one commit hides which bump broke what. Separating patch → minor → major and running tests between stages makes regressions attributable.

Non-goals

• Does NOT update toolchains (Node version, Python version, Rust edition, Go version).
• Does NOT run global installs (npm install -g, pip install --user, cargo install, etc.).
• Does NOT commit. Returns the diff for user review.
• Does NOT upgrade dev tools (eslint, prettier, rustfmt) unless they appear in the project's standard manifest alongside runtime deps.

Workflow

DETECT   → Identify ecosystem from manifest files
PARSE    → Bucket updates into patch / minor / major
REVIEW   → Fetch changelogs for major bumps
PROPOSE  → Present staged plan for user approval
EXECUTE  → Apply approved stages, regenerate lockfile, run tests
REPORT   → Summarise bumped packages + breaking-change notes

---

Phase 1: DETECT

Understand the project's package management BEFORE running any command. Do NOT assume from filename patterns alone — inspect the project's own canonical setup signals, then record the finding for reuse.

One ecosystem per invocation. Mixed-language repos run the skill once per ecosystem.

Steps:

1. Enumerate dependency-manifest and lockfile candidates in the project root:

   ls -la  # look for anything that declares or locks dependencies
   

   Typical manifests span many ecosystems — package.json, Cargo.toml, go.mod, pyproject.toml, Gemfile, pom.xml, build.sbt, build.gradle*, lakefile.toml / lakefile.lean, mix.exs, stack.yaml, *.cabal, Pipfile, flake.nix, shard.yml, deps.edn, elm.json, dune-project, gleam.toml, zig.zon, opam, BUILD.bazel, etc. This list is illustrative — do not treat it as exhaustive, and do not fall back to "no ecosystem" just because the manifest isn't on it.

2. Find the PROJECT'S canonical install / update / test commands. In priority order:

   • CI config (.github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml, Jenkinsfile, .buildkite/*.yml, azure-pipelines.yml). CI is authoritative — it records exactly how the project is built, installed, and tested in a clean environment.
   • README / CONTRIBUTING / DEVELOPMENT / docs — look for "Setup", "Installation", "Dependencies", "Development", "Testing" sections.
   • Makefile / justfile / Taskfile.yml / scripts/ — often wrap the ecosystem's commands.
   • CLAUDE.md ## Dependency Commands section — may already exist if this skill ran before; use it directly.

3. Record the finding. You need at minimum: manifest file(s), lockfile (if any), outdated query, audit query (or "n/a"), update command, test command. If the project uses a well-known ecosystem AND the CI/README confirms the standard commands, use the standard commands (reference table below). If anything is ambiguous or exotic, ASK the user rather than guess.

4. Persist the finding for reuse — append or update ## Dependency Commands in the project's CLAUDE.md so the next invocation skips discovery:

   ## Dependency Commands
   - Manifest: <file>
   - Lockfile: <file or "none">
   - Outdated: <command>
   - Audit: <command or "n/a">
   - Update: <command pattern, per-package or bulk>
   - Test: <command>
   

5. Run the outdated + audit commands. If a helper tool (cargo-outdated, cargo-audit, pip-audit, govulncheck, similar) is listed as recommended but not installed, note its absence in the final report. Do NOT install helper tools.

Reference: common ecosystems

Non-authoritative hint sheet for well-known ecosystems. When a project's CI / README confirms one of these setups, reuse the listed commands. For anything exotic (Lean 4, Gleam, Zig, Elm, Scala, Nim, OCaml, Clojure, Elixir, Haskell, Crystal, Lua/Rockspec, etc.) or customised, skip this table and use what you found in step 2.

Ecosystem	Manifest + lockfile	Outdated	Audit
pnpm	package.json + pnpm-lock.yaml	pnpm outdated --format json	pnpm audit --json
yarn	package.json + yarn.lock	yarn outdated --json	yarn npm audit --json
npm	package.json + package-lock.json	npm outdated --json	npm audit --json
cargo	Cargo.toml + Cargo.lock	cargo outdated --format json (or cargo update --dry-run)	cargo audit --json (if installed)
uv	pyproject.toml + uv.lock	uv lock --upgrade --check	n/a
poetry	pyproject.toml + poetry.lock	poetry show --outdated	n/a
pip	requirements*.txt or pyproject.toml	pip list --outdated --format json	pip-audit --format json (if installed)
go modules	go.mod	go list -u -m -json all	govulncheck ./... (if installed)

---

Phase 2: PARSE

From the outdated output, produce three explicit lists using semver-style bump classification:

• Patch — x.y.Z bumps only (third component changes). Low risk; bundle.
• Minor — x.Y.z bumps (second component changes). Usually safe.
• Major — X.y.z bumps (first component changes). Needs review.

For ecosystems without strict semver (e.g. Go modules using v0.x where every minor is effectively a major), treat v0.x.y → v0.X.z as major and say so in the report.

Preserve current-version and latest-version numbers for each package — they appear in the final report.

---

Phase 3: REVIEW MAJOR BUMPS

For each major bump, WebFetch the package's changelog. Source priority:

1. GitHub releases page (derive from package metadata: https://github.com/<org>/<repo>/releases/tag/v<new>).
2. npm package README on npmjs.com for Node packages.
3. crates.io changelog for cargo packages.
4. PyPI release history for Python packages.
5. pkg.go.dev release notes for Go modules.

Summarise breaking changes in ≤3 bullets per package. Quote specific removed APIs / changed signatures where named. If the changelog does not enumerate breaking changes explicitly, say so: "Changelog does not list breaking changes — review manually."

Do NOT auto-include majors in the executed bump plan. They require user sign-off in Phase 4.

If WebFetch fails for a package, record "changelog unreachable — review manually" and continue. Do not block on a single fetch failure.

---

Phase 4: PROPOSE STAGED PLAN

Present to the user exactly this shape:

Stage 1 — Patch (N packages): pkg-a 1.2.3→1.2.4, pkg-b 4.5.6→4.5.8
  Risk: low. Bundle.

Stage 2 — Minor (N packages): pkg-c 2.1.0→2.3.0
  Risk: usually safe.

Stage 3 — Major (N packages, needs review):
  - pkg-d 3.0.0→4.0.0
    Breaking changes (from changelog):
      - <bullet>
      - <bullet>
  - pkg-e 1.0.0→2.0.0
    Breaking changes: <...>
  Risk: requires review.

Which stages do you want executed? Default: Stage 1 only.

Wait for user response. STOP until user replies with the stage selection (e.g. "stage 1 and 2", "all three", "skip stage 3").

---

Phase 5: EXECUTE

For each approved stage, in order (1, then 2, then 3):

1. Run the ecosystem's update command. Source priority:

   • The Update command you recorded in CLAUDE.md ## Dependency Commands (Phase 1 step 4) — this is authoritative.
   • If a stage-scoped form is needed (e.g., only bump Stage 1 packages), derive it from the authoritative command using the ecosystem's conventional per-package syntax.

   Common patterns for recognised ecosystems (reference only — defer to the project's documented command):

   Ecosystem	Update pattern
   pnpm	pnpm update <pkg>@<version> ...
   yarn	yarn up <pkg>@<version> ...
   npm	npm install <pkg>@<version> ...
   cargo	cargo update -p <pkg> --precise <version> per package
   uv	uv lock --upgrade-package <pkg> per package
   poetry	poetry update <pkg> per package
   pip (requirements.txt)	edit pinned version in requirements.txt, then pip install -r requirements.txt
   go modules	go get <module>@<version> per package, then go mod tidy

   For exotic or customised ecosystems, use exactly what the project's CI config / Makefile / README prescribes. If you cannot determine the update command, STOP and ask the user.

2. Confirm the lockfile (if any) regenerated. Never hand-edit lockfiles. Never bypass lockfile regeneration.

3. Run the project's test command. Detection order (first match wins):

   • CLAUDE.md ## Test Command section.
   • Test entry from ## Dependency Commands (recorded in Phase 1 step 4).
   • The test step in CI config — copy the exact command CI runs.
   • A documented target in Makefile / justfile / Taskfile / README.
   • Only if the project is a recognised ecosystem AND none of the above exist: fall back to the ecosystem's conventional invocation (e.g. <pm> test, pytest, cargo test, go test ./...).
   • If still unknown, STOP and ask the user for the test command.

4. Record the stage's test outcome: PASS / FAIL / SKIPPED-no-tests.

HARD GATE — stage failure:

→ Tests fail after any stage → STOP. Do NOT proceed to the next stage. Report the failure, show the diff, let the user decide.

---

Phase 6: REPORT

Produce the final summary. Bounded to 600 words.

## Dependency Bump — <ecosystem>

### Bumped (Stage 1 — Patch, tests: PASS)
- pkg-a 1.2.3 → 1.2.4
- pkg-b 4.5.6 → 4.5.8

### Bumped (Stage 2 — Minor, tests: PASS)
- pkg-c 2.1.0 → 2.3.0

### Bumped (Stage 3 — Major, tests: PASS)
- pkg-d 3.0.0 → 4.0.0
  Breaking changes:
    - <bullet>
    - <bullet>
  - <bullet>

### Skipped
- pkg-x 1.0.0 → 2.0.0 — user declined major upgrade.

### Audit findings
- <vuln summary from audit command, or "audit tool unavailable">

### Next step
Review the diff. Commit when satisfied. This skill does NOT commit.

Major-bump changelog summaries: ≤3 bullets each, verbatim from Phase 3.

---

Safety summary

• Lockfile regeneration is mandatory for every stage.
• Global installs are forbidden.
• Commits are the user's decision, not this skill's.
• Stage failure halts the pipeline — no "just one more stage."
• Toolchain version changes (Node, Python, Rust, Go) are out of scope — refuse and explain.

---

Red flags

Thought	Reality
"I'll bundle all updates into one commit"	Staging is the whole point. Separate patch / minor / major.
"The major bump is probably fine"	Fetch the changelog. Always.
"Tests failed but it's probably flaky"	STOP. Report. Do not proceed.
"I'll update Node from 18 to 20 while I'm here"	Out of scope. Refuse.
"I'll install cargo-audit since it's missing"	No global installs. Note absence in the report.