Converting PRDs to JSON

Use the Ralph skill to convert markdown PRDs into prd.json format for autonomous execution

The Ralph skill converts your markdown PRD into the structured prd.json format that Ralph uses for autonomous execution.

Using the Ralph Skill

Once you have a PRD in tasks/prd-[feature-name].md, convert it to JSON:

Amp

Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json

The skill automatically triggers when you use phrases like:

• “convert this prd”
• “turn this into ralph format”
• “create prd.json from this”
• “ralph json”

The Conversion Process

1. Skill Reads Your PRD

   The Ralph skill analyzes your markdown PRD to extract user stories, acceptance criteria, and project metadata.

2. Stories Are Sized and Ordered

   Each user story is validated to ensure it’s:

   • Small enough to complete in one Ralph iteration (one context window)
   • Ordered by dependencies (schema → backend → UI)
   • Verifiable with concrete acceptance criteria

   Large stories are automatically split into smaller chunks.

3. JSON File Generated

   The skill creates prd.json with all stories marked as passes: false and ready for execution.

4. Previous Runs Archived (If Needed)

   If a prd.json exists from a different feature (different branchName), it’s automatically archived to archive/YYYY-MM-DD-feature-name/.

JSON Format Structure

The generated prd.json follows this structure:

{
  "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": ""
    }
  ]
}

Story Sizing: The Number One Rule

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 and produces broken code.

Right-Sized Stories

Good Story Examples

• 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

Stories That Are Too Big

Split These Stories

• “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: Dependencies First

Stories execute in priority order. The Ralph skill ensures earlier stories don’t 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 Validation

The Ralph skill automatically adds “Typecheck passes” to every story’s acceptance criteria.

For UI stories, it also adds:

"Verify in browser using dev-browser skill"

Verifiable vs. Vague Criteria

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”

Example Conversion

Here’s how a markdown PRD section converts to JSON:

Input (Markdown PRD):

### US-001: Add status field to tasks table
**Description:** As a developer, I need to store task status in the database.

**Acceptance Criteria:**
- [ ] Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')
- [ ] Generate and run migration successfully

Output (prd.json):

{
  "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,
  "passes": false,
  "notes": ""
}

Notice “Typecheck passes” was automatically added.

Automatic Archiving

Before creating a new prd.json, the skill checks if you’re starting a different feature:

1. Reads existing prd.json (if it exists)
2. Compares branchName values
3. If different AND progress.txt has content:
   • Creates archive/YYYY-MM-DD-feature-name/
   • Copies current prd.json and progress.txt to archive
   • Resets progress.txt with fresh header

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

Validation Checklist

Before the skill saves prd.json, it verifies:

• ✓ 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

Output Location

The prd.json file is created in:

scripts/ralph/prd.json

Or wherever you copied the Ralph files to your project.

Next Steps

After converting your PRD to JSON:

1. Review the generated prd.json
2. Make any manual adjustments if needed
3. Run Ralph to start autonomous execution

Ready to Run

Your prd.json is now ready for Ralph to execute autonomously!