What Ralph Does

Initializes PRD - Creates structured project requirements
Starts Claude Code - With --dangerously-skip-permissions flag
Manages RALPH Loop - Tracks task priority, completion, testing
Handles Commits - Auto-commits with task IDs (e.g., "SEC-001: Add .gitignore")
Monitors Progress - Updates PRD as tasks complete
Runs Tests - Verifies each task works before moving on

RALPH BUILD LOOP

Ralph follows this 8-step workflow automatically:

1. START      → Create .gitignore + .env.example (security first!)
2. LOOP       → Pick highest priority incomplete task
3. READ       → Check if file exists, read existing code
4. BUILD      → Implement task per acceptance_criteria
5. TEST       → Run test command, verify it works
6. COMMIT     → git add + commit with task ID
7. MARK       → Update task status to "complete"
8. REPEAT     → Go to step 2 until all tasks done
9. DONE       → Run full test suite

Monitoring

Ralph automatically monitors Claude Code builds in the background:

# Monitor a running build
ralph monitor --session <session_id> --dir <project_dir>

# With custom check interval (default 30s)
ralph monitor --session <session_id> --dir <project_dir> --interval 60

What monitoring does:

Checks session status every 30 seconds (configurable)
Reports file changes (what's being created/modified)
Shows recent activity snippets
Alerts if session stops unexpectedly
Continues for max duration (default 1 hour)

Output example:

📊 BUILD STATUS CHECK
⏱️  Session: fast-slug...
🟢 RUNNING
📝 Recent files (5):
   - package.json
   - src/App.jsx
   - Dockerfile
   - ...and 2 more
💬 Recent activity: CORE-001: Implementing chess logic...

The monitor runs continuously and reports status every interval, so you don't have to manually check!

Commands

ralph init

Initialize a new PRD-based project.

ralph init --name "Project Name" --language python
ralph init --name "Web App" --language javascript --github

Options:

--name (required) - Project name
--language (optional) - Programming language (python, javascript, go, rust, etc.)
--github (optional) - Create GitHub repo on initialization
--path (optional) - Project directory (default: current)

Creates:

PRD.json - Project requirements document
.gitignore - Security baseline
.env.example - Environment template
ralph.config.json - Ralph configuration

ralph build

Start Claude Code with the PRD and begin the RALPH BUILD LOOP.

ralph build                          # Use PRD.json in current dir
ralph build --prd custom-prd.json   # Use custom PRD
ralph build --auto-commit           # Auto-commit after each task

Options:

--prd (optional) - Path to PRD file
--auto-commit (optional) - Automatically commit after each task
--section (optional) - Start from specific section (00_security, 01_setup, etc.)

ralph status

Show current project status and task progress.

ralph status

Shows:

Tasks complete / total
Current section
Next task to work on
Recent commits
Test results

ralph update

Update PRD task status after manual changes.

ralph update --task SEC-001 --status complete
ralph update --task SEC-001 --comment "Security baseline added"

ralph test

Run project test suite (language-specific).

ralph test                    # Run all tests
ralph test --task SEC-001     # Test specific task

ralph commit

Create a commit with task ID (called automatically by ralph build).

ralph commit --task SEC-001 --message "Add .gitignore"

ralph cleanup

Clean up after project completion.

ralph cleanup                 # Archive PRD and config
ralph cleanup --full         # Remove entire project

PRD Structure

Ralph creates PRDs with this structure:

{
  "pn": "Project Name",
  "pd": "Project description",
  "sp": "Starter prompt for Claude Code",
  "gh": true,
  "ts": {
    "language": "Python",
    "framework": "Flask"
  },
  "p": {
    "00_security": {
      "n": "Security",
      "t": [
        {
          "id": "SEC-001",
          "ti": "Create .gitignore",
          "d": "Add .gitignore with secrets and dependencies",
          "f": ".gitignore",
          "pr": "high",
          "st": "pending",
          "ac": "[x] .gitignore created, [x] .env.example created"
        }
      ]
    },
    "01_setup": {...},
    "02_core": {...},
    "03_api": {...},
    "04_test": {...}
  }
}

Fields:

id - Task identifier (e.g., SEC-001)
ti - Task title
d - Task description
f - File(s) involved
pr - Priority (high, medium, low)
st - Status (pending, in_progress, complete, blocked)
ac - Acceptance criteria (checklist form)

Configuration

Ralph stores config in ralph.config.json:

{
  "project_name": "My Project",
  "language": "python",
  "prd_path": "PRD.json",
  "test_command": "pytest",
  "auto_commit": false,
  "claude_code_flags": ["--dangerously-skip-permissions"],
  "git_user": "name",
  "git_email": "email@example.com"
}

Task Priority Order

Ralph always works in this order:

00_security - .gitignore, .env.example, secrets management
01_setup - Git repo, GitHub, CI/CD, dependencies
02_core - Main application logic and features
03_api - API endpoints, integrations
04_test - Full test suite, coverage

Usage Example

# 1. Initialize new Python project
ralph init --name "Todo API" --language python

# 2. Edit PRD.json with your specific tasks
# (Ralph adds defaults; customize as needed)

# 3. Start Claude Code with RALPH loop
ralph build --auto-commit

# 4. Monitor progress
ralph status

# 5. When done, review and clean up
ralph cleanup

Advanced Features

Custom Test Commands

Ralph auto-detects test commands by language:

Python  → pytest
Node.js → npm test
Go      → go test ./...
Rust    → cargo test

Override in ralph.config.json:

{
  "test_command": "python -m pytest --cov"
}

GitHub Integration

Ralph can create GitHub repos and set up CI/CD:

ralph init --name "Project" --github

This creates:

Remote GitHub repository
.github/workflows/test.yml for CI/CD
Protected main branch rules

Task Dependencies

Mark tasks that depend on others:

{
  "id": "CORE-005",
  "ti": "Setup database",
  "depends_on": ["CORE-001", "CORE-002"],
  "st": "pending"
}

Ralph won't start CORE-005 until CORE-001 and CORE-002 are complete.

How to Start a Build

# Initialize a new project
ralph init --name "My Project" --language python

# Edit PRD.json with your specific tasks

# Start Claude Code (WITHOUT --dangerously-skip-permissions)
cd ~/Desktop/my-project
claude exec "Follow the RALPH BUILD LOOP. Here's the PRD: $(cat PRD.json)"

# Approve the security prompt when Claude Code asks
# Then let it work through each task

Important: Don't use --dangerously-skip-permissions - it causes Claude Code to get confused. Let it ask for permission normally when needed.

Permissions & Safety Philosophy

I (Clawd) am in charge of granting permissions during builds. You've indicated you're very tolerant of most operations as long as they:

Don't blow up the machine
Don't expose you to scammers
Don't nuke your files

Philosophy (from you):

"I take safety seriously. I want you to have an eye out for security AND balance good UX/good UI. I don't like security to the point of making user experiences unusable. Security is mostly theater. But the security that isn't theater—like .gitignore and envelopes—that is non-negotiable."

Translation: Optimize for user experience, but NEVER skip the fundamentals:

✅ .gitignore is mandatory (no credentials in repos)
✅ .env files are mandatory (secrets never committed)
✅ No security theater (don't ask for permission on safe, standard operations)
✅ UX/DX matters (make builds smooth and fast)

I will auto-approve safe operations:

✅ npm install, npm run, package management
✅ Creating/editing files in the project directory
✅ Running build/test commands (npm build, cargo test, etc.)
✅ Docker commands (docker build, docker compose up, etc.)
✅ Git operations (git init, git add, git commit, git push)
✅ Standard development tools and operations
✅ Adding proper .gitignore and .env.example files

I will ask or refuse:

❌ Commands that delete important directories
❌ Operations that modify system-level settings
❌ Running unvetted third-party scripts
❌ Anything accessing/exposing sensitive data or credentials
❌ Network operations that seem suspicious
❌ Skipping .gitignore or .env security (non-negotiable)

During builds: When Claude Code asks for permission, I'll handle it automatically if it's safe. You focus on the bigger picture while I manage the operational details AND ensure the fundamentals are solid.

Bundled Resources

scripts/init_prd.py - Create new PRD
scripts/run_ralph_loop.py - Execute RALPH workflow
scripts/monitor_build.py - Monitor Claude Code session and report progress
references/prd_templates.md - PRD templates by language
assets/prd_schema.json - PRD JSON schema

Common Issues

Claude Code won't start

Ensure claude CLI is installed
Check --dangerously-skip-permissions is supported in your version

Tasks aren't committing

Verify git is initialized: git init
Check git config: git config user.email

Tests failing

Ralph pauses and reports failures
Review test output and fix, then resume with ralph build --section 04_test

Tips

Start with security - Ralph always does .gitignore + .env.example first
Read the PRD carefully - Good PRD = good project
Test often - Ralph tests after each task
Commit messages - Task IDs make history clear
Review PRD regularly - Update acceptance_criteria as you learn

ralph

Ralph Skill - PRD-Driven Development

Quick Start