# PRD to Ralph JSON

Converts an existing product requirements document into Ralph's prd.json format.

- Repository: https://github.com/snarktank/ralph (22106 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-02-02
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add snarktank/ralph --skill ralph -g -a claude-code -y`
Codex: `npx skills add snarktank/ralph --skill ralph -g -a codex -y`
Cursor: `npx skills add snarktank/ralph --skill ralph -g -a cursor -y`
Gemini CLI: `npx skills add snarktank/ralph --skill ralph -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add snarktank/ralph`

## Description

Convert PRDs to prd.json format for the Ralph autonomous agent system. Use when you have an existing PRD and need to convert it to Ralph's JSON format. Triggers on: convert this prd, turn this into ralph format, create prd.json from this, ralph json.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Ralph PRD Converter

Converts existing PRDs to the prd.json format that Ralph uses for autonomous execution.

---

## The Job

Take a PRD (markdown file or text) and convert it to `prd.json` in your ralph directory.

---

## Output Format

```json
{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description from PRD title/intro]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 2",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}
```

---

## Story Size: The Number One Rule

**Each story must be completable in ONE Ralph iteration (one context window).**

Ralph spawns a fresh Amp instance per iteration with no memory of previous work. If a story is too big, the LLM runs out of context before finishing and produces broken code.

### Right-sized stories:
- Add a database column and migration
- Add a UI component to an existing page
- Update a server action with new logic
- Add a filter dropdown to a list

### Too big (split these):
- "Build the entire dashboard" - Split into: schema, queries, UI components, filters
- "Add authentication" - Split into: schema, middleware, login UI, session handling
- "Refactor the API" - Split into one story per endpoint or pattern

**Rule of thumb:** If you cannot describe the change in 2-3 sentences, it is too big.

---

## Story Ordering: Dependencies First

Stories execute in priority order. Earlier stories must not depend on later ones.

**Correct order:**
1. Schema/database changes (migrations)
2. Server actions / backend logic
3. UI components that use the backend
4. Dashboard/summary views that aggregate data

**Wrong order:**
1. UI component (depends on schema that does not exist yet)
2. Schema change

---

The rest: https://github.com/snarktank/ralph/blob/HEAD/skills/ralph/SKILL.md