| name | dependency-upgrade |
| description | Plan, execute, and verify safe dependency, framework, and runtime upgrades across any stack (npm/pnpm/yarn, Composer/PHP, pip/poetry/uv/Python, Go, Rust, .NET). Covers changelog-driven planning, one-major-at-a-time sequencing, breaking-change detection mapped to the actual codebase, peer/runtime gates, rollback planning, post-update verification, and supply-chain security audits against compromised or malicious updates. Merges the dependency-upgrade-planner procedure, the event4u upgrade workflow, and guardrails from Addy Osmani's engineering rules (dependency discipline, source-driven verification, security review). Use when upgrading a key dependency, responding to a security advisory, or scoping a framework migration. |
Dependency Upgrade
Plan, execute, verify, and audit dependency upgrades so that "bump the version"
becomes a safe, evidence-backed change instead of an act of faith.
This skill merges three sources into one coherent workflow:
- Planning (
references/planning.md) — from dependency-upgrade-planner:
map the version path, read every intermediate migration guide, and pin the
breaking changes to your actual call sites.
- Execution (
references/execution.md) — from the event4u upgrade
workflow: per-stack commands, verification pipeline, multi-package rules,
and pitfalls.
- Guards (
references/security-and-audit.md,
references/review-and-verification.md) — from Addy Osmani's engineering
rules: dependency discipline, source-driven verification, and the
post-update malware/behavior audit that makes the result safer than any of
the three alone.
The safety win is the combination: the planner prevents blind multi-major
jumps, the workflow forces per-step verification, and the security audit
catches the compromised update that CVE scanners miss.
Reference documents
| Reference | Contents | Load when |
|---|
references/planning.md | Pinning versions from the lockfile, reading migration guides for every major, grep-based call-site inventory, peer/runtime gates, one-major-at-a-time sequencing, rollback planning. | Scoping a large upgrade or framework migration; multi-major gaps. |
references/execution.md | Assess → plan → execute → verify → document per stack (Composer, npm, pip/poetry/uv, Go, Cargo), multi-package upgrades, pitfalls, version constraints, security upgrades, conflict detection. | Actually performing the upgrade and its verification. |
references/security-and-audit.md | Triaging audit results by reachability, post-update malware/behavior audit (install-without-scripts, capability/purpose-vs-behavior diff, provenance checks), supply-chain hygiene. | Any upgrade after a security advisory, or any add/upgrade in general. |
references/review-and-verification.md | Dependency discipline (one per change, tests decide, transitive graph, lockfile honesty), new-dependency gates, source-driven verification, review red flags, verification checklist. | Reviewing an upgrade before merge. |
How to use
- Plan first — load
references/planning.md to pin versions, read the
migration guides, and scope breaking changes against the real codebase.
- Execute one step, verify it — follow
references/execution.md per stack,
one major at a time, running the full suite plus type-checker after each step.
- Audit before you ship — run the post-update malware/behavior audit from
references/security-and-audit.md and surface any finding to the user for
confirmation.
- Review the diff — apply the discipline and checklist in
references/review-and-verification.md before merging.
Core rules
- Two or more majors behind → one major at a time, each land behind a green build.
- Never upgrade without reading the migration guide for every version in between.
- Never hand-edit the lockfile; always commit and review its diff.
- Never apply forced audit remediation automatically (
npm audit fix --force).
- After any upgrade: full test suite, type-checker, and a supply-chain audit — a
trusted package can still ship a compromised version.
