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 stringbranchName - Required, format: ralph/[slug]userStories - Required, non-empty array- Each story must have:
id - Format: US-XXXtitle - Non-empty stringacceptanceCriteria - Array with at least 2 itemspriority - Number 1-10passes - 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
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:
- US-001: [Title] (Priority 1) - Foundation
- US-002: [Title] (Priority 2) - Core logic
- US-003: [Title] (Priority 3) - API
...
Files Created/Updated:
Next Steps:
- Review prd.json for accuracy
- Create branch: git checkout -b ralph/[feature-slug]
- 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:
-
Create feature branch:
bash
1git checkout -b ralph/[feature-slug]
-
Start RALPH:
bash
1./scripts/ralph/ralph.sh 20
-
Monitor progress:
bash
1tail -f progress.txt
2cat prd.json | jq '.userStories[] | {id, title, passes}'
-
When complete:
bash
1git log --oneline
2# Review changes, create PR
