Update Dependencies

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 update_plan to track each phase, restating any remaining steps of a parent workflow alongside them:

1. Run $review-dependencies skill
2. User strategy selection
3. Research breaking changes
4. User confirmation
5. Execute upgrades
6. Apply migrations
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.

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

Use request_user_input for upgrade strategy (Codex request_user_input allows up to 3 options per question, so the strategies are split across two questions):

Question 1 — Header: "Approach" Options:

• Cautious — Upgrade minor/patch first, then major one-by-one with research
• All at once — Research all major changes, then upgrade everything together
• Major handling — Defer the major decision (Skip-major or Interactive)

When a major upgrade would force a migration that is costly to reverse, present a Get a second opinion option in place of All at once, keeping Question 1 at three options and leaving Major handling in place so Question 2 stays reachable. It runs the $consult-claude 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 upgrade everything together selects the All-at-once strategy.

If the user picks Major handling, ask a follow-up:

Question 2 — Header: "Major handling" Options:

• Skip major — Only upgrade minor and patch versions
• Interactive — Ask for each major update individually
• Cancel — Cancel and return to the previous step

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:

Web search: "[package-name] v[X] migration guide"
Web search: "[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 rg 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 request_user_input to confirm (Codex request_user_input allows up to 3 options per question, so the four actions are split across two questions):

Question 1 — Header: "Decision" Options:

• Proceed — Continue with upgrades and migrations
• Show details — Display detailed breaking changes for review
• Other action — Defer the choice (Skip-package or Abort)

If the user picks Other action, ask a follow-up:

Question 2 — Header: "Other action" Options:

• Skip package — Exclude a specific package from upgrade
• Abort — Cancel the upgrade process
• Cancel — Cancel and return to the previous step

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 annotated tag, follow the tag to its commit) and update the trailing version comment to match. For a tag ref, keep the ref's precision when the action publishes a tag at that precision for the target, otherwise use the full release tag.

After every install command in this phase, run both checks below before any tests and before Phase 6.

1. Confirm the installed tree moved — spot-check the resolved version of one or two upgraded packages in the installed dependency tree against the manifest. An install can record the new versions while leaving the installed packages on their old ones, which makes every later check report on the pre-upgrade tree. When the two disagree, force a clean resolve: use the package manager's lockfile-respecting install where it has one, otherwise clear the installed tree and install again. Re-check afterward.
2. Diff the package-manager configuration — inspect the package-manager config files for entries the tool wrote on its own. A tool enforcing a safety guard, such as a minimum age before a release is installable or a provenance requirement, may record a per-package exclusion rather than refusing. Treat such an entry as the guard being bypassed: revert it and lower the manifest constraint to the newest version the guard admits. When the lowered range still admits the rejected version, an existing lockfile keeps it: restore the lockfile from git (delete it when git does not track it), re-run the resolving install and any semver-respecting update command this phase already ran, and diff the configuration again.