prd.json Format

Complete schema reference for Ralph’s prd.json PRD format

The prd.json file is Ralph’s structured format for product requirement documents. It breaks features into small, autonomous user stories that Ralph can implement one at a time.

File Structure

{
  "project": "string",
  "branchName": "string",
  "description": "string",
  "userStories": []
}

Top-Level Fields

project · string · required

The name of the project or application.

Example: "MyApp"

branchName · string · required

Git branch name for this feature. Must be prefixed with ralph/ and use kebab-case.

Example: "ralph/task-priority"

Pattern: ralph/[feature-name-kebab-case]

description · string · required

High-level description of the feature being implemented.

Example: "Task Priority System - Add priority levels to tasks"

userStories · array · required

Array of user story objects. Stories execute in priority order.

User Story Object

Each story in the userStories array has the following structure:

id · string · required

Unique identifier for the story. Use sequential format.

Format: US-001, US-002, US-003, etc.

title · string · required

Brief, descriptive title for the user story.

Example: "Add priority field to database"

description · string · required

User story in standard format explaining the “who, what, why.”

Format: "As a [user type], I want [feature] so that [benefit]"

Example: "As a developer, I need to store task priority so it persists across sessions."

acceptanceCriteria · string[] · required

Array of verifiable acceptance criteria. Must be checkable, not vague.

Required criteria:

• Always include: "Typecheck passes"
• For UI stories, include: "Verify in browser using dev-browser skill"
• For testable logic, include: "Tests pass"

Example:

[
  "Add priority column to tasks table: 'high' | 'medium' | 'low' (default 'medium')",
  "Generate and run migration successfully",
  "Typecheck passes"
]

priority · number · required

Execution order. Lower numbers execute first. Must account for dependencies.

Values: 1, 2, 3, etc.

Ordering rule: Dependencies first (schema → backend → UI)

passes · boolean · required

Whether the story has been successfully implemented.

Initial value: false

Updated by: Ralph sets to true after successful implementation and commit

notes · string · required

Additional notes or context. Typically empty initially.

Initial value: ""

Complete Example

{
  "project": "MyApp",
  "branchName": "ralph/task-priority",
  "description": "Task Priority System - Add priority levels to tasks",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add priority field to database",
      "description": "As a developer, I need to store task priority so it persists across sessions.",
      "acceptanceCriteria": [
        "Add priority column to tasks table: 'high' | 'medium' | 'low' (default 'medium')",
        "Generate and run migration successfully",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-002",
      "title": "Display priority indicator on task cards",
      "description": "As a user, I want to see task priority at a glance.",
      "acceptanceCriteria": [
        "Each task card shows colored priority badge (red=high, yellow=medium, gray=low)",
        "Priority visible without hovering or clicking",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 2,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-003",
      "title": "Add priority selector to task edit",
      "description": "As a user, I want to change a task's priority when editing it.",
      "acceptanceCriteria": [
        "Priority dropdown in task edit modal",
        "Shows current priority as selected",
        "Saves immediately on selection change",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 3,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-004",
      "title": "Filter tasks by priority",
      "description": "As a user, I want to filter the task list to see only high-priority items.",
      "acceptanceCriteria": [
        "Filter dropdown with options: All | High | Medium | Low",
        "Filter persists in URL params",
        "Empty state message when no tasks match filter",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 4,
      "passes": false,
      "notes": ""
    }
  ]
}

Story Sizing Guidelines

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

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

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’s too big.

Story Ordering Rules

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 doesn’t exist yet) ❌
2. Schema change

Acceptance Criteria Best Practices

Each criterion must be verifiable, not 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” ❌

Required Criteria

Always include as final criterion:

"Typecheck passes"

For UI stories, also include:

"Verify in browser using dev-browser skill"

For testable logic, also include:

"Tests pass"

Frontend stories are NOT complete until visually verified in the browser.

Archiving Previous Runs

Before writing a new prd.json, check if there’s an existing one from a different feature:

1. Read the current prd.json if it exists
2. Check if branchName differs from the new feature’s branch name
3. If different AND progress.txt has content beyond the header:
   • Create archive folder: archive/YYYY-MM-DD-feature-name/
   • Copy current prd.json and progress.txt to archive
   • Reset progress.txt with fresh header

The ralph.sh script handles archiving automatically when you run it.

Conversion Checklist

Before saving prd.json, verify:

• Previous run archived (if prd.json exists with different branchName)
• Each story is completable in one iteration (small enough)
• Stories are ordered by dependency (schema → backend → UI)
• Every story has “Typecheck passes” as criterion
• UI stories have “Verify in browser using dev-browser skill” as criterion
• Acceptance criteria are verifiable (not vague)
• No story depends on a later story
• All stories have passes: false initially
• All stories have empty notes initially

Related

• progress.txt Format - Track implementation progress
• AGENTS.md Files - Knowledge persistence across iterations
• Ralph Skill - Convert PRDs to prd.json format