Safely upgrade dependencies or migrate framework versions.

Process

• If code changes are involved: run jj diff -s first to see changed files; then use jj diff -- path to restrict to specific files/directories

Step 1 - Identify Upgrade Type

Ask the user to clarify what they want to upgrade:

• Single dependency: Upgrade one package (e.g., react 18 -> 19 )

• All dependencies: Update all packages to latest compatible versions

• Framework migration: Major version upgrade with breaking changes (e.g., Next.js 13 -> 15 )

• Language version: Update runtime version (e.g., Python 3.11 -> 3.12 )

Step 2 - Analyze Current State

• Invoke code-analyze-project skill to detect package manager and project type

• Read the dependency file (package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, etc.)

• Identify current versions of packages to be upgraded

Step 3 - Research Changes

Research using WebSearch/WebFetch:

• Official changelogs for the target version

• Breaking changes and deprecated APIs

• Migration guides and best practices

• Community migration experiences

Also invoke code-researcher skill if available to get additional research insights.

Step 4 - Generate Plan

Create an upgrade plan with:

• Deprecated API replacements needed

• Breaking changes to address

• Test updates required

• Migration commands to run

Present the plan to the user for approval before proceeding.

Step 5 - Execute Upgrades

After user approval:

• Update dependency file with new versions

• Install new dependencies

• Fix breaking changes in code

• Invoke test skill to verify changes

• Fix any test failures

Step 6 - Fix Failures

For any test failures:

• Identify root cause (breaking change or test issue)

• Fix code or tests as appropriate

• Re-run tests to verify

Stop Condition

• If a fix fails twice, stop and ask for guidance.

Output

• Upgrading - What's being upgraded (package, version range, or all)

• Current Versions - Before upgrade

• Target Versions - After upgrade

• Breaking Changes - From research (with migration steps)

• Migration Plan - Step-by-step (presented before execution)

• Updates Applied - Files changed, commands run

• Test Results - From verification

• Failures Fixed - If any (with explanations)

• Remaining Issues - Requires manual intervention