gantisstorm/essentials-claude-code/prd-schema

Name: prd-schema
Author: gantisstorm

Claude Code and agent skill by gantisstorm/essentials-claude-code

Trust tier 3

community

Source check pending

Checking that the SKILL.md file is still in the repository.

prd.json schema reference for Ralph TUI — validates structure, prevents unsupported fields

Install

npx vskill@latest install gantisstorm/essentials-claude-code/prd-schema

SKILL.md

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

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 name, but name is preferred.

User Story Object

json

{
  "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.

json

{
  "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:

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

Minimal Valid Example

json

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

Complete Example

json

{
  "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:

bash

# 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").

Security

Security scanPassed, 100 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingessentials/skills/prd-schema/SKILL.md

Popularity

Repository stars: 85
Repository forks: 8
7-day trend score: 22

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 19 Mar 2026, 7 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/gantisstorm/essentials-claude-code/prd-schema/badge)](https://verified-skill.com/skills/gantisstorm/essentials-claude-code/prd-schema)

Something wrong with this skill or its page? Tell us.

Install

SKILL.md

When to Use

Conversion from Plans

Schema

Root Object

User Story Object

Required Fields (validation fails without these)

Unsupported Fields (rejected by Ralph TUI)

Dependencies

Task Selection Order

Minimal Valid Example

Complete Example

Instructions

If $ARGUMENTS starts with validate:

If $ARGUMENTS is empty:

Security

Quality evaluation

Source

Popularity

Works with

If `$ARGUMENTS` starts with `validate`:

If `$ARGUMENTS` is empty: