---

name: migration-agent description: Plan and execute large-scale codebase migrations using agent workflows. Use when user wants to migrate from one system to another or do broad refactoring. allowed-tools: "Read,Write,Bash,Grep,Glob,Edit" version: 1.0.0

Migration Agent

Plan and execute large migrations using multi-agent patterns.

Core Pattern

From Lee Robinson's cursor.com migration:

• Estimated time: 1-2 weeks → Actual time: 3 days
• Method: 344 agent requests, export scripts, parallel subagents
• Result: -322K lines deleted, $260 in tokens

Instructions

Step 1: Create Migration Plan

Ask clarifying questions:

1. What are we migrating FROM?
2. What are we migrating TO?
3. What must be preserved exactly?
4. What can be simplified/deleted?

Structure the plan:

Copy## Migration: [FROM] → [TO]

### Phase 1: Export
- [ ] Create script to fetch all content via API
- [ ] Convert to target format
- [ ] Validate structure matches

### Phase 2: Transform
- [ ] Process each item
- [ ] Handle assets (images, videos)
- [ ] Generate new file structure

### Phase 3: Integrate
- [ ] Update imports and references
- [ ] Delete old dependencies
- [ ] Verify each page/component

### Phase 4: Cleanup
- [ ] Remove old code
- [ ] Update documentation
- [ ] Measure improvements

Step 2: Build Export Scripts

Use existing API keys - don't manually click through UIs:

Copy#!/usr/bin/env python3
"""Export content from [SOURCE] to local files."""

import os
import json
import requests

API_KEY = os.environ.get("SOURCE_API_KEY")
OUTPUT_DIR = "content/"

def fetch_all_items():
    """Fetch all content items via API."""
    response = requests.get(
        "https://api.source.com/content",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    return response.json()

def convert_to_markdown(item):
    """Convert CMS item to markdown with frontmatter."""
    frontmatter = f"""---
title: {item['title']}
date: {item['createdAt']}
---

{item['content']}
"""
    return frontmatter

def export_assets(item):
    """Download and save assets to local storage."""
    for asset in item.get('assets', []):
        # Download and save locally
        pass

def main():
    items = fetch_all_items()
    for item in items:
        markdown = convert_to_markdown(item)
        filepath = f"{OUTPUT_DIR}/{item['slug']}.md"
        with open(filepath, 'w') as f:
            f.write(markdown)
        export_assets(item)
    print(f"Exported {len(items)} items")

if __name__ == "__main__":
    main()

Step 3: Run Parallel Agents

For broad changes across many files, use subagent pattern:

Copy## Subagent Task: Update [Component] across all pages

Files to update:
- src/pages/home.tsx
- src/pages/about.tsx
- src/pages/features.tsx
[... list all files ...]

For each file:
1. Find old pattern: `<OldComponent prop={...} />`
2. Replace with: `<NewComponent newProp={...} />`
3. Update imports
4. Verify no TypeScript errors

Step 4: Visual Verification

For UI migrations, use browser comparison:

CopyCompare local vs production:
1. Screenshot local: http://localhost:3000/page
2. Screenshot production: https://prod.com/page
3. Identify differences
4. Fix until pixel-perfect match

Step 5: Measure Results

Track the migration:

Copy# Lines changed
git diff --stat main

# Dependencies removed
diff <(git show main:package.json | jq '.dependencies | keys') \
     <(cat package.json | jq '.dependencies | keys')

# Build time before/after
time npm run build

Output Format

Copy## Migration Complete

### Stats
- Agent requests: X
- Commits: X
- Lines added: +X
- Lines removed: -X
- Dependencies removed: X
- Build time improvement: X%

### What Was Removed
- [Abstraction 1]
- [Abstraction 2]

### What Replaced It
- [Simple solution 1]
- [Simple solution 2]

### Verification
- [ ] All pages render correctly
- [ ] All tests pass
- [ ] No console errors
- [ ] Assets load properly

Key Lessons

1. Use APIs to export - Don't click through GUIs
2. Run agents in parallel - Many files, same pattern
3. Visual verify - Screenshot comparison catches regressions
4. Delete aggressively - If it's not needed, remove it
5. Measure improvement - Build time, bundle size, dependencies