migration-pack-builder

name	migration-pack-builder
description	Generate structured migration plans with inventory, risk-ranked sequence, rollback procedures, and acceptance criteria for major upgrades or framework migrations. Use when upgrading major dependencies (React 17→18, Python 3.9→3.12), migrating frameworks (Express→Fastify, CRA→Vite), or scoping 'modernize the codebase' initiatives. Do not use for patch-level dependency updates or greenfield projects.
license	Apache-2.0
compatibility	{"clients":["openai-codex","gemini-cli","opencode","github-copilot"]}

Migration Pack Builder

Turns "we need to upgrade X" into a methodical execution plan.

Procedure

1. Create migration inventory

Identify all affected surfaces:

## Inventory: [Migration Name]

### Direct Dependencies
| Package | Current | Target | Breaking Changes |
|---------|---------|--------|------------------|
| [name]  | [ver]   | [ver]  | [list]           |

### Affected Files
- [path pattern] ([N] files) — [why affected]

### Integration Points
- CI/CD: [changes needed]
- Testing: [framework upgrade required?]
- Build tooling: [changes needed]

2. Risk assessment per component

Risk Level	Criteria	Examples
High	Core business logic, payment, auth, data persistence	Payment processing, auth flow
Medium	UI components, utilities with many dependents	Shared component library
Low	Dev tooling, test utilities, isolated features	Linter config, test helpers

3. Define migration sequence

Order by: dependencies first, then risk (low → high):

### Migration Sequence
1. [ ] Update build tooling (low risk, unblocks others)
2. [ ] Migrate test utilities (enables validation of later stages)
3. [ ] Low-risk leaf components (build confidence)
4. [ ] Core utilities (high dependency count)
5. [ ] High-risk business logic (with extra validation)

4. Define rollback procedure per stage

### Rollback: Stage N
- Git: `git revert HEAD~N..HEAD`
- Dependencies: `npm ci` from lockfile at tag `pre-stage-N`
- Verification: `npm test && npm run e2e`

5. Define acceptance criteria

### Acceptance Criteria
- [ ] All existing tests pass (or intentional updates documented)
- [ ] No type errors introduced
- [ ] Bundle size delta < 5%
- [ ] Performance metrics maintained
- [ ] Manual QA of critical user flows

Output contract

# Migration Pack: [Name] — [From] → [To]

## Summary
- Scope: [N] files, [N] packages
- Estimated effort: [X] days
- Risk level: [High/Medium/Low]

## Inventory
[tables from step 1]

## Migration Sequence
[ordered stages with checkboxes]

## Rollback Procedures
[per-stage rollback]

## Acceptance Criteria
[checklist]

## Known Issues & Workarounds
[documented blockers and solutions]

Failure handling

• Circular dependencies in migration order: Identify cycle; create compatibility shim to break it
• No test coverage for affected code: Add characterization tests BEFORE migration
• Breaking change not documented upstream: Check GitHub issues and changelogs; document findings
• Partial migration blocks progress: Always use feature branches with atomic commits per stage