Objective
Set up the Ralph autonomous coding loop in any project. Ralph runs AI agents in a loop, picking tasks from a PRD, implementing one at a time, committing after each, and accumulating learnings until all tasks are complete.
This skill ONLY sets up Ralph - you run the commands yourself.
Quick Start
Setup Ralph interactively (recommended):
/setup-ralph -i
Setup for specific feature:
/setup-ralph -f 01-add-authentication
What this does:
- •Creates
.agent/ralph/structure in your project - •Runs setup script to create all Ralph files
- •(If -i): Brainstorms PRD with you interactively
- •Transforms PRD into user stories (prd.json)
- •Shows you the command to run Ralph (you run it yourself)
After setup, you run:
bun run .agent/ralph/ralph.sh -f <feature-name>
Critical Rule
🛑 NEVER run ralph.sh or any execution commands automatically 🛑 NEVER execute the loop - only set up files and show instructions ✅ ALWAYS let the user copy and run commands themselves ✅ ALWAYS end by showing the exact command to run
When To Use
Use this skill when:
- •Starting a new feature that can be broken into small stories
- •Setting up Ralph in a new project
- •Creating a new feature PRD interactively
Don't use for:
- •Simple single-file changes
- •Exploratory work without clear requirements
- •Major refactors without acceptance criteria
Parameters
| Flag | Description |
|---|---|
<project-path> | Path to the project (defaults to current directory) |
-i, --interactive | Interactive mode: brainstorm PRD with AI assistance |
-f, --feature <name> | Feature folder name (e.g., 01-add-auth) |
Examples:
/setup-ralph /path/to/project -i # Interactive PRD creation /setup-ralph . -f 01-add-auth # Setup for specific feature /setup-ralph -i -f 02-user-dashboard # Interactive with specific name
State Variables
| Variable | Type | Description |
|---|---|---|
{project_path} | string | Absolute path to target project |
{ralph_dir} | string | Path to .agent/ralph in project |
{feature_name} | string | Feature folder name (e.g., 01-add-auth) |
{feature_dir} | string | Path to task folder |
{interactive_mode} | boolean | Whether to brainstorm PRD interactively |
{prd_content} | string | PRD markdown content |
{user_stories} | array | User stories extracted from PRD |
{branch_name} | string | Git branch for the feature |
Entry Point
Load resources/steps/step-00-init.md
Step Files
| Step | File | Purpose |
|---|---|---|
| 00 | resources/steps/step-00-init.md | Parse flags, run setup script, create structure |
| 01 | resources/steps/step-01-interactive-prd.md | Interactive PRD brainstorming and creation |
| 02 | resources/steps/step-02-create-stories.md | Transform PRD into user stories (prd.json) |
| 03 | resources/steps/step-03-finish.md | Show run command (user runs it themselves) |
Scripts
| Script | Purpose |
|---|---|
scripts/setup.sh | Creates all Ralph files in the project |
Execution Rules
- •Progressive Loading: Load one step at a time
- •Script Execution: Use scripts/setup.sh to create files atomically
- •Interactive Mode: If -i flag, run brainstorming conversation
- •State Persistence: Track progress in feature_dir/progress.txt
- •Resume Support: Detect existing PRD.md and resume from there
- •NEVER RUN RALPH: Only setup and show commands - user runs them
Success Criteria
✅ Ralph structure created at {project_path}/.agent/ralph ✅ Feature folder created with PRD.md, prd.json, progress.txt ✅ User stories properly formatted in prd.json ✅ Clear run command provided to user (they run it themselves)