Full Codebase Migrator

Full Codebase Migrator

Leverage the full 1M token context window to ingest an entire codebase, understand its architecture end-to-end, and produce a comprehensive, file-by-file migration plan that a team can execute sequentially without conflicts.

Contents

• references/migration-types.md -- supported migration types; when to use and when not to use this skill.
• references/ingestion.md -- architecture, glob patterns, metadata collection, read order, context budgeting, and dependency graph construction (Steps 0-2).
• references/workflow-detail.md -- per-file assessment, migration order, risk scoring, and effort estimation templates (Steps 3-6).
• references/output-template.md -- migration-plan.md and migration-plan.json templates, edge cases, and the final quality checklist (Steps 7-8).

Workflow

1. Identify scope. Determine migration type, scope (full repo or directory), output location for migration-plan.md, and any exclusions or constraints. Infer from the user's prompt when already specified. See references/migration-types.md for supported types and fit. 2. Ingest the codebase. Glob all source files, collect metadata with Bash (line counts, package manifest, configs, git history, directory tree), then Read every source file. For 500+ file codebases, dispatch Agent sub-agents to read directory subtrees in parallel. See references/ingestion.md. 3. Build the dependency graph. Extract every import, build an adjacency list, classify each file into layers, detect circular dependencies, and classify external dependencies. See references/ingestion.md. 4. Assess each file. Produce a per-file migration assessment covering layer, complexity, patterns found, required changes, prerequisite dependencies, risk factors, and testing impact. See references/workflow-detail.md. 5. Calculate migration order. Run a topological sort by layer, apply practical adjustments (quick wins, high-risk-early, break cycles first), and group files into buildable, PR-sized phases. See references/workflow-detail.md. 6. Assess risk. Score each file 1-5 on complexity, centrality, volatility, test coverage, and external coupling. Build the migration-level risk matrix and rollback strategy. See references/workflow-detail.md. 7. Estimate effort. Derive per-file, per-phase, and total estimates with overhead and a 20% buffer, then translate into calendar time by team size. See references/workflow-detail.md and the effort calibration table in references/migration-types.md. 8. Generate the deliverable. Write migration-plan.md to the output location, and migration-plan.json when machine-readability helps. Verify against the quality checklist before delivering. See references/output-template.md.

Edge Cases

Codebases too large for context, monorepos, partially migrated codebases, and codebases without tests each need adjusted handling. See references/output-template.md.

Codebase Ingestion Reference

Detail for Step 1 (Full Codebase Ingestion) and Step 2 (Dependency Graph).

Architecture

Commander
 |
 |-- Phase 1: Full Ingestion (sequential, read everything)
 |    |-- Glob: discover all source files
 |    |-- Read: ingest every file into context
 |    |-- Bash: collect metadata (line counts, git history, package.json)
 |
 |-- Phase 2: Analysis (in-context reasoning)
 |    |-- Dependency graph construction
 |    |-- Complexity scoring per file
 |    |-- Risk classification
 |    |-- Migration pattern matching
 |
 |-- Phase 3: Plan Generation (Write output)
 |    |-- migration-plan.md (the deliverable)
 |    |-- Optional: migration-plan.json (machine-readable)

Glob Patterns by Migration Type

JS to TS:        **/*.{js,jsx,mjs,cjs}
React migration: **/*.{js,jsx,ts,tsx}
Vue migration:   **/*.{vue,js,ts}
Angular:         **/*.{ts,html,scss,css}
General:         **/*.{js,jsx,ts,tsx,vue,svelte,css,scss,json,yaml,yml,md}

Always exclude:

node_modules/**   dist/**   build/**   .next/**   coverage/**
*.min.js   *.bundle.js   package-lock.json   yarn.lock   pnpm-lock.yaml

Metadata Collection (Bash)

1. Line counts -- wc -l on every discovered file. Drives effort estimation. 2. Package manifest -- read package.json (or equivalent) for dependencies, scripts, config. 3. Config files -- read tsconfig.json, .babelrc, webpack.config.js, vite.config.ts, .eslintrc, .prettierrc, and any others. 4. Git history -- git log --oneline -20 for recent context; git log --all --pretty=format:"%h %s" --diff-filter=M -- "*.js" (adjust per migration type) to see which files change most frequently. 5. Directory structure -- find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' to map the layout.

Read Order

1. Entry points: index.js, App.js, main.js, server.js, or equivalents. 2. Config files: tsconfig, webpack, vite, eslint, babel. 3. Shared utilities, types, constants. 4. Feature files grouped by directory. 5. Test files last.

For large codebases (500+ files), use Agent sub-agents to read files in parallel batches. Each agent reads a directory subtree and returns file contents plus a brief summary.

Context Budget Management

• Files under 1000 lines: read in full. Prioritize 500-1000 line files -- they are the riskiest to migrate.
• Files 1000+ lines: read first 500 lines + last 100 lines + any class/function declarations. Flag for manual review.
• If total source exceeds ~800K tokens, prioritize: entry points > shared code > feature code > tests > styles. Note which files were partially read or skipped.

Dependency Graph Construction

Import Analysis

For every file, extract:

• Static imports: import X from './path', const X = require('./path')
• Dynamic imports: import('./path'), require.resolve('./path')
• Re-exports: export { X } from './path'
• Side-effect imports: import './styles.css'
• Type-only imports (TS): import type { X } from './path'

Build an adjacency list:

{
  "src/App.tsx": {
    "imports": ["src/components/Header.tsx", "src/hooks/useAuth.ts", "src/utils/api.ts"],
    "importedBy": ["src/index.tsx"],
    "externalDeps": ["react", "react-router-dom"]
  }
}

Layer Classification

Classify every file into one layer (top = most depended upon):

1. Foundation -- types, interfaces, constants, enums, config. Imported by many, imports few. 2. Utilities -- helpers, formatters, validators. Imported by features, imports foundation. 3. Services -- API clients, data access, state management. Imports utilities and foundation. 4. Components/Features -- UI components, route handlers, feature modules. 5. Pages/Routes -- top-level page compositions. Imports components. 6. Entry Points -- index.js, App.js, server.js. Imports pages. 7. Tests -- import everything, imported by nothing. 8. Config -- build/linter configs. Usually standalone.

Cycles

Detect circular dependencies. A cycle means files cannot migrate independently. Flag all cycles and recommend resolution strategies.

External Dependency Classification

• Compatible: works with both source and target (no changes).
• Needs Update: has a target-compatible version (update version).
• Needs Replacement: incompatible with target (find alternative).
• Needs Wrapper: works with an adapter/wrapper pattern.
• Must Remove: no path forward (rewrite functionality).

Supported Migration Types

When to Use This Skill

• Planning a major technology migration that needs a complete inventory before starting.
• Understanding the full blast radius of a framework or language change.
• Estimating effort and risk before committing to a migration.
• Producing a deterministic execution order that respects the dependency graph.
• Handing off a migration plan to a team with clear, file-level instructions.

When NOT to Use This Skill

• Single-file conversions (do them directly).
• Codebases with fewer than 5 files (overkill).
• When the migration should execute immediately (this skill plans; use agent-army to execute).

Output Template Reference (Steps 7 and 8)

Templates the skill emits as its deliverables.

Step 7: migration-plan.md Structure

Write the final deliverable to the specified output location using this structure:

# Migration Plan: [Source] to [Target]

Generated: [timestamp]
Codebase: [repo name / path]
Total files: [N]
Estimated effort: [Xh]
Estimated calendar time: [X days] ([N developers])

---

## Table of Contents

1. Executive Summary
2. Migration Type
3. Codebase Inventory
4. Dependency Graph
5. External Dependencies
6. Migration Phases
7. File-by-File Changes
8. Risk Assessment
9. Effort Estimation
10. Rollback Strategy
11. Pre-Migration Checklist
12. Post-Migration Verification

## Executive Summary

[2-3 paragraph overview: what is being migrated, why, key risks, estimated effort,
recommended approach (big bang vs incremental), and team recommendations]

## Migration Type

- From: [source technology/framework/pattern]
- To: [target technology/framework/pattern]
- Scope: [full repo / specific directories]
- Strategy: [incremental (recommended for 50+ files) / big bang (viable for <50 files)]

## Codebase Inventory

### File Distribution by Type
| File Type | Count | Total Lines | % of Codebase |
|-----------|-------|-------------|---------------|
| .js | N | N | N% |
| .jsx | N | N | N% |
| ... | ... | ... | ... |

### Directory Structure
[tree output, annotated with migration notes]

### File Size Distribution
| Range | Count | Notes |
|-------|-------|-------|
| < 50 lines | N | Quick migrations |
| 50-150 lines | N | Standard effort |
| 150-300 lines | N | Moderate effort |
| 300-500 lines | N | Significant effort |
| 500+ lines | N | Consider splitting before migrating |

## Dependency Graph

### Layer Classification
[Table of all files classified into Foundation / Utilities / Services / Components / Pages / Entry Points / Tests / Config]

### Critical Path
[Files with highest centrality -- the backbone of the codebase, must migrate cleanly]

### Circular Dependencies
[List of cycles with recommended resolution]

## External Dependencies

| Package | Current | Status | Action | Replacement |
|---------|---------|--------|--------|-------------|
| react | 18.2.0 | Compatible | None | -- |
| lodash | 4.17.21 | Compatible | None | -- |
| moment | 2.29.4 | Needs Replacement | Replace | dayjs or date-fns |
| ... | ... | ... | ... | ... |

## Migration Phases

[Phase-by-phase breakdown as defined in Step 4]

## File-by-File Changes

[Every file's migration assessment as defined in Step 3, organized by phase]

## Risk Assessment

[Risk matrix and macro risks as defined in Step 5]

## Effort Estimation

[Effort tables as defined in Step 6]

## Rollback Strategy

[Rollback plan as defined in Step 5]

## Pre-Migration Checklist

- [ ] All team members have read this plan
- [ ] Target framework/library versions agreed upon
- [ ] CI pipeline updated to support target (e.g., TypeScript compiler added)
- [ ] Branch strategy agreed (migration branch vs feature flags)
- [ ] Code freeze scheduled for foundation phase (if applicable)
- [ ] Rollback procedure tested
- [ ] Performance benchmarks captured (before state)
- [ ] Test suite passing at 100% before migration starts

## Post-Migration Verification

- [ ] All files migrated per plan
- [ ] Zero source-pattern files remaining (e.g., no .js files if migrating to TS)
- [ ] Build passes with zero errors
- [ ] Test suite passes at 100%
- [ ] No `any` types remaining (or documented exceptions)
- [ ] Performance benchmarks comparable to pre-migration
- [ ] Documentation updated
- [ ] Team trained on new patterns

Step 8: Optional migration-plan.json

If the user requests it (or for large migrations where machine-readability helps), also generate migration-plan.json:

{
  "metadata": {
    "generated": "ISO timestamp",
    "migrationFrom": "JavaScript",
    "migrationTo": "TypeScript",
    "totalFiles": 111,
    "estimatedHours": 51.6
  },
  "files": [
    {
      "path": "src/utils/helpers.js",
      "targetPath": "src/utils/helpers.ts",
      "lines": 145,
      "layer": "utility",
      "phase": 2,
      "phaseOrder": 3,
      "difficulty": 2,
      "estimatedMinutes": 20,
      "riskScore": 1.8,
      "dependencies": ["src/types/index.ts"],
      "dependedOnBy": ["src/services/api.ts", "src/components/Form.tsx"],
      "patterns": ["add-types", "update-imports"],
      "notes": "Pure functions, straightforward typing"
    }
  ],
  "phases": [],
  "dependencies": {},
  "risks": [],
  "externalDeps": []
}

Edge Cases

Codebase Too Large for Context

1. Prioritize by layer -- read foundation and utility layers in full, sample feature layers. 2. Use Agent sub-agents -- deploy agents to read and summarize subsections. Each agent reads one directory subtree and returns a structured summary (file list, import graph, patterns found). 3. Aggregate summaries -- the commander combines all sub-agent summaries into the full picture. 4. Flag gaps -- note clearly which files were summarized vs fully analyzed.

Monorepo with Multiple Packages

1. Treat each package as a semi-independent migration. 2. Identify cross-package dependencies. 3. Generate a per-package plan plus a top-level orchestration plan. 4. Recommend migration order across packages (shared libs first, apps last).

Mixed Codebase (Already Partially Migrated)

1. Identify which files are already in the target state. 2. Classify files as: migrated, partially migrated, not migrated. 3. Focus the plan on unmigrated files. 4. Note partially migrated files that need completion.

No Tests Exist

1. Flag this as a HIGH risk factor. 2. Recommend adding integration tests for critical paths BEFORE migrating. 3. Include a pre-migration test authoring phase in the plan.

Quality Checklist for the Plan

Before delivering, verify:

• [ ] Every source file is accounted for (inventory matches glob results)
• [ ] Every file has a phase assignment
• [ ] No file depends on an unmigrated file in a later phase (topological order holds)
• [ ] All external dependencies are classified
• [ ] Effort estimates sum correctly
• [ ] Risk scores are calculated and documented
• [ ] Circular dependencies are identified and have resolution strategies
• [ ] The plan is actionable -- a developer can pick up Phase 1 and start immediately
• [ ] Rollback strategy is defined
• [ ] Pre-migration and post-migration checklists are included

Workflow Detail: Steps 3 through 6

Expanded procedure for the analysis, ordering, risk, and effort steps of the skill.

Step 3: Per-File Migration Assessment

Produce this assessment for every source file:

### [relative/path/to/file.js]

- Lines: 245
- Layer: Component
- Complexity: Medium
- Imports: 8 internal, 3 external
- Imported by: 4 files
- Migration difficulty: 3/5
- Estimated effort: 30 minutes
- Risk level: Medium

Current patterns found:
- Class component with 3 lifecycle methods (componentDidMount, componentDidUpdate, componentWillUnmount)
- Local state with this.setState (5 occurrences)
- Refs via createRef (2 occurrences)
- HOC wrapper (withRouter)

Required changes:
1. Convert class to function component
2. Replace lifecycle methods with useEffect hooks
3. Replace this.state/this.setState with useState hooks
4. Replace createRef with useRef hooks
5. Replace withRouter HOC with useRouter/useNavigate hooks
6. Add TypeScript types for props (currently PropTypes)
7. Add TypeScript types for state shape
8. Update imports from '.js' to '.ts' extensions (if applicable)

Dependencies that must migrate first:
- src/types/user.ts (needs TypeScript types defined)
- src/hooks/useAuth.ts (referenced hook must exist)

Risk factors:
- Complex componentDidUpdate with multiple conditions -- requires careful useEffect dependency array
- Ref forwarding pattern may need forwardRef wrapper

Testing impact:
- src/__tests__/UserProfile.test.js must be updated (enzyme shallow render -> testing library render)

Step 4: Migration Order Calculation

Base Order (Topological Sort)

1. Foundation (types, constants, config) 2. Utilities 3. Services 4. Components (leaf components before composite components) 5. Pages 6. Entry points 7. Tests last

Practical Adjustments

• Quick wins first: within each layer, prioritize small/simple files. Early success builds momentum.
• High-risk files early: migrate complex files while the team is fresh.
• Batch by feature: group files so a single PR migrates a complete feature.
• Shared code before consumers: any file imported by 5+ others migrates before its consumers.
• Break cycles first: resolve circular dependencies before migrating either file in the cycle.

Phase Grouping

Each phase should:

• Be completable in 1-3 days by one developer.
• Contain files migratable without touching files in later phases.
• Result in a buildable, testable codebase when complete.
• Map to a single PR or small set of PRs.

## Phase 1: Foundation (Day 1)
- Estimated effort: 4 hours
- Files: 12
- Risk: Low
| # | File | Lines | Effort | Notes |
|---|------|-------|--------|-------|
| 1 | src/types/index.ts | 45 | 15m | Already TS, just verify |
| 2 | src/constants/config.ts | 30 | 10m | Rename .js to .ts, add types |
| ... | ... | ... | ... | ... |

Step 5: Risk Assessment

File Risk Scores

Score each file 1-5 on:

• Complexity: lines of code, cyclomatic complexity, number of patterns to change.
• Centrality: number of dependents (high centrality = high blast radius).
• Volatility: git change frequency (high volatility = merge conflict risk).
• Test Coverage: presence of tests (no tests = higher risk).
• External Coupling: tight integration with third-party libraries needing replacement.

Overall risk = weighted average: Complexity(0.25) + Centrality(0.30) + Volatility(0.15) + TestCoverage(0.15) + ExternalCoupling(0.15).

Migration-Level Risks

Rollback Strategy

• Each phase maps to a PR. Revert the PR to roll back.
• Maintain a migration branch. If the migration stalls, the main branch is untouched.
• Document the point of no return (usually after Phase 1 merges to main).

Step 6: Effort Estimation

Per-File Estimates

Per-Phase Estimates

• Overhead per phase: 30 minutes for PR creation, review, CI, merge.
• Integration testing: 15 minutes per phase to verify nothing broke.
• Buffer: add 20% for unexpected issues.

Total Estimate

## Effort Summary

| Phase | Files | Raw Effort | Buffer (20%) | Total |
|-------|-------|-----------|-------------|-------|
| 1. Foundation | 12 | 3h | 0.6h | 3.6h |
| 2. Utilities | 18 | 6h | 1.2h | 7.2h |
| 3. Services | 8 | 4h | 0.8h | 4.8h |
| 4. Components | 35 | 16h | 3.2h | 19.2h |
| 5. Pages | 10 | 5h | 1h | 6h |
| 6. Entry Points | 3 | 1h | 0.2h | 1.2h |
| 7. Tests | 25 | 8h | 1.6h | 9.6h |
| Total | 111 | 43h | 8.6h | 51.6h |

- Calendar time (1 dev): ~7 working days
- Calendar time (2 devs): ~4 working days
- Calendar time (3 devs, parallelized): ~3 working days

Note: Phases 1-3 are sequential. Phases 4-7 can partially parallelize across developers.

Effort Calibration by Migration Type

Per-file effort multipliers. Starting estimates -- adjust after ingestion.