prd

Original source / Raw SKILL.md

---
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.
author: Benjamin Jesuiter <[email protected]>
metadata:
  clawdbot:
    emoji: "📋"
    os: ["darwin", "linux"]
---

# 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

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

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

## Quick Reference

| Action | Command |
|--------|---------|
| Create PRD | Save to `agents/prd.json` |
| Check status | `cat prd.json | jq '.userStories[] | {id, passes}'` |
| View incomplete | `jq '.userStories[] | select(.passes == false)' prd.json` |

## 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


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "bjesuiter",
  "slug": "prd",
  "displayName": "Prd",
  "latest": {
    "version": "2.0.5",
    "publishedAt": 1768388387876,
    "commit": "https://github.com/clawdbot/skills/commit/f6874187b4a6ede3abb47cf1af64a5ff937944bc"
  },
  "history": [
    {
      "version": "2.0.4",
      "publishedAt": 1768135721147,
      "commit": "https://github.com/clawdbot/skills/commit/8c8143525d68dc962b5153bc405e8685b3b483f3"
    },
    {
      "version": "2.0.0",
      "publishedAt": 1768134224171,
      "commit": "https://github.com/clawdbot/skills/commit/d34ed8f485d2a9495f586322864ff9d436b9878d"
    }
  ]
}

```

### references/agent-usage.md

```markdown
# Agent Usage Patterns

This document describes how AI coding agents (Claude Code, OpenCode, etc.) can execute PRDs autonomously. **This skill only edits PRDs — agents use this reference to execute them.**

## Unattended Agentic Loop

### Claude Code
```bash
while :; do
  claude --print --dangerously-skip-permissions \
    "Read prd.json, find first story where passes=false, implement it, run checks, update passes=true if successful"
done
```

### OpenCode
```bash
opencode run "Load prd.json, implement next incomplete story, verify, mark complete"
```

### Key Files

| File | Purpose |
|------|---------|
| `prd.json` | Task list with completion status |
| `prompt.md` | Instructions for each iteration |
| `progress.txt` | Append-only learnings log |

## Human-in-the-Loop

### Manual Story-by-Story
```bash
claude "Implement US-001 from prd.json"
# Review, approve, continue to US-002
```

### Git Worktree Strategy
```bash
# Create worktree for feature
git worktree add ../myapp-feature ralph/feature-name

# Run agent in worktree
cd ../myapp-feature
claude "Implement prd.json stories"

# Review in main repo
cd ../myapp && git diff main..ralph/feature-name
```

## Agent Prompt Template

```markdown
# Agent Instructions

You are an autonomous coding agent.

## Your Task

1. Read `prd.json`
2. Read `progress.txt` (check Codebase Patterns first)
3. Checkout/create branch from PRD `branchName`
4. Pick highest priority story where `passes: false`
5. Implement that single story
6. Run quality checks (typecheck, lint, test)
7. If checks pass, commit: `feat: [Story ID] - [Story Title]`
8. Update prd.json: set `passes: true`
9. Append progress to `progress.txt`

## Quality Requirements

- ALL commits must pass typecheck
- Keep changes focused and minimal
- Follow existing code patterns

## Stop Condition

When ALL stories have `passes: true`, output:
<promise>COMPLETE</promise>
```

## Progress Tracking

Append to `progress.txt` after each iteration (never replace):

```markdown
## 2026-01-10 18:00 - US-001
- Implemented: Added priority column to tasks table
- Files changed: migrations/001_add_priority.sql, src/types.ts
- **Learnings:** Use `IF NOT EXISTS` for migrations
---
```

### Codebase Patterns (at top of progress.txt)

```markdown
## Codebase Patterns
- Use `sql<number>` template for aggregations
- Always use `IF NOT EXISTS` for migrations
- Export types from actions.ts for UI components
```

## Checklist Before Running

- [ ] Each story completable in one context window
- [ ] Stories ordered by dependency (schema → backend → UI)
- [ ] Every story has "Typecheck passes" criterion
- [ ] Acceptance criteria are verifiable (not vague)
- [ ] No story depends on a later story

## Tools & Resources

### Official Tools
- [Ralph by snarktank](https://github.com/snarktank/ralph) - Full Ralph implementation
- [Claude Code](https://github.com/anthropics/claude-code) - Anthropic's CLI agent
- [Amp Code](https://ampcode.com) - Another agent runner

### Guides
- [Tips for AI Coding with Ralph Wiggum](https://www.aihero.dev/tips-for-ai-coding-with-ralph-wiggum)

```

### references/output-patterns.md

```markdown
# Output Patterns and Templates

## prd.json Template

### Basic Structure
```json
{
  "project": "ProjectName",
  "branchName": "ralph/feature-slug",
  "description": "Brief feature description",
  "userStories": [
    {
      "id": "US-001",
      "title": "Clear action title",
      "description": "As a [user], I want [feature] so that [benefit].",
      "acceptanceCriteria": [
        "Specific, verifiable criterion 1",
        "Specific, verifiable criterion 2",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}
```

### Example: Database Field Addition
```json
{
  "project": "TaskApp",
  "branchName": "ralph/add-task-priority",
  "description": "Add priority levels to tasks",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add priority column to database",
      "description": "As a developer, I need to store task priority so it persists across sessions.",
      "acceptanceCriteria": [
        "Add priority column: 'high' | 'medium' | 'low' (default 'medium')",
        "Generate and run migration successfully",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}
```

### Example: UI Component Addition
```json
{
  "id": "US-002",
  "title": "Display priority indicator on task cards",
  "description": "As a user, I want to see task priority at a glance.",
  "acceptanceCriteria": [
    "Each task card shows colored priority badge",
    "Badge colors: red=high, yellow=medium, gray=low",
    "Priority visible without hovering",
    "Typecheck passes",
    "Verify in browser using dev-browser skill"
  ],
  "priority": 2,
  "passes": false,
  "notes": ""
}
```

## Markdown PRD Template

```markdown
# PRD: [Feature Name]

## Introduction
[Brief description of the feature]

## Goals
- [Goal 1]
- [Goal 2]
- [Goal 3]

## User Stories

### US-001: [Story Title]
**Description:** As a [user], I want [feature] so that [benefit].

**Acceptance Criteria:**
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

### US-002: [Story Title]
...

## Non-Goals
- [What this PRD does NOT cover]
- [What is explicitly out of scope]

## Technical Considerations
- [Technical constraints or patterns to follow]
- [Dependencies or prerequisites]
```

## Agent Prompt Template

```markdown
# Agent Instructions

You are an autonomous coding agent.

## Your Task

1. Read `prd.json`
2. Read `progress.txt` (check Codebase Patterns first)
3. Checkout/create branch from PRD `branchName`
4. Pick highest priority story where `passes: false`
5. Implement that single story
6. Run quality checks (typecheck, lint, test)
7. If checks pass, commit: `feat: [Story ID] - [Story Title]`
8. Update prd.json: set `passes: true`
9. Append progress to `progress.txt`

## Quality Requirements

- ALL commits must pass typecheck
- Keep changes focused and minimal
- Follow existing code patterns

## Stop Condition

When ALL stories have `passes: true`, output:
<promise>COMPLETE</promise>
```

## Progress.txt Template

```markdown
## Codebase Patterns
- [Pattern 1: reusable insight from earlier iterations]
- [Pattern 2]
- [Pattern 3]

---

## [YYYY-MM-DD HH:MM] - [Story ID]
- **Implemented:** [What was done]
- **Files changed:** [List files]
- **Learnings:**
  - [Insight 1]
  - [Insight 2]
---
```

## Acceptance Criteria Patterns

### Database Changes
```
- Add [column/table] with type [type] and default [value]
- Generate and run migration successfully
- Typecheck passes
```

### API Endpoints
```
- Endpoint [method] [path] returns [expected response]
- Returns [status code] for valid requests
- Returns [status code] for invalid requests
- Typecheck passes
```

### UI Components
```
- [Component] is rendered on [page/section]
- Shows [expected content/behavior]
- [Interactive element] works as expected
- Typecheck passes
- Verify in browser using dev-browser skill
```

### Bug Fixes
```
- [Expected behavior] now occurs when [trigger]
- Regression: [Related functionality] still works
- Typecheck passes
```

```

### references/workflows.md

```markdown
# Workflow Patterns for PRD Skills

## Sequential Workflow Pattern

When a skill involves multi-step processes with dependencies, use sequential workflows.

### Structure
```
## Workflow Decision Tree
## Step 1: [First Step]
## Step 2: [Second Step]
## ...
```

### Example: PRD Creation Workflow
```
## Step 1: Ask Clarifying Questions
Gather context before writing...

## Step 2: Generate Markdown PRD
Save to `tasks/prd-[feature-name].md`...

## Step 3: Convert to prd.json
...

## Step 4: Run Agentic Loop
...
```

## Conditional Logic Pattern

Use branching logic when different paths depend on user choices.

### Structure
```markdown
## Decision: [What is the user trying to do?]

- **Option A**: [Description] → See [Section A]
- **Option B**: [Description] → See [Section B]
```

### Example
```markdown
## Decision: What type of PRD do you need?

- **Quick PRD**: Single file with basic structure → See [Quick Template]
- **Detailed PRD**: Multi-section with full specs → See [Detailed Template]
- **AI-Ready PRD**: Optimized for autonomous agents → See [AI-Ready Format]
```

## Iteration Pattern

For processes that repeat until a condition is met.

### Structure
```markdown
## Repeat Until: [Stop Condition]

1. [Step 1]
2. [Step 2]
...

**Stop when:** [Condition description]
```

### Example (Agentic Loop)
```markdown
## Repeat Until: All stories have passes=true

1. Read prd.json, find first incomplete story
2. Implement the story
3. Run checks (typecheck, tests)
4. If checks pass, mark passes=true
5. Append to progress.txt

**Stop when:** `jq '.userStories[].passes' | grep -q "false"` is false
```

## Progressive Disclosure Pattern

Show overview first, link to details.

```markdown
## Creating Documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md) for details.

## Editing Documents

For simple edits, modify XML directly.
- **Tracked changes**: See [REDLINING.md](REDLINING.md)
- **OOXML details**: See [OOXML.md](OOXML.md)
```

## Validation Pattern

Include validation steps throughout.

```markdown
## Step 1: Create Schema

1. Define table structure
2. **Validate**: Run migration, verify no errors

## Step 2: Add Backend Logic

1. Create server action
2. **Validate**: Typecheck passes
3. **Validate**: Integration test passes
```

```