---
name: dependency-upgrade
description: Upgrades one dependency at a time, reviews its release notes for breaking changes, updates affected code, and verifies with typecheck, tests and build. Use when the user asks to upgrade, bump or update a package or library version, or asks what is outdated.
---

# Dependency upgrade

Target: `$ARGUMENTS` (a package name, optionally with `@version`). If empty, list outdated packages and ask which one to upgrade.

## 1. Preconditions

- Run `git status --porcelain`. If there are uncommitted changes, tell the user and ask whether to continue.
- Identify the package manager from the lockfile: `package-lock.json` (npm), `pnpm-lock.yaml` (pnpm), `yarn.lock` (Yarn), `composer.lock` (Composer), `uv.lock` (uv), `poetry.lock` (Poetry), `requirements*.txt` (pip), `Cargo.lock` (Cargo), `go.sum` (Go).

## 2. See what is outdated

Use the matching command:
- npm: `npm outdated`
- pnpm: `pnpm outdated`
- Yarn classic: `yarn outdated`
- Composer: `composer outdated --direct`
- pip: `pip list --outdated`
- Cargo: `cargo update --dry-run` (or `cargo outdated` if installed)
- Go: `go list -m -u all`

Confirm the package, current version and target version with the user. Default to the latest version within the same major if they did not specify.

## 3. Read the release notes

Between the current and target version, collect breaking changes, deprecations and changed defaults. Sources, in order:
1. A `CHANGELOG*` or `UPGRADE*` file inside the installed package (for example `node_modules/<pkg>/`, `vendor/<vendor>/<pkg>/`).
2. The project's releases or changelog page, if web access is available.
3. Ask the user to paste the notes.

If you cannot find release notes, say so. Do not assume there are no breaking changes.

## 4. Find affected code

For each breaking change or deprecation, search the codebase for the affected import, function, option or config key. Record the search you ran and the matches.

## 5. Upgrade

Use the package manager, never edit the lockfile by hand:
- npm: `npm install <pkg>@<version>`
- pnpm: `pnpm add <pkg>@<version>`
- Yarn: `yarn add <pkg>@<version>`
- Composer: `composer require <vendor/pkg>:<constraint>`
- uv: `uv add "<pkg>==<version>"` or `uv lock --upgrade-package <pkg>`
- Poetry: `poetry add <pkg>@<version>`
- Cargo: `cargo update -p <pkg> --precise <version>` (edit `Cargo.toml` first for a new major)
- Go: `go get <module>@v<version>` then `go mod tidy`

Keep dev vs production dependency placement unchanged. If the resolver reports a peer or version conflict, stop and explain it. Do not add `--force` or `--legacy-peer-deps` without permission.

If other packages must move together (for example a framework and its companion packages), list them and upgrade them in the same step.

## 6. Fix and verify

- Update each affected call site found in step 4.
- Run the project's checks that exist: typecheck, lint, tests, build. Find them in `package.json` scripts, `Makefile`, `composer.json` scripts, CI config, or `CLAUDE.md`.
- If something fails, fix it if the cause is the upgrade. If the fix is large or unclear, stop and report.

## 7. Summary

```
Upgraded <pkg> <from> -> <to>
Breaking changes reviewed: <list or "none listed in release notes">
Code changes: <files and why, or "none">
Checks: <command> - <result>, ...
Follow-ups: <deprecations to address later>
```