ralphi-convert

name	ralphi-convert
description	Converts PRD markdown files to .ralphi/prd.json format for the Ralph autonomous agent loop. Use when asked to convert a PRD, create .ralphi/prd.json, or turn a PRD into Ralph format.

Ralph PRD Converter

Convert a PRD markdown file into .ralphi/prd.json format for the Ralph autonomous agent loop.

Workflow

1. Read the PRD markdown file provided by the user.
2. Run a short planning pass before conversion:
   • Split oversized stories so each can be completed in one iteration
   • Order by dependencies (schema/backend before UI)
   • Add dependsOn links for blocked stories
3. If .ralphi/prd.json already exists with a different branchName, archive it first to .ralphi/archive/YYYY-MM-DD-feature-name/ before overwriting.
4. Convert the PRD content into structured JSON following the output format below.
5. Write the result to .ralphi/prd.json.

Output Format

{
  "project": "<project name>",
  "branchName": "ralph/<feature-name-kebab-case>",
  "description": "<brief project description>",
  "userStories": [
    {
      "id": "US-001",
      "title": "<story title>",
      "description": "<story description>",
      "acceptanceCriteria": ["<criterion 1>", "<criterion 2>"],
      "priority": 1,
      "status": "open",
      "dependsOn": [],
      "notes": ""
    }
  ]
}

Story Sizing — The Number One Rule

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

Right-sized examples:

• Add a database column
• Add a UI component
• Update a server action

Too big — split these:

• Build entire dashboard
• Add authentication

Story Ordering — Dependencies First

Order stories by dependency chain:

1. Schema / database changes
2. Server actions / backend logic
3. UI components
4. Dashboard / summary views

Acceptance Criteria — Must Be Verifiable

• Good: "Add status column with default 'pending'"
• Bad: "Works correctly"
• Always include quality checks (lint, type-check, tests pass) as final criteria in each story.

Conversion Rules

1. Each user story in the PRD becomes one JSON entry.
2. IDs are sequential: US-001, US-002, etc.
3. Priority is based on dependency order (1 = first).
4. All stories start with status: "open", dependsOn: [], and empty notes.
5. Add dependsOn IDs when a story is blocked by another story (dependency chain should still match priority order).
6. branchName is kebab-case, prefixed with ralph/.