| name | upgrade-dependency |
| description | Plans safe dependency upgrades via researched paths and risk gates. Use when upgrading a package/module, remediating a vulnerable dependency, reviewing breaking changes, or creating an upgrade issue/PR. |
Upgrade Dependency
Goal: dependency current -> target/latest stable. Path first. Safe -> apply. Risky -> report + issue + stop.
Input: $ARGUMENTS = package/module, repo/manifest path, target version, natural language.
Flow
-
Scope: detect package.json, bun.lock, yarn.lock, go.mod, go.sum, workspaces. Map target/direct/transitive/parents/dependents/peers/plugins/adapters/runtime entrypoints. Ask only if ambiguous.
-
Path: per installed -> target hop, inspect tags, changelog/notes, migration/codemod docs, blogs. Verify SemVer behavior; classify patch/minor/major. Non-SemVer/weak notes -> score volume, cadence, diff, API churn, effort, blast. Include moving peers/plugins/adapters. Check Snyk/GHSA/OSV/Socket/vendor/CVE. Pick latest stable, not blind latest; use supported patterns. Write docs/dependency-upgrades/<package>-<from>-to-<target>.md via REFERENCE.md.
-
Gate: safe = patch/minor + high SemVer confidence + clear changelog + peers OK + low security uncertainty. Risky = major/non-SemVer/missing changelog/unclear migration/high effort/blast/peer risk/security uncertainty. Plan-only -> report/issue only. Snyk/vuln -> apply safe remediation, issue risky. Risky major needs report/issue before user approval. Many dependencies -> subagents one report each; main merges gates; apply only independent safe paths.
-
Apply: supply-chain preflight = release age 7-30d, disable scripts or review trustedDependencies, block git/tarball/raw URL, Socket/npq if present, lockfile review, clean/frozen install. Incremental; one commit per major; batch patch/minor only low risk.
JS/Bun: bun update <pkg>@<version> -> bun install -> bun install --yarn when yarn.lock exists/Snyk needs it -> bun run lint:fix -> bun run type:check -> bun test.
Go: go get -u <module>@<version> -> go mod tidy -> go build ./... -> go test ./... -> go vet ./....
Update related packages. Never hand-edit lockfiles/go.sum.
-
Security: preserve exploitability/reachability. Prefer direct/top-level bump -> parent bump -> override/resolution/replace. Never run advisory code. Document fixed versions/advisory ids/reachable symbols/residual risk.
-
Output: risky -> GitHub issue; safe -> PR. Use REFERENCE.md / REFERENCE.md.
Examples
react latest: build hop report; patch/minor safe -> apply; major/migration risk -> issue.go.opentelemetry.io/otel@<version>: research hops; go get path; run build/test/vet.- Snyk alert: preserve advisory/reachability; prefer direct bump before override.
Rules
Path before edits. Changelog mandatory for major/non-SemVer. Record risk. Escalate before deferring reachable security fix. JS/Go first-class; same gate elsewhere.
