Cursor CLI Support

.cursor/rules/ralph-prd.mdc

@@ -0,0 +1,138 @@
+# Ralph PRD Generator Rule
+
+This rule guides Cursor to generate Product Requirements Documents (PRDs) for the Ralph autonomous agent system.
+
+## Purpose
+
+Create detailed PRDs that are clear, actionable, and suitable for conversion to `prd.json` format for autonomous execution by Ralph.
+
+## The Job
+
+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`
+
+**Important:** Do NOT start implementing. Just create the PRD.
+
+## Step 1: Clarifying Questions
+
+Ask only critical questions where the initial prompt is ambiguous. Focus on:
+
+- **Problem/Goal:** What problem does this solve?
+- **Core Functionality:** What are the key actions?
+- **Scope/Boundaries:** What should it NOT do?
+- **Success Criteria:** How do we know it's done?
+
+### Format Questions Like This:
+
+```
+1. What is the primary goal of this feature?
+   A. Improve user onboarding experience
+   B. Increase user retention
+   C. Reduce support burden
+   D. Other: [please specify]
+
+2. Who is the target user?
+   A. New users only
+   B. Existing users only
+   C. All users
+   D. Admin users only
+
+3. What is the scope?
+   A. Minimal viable version
+   B. Full-featured implementation
+   C. Just the backend/API
+   D. Just the UI
+```
+
+This lets users respond with "1A, 2C, 3B" for quick iteration.
+
+## Step 2: PRD Structure
+
+Generate the PRD with these sections:
+
+### 1. Introduction/Overview
+Brief description of the feature and the problem it solves.
+
+### 2. Goals
+Specific, measurable objectives (bullet list).
+
+### 3. User Stories
+Each story needs:
+- **Title:** Short descriptive name
+- **Description:** "As a [user], I want [feature] so that [benefit]"
+- **Acceptance Criteria:** Verifiable checklist of what "done" means
+
+Each story should be small enough to implement in one focused session.
+
+**Format:**
+```markdown
+### US-001: [Title]
+**Description:** As a [user], I want [feature] so that [benefit].
+
+**Acceptance Criteria:**
+- [ ] Specific verifiable criterion
+- [ ] Another criterion
+- [ ] Typecheck/lint passes
+- [ ] **[UI stories only]** Verify in browser (use browser MCP tools if available, or mark for manual verification)
+```
+
+**Important:** 
+- Acceptance criteria must be verifiable, not vague. "Works correctly" is bad. "Button shows confirmation dialog before deleting" is good.
+- **For any story with UI changes:** Always include browser verification requirement. If browser MCP tools are available, use them. Otherwise, mark for manual verification or require automated tests.
+
+### 4. Functional Requirements
+Numbered list of specific functionalities:
+- "FR-1: The system must allow users to..."
+- "FR-2: When a user clicks X, the system must..."
+
+Be explicit and unambiguous.
+
+### 5. Non-Goals (Out of Scope)
+What this feature will NOT include. Critical for managing scope.
+
+### 6. Design Considerations (Optional)
+- UI/UX requirements
+- Link to mockups if available
+- Relevant existing components to reuse
+
+### 7. Technical Considerations (Optional)
+- Known constraints or dependencies
+- Integration points with existing systems
+- Performance requirements
+
+### 8. Success Metrics
+How will success be measured?
+- "Reduce time to complete X by 50%"
+- "Increase conversion rate by 10%"
+
+### 9. Open Questions
+Remaining questions or areas needing clarification.
+
+## Writing for Junior Developers
+
+The PRD reader may be a junior developer or AI agent. Therefore:
+
+- Be explicit and unambiguous
+- Avoid jargon or explain it
+- Provide enough detail to understand purpose and core logic
+- Number requirements for easy reference
+- Use concrete examples where helpful
+
+## Output
+
+- **Format:** Markdown (`.md`)
+- **Location:** `tasks/`
+- **Filename:** `prd-[feature-name].md` (kebab-case)
+
+## Checklist
+
+Before saving the PRD:
+
+- [ ] Asked clarifying questions with lettered options
+- [ ] Incorporated user's answers
+- [ ] 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`

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Ralph is an autonomous AI agent loop that runs Amp repeatedly until all PRD items are complete. Each iteration is a fresh Amp instance with clean context.
+Ralph is an autonomous AI agent loop that runs an AI worker (default: Amp, optional: Cursor CLI) repeatedly until all PRD items are complete. Each iteration is a fresh worker invocation with clean context.
 
 ## Commands
 
@@ -13,15 +13,22 @@ cd flowchart && npm run dev
 # Build the flowchart
 cd flowchart && npm run build
 
-# Run Ralph (from your project that has prd.json)
-./ralph.sh [max_iterations]
+# Run Ralph (from your project that has scripts/ralph/prd.json)
+./scripts/ralph/ralph.sh [max_iterations] [--worker amp|cursor] [--cursor-timeout SECONDS]
+
+# Convert PRD markdown to prd.json using Cursor CLI
+./scripts/ralph/cursor/convert-to-prd-json.sh tasks/prd-[feature-name].md [--model MODEL] [--out OUT_JSON]
 ```
 
 ## Key Files
 
-- `ralph.sh` - The bash loop that spawns fresh Amp instances
-- `prompt.md` - Instructions given to each Amp instance
-- `prd.json.example` - Example PRD format
+- `scripts/ralph/ralph.sh` - The bash loop (Amp + optional Cursor worker)
+- `scripts/ralph/prompt.md` - Instructions given to each Amp iteration
+- `scripts/ralph/cursor/prompt.cursor.md` - Instructions given to each Cursor iteration
+- `scripts/ralph/cursor/convert-to-prd-json.sh` - Convert PRD markdown → `scripts/ralph/prd.json` via Cursor CLI
+- `scripts/ralph/prd.json.example` - Example PRD format
+- `scripts/ralph/prd.json` - User stories with `passes` status (the task list)
+- `scripts/ralph/progress.txt` - Append-only learnings for future iterations
 - `flowchart/` - Interactive React Flow diagram explaining how Ralph works
 
 ## Flowchart
@@ -37,7 +44,8 @@ npm run dev
 
 ## Patterns
 
-- Each iteration spawns a fresh Amp instance with clean context
-- Memory persists via git history, `progress.txt`, and `prd.json`
+- Each iteration spawns a fresh worker invocation (Amp or Cursor) with clean context
+- Memory persists via git history, `scripts/ralph/progress.txt`, and `scripts/ralph/prd.json`
 - Stories should be small enough to complete in one context window
 - Always update AGENTS.md with discovered patterns for future iterations
+- Cursor-specific prompts are in `scripts/ralph/cursor/` subfolder

README.md

@@ -2,30 +2,32 @@
 
 ![Ralph](ralph.webp)
 
-Ralph is an autonomous AI agent loop that runs [Amp](https://ampcode.com) repeatedly until all PRD items are complete. Each iteration is a fresh Amp instance with clean context. Memory persists via git history, `progress.txt`, and `prd.json`.
+Ralph is an autonomous AI agent loop that runs an AI worker (default: [Amp](https://ampcode.com), optional: Cursor CLI) repeatedly until all PRD items are complete. Each iteration is a fresh worker invocation with clean context. Memory persists via git history, `scripts/ralph/progress.txt`, and `scripts/ralph/prd.json`.
 
 Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/).
 
 [Read my in-depth article on how I use Ralph](https://x.com/ryancarson/status/2008548371712135632)
 
 ## Prerequisites
 
-- [Amp CLI](https://ampcode.com) installed and authenticated
+- One worker installed:
+  - [Amp CLI](https://ampcode.com) installed and authenticated, and/or
+  - Cursor CLI (`cursor`) installed and authenticated
 - `jq` installed (`brew install jq` on macOS)
 - A git repository for your project
 
 ## Setup
 
 ### Option 1: Copy to your project
 
-Copy the ralph files into your project:
+Copy the Ralph templates into your project:
 
 ```bash
 # From your project root
 mkdir -p scripts/ralph
-cp /path/to/ralph/ralph.sh scripts/ralph/
-cp /path/to/ralph/prompt.md scripts/ralph/
+cp -R /path/to/ralph/scripts/ralph/* scripts/ralph/
 chmod +x scripts/ralph/ralph.sh
+chmod +x scripts/ralph/cursor/convert-to-prd-json.sh
 ```
 
 ### Option 2: Install skills globally
@@ -53,51 +55,68 @@ This enables automatic handoff when context fills up, allowing Ralph to handle l
 
 ### 1. Create a PRD
 
-Use the PRD skill to generate a detailed requirements document:
+If you use Amp skills, 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`.
 
+If you use Cursor in the IDE, you can also generate a PRD using the repo's Cursor rules (see `.cursor/rules/`).
+
 ### 2. Convert PRD to Ralph format
 
-Use the Ralph skill to convert the markdown PRD to JSON:
+If you use Amp skills, 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
 ```
 
-This creates `prd.json` with user stories structured for autonomous execution.
+Alternatively, you can convert PRD markdown to `scripts/ralph/prd.json` using the Cursor helper script:
+
+```bash
+./scripts/ralph/cursor/convert-to-prd-json.sh tasks/prd-[feature-name].md
+```
+
+This creates `scripts/ralph/prd.json` with user stories structured for autonomous execution.
 
 ### 3. Run Ralph
 
 ```bash
-./scripts/ralph/ralph.sh [max_iterations]
+./scripts/ralph/ralph.sh [max_iterations] [--worker amp|cursor] [--cursor-timeout SECONDS]
 ```
 
 Default is 10 iterations.
 
-Ralph will:
-1. Create a feature branch (from PRD `branchName`)
-2. Pick the highest priority story where `passes: false`
-3. Implement that single story
-4. Run quality checks (typecheck, tests)
-5. Commit if checks pass
-6. Update `prd.json` to mark story as `passes: true`
-7. Append learnings to `progress.txt`
-8. Repeat until all stories pass or max iterations reached
+The runner loop will invoke the selected worker repeatedly. The worker prompt instructs it to:
+- Read `scripts/ralph/prd.json` and `scripts/ralph/progress.txt`
+- Implement one story per iteration, run checks, commit, and update `passes: true`
+- Stop by outputting `<promise>COMPLETE</promise>` when all stories pass
+
+Examples:
+
+```bash
+# Default worker is Amp
+./scripts/ralph/ralph.sh 10
+
+# Run with Cursor CLI (with a per-iteration timeout)
+./scripts/ralph/ralph.sh 10 --worker cursor --cursor-timeout 1800
+```
+
+Note: `--cursor-timeout` only applies if a `timeout` binary is available on your PATH. If it isn't, Ralph will run Cursor without a hard timeout.
 
 ## Key Files
 
 | File | Purpose |
 |------|---------|
-| `ralph.sh` | The bash loop that spawns fresh Amp instances |
-| `prompt.md` | Instructions given to each Amp instance |
-| `prd.json` | User stories with `passes` status (the task list) |
-| `prd.json.example` | Example PRD format for reference |
-| `progress.txt` | Append-only learnings for future iterations |
+| `scripts/ralph/ralph.sh` | The bash loop that spawns fresh worker invocations |
+| `scripts/ralph/prompt.md` | Instructions given to each Amp iteration |
+| `scripts/ralph/cursor/prompt.cursor.md` | Instructions given to each Cursor iteration |
+| `scripts/ralph/cursor/convert-to-prd-json.sh` | Convert PRD markdown → `scripts/ralph/prd.json` via Cursor CLI |
+| `scripts/ralph/prd.json` | User stories with `passes` status (the task list) |
+| `scripts/ralph/prd.json.example` | Example PRD format for reference |
+| `scripts/ralph/progress.txt` | Append-only learnings for future iterations |
 | `skills/prd/` | Skill for generating PRDs |
 | `skills/ralph/` | Skill for converting PRDs to JSON |
 | `flowchart/` | Interactive visualization of how Ralph works |
@@ -120,10 +139,10 @@ npm run dev
 
 ### Each Iteration = Fresh Context
 
-Each iteration spawns a **new Amp instance** with clean context. The only memory between iterations is:
+Each iteration spawns a **new worker invocation** (Amp or Cursor) with clean context. The only memory between iterations is:
 - Git history (commits from previous iterations)
-- `progress.txt` (learnings and context)
-- `prd.json` (which stories are done)
+- `scripts/ralph/progress.txt` (learnings and context)
+- `scripts/ralph/prd.json` (which stories are done)
 
 ### Small Tasks
 
@@ -170,25 +189,29 @@ Check current state:
 
 ```bash
 # See which stories are done
-cat prd.json | jq '.userStories[] | {id, title, passes}'
+cat scripts/ralph/prd.json | jq '.userStories[] | {id, title, passes}'
 
 # See learnings from previous iterations
-cat progress.txt
+cat scripts/ralph/progress.txt
 
 # Check git history
 git log --oneline -10
 ```
 
-## Customizing prompt.md
+## Customizing prompts
 
-Edit `prompt.md` to customize Ralph's behavior for your project:
+Edit the worker prompt(s) to customize Ralph's behavior for your project:
 - Add project-specific quality check commands
 - Include codebase conventions
 - Add common gotchas for your stack
 
+Worker prompt locations:
+- Amp: `scripts/ralph/prompt.md`
+- Cursor: `scripts/ralph/cursor/prompt.cursor.md`
+
 ## Archiving
 
-Ralph automatically archives previous runs when you start a new feature (different `branchName`). Archives are saved to `archive/YYYY-MM-DD-feature-name/`.
+Ralph automatically archives previous runs when you start a new feature (different `branchName`). Archives are saved to `scripts/ralph/archive/YYYY-MM-DD-feature-name/`.
 
 ## References