Run RALPH

Execute the RALPH autonomous development loop to implement features from the PRD.

Two Operating Modes

1. PRD Loop Mode (Greenfield)

For implementing features from a PRD file:

./scripts/ralph/ralph.sh 20

2. Single-Task Mode (Brownfield)

For quick one-off tasks without a PRD:

./scripts/ralph/ralph.sh --task "Fix the login button styling"

Prerequisites Check

1. Verify PRD exists (one of these formats):

cat prd.json 2>/dev/null || cat PRD.md 2>/dev/null || cat tasks.yaml 2>/dev/null

2. Check RALPH configuration:

cat .ralph/config.yaml

3. Check current status:

node scripts/run-ralph.js --status

Running RALPH

Start the autonomous loop:

# Run up to 20 iterations
./scripts/ralph/ralph.sh 20

# Or use the runner script
node scripts/run-ralph.js 20

With options:

# Skip tests (faster iteration)
./scripts/ralph/ralph.sh --skip-tests 20

# Skip linting
./scripts/ralph/ralph.sh --skip-lint 20

# Custom branch
./scripts/ralph/ralph.sh --branch feature/my-feature 20

# Dry run (no commits)
./scripts/ralph/ralph.sh --dry-run 20

PRD Formats Supported

JSON (prd.json)

{
  "userStories": [
    { "id": "US-001", "title": "...", "passes": false }
  ]
}

Markdown (PRD.md)

## Tasks
- [ ] First task
- [ ] Second task
- [x] Completed task

YAML (tasks.yaml)

tasks:
  - title: First task
    completed: false

Configuration

Edit .ralph/config.yaml to customize:

• rules: Instructions the AI MUST follow
• boundaries: Files the AI should NOT modify
• commands: Quality gate commands
• settings: Retry logic, auto-commit, etc.

Monitoring

• Watch .ralph/progress.txt for iteration logs and learnings
• Check PRD file for story completion status
• Review git log for commits: git log --oneline -20

Commands

If Stuck

1. Check .ralph/progress.txt for patterns and learnings
2. Review .ralph/config.yaml rules and boundaries
3. Manually fix blocking issues
4. Reset if needed: node scripts/run-ralph.js --reset
5. Resume: ./scripts/ralph/ralph.sh 20

Quality Gates

RALPH must pass ALL quality gates before marking a task complete:

1. Typecheck: npm run typecheck or npx tsc --noEmit
2. Lint: npm run lint
3. Tests: npm test

Configure these in .ralph/config.yaml under commands.