docs: clarify Ralph runner setup and output paths

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 |

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

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,10 +250,15 @@ 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)
 - [ ] Every story has "Typecheck passes" as criterion
 - [ ] 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.