prd-schema

prd.json schema reference from Ralph TUI. Use this when creating, editing, or reviewing .claude/prd/*.json files.

When to Use

Invoke /prd-schema before editing any prd.json file. Invoke /prd-schema validate <path> to check an existing file.

Conversion from Plans

prd.json files are typically created by /tasks-converter from architectural plans (.claude/plans/*-plan.md). The pipeline:

/plan-creator (or /bug-plan-creator, /code-quality-plan-creator)
    ↓ writes
.claude/plans/{slug}-{hash5}-plan.md
    ↓ consumed by
/tasks-converter <plan-path>
    ↓ writes
.claude/prd/<slug>.json
    ↓ executed by
/tasks-loop or /tasks-swarm or ralph-tui

How plan sections map to prd.json fields:

Plan Section	prd.json Field
## Summary	name, description
## Files	One user story per file (typically)
### Requirements	acceptanceCriteria[]
### Reference Implementation	description (full code copied verbatim)
### Migration Pattern	description (before/after code copied verbatim)
## Dependency Graph	dependsOn[] (file deps translated to story IDs)
## Exit Criteria	acceptanceCriteria[]
Plan path	metadata.planReference

Each story's description must be 100% self-contained — the executor agent receives only the story description, never the source plan. All code, requirements, and verification commands are copied verbatim from the plan into the story.

Schema

Root Object

{
  "name": "string (REQUIRED)",
  "description": "string (optional)",
  "branchName": "string (optional)",
  "userStories": ["array (REQUIRED, see below)"],
  "metadata": {
    "createdAt": "ISO 8601 string (optional)",
    "updatedAt": "ISO 8601 string (auto-set on write)",
    "version": "string (optional)",
    "sourcePrd": "string — path to source PRD markdown (optional)"
  }
}

project is accepted as an alias for name, but name is preferred.

User Story Object

{
  "id": "string (REQUIRED) — e.g. 'US-001'",
  "title": "string (REQUIRED)",
  "description": "string (optional)",
  "acceptanceCriteria": ["string[] (optional)"],
  "priority": "number (optional, default: 2) — 1=highest, 4=lowest",
  "passes": "boolean (REQUIRED) — false=incomplete, true=complete",
  "labels": ["string[] (optional)"],
  "dependsOn": ["string[] (optional) — IDs of blocking stories"],
  "notes": "string (optional)",
  "completionNotes": "string (optional, alias for notes)"
}

Required Fields (validation fails without these)

Scope	Field	Type
Root	name	string
Root	userStories	array (1+ elements)
Story	id	string
Story	title	string
Story	passes	boolean

Unsupported Fields (rejected by Ralph TUI)

Field	Why It's Wrong
prd	Don't wrap content in a prd key
tasks	Use userStories, not tasks
status	Use passes (boolean), not status (string)
subtasks	Flat list only, no nesting
estimated_hours	No time tracking
files	Not part of schema
assignee	Not part of schema
type	Not part of schema
epic	Not part of schema
parent	Not part of schema

Dependencies

dependsOn is an array of story IDs. A story is blocked until all its dependencies have passes: true.

{
  "id": "US-003",
  "title": "Integration tests",
  "dependsOn": ["US-001", "US-002"],
  "passes": false
}

• If a dependency ID doesn't exist in the file, the story is treated as ready.
• Circular dependencies are not checked — ensure a valid DAG.

Task Selection Order

Ralph TUI selects the next task by:

1. Filter to passes: false
2. Filter to stories with all dependsOn resolved (passes: true)
3. Sort by priority (lowest number first)
4. Return first match

Minimal Valid Example

{
  "name": "My Feature",
  "userStories": [
    {
      "id": "US-001",
      "title": "First task",
      "passes": false
    }
  ]
}

Complete Example

{
  "name": "User Authentication",
  "description": "Add user authentication to the application",
  "branchName": "feature/auth",
  "userStories": [
    {
      "id": "US-001",
      "title": "Create login page",
      "description": "Build login form with email and password fields.",
      "acceptanceCriteria": [
        "Form has email and password inputs",
        "Form validates required fields",
        "Submit button is disabled during submission"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "Implement authentication API",
      "description": "POST /api/auth/login endpoint that verifies credentials and returns JWT.",
      "acceptanceCriteria": [
        "POST /api/auth/login accepts email and password",
        "Returns JWT token on success",
        "Returns 401 on invalid credentials"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": []
    },
    {
      "id": "US-003",
      "title": "Connect login form to API",
      "description": "Wire up the login form to call the authentication API.",
      "acceptanceCriteria": [
        "Form submits to /api/auth/login",
        "Success stores token and redirects",
        "Error shows message to user"
      ],
      "priority": 2,
      "passes": false,
      "dependsOn": ["US-001", "US-002"]
    }
  ],
  "metadata": {
    "createdAt": "2024-01-15T10:00:00Z",
    "version": "1.0"
  }
}

Instructions

Parse $ARGUMENTS to determine mode.

If $ARGUMENTS starts with validate:

Extract the path from $ARGUMENTS (e.g., /prd-schema validate .claude/prd/auth.json).

Read the file and check for schema violations:

# Check for rejected top-level fields
jq 'keys[] | select(. == "prd" or . == "tasks")' <path>

# Check every story has required fields
jq '.userStories[] | select(.id == null or .title == null or .passes == null) | .id // "unnamed"' <path>

# Check for unsupported story fields
jq '.userStories[] | to_entries[] | select(.key | test("^(subtasks|estimated_hours|files|status|assignee|type|epic|parent)$")) | "\(.key) in story"' <path>

Report each violation with the fix from the schema above.

If $ARGUMENTS is empty:

Output the schema summary:

prd.json Schema (Ralph TUI)

Root: name (req), description, branchName, userStories (req), metadata
Story: id (req), title (req), passes (req), description, acceptanceCriteria, priority, labels, dependsOn, notes, completionNotes

Rejected fields: prd, tasks, status, subtasks, estimated_hours, files, assignee, type, epic, parent

Use "passes: false" (not "status: open"). Use "userStories" (not "tasks").