ruby-upgrade-toolkit

ruby-upgrade-toolkit

A Claude Code plugin for upgrading Ruby projects safely — including Ruby on Rails apps. Supports any Ruby version upgrade (2.7→3.x and beyond) and any Rails version upgrade (5→8), separately or together.

How It Works

The plugin gives Claude a structured, repeatable methodology for Ruby and Rails upgrades. The six commands compose — use as many or as few as you need. A sixth command — rules — is optional: it manages a project-local policy file (gem pins, gem swaps, Rails LTS / Sidekiq Pro substitutions, extra verification gates like Brakeman) that the other commands pick up automatically.

Mode 1: Fully automated

/ruby-upgrade-toolkit:upgrade ruby:X.Y.Z [rails:X.Y]

One command runs everything: detects versions, validates compatibility, computes the full upgrade path (including intermediate versions), creates a live task list, applies fixes phase by phase, verifies after each phase, and pauses with a recovery menu if anything fails.

Use this when you want to move quickly and trust Claude to sequence and execute the work.

Mode 2: Review first, then automate (recommended for first-time upgrades)

/ruby-upgrade-toolkit:audit ruby:X.Y.Z [rails:X.Y]   # understand the scope
/ruby-upgrade-toolkit:plan ruby:X.Y.Z [rails:X.Y]    # review the phase sequence
/ruby-upgrade-toolkit:upgrade ruby:X.Y.Z [rails:X.Y] # execute the plan

audit surfaces breaking changes and gives an effort estimate before touching any code. plan shows exactly which phases will run, in what order, and — in its Estimate Summary — the effort, risk, blast radius, and confidence for each phase so you can sanity-check scope and sequencing. Once you're comfortable with the plan, upgrade executes the same sequence automatically — no need to re-specify anything.

Use this when you're doing a major version jump, have a large codebase, or want to understand the scope before committing to execution.

Mode 3: Fully manual (maximum control)

/ruby-upgrade-toolkit:audit ruby:X.Y.Z [rails:X.Y]   # read-only scan
/ruby-upgrade-toolkit:plan  ruby:X.Y.Z [rails:X.Y]   # roadmap + creates a task list
/ruby-upgrade-toolkit:fix   next                     # apply next pending phase; repeat

plan creates a TodoWrite task list (one task per phase); fix next reads the list, picks the first pending task, applies it, verifies, prompts you for commit, and ticks it off. Iterate fix next until the list is empty. You can also pass explicit args to fix to jump to a specific phase — useful when resuming or working out of order.

Use this when you want to inspect and approve changes phase by phase, apply fixes to a specific scope (scope:path), or resume a partially completed upgrade.

Manual and automated share the same machinery. /upgrade is a loop of /fix next calls around the same TodoWrite task list that /plan creates, plus some pre-loop prerequisite checks (branch, Ruby installs) and a post-loop Final infra check (CI/CD, Dockerfiles). If you already ran /plan and did a few /fix next iterations manually, /upgrade reuses that list as-is (target-matching) and picks up where you left off — progress is preserved. If the invocation target differs or no list exists, upgrade regenerates the list via /plan. Either way, the per-phase work is byte-identical.

Why the order matters:

• audit is read-only — zero risk, surfaces breaking changes and effort before touching anything
• plan sequences work correctly (Ruby phases before Rails phases, intermediate versions in the right order), quantifies each phase (effort, risk, blast radius, confidence), and creates the task list that drives the rest of the workflow
• fix next consumes the next pending task from the list; on successful commit it ticks the task off. Repeat until the list is empty.
• status is an on-demand dashboard — useful for a full health snapshot, though fix's built-in verification is what gates the commit

Installation

Via Claude Code marketplace

Add the marketplace and install the plugin:

/plugin marketplace add dhruvasagar/ruby-upgrade-toolkit
/plugin install ruby-upgrade-toolkit@dhruvasagar

Or use the interactive UI: run /plugin, go to the Discover tab, search for ruby-upgrade-toolkit, and click Install.

Local development

git clone https://github.com/dhruvasagar/ruby-upgrade-toolkit

Then add the cloned directory as a local marketplace and install:

/plugin marketplace add /path/to/ruby-upgrade-toolkit
/plugin install ruby-upgrade-toolkit
/reload-plugins

Updating

Marketplace install

Uninstall and reinstall to get the latest version:

/plugin uninstall ruby-upgrade-toolkit@dhruvasagar
/plugin install ruby-upgrade-toolkit@dhruvasagar

Then reload without restarting Claude Code:

/reload-plugins