|

Agentic Orchestration Part 3: Tackling Major Upgrades

AI Agents

Claude

Refactoring

Major Upgrades

In Part 2, our pipeline successfully handled minor and patch updates using the /orchestrate dependency-updates command. But major version bumps are a different beast. They introduce breaking changes, modified APIs, and new architectural paradigms.

For this, we use the big gun: /orchestrate major-upgrade <repo>.

The major-upgrade Pipeline

The workflow defined in our ~/.claude/commands/orchestrate.md file looks like this:

planner -> major-upgrader -> pr-creator (loop: one PR per upgrade group)

The difference here is the loop. Let’s break it down.

1. The Planner Agent

The planner runs npx npm-check-updates --target latest to find all available major updates. Its most critical task is grouping related packages by ecosystem (e.g., all @nestjs/* or @angular/* packages).

It produces a .claude/upgrade-plan.md file and hands off the ordered list of groups to the major-upgrader.

2. The Major Upgrader Agent (The Loop)

The major-upgrader doesn’t just bump versions; it executes a strict, 7-step loop for each group defined in the plan:

  1. Create Branch: Checkout a new branch chore/upgrade-<group>-v<N>.
  2. Read Docs (MANDATORY): It actively curls the GitHub API to fetch the latest CHANGELOG.md or migration guides before touching any code.
  3. Upgrade Group: Runs pnpm add package1 package2 simultaneously.
  4. Code Adaptation: Modifies the repository code to fix breaking changes based on the migration guide.
  5. Validation Gate: Runs test -> format -> lint -> build.
  6. Iterative Fixing: If a step fails, it reads the compiler errors and attempts to fix the code up to 3 times.
  7. Handoff: It hands off the successful branch to the pr-creator.

Once the pr-creator finishes opening the GitHub PR, the major-upgrader loops back to step 1 and moves to the next ecosystem group.

True Autonomy

This is where the agentic architecture truly shines. The major-upgrader agent acts like an autonomous engineer. If it updates React Router from v5 to v6, it reads the v6 migration docs, searches your codebase for useHistory, replaces it with useNavigate, and runs the tests to ensure it worked.

But what happens when an upgrade fails completely, or a transitive dependency creates an unsolvable conflict? In Part 4, we will explore how our Orchestrator implements SemVer self-correction and rollback protocols to ensure our CI never breaks.

Keep pushing forward and savor every step of your coding journey.