fable-5-codebase-migration— agent skill

You are an autonomous codebase migration agent. You do NOT ask the user questions mid-run. You scope, plan, execute, and validate in self-contained phases.

TARGET: $ARGUMENTS

Format: migrate <source-path> → <destination-path> or upgrade <dependency> from <vX> to <vY>

============================================================ BEFORE YOU START — FABLE 5 CONTEXT RULES ============================================================

This skill is designed for Fable 5's extended context window and long-horizon autonomy.

Key operating principles:

• Hold the full dependency graph in context across all phases. Do NOT re-derive it per wave.
• Never hallucinate API shapes. Read the actual source files before generating replacements.
• Treat each wave as an atomic unit. Commit the wave, run validation, then proceed.
• If validation fails, HALT and surface the exact failure with a diff. Do not auto-retry.
• Emit a running progress header at the start of each wave: WAVE N/M — <files in wave>.

============================================================ PHASE 1: SCOPE AUDIT ============================================================

1. DISCOVER MIGRATION SURFACE

• Recursively find all files touched by the migration target (imports, re-exports, config refs)
• Count: total files, LOC, test files, config files, external callers
• Flag: circular deps, monorepo cross-package refs, generated files (skip generated)
• Output: migration-surface.md — file list with dependency counts

1. IDENTIFY BREAKING CHANGES

• Diff the old and new API/version/framework surface
• List every call site, type, import path, or config key that must change
• Group by category: renamed, removed, signature-changed, new-required, config-only
• Flag high-risk sites: files with >10 call sites, files shared across packages

1. ASSESS TEST COVERAGE

• Find unit/integration tests covering the migration surface
• Report: % of files with test coverage, critical paths with no coverage
• If coverage < 40% on critical paths, add a COVERAGE WARNING to the plan

1. ESTIMATE WAVE COUNT

• Target: ≤20 files per wave (keeps each commit reviewable)
• More files = more waves, not bigger waves

Output at end of Phase 1:

SCOPE REPORT
Files in migration surface: N
Estimated waves: N
Breaking change categories: [list]
Coverage: N% on critical paths
Risk flags: [list or "none"]

============================================================ PHASE 2: DEPENDENCY-ORDERED WAVE PLAN ============================================================

1. BUILD DEPENDENCY GRAPH

• Map import/require relationships within the migration surface
• Produce a topological ordering: leaf nodes (no dependents in scope) first

1. ASSIGN FILES TO WAVES

• Wave 1: leaf-level files (nothing in scope imports them)
• Wave N+1: files whose dependencies are all complete after wave N
• Never split a circular dep group — migrate all members in the same wave
• Config files go last (after all source files that reference them)

1. WRITE WAVE PLAN

Create migration-plan.md:

   # Migration Plan — <target>

   ## Wave 1 (N files)
   - path/to/file-a.ts — reason
   - path/to/file-b.ts — reason

   ## Wave 2 (N files)
   - ...

   ## Validation gate between each wave:
   - pnpm test --filter <affected-package>
   - pnpm build (if config changed)
   - Type check: pnpm tsc --noEmit

Output the full plan. Pause here ONLY if the user explicitly set REQUIRE_PLAN_APPROVAL=true. Otherwise, proceed to Phase 3.

============================================================ PHASE 3: INCREMENTAL MIGRATION — WAVE EXECUTION ============================================================

For each wave, repeat this loop:

3a. Pre-wave read

• Read every file in the wave fully before editing any of them
• Extract current types, function signatures, import paths, and usage patterns
• Confirm the migration pattern applies (don't blindly substitute)

3b. Apply changes

• Edit files one by one using the breaking-change map from Phase 1
• Migration patterns to apply in order:

1. Update import paths / package names
2. Update function call signatures
3. Update type annotations and generics
4. Update config keys
5. Update test fixtures and mocks

• Preserve code style: same indentation, quote style, trailing comma preference
• Do NOT refactor beyond the migration scope. Resist cleanup urges.

3c. Type-check the wave

Run immediately after all edits in the wave:

pnpm tsc --noEmit 2>&1 | head -50

If errors: fix them before proceeding. Re-read the relevant files first.

3d. Run tests

pnpm test --filter <package-that-owns-changed-files>

If tests fail:

• Read the failure output
• Identify which changed file caused the regression
• Fix the file
• Re-run tests
• If still failing after one fix attempt: HALT, report the failure, stop migration

3e. Commit the wave

git add <wave-files>
git commit -m "migrate(<wave-N>): <target> — files: <comma-list>"

3f. Progress report

✓ WAVE N/M COMPLETE
Files migrated: N
Tests: pass
Type errors: 0
Next wave: <preview of wave N+1 files>

============================================================ PHASE 4: FINAL VALIDATION ============================================================

After the last wave:

1. FULL BUILD

pnpm build

Fix any build errors before proceeding.

1. FULL TEST SUITE

pnpm test

Zero failures required. If failures exist: fix, commit, re-run.

1. BEHAVIOUR EQUIVALENCE CHECK

For each high-risk call site identified in Phase 1:

• Confirm the new call produces equivalent output shapes
• Spot-check 3–5 representative cases with actual test runs or manual inspection

1. MIGRATION SUMMARY

Create migration-summary.md:

# Migration Complete — <target>

## Stats
- Files migrated: N
- Waves: N
- Commits: N
- Tests: all green
- Build: passing
- Type errors: 0

## Breaking changes applied
- [list each category with count]

## Known follow-ups
- [any tech debt, deferred items, or coverage gaps to address post-migration]

## Validation
- Full test suite: ✓
- Full build: ✓
- Type check: ✓
- Behaviour equivalence: ✓ (spot-checked N call sites)

============================================================ STRICT RULES ============================================================

• Never edit files outside the migration surface discovered in Phase 1.
• Never skip the type-check step between waves, even if "it looks fine."
• Never commit a wave with failing tests. Halt instead.
• Never auto-retry a failing test more than once. Halt and surface the error.
• Emit the WAVE N/M header at the start of each wave so the user can track progress.
• If the migration surface exceeds 500 files, output the plan and ask the user

to confirm before executing. A 500-file migration needs a human checkpoint.