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`)

•Check for PRD file:

bash

# 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

•Display status for JSON format:

bash

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)
}'

•Show remaining stories:

bash

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

•Show progress log summary:

bash

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

Output format:

code

╔════════════════════════════════════════════════════════════════╗
║                      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`)

•Check prd.json exists:

bash

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

•Validate JSON syntax:

bash

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

•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

bash

# 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:

code

╔════════════════════════════════════════════════════════════════╗
║                  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`)

•Confirm with user:

Use AskUserQuestion:

code

? 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

•Reset progress.txt only:

bash

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

•Reset everything (if requested):

Also reset all story statuses:

bash

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

Output:

code

✓ 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`)

•Inform user:

code

🔍 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.

•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

•Regenerate PROJECT_SPEC.md:

Back up existing file, then regenerate with discovered patterns.

•Update config.yaml:

Update quality commands based on detected tools.

Output:

code

╔════════════════════════════════════════════════════════════════╗
║                  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

RALPH - Autonomous Development Manager

Commands

Triggers

Process

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

Validate (/ralph --validate)

Reset (/ralph --reset)

Analyze (/ralph --analyze)

Error Handling

Tips

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

Validate (`/ralph --validate`)

Reset (`/ralph --reset`)

Analyze (`/ralph --analyze`)