RALPH Skill - PRD Conversion & Management

Convert PRD Markdown files to prd.json format and manage RALPH autonomous development.

Triggers

This skill activates when:

• /ralph - Show status and help
• /ralph --status - Show detailed PRD status
• /ralph --validate - Validate prd.json
• /ralph --reset - Reset progress.txt for fresh start
• /ralph --analyze - Re-analyze project and update specs
• /ralph-convert <file> - Convert PRD markdown to prd.json

Commands

/ralph - Status & Help

Show current PRD status and available commands:

bash
1# Check if prd.json exists
2if [ -f prd.json ]; then
3  echo "=== RALPH Status ==="
4  cat prd.json | jq '{
5    project: .project,
6    branch: .branchName,
7    total: (.userStories | length),
8    complete: ([.userStories[] | select(.passes == true)] | length),
9    remaining: ([.userStories[] | select(.passes == false)] | length)
10  }'
11
12  echo ""
13  echo "=== Stories ==="
14  cat prd.json | jq -r '.userStories[] | "\(.id): \(.title) [\(if .passes then "✓" else "○" end)]"'
15else
16  echo "No prd.json found."
17  echo ""
18  echo "Create one with:"
19  echo "  /prd [feature description]"
20fi

/ralph --status - Detailed Status

bash
1echo "=== PRD Status ==="
2cat prd.json | jq '.'
3
4echo ""
5echo "=== Progress Log (last 50 lines) ==="
6tail -50 progress.txt 2>/dev/null || echo "No progress.txt found"
7
8echo ""
9echo "=== Git Status ==="
10git status --short
11git log --oneline -5

/ralph --validate - Validate PRD

Check prd.json for issues:

bash
1# Validation checks:
2# 1. JSON is valid
3# 2. Required fields exist
4# 3. All stories have acceptance criteria
5# 4. Stories have quality gate criteria
6# 5. Priorities are sequential
7# 6. Branch name follows convention

Validation Rules:

• project - Required, non-empty string
• branchName - Required, format: ralph/[slug]
• userStories - Required, non-empty array
• Each story must have:
  • id - Format: US-XXX
  • title - Non-empty string
  • acceptanceCriteria - Array with at least 2 items
  • priority - Number 1-10
  • passes - Boolean

Output:

Validating prd.json...

✓ JSON is valid
✓ Project name: [name]
✓ Branch: ralph/[slug]
✓ Stories: [N] total

Story Validation:
  US-001: [Title] ✓
  US-002: [Title] ✓
  ...

⚠ Warnings:
  - US-003: Missing "Tests pass" in acceptance criteria
  - US-005: Large story (6+ criteria), consider splitting

✓ PRD is valid and ready for RALPH

/ralph --reset - Reset Progress

Reset progress.txt while preserving patterns:

bash
1# Archive current progress
2if [ -f progress.txt ]; then
3  mkdir -p archive/$(date +%Y-%m-%d)
4  cp progress.txt archive/$(date +%Y-%m-%d)/progress-backup.txt
5fi
6
7# Extract patterns section from current progress
8PATTERNS=$(sed -n '/## Codebase Patterns/,/^---$/p' progress.txt 2>/dev/null)
9
10# Get branch name from prd.json
11BRANCH=$(cat prd.json | jq -r '.branchName')
12
13# Create fresh progress.txt
14cat > progress.txt << EOF
15# Progress Log - $BRANCH
16
17Reset: $(date +%Y-%m-%d)
18
19$PATTERNS
20
21---
22
23EOF
24
25echo "Progress reset. Previous progress archived."

/ralph --analyze - Re-analyze Project

Re-run project analysis and update specs:

bash
1# This triggers the project analyzer to refresh:
2# - PROJECT_SPEC.md
3# - scripts/ralph/CLAUDE.md context
4# - progress.txt patterns
5
6node scripts/run-ralph.js --analyze

/ralph-convert <file> - Convert PRD to JSON

Convert a PRD markdown file to prd.json:

Converting: tasks/prd-[feature].md

Reading PRD...
Extracting project info...
Parsing user stories...
Validating structure...

Generated prd.json:
- Project: [Feature Name]
- Branch: ralph/[feature-slug]
- Stories: [N] total

Initializing progress.txt...
Done!

Next: ./scripts/ralph/ralph.sh 20

PRD Conversion Process

Step 1: Read the PRD

bash
1cat tasks/prd-[feature-name].md

Step 2: Extract Information

Parse the PRD to extract:

• Project name - From # PRD: [Name] title
• Description - From ## Overview section
• Project Context - From ## Project Context if present
• User stories with:
  • ID (US-001, US-002, etc.)
  • Title
  • Description (As a... I want... So that...)
  • Acceptance criteria (bullet points)
  • Priority

Step 3: Generate prd.json

json
1{
2  "project": "[Feature Name]",
3  "branchName": "ralph/[feature-slug]",
4  "description": "[Overview text]",
5  "createdAt": "[Today's date]",
6  "projectContext": {
7    "name": "[Project name from PROJECT_SPEC.md]",
8    "language": "[typescript/python/go]",
9    "framework": "[react/express/fastapi]",
10    "hasTypes": true,
11    "testFramework": "[vitest/pytest]"
12  },
13  "existingPatterns": {
14    "moduleSystem": "[ES modules/CommonJS]",
15    "testFramework": "[vitest/jest/pytest]",
16    "linter": "[eslint/biome/ruff]"
17  },
18  "userStories": [
19    {
20      "id": "US-001",
21      "title": "[Story title]",
22      "description": "[Full story description]",
23      "acceptanceCriteria": [
24        "[Criterion 1]",
25        "[Criterion 2]"
26      ],
27      "priority": 1,
28      "passes": false,
29      "notes": ""
30    }
31  ]
32}

Step 4: Archive Previous PRD

If prd.json already exists:

bash
1mkdir -p archive/$(date +%Y-%m-%d)
2cp prd.json archive/$(date +%Y-%m-%d)/prd-backup.json
3cp progress.txt archive/$(date +%Y-%m-%d)/progress-backup.txt 2>/dev/null

Step 5: Initialize Progress

Create fresh progress.txt:

markdown
1# Progress Log - ralph/[feature-slug]
2
3Started: [Date]
4Feature: [Feature description]
5
6## Project Context
7[From PROJECT_SPEC.md if available]
8
9## Codebase Patterns
10[Patterns from analysis or PROJECT_SPEC.md]
11
12## Quality Commands
13```bash
14[typecheck command]
15[lint command]
16[test command]

## Story Conversion Rules

### 1. Story Sizing

If a PRD story is too large, split it:
- Data model → separate story
- Backend logic → separate story
- API endpoint → separate story
- UI component → separate story
- Tests → integrated into each story

### 2. Priority Assignment

Assign priorities based on dependencies:

| Priority | Category | Examples |
|----------|----------|----------|
| 1 | Foundation | Schema, types, interfaces |
| 2 | Core Logic | Services, business logic |
| 3 | API/Backend | Routes, controllers, middleware |
| 4 | UI Components | Forms, displays, interactions |
| 5 | Polish | Optimization, edge cases, docs |

### 3. Required Acceptance Criteria

Always ensure these criteria exist based on tech stack:

**TypeScript/JavaScript:**
- "TypeScript compiles without errors" or "No type errors"
- "ESLint/Biome passes"
- "Tests pass"

**Python:**
- "Type hints complete"
- "Ruff/Pylint passes"
- "Pytest passes"

**Go:**
- "`go build` succeeds"
- "`golangci-lint` passes"
- "`go test ./...` passes"

**For specific story types:**
- UI stories: "Verify in browser", "Accessible"
- API stories: "Response format correct", "Error handling complete"
- Auth stories: "Security best practices followed"

### 4. Branch Naming

Convert feature name to slug:
- "User Authentication" → `ralph/user-authentication`
- "Dark Mode Toggle" → `ralph/dark-mode-toggle`
- Use lowercase, replace spaces with hyphens
- Max 30 characters

## Output Format

After conversion:

=== PRD Converted ===

Project: [Feature Name] Branch: ralph/[feature-slug] Stories: [N] total

Story Summary:

1. US-001: [Title] (Priority 1) - Foundation
2. US-002: [Title] (Priority 2) - Core logic
3. US-003: [Title] (Priority 3) - API ...

Files Created/Updated:

• prd.json
• progress.txt

Next Steps:

1. Review prd.json for accuracy
2. Create branch: git checkout -b ralph/[feature-slug]
3. Start RALPH: ./scripts/ralph/ralph.sh 20

## Example Conversion

**Input** (`tasks/prd-user-auth.md`):
```markdown
# PRD: User Authentication

## Overview
Add user authentication with email/password login.

## User Stories

### US-001: Create user model
**As a** developer
**I want** a User model with proper types
**So that** I can store user data securely

**Acceptance Criteria:**
- [ ] User interface with id, email, passwordHash
- [ ] Validation for email format
- [ ] TypeScript compiles

**Priority:** 1

Output (prd.json):

json
1{
2  "project": "User Authentication",
3  "branchName": "ralph/user-auth",
4  "description": "Add user authentication with email/password login.",
5  "createdAt": "2026-01-22",
6  "userStories": [
7    {
8      "id": "US-001",
9      "title": "Create user model",
10      "description": "As a developer, I want a User model with proper types so that I can store user data securely",
11      "acceptanceCriteria": [
12        "User interface with id, email, passwordHash",
13        "Validation for email format",
14        "TypeScript compiles"
15      ],
16      "priority": 1,
17      "passes": false,
18      "notes": ""
19    }
20  ]
21}

Integration with RALPH

After prd.json is created:

1. Create feature branch:

   bash
   1git checkout -b ralph/[feature-slug]

2. Start RALPH:

   bash
   1./scripts/ralph/ralph.sh 20

3. Monitor progress:

   bash
   1tail -f progress.txt
   2cat prd.json | jq '.userStories[] | {id, title, passes}'

4. When complete:

   bash
   1git log --oneline
   2# Review changes, create PR