context-forge/.claude/docs/migrate.md

AI orchestration platform with autonomous teams, enhancement planning, migration tools, 25+ slash commands, checkpoints & hooks. Multi-IDE: Claude, Cursor, Windsurf, Cline, Copilot

# Migrate Guide - Context Forge

**Updated for v3.2.0 with Migration Intelligence**

## What is Migrate?

The `migrate` command creates comprehensive migration plans for transitioning between technology stacks. Powered by Migration Intelligence, it automatically detects frameworks, analyzes 200+ breaking change patterns, evaluates dependency compatibility, and provides AI-enhanced migration strategies.

## When to Use Migrate

Use the `migrate` command when:
- Upgrading major framework versions (React 17 → 18)
- Switching frameworks (Express → Fastify)
- Modernizing legacy code (jQuery → React)
- Moving between ecosystems (JavaScript → TypeScript)
- Adopting new architectures (Monolith → Microservices)

## Migration Strategies

### 1. Big Bang
- **When**: Small projects, clear boundaries
- **Risk**: High
- **Duration**: Short
- **Rollback**: Complete reversion

```bash
# All-at-once migration
context-forge migrate --strategy big-bang
```

### 2. Incremental (Recommended)
- **When**: Most projects
- **Risk**: Low to Medium
- **Duration**: Medium
- **Rollback**: Phase-specific

```bash
# Step-by-step migration
context-forge migrate --strategy incremental
```

### 3. Strangler Fig
- **When**: Large legacy systems
- **Risk**: Low
- **Duration**: Long
- **Rollback**: Granular

```bash
# Gradual replacement
context-forge migrate --strategy strangler-fig
```

### 4. Parallel Run
- **When**: Critical systems
- **Risk**: Very Low
- **Duration**: Long
- **Rollback**: Instant switch

```bash
# Side-by-side operation
context-forge migrate --strategy parallel-run
```

## Migration Intelligence Features

### 1. Framework Detection
- **10+ Framework Support**: React, Vue, Angular, Next.js, Nuxt, Django, FastAPI, Express, and more
- **Confidence Scoring**: 0-100% confidence in framework detection
- **Version Detection**: Automatic version identification from package.json and lock files
- **Variant Recognition**: Detects framework variants (Next.js vs React, Nuxt vs Vue)

### 2. Breaking Change Analysis
- **200+ Patterns**: Comprehensive database of breaking changes across frameworks
- **Version-Aware**: Specific breaking changes between version ranges
- **Automated Detection**: Scans codebase for potential breaking changes
- **Migration Scripts**: Generates automated fixes where possible

### 3. Dependency Intelligence
- **40+ Migration Paths**: Pre-configured dependency upgrade paths
- **Compatibility Analysis**: Cross-reference dependencies for conflicts
- **Replacement Suggestions**: Recommend modern alternatives for deprecated packages
- **Impact Assessment**: Estimate migration complexity and effort

## Step-by-Step Workflow

### 1. Start Migration Planning

```bash
# Full migration with intelligence
context-forge migrate

# Analysis only (show complexity without generating files)
context-forge migrate --analyze-only

# Quick assessment
context-forge migrate --quick

# Specific target stack
context-forge migrate --target react@18
```

### 2. Intelligent Source Analysis

Migration Intelligence automatically analyzes:
- **Framework Detection** with confidence scoring
- **Version identification** from multiple sources
- **Breaking change patterns** in your codebase
- **Dependency compatibility** matrix
- **Migration complexity** estimation

### 3. Intelligent Target Selection

Based on source analysis, Context Forge suggests optimal migration paths:
```
🔍 Framework Detection:
  • Primary: React v17.0.2 (95% confidence)
  • Also detected: Next.js v12.1.0 (78% confidence)

? Migration type:
❯ Framework upgrade: React 17 → React 18 (Recommended)
  Framework switch: React → Vue.js
  Full-stack upgrade: Next.js 12 → Next.js 14
  Language migration: JavaScript → TypeScript
  Architecture change: Monolith → Microservices
```

### 4. AI-Enhanced Migration Configuration

Context Forge analyzes your project and suggests:
- **Strategy selection** based on project complexity
- **Phase duration** estimates from similar migrations
- **Risk assessment** with specific mitigation strategies
- **Breaking change preview** with automated fixes
- **Dependency migration plan** with compatibility checks

## Generated Migration Artifacts

### 1. Migration Plan
```
MIGRATION_PLAN.md
├── Executive Summary
├── Breaking Changes Analysis
├── Migration Phases
├── Risk Assessment
├── Rollback Procedures
└── Success Metrics
```

### 2. Phase-Specific Guides
```
migration/
├── phase-1-preparation/
│   ├── checklist.md
│   ├── setup-guide.md
│   └── validation.md
├── phase-2-core-migration/
│   ├── breaking-changes.md
│   ├── code-transforms.md
│   └── testing-plan.md
└── phase-3-optimization/
    ├── performance.md
    ├── cleanup.md
    └── documentation.md
```

### 3. Automation Scripts
```
.claude/migration/
├── analyzers/
│   ├── breaking-change-detector.js
│   ├── dependency-analyzer.js
│   └── pattern-matcher.js
├── transformers/
│   ├── code-migrator.js
│   ├── config-updater.js
│   └── test-migrator.js
└── validators/
    ├── pre-migration-check.js
    ├── post-migration-test.js
    └── rollback-verifier.js
```

### 4. Tracking Tools
```
.claude/commands/migration/
├── migration-status.md      # Overall progress
├── migration-validate.md    # Run validations
├── migration-rollback.md    # Execute rollback
├── migration-metrics.md     # View metrics
└── migration-report.md      # Generate reports
```

## Common Migration Patterns

### 1. React 17 to React 18

```bash
context-forge migrate --from react@17 --to react@18

# Handles:
# - Automatic batching changes
# - Suspense updates
# - StrictMode changes
# - New hooks adoption
# - Concurrent features
```

Generated guides include:
- Component migration checklist
- Hook conversion patterns
- Performance optimization tips
- Testing strategy updates

### 2. Express to Fastify

```bash
context-forge migrate --from express --to fastify

# Addresses:
# - Middleware conversion
# - Route handler updates
# - Plugin architecture
# - Schema validation
# - Performance tuning
```

### 3. JavaScript to TypeScript

```bash
context-forge migrate --to typescript --incremental

# Manages:
# - Gradual type adoption
# - Config generation
# - Type definition creation
# - Build process updates
# - IDE configuration
```

### 4. Monolith to Microservices

```bash
context-forge migrate --architecture microservices

# Plans:
# - Service boundary identification
# - Data separation strategy
# - Communication patterns
# - Deployment orchestration
# - Monitoring setup
```

## Risk Management

### 1. Risk Assessment

Each migration includes:
- **Technical Risks**: Breaking changes, compatibility
- **Operational Risks**: Downtime, data loss
- **Business Risks**: Feature parity, user impact

### 2. Mitigation Strategies

```yaml
High Risk Areas:
- Authentication system
  Mitigation: Parallel run with gradual cutover
  
- Database schema
  Mitigation: Backward compatible changes
  
- API contracts
  Mitigation: Versioning with deprecation
```

### 3. Rollback Procedures

Every phase includes:
```bash
# Pre-migration snapshot
./migrate snapshot create

# Quick rollback
./migrate rollback --phase 2

# Complete rollback
./migrate rollback --full
```

## Validation and Testing

### 1. Pre-Migration Validation

```bash
# Check migration readiness
/migration-validate --pre

Checks:
✓ Test coverage adequate (>70%)
✓ No uncommitted changes
✓ Dependencies up to date
✓ Backup systems ready
✓ Team trained on new stack
```

### 2. Migration Testing

```bash
# Test migration scripts
/migration-test --dry-run

# Validate transformed code
/migration-test --phase 1

# Full regression testing
/migration-test --complete
```

### 3. Post-Migration Verification

```bash
# Verify success
/migration-validate --post

Validates:
✓ All tests passing
✓ Performance benchmarks met
✓ No functionality lost
✓ Documentation updated
✓ Monitoring active
```

## Phase Management

### Phase 1: Preparation (Typical)
```
Duration: 1-2 weeks
- Environment setup
- Tool installation
- Team training
- Backup creation
- Pilot testing
```

### Phase 2: Core Migration
```
Duration: 2-4 weeks
- Code transformation
- Dependency updates
- Configuration migration
- Initial testing
- Bug fixes
```

### Phase 3: Optimization
```
Duration: 1-2 weeks
- Performance tuning
- Code cleanup
- Documentation
- Knowledge transfer
- Final validation
```

## Advanced Features

### 1. Custom Transformers

Create custom code transformers:
```javascript
// .claude/migration/custom/auth-transformer.js
module.exports = {
  name: 'auth-migration',
  pattern: /passport\.(.*?)\(/g,
  transform: (match, method) => {
    return `newAuth.${methodMap[method]}(`;
  }
};
```

### 2. Dependency Mapping

Define dependency migrations:
```yaml
# .claude/migration/dependency-map.yml
dependencies:
  express: fastify
  body-parser: "@fastify/body"
  express-session: "@fastify/session"
  passport: "@fastify/passport"
```

### 3. Migration Hooks

Automate migration tasks:
```python
# .claude/hooks/pre-migration.py
#!/usr/bin/env python3

def pre_migration_check():
    # Verify environment
    # Create backups
    # Notify team
    # Set up monitoring
```

## Best Practices

### 1. Before Migration
- Comprehensive testing baseline
- Complete documentation
- Feature freeze period
- Team alignment
- Stakeholder communication

### 2. During Migration
- Follow phases strictly
- Test continuously
- Document changes
- Communicate progress
- Monitor systems

### 3. After Migration
- Performance monitoring
- User feedback collection
- Issue tracking
- Knowledge documentation
- Process refinement

## Integration with CI/CD

### 1. Migration Pipeline
```yaml
# .github/workflows/migration.yml
name: Migration Pipeline

on:
  workflow_dispatch:
    inputs:
      phase:
        description: 'Migration phase'
        required: true

jobs:
  migrate:
    steps:
      - name: Run migration phase
        run: |
          context-forge migrate --execute-phase ${{ inputs.phase }}
          context-forge migrate --validate-phase ${{ inputs.phase }}
```

### 2. Automated Testing
```bash
# Pre-commit hook
#!/bin/bash
context-forge migrate --check-compatibility
```

### 3. Progressive Rollout
```bash
# Canary deployment
context-forge migrate --canary 10%

# Blue-green deployment
context-forge migrate --blue-green
```

## Troubleshooting

### 1. Breaking Change Issues
```bash
# Detailed breaking change analysis
context-forge migrate --analyze-breaking

# Generate compatibility layer
context-forge migrate --compatibility-mode

# Find specific issues
context-forge migrate --find-issues
```

### 2. Performance Problems
```bash
# Migration performance
context-forge migrate --benchmark

# Optimize transformation
context-forge migrate --optimize

# Parallel processing
context-forge migrate --parallel
```

### 3. Rollback Scenarios
```bash
# Partial rollback
context-forge migrate --rollback-component auth

# Time-based rollback
context-forge migrate --rollback-to "2024-01-15"

# Emergency rollback
context-forge migrate --emergency-rollback
```

## Real-World Example

### E-commerce Platform Migration

```bash
# Scenario: Migrate from Express + Angular to Next.js

# 1. Initial assessment
context-forge migrate

# Configuration:
# - From: Express 4 + Angular 12
# - To: Next.js 14
# - Strategy: Strangler Fig
# - Duration: 12 weeks
# - Team: 5 developers

# 2. Phase breakdown:
# Phase 1: Setup Next.js alongside (2 weeks)
# Phase 2: Migrate authentication (2 weeks)  
# Phase 3: Migrate product catalog (3 weeks)
# Phase 4: Migrate checkout (2 weeks)
# Phase 5: Migrate admin panel (2 weeks)
# Phase 6: Deprecate old system (1 week)

# 3. Risk mitigation:
# - Shared session management
# - API gateway for routing
# - Feature flags for rollback
# - A/B testing for validation

# 4. Success metrics:
# - Zero downtime
# - <5% performance regression
# - 100% feature parity
# - Improved developer velocity
```

## Success Metrics

Track migration success:

### 1. Technical Metrics
- Test coverage maintained
- Performance benchmarks
- Error rates
- Build times
- Bundle sizes

### 2. Business Metrics
- User satisfaction
- Feature availability
- System reliability
- Time to market
- Developer productivity

### 3. Operational Metrics
- Deployment frequency
- Recovery time
- Incident rate
- Documentation coverage
- Team confidence

## Next Steps

1. **Assess Current State**
   ```bash
   context-forge analyze
   ```

2. **Plan Migration**
   ```bash
   context-forge migrate
   ```

3. **Execute Phases**
   - Follow generated guides
   - Use tracking commands
   - Validate each phase

4. **Monitor and Optimize**
   - Track metrics
   - Gather feedback
   - Refine process

5. **Document Learnings**
   - Update runbooks
   - Share knowledge
   - Improve tools