Convert PRD markdown to prd.json format for Ralph autonomous agent
Converts PRD markdown to prd.json format for Ralph autonomous agent
/plugin marketplace add Filiup/filiup_claude_marketpace/plugin install ralph-prd@filiup_marketplacePRD_FILE_PATHConverts existing PRDs to the prd.json format that Ralph uses for autonomous execution.
Take a PRD (markdown file) and convert it to prd.json in the current directory.
{
"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": ""
}
]
}
Each story must be completable in ONE Ralph iteration (one context window).
Ralph spawns a fresh Claude CLI process per user story. Each process gets a clean context window (~150k tokens). If a story is too big to implement within one context window, Claude will fail or produce incomplete/broken code.
Rule of thumb: If you cannot describe the change in 2-3 sentences, it is too big.
Stories execute in priority order. Earlier stories must not depend on later ones.
Correct order:
Wrong order:
Each criterion must be something Ralph can CHECK, not something vague.
status column to tasks table with default 'pending'""Typecheck passes"
For stories with testable logic, also include:
"Tests pass"
"Verify in browser using MCP browser"
Frontend stories are NOT complete until visually verified. Ralph will use the MCP browser to navigate to the page, interact with the UI, and confirm changes work.
passes: false and empty notesralph/If a PRD has big features, split them:
Original:
"Add user notification system"
Split into:
Each is one focused change that can be completed and verified independently.
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",
"Verify in browser using MCP browser"
],
"priority": 2,
"passes": false,
"notes": ""
},
{
"id": "US-003",
"title": "Add status toggle to task list rows",
"description": "As a user, I want to change task status directly from the list.",
"acceptanceCriteria": [
"Each row has status dropdown or toggle",
"Changing status saves immediately",
"UI updates without page refresh",
"Typecheck passes",
"Verify in browser using MCP browser"
],
"priority": 3,
"passes": false,
"notes": ""
},
{
"id": "US-004",
"title": "Filter tasks by status",
"description": "As a user, I want to filter the list to see only certain statuses.",
"acceptanceCriteria": [
"Filter dropdown: All | Pending | In Progress | Done",
"Filter persists in URL params",
"Typecheck passes",
"Verify in browser using MCP browser"
],
"priority": 4,
"passes": false,
"notes": ""
}
]
}
Before writing a new prd.json, check if there is an existing one from a different feature:
prd.json if it existsbranchName differs from the new feature's branch nameprogress.txt has content beyond the header:
archive/YYYY-MM-DD-feature-name/prd.json and progress.txt to archiveprogress.txt with fresh headerBefore writing prd.json, verify: