agentic-loop 3.23.0 → 3.26.0

package/README.md

@@ -12,34 +12,33 @@ You describe what you want to build. Claude Code writes a PRD (Product Requireme
 
 ```
 ┌──────────────────────────────────────────────────────────────────────────────────┐
-│  TERMINAL 1: Claude CLI                │  TERMINAL 2: Execute                    │
+│  TERMINAL 1: Plan & Generate           │  TERMINAL 2: Execute                    │
 ├────────────────────────────────────────┼─────────────────────────────────────────┤
 │                                        │                                         │
-│  claude                                │                                         │
-|(--dangerously-skip-permissions)        │  npx agentic-loop run                   │
+│  claude --dangerously-skip-permissions │  npx agentic-loop run                   │
 │                                        │                                         │
-│  PLAN FEATURES                         │  ┌─ prd-check (once) ───────────────┐   │
-│  /idea 'your feature or bugfix'        │  │ Validate all stories upfront     │   │
-│  → Claude asks questions               │  │ Auto-fix missing test steps      │   │
-│  → Explores codebase                   │  └──────────────────────────────────┘   │
-│  → Generates PRD                       │            ↓                            │
-|  (using claude code plan mode?)        │
-|  → use /prd filename.md                │
-|    on the plan file generated by claude|
-│  ENHANCE AS YOU LEARN                  │   ──────────────────────────────────    │ 
-│  → Add signs when Ralph repeats        │  │ Read prd.json → get next story   │   │
-│    the same mistake                    │  │ Load PROMPT.md, signs, config    │   │
-│  → Tune timeouts, retries, checks      │  │ Load last_failure.txt (if retry) │   │
-│  → Refine test commands for your       │  │ Build prompt with full context   │   │
-│    stack                               │  │ Spawn Claude → write code        │   │
-│                                        │  │                                  │   │
-│  (OPTIONAL) CUSTOMIZE YOUR LOOP        │  │ code-check:                      │   │
-│  /my-dna      → your coding style      │  │   [1] Lint                       │   │
-│  /styleguide  → UI consistency         │  │   [2] Tests                      │   │
+│  THE PIPELINE                          │  ┌─ prd-check (once) ───────────────┐   │
+│  1. Plan mode                          │  │ Validate all stories upfront     │   │
+│     → Think through the feature        │  │ Auto-fix missing test steps      │   │
+│     → Claude explores codebase         │  └──────────────────────────────────┘   │
+│     → Plan saved to docs/plans/        │            ↓                            │
+│                                        │                                         │
+│  2. /prd plans/my-feature              │  ┌──────────────────────────────────┐   │
+│     → Hardening questions              │  │ Read prd.json → get next story   │   │
+│     → Generates .ralph/prd.json        │  │ Load PROMPT.md, signs, config    │   │
+│                                        │  │ Load last_failure.txt (if retry) │   │
+│  3. /prd-check                         │  │ Build prompt with full context   │   │
+│     → Validate stories                 │  │ Spawn Claude → write code        │   │
+│     → Cross-ref signs                  │  │                                  │   │
+│     → Auto-fix issues                  │  │ code-check:                      │   │
+│                                        │  │   [1] Lint                       │   │
+│  ENHANCE AS YOU LEARN                  │  │   [2] Tests                      │   │
 │  /sign        → teach patterns         │  │   [3] PRD test steps             │   │
-│  config.json  → tune your setup        │  │   [4] API smoke                  │   │
-│                                        │  │   [5] Frontend smoke             │   │
-│                                        │  │                                  │   │
+│  /my-dna      → your coding style      │  │   [4] API smoke                  │   │
+│  /styleguide  → UI consistency         │  │   [5] Frontend smoke             │   │
+│  /color       → terminal tint          │  │                                  │   │
+│  /tab-rename  → name your tabs         │  │                                  │   │
+│  config.json  → tune your setup        │  │                                  │   │
 │                                        │  │ Pass → commit, next story        │   │
 │                                        │  │ Fail → save to last_failure.txt, │   │
 │                                        │  │        retry                     │   │
@@ -48,10 +47,10 @@ You describe what you want to build. Claude Code writes a PRD (Product Requireme
 └────────────────────────────────────────┴─────────────────────────────────────────┘
 ```
 
-**Terminal 1** is where you shape *what* gets built and *how* Ralph builds it.
-**Terminal 2** is where Ralph executes autonomously.
+**Terminal 1** is where you plan and generate. Plan mode lets you think through a feature with Claude before committing to code. `/prd` turns that plan into executable stories. `/prd-check` validates them.
+**Terminal 2** is where Ralph executes autonomously — coding, testing, and committing each story in a loop.
 
-Your loop gets smarter over time. When Ralph struggles with something, add a sign. When tests flake, tune the config. The customization never really stops—it's how you make Ralph work for *your* project.
+The loop gets smarter over time. When Ralph struggles with something, teach it with `/sign`. Tune timeouts and checks in `config.json`. Capture your coding style with `/my-dna`.
 
 ---
 
@@ -64,26 +63,29 @@ npm install agentic-loop
 npx agentic-loop setup
 ```
 
-**Terminal 1 - Claude Code:**
+**Terminal 1 — Plan and generate with Claude:**
 ```bash
-claude  (optinally you cna use, but you don't need it --dangerously-skip-permissions)
-/tour                    # Guided walkthrough (recommended first time)
-/idea 'your feature'     # Generate a PRD
+claude --dangerously-skip-permissions
 
----
-# Already have an idea/plan/PRD file? 
-/prd   #Run the /prd command to turn any file into a prd.json
+# 1. Use plan mode to think through your feature
+#    Claude explores the codebase, you discuss, plan saved to docs/plans/
+
+# 2. Turn the plan into executable stories
+/prd plans/my-feature
+
+# 3. Validate before running
+/prd-check
 ```
 
-**Terminal 2 - Ralph Loop:**
+**Terminal 2 — Run the loop:**
 ```bash
-npx agentic-loop run         # Execute PRDs autonomously (Spins up claude -p)
+npx agentic-loop run         # Execute PRDs autonomously (spins up claude -p)
 npx agentic-loop run --quiet # Same, but suppress activity feed
 ```
 
-Ralph shows a live activity feed as it works — what files it's reading, what code it's writing, and why. Use `--quiet` to suppress it.
+Ralph shows a live activity feed as it works — what files it's reading, what code it's writing, and why. Use `--quiet` to suppress it. On macOS Terminal.app, Ralph tints the terminal background dark teal so you can tell the two terminals apart at a glance — the original color is restored when the loop ends.
 
-> **Tip:** Use two terminals. Plan with Claude in one, run Ralph in the other.
+> **Tip:** Plan first, then generate. Use plan mode to explore and think, `/prd` to create stories, `/prd-check` to validate, and `ralph run` to execute.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-loop",
-  "version": "3.23.0",
+  "version": "3.26.0",
   "description": "Autonomous AI coding loop - PRD-driven development with Claude Code",
   "author": "Allie Jones <allie@allthrive.ai>",
   "license": "MIT",

package/ralph/hooks/install.sh

@@ -108,70 +108,54 @@ if [[ "$FORCE" != "true" ]] && jq -e '.hooks' "$SETTINGS_FILE" > /dev/null 2>&1;
   fi
 fi
 
-# Build hooks config with actual path
-HOOKS_CONFIG=$(cat <<EOF
-{
-  "PostToolUse": [
-    {
-      "matcher": "Edit|Write",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/warn-debug.sh",
-          "timeout": 5
-        },
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/warn-secrets.sh",
-          "timeout": 5
-        },
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/warn-urls.sh",
-          "timeout": 5
-        },
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/warn-empty-catch.sh",
-          "timeout": 5
-        }
-      ]
-    },
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/log-tools.sh",
-          "timeout": 3
-        }
-      ]
-    }
-  ],
-  "SessionStart": [
-    {
-      "hooks": [
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/inject-context.sh",
-          "timeout": 5
-        }
-      ]
-    }
-  ],
-  "Stop": [
-    {
-      "hooks": [
-        {
-          "type": "command",
-          "command": "$SCRIPT_DIR/save-learnings.sh",
-          "timeout": 10
-        }
-      ]
-    }
-  ]
+# Wrap hook path with existence check so missing files don't produce errors
+_safe_cmd() {
+  local path="$1"
+  printf 'if [ -f "%s" ]; then "%s"; else echo '"'"'{"continue": true}'"'"'; fi' "$path" "$path"
 }
-EOF
+
+# Build hooks config using jq for proper JSON escaping
+HOOKS_CONFIG=$(jq -n \
+  --arg warn_debug "$(_safe_cmd "$SCRIPT_DIR/warn-debug.sh")" \
+  --arg warn_secrets "$(_safe_cmd "$SCRIPT_DIR/warn-secrets.sh")" \
+  --arg warn_urls "$(_safe_cmd "$SCRIPT_DIR/warn-urls.sh")" \
+  --arg warn_empty_catch "$(_safe_cmd "$SCRIPT_DIR/warn-empty-catch.sh")" \
+  --arg log_tools "$(_safe_cmd "$SCRIPT_DIR/log-tools.sh")" \
+  --arg inject_context "$(_safe_cmd "$SCRIPT_DIR/inject-context.sh")" \
+  --arg save_learnings "$(_safe_cmd "$SCRIPT_DIR/save-learnings.sh")" \
+  '{
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {"type": "command", "command": $warn_debug, "timeout": 5},
+          {"type": "command", "command": $warn_secrets, "timeout": 5},
+          {"type": "command", "command": $warn_urls, "timeout": 5},
+          {"type": "command", "command": $warn_empty_catch, "timeout": 5}
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {"type": "command", "command": $log_tools, "timeout": 3}
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {"type": "command", "command": $inject_context, "timeout": 5}
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {"type": "command", "command": $save_learnings, "timeout": 10}
+        ]
+      }
+    ]
+  }'
 )
 
 # Merge hooks into settings

package/ralph/init.sh

@@ -13,7 +13,7 @@ ralph_init() {
   echo "Initializing ralph..."
 
   # Create directory structure
-  mkdir -p "$RALPH_DIR/archive" "$RALPH_DIR/screenshots"
+  mkdir -p "$RALPH_DIR/archive" "$RALPH_DIR/screenshots" "$RALPH_DIR/hooks"
 
   # Detect project type and generate appropriate config
   local project_type
@@ -68,7 +68,7 @@ ralph_init() {
   echo "Next steps:"
   echo "  1. Review .ralph/config.json (test credentials, checks, etc.)"
   echo "  2. Generate PRD:"
-  echo "     - Thorough: /idea 'feature description' (brainstorm + architecture + scalability)"
+  echo "     - Thorough: /prd 'feature description' (brainstorm + architecture + scalability)"
   echo "     - Quick:    ralph prd 'feature description' (basic PRD)"
   echo "  3. Start loop: ralph run"
 }
@@ -677,7 +677,7 @@ What is this?
     commands without asking permission each time. This enables fluid,
     uninterrupted collaboration while you brainstorm and refine ideas.
 
-    Use /idea to brainstorm big features. Claude saves your ideas to
+    Use /prd to brainstorm big features. Claude saves your ideas to
     docs/ideas/, then breaks them into small, executable PRDs.
 
   Terminal 2 - Ralph (autonomous execution):
@@ -690,7 +690,7 @@ What is this?
 Quick Start:
   1. npx agentic-loop setup
   2. Terminal 1: claude --dangerously-skip-permissions
-  3. In Claude: /idea "your feature description"
+  3. In Claude: /prd "your feature description"
   4. Terminal 2: npx agentic-loop run
   5. Monitor Terminal 2 - it should be autonomous. If issues come up,
      stop the loop (Ctrl+C) and paste the errors into Terminal 1.
@@ -729,12 +729,12 @@ Commands:
   help                    Show this help message
 
 PRD Generation:
-  /idea <description>           Thorough brainstorm (in Claude Code)
+  /prd <description>            Thorough brainstorm (in Claude Code)
   npx agentic-loop prd <notes>     Quick PRD generation
 
 Examples:
   npm install agentic-loop && npx agentic-loop setup
-  /idea "Add user authentication with OAuth"
+  /prd "Add user authentication with OAuth"
   npx agentic-loop prd "Add a contact form"
   npx agentic-loop run
   npx agentic-loop run --max 10

package/ralph/loop.sh

@@ -2,6 +2,107 @@
 # shellcheck shell=bash
 # loop.sh - The autonomous development loop
 
+# Check for newer version on npm and offer to update
+check_for_updates() {
+  local cache_file="$RALPH_DIR/.update_cache"
+
+  # Skip if checked recently (once per day)
+  if [[ -f "$cache_file" ]]; then
+    local cached_time
+    read -r cached_time _ < "$cache_file"
+    local now
+    now=$(date +%s)
+    if [[ $(( now - cached_time )) -lt $UPDATE_CHECK_TTL_SECONDS ]]; then
+      return 0
+    fi
+  fi
+
+  local latest
+  latest=$(timeout 5 npm view agentic-loop version --json 2>/dev/null | tr -d '"' || echo "")
+  # Fall back to gtimeout on macOS if timeout isn't available
+  if [[ -z "$latest" ]] && command -v gtimeout &>/dev/null; then
+    latest=$(gtimeout 5 npm view agentic-loop version --json 2>/dev/null | tr -d '"' || echo "")
+  fi
+
+  # Write cache regardless of result (don't retry on failure)
+  echo "$(date +%s) $latest" > "$cache_file"
+
+  # If registry unreachable or empty, skip silently
+  [[ -z "$latest" ]] && return 0
+
+  # Compare versions — if already current or newer, skip
+  if [[ "$RALPH_VERSION" == "$latest" ]]; then
+    return 0
+  fi
+
+  # Simple semver comparison: split on dots and compare numerically
+  local IFS='.'
+  # shellcheck disable=SC2206  # Intentional word-split on IFS='.'
+  local -a current_parts=($RALPH_VERSION)
+  # shellcheck disable=SC2206
+  local -a latest_parts=($latest)
+
+  local i
+  for i in 0 1 2; do
+    local c="${current_parts[$i]:-0}"
+    local l="${latest_parts[$i]:-0}"
+    if [[ "$c" -gt "$l" ]]; then
+      return 0  # Current is ahead (dev build)
+    elif [[ "$c" -lt "$l" ]]; then
+      break  # Current is behind — needs update
+    fi
+  done
+
+  echo ""
+  print_warning "Update available: v$RALPH_VERSION → v$latest"
+
+  # Detect install method to determine update command
+  local update_cmd=""
+  local script_path
+  script_path="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+  if [[ "$script_path" == *"node_modules/agentic-loop"* ]]; then
+    # Local install
+    update_cmd="npm update agentic-loop"
+  elif npm list -g agentic-loop --depth=0 &>/dev/null 2>&1; then
+    # Global install
+    update_cmd="npm update -g agentic-loop"
+  else
+    # npx or unknown — use npx with latest
+    update_cmd="npx agentic-loop@latest"
+  fi
+
+  read -r -p "  Update now and restart? [Y/n] " response
+  if [[ "$response" =~ ^[Nn] ]]; then
+    echo "  Skipping update. Run: $update_cmd"
+    echo ""
+    return 0
+  fi
+
+  echo "  Updating..."
+  if [[ "$update_cmd" == "npx agentic-loop@latest" ]]; then
+    # For npx users, clear the cache so next npx call fetches latest
+    local npx_cache
+    npx_cache=$(npm config get cache 2>/dev/null || echo "$HOME/.npm")
+    rm -rf "${npx_cache}/_npx" 2>/dev/null || true
+    print_success "  npx cache cleared — restarting with v$latest..."
+    echo ""
+    exec npx agentic-loop@latest run "$@"
+  else
+    if $update_cmd 2>&1 | tail -3; then
+      print_success "  Updated to v$latest — restarting..."
+      echo ""
+      # Re-exec ralph.sh with "run" + original args
+      local ralph_bin
+      ralph_bin="$(cd "$(dirname "${BASH_SOURCE[0]}")/../bin" && pwd)/ralph.sh"
+      exec "$ralph_bin" run "$@"
+    else
+      print_warning "  Update failed. Run manually: $update_cmd"
+      echo ""
+    fi
+  fi
+}
+
 # Pre-loop checks to catch common issues before wasting iterations
 preflight_checks() {
   echo ""
@@ -621,6 +722,9 @@ _docker_safety_warning() {
 }
 
 run_loop() {
+  # Save original args for update restart
+  local _original_args=("$@")
+
   # PID of the currently running Claude pipeline (used by trap to kill it)
   _CLAUDE_PIPELINE_PID=""
 
@@ -630,6 +734,8 @@ run_loop() {
   # pipeline in a background subshell and `wait`ing for it, which lets the trap
   # fire immediately. The trap kills the subshell, touches .stop, then exits.
   trap '
+    restore_tab_title
+    restore_terminal_bg
     echo ""
     print_warning "Ctrl+C received — stopping loop..."
     [[ -n "$_CLAUDE_PIPELINE_PID" ]] && kill -TERM "$_CLAUDE_PIPELINE_PID" 2>/dev/null
@@ -638,6 +744,18 @@ run_loop() {
     exit 130
   ' INT
 
+  # Tint terminal background so Ralph's terminal is visually distinct
+  local tint_color
+  tint_color=$(get_config '.terminalTint' "#1a2e2e")
+  if [[ "$tint_color" != "off" ]]; then
+    set_terminal_bg "$tint_color"
+  fi
+
+  # Set tab title to project name so the Ralph terminal is identifiable
+  local project_name
+  project_name=$(basename "$(pwd)")
+  set_tab_title "Ralph: $project_name"
+
   local max_iterations=""  # No cap by default — per-story circuit breaker is the safety net
   local specific_story=""
   local fast_mode=false
@@ -675,6 +793,9 @@ run_loop() {
   # Validate prerequisites
   check_dependencies
 
+  # Check for newer version on npm (once per day, non-blocking if offline)
+  check_for_updates "${_original_args[@]}"
+
   # Warn if no Docker compose file (safety net for autonomous execution)
   _docker_safety_warning
 
@@ -720,9 +841,9 @@ run_loop() {
       echo ""
       echo "  2. Inside Claude, type:"
       echo ""
-      echo "       /idea \"your feature description\""
+      echo "       /prd \"your feature description\""
       echo ""
-      echo "  Note: /idea is a Claude skill — it only works inside an active"
+      echo "  Note: /prd is a Claude skill — it only works inside an active"
       echo "  Claude session, not from your regular terminal."
       echo ""
       echo "  See Step 4 of the Getting Started guide:"
@@ -938,6 +1059,9 @@ run_loop() {
     passed_stories=$(jq '[.stories[] | select(.passes==true)] | length' "$RALPH_DIR/prd.json")
     current_num=$((passed_stories + 1))
 
+    # Update tab title with current story
+    set_tab_title "Ralph: $story — $story_title"
+
     # Display dynamic banner (truncate long text to fit box)
     local max_width=53
     local display_title="$story_title"
@@ -1700,6 +1824,6 @@ archive_feature() {
   echo "All stories passed! PRD kept at: $RALPH_DIR/prd.json"
   echo ""
   echo "Next:"
-  echo "  Start a Claude Code session and run /idea to brainstorm your next feature."
+  echo "  Start a Claude Code session and run /prd to brainstorm your next feature."
   echo "  ralph status            # See completed stories"
 }

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

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

@@ -186,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"
@@ -198,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
@@ -402,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