Skip to content

MIGRATION.md

Latest commit

 

History

History
378 lines (273 loc) · 8.56 KB

MIGRATION.md

File metadata and controls

378 lines (273 loc) · 8.56 KB

Migration Guide: Enhanced Ralph → Ralph Ultra

This guide helps you migrate from enhanced-ralph-claude-code to Ralph Ultra.

What Changed?

1. Rebranding

Old Name New Name Reason
Enhanced Ralph Ralph Ultra Clearer branding, easier to say
.ralph/ directory .ralph/ directory No change (backwards compatible)

2. CLI Command Changes

Old Command New Command Status
ralph init ralph init No change
ralph fix ralph fix No change
ralph loop ralph run Renamed for clarity
ralph loop --max 10 ralph run 10 Simplified syntax
N/A ralph status New command
N/A ralph prd New command
N/A ralph verify New command
N/A ralph deploy New command
N/A ralph dashboard New command
N/A ralph skill New command

3. New Directory Structure

Before (Enhanced Ralph):

.ralph/
├── prd.json
├── progress.txt
└── codebase_index.json (optional)

After (Ralph Ultra):

.ralph/
├── prd.json
├── progress.txt
├── config.json           # NEW: Security settings, preferences
├── audit.log             # NEW: Command execution log
├── codebase_index.json   # Enhanced with skill integration
├── perf_baseline.json    # NEW: Performance benchmarks
└── analysis_report.md    # Generated by ralph fix --analyze

4. New Features

  • Three-tier security model (sandbox/standard/YOLO)
  • 21 modular skills (was 10)
  • Smart loop engine with auto-recovery
  • Real-time observability via ralph dashboard
  • Claude Code plugin for IDE integration
  • Skill marketplace for community extensions

Migration Steps

Step 1: Uninstall Enhanced Ralph

# If you installed via install.sh
sudo rm /usr/local/bin/ralph

# If you installed via npm (if applicable)
npm uninstall -g enhanced-ralph-claude-code

Step 2: Install Ralph Ultra

# Clone the new repository
git clone https://github.com/kimhons/ralph-ultra-claude-code.git
cd ralph-ultra-claude-code

# Run the installer
sudo ./install.sh

Verify installation:

ralph --version
# Should output: Ralph Ultra v1.0.0

Step 3: Update Existing Projects

Navigate to each project that uses Ralph:

cd /path/to/your/project

Option A: Automatic Migration (Recommended)

ralph fix --migrate

This command:

  1. Detects the old Ralph configuration
  2. Converts prd.json to the new schema
  3. Creates .ralph/config.json with default security settings
  4. Backs up old files to .ralph/backup/

Option B: Manual Migration

  1. Update prd.json:

Old format:

{
  "userStories": [
    {
      "id": "US-001",
      "title": "Add feature",
      "acceptanceCriteria": [...],
      "priority": 1,
      "passes": false
    }
  ]
}

New format:

{
  "project": "my-project",
  "version": "1.0.0",
  "stories": [
    {
      "id": "US-001",
      "title": "Add feature",
      "acceptance_criteria": [...],
      "priority": "high",
      "status": "pending"
    }
  ]
}

Changes:

  • userStories → stories
  • acceptanceCriteria → acceptance_criteria (snake_case)
  • priority is now a string ("critical", "high", "medium", "low")
  • passes → status ("pending", "in-progress", "done", "blocked")
  • Added required top-level fields: project, version
  1. Create config.json:
cat > .ralph/config.json <<EOF
{
  "security": {
    "mode": "standard",
    "allowlist": [
      "^npm (install|test|run build)$",
      "^git (add|commit|status)$"
    ]
  }
}
EOF
  1. Update CLAUDE.md (if needed):

Ralph Ultra introduces new verification workflow patterns. If your CLAUDE.md references the old "5-gate verification", update it to:

## Verification Workflow
1. Static analysis (linter) must pass.
2. Type checking must pass.
3. All tests must pass.
4. Security audit must pass (no HIGH or CRITICAL vulnerabilities).
5. Visual verification for UI changes (use ralph skill run dev-browser).

Step 4: Test the Migration

Run a verification check:

ralph verify

Expected output:

✓ Gate 1: Static Analysis passed
✓ Gate 2: Type Checking passed
✓ Gate 3: Tests passed
✓ Gate 4: Security Audit passed
✓ Gate 5: Visual Verification skipped (no UI changes)

All verification gates passed!

Breaking Changes

1. PRD Schema Changes

The prd.json schema has changed. Use ralph prd validate to check your PRD:

ralph prd validate

If invalid, the command will show specific errors:

❌ Error at stories[0].priority: Expected string, got number
❌ Error at stories[0]: Missing required field "status"

2. CLI Flag Changes

Old Flag New Flag Notes
--max N N Positional argument now
--skip-verify --skip-gate N More granular control
N/A --security MODE New flag for security tier

3. Skills Directory Location

Skills are now in /usr/local/lib/ralph/skills/ (global) and .ralph/skills/ (local).

Migration: If you have custom skills in ~/.ralph/skills/, move them to .ralph/skills/ in each project.

4. Environment Variables

Old Var New Var Notes
RALPH_MAX_ITERATIONS RALPH_RUN_ITERATIONS Renamed
N/A RALPH_SECURITY_MODE New variable
N/A RALPH_SKIP_GATES New variable (comma-separated gate numbers)

New Features Worth Exploring

1. Security Tiers

Try the new security model:

# Sandbox mode (default, safest)
ralph run

# Standard mode (common development)
ralph run --security standard

# YOLO mode (maximum velocity)
ralph run --security yolo

2. Skills

Explore the new skills:

ralph skill list
ralph skill run deep-codebase-navigator
ralph skill run requirement-analyzer

3. Dashboard

Launch the web UI:

ralph dashboard

Open http://localhost:3737 to see real-time progress.

4. Claude Code Plugin

Install the plugin for IDE integration:

/plugin marketplace add kimhons/ralph-ultra-claude-code

Rollback Plan

If you encounter issues, you can rollback to Enhanced Ralph:

Step 1: Restore Backups

cd /path/to/your/project
cp .ralph/backup/prd.json.old .ralph/prd.json
cp .ralph/backup/CLAUDE.md.old CLAUDE.md

Step 2: Reinstall Enhanced Ralph

git clone https://github.com/kimhons/enhanced-ralph-claude-code.git
cd enhanced-ralph-claude-code
sudo ./install.sh

Step 3: Report the Issue

Please report migration issues to:

Frequently Asked Questions

Q: Do I need to migrate immediately?

A: No. Enhanced Ralph will continue to work, but it will not receive new features. We recommend migrating within 3 months.

Q: Will my old PRDs work with Ralph Ultra?

A: Most will work, but the schema has changed. Use ralph fix --migrate to auto-convert.

Q: Can I use both Enhanced Ralph and Ralph Ultra on the same machine?

A: No. The ralph command will point to whichever is installed last. Uninstall Enhanced Ralph before installing Ralph Ultra.

Q: What if I have custom skills?

A: Custom skills should work with minimal changes. The skill contract is backwards-compatible. Run ralph skill validate my-skill to check.

Q: Are there any performance improvements?

A: Yes. Ralph Ultra includes:

  • 30% faster loop execution due to parallel skill invocation
  • 50% fewer token usage via smarter context management
  • Incremental verification (only re-run failed gates)

Q: What happened to the "Ralph Wiggum" name?

A: The methodology is still inspired by the original "Ralph" pattern, but we've rebranded to "Ralph Ultra" to emphasize the significant enhancements and avoid confusion with the original implementation.

Getting Help

If you encounter issues during migration:

  1. Check the logs:

    tail -n 100 .ralph/audit.log

  2. Run diagnostics:

    ralph skill run environment-doctor

  3. Join the community:

  4. File an issue:

Last Updated: January 31, 2026 Migration Guide Version: 1.0