doravidan/ralph

RALPH - Autonomous Development Manager

Manage RALPH (Recursive Autonomous Loop for Production Harmony) autonomous development in any project.

Commands

| Command | Description | |---------|-------------| | /ralph | Show PRD completion status | | /ralph --status | Detailed status with remaining stories | | /ralph --validate | Validate prd.json schema | | /ralph --reset | Reset progress.txt for fresh start | | /ralph --analyze | Re-analyze project, regenerate PROJECT_SPEC.md |

Triggers

• /ralph or /ralph --status
• "show RALPH status"
• "what's the PRD status"
• "how many stories are done"

Process

Status Check (/ralph or /ralph --status)

1. Check for PRD file:

# Check which PRD format exists
if [ -f prd.json ]; then
  echo "Found: prd.json (JSON format)"
elif [ -f PRD.md ]; then
  echo "Found: PRD.md (Markdown format)"
elif [ -f tasks.yaml ]; then
  echo "Found: tasks.yaml (YAML format)"
else
  echo "No PRD found. Run /prd or /setup-project first."
fi

2. Display status for JSON format:

cat prd.json | jq '{
  project: .project,
  branch: .branchName,
  total: (.userStories | length),
  complete: ([.userStories[] | select(.passes == true)] | length),
  remaining: ([.userStories[] | select(.passes == false)] | length),
  percentComplete: (([.userStories[] | select(.passes == true)] | length) * 100 / (.userStories | length) | floor)
}'

3. Show remaining stories:

echo ""
echo "=== Remaining Stories ==="
cat prd.json | jq -r '.userStories[] | select(.passes == false) | "  \(.id): \(.title) (Priority \(.priority))"'

4. Show progress log summary:

if [ -f .ralph/progress.txt ]; then
  echo ""
  echo "=== Recent Progress ==="
  tail -20 .ralph/progress.txt
fi

Output format:

╔════════════════════════════════════════════════════════════════╗
║                      RALPH Status                               ║
╚════════════════════════════════════════════════════════════════╝

Project: User Authentication
Branch: ralph/user-authentication
Progress: 3/6 stories (50% complete)

=== Remaining Stories ===
  US-004: Add login and register routes (Priority 4)
  US-005: Implement auth middleware (Priority 5)
  US-006: Add logout and session management (Priority 6)

=== Recent Progress ===
## 2024-01-15 - US-003: Create JWT token utilities
- Implemented JWT signing and verification
- Files changed: src/utils/jwt.ts, tests/jwt.test.ts
- Learnings: Use jose library for edge compatibility
---

Validate (/ralph --validate)

1. Check prd.json exists:

if [ ! -f prd.json ]; then
  echo "❌ No prd.json found"
  echo "Run /prd [feature] to create one"
  exit 1
fi

2. Validate JSON syntax:

cat prd.json | jq . > /dev/null 2>&1
if [ $? -ne 0 ]; then
  echo "❌ prd.json is not valid JSON"
  exit 1
fi

3. Validate schema:

Check for required fields:

• project (string) - Project/feature name
• userStories (array) - List of stories
• Each story must have:
  • id (string) - Unique identifier like "US-001"
  • title (string) - Brief title
  • description (string) - What to implement
  • acceptanceCriteria (array of strings) - What must be true
  • priority (number) - 1 is highest
  • passes (boolean) - Completion status

# Check required fields
VALID=true

PROJECT=$(cat prd.json | jq -r '.project // empty')
if [ -z "$PROJECT" ]; then
  echo "❌ Missing 'project' field"
  VALID=false
fi

STORIES=$(cat prd.json | jq '.userStories | length')
if [ "$STORIES" -eq 0 ]; then
  echo "❌ No user stories found"
  VALID=false
fi

# Check each story
cat prd.json | jq -r '.userStories[] | select(.id == null or .title == null or .priority == null or .passes == null) | .id // "unknown"' | while read id; do
  echo "❌ Story '$id' missing required fields"
  VALID=false
done

if $VALID; then
  echo "✓ prd.json is valid"
  echo "  Project: $PROJECT"
  echo "  Stories: $STORIES"
fi

Output format:

╔════════════════════════════════════════════════════════════════╗
║                  PRD Validation Results                         ║
╚════════════════════════════════════════════════════════════════╝

✓ JSON syntax: Valid
✓ Project field: "User Authentication"
✓ User stories: 6 stories found

Story Validation:
  ✓ US-001: Has all required fields
  ✓ US-002: Has all required fields
  ⚠ US-003: Missing acceptanceCriteria (recommended)
  ✓ US-004: Has all required fields
  ✓ US-005: Has all required fields
  ✓ US-006: Has all required fields

Overall: ✓ Valid (1 warning)

Reset (/ralph --reset)

1. Confirm with user:

Use AskUserQuestion:

? Are you sure you want to reset RALPH progress?
  ○ Yes, reset progress.txt (keeps prd.json untouched)
  ○ Yes, reset everything (resets progress and all story statuses)
  ○ No, cancel

2. Reset progress.txt only:

cat > .ralph/progress.txt << 'EOF'
# RALPH Progress Log

Reset: $(date +%Y-%m-%d)
Reason: Manual reset by user

## Discovered Patterns
(Patterns will be logged here as they are discovered during iterations)

## Learnings
(Key learnings from each task will be recorded here)

---
EOF

3. Reset everything (if requested):

Also reset all story statuses:

# Reset all stories to passes: false
cat prd.json | jq '.userStories |= map(.passes = false)' > prd.json.tmp
mv prd.json.tmp prd.json

Output:

✓ Reset complete

Progress log cleared: .ralph/progress.txt
{{#if resetStories}}
Story statuses reset: All 6 stories set to incomplete
{{/if}}

Run /ralph-run to start fresh.

Analyze (/ralph --analyze)

1. Inform user:

🔍 Re-analyzing project...

This will:
  1. Scan the codebase for patterns
  2. Detect frameworks, test setup, linting
  3. Regenerate PROJECT_SPEC.md
  4. Update .ralph/config.yaml if needed

Existing files will be backed up.

2. Run analysis:

• Scan directory structure
• Detect language from file extensions
• Parse package.json / requirements.txt / go.mod
• Detect test framework from dependencies and config files
• Find existing patterns in code

3. Regenerate PROJECT_SPEC.md:

Back up existing file, then regenerate with discovered patterns.

4. Update config.yaml:

Update quality commands based on detected tools.

Output:

╔════════════════════════════════════════════════════════════════╗
║                  Project Analysis Complete                      ║
╚════════════════════════════════════════════════════════════════╝

Detected:
  Language: TypeScript
  Framework: Express
  Test Framework: Vitest
  Linter: ESLint + Prettier

Patterns Found:
  - ES Modules (import/export)
  - Functional components
  - Tests co-located with source

Updated:
  ✓ PROJECT_SPEC.md (backed up to PROJECT_SPEC.md.bak)
  ✓ .ralph/config.yaml

Run /ralph --status to see current PRD status.

Error Handling

| Error | Message | Solution | |-------|---------|----------| | No PRD | "No PRD found" | Run /prd [feature] or /setup-project | | Invalid JSON | "prd.json is not valid JSON" | Fix syntax errors in prd.json | | No .ralph directory | "RALPH not configured" | Run /setup-project | | Permission denied | "Cannot write to .ralph/" | Check directory permissions |

Tips

• Run /ralph --status frequently to track progress
• Use /ralph --validate before starting /ralph-run
• Use /ralph --reset if you want to start a feature over
• Use /ralph --analyze after major codebase changes