Dependency Upgrade Planner
Produce a plan. Do not upgrade anything until the user approves the plan.
Procedure
- Detect the ecosystem from the manifest:
package.json,requirements.txtorpyproject.toml,go.mod,Cargo.toml,Gemfile,pom.xml. If several exist, ask which to plan, or plan them separately. - Read the current versions from the manifest and the lockfile (
package-lock.json,poetry.lock,go.sum,Cargo.lock,Gemfile.lock). - Find available versions with the ecosystem's own tool, and report the output you actually got:
- npm:
npm outdated - Python:
pip list --outdatedoruv pip list --outdated - Go:
go list -u -m all - Rust:
cargo outdated - Ruby:
bundle outdatedIf the tool is unavailable, say so and work from the manifest, marking versions as unverified.
- npm:
- Classify each outdated package:
- Patch / minor — usually safe.
- Major — read the changelog or release notes for breaking changes before planning it.
- Security — anything flagged by
npm audit,pip-audit,govulncheck,cargo audit, orbundle audit. These go first.
- Order the work into batches:
- Batch 0: security fixes, even if major.
- Batch 1: patch and minor bumps, grouped by area.
- Batch 2: majors with no cross-dependency, one per commit.
- Batch 3: majors that must move together (for example a framework and its plugins).
- For each batch, state: the packages, the from/to versions, the breaking changes that apply, the code or config that must change, and how to verify.
Output template
## Upgrade plan
Ecosystem: <npm / pip / go / cargo / ...>
Manifest: <path>
### Batch 0 — Security
| Package | From | To | Why | Breaking? |
| --- | --- | --- | --- | --- |
### Batch 1 — Patch and minor
...
### Batch 2 — Major, independent
...
### Batch 3 — Major, must move together
...
### Verification
After each batch: <the exact command that proves nothing regressed>
### Rollback
Per batch: <how to revert, e.g. git revert of the batch commit>
### Deferred
<Packages intentionally left alone, and why>
Rules
- Never edit the manifest during planning. Output the plan, then stop.
- Read the actual changelog for a major bump when one is available; do not assume a version is breaking because the major number changed.
- Always name the verification command. "Run the tests" is not a command;
npm testis. - Pin the reason for deferral when you leave a package out — for example, a major whose release notes you could not read.
- Do not run install, upgrade, or audit commands that modify the tree.
npm outdated,npm audit, and their equivalents are read-only and fine.
Supporting file
references/upgrade-strategy.md explains batching, semver edge cases, and how to handle a package that must be held back.