ralph

name: ralph description: "Convert PRDs to prd.json format for the Ralph autonomous agent system. Use when you have an existing PRD and need to convert it to Ralph's JSON format. Triggers on: convert this prd, turn this into ralph format, create prd.json from this, ralph json." user-invocable: true

Ralph PRD Converter

Converts existing PRDs to the scripts/ralph/prd.json format that Ralph uses for autonomous execution.

The Job

Take a PRD (markdown file or text) and convert it to scripts/ralph/prd.json.

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",
        "npm run build passes",
        "npm run lint passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Story Size: The Number One Rule

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

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 in supabase/migrations/)
2. Supabase types update (src/integrations/supabase/types.ts)
3. Server actions / backend logic / Edge Functions
4. React hooks and TanStack Query hooks
5. UI components that use the backend
6. Dashboard/summary views that aggregate data

Acceptance Criteria: Must Be Verifiable

Good criteria (verifiable):

• "Add status column to tasks table with default 'pending'"
• "Filter dropdown has options: All, Active, Completed"
• "npm run build passes"
• "npm run lint passes"

Bad criteria (vague):

• "Works correctly"
• "User can do X easily"
• "Handles edge cases"

Always include as final criteria for every story:

"npm run build passes",
"npm run lint passes"

For stories that change UI, also include:

"Verify in browser using dev-browser skill"

Archiving Previous Runs

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

1. Read the current scripts/ralph/prd.json if it exists
2. Check if branchName differs from the new feature's branch name
3. If different, archive to scripts/ralph/archive/YYYY-MM-DD-feature-name/

The ralph.sh script handles archiving automatically on the next run.

Checklist Before Saving

• Each story is completable in one iteration (small enough)
• Stories are ordered by dependency (schema → types → backend → UI)
• Every story has "npm run build passes" and "npm run lint passes" criteria
• UI stories have "Verify in browser using dev-browser skill" criteria
• Acceptance criteria are verifiable (not vague)
• No story depends on a later story
• Saved to scripts/ralph/prd.json