ralph-tasks

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 .plans/prd.json.

Output Format

Generate the PRD json based on the following json schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "minItems": 1,
  "description": "Product Requirements Document: an array of features to be implemented by an LLM agent.",
  "items": {
    "type": "object",
    "required": ["category", "title", "description", "passes", "acceptance"],
    "properties": {
      "id": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[a-z0-9-]+$",
        "description": "Unique identifier for cross-referencing (e.g., 'user-auth', 'api-rate-limiting'). Use lowercase with hyphens."
      },
      "category": {
        "type": "string",
        "minLength": 1,
        "description": "Feature category for grouping (e.g., 'Authentication', 'API', 'UI', 'Testing'). Helps locate related code."
      },
      "title": {
        "type": "string",
        "minLength": 1,
        "description": "Concise feature title (e.g., 'User Login', 'Rate Limiting Middleware'). Used in progress reports."
      },
      "description": {
        "type": "string",
        "minLength": 1,
        "description": "Detailed feature description explaining the expected behavior, user value, and any important context."
        "example": "User can log in with valid credentials"
      },
      "passes": {
        "type": "boolean",
        "description": "Completion status. Set to true only after implementation passes all acceptance criteria and tests."
      },
      "acceptance": {
        "type": "array",
        "minItems": 1,
        "description": "Acceptance criteria list. Each item should be independently verifiable. Write as assertions (e.g., 'Login form validates email format'). Describe creating tests or verifying in browser using dev-browser skill",
        "example": [
          "Login form validates email format",
          "Login form validates password length"
        ],
        "items": {
          "type": "string",
          "minLength": 1,
          "description": "A specific, testable criterion for feature completion"
        }
      },
      "priority": {
        "type": "string",
        "enum": ["critical", "high", "medium", "low"],
        "description": "Feature priority for ordering work. Defaults to 'medium' if not specified."
      },
      "dependencies": {
        "type": "array",
        "description": "Array of feature IDs that must pass before this feature can be started. Prevents working out of order.",
        "items": {
          "type": "string",
          "minLength": 1
        }
      },
      "technicalNotes": {
        "type": "string",
        "description": "Implementation hints: patterns to follow, libraries to use, constraints to respect (e.g., 'Use existing AuthService', 'Must support IE11')."
      },
      "testStrategy": {
        "type": "string",
        "description": "Testing guidance: test types needed (unit/integration/e2e), what to mock, edge cases to cover."
      },
      "suggestedFiles": {
        "type": "array",
        "description": "Paths to files likely needing changes or examination. Glob patterns allowed (e.g., 'src/auth/**/*.ts').",
        "items": {
          "type": "string",
          "minLength": 1
        }
      },
      "outOfScope": {
        "type": "array",
        "description": "Explicit exclusions to prevent over-engineering (e.g., 'No OAuth support yet', 'Skip mobile responsive').",
        "items": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "additionalProperties": false
  }
}

Rules

• Important: Acceptance criteria must be verifiable, not vague. "Works correctly" is bad. "Button shows confirmation dialog before deleting" is good.
• For any story with UI changes: Always include "Verify in browser using dev-browser skill" as acceptance criteria. This ensures visual verification of frontend work.
• For any story that includes domain logic: Always include "Verify with unit tests" as acceptance criteria.

Writing for Junior Developers

The PRD reader may be a junior developer or AI agent. Therefore:

• Be explicit and unambiguous
• Avoid jargon or explain it
• Provide enough detail to understand purpose and core logic
• Number requirements for easy reference
• Use concrete examples where helpful

Output

• Format: JSON (.json)
• Location: ./plans
• Filename: prd.md

Before writing prd.json, verify:

• Asked clarifying questions
• Incorporated user's answers
• PRD item is completable in one iteration (small enough)
• UI stories have "Verify in browser using dev-browser skill" as criterion
• Acceptance criteria are verifiable (not vague)
• Saved to ./plans/prd.json