ralph

Purpose

Convert a Product Requirements Document (PRD) in markdown to structured prd.json for Ralph loop execution. Sets up autonomous development with:

• •Feature branches from main (independent PRs, no cascading conflicts)
• •Optional scaffold skills (e.g., /mern-add-feature before implementation)
• •Detailed commit messages and PRs (full story context)

Arguments

• •<prd-file> — Path to PRD markdown file (e.g., docs/PRD.md)
• •--setup — Also copy template files (ralph.sh, CLAUDE.md, etc.)

Output

Creates scripts/ralph/ with:

Git Workflow: Feature Branches from Main

All PRs Target Main Directly

Every story creates a feature branch from main and a PR back to main:

main ─────┬─────────────────────────────────
          │
          ├── feat/story-001 ──→ PR #1 → main
          │
          ├── feat/story-002 ──→ PR #2 → main
          │
          └── feat/story-003 ──→ PR #3 → main

Benefits

Sequential Dependencies

Stories often build on each other (story-002 needs story-001's code). The workflow handles this:

1. •Run ralph-once.sh → story-001 gets PR created
2. •Merge PR #1 (via github-merge-stack or manually)
3. •Run ralph-once.sh → pulls latest main (now has story-001 code)
4. •story-002 implementation has access to story-001's code

In full autonomous mode (ralph.sh), PRs are auto-merged between stories so each iteration starts with all prior code in main.

Scaffold Skills

Stories can specify a scaffoldSkill to run before implementation. This is useful for:

• •Creating feature structure with /mern-add-feature
• •Adding authentication with /mern-add-auth
• •Setting up new modules with /nean-add-feature

prd.json with Scaffold Skill

{
  "userStories": [
    {
      "id": "user-001",
      "title": "Create User CRUD",
      "scaffoldSkill": "mern-add-feature",
      "description": "Implement user management",
      "acceptanceCriteria": ["..."],
      "passes": false
    }
  ]
}

Scaffold Skill Examples

The /ralph skill automatically adds scaffoldSkill to stories matching these patterns. Use the scaffold skill matching the detected stack:

Detailed Commits and PRs

Commit Message Format

feat(story-id): Short title

Description from prd.json

Acceptance Criteria:
- criterion 1
- criterion 2

Files changed (N):
- path/to/file1.ts
- path/to/file2.tsx

Notes: Any notes from prd.json

Story-ID: story-id

PR Body Format

## Story Title

Description from prd.json

### Acceptance Criteria
- [x] criterion 1
- [x] criterion 2

### Files Created
- path/to/file1.ts
- path/to/file2.tsx

### Notes
Any notes from prd.json

---
**Story ID:** `story-id`
**Ralph Iteration:** N

*Generated by Ralph loop*

prd.json Schema

{
  "projectName": "string",
  "description": "string",
  "userStories": [
    {
      "id": "string (kebab-case, e.g., auth-001)",
      "title": "string (short, imperative)",
      "priority": "number (1 = highest)",
      "description": "string (what to implement)",
      "acceptanceCriteria": ["string (testable criteria)"],
      "testCriteria": ["string (specific test assertions to write)"],
      "testFiles": ["string (test file paths to create)"],
      "filesToCreate": ["string (expected file paths)"],
      "scaffoldSkill": "string (optional: mern-add-feature, mern-add-auth, etc.)",
      "notes": "string (optional: hints for implementation)",
      "passes": false
    }
  ]
}

Test Fields (TDD Support)

Example:

{
  "id": "layout-001",
  "title": "Create page header",
  "acceptanceCriteria": [
    "Header displays logo",
    "Header includes navigation links"
  ],
  "testCriteria": [
    "Header renders logo image with correct alt text",
    "Header contains Home, About, Contact links",
    "Navigation links have correct href attributes"
  ],
  "testFiles": [
    "apps/web/src/components/layout/__tests__/Header.test.tsx"
  ],
  "filesToCreate": [
    "apps/web/src/components/layout/Header.tsx"
  ]
}

Environment Variables

Commands

Single Iteration (Recommended Start)

# Run one story (create PR, stop for review)
./scripts/ralph/ralph-once.sh

# Run one story and auto-merge the PR
./scripts/ralph/ralph-once.sh --merge

# Custom merge timeout (default: 600s)
./scripts/ralph/ralph-once.sh --merge --merge-timeout 900

Full Autonomous Loop

# Run up to 10 stories (auto-merge between each)
./scripts/ralph/ralph.sh

# Custom max iterations
./scripts/ralph/ralph.sh 50

# Create PRs without auto-merging
./scripts/ralph/ralph.sh 50 --no-merge

Status Checks

# Story status
cat scripts/ralph/prd.json | jq '.userStories[] | {id, title, passes}'

# Progress log
cat scripts/ralph/progress.txt

# Branch stack
git branch -a | grep feat/

Story Sizing (Critical)

Each story must complete in ONE context window. Split large stories:

Priority Rules

1. •Shared code first (schemas, types, utilities)
2. •Dependencies before dependents (model before API, API before UI)
3. •PRD order (earlier = higher priority)
4. •Logical sequence (scaffold → core → polish)

Stack Detection (Required)

Before generating prd.json, determine the project stack by examining the project root:

Use the detected stack to select scaffold skill prefix. Do NOT assume MERN. If ambiguous, ask the user.

Workflow

1. •Read the PRD markdown file
2. •Detect project stack (see Stack Detection above)
3. •Extract features and user stories
4. •Split large stories into right-sized chunks
5. •Automatically add scaffoldSkill to stories that need it (using detected stack prefix)
6. •Assign priorities based on dependencies
7. •Generate prd.json
8. •If --setup, copy template files
9. •Report summary

Scaffold Skill Auto-Detection

When generating prd.json, automatically add the scaffoldSkill field to stories that match these patterns:

Do NOT add scaffoldSkill for:

• •Bug fixes (modifying existing code)
• •Refactoring (restructuring existing code)
• •Configuration/setup (no new features)
• •Static content (config-driven, no database)
• •UI-only changes (no new data model)
• •Extending existing features (files already exist)

After Setup

1. •Review scripts/ralph/prd.json — verify priorities and scaffold skills are correct
2. •Run ./scripts/ralph/ralph-once.sh — test single iteration
3. •Review changes, verify quality
4. •Run ./scripts/ralph/ralph.sh N — full loop
5. •Create PR(s) to merge to main

Note: The skill automatically adds scaffoldSkill to appropriate stories. Review to verify correctness, not to add them manually.

Self-Improvement

After this skill completes, run /retro-create to review the session for issues and improve this skill. This is automatic — do not skip it.

Reference

See reference/ralph-reference.md for detailed documentation.