---
name: migration-guide
description: >
  Generate step-by-step migration guides between tools, frameworks, or workflows.
  Outputs: Phase-by-phase migration plan, compatibility mapping, rollback strategy.
  Use when switching tools, upgrading frameworks, or adopting new workflows.
  Triggers: migrate from X to Y, switch to, upgrade from, moving from, /migrate
---

# Migration Guide

Transform tool/framework switches from risky leaps into controlled, reversible transitions.

## Purpose

Migrations fail when users try to switch everything at once. This skill creates phased migration plans that maintain productivity while transitioning, with rollback options at each phase.

## Migration Categories

```
1. Tool Migration:
   - IDE: Cursor → Claude Code
   - AI: Copilot → Claude
   - Bundler: Webpack → Vite

2. Framework Migration:
   - React → Next.js
   - Express → Fastify
   - REST → GraphQL

3. Workflow Migration:
   - Manual → Automated
   - Monolith → Microservices
   - Local → Cloud

4. Version Migration:
   - Major upgrades (v1 → v2)
   - Breaking changes
   - Deprecation handling
```

---

## Process

### Phase 1: Migration Assessment

#### Entry Check

```
IF user provided: current state + target state + reason
    → Proceed to Phase 2
ELSE
    → Assess migration scope first
```

#### Assessment Questions

| Question                           | Purpose             |
| ---------------------------------- | ------------------- |
| "What are you migrating from?"     | Identify source     |
| "What are you migrating to?"       | Identify target     |
| "Why are you migrating?"           | Validate motivation |
| "What's your timeline?"            | Scope the phases    |
| "Can you run both simultaneously?" | Determine strategy  |

#### Migration Type Detection

```
IF source and target can coexist:
    → Recommend: Parallel Migration (lowest risk)
    → Run both, gradually shift traffic/usage

IF must be atomic swap:
    → Recommend: Big Bang Migration (higher risk)
    → Requires thorough testing, clear rollback

IF partial migration possible:
    → Recommend: Strangler Fig Pattern
    → New features in new system, old stays
```

---

### Phase 2: Compatibility Mapping

#### Entry Check

```
IF migration assessed:
    → Map compatibility
ELSE
    → Return to Phase 1
```

#### Feature Mapping Table

```markdown
## Feature Compatibility

| Feature     | [Source]       | [Target]             | Migration Effort         |
| ----------- | -------------- | -------------------- | ------------------------ |
| [feature 1] | ✓ How it works | ✓ Equivalent         | Low/Med/High             |
| [feature 2] | ✓ How it works | ⚠ Different approach | Med                      |
| [feature 3] | ✓ How it works | ✗ Not available      | High (workaround needed) |
| [feature 4] | ✗ N/A          | ✓ New capability     | Gain                     |
```

#### Breaking Changes Identification

```
FOR each feature in source:
    Compare with target:

    IF identical API/behavior:
        → Mark: Direct migration

    IF different API, same result:
        → Mark: Adaptation needed
        → Document: transformation required

    IF no equivalent:
        → Mark: Blocker or accept loss
        → Document: workaround or alternative
```

#### Dependency Analysis

```
LIST all dependencies:
    - Which work with both?
    - Which need replacement?
    - Which are source-specific?
    - Which are target-specific?

OUTPUT:
| Dependency | Source | Target | Action |
|------------|--------|--------|--------|
| [dep] | v1.x | v2.x | Upgrade |
| [dep] | ✓ | ✗ | Replace with [alt] |
```

---

### Phase 3: Migration Plan Generation

#### Entry Check

```
IF compatibility mapped:
    → Generate phased plan
ELSE
    → Return to Phase 2
```

#### Phase Structure

```markdown
## Migration Plan: [Source] → [Target]

### Phase 0: Preparation (Before Starting)

**Duration:** [estimate]
**Risk:** Low

Actions:

- [ ] Document current configuration
- [ ] Create backup/snapshot
- [ ] Set up target environment
- [ ] Verify team readiness

Rollback: N/A (nothing changed yet)

---

### Phase 1: Parallel Setup

**Duration:** [estimate]
**Risk:** Low

Actions:

- [ ] Install [target] alongside [source]
- [ ] Configure [target] with basic settings
- [ ] Verify [target] works independently
- [ ] Keep using [source] for production work

Rollback: Remove [target], continue with [source]

Success Criteria:

- [Target] runs without errors
- No impact on [source] workflow

---

### Phase 2: Feature Migration

**Duration:** [estimate]
**Risk:** Medium

Actions:

- [ ] Migrate [feature 1] (easiest first)
- [ ] Test [feature 1] in [target]
- [ ] Migrate [feature 2]
- [ ] Test [feature 2] in [target]
- [ ] [Continue for each feature...]

Rollback: Switch back to [source] for migrated features

Success Criteria:

- All migrated features work in [target]
- No data loss or corruption

---

### Phase 3: Workflow Transition

**Duration:** [estimate]
**Risk:** Medium

Actions:

- [ ] Switch primary workflow to [target]
- [ ] Use [source] only for unsupported features
- [ ] Document any gaps or issues
- [ ] Adjust team processes

Rollback: Return to [source] as primary

Success Criteria:

- 80%+ of work done in [target]
- Team comfortable with new workflow

---

### Phase 4: Full Cutover

**Duration:** [estimate]
**Risk:** Low (if previous phases succeeded)

Actions:

- [ ] Disable/uninstall [source]
- [ ] Remove [source] configurations
- [ ] Update documentation
- [ ] Archive [source] backups

Rollback: Reinstall [source] from backup

Success Criteria:

- [Source] fully removed
- No references to [source] in workflow
```

---

### Phase 4: Specific Migration Guides

#### Tool-Specific Templates

##### Cursor → Claude Code Migration

````markdown
## Cursor → Claude Code

### What Changes

| Cursor         | Claude Code        |
| -------------- | ------------------ |
| GUI-based      | Terminal-based     |
| .cursorrules   | CLAUDE.md          |
| Cmd+K          | Direct prompt      |
| Tab completion | Different paradigm |

### Phase 1: Parallel (Keep Both)

1. Install Claude Code: `npm install -g @anthropic-ai/claude-code`
2. Run from project: `claude`
3. Use for multi-file tasks only

### Phase 2: Translate Configuration

Convert .cursorrules to CLAUDE.md:

```markdown
# From .cursorrules

[content]

# To CLAUDE.md

[translated content]
```
````

### Phase 3: Workflow Integration

- Keep Cursor for: Quick edits, tab completion
- Use Claude Code for: Complex tasks, multi-file, planning

### Phase 4: Optional Full Switch

Only if comfortable. Hybrid is valid long-term.

````

##### Copilot → Claude Migration
```markdown
## GitHub Copilot → Claude Code

### Paradigm Shift
- Copilot: Reactive (suggests next line)
- Claude: Agentic (executes full tasks)

### Phase 1: Keep Both
1. Keep Copilot active in IDE
2. Add Claude Code for tasks
3. Use Copilot for: Writing new code
4. Use Claude for: "Do X for me"

### Phase 2: Task Differentiation
````

Small (single line) → Copilot
Medium (function) → Either
Large (multi-file) → Claude Code
Planning → Claude Code (Plan Mode)

```

### Phase 3: Evaluate Value
After 2 weeks:
- Which saves more time?
- Which produces better code?
- TCO comparison

### Phase 4: Decide
- Keep both (common)
- Drop Copilot (if Claude covers needs)
- Drop Claude (if Copilot sufficient)
```

---

### Phase 5: Rollback Strategy

#### Entry Check

```
IF migration plan generated:
    → Add rollback details
ELSE
    → Return to Phase 3
```

#### Rollback Documentation

```markdown
## Rollback Strategy

### Checkpoints

| Phase | Checkpoint     | Rollback Command        |
| ----- | -------------- | ----------------------- |
| 1     | Before install | N/A                     |
| 2     | After config   | Restore [source] config |
| 3     | After workflow | Switch back to [source] |
| 4     | After cutover  | Reinstall [source]      |

### Data Preservation

- Backup location: [path]
- Backup command: [command]
- Restore command: [command]

### Emergency Rollback

If critical failure during migration:

1. Stop current action
2. Run: [rollback command]
3. Verify: [verification steps]
4. Document: What failed and why
```

---

## Self-Check (Read before every response)

□ Did I identify the migration type?
→ Parallel vs Big Bang vs Strangler changes everything

□ Is every phase reversible?
→ No rollback = no safety net

□ Did I map feature compatibility?
→ Surprise gaps kill migrations

□ Are phases small enough?
→ Large phases = large risks

□ Did I include success criteria?
→ "Done" must be measurable

□ Is the timeline realistic?
→ Rushed migrations fail

□ Did I account for team learning curve?
→ New tool = temporary slowdown

---

## Integration with Vibery

```
AFTER migration planned:
    Suggest relevant components:
    - "project-blueprint for new project setup"
    - "workflow-composer to automate new workflows"
    - "[target]-pro agent for learning new tool"
```