agentic-loop 3.23.0 → 3.26.0

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/.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`.

package/.claude/skills/idea/SKILL.md

@@ -1,272 +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?
-
-**Migration/Refactoring (IMPORTANT - ask if moving or restructuring code):**
-- Source paths: Where does the code currently live?
-- Destination paths: Where should it end up? (be explicit, not vague)
-- Phases: What's the logical order? (move files → update imports → verify)
-- Verification: What commands prove each phase worked?
-
-### 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?
-
-   ## Migration Mapping (if moving/restructuring code)
-   For refactoring or migration tasks, explicitly map source to destination:
-
-   | Source | Destination |
-   |--------|-------------|
-   | `~/Sites/old-project/src/` | `apps/new-location/src/` |
-   | `~/Sites/old-project/tests/` | `apps/new-location/tests/` |
-
-   ## Phases & Verification
-   Break complex work into phases with explicit verification commands:
-
-   ### Phase 1: [Name]
-   **What:** Description of what this phase accomplishes
-   **Exit Criteria:**
-   ```bash
-   # These commands must pass before phase is complete
-   test -d apps/new-location/src
-   cd apps/new-location && uv run pytest -x
-   cd apps/new-location && npm run build
-   ```
-
-   ### Phase 2: [Name]
-   **What:** Description
-   **Exit Criteria:**
-   ```bash
-   # Verification commands for phase 2
-   docker-compose config | grep -q 'service-name:'
-   curl -s http://localhost:8000/health | jq -e '.status == "ok"'
-   ```
-
-   ## 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?
-- **Verification commands** - How do we know it worked? (executable commands, not prose)
-
-### Migration/Refactoring Ideas
-
-For ideas that involve moving or restructuring code, MUST include:
-
-1. **Explicit path mapping** - Source → Destination for every directory
-   ```
-   ❌ "Move GOPA to apps folder"
-   ✅ "~/Sites/gopa/src/gopa/ → apps/gopa/src/gopa/"
-   ```
-
-2. **Phase-based verification** - Each phase has exit criteria with commands
-   ```
-   ❌ "Verify everything still works"
-   ✅ "cd apps/gopa && uv run pytest -x && uv run python -c 'from gopa.server import mcp'"
-   ```
-
-3. **Order of operations** - What must happen before what?
-   - Move files → Update imports → Update configs → Verify
-
-### 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`.