/prd

name: prd description: Use when planning a feature, starting a new project, or asked to create a PRD. Generates JSON-based PRD for Ralph. Adding stories uses update.json pattern. Covers PRD, create PRD, plan feature, Ralph stories. NOT for: running Ralph (user runs externally).

Create PRDs for autonomous AI implementation via Ralph loop.

The Job

1. Ask 3-5 clarifying questions (use AskUserQuestion tool)
2. Find git root: git rev-parse --show-toplevel
3. Discover relevant skills for this project (see below)
4. Create JSON output:
   • prd-json/index.json - Story order (stats computed automatically)
   • prd-json/stories/{US-XXX}.json - One file per story
5. Create prd-json/AGENTS.md with skills section
6. Create progress.txt at git root
7. STOP and say: "PRD ready. Run Ralph to execute."

🛑 DO NOT IMPLEMENT - Ralph handles that externally.

Skill Discovery (CRITICAL for Ralph)

Before creating stories, determine which skills are relevant for THIS project:

Step 1: Check Project Context

# What's in this project?
[ -f "convex.json" ] && echo "HAS_CONVEX=true"
[ -f ".linear" ] || grep -q "linear" package.json 2>/dev/null && echo "HAS_LINEAR=true"
[ -d "src/components" ] || [ -d "app" ] && echo "HAS_UI=true"
[ -f "playwright.config.ts" ] && echo "HAS_PLAYWRIGHT=true"

Step 2: Match Skills to Project

UNIVERSAL (always include):

PROJECT-SPECIFIC (include if detected):

DO NOT INCLUDE (meta skills, not for Ralph):

• /prd, /skills, /writing-skills, /ralph-install, /example-*

Step 3: List Available Skills (Reference)

# See all installed skills
ls -1 ~/.claude/commands/*/SKILL.md 2>/dev/null | while read f; do
  skill=$(dirname "$f" | xargs basename)
  desc=$(awk '/^description:/{gsub(/^description: *"?/, ""); gsub(/"$/, ""); print}' "$f")
  echo "/$skill: $desc"
done

Step 4: Include ONLY Relevant Skills in AGENTS.md

Don't dump all skills - only include ones this project will actually use. Ralph should see a focused list, not 20+ skills.

Story Prefix = Model Selection (CRITICAL)

Ralph routes stories to AI models based on the prefix. Wrong prefix = wrong model = failed story.

Decision rule: If any criterion says "approach chosen", "design decision", or requires choosing between strategies — use MP-, not US-. Sonnet struggles with open-ended design. When in doubt, use MP-.

Config: ~/.config/golems/config.json → models object. Default fallback: opus.

Story Rules

Sizing (THE NUMBER ONE RULE)

Each story must complete in ONE context window (~10 min of AI work).

Right-sized: Add one component, update one action, fix one bug Too big (split): "Build dashboard" → Schema + Queries + UI + Filters

Ordering (Dependencies First)

1. Schema/database
2. Server actions
3. UI components
4. Verification stories (V-XXX)

Acceptance Criteria

• Must be verifiable (not vague)
• Include "Typecheck passes"
• Include "Verify in browser" for UI stories

⚠️ MANDATORY: Last two criteria of EVERY story (in this exact order):

1. "Run CodeRabbit review - must pass (or create BUG if unfixable)"
2. "Commit: {type}: {STORY-ID} {description}"

CodeRabbit ALWAYS comes BEFORE commit. No exceptions.

TDD / Test Enforcement (CRITICAL)

When to add test criteria:

• New functions/helpers: "Add unit test for [function] in tests/"
• Bug fixes: "Add regression test to prevent reintroduction"
• Core logic changes: "Verify all existing tests pass (X/X)"
• Refactors that touch tested code: "Run test suite - must pass with same count"

Why this matters: If a function has tests, and a future story accidentally deletes that function, the tests will fail and block the commit. Tests are your safety net against regressions.

Example criteria:

"Add unit test for _ralph_new_helper_function"
"Run ./tests/test-ralph.zsh - must pass (49/49)"
"Add regression test: verify X doesn't break when Y"

Commit Convention

Every story ends with a commit criterion. Match type to story:

Last two criteria (always):

"Run CodeRabbit review - must pass (or create BUG if unfixable)"
"Commit: {type}: {STORY-ID} {description}"

Examples:

• "Run CodeRabbit review - must pass (or create BUG if unfixable)"
• "Commit: feat: US-034 add user profile page"
• "Commit: fix: BUG-012 handle null response from API"
• "Commit: test: V-034 verify profile page renders correctly"
• "Commit: refactor: MP-002 migrate to modular contexts"

Conditional Rules

For RTL projects (Hebrew/Arabic): Include RTL checklist in stories: flex order reversal, text-right/items-end, RTL propagation in nested flex containers.

For modals/dynamic states: Each dynamic state = separate story. Don't bundle modal states into one story.

⚠️ ADDING TO EXISTING PRD (CRITICAL)

NEVER edit index.json directly when adding stories to an existing PRD!

Use prd-json/update.json instead. Ralph auto-merges it on next run.

To add new stories:

1. Create story files in prd-json/stories/ (e.g., US-034.json)
2. Create prd-json/update.json:

{
  "storyOrder": ["...existing IDs...", "US-034", "US-035"],
  "pending": ["...existing pending...", "US-034", "US-035"]
}

Note: Do NOT include stats - they are computed automatically from arrays. 3. Ralph merges update.json → index.json automatically, then deletes update.json

Why update.json?

• Prevents merge conflicts
• Clear audit trail
• Multiple agents can queue changes safely

JSON Templates

index.json

{
  "$schema": "https://ralph.dev/schemas/prd-index.schema.json",
  "generatedAt": "2026-01-19T12:00:00Z",
  "nextStory": "US-001",
  "storyOrder": ["US-001", "US-002", "V-001", "V-002"],
  "pending": ["US-001", "US-002", "V-001", "V-002"],
  "blocked": []
}

Note: Do NOT include stats - the UI computes them from array lengths.

Story JSON (prd-json/stories/US-XXX.json)

{
  "id": "US-001",
  "title": "[Story Title]",
  "description": "[What and why]",
  "acceptanceCriteria": [
    {"text": "[Specific criterion]", "checked": false},
    {"text": "Typecheck passes", "checked": false},
    {"text": "Verify in browser", "checked": false},
    {"text": "Run CodeRabbit review - must pass (or create BUG if unfixable)", "checked": false},
    {"text": "Commit: feat: US-001 [description]", "checked": false}
  ],
  "passes": false,
  "blockedBy": null
}

Output

Create at repository root:

• prd-json/index.json
• prd-json/stories/*.json
• prd-json/AGENTS.md - Instructions for AI agents (see template below)
• progress.txt

AGENTS.md Template

IMPORTANT: Run skill discovery first and include ACTUAL descriptions in AGENTS.md:

# Generate skills table for AGENTS.md
echo "| Skill | When to Use |"
echo "|-------|-------------|"
ls -1 ~/.claude/commands/golem-powers/*/SKILL.md 2>/dev/null | while read f; do
  skill=$(dirname "$f" | xargs basename)
  desc=$(awk '/^description:/{gsub(/^description: *"?/, ""); gsub(/"$/, ""); print}' "$f")
  echo "| \`/$skill\` | $desc |"
done
 
# Get project contexts from registry
project_key="$(basename $(pwd))"  # or the registered project name
jq -r --arg p "$project_key" '.projects[$p].contexts // [] | .[]' ~/.config/golems/registry.json 2>/dev/null

# AI Agent Instructions for PRD
 
## 🚀 Available Skills
 
**Invoke skills via `/skill-name` - read the description to know WHEN to use each:**
 
<!-- PASTE OUTPUT FROM SKILL DISCOVERY HERE -->
| Skill | When to Use |
|-------|-------------|
| `/ralph-commit` | Atomic commit + criterion check for Ralph stories. Use for "Commit:" criteria. |
| `/coderabbit` | Runs AI code reviews. Use when reviewing changes, preparing PRs, or checking code quality. |
| `/prd-manager` | Manage PRD stories - add, update, bulk operations. |
| `/catchup` | Recover context by reading all files changed since diverging from main. |
 
## 📦 Project Contexts
 
**Ralph loads these contexts automatically from the registry:**
 
<!-- List contexts from: jq '.projects["<project>"].contexts[]' ~/.config/golems/registry.json -->
- `base` - Universal rules (scratchpad, AIDEV-NOTE, type safety)
- `skill-index` - Available skills reference
- `workflow/interactive` - CLAUDE_COUNTER, git safety
 
These contexts provide project-specific rules and patterns. If you need additional contexts, update the project's `contexts` array in `~/.config/golems/registry.json`.
 
## 🔄 CodeRabbit Iteration Rule
 
**For "Run CodeRabbit review" criteria, iterate until clean:**
 
1. Run: `cr review --prompt-only --type uncommitted`
2. If issues found → Fix them
3. Run CR again
4. Repeat until: "No issues found" or only intentional patterns remain
5. If intentional pattern → Add to CLAUDE.md's CodeRabbit Context section
 
**Never skip CR or commit with unresolved issues.**
 
## ⚠️ NEVER EDIT index.json DIRECTLY
 
To add/modify stories, use `update.json`:
 
1. Create story files in `stories/`
2. Write changes to `update.json` (not index.json!)
3. Ralph merges automatically on next run
 
## Example update.json
\`\`\`json
{
  "storyOrder": ["existing...", "NEW-001"],
  "pending": ["existing...", "NEW-001"]
}
\`\`\`
Note: Do NOT include `stats` - computed automatically.
 
## Story ID Rules
- Check `archive/` for used IDs before creating new ones
- Use next available number (e.g., if US-033 exists, use US-034)

Then say:

✅ PRD saved to prd-json/ with X stories + X verification stories. Run Ralph to execute. I will not implement - that's Ralph's job.

Checklist

• Ran skill discovery - identified relevant skills for project
• prd-json/ created at repo root
• index.json has storyOrder, pending, blocked (NO stats - computed automatically)
• AGENTS.md created with skills section + update.json instructions
• Each story has its own JSON file
• Stories ordered by dependency
• All criteria are verifiable
• Every story has "Typecheck passes"
• UI stories have "Verify in browser"
• Verification stories (V-XXX) for each US-XXX
• Every story ends with CodeRabbit + Commit criteria
• RTL rules included (if applicable) — flex order, text-right, items-end, nested RTL
• Modal rules followed (if applicable) — each state = separate story