ralph

Original：🇺🇸 English

Translated

3 scripts

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.

3installs

Sourceralphcrisostomo/nuxt-development-skills

Added on2026-03-06

NPX Install

npx skill4agent add ralphcrisostomo/nuxt-development-skills ralph

SKILL.md Content

View Translation Comparison →

Ralph PRD Converter

Converts existing PRDs to

prd.json

for Ralph's autonomous execution loop.

The Job

Run Pre-flight Setup, then convert a PRD (markdown or text) into

scripts/ralph/prd.json

Pre-flight Setup

Project name — read
```
package.json
```
```
name
```
field; fall back to directory basename.
Copy runtime files — if missing in target project, copy from this skill's
```
ralph/
```
subdirectory to
```
scripts/ralph/
```
:
- ```
ralph.sh
```
  ,
```
ralph-tree.sh
```
  →
```
chmod +x
```
- ```
CLAUDE.md
```
- ```
ralph-audit.ts
```
Set NTFY_TOPIC — in
```
scripts/ralph/ralph.sh
```
, replace
```
<project-name>
```
placeholder with actual project name. Skip if already customized.

Add package.json scripts — if

package.json

exists, add missing entries:

"ralph-tree": "bash scripts/ralph/ralph-tree.sh"

"ralph-audit": "bun scripts/ralph/ralph-audit.ts"

Verify curl — required by ralph.sh for ntfy.sh notifications.
Confirm setup — print summary: file status, NTFY_TOPIC, curl availability.

Output Format

json

{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": ["Criterion 1", "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 instance per iteration with no memory of previous work.

Right-sized: add a DB column, add a UI component, update a server action, add a filter. Too big (split): "build the dashboard", "add auth", "refactor the API".

Rule of thumb: if you can't describe the change in 2-3 sentences, split it.

Story Ordering

Dependencies first: schema/migrations → backend logic → UI components → aggregation views.

Acceptance Criteria

Must be verifiable — something Ralph can CHECK.

Good: "Add

status

column with default 'pending'", "Filter has options: All, Active, Done", "Typecheck passes" Bad: "Works correctly", "Good UX", "Handles edge cases"

Always include

"Typecheck passes"

as final criterion. Add

"Tests pass"

for testable logic. Add

"Verify in browser using dev-browser skill"

for UI changes.

Conversion Rules

Each user story → one JSON entry
IDs: sequential
```
US-001
```
,
```
US-002
```
, ...
Priority: dependency order, then document order
All stories:
```
passes: false
```
, empty
```
notes
```
branchName: kebab-case from feature name, prefixed
```
ralph/
```
Every story gets
```
"Typecheck passes"
```
criterion

Splitting Large PRDs

Break big features into focused, independent stories. Example: "Add notification system" becomes: 1) notifications table, 2) notification service, 3) bell icon, 4) dropdown panel, 5) mark-as-read, 6) preferences page.

See

references/example.md

for a full input/output conversion example.

Archiving Previous Runs

Before writing new

prd.json

, check for an existing one with a different

branchName

. If different and

progress.txt

has content beyond the header: archive to

archive/YYYY-MM-DD-feature-name/

, then reset

progress.txt

Checklist

Pre-flight complete (runtime files copied, NTFY_TOPIC set, package.json scripts added)
Previous run archived if needed
Each story fits one iteration
Dependency order respected
Every story has "Typecheck passes"
UI stories have "Verify in browser using dev-browser skill"
Criteria are verifiable, not vague
No story depends on a later story