doravidan/ralph

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:

# Check if prd.json exists
if [ -f prd.json ]; then
  echo "=== RALPH Status ==="
  cat prd.json | jq '{
    project: .project,
    branch: .branchName,
    total: (.userStories | length),
    complete: ([.userStories[] | select(.passes == true)] | length),
    remaining: ([.userStories[] | select(.passes == false)] | length)
  }'

  echo ""
  echo "=== Stories ==="
  cat prd.json | jq -r '.userStories[] | "\(.id): \(.title) [\(if .passes then "✓" else "○" end)]"'
else
  echo "No prd.json found."
  echo ""
  echo "Create one with:"
  echo "  /prd [feature description]"
fi

/ralph --status - Detailed Status

echo "=== PRD Status ==="
cat prd.json | jq '.'

echo ""
echo "=== Progress Log (last 50 lines) ==="
tail -50 progress.txt 2>/dev/null || echo "No progress.txt found"

echo ""
echo "=== Git Status ==="
git status --short
git log --oneline -5

/ralph --validate - Validate PRD

Check prd.json for issues:

# Validation checks:
# 1. JSON is valid
# 2. Required fields exist
# 3. All stories have acceptance criteria
# 4. Stories have quality gate criteria
# 5. Priorities are sequential
# 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:

# Archive current progress
if [ -f progress.txt ]; then
  mkdir -p archive/$(date +%Y-%m-%d)
  cp progress.txt archive/$(date +%Y-%m-%d)/progress-backup.txt
fi

# Extract patterns section from current progress
PATTERNS=$(sed -n '/## Codebase Patterns/,/^---$/p' progress.txt 2>/dev/null)

# Get branch name from prd.json
BRANCH=$(cat prd.json | jq -r '.branchName')

# Create fresh progress.txt
cat > progress.txt << EOF
# Progress Log - $BRANCH

Reset: $(date +%Y-%m-%d)

$PATTERNS

---

EOF

echo "Progress reset. Previous progress archived."

/ralph --analyze - Re-analyze Project

Re-run project analysis and update specs:

# This triggers the project analyzer to refresh:
# - PROJECT_SPEC.md
# - scripts/ralph/CLAUDE.md context
# - progress.txt patterns

node 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

cat 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

{
  "project": "[Feature Name]",
  "branchName": "ralph/[feature-slug]",
  "description": "[Overview text]",
  "createdAt": "[Today's date]",
  "projectContext": {
    "name": "[Project name from PROJECT_SPEC.md]",
    "language": "[typescript/python/go]",
    "framework": "[react/express/fastapi]",
    "hasTypes": true,
    "testFramework": "[vitest/pytest]"
  },
  "existingPatterns": {
    "moduleSystem": "[ES modules/CommonJS]",
    "testFramework": "[vitest/jest/pytest]",
    "linter": "[eslint/biome/ruff]"
  },
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "[Full story description]",
      "acceptanceCriteria": [
        "[Criterion 1]",
        "[Criterion 2]"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Step 4: Archive Previous PRD

If prd.json already exists:

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

Step 5: Initialize Progress

Create fresh progress.txt:

# Progress Log - ralph/[feature-slug]

Started: [Date]
Feature: [Feature description]

## Project Context
[From PROJECT_SPEC.md if available]

## Codebase Patterns
[Patterns from analysis or PROJECT_SPEC.md]

## Quality Commands
```bash
[typecheck command]
[lint command]
[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):

{
  "project": "User Authentication",
  "branchName": "ralph/user-auth",
  "description": "Add user authentication with email/password login.",
  "createdAt": "2026-01-22",
  "userStories": [
    {
      "id": "US-001",
      "title": "Create user model",
      "description": "As a developer, I want a User model with proper types so that I can store user data securely",
      "acceptanceCriteria": [
        "User interface with id, email, passwordHash",
        "Validation for email format",
        "TypeScript compiles"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Integration with RALPH

After prd.json is created:

1. Create feature branch:

   git checkout -b ralph/[feature-slug]
   

2. Start RALPH:

   ./scripts/ralph/ralph.sh 20
   

3. Monitor progress:

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

4. When complete:

   git log --oneline
   # Review changes, create PR