upgrade-repo

Automate one-major-version-at-a-time upgrades with rollback points and verification.

Updated Mar 2, 2026
One-click install
npx skills add https://github.com/maestria-co/ai-playbook --skill upgrade-repo
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: upgrade-repo
Source: https://github.com/maestria-co/ai-playbook/tree/main/skills/upgrade-repo
Command: npx skills add https://github.com/maestria-co/ai-playbook --skill upgrade-repo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Safely upgrade language versions, frameworks, and major dependencies with a structured pre/during/post process and a clear rollback plan. The goal is to stay in control at every step: understand breaking changes before touching code, verify the build after each fix, and keep commits granular enough that any problem can be isolated and reverted.

Core Features & Use Cases

  • One major version at a time upgrades to avoid cascading issues and reduce blast radius.
  • Branching, tagging, and a dedicated rollback anchor to enable precise rollbacks if something goes wrong.
  • End-to-end upgrade lifecycle including pre-upgrade research, dependency compatibility checks, per-version steps (update, install, fix builds, run tests, address deprecations), and post-upgrade verification.

Quick Start

Create a dedicated upgrade branch, consult migration guides, and apply changes incrementally with tests so each change remains isolated and reversible.

Frequently Asked Questions about upgrade-repo

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I safely upgrade major framework versions without breaking my codebase?

To safely upgrade major framework versions, apply changes incrementally one major version at a time. This structured approach enforces pre-upgrade research, dedicated branching, and post-upgrade verification to isolate breaking changes and maintain a clear rollback path.

What is the best way to handle dependency migrations across Node and Python?

Handling dependency migrations across Node and Python requires checking compatibility and consulting migration guides before touching code. The process involves structured per-version steps: update, install, fix builds, run tests, and address deprecations deterministically.

How do I create a rollback anchor before upgrading language versions?

Creating a rollback anchor before upgrading language versions involves branching and tagging your codebase. This establishes a dedicated, precise revert point so that if post-upgrade verification fails, you can isolate and revert granular commits without cascading issues.

Can I upgrade multiple major dependency versions simultaneously?

Upgrading multiple major dependency versions simultaneously is not recommended. To reduce the blast radius and avoid cascading issues, upgrades should be applied one major version at a time with explicit testing and build verification between each step.

Why does my build fail after a language version upgrade?

A build fails after a language version upgrade because of unaddressed breaking changes or dependency incompatibilities. Resolving this requires a structured process of consulting migration guides, fixing builds incrementally, and running tests after each per-version step.

When do I need a structured pre-upgrade research process for dependencies?

You need a structured pre-upgrade research process for dependencies when tackling major version bumps. Understanding breaking changes and checking dependency compatibility before modifying code ensures deterministic, auditable changes and prevents unexpected build failures.