Migrate

Find every usage of [the library/pattern/API being migrated away from] in this codebase.

Search for:
- Import/require statements
- Direct API calls and method usage
- Type references and interface implementations
- Configuration entries (build config, lint config, etc.)
- Usage in tests and test fixtures
- References in documentation, comments, and scripts
- Transitive usage through wrapper modules

For each usage, report: file:line, the specific API/pattern used, and surrounding context.
Group by file, sort by frequency of usage.
Report total count of usages and number of files affected.

Agent 2: Migration guide research (subagent_type: general-purpose)

Research the migration from [source] to [target].

Find:
- Official migration guide or changelog (search the web)
- Breaking changes between versions (if an upgrade)
- API mapping: old API → new API equivalents
- Known gotchas, edge cases, or compatibility issues
- Codemods or automated migration tools available
- Required peer dependency changes

Summarize as a concise mapping table: old pattern → new pattern.
Flag any changes that require manual judgment (not a 1:1 swap).

Step 2: Create the migration plan

Present the plan to the user:

## Migration Plan

**Type:** [upgrade | swap | adopt | modernize]
**From:** [current library/version/pattern]
**To:** [target library/version/pattern]

### Scope
- **Files affected:** N
- **Total usages:** N
- **Automated:** N (1:1 mappings that can be mechanically replaced)
- **Manual review:** N (changes requiring judgment)

### API Mapping
| Old | New | Notes |
|-----|-----|-------|
| ... | ... | ...   |

### Migration steps
1. [Ordered list of steps]

### Risks
- [Breaking changes, behavioral differences, or edge cases]

Wait for user confirmation before proceeding.

Step 3: Execute the migration

Apply changes in a safe order:

1. Update dependencies first — bump versions in package manifests, update lockfile
2. Apply mechanical replacements — 1:1 API swaps that don't require judgment, working file by file
3. Handle complex migrations — changes that require understanding context or choosing between alternatives
4. Update types — adjust type imports, interfaces, and generics to match the new API
5. Update configuration — build config, lint rules, babel/bundler plugins
6. Update tests — adapt test code, update mocks/stubs, fix broken assertions
7. Clean up — remove old library imports, delete compatibility shims, remove unused polyfills

Guidelines

• Work file by file — complete all changes in one file before moving to the next
• Preserve behavior — the migration should not change what the code does, only how it does it
• Don't mix refactoring with migration — resist the urge to "improve" code while migrating; that makes it harder to verify the migration is correct
• Flag ambiguous cases — when the old and new APIs aren't equivalent, flag it for the user rather than guessing
• Keep the old dependency until done — don't remove the old library from the manifest until all usages are migrated

Step 4: Verify

After applying changes:

1. Search for any remaining references to the old library/API/pattern
2. Check that no old imports or require statements remain
3. If a codemod was available, compare its output against manual changes for consistency
4. List all files modified for the user to review
5. Suggest running tests and the build to verify nothing is broken
6. If any usages couldn't be migrated automatically, list them with explanations