ralph

name	ralph
description	Convert a PRD markdown file to prd.json and set up Ralph loop infrastructure for autonomous development with feature branches and optional scaffold skills.
argument-hint	<prd-file.md> [--setup]

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:

File	Purpose
prd.json	User stories with status, scaffold skills, acceptance criteria
CLAUDE.md	Prompt for each iteration
ralph.sh	Main loop script (autonomous, auto-merge between stories)
ralph-once.sh	Single iteration (human-in-the-loop)
progress.txt	Progress log

---

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

Benefit	Description
No cascading conflicts	Merging one PR doesn't break others
Independent PRs	Each PR can be reviewed/merged separately
Simple merges	No rebasing or base updates needed
Clear history	Each feature is a single squash commit

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:

Story Type	MERN	NEAN	iOS
New CRUD feature	mern-add-feature	nean-add-feature	ios-add-feature
Authentication	mern-add-auth	nean-add-auth	ios-add-auth
Bug fix / Refactor / Config	(none)	(none)	(none)

---

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" 
       
       
    
  

Test Fields (TDD Support)

Field	Purpose
testCriteria	Specific assertions to write (derived from acceptanceCriteria)
testFiles	Test file paths to create BEFORE implementation

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

Variable	Default	Purpose
RALPH_MAIN_BRANCH	main	Base branch name

---

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:

Too Big	Split Into
"Build authentication"	Login form, Auth API, Session provider
"Create user CRUD"	Schema/types, Model + API, UI components
"Add dashboard"	Layout, Stats cards, Charts, Filters

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:

Indicator	Stack	Scaffold Prefix
pnpm-workspace.yaml + next.config.*	MERN	mern-
nx.json + angular.json	NEAN	nean-
project.yml (XcodeGen) or *.xcodeproj	iOS	ios-
Package.swift	iOS	ios-

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:

Story Pattern	Scaffold Skill	Detection Criteria
New CRUD feature	mern-add-feature	Creates schema + model + API + UI for a new entity
Authentication	mern-add-auth	Implements login, registration, sessions
New NEAN feature	nean-add-feature	Creates DTO + entity + service + controller + UI
NEAN auth	nean-add-auth	Implements guards, strategies, auth module
iOS feature	ios-add-feature	Creates View + ViewModel + tests
iOS auth	ios-add-auth	Implements auth service, keychain, biometrics

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.