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."
---

# 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

```json
{
    "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:**

```markdown
# 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:**

```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 `branchName`s 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