Migration Guides.md - johnpeterman72/CursorRIPER.sigma GitHub Wiki

🔄 Migration Guides

This guide helps you migrate between different versions of CursorRIPER.sigma, including upgrading from the original CursorRIPER framework.

📋 Migration Overview

🎯 Migration Types

Migration Type	Complexity	Time Required	Downtime
Patch Updates (1.0.x → 1.0.y)	Low	5-15 minutes	None
Minor Updates (1.x → 1.y)	Medium	30-60 minutes	Minimal
Major Updates (x.0 → y.0)	High	2-8 hours	Planned
Original to Sigma	High	4-12 hours	Planned

🔍 Pre-Migration Checklist

Before starting any migration:

Backup everything (database, files, configuration)
Review breaking changes in target version
Test in staging environment first
Schedule maintenance window for production
Verify system requirements are met
Check dependency compatibility
Plan rollback strategy if needed

🚀 Current Version Migrations

📈 Upgrading to v1.0.5 (Latest)

From v1.0.4 → v1.0.5

✅ This is a minor update with no breaking changes.

Quick Upgrade:

# 1. Backup current installation
npm run framework:backup

# 2. Update dependencies
npm update @cursoriper/core

# 3. Install new optional dependencies
npm install

# 4. Run any new migrations
npm run db:migrate

# 5. Restart application
npm restart

New Features Available:

Docker MCP Integration (optional)
BMAD Enterprise Platform (optional)
Enhanced troubleshooting tools
Improved security and performance

Configuration Updates (Optional):

// framework.config.js - Add these sections if you want new features
module.exports = {
  // ... existing configuration

  // Enable BMAD Enterprise features
  modules: {
    bmad: {
      enabled: true,  // Set to true to enable
      config: {
        database_prefix: 'bmad_',
        canvas_autosave: true,
        analytics_enabled: true
      }
    }
  },

  // Enable Docker MCP integration
  docker: {
    enabled: false,  // Set to true to enable
    compose_file: './docker/mcp/docker-compose.yml',
    auto_start: true
  }
};

From v1.0.3 → v1.0.5

⚠️ This spans multiple versions - follow each step carefully.

Step 1: Upgrade to v1.0.4 first

# Upgrade to intermediate version first
npm install @cursoriper/[email protected]
npm run db:migrate

Step 2: Handle v1.0.4 breaking changes

// Plugin system changed in v1.0.4
// Old way:
framework.loadPlugin('my-plugin', config);

// New way:
framework.plugins.register('my-plugin', config);

Step 3: Upgrade to v1.0.5

npm install @cursoriper/[email protected]
npm run db:migrate
npm restart

From v1.0.2 or earlier → v1.0.5

⚠️ Major changes - thorough testing required.

Preparation:

Full system backup including database and files
Test environment setup with exact production data
Review all breaking changes from each intermediate version

Migration Steps:

# 1. Create migration workspace
mkdir migration-workspace
cd migration-workspace

# 2. Clone current project
cp -r /path/to/current/project ./current
cp -r /path/to/current/project ./migrated

# 3. Upgrade migrated copy step by step
cd migrated
npm install @cursoriper/[email protected]  # Intermediate step
npm run db:migrate
npm install @cursoriper/[email protected]
npm run db:migrate
npm install @cursoriper/[email protected]
npm run db:migrate

# 4. Test thoroughly before applying to production
npm test
npm run integration-test

# 5. Apply to production during maintenance window

Breaking Changes Summary:

v1.0.3: Event system refactoring
v1.0.4: Plugin loading mechanism change
v1.0.5: No breaking changes (backward compatible)

🔄 Migrating from Original CursorRIPER

📊 CursorRIPER → CursorRIPER.sigma

Why Migrate?

93% token reduction through symbolic notation
Better performance and reduced memory usage
Enhanced security and modern architecture
Enterprise features for larger teams
Active development and community support

Migration Complexity: High (4-12 hours) Recommended Approach: Gradual migration over time

🔍 Pre-Migration Assessment

Compatibility Check:

# Download migration assessment tool
npx @cursoriper/migration-tool assess /path/to/original/project

# This will generate a report showing:
# - Compatible features
# - Features requiring changes
# - Recommended migration path
# - Estimated effort

Assessment Output Example:

CursorRIPER Migration Assessment
===============================
Project: MyProject v2.1.0
Original Framework: CursorRIPER v3.2.1

Compatibility Analysis:
✅ Core RIPER modes: 100% compatible
✅ Basic workflows: 95% compatible
⚠️  Custom plugins: 60% compatible (need updates)
⚠️  Advanced features: 40% compatible (major changes)
❌ Legacy integrations: 0% compatible (need rewrite)

Estimated Migration Effort: 6-8 hours
Recommended Strategy: Gradual migration

📋 Migration Strategies

Strategy 1: Complete Migration (Recommended for small projects)

Convert entire project at once
Minimal ongoing maintenance
Clean break from legacy system

Strategy 2: Gradual Migration (Recommended for large projects)

Migrate modules one at a time
Run both systems in parallel
Lower risk and easier rollback

Strategy 3: Hybrid Approach

Keep legacy system for critical features
Use CursorRIPER.sigma for new development
Gradually migrate over months

🛠️ Complete Migration Process

Phase 1: Environment Setup

# 1. Create migration project structure
mkdir my-project-sigma
cd my-project-sigma

# 2. Initialize new CursorRIPER.sigma project
npx create-cursoriper-app . --template=migration

# 3. Install migration tools
npm install @cursoriper/migration-tools

Phase 2: Configuration Migration

# Run automated configuration migration
npx cursoriper-migrate config /path/to/original/project

# This creates:
# - framework.config.js (new format)
# - .env (environment variables)
# - migration-report.md (what was converted)

Manual Configuration Updates:

// Original CursorRIPER config (verbose)
const config = {
  riperModes: {
    research: {
      enabled: true,
      permissions: ['read', 'analyze'],
      tools: ['web_search', 'documentation']
    }
    // ... hundreds of lines
  }
};

// CursorRIPER.sigma config (symbolic)
module.exports = {
  riper: {
    modes: 'Ω{r,i,p,e,rev}',
    permissions: 'ℙ{r:Γα,i:Γβ,p:Γγ,e:Γδ,rev:Γε}',
    tools: '@{search,docs,git,fs}'
  }
};

Phase 3: Code Migration

# Run automated code migration
npx cursoriper-migrate code /path/to/original/project

# This handles:
# - Function signature updates
# - Import statement changes
# - API endpoint updates
# - Event system migration

Manual Code Updates:

// Original CursorRIPER (verbose)
const framework = new CursorRIPERFramework({
  mode: 'research',
  permissions: {
    read: true,
    write: false,
    execute: false
  },
  context: {
    project: 'MyProject',
    files: ['src/main.js', 'src/utils.js']
  }
});

// CursorRIPER.sigma (symbolic)
const framework = new CursorRIPER({
  mode: 'Ωr',
  perms: 'ℙr',
  ctx: 'Γα[main.js,utils.js]'
});

Phase 4: Data Migration

# Migrate project data and memory files
npx cursoriper-migrate data /path/to/original/project

# This migrates:
# - Project memory files
# - User preferences
# - Plugin configurations
# - Custom templates

Phase 5: Testing and Validation

# Run migration validation tests
npm run test:migration

# Compare functionality
npm run compare:original /path/to/original/project

# Performance comparison
npm run benchmark:compare /path/to/original/project

🔧 Gradual Migration Process

Step 1: Parallel Setup

# Set up CursorRIPER.sigma alongside original
mkdir project-sigma
cd project-sigma
npx create-cursoriper-app . --template=parallel

# Configure to work with existing project
npm run setup:parallel /path/to/original/project

Step 2: Module-by-Module Migration

# Migrate authentication module first (typically safest)
npx cursoriper-migrate module auth /path/to/original/project

# Test the migrated module
npm run test:module auth

# Gradually migrate other modules
npx cursoriper-migrate module api /path/to/original/project
npx cursoriper-migrate module plugins /path/to/original/project

Step 3: Feature Flag Migration

// Use feature flags to gradually switch features
const config = {
  features: {
    use_sigma_auth: true,      // Migrated
    use_sigma_api: false,      // Still using original
    use_sigma_plugins: false   // Still using original
  }
};

Step 4: Data Synchronization

# Keep data in sync between systems during transition
npm run sync:data --from=original --to=sigma

Step 5: Gradual Cutover

# Week 1: Migrate development environment
npm run cutover:dev

# Week 2: Migrate staging environment  
npm run cutover:staging

# Week 3: Migrate production (blue-green deployment)
npm run cutover:production

🚨 Migration Troubleshooting

Common Issues:

Issue 1: Plugin Compatibility

# Problem: Custom plugins don't work
# Solution: Update plugin API calls

# Original plugin:
framework.registerPlugin('my-plugin', {
  onInit: function() { /* ... */ }
});

# Sigma plugin:
framework.plugins.register('my-plugin', {
  initialize: async function() { /* ... */ }
});

Issue 2: Memory File Format

# Problem: Original memory files not recognized
# Solution: Convert memory file format

npx cursoriper-migrate memory /path/to/original/.memory/

Issue 3: Configuration Errors

# Problem: Configuration validation fails
# Solution: Use migration validator

npx cursoriper-validate config ./framework.config.js
npx cursoriper-fix config ./framework.config.js

Issue 4: Performance Regression

# Problem: Sigma version slower than original
# Solution: Performance optimization

npm run optimize:config
npm run optimize:database
npm run optimize:cache

🔧 Manual Migration Tasks

📝 Configuration File Updates

1. Framework Configuration

// Create new framework.config.js
module.exports = {
  // Core settings
  server: {
    port: process.env.PORT || 3000,
    host: process.env.HOST || 'localhost'
  },

  // Database configuration
  database: {
    type: 'sqlite',  // or 'postgresql', 'mysql'
    database: './data/framework.sqlite'
  },

  // RIPER mode configuration (symbolic)
  riper: {
    modes: 'Ω{r,i,p,e,rev}',
    default: 'Ωr',
    transitions: 'α→β→γ→δ→ε'
  },

  // Memory system
  memory: {
    files: ['σ₁', 'σ₂', 'σ₃', 'σ₄', 'σ₅', 'σ₆'],
    auto_save: true,
    retention: '30d'
  }
};

2. Environment Variables

# Create .env file
NODE_ENV=development
PORT=3000
JWT_SECRET=your-secure-jwt-secret
DATABASE_URL=sqlite://./data/framework.sqlite

# Optional features
BMAD_ENABLED=false
DOCKER_ENABLED=false

3. Package.json Scripts

{
  "scripts": {
    "start": "node bin/www",
    "dev": "nodemon bin/www",
    "test": "npm run test:unit && npm run test:integration",
    "migrate": "npm run db:migrate",
    "framework:health": "cursoriper health-check"
  }
}

🗃️ Database Schema Migration

Automated Migration:

# Generate migration from existing schema
npx cursoriper-migrate generate-schema /path/to/original/database

# Apply generated migration
npm run db:migrate

Manual Schema Updates:

-- Add new framework tables
CREATE TABLE IF NOT EXISTS framework_sessions (
  id VARCHAR(36) PRIMARY KEY,
  user_id VARCHAR(36),
  data TEXT,
  expires_at TIMESTAMP
);

CREATE TABLE IF NOT EXISTS framework_plugins (
  id VARCHAR(36) PRIMARY KEY,
  name VARCHAR(255),
  version VARCHAR(50),
  config TEXT,
  enabled BOOLEAN DEFAULT true
);

-- Migrate existing data
INSERT INTO framework_sessions (id, user_id, data, expires_at)
SELECT session_id, user_id, session_data, expires 
FROM old_sessions_table;

📁 File Structure Migration

New Project Structure:

project/
├── src/
│   ├── modules/          # Migrated from original modules
│   ├── plugins/          # Updated plugin format
│   ├── services/         # Business logic
│   └── utils/            # Utility functions
├── config/
│   ├── framework.config.js
│   ├── development.js
│   └── production.js
├── data/                 # Database and memory files
│   ├── framework.sqlite
│   └── memory/
│       ├── σ₁.json      # Project context
│       ├── σ₂.json      # User preferences  
│       └── ...
├── tests/               # Test files
├── docs/                # Documentation
└── logs/                # Log files

File Migration Script:

#!/bin/bash
# migrate-files.sh

# Create new directory structure
mkdir -p src/{modules,plugins,services,utils}
mkdir -p config data/memory tests docs logs

# Migrate modules
cp -r /path/to/original/modules/* src/modules/

# Migrate plugins (may need manual updates)
cp -r /path/to/original/plugins/* src/plugins/

# Migrate configuration
npx cursoriper-migrate config /path/to/original

# Migrate memory files
npx cursoriper-migrate memory /path/to/original/.memory/

🧪 Testing Migration

📋 Migration Test Checklist

Functional Testing:

All RIPER modes work correctly
Protection system functions properly
Context management works
Permission system enforced
Memory files load and save
Plugins load and function
API endpoints respond correctly

Performance Testing:

Response times comparable or better
Memory usage acceptable
Database queries optimized
No memory leaks detected
Concurrent user handling

Integration Testing:

Database connectivity
External API integrations
Authentication system
File upload/download
Real-time features

Security Testing:

Authentication working
Authorization enforced
Input validation functioning
Security headers present
No security regressions

🧰 Migration Testing Tools

Automated Testing:

# Run full migration test suite
npm run test:migration

# Compare functionality with original
npm run test:compare /path/to/original

# Performance benchmark comparison
npm run benchmark:compare /path/to/original

# Security scan
npm run security:scan

Manual Testing Checklist:

# 1. Basic functionality
curl http://localhost:3000/health

# 2. Authentication
curl -X POST http://localhost:3000/auth/login \
  -d '{"email":"[email protected]","password":"test"}'

# 3. API endpoints
curl http://localhost:3000/api/projects

# 4. File operations
curl -X POST http://localhost:3000/api/files/upload \
  -F "[email protected]"

# 5. Real-time features (if applicable)
# Test WebSocket connections and updates

🛡️ Rollback Procedures

🔄 Rollback Strategy

Immediate Rollback (< 1 hour):

# Stop new system
npm stop

# Restore database backup
pg_restore -d framework_db backup.sql

# Restore files
cp -r backup/* /path/to/project/

# Start original system
cd /path/to/original
npm start

Planned Rollback (maintenance window):

# 1. Notify users of rollback
echo "System rollback in progress" > public/maintenance.html

# 2. Stop all services
npm stop
pm2 stop all

# 3. Restore from backup
./scripts/restore-backup.sh backup-$(date +%Y%m%d)

# 4. Verify restoration
npm run health-check

# 5. Resume normal operations
npm start

🔍 Rollback Validation

Post-Rollback Checklist:

Database integrity verified
All services responding
User authentication working
Data consistency confirmed
Performance metrics normal
No data loss detected

📊 Migration Success Metrics

🎯 Success Criteria

Technical Metrics:

Response time: ≤ original performance + 10%
Memory usage: ≤ original usage + 20%
Error rate: < 0.1%
Uptime: > 99.9%

Functional Metrics:

Feature parity: 100% of critical features
User workflow: No breaking changes
Data integrity: 100% data preserved
Integration: All external integrations working

Business Metrics:

User satisfaction: > 90%
Training time: < 2 hours for existing users
Support tickets: < 5% increase
Performance: Measurable improvement

📈 Post-Migration Monitoring

Week 1: Intensive Monitoring

Monitor all metrics hourly
24/7 support availability
Daily user feedback collection
Performance trend analysis

Week 2-4: Standard Monitoring

Monitor key metrics daily
Regular user feedback
Performance optimization
Documentation updates

Month 2+: Normal Operations

Standard monitoring schedules
Quarterly performance reviews
User satisfaction surveys
Continuous improvement planning

📞 Migration Support

🆘 Getting Help During Migration

Support Channels:

Emergency: [email protected] (< 2 hour response)
Migration Support: [email protected] (< 8 hour response)
General Questions: [email protected] (< 24 hour response)
Community: GitHub Discussions

Professional Services:

Migration Consulting: $200/hour
Assisted Migration: $2,000 fixed price (small projects)
Full Migration Service: $5,000+ (large projects)
Training and Support: $500/day

📚 Migration Resources

Documentation:

Tools and Utilities:

Migration assessment tool
Automated migration scripts
Configuration validators
Performance comparison tools
Rollback utilities

Need help with migration? Contact our migration support team at [email protected]

Last Updated: June 28, 2025
Framework Version: CursorRIPER.sigma v1.0+

Successful migration leads to better performance, security, and maintainability! 🚀