diff --git a/README.md b/README.md index d79d8b62e..98d817db8 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,13 @@ Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/). ## Setup -### Option 1: Copy to your project +### Step 1: Install the Ralph runner into your project (required) -Copy the ralph files into your project: +Copy the Ralph runner into your project. Ralph stores `prd.json` and +`progress.txt` next to `ralph.sh`, so keep these files together in the same +directory. + +Example: ```bash # From your project root @@ -35,7 +39,15 @@ cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md # For Claude Code chmod +x scripts/ralph/ralph.sh ``` -### Option 2: Install skills globally (Amp) +This step is required whether you use the skills manually, install them +globally, or install them from the Claude Code marketplace. + +### Step 2: Install the converter skills (optional) + +The converter skills help you generate a markdown PRD and convert it into +`prd.json`, but they do not install the Ralph runner into your project. + +#### Option 2A: Install skills globally (Amp) Copy the skills to your Amp or Claude config for use across all projects: @@ -51,7 +63,7 @@ cp -r skills/prd ~/.claude/skills/ cp -r skills/ralph ~/.claude/skills/ ``` -### Option 3: Use as Claude Code Marketplace +#### Option 2B: Use the Claude Code Marketplace Add the Ralph marketplace to Claude Code: @@ -69,6 +81,10 @@ Available skills after installation: - `/prd` - Generate Product Requirements Documents - `/ralph` - Convert PRDs to prd.json format +Marketplace installation only provides the `/prd` and `/ralph` skills. You +still need Step 1 so `ralph.sh`, `prompt.md` or `CLAUDE.md`, `prd.json`, and +`progress.txt` live inside your project instead of a plugin cache directory. + Skills are automatically invoked when you ask Claude to: - "create a prd", "write prd for", "plan this feature" - "convert this prd", "turn into ralph format", "create prd.json" @@ -95,17 +111,21 @@ Use the PRD skill to generate a detailed requirements document: Load the prd skill and create a PRD for [your feature description] ``` -Answer the clarifying questions. The skill saves output to `tasks/prd-[feature-name].md`. +Answer the clarifying questions. By default the skill writes the markdown PRD to +`tasks/prd-[feature-name].md`, but you can save that markdown wherever your +project keeps planning docs. ### 2. Convert PRD to Ralph format Use the Ralph skill to convert the markdown PRD to JSON: ``` -Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json +Load the ralph skill and convert your markdown PRD to `scripts/ralph/prd.json` +or the matching path where you installed `ralph.sh`. ``` This creates `prd.json` with user stories structured for autonomous execution. +Keep it in the same directory as `ralph.sh` so the runner can find it. ### 3. Run Ralph @@ -136,9 +156,9 @@ Ralph will: | `ralph.sh` | The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`) | | `prompt.md` | Prompt template for Amp | | `CLAUDE.md` | Prompt template for Claude Code | -| `prd.json` | User stories with `passes` status (the task list) | +| `prd.json` | User stories with `passes` status; saved next to `ralph.sh` | | `prd.json.example` | Example PRD format for reference | -| `progress.txt` | Append-only learnings for future iterations | +| `progress.txt` | Append-only learnings for future iterations; saved next to `ralph.sh` | | `skills/prd/` | Skill for generating PRDs (works with Amp and Claude Code) | | `skills/ralph/` | Skill for converting PRDs to JSON (works with Amp and Claude Code) | | `.claude-plugin/` | Plugin manifest for Claude Code marketplace discovery | diff --git a/skills/prd/SKILL.md b/skills/prd/SKILL.md index 3c2f7acf8..ea951edbf 100644 --- a/skills/prd/SKILL.md +++ b/skills/prd/SKILL.md @@ -15,7 +15,8 @@ Create detailed Product Requirements Documents that are clear, actionable, and s 1. Receive a feature description from the user 2. Ask 3-5 essential clarifying questions (with lettered options) 3. Generate a structured PRD based on answers -4. Save to `tasks/prd-[feature-name].md` +4. Save to the project's preferred planning-doc location (for example + `tasks/prd-[feature-name].md`) **Important:** Do NOT start implementing. Just create the PRD. @@ -135,7 +136,7 @@ The PRD reader may be a junior developer or AI agent. Therefore: ## Output - **Format:** Markdown (`.md`) -- **Location:** `tasks/` +- **Location:** Your project's planning-doc directory (for example `tasks/`) - **Filename:** `prd-[feature-name].md` (kebab-case) --- @@ -238,4 +239,4 @@ Before saving the PRD: - [ ] User stories are small and specific - [ ] Functional requirements are numbered and unambiguous - [ ] Non-goals section defines clear boundaries -- [ ] Saved to `tasks/prd-[feature-name].md` +- [ ] Saved to the project's chosen planning-doc path diff --git a/skills/ralph/SKILL.md b/skills/ralph/SKILL.md index e402ab8d3..c1c0d6285 100644 --- a/skills/ralph/SKILL.md +++ b/skills/ralph/SKILL.md @@ -12,7 +12,8 @@ Converts existing PRDs to the prd.json format that Ralph uses for autonomous exe ## The Job -Take a PRD (markdown file or text) and convert it to `prd.json` in your ralph directory. +Take a PRD (markdown file or text) and convert it to `prd.json` in the same +directory as `ralph.sh`. --- @@ -249,6 +250,7 @@ Add ability to mark tasks with different statuses. Before writing prd.json, verify: +- [ ] `prd.json` will be saved alongside `ralph.sh` - [ ] **Previous run archived** (if prd.json exists with different branchName, archive it first) - [ ] Each story is completable in one iteration (small enough) - [ ] Stories are ordered by dependency (schema to backend to UI) @@ -256,3 +258,7 @@ Before writing prd.json, verify: - [ ] UI stories have "Verify in browser using dev-browser skill" as criterion - [ ] Acceptance criteria are verifiable (not vague) - [ ] No story depends on a later story + +If the project uses `scripts/ralph/ralph.sh`, save to +`scripts/ralph/prd.json`. Do not write `prd.json` to the repo root or another +directory unless that is where `ralph.sh` lives.