48Nauts-Operator avatar

ralph

Convert PRDs to prd.json format for the Ralph autonomous agent system. Use when you have an existing

提供方 48Nauts-Operator|开源

Ralph PRD Converter

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

The Job

Take a PRD (markdown file or text) and convert it to scripts/ralph/prd.json.

Output Format

{
  "project": "ProjectName",
  "branchName": "ralph/[feature-name-kebab-case]",
  "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",
        "npm run typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Story Size: The #1 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. 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 + 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 can't describe the change in 2-3 sentences, it's 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 doesn't 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 investorType column to investor table with default 'cold'"
  • "Filter dropdown has options: All, Cold, Friend"
  • "Clicking toggle shows confirmation dialog"
  • "npm run typecheck passes"
  • "npm test passes"

Bad criteria (vague):

  • "Works correctly"
  • "User can do X easily"
  • "Good UX"
  • "Handles edge cases"

Always include as final criterion:

"npm run typecheck passes"

For stories with testable logic:

"npm test passes"

For stories that change UI:

"Verify in browser using dev-browser skill"

Conversion Rules

  1. Each user story -> 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: "npm run typecheck passes" to every story's acceptance criteria

Output Location

Write to: scripts/ralph/prd.json

Checklist Before Saving

Before writing prd.json, verify:

  • Each story is completable in one iteration (small enough)
  • Stories are ordered by dependency (schema -> backend -> UI)
  • Every story has "npm run 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
下载 Skill