Ralph

Ralph PRD Converter

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

The Job

Convert tasks/<short-desc>/prd.md to tasks/<short-desc>/prd.json in the same folder.

Required arguments:

• Folder path (positional, e.g. tasks/install-prereq-detection/). The folder name is <short-desc>.
• --issue <N> — GitHub issue number this PRD addresses. Required. The branch name embeds this.
• --prefix <type> — branch prefix per .claude/rules/git.md. One of feat | bug | task | audit | skill | agent. Default: feat.

branchName in the produced JSON follows .claude/rules/git.md:

<prefix>/<issue#>-<short-desc>

Example: folder tasks/install-prereq-detection/ + --issue 175 + --prefix task → branchName: "task/175-install-prereq-detection".

If --issue is missing, hard-fail with: "issue number required — open the GitHub issue first per .claude/rules/git.md and re-run with --issue <N>." This matches the project's "issue first, then branch" workflow.

The folder name IS the feature name — do not re-derive it from branchName or anywhere else.

Output Format

{
    "schemaVersion": 1,
    "project": "[Project Name]",
    "branchName": "<prefix>/<issue#>-<short-desc>",
    "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",
                "Typecheck passes"
            ],
            "priority": 1,
            "passes": false,
            "notes": ""
        }
    ]
}

Story Size: The Number One Rule

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

Ralph spawns a fresh Amp 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:

• 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)
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 does not exist yet)
2. Schema change

Acceptance Criteria: Must Be Verifiable

Each criterion must be something Ralph can CHECK, not something 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"

Always include as final criterion:

"Typecheck passes"

For stories with testable logic, also include:

"Tests pass"

For stories that change UI, also include:

"Verify in browser using agent-browser skill"

Frontend stories are NOT complete until visually verified. Ralph will use the agent-browser skill to navigate to the page, interact with the UI, and confirm changes work.

Conversion Rules

1. Each user story becomes one JSON entry
2. IDs: Sequential (US-001, US-002, etc.)
3. Priority: Based on dependency order, then document order
4. All stories: passes: false and empty notes
5. branchName: Derive from feature name, kebab-case, prefixed with ralph/
6. Always add: "Typecheck passes" to every story's acceptance criteria

Splitting Large PRDs

If a PRD has big features, split them:

Original:

"Add user notification system"

Split into:

1. US-001: Add notifications table to database
2. US-002: Create notification service for sending notifications
3. US-003: Add notification bell icon to header
4. US-004: Create notification dropdown panel
5. US-005: Add mark-as-read functionality
6. US-006: Add notification preferences page

Each is one focused change that can be completed and verified independently.

Example

Input PRD:

# Task Status Feature

Add ability to mark tasks with different statuses.

## Requirements

- Toggle between pending/in-progress/done on task list
- Filter list by status
- Show status badge on each task
- Persist status in database

Output prd.json:

{
    "project": "TaskApp",
    "branchName": "ralph/task-status",
    "description": "Task Status Feature - Track task progress with status indicators",
    "userStories": [
        {
            "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": ""
        },
        {
            "id": "US-002",
            "title": "Display status badge on task cards",
            "description": "As a user, I want to see task status at a glance.",
            "acceptanceCriteria": [
                "Each task card shows colored status badge",
                "Badge colors: gray=pending, blue=in_progress, green=done",
                "Typecheck passes",
                "Verify in browser using agent-browser skill"
            ],
            "priority": 2,
            "passes": false,
            "notes": ""
        },
        {
            "id": "US-003",
            "title": "Add status toggle to task list rows",
            "description": "As a user, I want to change task status directly from the list.",
            "acceptanceCriteria": [
                "Each row has status dropdown or toggle",
                "Changing status saves immediately",
                "UI updates without page refresh",
                "Typecheck passes",
                "Verify in browser using agent-browser skill"
            ],
            "priority": 3,
            "passes": false,
            "notes": ""
        },
        {
            "id": "US-004",
            "title": "Filter tasks by status",
            "description": "As a user, I want to filter the list to see only certain statuses.",
            "acceptanceCriteria": [
                "Filter dropdown: All | Pending | In Progress | Done",
                "Filter persists in URL params",
                "Typecheck passes",
                "Verify in browser using agent-browser skill"
            ],
            "priority": 4,
            "passes": false,
            "notes": ""
        }
    ]
}

Archiving Previous Runs

Archive fires only when all of the following hold for tasks/<short-desc>/:

1. prd.json already exists (re-running ralph on a feature that ran before).
2. progress.txt has content beyond the header (the runner has written entries — there is execution history worth preserving).

If both hold:

1. Read the current prd.json and progress.txt.

2. Create tasks/<short-desc>/archive/<ISO-timestamp>/ where the timestamp is YYYY-MM-DDTHH-MM-SS (UTC; second-resolution avoids same-day collisions).

3. Copy prd.json and progress.txt into that directory.

4. Reset progress.txt to its header only:

   # progress
   

5. Overwrite prd.json with the new conversion.

Different branchNames do not trigger archiving. In the per-folder layout, a different feature lives in a different folder, so there is no shared slot to protect.

Checklist Before Saving

Before writing prd.json, verify:

• Operating on tasks/<short-desc>/ — folder name is the feature name
• Archive on rerun: if prd.json exists AND progress.txt has run history, archived to tasks/<short-desc>/archive/<ISO-timestamp>/ before overwriting
• Each story is completable in one iteration (small enough)
• Stories are ordered by dependency (schema to backend to UI)
• Every story has "Typecheck passes" as criterion
• UI stories have "Verify in browser using agent-browser skill" as criterion
• Acceptance criteria are verifiable (not vague)
• No story depends on a later story