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 the Ralph project directory.

Usage: /ralph convert <prd-file> to <project-name>

Example: /ralph convert tasks/prd-task-status.md to task-status

This creates: .ralph/projects/task-status/prd.json

Output Location

All output goes to: .ralph/projects/<project-name>/

Before writing, ensure the directory exists:

bash

mkdir -p .ralph/projects/<project-name>

Write the prd.json to: .ralph/projects/<project-name>/prd.json

Output Format

json

{
  "project": "[Project Name]",
  "branchName": "ralph/[project-name]",
  "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,
      "status": "pending",
      "phases": {
        "investigate": { "status": "pending", "output": null },
        "implement": { "status": "pending", "output": null },
        "test": { "status": "pending", "output": null },
        "review": { "status": "pending", "output": null },
        "document": { "status": "pending", "output": null }
      },
      "passes": false,
      "notes": ""
    }
  ]
}

Story Size: The Number One Rule

Each story must be completable in ONE Ralph manager invocation.

Ralph uses a phased manager/subagent architecture. If a story is too big, the manager runs out of context before finishing all phases.

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:

code

"Typecheck passes"

For stories with testable logic, also include:

code

"Tests pass"

For stories that change UI, also include:

code

"Verify in browser"

Frontend stories are NOT complete until visually verified.

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: status: "pending", passes: false, empty notes
•All phases: Initialize with status: "pending" and output: null
•branchName: Use the project name, 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

Command: /ralph convert tasks/prd-task-status.md to task-status

Input PRD (tasks/prd-task-status.md):

markdown

# 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 (.ralph/projects/task-status/prd.json):

json

{
  "project": "Task Status",
  "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,
      "status": "pending",
      "phases": {
        "investigate": { "status": "pending", "output": null },
        "implement": { "status": "pending", "output": null },
        "test": { "status": "pending", "output": null },
        "review": { "status": "pending", "output": null },
        "document": { "status": "pending", "output": null }
      },
      "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"
      ],
      "priority": 2,
      "status": "pending",
      "phases": {
        "investigate": { "status": "pending", "output": null },
        "implement": { "status": "pending", "output": null },
        "test": { "status": "pending", "output": null },
        "review": { "status": "pending", "output": null },
        "document": { "status": "pending", "output": null }
      },
      "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"
      ],
      "priority": 3,
      "status": "pending",
      "phases": {
        "investigate": { "status": "pending", "output": null },
        "implement": { "status": "pending", "output": null },
        "test": { "status": "pending", "output": null },
        "review": { "status": "pending", "output": null },
        "document": { "status": "pending", "output": null }
      },
      "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"
      ],
      "priority": 4,
      "status": "pending",
      "phases": {
        "investigate": { "status": "pending", "output": null },
        "implement": { "status": "pending", "output": null },
        "test": { "status": "pending", "output": null },
        "review": { "status": "pending", "output": null },
        "document": { "status": "pending", "output": null }
      },
      "passes": false,
      "notes": ""
    }
  ]
}

After Creating prd.json

Tell the user:

code

Created: .ralph/projects/<project-name>/prd.json

To run Ralph:
  .ralph/ralph.sh <project-name>

Checklist Before Saving

Before writing prd.json, verify:

• Project directory created: .ralph/projects/<project-name>/
• Each story is completable in one manager invocation (small enough)
• Stories are ordered by dependency (schema to backend to UI)
• Every story has "Typecheck passes" as criterion
• UI stories have "Verify in browser" as criterion
• Acceptance criteria are verifiable (not vague)
• No story depends on a later story
• All stories have phases initialized with pending status
• branchName matches the project name with ralph/ prefix