maestria-co/upgrade-repo
skills/upgrade-repo/SKILL.md
Safely upgrade a language version, framework, or major dependency. Use when someone says "upgrade Node to v22", "migrate to React 19", "we need to get off this old version", "update our framework", or "how do we upgrade X?". Also triggers when a security advisory requires a version bump. Scope is infrastructure only: manifests, lock files, build configuration, and source changes required by the new version. Content drift discovered during an upgrade (outdated docs, stale patterns) is out of scope — delegate those to `context-maintenance`. Prevents the most common upgrade pitfalls: skipping migration guides, multi-major jumps, and losing rollback options.
development
Updated Apr 26, 2026
$ install --global
skillsauthnpx skillsauth add maestria-co/ai-playbook upgrade-repoInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 26, 2026, 6:42 AM59.5s1 file scanned
SKILL.md
- name:
- upgrade-repo
- description:
- >
- security advisory requires a version bump. Scope is infrastructure only:
- manifests,
- pitfalls:
- skipping migration guides, multi-major jumps, and losing rollback options.
Skill: Upgrade Repo
Purpose
Upgrade language versions, frameworks, and major dependencies safely 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.
Pre-Upgrade
1. Research Before Touching Code
Read the official release notes, migration guide, and CHANGELOG for the new version:
- What is removed or renamed?
- What patterns are deprecated?
- Are there any required migration steps?
Skipping the migration guide is the #1 cause of upgrade pain — breaking changes are always documented.
2. Check Dependency Compatibility
Verify your direct dependencies support the new version. Run your package manager's outdated/audit command and check whether dependencies need to update alongside the upgrade.
3. Assess Scope
Search the codebase for deprecated API usage before starting. This turns vague fear into a concrete list of files to update and helps you estimate the effort.
4. Create a Dedicated Branch and Tag
git checkout -b upgrade/[name]-[old-version]-to-[new-version]
git tag pre-upgrade-[name]-$(date +%Y%m%d)
git push origin pre-upgrade-[name]-$(date +%Y%m%d)
The tag is your rollback anchor — push it before making any changes.
Upgrade Process
Rule: One Major Version at a Time
Never jump multiple major versions in one step. If upgrading Node 16 → 22, go 16 → 18 → 20 → 22. Verify tests pass after each step. This isolates which version introduced each breakage and keeps PRs reviewable.
Per-Version Steps
-
Update version in the manifest (
package.json,pyproject.toml,go.mod, etc.)
Commit this change before installing so the diff is readable. -
Install dependencies — check the output for conflicts
-
Fix build errors first — imports, syntax, renamed APIs — before running tests.
Fix in order: import errors → syntax → type errors → API changes.
Commit after each logical group of fixes. -
Run tests — fix failures one at a time, commit each fix separately.
-
Address deprecation warnings — these become errors in the next major version, so clearing them now prevents the next upgrade from being painful.
-
Commit the working state before advancing to the next major version.
Post-Upgrade
Verification Checklist
- [ ] All tests pass (unit, integration, e2e)
- [ ] Build succeeds with no errors or unaddressed deprecation warnings
- [ ] Critical user paths tested manually
- [ ] Performance hasn't regressed (startup time, key latencies)
- [ ] Dependencies are compatible with the new version
Document in .context/
Add a decision record at .context/decisions/upgrade-[package]-[date].md:
# Upgrade [Package] to [New Version]
## Decision
Upgraded from [old] to [new] on [date].
## Rationale
[Why: security fix / new features / dependency requirement]
## Breaking Changes & Mitigations
- [Change]: [how we addressed it]
## Migration Notes
[Patterns that changed; new best practices to follow going forward]
## Rollback
Tag: `pre-upgrade-[name]-[date]`
Rollback Procedure
# Revert to the pre-upgrade state
git checkout pre-upgrade-[name]-[date]
git checkout -b rollback/[package]-[date]
# Restore dependencies and verify
[install command] # npm install / pip install / etc.
[test command]
If the upgrade must be abandoned entirely, delete the upgrade branch and document
the reason in .context/decisions/.
Constraints
- Read the migration guide before writing any code
- One major version per upgrade branch — not multiple
- Scope is infrastructure only — manifests, lock files, build config, and source changes
required by the new version. If you discover outdated documentation or stale patterns during
the upgrade, note them and delegate to
context-maintenance— do not fix them in this branch - Merge only when all tests are green
- Never upgrade in a production hotfix branch — upgrades need dedicated branches and full testing
- Always tag before upgrading so you can roll back
- Document the rationale — future maintainers need to know why the version changed
Related Skills
maestria-co/writing-tests
development
VerifiedTrustedCommunity
Writes and runs a test suite for a piece of code, covering happy path, edge cases, error cases, and security cases. Use when: implementation is complete and needs test coverage, a bug needs a reproduction test and fix validation, or code needs coverage before a refactor. Do not use when: the code under test is not yet implemented, or the spec is still unclear.
SKILL.mdUpdated Apr 26, 2026
maestria-co/writing-skills
testing
VerifiedTrustedCommunity
Use when creating a new skill, editing an existing skill, or helping a user author a skill for this system. Covers structure, discoverability, quality, and discipline hardening.
SKILL.mdUpdated Apr 26, 2026
maestria-co/verification-checklist
development
VerifiedTrustedCommunity
Evidence-based verification process to run before marking any task complete. Use this skill every time you're about to report that work is done — for features, bug fixes, refactoring, or any code change. This catches the most common failure mode: declaring "done" without proof. If you're finishing up and about to tell the user the task is complete, run this checklist first.
SKILL.mdUpdated Apr 26, 2026
maestria-co/using-skills
development
VerifiedTrustedCommunity
Teaches agents how to discover, select, and invoke skills from the skill library. Use this skill whenever you're uncertain which skill applies to a task, when composing multiple skills for complex work, or when you need to understand what skills are available. This is your go-to when facing an ambiguous task and need to figure out the right approach before diving into implementation.
SKILL.mdUpdated Apr 26, 2026