# Ralph

> Convert a PRD markdown file to prd.json and set up Ralph loop infrastructure for autonomous development with feature branches and optional scaffold skills. Use when this capability is needed.

- Skill: `tomevault-io/ralph-9` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/ralph-9`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ralph-9/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/ralph-9

---


## 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

```json
{
  "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

```markdown
## 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

```json
{
  "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)

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

**Example:**
```json
{
  "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)

```bash
# 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

```bash
# 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

```bash
# 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.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/edfenton) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->