agentic-loop 3.22.1 → 3.26.0

package/ralph/prd-check.sh

@@ -119,7 +119,7 @@ validate_prd() {
     print_error "prd.json is not valid JSON."
     echo ""
     echo "Fix it manually or regenerate with:"
-    echo "  /idea 'your feature'"
+    echo "  /prd 'your feature'"
     echo ""
     return 1
   fi
@@ -131,7 +131,7 @@ validate_prd() {
     print_error "prd.json is missing .feature.name"
     echo ""
     echo "Add a feature name to your PRD or regenerate with:"
-    echo "  /idea 'your feature'"
+    echo "  /prd 'your feature'"
     echo ""
     return 1
   fi
@@ -140,7 +140,7 @@ validate_prd() {
   if ! jq -e '.stories' "$prd_file" >/dev/null 2>&1; then
     print_error "prd.json is missing 'stories' array."
     echo ""
-    echo "Regenerate with: /idea 'your feature'"
+    echo "Regenerate with: /prd 'your feature'"
     echo ""
     return 1
   fi
@@ -151,7 +151,7 @@ validate_prd() {
   if [[ "$story_count" == "0" ]]; then
     print_error "prd.json has no stories."
     echo ""
-    echo "Regenerate with: /idea 'your feature'"
+    echo "Regenerate with: /prd 'your feature'"
     echo ""
     return 1
   fi
@@ -163,7 +163,7 @@ validate_prd() {
     print_error "Some stories are missing required fields (id, title):"
     echo "$invalid_stories" | head -5
     echo ""
-    echo "Fix the PRD or regenerate with: /idea 'your feature'"
+    echo "Fix the PRD or regenerate with: /prd 'your feature'"
     echo ""
     return 1
   fi
@@ -405,6 +405,20 @@ _check_story_issues() {
     fi
   fi
 
+  # Import-check anti-pattern: python -c "from X import Y" or hasattr()
+  if [[ -n "$test_steps" ]] && echo "$test_steps" | grep -qE '(python[3]? -c .*(from |import |hasattr))'; then
+    echo "testSteps use import-checks (python -c 'from/import/hasattr') — replace with real behavioral tests"
+  fi
+
+  # Frontend stories must include Playwright MCP visual verification guidance in notes
+  if [[ "$story_type" == "frontend" ]]; then
+    local story_notes
+    story_notes=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .notes // ""' "$prd_file")
+    if ! echo "$story_notes" | grep -qiE "(playwright.*mcp|mcp.*playwright|visual.*verif|screenshot|navigate.*screenshot)"; then
+      echo "frontend notes should include Playwright MCP visual verification guidance"
+    fi
+  fi
+
   # All testSteps are server-dependent
   if [[ -n "$test_steps" ]]; then
     local has_offline=false has_server=false
@@ -443,6 +457,8 @@ _validate_and_fix_stories() {
   local cnt_naming_convention=0 cnt_bare_pytest=0 cnt_bare_python=0
   local cnt_server_only=0
   local cnt_custom=0
+  local cnt_import_check=0
+  local cnt_playwright_notes=0
 
   echo "  Checking test coverage..."
 
@@ -508,6 +524,8 @@ _validate_and_fix_stories() {
         "missing pagination criteria") cnt_list_pagination=$((cnt_list_pagination + 1)) ;;
         "API consumer needs camelCase transformation note") cnt_naming_convention=$((cnt_naming_convention + 1)) ;;
         "all testSteps need a live server"*) cnt_server_only=$((cnt_server_only + 1)) ;;
+        "testSteps use import-checks"*) cnt_import_check=$((cnt_import_check + 1)) ;;
+        "frontend notes should include Playwright"*) cnt_playwright_notes=$((cnt_playwright_notes + 1)) ;;
       esac
     done <<< "$shared_issues"
 
@@ -539,6 +557,17 @@ _validate_and_fix_stories() {
     fi
   done <<< "$story_ids"
 
+  # Global check: if any frontend stories exist, at least one story should have E2E tests
+  local has_frontend_stories has_e2e_story
+  has_frontend_stories=$(jq -r '[.stories[] | select(.type == "frontend")] | length' "$prd_file" 2>/dev/null)
+  has_e2e_story=$(jq -r '[.stories[] | select(.testing.types[]? == "e2e")] | length' "$prd_file" 2>/dev/null)
+  if [[ "$has_frontend_stories" -gt 0 && "$has_e2e_story" == "0" ]]; then
+    echo ""
+    print_warning "No E2E story found — frontend features should have at least one Playwright E2E story"
+    echo "  Add a final story with testing.types: [\"e2e\"] and Playwright testSteps"
+    echo ""
+  fi
+
   # If issues found, show summary and attempt fix
   if [[ "$needs_fix" == "true" ]]; then
     echo "  Optimizing test coverage for $story_count stories..."
@@ -558,6 +587,8 @@ _validate_and_fix_stories() {
     [[ $cnt_bare_pytest -gt 0 ]] && echo "    ${cnt_bare_pytest}x use '${py_runner:-python3} pytest' not bare 'pytest'"
     [[ $cnt_bare_python -gt 0 ]] && echo "    ${cnt_bare_python}x use 'python3' not bare 'python' (macOS compatibility)"
     [[ $cnt_server_only -gt 0 ]] && echo "    ${cnt_server_only}x all testSteps need live server (add offline fallback)"
+    [[ $cnt_import_check -gt 0 ]] && echo "    ${cnt_import_check}x testSteps use import-checks (replace with real tests)"
+    [[ $cnt_playwright_notes -gt 0 ]] && echo "    ${cnt_playwright_notes}x frontend: add Playwright MCP visual verification to notes"
     [[ $cnt_custom -gt 0 ]] && echo "    ${cnt_custom} stories with custom check issues"
 
     # Skip auto-fix in dry-run mode

package/ralph/prd.sh

@@ -118,7 +118,7 @@ ralph_prd() {
   printf '%s\n' '      "acceptanceCriteria": ["AC 1", "AC 2"],' >> "$prompt_file"
   printf '%s\n' '      "errorHandling": ["what happens on failure"],' >> "$prompt_file"
   printf '%s\n' '      "testSteps": ["executable shell commands only"],' >> "$prompt_file"
-  printf '%s\n' '      "contextFiles": ["docs/ideas/feature.md"],' >> "$prompt_file"
+  printf '%s\n' '      "contextFiles": ["docs/ideas/feature.md", "docs/plans/feature-plan.md"],' >> "$prompt_file"
   printf '%s\n' '      "notes": ""' >> "$prompt_file"
   printf '%s\n' '    }' >> "$prompt_file"
   printf '%s\n' '  ]' >> "$prompt_file"

package/ralph/setup/feature-tour.sh

@@ -130,7 +130,7 @@ demo_skills() {
 
   echo -e "  ${BOLD}In Claude Code, type these commands:${NC}\n"
 
-  echo -e "  ${CYAN}/idea${NC}            Brainstorm → PRD → Ready for Ralph"
+  echo -e "  ${CYAN}/prd${NC}             Brainstorm → PRD → Ready for Ralph"
   sleep 0.1
   echo -e "  ${CYAN}/vibe-help${NC}       Quick reference cheatsheet"
   sleep 0.1

package/ralph/setup/tutorial.sh

@@ -83,7 +83,7 @@ lesson_slash_commands() {
   echo ""
   echo -e "  ${BOLD}Custom commands${NC} (from ${DIM}.claude/skills/${NC}):"
   echo ""
-  echo -e "    ${CYAN}/idea${NC}      Brainstorm → PRD → Ready for Ralph"
+  echo -e "    ${CYAN}/prd${NC}       Brainstorm → PRD → Ready for Ralph"
   echo -e "    ${CYAN}/vibe-check${NC} Code quality audit"
   echo -e "    ${CYAN}/review${NC}    Code review with security checks"
   echo ""
@@ -135,7 +135,7 @@ lesson_integration() {
 
   echo -e "  ${BOLD}agentic-loop${NC} adds superpowers to Claude Code:"
   echo ""
-  echo -e "  ${BOLD}1. The Workflow (/idea → Ralph → Ship)${NC}"
+  echo -e "  ${BOLD}1. The Workflow (/prd → Ralph → Ship)${NC}"
   echo -e "     ${DIM}Brainstorm ideas, generate PRDs, execute autonomously${NC}"
   echo ""
   echo -e "  ${BOLD}2. Code Quality (/vibe-check)${NC}"
@@ -145,7 +145,7 @@ lesson_integration() {
   echo -e "     ${DIM}Automatically blocks problematic commits${NC}"
   echo ""
   echo -e "  ${BOLD}4. Slash Commands (7 included)${NC}"
-  echo -e "     ${DIM}/idea, /vibe-help, /tour, /vibe-check, /review, /explain, /styleguide${NC}"
+  echo -e "     ${DIM}/prd, /vibe-help, /tour, /vibe-check, /review, /explain, /styleguide${NC}"
   echo ""
   echo -e "  ${BOLD}5. MCP Configuration${NC}"
   echo -e "     ${DIM}Chrome DevTools for visual verification${NC}"

package/ralph/setup.sh

@@ -169,6 +169,7 @@ ralph_setup() {
   setup_custom_checks
   setup_gitignore
   setup_claude_hooks "$pkg_root"
+  setup_claude_hud
   setup_slash_commands "$pkg_root"
   setup_claude_md
   setup_mcp
@@ -185,7 +186,7 @@ ralph_setup() {
   echo "  --- Terminal 1: Claude Code ---"
   echo "  claude --dangerously-skip-permissions"
   echo "  /tour                   # Guided walkthrough"
-  echo "  /idea 'your feature'    # Generate a PRD"
+  echo "  /prd 'your feature'     # Generate a PRD"
   echo ""
   echo "  --- Terminal 2: Ralph Loop ---"
   echo "  npx agentic-loop run         # Execute PRDs autonomously"
@@ -197,7 +198,7 @@ setup_ralph_dir() {
   local pkg_root="$1"
 
   echo "Creating .ralph/ directory..."
-  mkdir -p ".ralph/archive" ".ralph/screenshots"
+  mkdir -p ".ralph/archive" ".ralph/screenshots" ".ralph/hooks"
 
   # Copy config template based on detected project type
   if [[ ! -f ".ralph/config.json" ]]; then
@@ -401,26 +402,34 @@ setup_claude_hooks() {
   inject_context=$(_resolve_hook "inject-context.sh")
   save_learnings=$(_resolve_hook "save-learnings.sh")
 
+  # Wrap hook path with existence check so missing files don't produce errors.
+  # If the hook script is deleted after setup (git clean, etc.), this prevents
+  # "No such file or directory" errors on every Claude session end.
+  _safe_cmd() {
+    local path="$1"
+    printf 'if [ -f "%s" ]; then "%s"; else echo '"'"'{"continue": true}'"'"'; fi' "$path" "$path"
+  }
+
   # Build hooks arrays using jq for proper JSON
   local post_edit_hooks post_all_hooks session_start_hooks stop_hooks
 
   # PostToolUse: warn-* hooks on Edit|Write
   post_edit_hooks="[]"
   for hook_path in "$warn_debug" "$warn_secrets" "$warn_urls" "$warn_empty_catch"; do
-    [[ -n "$hook_path" ]] && post_edit_hooks=$(echo "$post_edit_hooks" | jq --arg cmd "$hook_path" '. + [{"type": "command", "command": $cmd, "timeout": 5}]')
+    [[ -n "$hook_path" ]] && post_edit_hooks=$(echo "$post_edit_hooks" | jq --arg cmd "$(_safe_cmd "$hook_path")" '. + [{"type": "command", "command": $cmd, "timeout": 5}]')
   done
 
   # PostToolUse: log-tools on all
   post_all_hooks="[]"
-  [[ -n "$log_tools" ]] && post_all_hooks=$(jq -n --arg cmd "$log_tools" '[{"type": "command", "command": $cmd, "timeout": 3}]')
+  [[ -n "$log_tools" ]] && post_all_hooks=$(jq -n --arg cmd "$(_safe_cmd "$log_tools")" '[{"type": "command", "command": $cmd, "timeout": 3}]')
 
   # SessionStart: inject-context
   session_start_hooks="[]"
-  [[ -n "$inject_context" ]] && session_start_hooks=$(jq -n --arg cmd "$inject_context" '[{"type": "command", "command": $cmd, "timeout": 5}]')
+  [[ -n "$inject_context" ]] && session_start_hooks=$(jq -n --arg cmd "$(_safe_cmd "$inject_context")" '[{"type": "command", "command": $cmd, "timeout": 5}]')
 
   # Stop: save-learnings
   stop_hooks="[]"
-  [[ -n "$save_learnings" ]] && stop_hooks=$(jq -n --arg cmd "$save_learnings" '[{"type": "command", "command": $cmd, "timeout": 10}]')
+  [[ -n "$save_learnings" ]] && stop_hooks=$(jq -n --arg cmd "$(_safe_cmd "$save_learnings")" '[{"type": "command", "command": $cmd, "timeout": 10}]')
 
   # Build the complete hooks config
   local hooks_config
@@ -446,6 +455,106 @@ setup_claude_hooks() {
   echo "  Configured .claude/settings.json"
 }
 
+# Install claude-hud statusline plugin for Claude Code
+setup_claude_hud() {
+  local hud_dir="$HOME/.claude/plugins/claude-hud"
+  local marketplaces_file="$HOME/.claude/plugins/known_marketplaces.json"
+
+  # Check dependencies
+  if ! command -v git &>/dev/null; then
+    print_warning "git not found — skipping claude-hud install"
+    return 0
+  fi
+  if ! command -v node &>/dev/null; then
+    print_warning "node not found — skipping claude-hud install"
+    return 0
+  fi
+  if ! command -v jq &>/dev/null; then
+    print_warning "jq not found — skipping claude-hud install"
+    return 0
+  fi
+
+  echo "Setting up claude-hud statusline..."
+
+  # Clone if not already present
+  if [[ ! -d "$hud_dir" ]]; then
+    mkdir -p "$HOME/.claude/plugins"
+    if ! git clone --depth 1 https://github.com/jarrodwatts/claude-hud.git "$hud_dir" 2>/dev/null; then
+      print_warning "Failed to clone claude-hud — skipping"
+      return 0
+    fi
+    echo "  Cloned claude-hud plugin"
+  else
+    echo "  claude-hud already installed"
+  fi
+
+  # Build if dist/index.js is missing
+  if [[ ! -f "$hud_dir/dist/index.js" ]]; then
+    echo "  Building claude-hud..."
+    if ! (cd "$hud_dir" && npm ci --production=false --ignore-scripts 2>/dev/null && npm run build 2>/dev/null); then
+      print_warning "Failed to build claude-hud — statusline may not work"
+      echo "    Try manually: cd $hud_dir && npm ci && npm run build"
+      return 0
+    fi
+    echo "  Built successfully"
+  fi
+
+  # Register in known_marketplaces.json
+  if [[ -f "$marketplaces_file" ]]; then
+    if ! jq -e '."claude-hud"' "$marketplaces_file" > /dev/null 2>&1; then
+      local tmp
+      tmp=$(mktemp)
+      jq '."claude-hud" = {
+        "source": {
+          "source": "github",
+          "repo": "jarrodwatts/claude-hud"
+        },
+        "installLocation": ($ENV.HOME + "/.claude/plugins/claude-hud"),
+        "lastUpdated": (now | todate)
+      }' "$marketplaces_file" > "$tmp" && mv "$tmp" "$marketplaces_file"
+      echo "  Registered in known_marketplaces.json"
+    fi
+  else
+    mkdir -p "$(dirname "$marketplaces_file")"
+    jq -n '{
+      "claude-hud": {
+        "source": {
+          "source": "github",
+          "repo": "jarrodwatts/claude-hud"
+        },
+        "installLocation": ($ENV.HOME + "/.claude/plugins/claude-hud"),
+        "lastUpdated": (now | todate)
+      }
+    }' > "$marketplaces_file"
+    echo "  Created known_marketplaces.json with claude-hud"
+  fi
+
+  # Write agentic-loop-tuned config
+  cat > "$hud_dir/config.json" << 'EOF'
+{
+  "lineLayout": "expanded",
+  "pathLevels": 2,
+  "gitStatus": {
+    "enabled": true,
+    "showDirty": true,
+    "showAheadBehind": true
+  },
+  "display": {
+    "showContextBar": true,
+    "contextValue": "percent",
+    "showModel": true,
+    "showDuration": true,
+    "showSpeed": false,
+    "showUsage": true,
+    "showTools": true,
+    "showAgents": true,
+    "showTodos": true
+  }
+}
+EOF
+  echo "  Configured claude-hud for agentic-loop (expanded layout, all panels)"
+}
+
 # Copy slash commands (skills format for Claude Code)
 setup_slash_commands() {
   local pkg_root="$1"
@@ -569,6 +678,8 @@ ${python_runner:+- Python: Use \`$python_runner\` (not bare \`python\`)}
     framework_template="$pkg_root/templates/examples/CLAUDE-${framework_type}.md"
   fi
 
+  local style_marker="<!-- vibe-and-thrive-detected -->"
+
   if [[ -f "CLAUDE.md" ]]; then
     # Append framework template if it exists and not already included
     if [[ -n "$framework_template" && -f "$framework_template" ]]; then
@@ -581,6 +692,16 @@ ${python_runner:+- Python: Use \`$python_runner\` (not bare \`python\`)}
         echo "  Appended ${framework_type} conventions to CLAUDE.md"
       fi
     fi
+    # Add writing style defaults if not already present
+    if ! grep -q "$style_marker" "CLAUDE.md" 2>/dev/null; then
+      cat >> CLAUDE.md << EOF
+
+$style_marker
+## Writing Style
+- Active voice only. Never use passive voice.
+- Never use em dashes. Use commas, periods, or parentheses instead.
+EOF
+    fi
     echo "$detected_section" >> CLAUDE.md
     echo "  Updated CLAUDE.md"
   else
@@ -590,6 +711,11 @@ ${python_runner:+- Python: Use \`$python_runner\` (not bare \`python\`)}
 
 ## Your Rules
 <!-- Add your project-specific rules, patterns, and conventions here -->
+
+<!-- vibe-and-thrive-detected -->
+## Writing Style
+- Active voice only. Never use passive voice.
+- Never use em dashes. Use commas, periods, or parentheses instead.
 EOF
 
     # Include framework template if available
@@ -715,20 +841,28 @@ setup_precommit_hooks() {
   # Create .pre-commit-config.yaml if it doesn't exist
   if [[ ! -f ".pre-commit-config.yaml" ]]; then
     cat > .pre-commit-config.yaml << 'EOF'
+# Pre-commit hooks powered by agentic-loop vibe-check
+# Runs on staged files before each commit
 repos:
-  - repo: https://github.com/allierays/agentic-loop
-    rev: v1.0.0
+  - repo: local
+    hooks:
+      - id: vibe-check
+        name: Vibe Check
+        entry: npx vibe-check --fail-on error
+        language: node
+        types_or: [javascript, ts, python, json]
+        pass_filenames: true
+
+  # Standard hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
     hooks:
-      - id: backup-db
-        name: Backup database before commit
-      - id: check-secrets
-        name: Check for hardcoded secrets
-      - id: check-hardcoded-urls
-        name: Check for hardcoded URLs
-      - id: check-debug
-        name: Check for debug statements
-      - id: check-signs-secrets
-        name: Check signs.json for credentials
+      - id: trailing-whitespace
+        exclude: '\.txt$'
+      - id: end-of-file-fixer
+        exclude: '\.txt$'
+      - id: check-yaml
+      - id: check-added-large-files
 EOF
     echo "  Created .pre-commit-config.yaml"
   else

package/ralph/utils.sh

@@ -34,6 +34,7 @@ readonly BROWSER_PAGE_TIMEOUT_MS=30000
 readonly CURL_TIMEOUT_SECONDS=10
 readonly SIGN_EXTRACTION_TIMEOUT_SECONDS=30
 readonly PREFLIGHT_CACHE_TTL_SECONDS=600
+readonly UPDATE_CHECK_TTL_SECONDS=86400  # Check for updates once per day
 
 # Common project directories (avoid duplication across files)
 readonly FRONTEND_DIRS=("apps/web" "frontend" "client" "web")
@@ -49,6 +50,51 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
+# Terminal background theming for Ralph
+# Saves original background color and applies a teal tint to visually
+# distinguish the Ralph terminal from Claude Code.
+# Only works in macOS Terminal.app — no-op on Linux, iTerm2, VS Code, etc.
+# Note: AppleScript targets "front window" (focused window) not the specific
+# window running the script. In practice this works because the user just
+# ran the command, but rapid window switching can cause a mismatch.
+_ORIGINAL_TERMINAL_BG=""
+
+set_terminal_bg() {
+  local hex="${1:-#1a2e2e}"  # Default: subtle dark teal
+
+  # Only works in Terminal.app
+  [[ "$TERM_PROGRAM" != "Apple_Terminal" ]] && return 0
+
+  # Save current background color for restore
+  _ORIGINAL_TERMINAL_BG=$(osascript -e 'tell application "Terminal" to get background color of front window' 2>/dev/null) || return 0
+
+  # Parse hex to 16-bit RGB values (Terminal.app uses 0-65535 range)
+  local r=$((16#${hex:1:2} * 257))
+  local g=$((16#${hex:3:2} * 257))
+  local b=$((16#${hex:5:2} * 257))
+
+  osascript -e "tell application \"Terminal\" to set background color of front window to {$r, $g, $b}" 2>/dev/null || true
+}
+
+restore_terminal_bg() {
+  [[ -z "$_ORIGINAL_TERMINAL_BG" ]] && return 0
+  [[ "$TERM_PROGRAM" != "Apple_Terminal" ]] && return 0
+
+  osascript -e "tell application \"Terminal\" to set background color of front window to {$_ORIGINAL_TERMINAL_BG}" 2>/dev/null || true
+  _ORIGINAL_TERMINAL_BG=""
+}
+
+# Set terminal tab title (works in Terminal.app, iTerm2, and most xterm-compatible terminals)
+set_tab_title() {
+  local title="$1"
+  printf '\033]0;%s\007' "$title"
+}
+
+# Restore tab title to default (empty = terminal decides)
+restore_tab_title() {
+  printf '\033]0;\007'
+}
+
 # Get existing frontend directories in this project
 get_frontend_dirs() {
   local dirs=()
@@ -410,6 +456,8 @@ create_temp_file() {
 
 # Clean up only tracked temp files on exit
 cleanup() {
+  restore_tab_title
+  restore_terminal_bg
   if [[ ${#RALPH_TEMP_FILES[@]} -gt 0 ]]; then
     for f in "${RALPH_TEMP_FILES[@]}"; do
       rm -f "$f" 2>/dev/null

package/templates/examples/CLAUDE-fullstack.md

@@ -249,9 +249,9 @@ make typecheck       # Check TypeScript types
 
 ## Workflow
 
-1. **Idea** - Run `/idea "feature description"` to brainstorm
-2. **Approve** - Review the idea file, then approve
-3. **PRD** - Review generated stories in `.ralph/prd.json`
+1. **PRD** - Run `/prd "feature description"` to generate stories
+2. **Review** - Review generated stories in `.ralph/prd.json`
+3. **Validate** - PRD validation checks story coherence
 4. **Run** - Execute `ralph run` for autonomous coding
 5. **Audit** - Run `/vibe-check` before shipping
 6. **Commit** - Pre-commit hooks catch remaining issues

package/templates/signs.json

@@ -48,6 +48,13 @@
       "category": "testing",
       "learnedFrom": null,
       "createdAt": "2026-01-25T00:00:00-08:00"
+    },
+    {
+      "id": "sign-008",
+      "pattern": "NEVER use import-checks as test steps (python -c 'from X import Y', hasattr, test -f). These only verify a symbol exists, not that it works. A function that raises on every call still passes an import check. Always use real behavioral tests: curl for API endpoints, pytest with actual function calls, or Playwright for UI.",
+      "category": "testing",
+      "learnedFrom": "Okta SSO PRD review — all 4 backend stories had import-check testSteps that would pass even with completely broken code",
+      "createdAt": "2026-02-17T00:00:00-08:00"
     }
   ]
 }