doravidan/ralph-run

RALPH-RUN - Multi-Agent Autonomous Development

Execute the RALPH development cycle using a multi-agent pipeline: Planner → Coder → QA Reviewer → QA Fixer

Commands

| Command | Description | |---------|-------------| | /ralph-run | Start with default 10 iterations | | /ralph-run 20 | Start with 20 iterations | | /ralph-run --parallel | Run independent subtasks in parallel | | /ralph-run --simple | Skip planner, direct implementation | | /ralph-run --task "desc" | Single-task mode (no PRD needed) | | /ralph-run --no-worktree | Run in current branch (skip worktree isolation) |

Related Commands

| Command | Description | |---------|-------------| | /ralph-merge | Merge completed worktree to main branch | | /ralph-review | Review worktree changes before merging | | /ralph-discard | Abandon worktree without merging |

Triggers

• /ralph-run
• "run RALPH"
• "start autonomous development"
• "implement the PRD"

Critical Rules

1. USE AGENT PIPELINE - Planner → Coder → QA Reviewer → QA Fixer
2. ONE SUBTASK AT A TIME - Complete fully before moving on
3. QA MUST PASS - No skipping QA validation
4. ASK WHEN UNCERTAIN - Use AskUserQuestion for ambiguity
5. RESPECT BOUNDARIES - Never modify files in boundaries list
6. LOG TO MEMORY - Save learnings for future iterations
7. MAX 3 QA FIX ATTEMPTS - Escalate to human after 3 failures

Multi-Agent Pipeline

┌─────────────────────────────────────────────────────────────────┐
│                    RALPH Pipeline v3.0                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐ │
│   │ PLANNER  │───▶│  CODER   │───▶│ QA REV   │───▶│ QA FIX   │ │
│   └──────────┘    └──────────┘    └──────────┘    └──────────┘ │
│        │                │               │               │       │
│        ▼                ▼               ▼               ▼       │
│   impl_plan.json   subtask done    QA report      fixes done   │
│                                         │               │       │
│                                         └───────────────┘       │
│                                         (loop until pass)       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Phase 0: Prerequisites & Worktree Setup

Before starting, verify environment and set up isolated worktree:

# Check for PRD
if [ -f prd.json ]; then
  REMAINING=$(cat prd.json | jq '[.userStories[] | select(.passes == false)] | length')
  PROJECT=$(cat prd.json | jq -r '.project')
  BRANCH=$(cat prd.json | jq -r '.branchName // "ralph/feature"')
  echo "✓ PRD: $PROJECT - $REMAINING stories remaining"
else
  echo "❌ No prd.json - run /prd first"
  exit 1
fi

# Check for implementation plan
if [ -f implementation_plan.json ]; then
  echo "✓ Implementation plan exists"
else
  echo "⚠ No implementation_plan.json - will invoke Planner"
fi

# Check for config
[ -f .ralph/config.yaml ] && echo "✓ Config loaded"
[ -f PROJECT_SPEC.md ] && echo "✓ Project spec loaded"

Worktree Isolation (unless --no-worktree)

RALPH runs in an isolated git worktree to protect the main branch:

╔════════════════════════════════════════════════════════════════╗
║                    Worktree Setup                               ║
╚════════════════════════════════════════════════════════════════╝

Checking for existing worktree...

Creating worktree for: user-authentication
  Branch: ralph/user-authentication
  Path: .worktrees/user-authentication/

✓ Worktree created
✓ .gitignore updated (ignoring .worktrees/)

All development will happen in: .worktrees/user-authentication/

When complete, use:
  /ralph-merge    - Merge changes to main
  /ralph-review   - Review changes before merging
  /ralph-discard  - Abandon changes

Worktree Structure:

project/
├── .worktrees/                    # Worktree directory (gitignored)
│   └── {spec-name}/               # Isolated working copy
│       ├── src/                   # Full project copy
│       ├── .ralph/                # RALPH state
│       └── prd.json               # PRD file
├── src/                           # Main branch (untouched)
└── prd.json                       # Original PRD

Benefits:

• Main branch stays clean until merge
• Safe experimentation without polluting history
• Easy discard if implementation goes wrong
• Review all changes before integrating

Phase 1: Planning (Planner Agent)

If no implementation_plan.json exists, invoke the Planner:

The Planner agent decomposes stories into subtasks:

╔════════════════════════════════════════════════════════════════╗
║                    Phase 1: PLANNING                            ║
║                    Agent: Planner                               ║
╚════════════════════════════════════════════════════════════════╝

Analyzing PRD...
Reading PROJECT_SPEC.md for patterns...
Querying memory for past implementations...

Decomposing US-001 into subtasks:
  ST-001-1: Create User type definitions
  ST-001-2: Create Zod validation schema
  ST-001-3: Create User service layer
  ST-001-4: Add unit tests

Writing implementation_plan.json...

Planner outputs implementation_plan.json:

{
  "stories": [{
    "storyId": "US-001",
    "subtasks": [{
      "id": "ST-001-1",
      "title": "Create User type definitions",
      "files_to_create": ["src/types/user.ts"],
      "files_to_modify": ["src/types/index.ts"],
      "dependencies": [],
      "acceptance_criteria": ["User interface defined", "Exported from index"]
    }]
  }]
}

Phase 2: Implementation (Coder Agent)

For each subtask, the Coder agent implements:

╔════════════════════════════════════════════════════════════════╗
║                    Phase 2: IMPLEMENTATION                      ║
║                    Agent: Coder                                 ║
║                    Subtask: ST-001-1                            ║
╚════════════════════════════════════════════════════════════════╝

Reading subtask requirements...
Checking project patterns...
Loading memory insights...

Implementing: Create User type definitions
  → Creating src/types/user.ts
  → Modifying src/types/index.ts

Running quality gates...
  ✓ Typecheck passed
  ✓ Lint passed
  ✓ Tests passed

Subtask implementation complete.
Passing to QA Reviewer...

Coder can spawn subagents for parallel work:

// For independent subtasks, use Task tool
Task({
  subagent_type: "general-purpose",
  description: "Implement ST-001-2",
  prompt: "Implement the Zod validation schema...",
  run_in_background: true
})

Phase 3: QA Review (QA Reviewer Agent)

QA Reviewer validates each subtask against acceptance criteria:

╔════════════════════════════════════════════════════════════════╗
║                    Phase 3: QA REVIEW                           ║
║                    Agent: QA Reviewer                           ║
║                    Subtask: ST-001-1                            ║
╚════════════════════════════════════════════════════════════════╝

Validating acceptance criteria...

Criterion: User interface defined
  ✓ PASS - Found User interface in src/types/user.ts:5-15

Criterion: Exported from index
  ✗ FAIL - Export statement missing from src/types/index.ts

Quality Gates:
  ✓ Typecheck
  ✓ Lint
  ✓ Tests

Issues Found: 1
  [HIGH] Missing export in src/types/index.ts

Status: NEEDS_FIX
Passing to QA Fixer...

QA Report Schema:

{
  "subtaskId": "ST-001-1",
  "status": "needs_fix",
  "criteria": [
    {"criterion": "User interface defined", "passed": true},
    {"criterion": "Exported from index", "passed": false, "issue": "Missing export"}
  ],
  "issues": [{
    "severity": "high",
    "file": "src/types/index.ts",
    "suggestion": "Add: export * from './user';"
  }]
}

Phase 4: QA Fix (QA Fixer Agent)

If QA fails, QA Fixer attempts to resolve issues:

╔════════════════════════════════════════════════════════════════╗
║                    Phase 4: QA FIX                              ║
║                    Agent: QA Fixer                              ║
║                    Attempt: 1/3                                 ║
╚════════════════════════════════════════════════════════════════╝

Issues to fix: 1
  [HIGH] Missing export in src/types/index.ts

Applying fix...
  → Editing src/types/index.ts
  → Adding: export * from './user';

Re-running quality gates...
  ✓ Typecheck passed
  ✓ Lint passed
  ✓ Tests passed

Status: ALL_FIXED
Returning to QA Reviewer for verification...

QA Fix Loop:

QA Reviewer ─────▶ PASS ─────▶ Next Subtask
     │
     ▼
  FAIL (issues)
     │
     ▼
QA Fixer ─────▶ Fixed ─────▶ QA Reviewer (re-verify)
     │
     ▼
  Attempt 3 failed
     │
     ▼
ESCALATE TO HUMAN

Phase 5: Commit & Update

After subtask passes QA:

# Commit the changes
git add -A
git commit -m "feat: ST-001-1 - Create User type definitions

- Created User interface with id, email, createdAt
- Exported from src/types/index.ts
- All quality gates pass

Reviewed-By: QA-Agent
Co-Authored-By: RALPH <[email protected]>"

# Update implementation plan
# Mark subtask as complete

Phase 6: Memory & Learning

Log insights to .ralph/memory/insights.json:

{
  "context": "Implementing type definitions",
  "learning": "Always export new types from index.ts immediately",
  "tags": ["types", "exports", "patterns"],
  "timestamp": "2026-01-25T10:30:00Z"
}

Phase 7: Context Compaction

If compact_after_each_story: true in config:

📦 Compacting context...

Preserving:
  - PRD state (5 stories remaining)
  - Memory insights (12 total)
  - Progress log (1 story complete)

Releasing:
  - File exploration details
  - Implementation specifics
  - QA fix history

Context compacted at 60% threshold.

Full Iteration Output

╔════════════════════════════════════════════════════════════════╗
║               RALPH Iteration 1 Complete                        ║
╚════════════════════════════════════════════════════════════════╝

Worktree: .worktrees/user-authentication
Branch: ralph/user-authentication

Story: US-001 - Create User model
Subtasks: 4/4 complete

Pipeline Summary:
  ┌──────────────────────────────────────────────────────────────┐
  │ Planner   │ ✓ Created 4 subtasks                            │
  │ Coder     │ ✓ Implemented all subtasks                      │
  │ QA Review │ ✓ 3 passed first time, 1 needed fix             │
  │ QA Fixer  │ ✓ Fixed 1 issue (missing export)                │
  └──────────────────────────────────────────────────────────────┘

Quality Gates:
  ✓ Typecheck passed
  ✓ Lint passed
  ✓ Tests passed (4 new tests)

Commits (in worktree):
  abc1234 feat: ST-001-1 - Create User type definitions
  def5678 feat: ST-001-2 - Create Zod validation schema
  ghi9012 feat: ST-001-3 - Create User service layer
  jkl3456 feat: ST-001-4 - Add unit tests

Memory:
  + 3 new insights saved

Progress: 1/6 stories (17% complete)
Remaining: 5 stories

Worktree Status:
  ✓ 4 commits ahead of main
  ✓ 12 files changed

Next: US-002 - Implement password hashing

When complete, run /ralph-merge to integrate changes.

Escalation Protocol

When QA Fixer fails 3 times:

╔════════════════════════════════════════════════════════════════╗
║                 ESCALATION REQUIRED                             ║
╚════════════════════════════════════════════════════════════════╝

Subtask: ST-001-3 - Create User service
Attempts: 3 (max reached)

Unresolved Issue:
  [HIGH] Type mismatch in UserService.create()

  Tried:
    1. Cast to correct type - still fails
    2. Add type assertion - introduces any
    3. Refactor function signature - breaks tests

Recommendation:
  This may require architectural changes.

Options:
  1. Provide guidance to continue
  2. Skip this subtask for now
  3. Abort RALPH run

Use AskUserQuestion for human decision.

Parallel Mode

With /ralph-run --parallel:

╔════════════════════════════════════════════════════════════════╗
║               RALPH Parallel Mode                               ║
╚════════════════════════════════════════════════════════════════╝

Analyzing subtask dependencies...

Parallel Batch 1 (no dependencies):
  → Spawning agent: ST-001-1
  → Spawning agent: ST-001-2

Waiting for completion...

[████████░░] ST-001-1: Implementing types...
[██████████] ST-001-2: ✓ Complete

Parallel Batch 2 (depends on batch 1):
  → Spawning agent: ST-001-3
  → Spawning agent: ST-001-4

Simple Mode

With /ralph-run --simple:

Skip the Planner agent, implement stories directly:

╔════════════════════════════════════════════════════════════════╗
║               RALPH Simple Mode                                 ║
╚════════════════════════════════════════════════════════════════╝

Skipping Planner (simple mode)
Implementing US-001 directly...

Pipeline: Coder → QA Reviewer → QA Fixer

Complexity-Based Pipeline Adaptation

RALPH automatically adapts the pipeline based on PRD complexity:

Auto-Detection

╔════════════════════════════════════════════════════════════════╗
║               Complexity Classification                         ║
╚════════════════════════════════════════════════════════════════╝

Analyzing PRD complexity...

Level: STANDARD
Score: 28

Metrics:
  Stories: 6
  Files affected: 12
  Dependencies: 3
  Acceptance criteria: 24

Pipeline configured for STANDARD complexity.

SIMPLE Pipeline (1-2 stories, minimal dependencies)

╔════════════════════════════════════════════════════════════════╗
║               SIMPLE Pipeline                                   ║
╚════════════════════════════════════════════════════════════════╝

Complexity: SIMPLE (score < 15)

Pipeline: CODER → LIGHT QA

  - No Planner agent (direct implementation)
  - Light QA validation (essential checks only)
  - No parallel execution
  - No research phase
  - Single iteration per story

STANDARD Pipeline (3-6 stories, moderate complexity)

╔════════════════════════════════════════════════════════════════╗
║               STANDARD Pipeline                                 ║
╚════════════════════════════════════════════════════════════════╝

Complexity: STANDARD (score 15-40)

Pipeline: PLANNER → CODER → QA REVIEWER → QA FIXER

  - Full planning phase
  - Standard QA validation
  - Parallel execution enabled
  - Max 3 QA fix attempts
  - Memory logging

COMPLEX Pipeline (7+ stories, architectural changes)

╔════════════════════════════════════════════════════════════════╗
║               COMPLEX Pipeline                                  ║
╚════════════════════════════════════════════════════════════════╝

Complexity: COMPLEX (score > 40)

Pipeline: RESEARCH → PLANNER → SELF-CRITIQUE → CODER → EXTENSIVE QA

  - Research phase before planning
  - Extended planning with risk analysis
  - Self-critique validates plan quality
  - Extensive QA with more iterations
  - Max 5 QA fix attempts
  - Mandatory human checkpoints

Override Complexity

Force a specific complexity level:

/ralph-run --complexity=COMPLEX
/ralph-run --complexity=SIMPLE

Complexity Settings in Config

# .ralph/config.yaml
complexity:
  auto_detect: true
  default_level: STANDARD

  simple:
    max_qa_attempts: 2
    use_planner: false
    parallel_enabled: false

  standard:
    max_qa_attempts: 3
    use_planner: true
    parallel_enabled: true

  complex:
    max_qa_attempts: 5
    use_planner: true
    parallel_enabled: true
    research_phase: true
    self_critique: true
    human_checkpoints: true

Error Recovery

| Error | Action | |-------|--------| | No PRD found | Direct to /prd [feature] | | No implementation plan | Invoke Planner agent | | QA fails 3 times | Escalate to human | | Quality gate fails | QA Fixer attempts fix | | Agent timeout | Retry or skip subtask | | Unclear requirements | Use AskUserQuestion |

Configuration

In .ralph/config.yaml:

pipeline:
  use_planner: true
  max_qa_attempts: 3
  parallel_enabled: false
  max_parallel_agents: 4

settings:
  compact_after_each_story: true
  compact_threshold: 60
  commit_after_each_subtask: true

Tips

• Trust the pipeline - Let each agent do its job
• QA is mandatory - Never skip validation
• Escalate early - 3 failed attempts = human help needed
• Log everything - Memory helps future iterations
• Parallel when safe - Only for truly independent work