codebase-migrate

Codebase Migrate

Use This Skill When

• Upgrading frameworks (React 17→19, Django 4→5, Node 18→22)
• Renaming APIs or functions across entire codebase
• Migrating configurations (webpack→vite, eslint→biome, jest→vitest)
• Refactoring file structures or naming conventions
• Running codemods on 100+ files simultaneously
• Coordinating changes across monorepos or large projects
• Need reviewable, batched PRs for large-scale changes

When NOT to Use

• Small single-file changes (use direct edits instead)
• When you want all changes in one massive PR
• Projects without test coverage (risky to batch migrate)
• Custom migrations with complex manual logic
• When CI/CD pipeline is not stable

Context: Migration Maturity

Undeveloped: Single massive PR, hard to review, hard to debug failures.

Target: Changes batched into 25–50 file chunks, each PR passes CI, easy to revert per-batch.

Optimized: Fully automated pipelines, parallel batch testing, quick rollback, minimal manual intervention.

Core Principle

Large codebase migrations succeed when broken into small, reviewable, verifiable chunks. Batch changes to keep PRs under 10–15 files each, run full tests per batch, and use issue tracking to maintain checkpoint progress.

Prerequisites

curl -fsSL https://composio.dev/install | bash
composio login
composio link github        # PR creation + CI status
composio link linear        # Issue tracking (or jira)

Local Tools Required:

• git (version control)
• rg / grep (file search)
• jscodeshift / ts-morph / comby / ast-grep (language-specific codemods)
• Test runner for your language

Instructions

Step 1: Define and Scope the Transform

Good Definition Example:

• ✓ "Replace jest.mock with vi.mock, swap jest.fn() for vi.fn(), rename jest.config.js → vitest.config.ts"

Bad Definition Example:

• ✗ "Migrate to vitest" (too vague)

Scope the Blast Radius:

# Find all files that need changes
rg -l 'jest\.(mock|fn|spyOn)' | wc -l
rg -l 'from "jest"' | sort | wc -l