# Setup Ralph

> Setup the Ralph autonomous AI coding loop - ships features while you sleep

- Skill: `nicanac/setup-ralph` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add nicanac/setup-ralph`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nicanac/setup-ralph/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nicanac (https://skillmd.com/u/nicanac)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nicanac/setup-ralph

---


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

```bash
/setup-ralph -i
```

**Setup for specific feature:**

```bash
/setup-ralph -f 01-add-authentication
```

**What this does:**

1. Creates `.agent/ralph/` structure in your project
2. Runs setup script to create all Ralph files
3. (If -i): Brainstorms PRD with you interactively
4. Transforms PRD into user stories (prd.json)
5. Shows you the command to run Ralph (you run it yourself)

**After setup, you run:**

```bash
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:**

```bash
/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

1. **Progressive Loading**: Load one step at a time
2. **Script Execution**: Use scripts/setup.sh to create files atomically
3. **Interactive Mode**: If -i flag, run brainstorming conversation
4. **State Persistence**: Track progress in feature_dir/progress.txt
5. **Resume Support**: Detect existing PRD.md and resume from there
6. **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)