prd

name	prd
description	Create and manage Product Requirements Documents (PRDs). Use when: (1) Creating structured task lists with user stories, (2) Specifying features with acceptance criteria, (3) Planning feature implementation for AI agents or human developers.

PRD Skill

Create and manage Product Requirements Documents (PRDs) for feature planning.

What is a PRD?

A PRD (Product Requirements Document) is a structured specification that:

1. Breaks a feature into small, independent user stories
2. Defines verifiable acceptance criteria for each story
3. Orders tasks by dependency (schema → backend → UI)

Quick Start

1. Create/edit agents/prd.json in the project
2. Define user stories with acceptance criteria
3. Track progress by updating passes: false → true

prd.json Format

{
  "project": "MyApp",
  "branchName": "ralph/feature-name",
  "description": "Short description of the feature",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add priority field to database",
      "description": "As a developer, I need to store task priority.",
      "acceptanceCriteria": [
        "Add priority column: 'high' | 'medium' | 'low'",
        "Generate and run migration",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Field Descriptions

Field	Description
project	Project name for context
branchName	Git branch for this feature (prefix with ralph/)
description	One-line feature summary
userStories	List of stories to complete
userStories[].id	Unique identifier (US-001, US-002)
userStories[].title	Short descriptive title
userStories[].description	"As a [user], I want [feature] so that [benefit]"
userStories[].acceptanceCriteria	Verifiable checklist items
userStories[].priority	Execution order (1 = first)
userStories[].passes	Completion status (false → true when done)
userStories[].notes	Runtime notes added by agent

Story Sizing

Each story should be completable in one context window.

✅ Right-sized:

• Add a database column and migration
• Add a UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list

❌ Too large (split these):

• "Build the entire dashboard" → Split into: schema, queries, UI, filters
• "Add authentication" → Split into: schema, middleware, login UI, session

Story Ordering

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

Acceptance Criteria

Must be verifiable, not vague.

✅ Good:

• "Add status column to tasks table with default 'pending'"
• "Filter dropdown has options: All, Active, Completed"
• "Typecheck passes"

❌ Bad:

• "Works correctly"
• "User can do X easily"

Always include: "Typecheck passes"

Progress Tracking

Update passes: true when a story is complete. Use notes field for runtime observations:

"notes": "Used IF NOT EXISTS for migrations"

Quick Reference

Action	Command
Create PRD	Save to agents/prd.json
Check status	`cat prd.json
View incomplete	`jq '.userStories[]

Resources

See references/ for detailed documentation:

• agent-usage.md - How AI agents execute PRDs (Claude Code, OpenCode, etc.)
• workflows.md - Sequential workflow patterns
• output-patterns.md - Templates and examples