ralph

Ralph PRD Converter

Convert existing PRDs to the prd.json format for autonomous execution by the Ralph loop system.

Setup

Before converting a PRD, ensure the project has the Ralph directory structure. If it doesn't exist, create it:

mkdir -p ralph

Also create an empty progress file if it doesn't exist:

touch ralph/progress.txt

The Job

1. Read the PRD from tasks/prd-*.md (or specified path)
2. Parse user stories and requirements
3. Convert to prd.json format
4. Create the Ralph directory structure if needed
5. Save to ralph/prd.json
6. Initialize ralph/progress.txt if empty

Output Format

{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name]",
  "description": "[Feature description from PRD overview]",
  "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": ""
    }
  ]
}

Critical Rules

Story Size

Each story must be completable in ONE iteration (one context window). If a story from the PRD is too large, split it into smaller stories.

Story Ordering

Set priorities to ensure dependencies come first:

1. Schema/database changes (priority: 1)
2. Server actions / backend logic (priority: 2)
3. Utility functions / helpers (priority: 3)
4. UI components (priority: 4)
5. Dashboard/summary views (priority: 5)
6. Tests and documentation (priority: 6)

Acceptance Criteria

Must be verifiable, not vague.

Good:

• "Add status column to users table with default 'pending'"
• "API returns 200 with user object on success"
• "Form displays validation error when email is invalid"
• "Typecheck passes"

Bad:

• "Works correctly"
• "Is user friendly"
• "Handles errors properly"

Always include at the end of each story:

• "Typecheck passes"

For UI stories, also include:

• "Verify changes work in browser"

Initial State

All stories start with:

• passes: false
• notes: ""

Output Steps

1. Create ralph/ directory if it doesn't exist
2. Save ralph/prd.json with the converted PRD
3. Create ralph/progress.txt if it doesn't exist
4. Confirm all files were created and provide the paths

Branch Naming

Generate branch name from the feature:

• "User Profile Settings" -> ralph/user-profile-settings
• "Payment Integration" -> ralph/payment-integration

Use lowercase, hyphen-separated format.