Upgrade a dependency safely
A dependency change imports someone else's decisions into your build. Treat it like a
code change from a stranger: read what changed, run everything that could be affected,
keep the lockfile honest, and never "bump and hope".
Gaffer constraints — read first.
- Your delivery prompt forbids installing, updating or removing dependencies in any
ecosystem; that needs human approval. The safety hook enforces it for
npm|pnpm|yarn install|i|add|ci|update|up|upgrade|remove|rm|uninstall and
pip install. Do not look for a command that dodges the hook (bare yarn,
bun install, uv sync, poetry add, bundle install, go get, cargo update
are equally off-limits), and never hand-edit a lockfile to fake one.
- In a delivery worktree
node_modules is a symlink to the main checkout's install.
Never run npm ci, pnpm install, update or prune there: it rewrites or empties
the shared install and breaks every other worktree.
- Consequence: your tests run against the version that is ALREADY installed, not the
one in your edited manifest. Check which version actually ran
(
node -p "require('<pkg>/package.json').version", pip show <pkg>, go list -m <mod>)
before claiming the new version is tested.
Steps
- Pin down the reason. A security advisory (which CVE/GHSA, which versions are
fixed), a feature you need, or hygiene. The reason sets the minimum target and does not
license unrelated bumps. For an advisory, prefer the smallest version that fixes it.
Call
search_lore for pinned versions and known incompatibilities in this repo.
- Classify the jump with semver. Patch and minor promise compatibility; major does
not; any bump inside
0.y.z may break. Treat a transitive major change, a raised
engines/runtime floor, or a changed peer-dependency range as a major.
- Read the upstream changelog, release notes and migration guide between the
current and target versions. List every breaking change, deprecation and behaviour
change, then
grep the repo for the imports and APIs each one names. An empty grep
is evidence too; record it. A major bump with no notes read is a guess.
- For a NEW package, vet it before adding it: exact name (typosquats differ by one
character), maintainer and release activity, licence against the repo's policy,
whether it runs install scripts, and whether the standard library or an existing
dependency already covers the need (the
minimalism skill). New dependencies need a
human decision in this factory: request_decision with the justification.
- Do not run the package manager yourself. The manifest and lockfile must be
produced by the owning tool (e.g.
pnpm up <pkg>@<ver> --ignore-scripts,
go get <mod>@<ver>, cargo update -p <crate> --precise <ver>), and that is a
human's step here. Unless the target version is already installed and locked on the
branch, stop (see "Stop and escalate") with the exact command a human should run.
Scope stays at one package plus the transitive changes it forces; a lockfile diff of
thousands of lines hides the one that matters.
- Adapt the code minimally to the breaking changes you listed. If the upgrade
forces a refactor larger than the ticket implies, stop and
request_decision with the
size and the option of an interim minor/patch bump.
- Verify at the edges. With the target version actually installed, run build,
typecheck, lint, the full test suite and any integration or browser suite the repo
has — dependency changes break at the boundaries. Then run the ecosystem audit
(
pnpm audit, npm audit, pip-audit, cargo audit, govulncheck) and confirm the
advisory is gone and no new high-severity finding appeared.
- Evidence via the
record-evidence skill: the version pair, the changelog items
you handled (and the empty greps), the verification output with the installed version
shown, the audit result, and any transitive major change. On a resume that call is
refused: do not retry; put this, the AC → test map and the smallest-change note in
your final message.
Done when
The manifest and lockfile were produced by the package manager, the version under test
is the target version, the full verification and audit pass, and every breaking change
in the notes is either handled or shown not to apply. Otherwise you are not done: the
ticket is blocked with the exact command and your changelog analysis.
Stop and escalate when
- The lockfile cannot be regenerated because installs are off-limits to you:
mark_ticket_blocked with the exact command (e.g.
pnpm up <pkg>@<ver> --ignore-scripts) and the changelog analysis you already did, so
the human run is one step.
- The tests could only run against the old installed version: say so plainly; never
report them as proof of the upgrade.
- The upgrade needs a fork, a patch-package, or a vendored copy: that is a decision.
Rules
- Lockfiles are generated, never hand-edited; one package manager, at CI's version.
- One package per ticket unless the ticket is a refresh; no drive-by bumps.
.npmrc and other credential files are blocked by the hook; registry and auth
changes are a human's job.
- Work on the delivery branch (verify with
git branch --show-current); commit, never push.
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While bumping a package you learn which pins must not move, which packages break each other, and which manager version CI insists on. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
1---2name: dependency-upgrade3description: Use when a ticket bumps, adds, or removes a dependency — a security advisory, a major-version upgrade, a lockfile refresh, a Dependabot follow-up — and the change must be proven safe with the repo's tests and the upstream changelog, not assumed. Invoke for "upgrade X to v4", "fix the audit finding", "remove the unused package", or any change to a manifest or lockfile.4stack: []5area: workflow6metadata:7 source: https://skillmd.com/skills/tmj-90/dependency-upgrade8---910# Upgrade a dependency safely1112A dependency change imports someone else's decisions into your build. Treat it like a13code change from a stranger: read what changed, run everything that could be affected,14keep the lockfile honest, and never "bump and hope".1516**Gaffer constraints — read first.**1718- Your delivery prompt forbids installing, updating or removing dependencies in any19 ecosystem; that needs human approval. The safety hook enforces it for20 `npm|pnpm|yarn install|i|add|ci|update|up|upgrade|remove|rm|uninstall` and21 `pip install`. Do not look for a command that dodges the hook (bare `yarn`,22 `bun install`, `uv sync`, `poetry add`, `bundle install`, `go get`, `cargo update`23 are equally off-limits), and never hand-edit a lockfile to fake one.24- In a delivery worktree `node_modules` is a symlink to the main checkout's install.25 Never run `npm ci`, `pnpm install`, `update` or `prune` there: it rewrites or empties26 the shared install and breaks every other worktree.27- Consequence: your tests run against the version that is ALREADY installed, not the28 one in your edited manifest. Check which version actually ran29 (`node -p "require('<pkg>/package.json').version"`, `pip show <pkg>`, `go list -m <mod>`)30 before claiming the new version is tested.3132## Steps33341. **Pin down the reason.** A security advisory (which CVE/GHSA, which versions are35 fixed), a feature you need, or hygiene. The reason sets the minimum target and does not36 license unrelated bumps. For an advisory, prefer the smallest version that fixes it.37 Call `search_lore` for pinned versions and known incompatibilities in this repo.382. **Classify the jump with semver.** Patch and minor promise compatibility; major does39 not; any bump inside `0.y.z` may break. Treat a transitive major change, a raised40 `engines`/runtime floor, or a changed peer-dependency range as a major.413. **Read the upstream changelog, release notes and migration guide** between the42 current and target versions. List every breaking change, deprecation and behaviour43 change, then `grep` the repo for the imports and APIs each one names. An empty grep44 is evidence too; record it. A major bump with no notes read is a guess.454. **For a NEW package, vet it before adding it:** exact name (typosquats differ by one46 character), maintainer and release activity, licence against the repo's policy,47 whether it runs install scripts, and whether the standard library or an existing48 dependency already covers the need (the `minimalism` skill). New dependencies need a49 human decision in this factory: `request_decision` with the justification.505. **Do not run the package manager yourself.** The manifest and lockfile must be51 produced by the owning tool (e.g. `pnpm up <pkg>@<ver> --ignore-scripts`,52 `go get <mod>@<ver>`, `cargo update -p <crate> --precise <ver>`), and that is a53 human's step here. Unless the target version is already installed and locked on the54 branch, stop (see "Stop and escalate") with the exact command a human should run.55 Scope stays at one package plus the transitive changes it forces; a lockfile diff of56 thousands of lines hides the one that matters.576. **Adapt the code minimally** to the breaking changes you listed. If the upgrade58 forces a refactor larger than the ticket implies, stop and `request_decision` with the59 size and the option of an interim minor/patch bump.607. **Verify at the edges.** With the target version actually installed, run build,61 typecheck, lint, the full test suite and any integration or browser suite the repo62 has — dependency changes break at the boundaries. Then run the ecosystem audit63 (`pnpm audit`, `npm audit`, `pip-audit`, `cargo audit`, `govulncheck`) and confirm the64 advisory is gone and no new high-severity finding appeared.658. **Evidence** via the `record-evidence` skill: the version pair, the changelog items66 you handled (and the empty greps), the verification output with the installed version67 shown, the audit result, and any transitive major change. On a resume that call is68 refused: do not retry; put this, the AC → test map and the smallest-change note in69 your final message.7071## Done when7273The manifest and lockfile were produced by the package manager, the version under test74is the target version, the full verification and audit pass, and every breaking change75in the notes is either handled or shown not to apply. Otherwise you are not done: the76ticket is blocked with the exact command and your changelog analysis.7778## Stop and escalate when7980- The lockfile cannot be regenerated because installs are off-limits to you:81 `mark_ticket_blocked` with the exact command (e.g.82 `pnpm up <pkg>@<ver> --ignore-scripts`) and the changelog analysis you already did, so83 the human run is one step.84- The tests could only run against the old installed version: say so plainly; never85 report them as proof of the upgrade.86- The upgrade needs a fork, a patch-package, or a vendored copy: that is a decision.8788## Rules8990- Lockfiles are generated, never hand-edited; one package manager, at CI's version.91- One package per ticket unless the ticket is a refresh; no drive-by bumps.92- `.npmrc` and other credential files are blocked by the hook; registry and auth93 changes are a human's job.94- Work on the delivery branch (verify with `git branch --show-current`); commit, never push.9596## Capture lore9798This skill is one of the places durable, reusable knowledge naturally surfaces:99**While bumping a package you learn which pins must not move, which packages break each other, and which manager version CI insists on.** That kind of fact is *lore*. Capture it via the **lore-capture100protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):101call the Memory MCP `suggest_lore` once at the close of your work — reusable102conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.