agentic-loop 3.23.0 → 3.27.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

@@ -118,6 +118,50 @@ _migrate_credentials_to_env() {
   echo ""
 }
 
+# Lightweight refresh after auto-update — syncs files from the new package version
+# without re-running interactive or first-time-only setup steps.
+setup_refresh() {
+  local pkg_root
+  pkg_root="$(cd "$RALPH_LIB/.." && pwd)"
+
+  echo "  Syncing updated files..."
+
+  # Re-copy slash commands/skills
+  setup_slash_commands "$pkg_root"
+
+  # Re-copy hooks (scripts + settings.json wiring)
+  setup_claude_hooks "$pkg_root"
+
+  # Merge any new default signs
+  if [[ -f ".ralph/signs.json" ]] && [[ -f "$pkg_root/templates/signs.json" ]] && command -v jq &>/dev/null; then
+    local existing_ids new_signs_added=0
+    existing_ids=$(jq -r '.signs[].id // empty' ".ralph/signs.json" 2>/dev/null | tr '\n' '|')
+
+    while IFS= read -r sign; do
+      local sign_id
+      sign_id=$(echo "$sign" | jq -r '.id // empty')
+      if [[ -n "$sign_id" && ! "$existing_ids" =~ "$sign_id" ]]; then
+        local tmp_file
+        tmp_file=$(mktemp)
+        jq --argjson new_sign "$sign" '.signs += [$new_sign]' ".ralph/signs.json" > "$tmp_file"
+        mv "$tmp_file" ".ralph/signs.json"
+        ((new_signs_added++)) || true
+      fi
+    done < <(jq -c '.signs[]' "$pkg_root/templates/signs.json" 2>/dev/null)
+
+    if [[ $new_signs_added -gt 0 ]]; then
+      echo "  Merged $new_signs_added new sign(s)"
+    fi
+  fi
+
+  # Append any new PROMPT.md sections
+  if [[ -f "PROMPT.md" ]] && [[ -f "$pkg_root/templates/PROMPT.md" ]]; then
+    append_prompt_sections "$pkg_root/templates/PROMPT.md" "PROMPT.md"
+  fi
+
+  print_success "  Setup refreshed"
+}
+
 ralph_setup() {
   echo ""
   echo "    _                    _   _        _                       "
@@ -186,7 +230,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 +242,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
@@ -252,7 +296,7 @@ setup_ralph_dir() {
           tmp_file=$(mktemp)
           jq --argjson new_sign "$sign" '.signs += [$new_sign]' ".ralph/signs.json" > "$tmp_file"
           mv "$tmp_file" ".ralph/signs.json"
-          ((new_signs_added++))
+          ((new_signs_added++)) || true
         fi
       done < <(jq -c '.signs[]' "$pkg_root/templates/signs.json" 2>/dev/null)
 
@@ -312,6 +356,7 @@ setup_gitignore() {
     ".ralph/tool-log.txt"
     ".ralph/suggested-signs.txt"
     ".ralph/.preflight_cache"
+    ".ralph/.last_version"
     ".ralph/.lock"
     ".backups/"
     ".claude/settings.json"
@@ -402,26 +447,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

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,70 @@ 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=""
+_ORIGINAL_TERMINAL_FG=""
+
+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 and text colors for restore
+  _ORIGINAL_TERMINAL_BG=$(osascript -e 'tell application "Terminal" to get background color of front window' 2>/dev/null) || return 0
+  _ORIGINAL_TERMINAL_FG=$(osascript -e 'tell application "Terminal" to get normal text color of front window' 2>/dev/null) || true
+
+  # 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
+
+  # If the background is dark, ensure text is light enough to read
+  # Calculate perceived brightness: (R*299 + G*587 + B*114) / 1000 (8-bit scale)
+  local r8=$((16#${hex:1:2}))
+  local g8=$((16#${hex:3:2}))
+  local b8=$((16#${hex:5:2}))
+  local brightness=$(( (r8 * 299 + g8 * 587 + b8 * 114) / 1000 ))
+
+  if [[ $brightness -lt 128 ]]; then
+    # Dark background — set light text (soft white: #e0e0e0)
+    osascript -e 'tell application "Terminal" to set normal text color of front window to {57568, 57568, 57568}' 2>/dev/null || true
+  fi
+}
+
+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=""
+
+  if [[ -n "$_ORIGINAL_TERMINAL_FG" ]]; then
+    osascript -e "tell application \"Terminal\" to set normal text color of front window to {$_ORIGINAL_TERMINAL_FG}" 2>/dev/null || true
+    _ORIGINAL_TERMINAL_FG=""
+  fi
+}
+
+# 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" >&2
+}
+
+# Restore tab title to default (empty = terminal decides)
+restore_tab_title() {
+  printf '\033]0;\007' >&2
+}
+
 # Get existing frontend directories in this project
 get_frontend_dirs() {
   local dirs=()
@@ -410,6 +475,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/.claude/commands/idea.md

@@ -1,216 +0,0 @@
----
-description: Brainstorm a feature idea, then generate PRDs for Ralph autonomous execution.
----
-
-# /idea - From Brainstorm to PRD
-
-You are helping the user go from a rough idea to executable PRDs for Ralph.
-
-**CRITICAL: This command does NOT write code. It produces documentation files only.**
-
-## When to Use
-
-| Workflow | Best For |
-|----------|----------|
-| **`/idea`** | Structured brainstorming with guided questions - Claude leads |
-| **Plan mode → save to `docs/ideas/`** | Free-form exploration - you lead the thinking |
-| **`/prd "description"`** | Quick PRD, no docs artifact needed |
-
-**Both `/idea` and plan mode can produce `docs/ideas/*.md` files.** The difference is who drives the conversation:
-- `/idea` asks you structured questions (scope, UX, edge cases, etc.)
-- Plan mode lets you explore freely with Claude's help
-
-Use `/idea` when you want the structured checklist. Use plan mode when you prefer to think through it your way.
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-## Workflow
-
-### Step 1: Start Brainstorming
-
-If `$ARGUMENTS` is empty, ask: "What feature or idea would you like to brainstorm?"
-
-If `$ARGUMENTS` has content, acknowledge it and proceed.
-
-Say: "Let's brainstorm this idea. I'll help you think it through, then we'll create documentation for Ralph to execute."
-
-### Step 2: Explore and Ask Questions
-
-Help the user flesh out the idea through conversation:
-
-1. **Understand the goal** - What problem does this solve? Who benefits?
-2. **Explore the codebase** - Use Glob/Grep/Read to understand what exists and what patterns to follow
-3. **Ask clarifying questions** about:
-
-**Scope & UX:**
-- What's in scope vs out of scope?
-- What does the user see/do? (ask for mockup if UI)
-- What are the edge cases?
-
-**Security (IMPORTANT - ask if feature involves):**
-- Authentication: Who can access this? Login required?
-- Passwords: How stored? (must be hashed, never plain text)
-- User input: What validation needed? (SQL injection, XSS, command injection)
-- Sensitive data: What should NEVER be in API responses?
-- Rate limiting: Should this be rate limited? (login attempts, API calls)
-
-**Scale (IMPORTANT - ask if feature involves lists/data):**
-- 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?
-
-### Step 3: Summarize Before Writing
-
-When you have enough information, summarize what you've learned:
-
-Say: "Here's what I understand about the feature:
-
-**Problem:** [summary]
-**Solution:** [summary]
-**Key decisions:** [list]
-
-Ready to write this to `docs/ideas/{feature-name}.md`? Say **'yes'** or tell me what to adjust."
-
-**STOP and wait for user confirmation before writing any files.**
-
-### Step 4: Write the Idea File
-
-Once the user confirms, write the idea file:
-
-1. Create the directory if needed:
-   ```bash
-   mkdir -p docs/ideas
-   ```
-
-2. Write to `docs/ideas/{feature-name}.md` with this structure:
-   ```markdown
-   # {Feature Name}
-
-   ## Problem
-   What problem does this solve?
-
-   ## Solution
-   High-level description of the solution.
-
-   ## User Stories
-   - As a [user], I want to [action] so that [benefit]
-   - ...
-
-   ## Scope
-   ### In Scope
-   - ...
-
-   ### Out of Scope
-   - ...
-
-   ## Architecture
-   ### Directory Structure
-   - Where new files should go (be specific: `src/components/forms/`, not just `src/`)
-
-   ### Patterns to Follow
-   - Existing components/utilities to reuse
-   - Naming conventions
-
-   ### Do NOT Create
-   - List things that already exist (avoid duplication)
-
-   ## Security Requirements
-   - **Authentication**: Who can access? Login required?
-   - **Password handling**: Must be hashed with bcrypt (cost 10+), never in responses
-   - **Input validation**: What must be validated/sanitized?
-   - **Rate limiting**: What should be rate limited?
-   - **Sensitive data**: What must NEVER appear in logs/responses?
-
-   ## Scale Requirements
-   - **Expected volume**: How many users/items/requests?
-   - **Pagination**: Max items per page (recommend 100)
-   - **Caching**: What can be cached? For how long?
-   - **Database**: What indexes are needed?
-
-   ## UI Mockup (if applicable)
-   ```
-   ┌─────────────────────────────────┐
-   │  [ASCII mockup of the UI]       │
-   └─────────────────────────────────┘
-   ```
-
-   ## Open Questions
-   - Any unresolved decisions
-   ```
-
-3. Say: "I've written the idea to `docs/ideas/{feature-name}.md`.
-
-   Review it and let me know:
-   - **'approved'** - Ready to generate PRD
-   - **'edit [changes]'** - Tell me what to change"
-
-**STOP and wait for user response. Do not proceed until they say 'approved' or 'done'.**
-
-### Step 5: Generate PRD
-
-**Only proceed here after user explicitly approves the idea file.**
-
-Say: "Now I'll generate the PRD from your idea file."
-
-**Use the Skill tool** to invoke `/prd` with the idea file path:
-```
-Skill: prd
-Args: docs/ideas/{feature-name}.md
-```
-
-This hands off to `/prd` which handles:
-- Reading the idea file
-- Splitting into stories
-- Writing `.ralph/prd.json`
-- All PRD schema details (testing, testSteps, MCP tools, etc.)
-
-**DO NOT duplicate the PRD schema or guidelines here - /prd is the single source of truth.**
-
----
-
-## Error Handling
-
-- If user provides no arguments, ask what they want to brainstorm
-- If user abandons mid-flow, the idea file is still saved for later
-- If /prd fails, check the idea file has enough detail
-
----
-
-## Guidelines
-
-### Idea File Quality
-
-A good idea file has:
-- **Clear problem statement** - What's broken or missing?
-- **Specific solution** - Not vague ("improve UX") but concrete ("add inline validation")
-- **Scope boundaries** - What's explicitly out of scope?
-- **Architecture hints** - Where do files go? What patterns to follow?
-
-### ASCII Art for UI
-
-If the feature involves UI, include ASCII mockups in the idea file:
-
-```
-┌─────────────────────────────────────┐
-│  Dashboard                    [⚙️]  │
-├─────────────────────────────────────┤
-│                                     │
-│  ┌─────────┐  ┌─────────┐          │
-│  │ Card 1  │  │ Card 2  │          │
-│  │  $1,234 │  │  89%    │          │
-│  └─────────┘  └─────────┘          │
-│                                     │
-│  ┌─────────────────────────────┐   │
-│  │ Recent Activity              │   │
-│  │ • Item 1                     │   │
-│  │ • Item 2                     │   │
-│  └─────────────────────────────┘   │
-└─────────────────────────────────────┘
-```
-
-Ralph will read these from the idea file via `story.contextFiles`.