/update-dependencies

name: update-dependencies
description: "Upgrade project dependencies, researching breaking changes in major updates. Use when the user asks to \"update dependencies\", \"upgrade packages\", \"update deps\", or \"update GitHub Actions\"."

Update Dependencies

Upgrade project dependencies, researching breaking changes for major version updates.

Optional filter: `$ARGUMENTS` (e.g., `react`, `Alamofire`, `serde tokio`)

Task Tracking

At the start, use `TaskCreate` to create a task for each phase:

1. Run `/review-dependencies` skill 2. User strategy selection 3. Research breaking changes 4. User confirmation 5. Execute upgrades 6. Apply migrations and sync out-of-manifest records 7. Run `/run-checks` skill 8. Exercise upgraded schema against the real store 9. Report results 10. Recommend next steps

Phase 1: Review Dependencies

Run the `/review-dependencies` skill to detect package managers and discover available updates. If no updates are available, stop.

Phase 2: User Strategy Selection

Before summarizing, set aside packages whose version tracks a pinned runtime or platform rather than the newest release, such as runtime type definitions and platform SDKs. Find the pin the project declares (version manager file, `engines` field, container base image, CI setup step) and hold any version beyond it until the pin moves.

A package whose newer releases raise their own declared runtime or platform minimum above the project's is not set aside on that basis.

Present a summary showing:

• Count and list of major updates (with current → target versions)
• Count of minor updates
• Count of patch updates
• Packages set aside, each with the pin that governs it
• Packages whose newer releases need a higher runtime or platform minimum, each with the minimum they need

Before the strategy question, use AskUserQuestion to ask for each package that needs a higher minimum whether to raise the project's minimum, naming the versions or devices that lose support and the dependents that must raise theirs in lockstep, or to cap the package at the last release the current minimum admits. A project that declares no minimum counts as below every package's declared minimum: there, the raise option declares the package's minimum as the project's pin, in a version manager file, the `engines` field, or a CI setup step, and the cap option holds the package at the last release before it raised its minimum. Add a **Get a second opinion** option, which runs the `/consult-codex` skill for what each option commits to and what reversing it costs. Then resolve the choice with that answer in hand, re-asking when it stays the user's. Apply a raise only when the package is upgraded.

Use AskUserQuestion for upgrade strategy:

**Header**: "Strategy" **Options**:

• **Cautious** — Upgrade minor/patch first, then major one-by-one with research
• **All at once** — Research all major changes, then upgrade everything together
• **Skip major** — Only upgrade minor and patch versions
• **Interactive** — Ask for each major update individually

When a major upgrade would force a migration that is costly to reverse, present a **Get a second opinion** option in place of **Interactive**, keeping the question at four options. It runs the `/consult-codex` skill for which strategy the breaking changes warrant. Then resolve the strategy with that answer in hand, re-asking when the choice stays the user's. A freeform answer asking to decide each major update individually selects the Interactive strategy.

Phase 3: Research Breaking Changes

For **each package or CI action with a major version update**:

Step 1: Calculate Version Gap

Identify all major versions between current and target. For example:

• `react: 17.0.2 → 19.0.0` → research v18 AND v19 breaking changes
• `Alamofire: 4.9.1 → 6.0.0` → research v5 AND v6 breaking changes

Step 2: Research Each Major Version

Search for migration documentation:

WebSearch: "[package-name] v[X] migration guide"
WebSearch: "[package-name] v[X] breaking changes"

Common sources: GitHub releases page, official docs, changelog files.

Step 3: Extract Key Breaking Changes

Identify: API changes (renamed/removed functions), configuration changes, peer/transitive dependency requirements, behavioral changes, deprecated features now removed.

Step 4: Search Codebase for Affected Code

Use Grep to find usage of deprecated or changed APIs. Document which files are affected and what changes are needed.

Then check the package's installed consumers: read their declared peer or compatibility ranges and flag any range that excludes the target version. Toolchain consumers such as linters, type checkers, and build tooling can block a major even when the project's own code and configuration are clean. Carry each one into Phase 4 as a blocker.

A CI action that installs or runs the package counts as such a consumer. When a newer release of it supports the target, pair that bump with the package instead of carrying a blocker: Phase 4 presents the two together, and they are upgraded or skipped together.

Phase 4: User Confirmation

For each major update, present:

• Package name and version transition
• Breaking changes found (summarized)
• Files potentially affected (count and list)
• Consumers whose declared ranges block the upgrade, and CI action bumps paired with it, when Phase 3 found any

Use AskUserQuestion to confirm:

**Header**: "Confirm" **Options**:

• **Proceed** — Continue with upgrades and migrations
• **Show details** — Display detailed breaking changes for review
• **Skip package** — Exclude a specific package from upgrade
• **Abort** — Cancel the upgrade process

If "Show details" selected, display full migration research, then ask again.

Phase 5: Execute Upgrades

Bump each outdated CI action ref in the file that declares it, under the chosen strategy. For a ref pinned to a commit SHA, resolve the target release tag to the commit it points to (for an a