agentic-loop 3.23.0 → 3.27.1

package/.claude/commands/color.md

@@ -0,0 +1,74 @@
+---
+description: Pick the terminal background color Ralph uses to distinguish its terminal from Claude Code.
+---
+
+# Terminal Color
+
+The user wants to change Ralph's terminal background tint - the color applied during `npx agentic-loop run` to visually distinguish Ralph's terminal from Claude Code.
+
+> **Note:** This only works in macOS Terminal.app. On other terminals (iTerm2, VS Code, Linux), Ralph skips tinting automatically.
+
+## Step 1: Show Current Color
+
+Read `.ralph/config.json` and check for `terminalTint`. Show the current setting:
+- If set: "Current tint: `{value}`"
+- If not set: "Current tint: `#1a2e2e` (default dark teal)"
+
+## Step 2: Ask Color Preference
+
+Use AskUserQuestion:
+
+**Question:** "What color should Ralph's terminal background be?"
+**Header:** "Tint color"
+**Options:**
+- **Dark Teal (default)** - "`#1a2e2e` - subtle blue-green, easy on the eyes"
+- **Dark Purple** - "`#1a1a2e` - cool and distinct from standard dark themes"
+- **Dark Red** - "`#2e1a1a` - warm undertone, clearly different"
+- **Off** - "Disable terminal tinting entirely"
+
+If the user selects "Other", ask them to provide a hex color (e.g., `#2e2e1a`).
+
+## Step 3: Validate (if custom hex)
+
+If the user provided a custom hex:
+- Must match `#` followed by exactly 6 hex characters (`/^#[0-9a-fA-F]{6}$/`)
+- If invalid, say "That doesn't look like a valid hex color (e.g., `#1a2e2e`). Try again." and re-ask.
+
+## Step 4: Save to Config
+
+Read `.ralph/config.json`, set the `terminalTint` field, and write it back.
+
+- **If a color was chosen:** Set `"terminalTint": "#xxxxxx"`
+- **If "Off" was chosen:** Set `"terminalTint": "off"`
+
+Use jq to update:
+```bash
+jq --arg color "THE_HEX_VALUE" '.terminalTint = $color' .ralph/config.json > .ralph/config.json.tmp && mv .ralph/config.json.tmp .ralph/config.json
+```
+
+## Step 5: Preview (macOS Terminal.app only)
+
+If running in Terminal.app, apply the color immediately so the user can see it:
+
+```bash
+# Apply preview (will be restored when Claude session ends)
+osascript -e 'tell application "Terminal" to set background color of front window to {R, G, B}' 2>/dev/null
+```
+
+Where R, G, B are the hex values converted to 16-bit (multiply each 8-bit value by 257).
+
+If "Off" was chosen, skip the preview.
+
+## Step 6: Confirm
+
+Say:
+
+"Done! Ralph will use `#xxxxxx` as the terminal tint.
+
+Next time you run `npx agentic-loop run`, the terminal background will change to this color. It restores to your original background when the loop ends.
+
+Run `/color` again anytime to change it."
+
+If "Off" was chosen, say:
+
+"Done! Terminal tinting is now disabled. Ralph will run without changing your terminal background."

package/.claude/commands/tab-rename.md

@@ -0,0 +1,76 @@
+---
+description: Rename the current terminal tab so you can tell your Claude Code tabs apart.
+---
+
+# Tab Rename
+
+The user wants to rename the current terminal tab. This is useful when you have multiple Claude Code sessions open and every tab just shows "...skip-permissions".
+
+## Step 1: Determine the Tab Name
+
+Check if the user provided an argument: `$ARGUMENTS`
+
+- **If provided:** Use it as the tab name (e.g., `/tab-rename my-api` → tab name is "my-api").
+- **If not provided:** Auto-detect a sensible name from the project. Read the `name` field from `package.json` if it exists, or use the current directory's basename. Then ask the user to confirm or customize:
+
+Use AskUserQuestion:
+
+**Question:** "What should this tab be called?"
+**Header:** "Tab name"
+**Options:**
+- **{detected_name}** - "Auto-detected from the project"
+- **Claude: {detected_name}** - "Prefixed to distinguish from Ralph's terminal"
+
+If the user selects "Other", use their custom text as the tab name.
+
+## Step 2: Set the Tab Title
+
+Use `$TERM_PROGRAM` (via Bash: `echo $TERM_PROGRAM`) to detect the terminal, then apply the right method. **Important:** Escape any double quotes in the tab name before embedding in AppleScript strings.
+
+### iTerm2 (`TERM_PROGRAM=iTerm.app`)
+
+Use iTerm2's proprietary escape sequence — this is the most reliable method:
+
+```bash
+printf '\033]1337;SetUserVar=tab_title=%s\007' "$(echo -n 'TAB_NAME' | base64)"
+```
+
+Then also set the session name via osascript as a fallback:
+
+```bash
+osascript -e 'tell application "iTerm2" to tell current session of current window to set name to "TAB_NAME"' 2>/dev/null
+```
+
+### Terminal.app (`TERM_PROGRAM=Apple_Terminal`)
+
+Terminal.app requires **two steps** — set the custom title AND enable the custom title display (otherwise the shell's auto-title overrides it):
+
+```bash
+osascript -e '
+tell application "Terminal"
+  set t to selected tab of front window
+  set custom title of t to "TAB_NAME"
+end tell' 2>/dev/null
+```
+
+Then use the ANSI escape to set the window/tab title (this is what actually sticks):
+
+```bash
+printf '\033]0;TAB_NAME\007'
+```
+
+### Other terminals / fallback
+
+Use the standard ANSI escape sequence:
+
+```bash
+printf '\033]0;TAB_NAME\007'
+```
+
+## Step 3: Confirm
+
+If the rename succeeded, say:
+
+"Tab renamed to **{tab_name}**."
+
+> **Tip:** If your shell resets the title on each prompt (common with oh-my-zsh), add `export DISABLE_AUTO_TITLE="true"` to your `~/.zshrc`, then restart your shell.

package/.claude/commands/tour.md

@@ -337,7 +337,7 @@ Quick Reference
 ───────────────
 
 Workflow:
-  /idea [feature]       Brainstorm → PRD
+  /prd [feature]        Brainstorm → PRD
   npx ralph run         Execute autonomously
   npx ralph status      Check progress
   npx ralph stop        Stop after current story
@@ -354,4 +354,4 @@ Other:
   /vibe-help            Full cheatsheet
 ```
 
-Say: "You're all set! Run `/idea [your next feature]` to get started."
+Say: "You're all set! Run `/prd [your next feature]` to get started."

package/.claude/commands/vibe-help.md

@@ -11,7 +11,7 @@ Print this cheatsheet for the user. Do not add any commentary or explanation.
 ## The Loop
 
 ```
-/idea [feature]          brainstorm & generate PRD
+/prd [feature]           brainstorm & generate PRD
 npx ralph run            autonomous coding loop (live activity feed)
 npx ralph run --quiet    same, but suppress activity feed
 npx ralph status         check progress

package/.claude/commands/vibe-list.md

@@ -12,7 +12,7 @@ Print this complete reference for the user. Do not add any commentary.
 
 | Command | Description |
 |---------|-------------|
-| `/idea [feature]` | Brainstorm in plan mode, generate PRD for Ralph |
+| `/prd [feature]` | Brainstorm feature, generate executable PRD for Ralph |
 | `/setup-review` | Review config against project, fix mismatches |
 | `/sign` | Add a learned pattern for Ralph to remember |
 | `/my-dna` | Set up your personal style preferences |
@@ -90,7 +90,7 @@ Print this complete reference for the user. Do not add any commentary.
 ## The Loop
 
 ```
-/idea [feature]          Brainstorm → PRD
+/prd [feature]           Brainstorm → PRD
 npx ralph run            Autonomous coding
 npx ralph status         Check progress
 npx ralph stop           Stop after current story
@@ -100,10 +100,10 @@ npx ralph stop           Stop after current story
 
 ## Slash Command Details
 
-### /idea [feature description]
-Brainstorm in plan mode, explore codebase, ask clarifying questions.
-- Writes idea to `docs/ideas/{feature}.md`
-- On approval, splits into PRD stories
+### /prd [feature description]
+Brainstorm feature, explore codebase, ask clarifying questions.
+- Accepts a description or plan file (`docs/ideas/{feature}.md`)
+- Splits into executable PRD stories
 - Writes to `.ralph/prd.json`
 
 ### /review [file or selection]
@@ -206,7 +206,7 @@ npx ralph unsign "camelCase"
 
 CLAUDE.md            # Project standards (shared with team)
 PROMPT.md            # Base prompt for Ralph sessions
-docs/ideas/          # Brainstorm outputs from /idea
+docs/ideas/          # Brainstorm outputs from /prd
 
 # Global files (your home directory)
 ~/.claude/

package/.claude/skills/color/SKILL.md

@@ -0,0 +1,74 @@
+---
+description: Pick the terminal background color Ralph uses to distinguish its terminal from Claude Code.
+---
+
+# Terminal Color
+
+The user wants to change Ralph's terminal background tint - the color applied during `npx agentic-loop run` to visually distinguish Ralph's terminal from Claude Code.
+
+> **Note:** This only works in macOS Terminal.app. On other terminals (iTerm2, VS Code, Linux), Ralph skips tinting automatically.
+
+## Step 1: Show Current Color
+
+Read `.ralph/config.json` and check for `terminalTint`. Show the current setting:
+- If set: "Current tint: `{value}`"
+- If not set: "Current tint: `#1a2e2e` (default dark teal)"
+
+## Step 2: Ask Color Preference
+
+Use AskUserQuestion:
+
+**Question:** "What color should Ralph's terminal background be?"
+**Header:** "Tint color"
+**Options:**
+- **Dark Teal (default)** - "`#1a2e2e` - subtle blue-green, easy on the eyes"
+- **Dark Purple** - "`#1a1a2e` - cool and distinct from standard dark themes"
+- **Dark Red** - "`#2e1a1a` - warm undertone, clearly different"
+- **Off** - "Disable terminal tinting entirely"
+
+If the user selects "Other", ask them to provide a hex color (e.g., `#2e2e1a`).
+
+## Step 3: Validate (if custom hex)
+
+If the user provided a custom hex:
+- Must match `#` followed by exactly 6 hex characters (`/^#[0-9a-fA-F]{6}$/`)
+- If invalid, say "That doesn't look like a valid hex color (e.g., `#1a2e2e`). Try again." and re-ask.
+
+## Step 4: Save to Config
+
+Read `.ralph/config.json`, set the `terminalTint` field, and write it back.
+
+- **If a color was chosen:** Set `"terminalTint": "#xxxxxx"`
+- **If "Off" was chosen:** Set `"terminalTint": "off"`
+
+Use jq to update:
+```bash
+jq --arg color "THE_HEX_VALUE" '.terminalTint = $color' .ralph/config.json > .ralph/config.json.tmp && mv .ralph/config.json.tmp .ralph/config.json
+```
+
+## Step 5: Preview (macOS Terminal.app only)
+
+If running in Terminal.app, apply the color immediately so the user can see it:
+
+```bash
+# Apply preview (will be restored when Claude session ends)
+osascript -e 'tell application "Terminal" to set background color of front window to {R, G, B}' 2>/dev/null
+```
+
+Where R, G, B are the hex values converted to 16-bit (multiply each 8-bit value by 257).
+
+If "Off" was chosen, skip the preview.
+
+## Step 6: Confirm
+
+Say:
+
+"Done! Ralph will use `#xxxxxx` as the terminal tint.
+
+Next time you run `npx agentic-loop run`, the terminal background will change to this color. It restores to your original background when the loop ends.
+
+Run `/color` again anytime to change it."
+
+If "Off" was chosen, say:
+
+"Done! Terminal tinting is now disabled. Ralph will run without changing your terminal background."

package/.claude/skills/prd/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Generate an executable PRD for Ralph from an idea file or description.
+description: Brainstorm, harden, and generate an executable PRD for Ralph from a description, idea file, or plan file.
 ---
 
 # /prd - Generate PRD for Ralph
@@ -19,21 +19,29 @@ $ARGUMENTS
 ### Step 1: Determine Input Type
 
 **If `$ARGUMENTS` is empty:**
-1. Check for idea files:
+1. Scan for existing source files:
    ```bash
-   ls docs/ideas/*.md 2>/dev/null || echo "No ideas found"
+   ls docs/ideas/*.md 2>/dev/null || echo "No idea files found"
+   ls docs/plans/*.md 2>/dev/null || echo "No plan files found"
    ```
-2. Ask: "Would you like to:
-   - Convert an idea file (e.g., `/prd auth` for `docs/ideas/auth.md`)
-   - Describe a feature directly (e.g., `/prd 'Add user logout button'`)"
+2. If source files exist, use AskUserQuestion to let the user pick:
+   - **Question:** "What should I build the PRD from?"
+   - **Header:** "PRD source"
+   - **Options:** List discovered idea/plan files (up to 3-4 most relevant), plus a "Describe a feature" option that says "Type a description directly (e.g., 'Add user logout button')"
+   - If no source files found, skip AskUserQuestion and just say: "Describe the feature you'd like to build (e.g., `/prd 'Add user logout button'`)"
 
-**If `$ARGUMENTS` looks like a file reference** (no spaces, matches `docs/ideas/*.md`):
+**If `$ARGUMENTS` looks like a plan file** (`plans/` prefix, `docs/plans/` path, or full path to a plan file):
 - If it's a full path, use it directly
-- If it's just a name like `content-engine`, look for `docs/ideas/content-engine.md`
+- If it's `plans/name` or just a prefix, look for `docs/plans/{name}.md`
+- Proceed to "Read and Understand the Plan"
+
+**If `$ARGUMENTS` looks like an idea file reference** (no spaces, matches `docs/ideas/*.md`):
+- If it's a full path, use it directly
+- If it's just a name like `content-engine`, check `docs/ideas/content-engine.md` first, fall back to `docs/plans/content-engine.md`
 - Proceed to "Read and Understand the Idea"
 
 **If `$ARGUMENTS` is a description** (has spaces, is a sentence):
-- This is the **quick PRD flow** - no `docs/ideas/` file created
+- This is the **quick PRD flow** - no source file created
 - Good for small features that don't need documentation
 - Skip to "Confirm Understanding" below
 
@@ -48,9 +56,9 @@ Say: "I've read `{path}`. Here's my understanding:
 **Solution:** {one line}
 **Scope:** {key items}
 
-I'll now split this into {N} stories for Ralph. Continue?"
+I'll now ask a few hardening questions before generating stories."
 
-**STOP and wait for user confirmation.**
+**Proceed to Step 2.5.**
 
 ### Step 2b: Confirm Understanding (from description)
 
@@ -65,14 +73,64 @@ Use the detected tech stack, test runners, and constraints when building each st
 
 Then say: "I'll create a PRD for: **{description}**
 
-Before I generate stories, quick questions:
-1. **Type:** Frontend or backend?
-2. **Scale:** Any specific limits (users, items, rate limits)?
-3. **Anything else** I should know?
+Here's what I found in your codebase: [brief summary of tech stack, existing patterns]
+
+I'll now ask a few hardening questions before generating stories."
+
+**Proceed to Step 2.5.**
+
+### Step 2c: Read and Understand the Plan (from plan file)
+
+Read the plan file and summarize:
+
+Say: "I've read `{path}`. Here's my understanding:
+
+**Feature/Goal:** {name}
+**Approach:** {summary of approach}
+**Key Files:** {files mentioned}
+**Scope:** {key items}
+
+I'll now ask a few hardening questions before generating stories."
+
+**Proceed to Step 2.5.**
+
+### Step 2.5: Harden the Requirements
+
+**This step runs for ALL input types** (idea file, plan file, or description). Review what you already know from the input and ask ONLY about gaps — skip questions the input already answers.
 
-(Or say 'go' to proceed with defaults)"
+Say: "Before I generate stories, I want to make sure we've covered the key areas:"
 
-**STOP and wait for user input** (can be brief or 'go').
+**Scope & UX** (always ask):
+- What's in scope vs out of scope?
+- Is this user-facing? What does the user see/do?
+- What are the edge cases?
+- **Responsive design** (if frontend): Must it work on mobile/tablet? What breakpoints? Any layout changes between screen sizes?
+
+**Security** (ask if feature involves auth, user input, or sensitive data):
+- Authentication: Who can access this? Login required?
+- Passwords: How stored? (must be hashed, never plain text)
+- User input: What validation needed? (SQL injection, XSS)
+- Sensitive data: What should NEVER be in API responses?
+- Rate limiting: Should this be rate limited?
+
+**Scale** (ask if feature involves lists, data, or APIs):
+- How many items expected? (10s, 1000s, millions?)
+- Pagination needed? What's the max per page?
+- Caching needed? How fresh must data be?
+- Database indexes: What will be queried/sorted frequently?
+
+**Migration** (ask if feature involves restructuring or moving code):
+- Source → destination mapping: Where does code currently live? Where should it end up?
+- Phases: What's the logical order?
+- Verification: What commands prove each phase worked?
+
+After presenting the hardening questions, use AskUserQuestion:
+- **Question:** "Answer the questions above, or proceed with sensible defaults?"
+- **Header:** "Hardening"
+- **Options:**
+  - **"Go with defaults"** — "Proceed with sensible defaults for unanswered questions"
+  - **"Let me answer"** — "I'll respond to the questions above"
+- If the user selects "Let me answer" or "Other", **STOP and wait for their response** before continuing.
 
 ### Step 3: Check for Existing PRD
 
@@ -81,16 +139,11 @@ cat .ralph/prd.json 2>/dev/null
 ```
 
 If it exists, read it and say:
-"`.ralph/prd.json` exists with {N} stories ({M} completed, {P} pending).
+"`.ralph/prd.json` exists with {N} stories ({M} completed, {P} pending). I'll append new stories to it."
 
-Options:
-- **'append'** - Add new stories to the existing PRD (recommended)
-- **'overwrite'** - Replace it entirely
-- **'cancel'** - Stop here"
+**Default behavior is append** — just proceed. Do NOT ask for confirmation unless the user explicitly says "overwrite" or "replace".
 
-**STOP and wait for user choice.**
-
-If user chooses **'append'**:
+When appending:
 - Find highest existing story number (ignore prefix - could be US-005 or TASK-005)
 - **Always use TASK- prefix** for new stories (e.g., if highest is US-005 or TASK-005, new stories start at TASK-006)
 - New stories will be added after existing ones
@@ -176,7 +229,7 @@ Does acceptanceCriteria include:
 - Large datasets → "Database query uses index on [column]"
 
 #### 6e. Context (for all stories)
-- Does `contextFiles` include the idea file (has ASCII mockups)?
+- Does `contextFiles` include the source file (idea or plan file, especially if it has ASCII mockups)?
 - Does `contextFiles` include styleguide (if exists)?
 - Does `techStack` include the relevant stack for this story?
 - Does `constraints` include any rules this story must follow?
@@ -192,6 +245,26 @@ If the feature has ANY frontend stories that add or modify user-facing UI:
 - The E2E story should be the LAST story (depends on all others) to test the full integrated flow
 - If no E2E story exists, CREATE one as the final story
 
+#### 6h. Responsive Design (for frontend stories)
+Every frontend story that creates or modifies user-facing UI MUST include:
+- `acceptanceCriteria` with responsive behavior: "Layout adapts to mobile (< 768px), tablet (768-1024px), and desktop (> 1024px)"
+- `testSteps` with a viewport resize check OR Playwright test that validates mobile layout
+- `notes` with Playwright MCP instructions to screenshot at mobile and desktop widths
+
+**Example acceptanceCriteria:**
+```
+"Component renders in single-column layout on mobile (< 768px)",
+"Navigation collapses to hamburger menu on mobile",
+"Touch targets are at least 44x44px on mobile"
+```
+
+**Example testSteps:**
+```
+"npx playwright test tests/e2e/dashboard.spec.ts --project=mobile"
+```
+
+If a frontend story has no responsive criteria and the feature is user-facing, add them.
+
 #### 6g. Test Scenario Specificity
 Every story's `notes` field MUST include **3+ specific test scenarios** that describe what to test and how. Vague notes like "Test the service methods" are not acceptable.
 
@@ -214,7 +287,7 @@ Bad example:
 | Story depends on something not created | Reorder or add missing dependency |
 | Auth story missing security criteria | Add password hashing, rate limiting to acceptanceCriteria |
 | List endpoint missing pagination | Add pagination criteria to acceptanceCriteria |
-| Frontend missing contextFiles | Add idea file + styleguide paths |
+| Frontend missing contextFiles | Add source file (idea or plan) + styleguide paths |
 | Frontend missing testUrl | Add URL from config |
 | Frontend missing mcp | Add `"mcp": ["playwright", "devtools"]` |
 | Frontend notes missing Playwright MCP guidance | Add visual verification instructions to notes (see Playwright MCP section) |
@@ -223,6 +296,7 @@ Bad example:
 | testSteps use import-checks (`python -c "from X import Y"`) | Replace with curl, pytest, or real behavioral tests |
 | No E2E story for user-facing feature | Add a final E2E story with Playwright tests |
 | Story notes lack specific test scenarios | Add 3+ concrete scenarios with inputs, expected outputs, and fixture references |
+| Frontend story missing responsive design | Add mobile/tablet/desktop acceptanceCriteria and viewport test steps |
 
 ### Step 7: Reorder if Needed
 
@@ -259,14 +333,18 @@ Open the PRD for review:
 open -a TextEdit .ralph/prd.json
 ```
 
-Say: "I've {created|updated} the PRD with {N} stories and opened it in TextEdit.
+Say: "I've {created|updated} the PRD with {N} stories and opened it in TextEdit."
 
-Review the PRD and let me know:
-- **'approved'** - Ready to run in your other terminal
-- **'edit [changes]'** - Tell me what to change
-- Or edit the JSON directly and say **'done'**"
+Then use AskUserQuestion with **multiSelect: true**:
+- **Question:** "How does the PRD look?"
+- **Header:** "PRD review"
+- **multiSelect:** true
+- **Options:**
+  - **"Approved"** — "PRD is good — ready to run with Ralph"
+  - **"Edit"** — "I'll tell you what to change"
+  - **"I edited the JSON"** — "I made changes directly in the file, re-validate it"
 
-**STOP and wait for user response.**
+If the user selects "Edit" (with or without other selections), **STOP and wait for their changes**. If "I edited the JSON" is selected, re-read and re-validate the PRD. If only "Approved" is selected, proceed to Step 9.
 
 ### Step 9: Final Instructions
 
@@ -274,7 +352,7 @@ Once approved, say:
 
 "PRD is ready!
 
-**Source:** `{idea-file-path}`
+**Source:** `{source-file-path}`
 **PRD:** `.ralph/prd.json` ({N} stories)
 
 To start autonomous development, open another terminal and run:
@@ -296,7 +374,7 @@ Ralph will work through each story, running tests and committing as it goes."
 {
   "feature": {
     "name": "Feature Name",
-    "ideaFile": "docs/ideas/{feature-name}.md",
+    "ideaFile": "docs/ideas/{feature-name}.md or docs/plans/{feature-name}.md",
     "branch": "feature/{feature-name}",
     "status": "pending"
   },
@@ -404,7 +482,7 @@ Ralph will work through each story, running tests and committing as it goes."
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `feature` | Yes | Feature name, ideaFile, branch, status |
+| `feature` | Yes | Feature name, ideaFile (idea or plan path), branch, status |
 | `metadata` | Yes | Created date, estimated stories, complexity |
 
 **Note:** URLs come from `.ralph/config.json`, not the PRD. Use `{config.urls.backend}` in testSteps.
@@ -786,6 +864,7 @@ Use `contextFiles` to point Claude to important reference material:
 ```json
 "contextFiles": [
   "docs/ideas/dashboard.md",
+  "docs/plans/auth-feature.md",
   "src/styles/styleguide.html",
   "docs/api-spec.md"
 ]
@@ -807,7 +886,9 @@ This is where ASCII mockups, design specs, and detailed requirements live. Claud
 ### UI Stories Must Include
 - `testUrl` - Where to verify
 - `mcp: ["playwright", "devtools"]` - Browser tools
-- Acceptance criteria for: page loads, elements render, mobile works
+- Acceptance criteria for: page loads, elements render correctly
+- **Responsive design criteria**: layout adapts at mobile (< 768px), tablet (768-1024px), desktop (> 1024px) breakpoints
+- Playwright test or MCP verification at multiple viewport widths
 
 ### API Stories Must Include
 - `apiContract` - Expected request/response

package/.claude/skills/prd-check/SKILL.md

@@ -4,7 +4,7 @@ description: Run PRD validation to check story quality, test coverage, and struc
 
 # PRD Check
 
-Run PRD validation on demand to check story quality, test coverage, and structure before starting the autonomous loop.
+Run PRD validation on demand to check story quality, test coverage, and structure before starting the autonomous loop. Cross-references against learned signs and past failure patterns.
 
 ## Instructions
 
@@ -17,32 +17,89 @@ ls -la .ralph/prd.json 2>/dev/null || echo "NOT_FOUND"
 ```
 
 If no PRD exists, tell the user:
-> No PRD found at `.ralph/prd.json`. Generate one first with `/idea` or `/prd`.
+> No PRD found at `.ralph/prd.json`. Generate one first with `/prd`.
 
 **STOP** if no PRD found.
 
-### Step 2: Run Validation (dry-run)
+### Step 2: Load Project Knowledge
 
-Run validation without auto-fix so you can present results and let the user decide:
+Read the project's accumulated knowledge:
+
+1. Read signs:
+   ```bash
+   cat .ralph/signs.json 2>/dev/null
+   ```
+
+2. Read suggested signs (last 50 lines — file can be huge):
+   ```bash
+   tail -50 .ralph/suggested-signs.txt 2>/dev/null
+   ```
+
+3. Read recent progress for failure patterns:
+   ```bash
+   tail -100 .ralph/progress.txt 2>/dev/null
+   ```
+
+### Step 3: Run Structural Validation (dry-run)
 
 ```bash
 npx ralph prd-check --dry-run 2>&1
 ```
 
-### Step 3: Present Results
+Present any structural issues found.
+
+### Step 4: Cross-Reference Against Signs
+
+Read `.ralph/prd.json` and for each story, check if any sign applies:
+
+- **Backend signs** → check against backend stories
+- **Frontend signs** → check against frontend stories
+- **General signs** → check against all stories
+
+For each applicable sign, verify the story's `acceptanceCriteria`, `constraints`,
+`notes`, or `testSteps` reflect the pattern. Flag stories that should account for
+a sign but don't.
+
+**Examples:**
+- Sign: "Always use bcrypt cost 10+ for passwords" → Flag auth stories missing
+  bcrypt in acceptanceCriteria
+- Sign: "Use date-fns instead of moment.js" → Flag frontend stories that create
+  date utilities without this constraint
+- Sign: "Add data-testid for Playwright selectors" → Flag frontend stories missing
+  this in constraints
+
+### Step 5: Check Against Suggested Learnings
+
+Scan `suggested-signs.txt` for patterns relevant to the current PRD's feature area.
+Flag any recurring failure patterns that the PRD's stories don't address.
+
+### Step 6: Present Results
+
+Summarize all findings in categories:
 
-Show the validation output to the user. If there are issues, summarize them clearly.
+> **Structural Issues** (from prd-check):
+> - [list]
+>
+> **Sign Conflicts** (stories that don't account for known patterns):
+> - TASK-003: Missing sign "bcrypt cost 10+" in auth story
+> - TASK-005: Missing sign "data-testid attributes" in frontend story
+>
+> **Suggested Improvements** (from past learnings):
+> - [relevant patterns from suggested-signs.txt]
 
-If issues were found, ask:
-> "Would you like me to fix these issues in the PRD?"
+Ask: "Would you like me to fix these issues in the PRD?"
 
 **STOP and wait for user response.**
 
-If the user says yes, read `.ralph/prd.json`, fix the issues following PRD best practices (executable testSteps with curl/pytest/playwright, apiContract for backends, testUrl for frontends, security criteria for auth stories, pagination for list endpoints), and write the fixed file back.
+If yes, update `.ralph/prd.json`:
+- Add missing sign patterns to relevant story `constraints` or `acceptanceCriteria`
+- Fix structural issues per PRD best practices
+- Write the fixed file back
 
 ## Notes
 
-- This is the same validation that runs automatically at `ralph run` startup
+- This is the same structural validation that runs automatically at `ralph run` startup
 - `--dry-run` skips auto-fix so you have control over what changes
 - Custom checks in `.ralph/checks/prd/` are also evaluated
+- Signs cross-referencing catches patterns that structural validation can't
 - Run this before `ralph run` to catch and fix issues interactively