/ralph

name: ralph
description: "Convert PRDs to prd.json format for the Ralph autonomous agent system"
license: MIT
compatibility: cline, claude, opencode, amp, codex, gemini, cursor, pi
hint: Use when converting PRDs to prd.json format for Ralph autonomous agent system
user-invocable: true
disable-model-invocation: true
metadata:
  audience: all
  workflow: product

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

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

---

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"

For stories that change UI, also include:

"Verify in browser using dev-browser skill"

Frontend stories are NOT complete until visually verified. Ralph will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work.

---

Conversion Rules

1. **Each user story becomes one JSON entry** 2. **IDs**: Sequential (US-001, US-002, etc.) 3. **Priority**: Based on dependency order, then document order 4. **All stories**: `passes: false` and empty `notes` 5. **branchName**: Derive from feature name, kebab-case, prefixed with `ralph/` 6. **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:**

1. US-001: Add notifications table to database 2. US-002: Create notification service for sending notifications 3. US-003: Add notification bell icon to header 4. US-004: Create notification dropdown panel 5. US-005: Add mark-as-read functionality 6. 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",
				"Verify in browser using dev-browser skill"
			],
			"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 dev-browser skill"
			],
			"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