prd-schema

prd.json schema reference from [Ralph TUI](https://github.com/subsy/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

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