Migration Guide

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

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

## 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

## 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

## 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

## 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"