agentic-loop 3.26.0 → 3.27.1

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

@@ -6,8 +6,6 @@ description: Rename the current terminal tab so you can tell your Claude Code ta
 
 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`
@@ -27,20 +25,47 @@ 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:
+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
-# 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
+printf '\033]1337;SetUserVar=tab_title=%s\007' "$(echo -n 'TAB_NAME' | base64)"
 ```
 
-If that fails (not Terminal.app), try iTerm2:
+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
 ```
 
-**Important:** Escape any double quotes in the tab name before embedding in the AppleScript string.
+### 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
 
@@ -48,6 +73,4 @@ 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'`"
+> **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/skills/prd/SKILL.md

@@ -24,9 +24,11 @@ $ARGUMENTS
    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. 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'`)"
+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 plan file** (`plans/` prefix, `docs/plans/` path, or full path to a plan file):
 - If it's a full path, use it directly
@@ -122,9 +124,13 @@ Say: "Before I generate stories, I want to make sure we've covered the key areas
 - 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').
+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
 
@@ -133,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).
-
-Options:
-- **'append'** - Add new stories to the existing PRD (recommended)
-- **'overwrite'** - Replace it entirely
-- **'cancel'** - Stop here"
+"`.ralph/prd.json` exists with {N} stories ({M} completed, {P} pending). I'll append new stories to it."
 
-**STOP and wait for user choice.**
+**Default behavior is append** — just proceed. Do NOT ask for confirmation unless the user explicitly says "overwrite" or "replace".
 
-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
@@ -332,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
 

package/bin/ralph.sh

@@ -152,6 +152,12 @@ main() {
         echo ""
         exit 1
       fi
+      # Auto-refresh skills/hooks/signs when the package version changes
+      local version_file="$RALPH_DIR/.last_version"
+      if [[ ! -f "$version_file" ]] || [[ "$(cat "$version_file" 2>/dev/null)" != "$RALPH_VERSION" ]]; then
+        setup_refresh
+        echo "$RALPH_VERSION" > "$version_file"
+      fi
       # Clear any previous stop signal
       rm -f "$RALPH_DIR/.stop"
       run_loop "$@"

package/package.json

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

package/ralph/loop.sh

@@ -92,7 +92,8 @@ check_for_updates() {
     if $update_cmd 2>&1 | tail -3; then
       print_success "  Updated to v$latest — restarting..."
       echo ""
-      # Re-exec ralph.sh with "run" + original args
+      # Re-exec ralph.sh — version-change detection in the run path
+      # will auto-refresh skills, hooks, and signs from the new package
       local ralph_bin
       ralph_bin="$(cd "$(dirname "${BASH_SOURCE[0]}")/../bin" && pwd)/ralph.sh"
       exec "$ralph_bin" run "$@"
@@ -681,8 +682,8 @@ _docker_safety_warning() {
   echo "  ║   and executes migrations without asking.                        ║"
   echo "  ║                                                                  ║"
   echo "  ║   Without Docker, Ralph operates directly on your local          ║"
-  echo "  ║   machine. A bad migration can corrupt real databases.           ║"
-  echo "  ║   A runaway command can affect services outside this repo.       ║"
+  echo "  ║   machine. A runaway command can affect services outside        ║"
+  echo "  ║   this repo.                                                    ║"
   echo "  ║                                                                  ║"
   echo "  ║   With Docker, your project's services are isolated:             ║"
   echo "  ║     - Databases and caches run in containers, not locally        ║"
@@ -722,8 +723,9 @@ _docker_safety_warning() {
 }
 
 run_loop() {
-  # Save original args for update restart
-  local _original_args=("$@")
+  # Save original args for update restart (explicit empty init for Bash 3.2 compatibility)
+  local _original_args=()
+  [[ $# -gt 0 ]] && _original_args=("$@")
 
   # PID of the currently running Claude pipeline (used by trap to kill it)
   _CLAUDE_PIPELINE_PID=""
@@ -794,7 +796,7 @@ run_loop() {
   check_dependencies
 
   # Check for newer version on npm (once per day, non-blocking if offline)
-  check_for_updates "${_original_args[@]}"
+  check_for_updates "${_original_args[@]+"${_original_args[@]}"}"
 
   # Warn if no Docker compose file (safety net for autonomous execution)
   _docker_safety_warning

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 "    _                    _   _        _                       "
@@ -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"

package/ralph/utils.sh

@@ -58,6 +58,7 @@ NC='\033[0m' # No Color
 # 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
@@ -65,8 +66,9 @@ set_terminal_bg() {
   # Only works in Terminal.app
   [[ "$TERM_PROGRAM" != "Apple_Terminal" ]] && return 0
 
-  # Save current background color for restore
+  # 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))
@@ -74,6 +76,18 @@ set_terminal_bg() {
   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() {
@@ -82,17 +96,22 @@ restore_terminal_bg() {
 
   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"
+  printf '\033]0;%s\007' "$title" >&2
 }
 
 # Restore tab title to default (empty = terminal decides)
 restore_tab_title() {
-  printf '\033]0;\007'
+  printf '\033]0;\007' >&2
 }
 
 # Get existing frontend directories in this project