| name | ralph |
| description | Convert an existing PRD into prd.json format for Ralph autonomous agent execution. Use when you have a PRD and want to run it through the Ralph loop. Triggers on: convert this prd, turn this into ralph format, create prd.json, ralph json.
|
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 .ralph/prd.json.
Output Format
{
"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 Claude/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:
- Schema/database changes (migrations)
- Server actions / backend logic
- UI components that use the backend
- Dashboard/summary views that aggregate data
Wrong order:
- UI component (depends on schema that does not exist yet)
- Schema change
Acceptance Criteria: Must Be Verifiable
Each criterion must be something Ralph can CHECK, not something vague.
Good criteria (verifiable):
- "Add status column to tasks table with default 'pending'"
- "Filter dropdown has options: All, Active, Completed"
- "Clicking delete shows confirmation dialog"
- "Typecheck passes"
- "Tests pass"
Bad criteria (vague):
- "Works correctly"
- "User can do X easily"
- "Good UX"
- "Handles edge cases"
Always include as final criterion:
"Typecheck passes"
For stories with testable logic, also include:
"Tests pass"
<% if (playwright) { %>
For stories that change UI, also include:
<% if (playwright === 'cli') { -%>
"Verify in browser using Playwright CLI"
<% } else { -%>
"Verify in browser using Playwright MCP tools"
<% } -%>
<% if (playwright === 'cli') { -%>
Frontend stories are NOT complete until visually verified. Ralph will use playwright-cli to navigate to the page, take snapshots/screenshots, and confirm changes work.
<% } else { -%>
Frontend stories are NOT complete until visually verified. Ralph will use Playwright MCP tools to navigate to the page, interact with the UI, and confirm changes work.
<% } -%>
<% } %>
Conversion Rules
- Each user story becomes one JSON entry
- IDs: Sequential (US-001, US-002, etc.)
- Priority: Based on dependency order, then document order
- All stories:
passes: false and empty notes
- branchName: Derive from feature name, kebab-case, prefixed with
ralph/
- Always add: "Typecheck passes" to every story's acceptance criteria
Splitting Large PRDs
If a PRD has big features, split them:
Original:
"Add user notification system"
Split into:
- US-001: Add notifications table to database
- US-002: Create notification service for sending notifications
- US-003: Add notification bell icon to header
- US-004: Create notification dropdown panel
- US-005: Add mark-as-read functionality
- US-006: Add notification preferences page
Each is one focused change that can be completed and verified independently.
Example
Input PRD:
# Task Status Feature
Add ability to mark tasks with different statuses.
## Requirements
- Toggle between pending/in-progress/done on task list
- Filter list by status
- Show status badge on each task
- Persist status in database
Output prd.json:
{
"project": "TaskApp",
"branchName": "ralph/task-status",
"description": "Task Status Feature - Track task progress with status indicators",
"userStories": [
{
"id": "US-001",
"title": "Add status field to tasks table",
"description": "As a developer, I need to store task status in the database.",
"acceptanceCriteria": [
"Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
"Generate and run migration successfully",
"Typecheck passes"
],
"priority": 1,
"passes": false,
"notes": ""
},
{
"id": "US-002",
"title": "Display status badge on task cards",
"description": "As a user, I want to see task status at a glance.",
"acceptanceCriteria": [
"Each task card shows colored status badge",
"Badge colors: gray=pending, blue=in_progress, green=done",
"Typecheck passes"<% if (playwright === 'cli') { %>,
"Verify in browser using Playwright CLI"<% } else if (playwright === 'mcp') { %>,
"Verify in browser using Playwright MCP tools"<% } %>
],
"priority": 2,
"passes": false,
"notes": ""
}
]
}
Archiving Previous Runs
Before writing a new prd.json, check if there is an existing one from a different feature:
- Read the current
.ralph/prd.json if it exists
- Check if
branchName differs from the new feature's branch name
- If different AND
.ralph/progress.txt has content beyond the header:
- Create archive folder:
.ralph/archive/YYYY-MM-DD-feature-name/
- Copy current
prd.json and progress.txt to archive
- Reset
progress.txt with fresh header
Checklist Before Saving
Before writing .ralph/prd.json, verify:
