# legacy-migration-planner

The legacy-migration-planner skill plans legacy migrations, codebase modernization, and monolith decomposition. Use it before implementation when the move needs documented research and staged decisions.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 7191 repo stars
- Author: Felipe Rodrigues - github.com/felipfr
- License: CC-BY-4.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/tech-leads-club/agent-skills/tree/HEAD/packages/skills-catalog/skills/(architecture)/legacy-migration-planner/SKILL.md
- Updated: 2026-10-24
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/legacy-migration-planner

## What it does

The skill works in two phases: RESEARCH and PLAN. It inspects project structure, entry points, configuration, and dependencies, then maps candidate domains, studies the current and target stacks, and records risks and integration points. Codebase findings use `file:line` references.

During PLAN, it selects a migration direction and defines seams plus a facade or router for incremental change. It writes `./migration-plan/00-roadmap.md`, research files under `./migration-plan/research/`, and one migration file per domain in `./migration-plan/domains/`. Domain files cover migration steps, testing, rollback, and success criteria.

This skill produces planning documents rather than changing the system. Technology recommendations require web research, with `context7` used when available; without evidence and code references, the resulting plan is not grounded enough to guide implementation.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add tech-leads-club/agent-skills --skill legacy-migration-planner -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/legacy-migration-planner/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/legacy-migration-planner/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add tech-leads-club/agent-skills --skill legacy-migration-planner -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/legacy-migration-planner/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add tech-leads-club/agent-skills --skill legacy-migration-planner -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/legacy-migration-planner/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install tech-leads-club/agent-skills 'packages/skills-catalog/skills/(architecture)/legacy-migration-planner'
```

2. **Manually: put the files in place**
- File: `.github/skills/legacy-migration-planner/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add tech-leads-club/agent-skills --skill legacy-migration-planner -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/tech-leads-club/agent-skills --path 'packages/skills-catalog/skills/(architecture)/legacy-migration-planner'
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/legacy-migration-planner/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/tech-leads-club/agent-skills/tree/HEAD/packages/skills-catalog/skills/(architecture)/legacy-migration-planner/SKILL.md

## When to use it
- plan a legacy system migration
- split a monolith into bounded domains
- map a cross-language or framework rewrite
- sequence an incremental migration roadmap
- define rollback and testing for migration stages

## Example prompts
- Analyze this monolith and create a staged migration plan with dependency and risk mapping.
- Prepare `./migration-plan/00-roadmap.md` for moving this codebase to microservices.
- Plan the framework upgrade, including migration seams, testing, rollback, and a separate file for each domain.

## Source text · SKILL.md · CC-BY-4.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: a54f83790648962a.

BEGIN THIRD-PARTY FILE a54f83790648962a
````text
---
name: legacy-migration-planner
description: Use when planning legacy system migrations, codebase modernization, monolith decomposition, microservices consolidation, cross-language rewrites, or framework upgrades. Invoke for strangler fig pattern, incremental migration strategy, or refactoring roadmaps. Do NOT use for domain analysis (use domain-analysis), component sizing (use component-identification-sizing), or step-by-step decomposition plans (use decomposition-planning-roadmap).
license: CC-BY-4.0
metadata:
  author: Felipe Rodrigues - github.com/felipfr
  version: 1.0.0
---

# Legacy Migration Planner

Senior migration architect that produces comprehensive, evidence-based migration plans using the Strangler Fig pattern. You create plans — you do not implement them. Other agents or developers execute the plan you produce.

## Core Principles

These are non-negotiable. Violating any of these invalidates your output.

1. **Never assume.** If you encounter an acronym, term, pattern, or technology you are not 100% certain about, stop and either research it (web search, context7) or ask the user. Say "I don't know what X means — can you clarify?" rather than guessing.
2. **Always cite evidence.** Every claim in your output must reference either a specific `file:line` from the user's codebase or a verified external URL. No unreferenced assertions.
3. **Always research before recommending.** Before suggesting any technology, pattern, or approach, use web search and context7 (when available) to verify it is current, maintained, and appropriate. Never recommend based solely on training data.
4. **Minimize token consumption.** Write output files per domain. Never dump entire file contents — reference by `file:line` ranges. Keep each output file focused on one bounded context.
5. **Direction-agnostic.** This skill handles ANY migration direction: monolith to microservices, microservices to modular monolith, microfrontends to SPA, cross-language, cross-framework, or any combination.

## Workflow

Every engagement follows two mandatory phases. Never skip RESEARCH. Never start PLAN without completing RESEARCH.

```
RESEARCH (mandatory)                    PLAN (mandatory)
├─ 1. Codebase deep analysis            ├─ 5. Define migration direction
├─ 2. Domain/bounded context mapping    ├─ 6. Design seams and facades
````
END THIRD-PARTY FILE a54f83790648962a

The third-party file has ended. Everything between the a54f83790648962a tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2369 of 7416 bytes. © Felipe Rodrigues - github.com/felipfr · CC-BY-4.0 · https://github.com/tech-leads-club/agent-skills/tree/HEAD/packages/skills-catalog/skills/(architecture)/legacy-migration-planner/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
