prd-gen 0.1.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "prd-gen",
+  "version": "0.1.0",
+  "description": "Single-story-at-a-time PRD review tool",
+  "type": "module",
+  "bin": {
+    "prd-gen": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "prd",
+    "cli",
+    "review"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0"
+  }
+}

package/prd.json

@@ -0,0 +1,187 @@
+{
+  "project": "prd-gen",
+  "branchName": "ralph/prd-gen-cli",
+  "description": "prd-gen CLI Tool - Single-story-at-a-time PRD review with priority assignment, editing, add/delete; changes saved to prd.json",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Project scaffold and npm package setup",
+      "description": "As a developer, I need a runnable npm package so that users can install and run prd-gen via npx.",
+      "acceptanceCriteria": [
+        "package.json with name 'prd-gen', bin entry pointing to cli entry point",
+        "Entry point file exists and is executable",
+        "Running `node index.js` (or equivalent) does not throw on startup",
+        "Typecheck passes"
+      ],
+      "priority": 1,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-002",
+      "title": "HTTP server that loads prd.json and serves frontend",
+      "description": "As a developer, I need a native http server that reads prd.json and serves a static HTML page so that the browser UI can display stories.",
+      "acceptanceCriteria": [
+        "Server starts on a local port using Node's native `http` module (no Express)",
+        "GET / serves an HTML page",
+        "GET /api/stories returns JSON array from ./prd.json (empty array if file missing)",
+        "POST /api/stories accepts JSON body and writes to ./prd.json",
+        "Browser is opened automatically on start using `open` package or child_process",
+        "Ctrl+C shuts down gracefully",
+        "Typecheck passes"
+      ],
+      "priority": 2,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-003",
+      "title": "Basic story card UI with title, description and story counter",
+      "description": "As a user, I want to see the current story's title and description in a centered card so that I can review it.",
+      "acceptanceCriteria": [
+        "Page shows a centered container (~800px wide) with a soft shadow on white (#FFFFFF) background",
+        "Current story title shown in ~48px bold black (#000)",
+        "Current story description shown in ~20px #333, multiline",
+        "Top-right corner shows 'Story X / Y' in grey small text",
+        "If prd.json is empty or missing, page shows 'No stories to review.' with an Add button",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 3,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-004",
+      "title": "Priority badge and 1–10 priority selector buttons",
+      "description": "As a user, I want to see the current priority and set a new one by clicking numbered buttons so that I can assign priority quickly.",
+      "acceptanceCriteria": [
+        "Priority badge (#FF2D55 circle) shown on the story card displaying current priority (1–10) or empty if unset",
+        "10 round buttons labelled 1–10 shown at the bottom of the card",
+        "Selected priority button is highlighted in #FF2D55; others are grey",
+        "Hovering a button turns it #FF2D55",
+        "Clicking a button sets that priority and marks the form as dirty",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 4,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-005",
+      "title": "Inline editing for title and description",
+      "description": "As a user, I want to click the title or description to edit them inline so that I can correct or improve story text.",
+      "acceptanceCriteria": [
+        "Clicking the title makes it an editable input/contenteditable field",
+        "Clicking the description makes it an editable textarea/contenteditable field",
+        "Editing either field marks the form as dirty",
+        "Pressing Esc while a field is focused blurs it without reverting changes",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 5,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-006",
+      "title": "Save button and Next story navigation",
+      "description": "As a user, I want a Save button when changes are unsaved and a Next story button when clean so that I can progress through the review.",
+      "acceptanceCriteria": [
+        "When form is clean, bottom-center shows a grey 'Next story' button",
+        "When form is dirty, bottom-center shows a red (#FF2D55 with white text) 'Save' button",
+        "Clicking Save POSTs changes to /api/stories and writes prd.json; shows thin red spinner during write",
+        "After save, button returns to 'Next story'",
+        "Clicking 'Next story' advances to the next story",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 6,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-007",
+      "title": "Fanned story stack behind current card",
+      "description": "As a user, I want to see the remaining stories stacked behind the current card so that I can get a sense of how many are left.",
+      "acceptanceCriteria": [
+        "Stories behind current card are shown as fanned cards",
+        "1–5 remaining: all cards visible in the fan",
+        "6–15 remaining: top 5 cards visible + '+N' label",
+        "16+ remaining: top 3 cards visible + '+N' label",
+        "Fan shrinks as Next is clicked (card count decreases)",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 7,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-008",
+      "title": "Add new story button",
+      "description": "As a user, I want to add a new story before the current one so that I can capture ideas during review.",
+      "acceptanceCriteria": [
+        "A '+' icon appears at the top-left of the card on hover",
+        "Clicking '+' inserts a new blank story immediately before the current story with defaults: title 'New Item', description 'Describe here…', priority null",
+        "After save, view returns to the original story position",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 8,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-009",
+      "title": "Delete story with confirmation",
+      "description": "As a user, I want to delete a story with a confirmation prompt so that I don't accidentally remove stories.",
+      "acceptanceCriteria": [
+        "A red trash icon appears at the top-right of the card on hover",
+        "Clicking trash shows a confirmation dialog with text 'Delete this story? No undo.'",
+        "Confirming deletes the story and saves prd.json immediately",
+        "Cancelling closes the dialog without changes",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 9,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-010",
+      "title": "Keyboard shortcuts",
+      "description": "As a power user, I want keyboard shortcuts for all actions so that I can review stories without touching the mouse.",
+      "acceptanceCriteria": [
+        "Keys 1–9 set priority 1–9 globally (even when not editing text)",
+        "Key 0 sets priority 10 globally",
+        "Enter or Space triggers Save when dirty, or Next story when clean",
+        "Backspace or Delete opens the delete confirmation dialog",
+        "N inserts a new story (same as clicking '+')",
+        "Esc closes any open confirmation dialog, or blurs the currently focused edit field",
+        "Priority keys are ignored when a text input/textarea is focused",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 10,
+      "passes": true,
+      "notes": ""
+    },
+    {
+      "id": "US-011",
+      "title": "End-of-review summary screen",
+      "description": "As a user, I want to see a summary after reviewing all stories so that I know the session is complete.",
+      "acceptanceCriteria": [
+        "After the last story, 'Next story' button becomes a dimmed 'Finish' button",
+        "Clicking Finish shows a summary screen with: 'Good job! You've reviewed all stories.' and counts for Reviewed, Created (new), Deleted",
+        "An 'Add new story' button is still visible on the summary screen and appends to the end",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 11,
+      "passes": true,
+      "notes": ""
+    }
+  ]
+}

package/prd.md

@@ -0,0 +1,101 @@
+**prd-gen CLI Tool – Final Comprehensive MVP Specification**
+
+**Name**  
+prd-gen
+
+**Type**  
+Node.js CLI, published to npm
+
+**Command**  
+`prd-gen` or `npx prd-gen` (run in directory containing `prd.json`)
+
+**Purpose**  
+Single-story-at-a-time review, priority assignment, title/description editing, add/delete; changes saved to `./prd.json`
+
+**Input file** (`prd.json`)  
+Array of objects:
+```json
+[
+  {
+    "id": "story-001",
+    "title": "User login flow",
+    "description": "Implement OAuth2 …",
+    "priority": 5
+  }
+]
+```
+
+**Startup**  
+- Load `./prd.json`  
+- Start minimal HTTP server  
+- Open browser to localhost  
+- Empty/missing file → “No stories to review.” + Add button
+
+**Visual style**  
+- #FFFFFF background  
+- #000 title, #333 body, #666 secondary  
+- Accent: #FF2D55 only (priority, Save, delete, hover/selected)  
+- Centered container (~800px), soft shadow  
+- Fanned story stack behind current:  
+  - 1–5 → all visible  
+  - 6–15 → top 5 + “+N”  
+  - 16+ → top 3 + “+N”  
+  - Stack shrinks on Next  
+- Top-right: “Story X / Y” (grey, small)
+
+**Story view**  
+- Title (~48px bold, editable)  
+- Description (~20px #333, multiline editable)  
+- Priority badge (#FF2D55 circle, shows 1–10 or empty)  
+- Bottom: 10 round buttons 1–10 (grey → #FF2D55 hover/selected)  
+- Bottom center:  
+  - “Next story” (grey) when clean  
+  - “Save” (#FF2D55 white text) when dirty  
+- Top-left (hover): “+” → Add new story (inserts before current)  
+- Top-right (hover): red trash → confirm delete
+
+**Blank story defaults**  
+title: "New Item"  
+description: "Describe here…"  
+priority: null
+
+**Save**  
+Explicit “Save” click only  
+Thin red spinner during write  
+No auto-save, no undo
+
+**Add new story**  
+Inserts immediately before current  
+After save → returns to original position
+
+**Delete**  
+Confirm dialog “Delete this story? No undo.”
+
+**End of review**  
+After last → dimmed “Finish”  
+Click → summary:  
+“Good job! You've reviewed all stories.  
+Reviewed: X  
+Created: Y new  
+Deleted: Z”  
+Add new story button still visible (adds to end)
+
+**Keyboard shortcuts**  
+- 1–9 → priority 1–9  
+- 0 → priority 10  
+- Enter / Space → Next story or Save  
+- Backspace / Delete → open delete confirm  
+- N → Add new story  
+- Esc → close confirm or blur edit  
+Priority keys global; others ignored when editing text
+
+**Tech**  
+- Native `http` module (no Express)  
+- Serve static HTML/CSS/JS + JSON API  
+- Manual body parsing  
+- `fs` write on save  
+- `open` package or `child_process` for browser  
+- Vanilla frontend (or Alpine/htmx)
+
+**Exit**  
+Ctrl+C → graceful shutdown (save pending)

package/progress.txt

@@ -0,0 +1,118 @@
+## 2026-02-27 - US-011
+- What was implemented: End-of-review summary screen. Added `showSummary`, `createdCount`, `deletedCount` state variables. Last story renders a dimmed 'Finish' button (`.finish-btn`). Clicking Finish sets `showSummary = true` and renders a summary card showing "Good job! You've reviewed all stories." with Reviewed/Created/Deleted stat counters and an "Add new story" button. `addStoryAtEnd()` appends to end and exits summary view. `createdCount` incremented in all add functions; `deletedCount` in `deleteStory()`. Keyboard handler returns early when `showSummary` is true.
+- Files changed: src/index.ts (CSS: `.finish-btn`, `.summary-state`, `.summary-check`, `.summary-heading`, `.summary-subheading`, `.summary-stats`, `.summary-stat-value`, `.summary-stat-label`; state: `showSummary`, `createdCount`, `deletedCount`; render(): summary branch before story rendering; actionHtml: isLastStory detection; actionBtn click: shows summary on last story; addStory/addStoryBefore: increment createdCount; new addStoryAtEnd(); deleteStory: increment deletedCount; handleKeyDown: guard against showSummary)
+- **Learnings for future iterations:**
+  - Place the summary screen check early in render() (after empty-state, before story rendering) so it short-circuits cleanly
+  - `isLastStory` local var in render() drives both the Finish button style (`.finish-btn`) and the Finish click handler to set `showSummary = true`
+  - Summary uses same `.card-stack` + `.card` wrapper as normal view for consistent layout/centering
+  - `addStoryAtEnd()` must reset `showSummary = false` before calling `saveAndRender()` so the new story card renders instead of the summary
+  - Guard keyboard shortcuts with `|| showSummary` check so number keys don't act on a nonexistent `stories[currentIndex]` from summary view
+---
+
+## 2026-02-27 - US-010
+- What was implemented: Global `keydown` event listener added once inside the IIFE (via `document.addEventListener`). `isEditingText()` helper checks `document.activeElement` tag/contenteditable to block shortcuts while editing. Shortcuts: 1–9 set priority; 0 sets priority 10; Enter/Space clicks actionBtn (save or next); Backspace/Delete opens delete confirm; N calls addStoryBefore(); Esc closes dialog or blurs active element. All shortcuts except Esc are no-ops when `isEditingText()` returns true or `saving` is true.
+- Files changed: src/index.ts (added `isEditingText()` + `handleKeyDown()` functions and `document.addEventListener('keydown', handleKeyDown)` inside IIFE)
+- **Learnings for future iterations:**
+  - Add global keyboard handler once with `document.addEventListener('keydown', fn)` inside the IIFE — closure gives access to all state variables without re-registering on each render
+  - `isEditingText()` checks `document.activeElement.tagName` (input/textarea) AND `getAttribute('contenteditable') === 'true'` to cover both cases
+  - Guard action shortcuts (Enter, Space, Backspace, N) with `!saving` to avoid double-firing during a fetch
+  - `e.preventDefault()` on Space/Enter prevents page scroll or form submission
+  - Esc is the only shortcut that works even when editing text — it closes the dialog first, then blurs the active field if no dialog is open
+---
+
+## 2026-02-27 - US-009
+- What was implemented: Red trash icon button at top-right corner of card (position: absolute; top: -14px; right: -14px; 32px circle), hidden by default, shown on `.card:hover`. Clicking shows a fixed-overlay confirmation dialog with 'Delete this story? No undo.' text and Delete/Cancel buttons. Confirming removes the story at `currentIndex`, adjusts index if at end, then saves via `saveAndRender()`. Cancelling closes dialog. `showDeleteConfirm` boolean state variable controls visibility.
+- Files changed: src/index.ts (CSS: `.card-delete-btn`, `.card:hover .card-delete-btn`, `.card-delete-btn:hover`, `.confirm-overlay`, `.confirm-dialog`, `.confirm-dialog p`, `.confirm-actions`, `.confirm-delete-btn`, `.confirm-cancel-btn`; state: `showDeleteConfirm`; HTML: deleteStoryBtn button with SVG icon inside .card; conditional overlay HTML; JS: deleteStoryBtn/confirmDeleteBtn/confirmCancelBtn event listeners; `deleteStory()` function)
+- **Learnings for future iterations:**
+  - Confirmation dialog is a fixed overlay (position: fixed; inset: 0; z-index: 100) — works regardless of DOM position
+  - Reset `showDeleteConfirm = false` BEFORE calling `deleteStory()` or `render()` to avoid the dialog re-appearing after re-render
+  - After splicing a story, clamp `currentIndex` to `stories.length - 1` if it's now out of bounds
+  - The trash button uses an inline SVG for the icon — style via `stroke="currentColor"` so CSS color applies
+  - Conditional overlay template: `\${showDeleteConfirm ? \`...\` : ''}` within the outer TypeScript template literal
+---
+
+## 2026-02-27 - US-008
+- What was implemented: '+' icon button at the top-left corner of the card (absolute top:-14px left:-14px, 32px circle), hidden by default, shown on `.card:hover`. Clicking it inserts a new blank story (title 'New Item', description 'Describe here…', priority null) immediately before the current story, then increments `currentIndex` so the view returns to the original story position after save. Empty-state `addStory()` left unchanged; new `addStoryBefore()` function handles card-level insertion.
+- Files changed: src/index.ts (CSS: `.card-add-btn`, `.card:hover .card-add-btn`, `.card-add-btn:hover`; HTML: button#addStoryBtn inside .card; JS: addStoryBtn event listener in render(); addStoryBefore() function)
+- **Learnings for future iterations:**
+  - To show an element only on parent hover: set `opacity: 0` on child and `opacity: 1` on `.parent:hover .child`
+  - Place the '+' button at `position: absolute; top: -14px; left: -14px; z-index: 10` so it overlaps the card corner without conflicting with the priority badge (top: 20px; left: 24px)
+  - Keep `addStory()` (empty state) and `addStoryBefore()` (card button) separate — the empty-state case must keep currentIndex at 0, while the card case increments currentIndex to return to original position
+  - `currentIndex++` must happen BEFORE `saveAndRender()` so the post-save render() shows the original story
+---
+
+## 2026-02-27 - US-007
+- What was implemented: Fanned ghost card stack behind the current card. Remaining stories after current index are counted; 1–5 shows all as ghost cards, 6–15 shows 5 + overflow badge, 16+ shows 3 + overflow badge. Ghost cards rendered as absolutely-positioned divs inside a `.card-stack` wrapper with rotation transforms (transform-origin: center 90%) — furthest ghost is most rotated. Overflow badge shows "+N" on the furthest ghost card.
+- Files changed: src/index.ts (CSS: `.card-stack`, `.card-ghost`, `.stack-overflow-badge`; removed `max-width` from `.card` and moved to `.card-stack`; render() builds ghostHtml loop and wraps main card in `.card-stack`)
+- **Learnings for future iterations:**
+  - Ghost cards use `position: absolute; top:0; left:0; right:0; bottom:0` within `.card-stack` — they size automatically to match the main card
+  - `transform-origin: center 90%` makes cards rotate around a point near the bottom, causing upper portions to fan out from behind the main card
+  - Ghost cards rendered first in DOM (lower z-index by natural stacking) so main card (rendered last, no explicit z-index needed) appears on top
+  - The `rotationSets` object maps `visibleGhosts` count → array of per-card rotation degrees (largest first = furthest ghost)
+  - Moving `max-width: 800px` from `.card` to `.card-stack` ensures ghost cards use the same width constraint
+---
+
+## 2026-02-27 - US-006
+- What was implemented: Save button (red #FF2D55) shown when dirty; grey 'Next story' button when clean. Clicking Save POSTs stories to /api/stories, shows a thin red spinner during write, then resets dirty and re-renders. Clicking Next story advances currentIndex by 1 (clamped at end). saveAndRender() also resets dirty.
+- Files changed: src/index.ts (CSS for action-area/save-btn/next-btn/spinner-ring/@keyframes spin; `saving` state variable; actionHtml in render(); action button event listeners; saveAndRender updated)
+- **Learnings for future iterations:**
+  - `saving` state variable added alongside `dirty` — set true before POST, false in .then/.catch
+  - Show spinner by rendering a `.spinner-ring` span in place of the button (CSS border-top animation)
+  - Action button is either save-btn or next-btn depending on `dirty`; attach appropriate handler after innerHTML is set
+  - saveAndRender() (used by addStory) should also reset dirty=false after successful save
+  - When dirty=false and Next is clicked, currentIndex advances; no need to reset dirty since it's already false
+---
+
+## 2026-02-27 - US-005
+- What was implemented: Inline editing for title and description using `contenteditable="true"` on both divs. Title uses `textContent` for updates; description uses `innerText` to preserve newlines. Input events update `stories[currentIndex]` and set `dirty = true`. Esc key blurs the focused field. CSS adds cursor:text, hover/focus background highlights and a red outline on focus.
+- Files changed: src/index.ts (CSS additions + contenteditable attrs + event listeners in render())
+- **Learnings for future iterations:**
+  - Use `contenteditable="true"` on existing divs — no swap to input/textarea needed
+  - Use `element.textContent` for single-line fields (title); use `element.innerText` for multiline (description) to preserve newlines
+  - Add `spellcheck="false"` on title field to avoid red squiggles under story titles
+  - `input` event fires on every keystroke for contenteditable; `keydown` for Esc handling
+  - `escapeHtml()` still used for initial innerHTML render; safe because browser interprets entities as plain text in contenteditable
+  - When render() is called (e.g. after priority change), contenteditable fields reset from stories array — dirty text changes are safe because `input` event syncs to stories before any click event fires
+---
+
+## Codebase Patterns
+- ESM project: `"type": "module"` in package.json — use `import`/`export`, not `require`/`module.exports`
+- TypeScript with NodeNext module resolution — file extensions matter for imports
+- Use `fileURLToPath(import.meta.url)` + `path.dirname` to get `__dirname` equivalent in ESM
+- PRD data lives in `prd.json` at `process.cwd()` with shape `{ userStories: [...] }`
+- No external runtime dependencies (no Express, no open package) — use Node native modules
+
+- HTML UI is embedded as a template literal in `HTML_PAGE` const in src/index.ts — all frontend code lives inline there
+- Use `escapeHtml()` in JS to prevent XSS when rendering story content into innerHTML
+
+---
+
+## 2026-02-27 - US-002
+- What was implemented: Native HTTP server using Node's `http` module. Serves GET / (HTML page), GET /api/stories (reads prd.json), POST /api/stories (writes prd.json). Opens browser via child_process exec on start. Handles SIGINT for graceful shutdown.
+- Files changed: src/index.ts (full rewrite)
+- **Learnings for future iterations:**
+  - prd.json shape: `{ userStories: [...] }` — read/write via `data.userStories`, not root array
+  - Browser open: platform-specific commands via `process.platform` (darwin=open, win32=start, linux=xdg-open)
+  - POST body: collect chunks with `req.on('data')`, parse in `req.on('end')`
+  - TypeScript: type `chunk` as `Buffer` in data event to satisfy strict mode
+---
+
+## 2026-02-27 - US-003
+- What was implemented: Full story card UI replacing the placeholder HTML. Centered 800px card with soft shadow, 48px bold title, 20px description, Story X/Y counter top-right. Empty state shows "No stories to review." with Add button.
+- Files changed: src/index.ts (HTML_PAGE replaced with full SPA)
+- **Learnings for future iterations:**
+  - All frontend code is inline in the `HTML_PAGE` template literal — use template literal escaping carefully (backtick → \\\`, dollar+brace → no conflict if inside JS string literals)
+  - The JS in HTML uses IIFE pattern and fetches `/api/stories` on load; `stories` array and `currentIndex` are module-level state
+  - `escapeHtml()` helper is defined in JS to prevent XSS
+  - The `addStory()` function inserts at `currentIndex` position and calls `saveAndRender()`
+---
+
+## 2026-02-27 - US-004
+- What was implemented: Priority badge (#FF2D55 circle) on card top-left showing current priority or empty grey circle if unset. 10 round priority buttons (1–10) at card bottom; selected button highlighted in #FF2D55, hover also turns #FF2D55. Clicking a button updates `stories[currentIndex].priority` and sets `dirty = true`, then re-renders.
+- Files changed: src/index.ts (CSS additions + render function update + dirty state variable)
+- **Learnings for future iterations:**
+  - `dirty` state variable added at IIFE module level alongside `stories` and `currentIndex`
+  - After setting innerHTML, re-attach event listeners by querying the newly-created DOM elements
+  - Inner JS template literals inside `HTML_PAGE` TypeScript template literal: escape backticks as `\`` and template expressions as `\${}`
+  - Priority buttons use `data-priority` attribute; read with `btn.getAttribute('data-priority')`
+---

package/scripts/ralph/CLAUDE.md

@@ -0,0 +1,104 @@
+# Ralph Agent Instructions
+
+You are an autonomous coding agent working on a software project.
+
+## Your Task
+
+1. Read the PRD at `prd.json` (in the same directory as this file)
+2. Read the progress log at `progress.txt` (check Codebase Patterns section first)
+3. Check you're on the correct branch from PRD `branchName`. If not, check it out or create from main.
+4. Pick the **highest priority** user story where `passes: false`
+5. Implement that single user story
+6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)
+7. Update CLAUDE.md files if you discover reusable patterns (see below)
+8. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]`
+9. Update the PRD to set `passes: true` for the completed story
+10. Append your progress to `progress.txt`
+
+## Progress Report Format
+
+APPEND to progress.txt (never replace, always append):
+```
+## [Date/Time] - [Story ID]
+- What was implemented
+- Files changed
+- **Learnings for future iterations:**
+  - Patterns discovered (e.g., "this codebase uses X for Y")
+  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
+  - Useful context (e.g., "the evaluation panel is in component X")
+---
+```
+
+The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
+
+## Consolidate Patterns
+
+If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings:
+
+```
+## Codebase Patterns
+- Example: Use `sql<number>` template for aggregations
+- Example: Always use `IF NOT EXISTS` for migrations
+- Example: Export types from actions.ts for UI components
+```
+
+Only add patterns that are **general and reusable**, not story-specific details.
+
+## Update CLAUDE.md Files
+
+Before committing, check if any edited files have learnings worth preserving in nearby CLAUDE.md files:
+
+1. **Identify directories with edited files** - Look at which directories you modified
+2. **Check for existing CLAUDE.md** - Look for CLAUDE.md in those directories or parent directories
+3. **Add valuable learnings** - If you discovered something future developers/agents should know:
+   - API patterns or conventions specific to that module
+   - Gotchas or non-obvious requirements
+   - Dependencies between files
+   - Testing approaches for that area
+   - Configuration or environment requirements
+
+**Examples of good CLAUDE.md additions:**
+- "When modifying X, also update Y to keep them in sync"
+- "This module uses pattern Z for all API calls"
+- "Tests require the dev server running on PORT 3000"
+- "Field names must match the template exactly"
+
+**Do NOT add:**
+- Story-specific implementation details
+- Temporary debugging notes
+- Information already in progress.txt
+
+Only update CLAUDE.md if you have **genuinely reusable knowledge** that would help future work in that directory.
+
+## Quality Requirements
+
+- ALL commits must pass your project's quality checks (typecheck, lint, test)
+- Do NOT commit broken code
+- Keep changes focused and minimal
+- Follow existing code patterns
+
+## Browser Testing (If Available)
+
+For any story that changes UI, verify it works in the browser if you have browser testing tools configured (e.g., via MCP):
+
+1. Navigate to the relevant page
+2. Verify the UI changes work as expected
+3. Take a screenshot if helpful for the progress log
+
+If no browser tools are available, note in your progress report that manual browser verification is needed.
+
+## Stop Condition
+
+After completing a user story, check if ALL stories have `passes: true`.
+
+If ALL stories are complete and passing, reply with:
+<promise>COMPLETE</promise>
+
+If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story).
+
+## Important
+
+- Work on ONE story per iteration
+- Commit frequently
+- Keep CI green
+- Read the Codebase Patterns section in progress.txt before starting

package/scripts/ralph/progress.txt

@@ -0,0 +1,20 @@
+## Codebase Patterns
+- Project is a Node.js/TypeScript CLI tool using ESM modules (`"type": "module"`)
+- Build: `npm run build` (tsc), Typecheck: `npm run typecheck`, Dev: `npx tsx src/index.ts`
+- Source files in `src/`, compiled output to `dist/`
+- tsconfig uses `"module": "NodeNext"`, `"moduleResolution": "NodeNext"`
+
+# Ralph Progress Log
+Started: Fri Feb 27 21:15:29 CST 2026
+---
+
+## 2026-02-27 - US-001
+- Implemented project scaffold: package.json with prd-gen bin entry, tsconfig.json, src/index.ts entry point
+- Initialized git repo and created branch ralph/prd-gen-cli
+- Files changed: package.json, tsconfig.json, src/index.ts, .gitignore, package-lock.json
+- **Learnings for future iterations:**
+  - Project uses ESM (`"type": "module"`), so imports need `.js` extension in TypeScript source
+  - TypeScript module setting is `NodeNext` which requires explicit file extensions
+  - Dev runner is `tsx` (in devDependencies), use `npx tsx src/index.ts` for running during dev
+  - Typecheck with `npm run typecheck` (tsc --noEmit)
+---