agentic-loop 3.22.1 → 3.26.0

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,53 @@
+---
+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".
+
+> **Note:** This uses AppleScript and only works in macOS Terminal.app and iTerm2.
+
+## 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
+
+Detect which terminal is running and set the title:
+
+```bash
+# Try Terminal.app first
+osascript -e 'tell application "Terminal" to set custom title of selected tab of front window to "TAB_NAME"' 2>/dev/null
+```
+
+If that fails (not Terminal.app), try iTerm2:
+
+```bash
+osascript -e 'tell application "iTerm2" to tell current session of current window to set name to "TAB_NAME"' 2>/dev/null
+```
+
+**Important:** Escape any double quotes in the tab name before embedding in the AppleScript string.
+
+## Step 3: Confirm
+
+If the rename succeeded, say:
+
+"Tab renamed to **{tab_name}**."
+
+If both osascript commands fail, say:
+
+"Tab renaming requires macOS Terminal.app or iTerm2. On other terminals, you can set the tab title manually with: `printf '\033]0;my-title\007'`"

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/my-dna/SKILL.md

@@ -95,8 +95,10 @@ Use a marker `<!-- my-dna -->` to identify the section. If marker exists, replac
 ### Core Values
 - [List their selected values]
 
-### Voice
+### Writing Style (responses and all file content)
 [Their style + any notes from writing sample]
+- Never use em dashes. Use commas, periods, or parentheses instead.
+Apply this style to everything: responses, code comments, docs, page copy, commit messages, and any content written to files.
 
 ### Project
 - **Priority:** [ship it / solid / beautiful / scale]

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,27 @@ $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`)
+2. List what's available and ask: "Would you like to:
+   - Convert a source file (e.g., `/prd auth` or `/prd plans/my-feature`)
    - Describe a feature directly (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 +54,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,12 +71,58 @@ 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
 
-(Or say 'go' to proceed with defaults)"
+**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.
+
+Say: "Before I generate stories, I want to make sure we've covered the key areas:"
+
+**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?
+
+End with: "(Or say **'go'** to proceed with defaults for anything not answered)"
 
 **STOP and wait for user input** (can be brief or 'go').
 
@@ -95,6 +147,26 @@ If user chooses **'append'**:
 - **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
 
+### Step 3.5: Read Existing Test Infrastructure
+
+Before writing stories, discover the project's existing test setup so stories reference real fixtures, helpers, and patterns:
+
+```bash
+# Find test config and fixtures
+ls tests/conftest.py tests/fixtures/ src/__tests__/ e2e/ 2>/dev/null
+cat tests/conftest.py 2>/dev/null | head -50
+cat e2e/*.config.ts 2>/dev/null | head -30
+
+# Find existing test patterns
+grep -r "def test_\|async def test_\|it(\|describe(" tests/ src/__tests__/ e2e/ 2>/dev/null | head -20
+```
+
+Use what you find to:
+- Reference correct fixture names in story `notes` (e.g., "Use `db_session` and `client` fixtures from `conftest.py`")
+- Match existing test file organization (e.g., `tests/domains/auth/` not `tests/test_auth.py`)
+- Include specific test scenarios in `notes` based on patterns you see in existing tests
+- Reference real helpers (e.g., "Use `MockRequest` from `test_auth.py` for request mocking")
+
 ### Step 4: Split into Stories
 
 Break the idea into small, executable stories:
@@ -156,12 +228,54 @@ 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?
 - For frontend: Is `testUrl` set?
 - For frontend: Is `mcp` set to `["playwright", "devtools"]`?
+- For frontend: Does `notes` include Playwright MCP visual verification instructions? (See "Playwright MCP for Visual Verification" section below)
+
+#### 6f. E2E Coverage (MANDATORY for user-facing features)
+If the feature has ANY frontend stories that add or modify user-facing UI:
+- There MUST be at least one story with `"e2e"` in its `testing.types`
+- That story MUST have Playwright test files in `testing.files.e2e`
+- That story's `testSteps` MUST include `npx playwright test ...`
+- 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.
+
+Good example:
+```
+"notes": "Test scenarios: (1) Exchange valid auth code → returns JWT with correct claims. (2) Exchange expired code → returns 401 with 'code_expired' error. (3) Exchange code with wrong redirect_uri → returns 400. (4) Verify nonce mismatch is rejected. Use existing test fixtures: db_session, client from conftest.py."
+```
+
+Bad example:
+```
+"notes": "Test the authentication service methods with proper mocking."
+```
 
 **Fix any issues you find:**
 
@@ -172,11 +286,16 @@ Does acceptanceCriteria include:
 | 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) |
 | Story missing techStack | Add relevant subset of detected tech |
 | Story missing constraints | Add applicable rules for this story |
+| 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
 
@@ -228,7 +347,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:
@@ -250,7 +369,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"
   },
@@ -358,7 +477,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.
@@ -583,9 +702,30 @@ Specify which MCP tools Claude should use for verification:
 | `devtools` | Console errors, network inspection, DOM debugging |
 | `postgres` | Database verification (future) |
 
-**Frontend stories** default to `["playwright", "devtools"]`.
+**Frontend stories** MUST have `"mcp": ["playwright", "devtools"]`.
 **Backend-only stories** can use `[]` or omit.
 
+### Playwright MCP for Visual Verification
+
+Frontend stories should include guidance in `notes` for using Playwright MCP during implementation. This is how Ralph visually verifies that UI changes actually render correctly — screenshots catch layout bugs, missing elements, and broken styles that unit tests miss.
+
+**Every frontend story's `notes` should include Playwright MCP instructions like:**
+
+```
+Use Playwright MCP to verify:
+1. Navigate to {testUrl} and take a screenshot
+2. Verify [specific element] is visible and correctly styled
+3. Click [interactive element] and verify [expected behavior]
+4. Check browser console for errors after interactions
+```
+
+**Example for a login page SSO button story:**
+```json
+"notes": "Use Playwright MCP to verify: navigate to /login, screenshot the page, confirm 'Sign in with Okta' button is visible below the email/password form with a divider. Click the button and verify it redirects to /api/v1/auth/okta/authorize. Check devtools console for errors."
+```
+
+This is NOT a replacement for automated Playwright tests — it's additional visual verification that Ralph performs during the implementation step using the MCP browser tools.
+
 ---
 
 ## Skills Reference
@@ -697,11 +837,15 @@ Ralph reads `.ralph/config.json` and expands `{config.urls.backend}` before runn
   "grep -q 'function createUser' app/services/user.py",  // ❌ PASSES if code exists, even if broken
   "grep -q 'export default' src/components/Dashboard.tsx", // ❌ PASSES even if component crashes
   "test -f src/api/users.ts",                            // ❌ PASSES if file exists, even if empty
+  "python -c \"from app.services.auth import AuthService\"", // ❌ PASSES if import works, says nothing about behavior
+  "python -c \"hasattr(AuthService, 'login')\"",          // ❌ PASSES if method exists, even if completely broken
   "Visit http://localhost:3000/dashboard",                // ❌ Not executable
   "User can see the dashboard"                            // ❌ Not executable
 ]
 ```
 
+**NEVER use import-checks (`python -c "from X import Y"` or `hasattr`) as test steps.** These only verify a symbol exists — they don't test behavior, error handling, or integration. A function that raises on every call still passes an import check.
+
 **NEVER use grep/test to verify behavior.** These will mark stories as PASSED when the feature is broken.
 
 **If a step can't be automated**, put it in `acceptanceCriteria` instead. Claude will verify it visually using MCP tools.
@@ -715,6 +859,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"
 ]
@@ -736,7 +881,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