agentic-loop 3.14.1 → 3.16.1

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

@@ -64,6 +64,12 @@ Help the user flesh out the idea through conversation:
 - 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:
@@ -132,6 +138,36 @@ Once the user confirms, write the idea file:
    - **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)
    ```
    ┌─────────────────────────────────┐
@@ -190,6 +226,26 @@ A good idea file has:
 - **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
 

package/.claude/skills/prd/SKILL.md

@@ -61,6 +61,8 @@ cat package.json 2>/dev/null | jq '{name, dependencies}' || true
 cat pyproject.toml 2>/dev/null | head -20 || true
 ```
 
+Use the detected tech stack, test runners, and constraints when building each story — these go into each story's `techStack`, `constraints`, and `testing.runner` fields (not at the PRD root).
+
 Then say: "I'll create a PRD for: **{description}**
 
 Before I generate stories, quick questions:
@@ -101,6 +103,7 @@ Break the idea into small, executable stories:
 - Max 3-4 acceptance criteria per story
 - Max 10 stories (suggest phases if more needed)
 - If appending, start IDs from the next available number
+- **Each story must include its own `techStack`, `constraints`, and `contextFiles`.** Include only what's relevant to that story — don't copy-paste identical context into every story.
 
 ### Step 5: Write Draft PRD
 
@@ -152,10 +155,13 @@ Does acceptanceCriteria include:
 - Query params → "Accepts ?page=N&limit=N"
 - Large datasets → "Database query uses index on [column]"
 
-#### 6e. Context (for frontend stories)
+#### 6e. Context (for all stories)
 - Does `contextFiles` include the idea file (has ASCII mockups)?
 - Does `contextFiles` include styleguide (if exists)?
-- Is `testUrl` set?
+- Does `techStack` include the relevant stack for this story?
+- Does `constraints` include any rules this story must follow?
+- For frontend: Is `testUrl` set?
+- For frontend: Is `mcp` set to `["playwright", "devtools"]`?
 
 **Fix any issues you find:**
 
@@ -168,6 +174,9 @@ Does acceptanceCriteria include:
 | List endpoint missing pagination | Add pagination criteria to acceptanceCriteria |
 | Frontend missing contextFiles | Add idea file + styleguide paths |
 | Frontend missing testUrl | Add URL from config |
+| Frontend missing mcp | Add `"mcp": ["playwright", "devtools"]` |
+| Story missing techStack | Add relevant subset of detected tech |
+| Story missing constraints | Add applicable rules for this story |
 
 ### Step 7: Reorder if Needed
 
@@ -229,45 +238,6 @@ Ralph will work through each story, running tests and committing as it goes."
     "status": "pending"
   },
 
-  "originalContext": "docs/ideas/{feature-name}.md",
-
-  "techStack": {
-    "frontend": "{detected from package.json}",
-    "backend": "{detected from pyproject.toml/go.mod}",
-    "database": "{detected or asked}"
-  },
-
-  "testing": {
-    "approach": "TDD",
-    "unit": {
-      "frontend": "{vitest|jest - detected from package.json}",
-      "backend": "{pytest|go test - detected from project}"
-    },
-    "integration": "{playwright|cypress}",
-    "e2e": "{playwright|cypress}",
-    "coverage": {
-      "minimum": 80,
-      "enforced": false
-    }
-  },
-
-  "architecture": {
-    "frontend": "src/components",
-    "backend": "src/api",
-    "doNotCreate": ["new database tables without migration"]
-  },
-
-  "globalConstraints": [
-    "All API calls must have error handling",
-    "No console.log in production code",
-    "Use existing UI components from src/components/ui"
-  ],
-
-  "testUsers": {
-    "admin": {"email": "admin@test.com", "password": "test123"},
-    "user": {"email": "user@test.com", "password": "test123"}
-  },
-
   "metadata": {
     "createdAt": "ISO timestamp",
     "estimatedStories": 5,
@@ -282,6 +252,17 @@ Ralph will work through each story, running tests and committing as it goes."
       "priority": 1,
       "passes": false,
 
+      "techStack": {
+        "frontend": "{detected from package.json}",
+        "backend": "{detected from pyproject.toml/go.mod}",
+        "database": "{detected or asked}"
+      },
+
+      "constraints": [
+        "Rules that apply to this story",
+        "E.g. Use existing UI components from src/components/ui"
+      ],
+
       "files": {
         "create": ["paths to new files"],
         "modify": ["paths to existing files"],
@@ -299,6 +280,7 @@ Ralph will work through each story, running tests and committing as it goes."
       "testing": {
         "types": ["unit", "integration"],
         "approach": "TDD",
+        "runner": "vitest|jest|pytest|go test",
         "files": {
           "unit": ["src/components/Dashboard.test.tsx"],
           "integration": ["tests/integration/dashboard.test.ts"],
@@ -330,6 +312,10 @@ Ralph will work through each story, running tests and committing as it goes."
         "response": {"field": "type"}
       },
 
+      "testUsers": {
+        "admin": {"email": "admin@test.com", "password": "test123"}
+      },
+
       "prerequisites": [
         "Backend server running",
         "Database seeded"
@@ -358,19 +344,15 @@ Ralph will work through each story, running tests and committing as it goes."
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `feature` | Yes | Feature name, branch, status |
-| `originalContext` | Yes | Path to idea file (Claude reads this for full context) |
-| `techStack` | No | Technologies in use (auto-detect from project) |
-| `testing` | Yes | Testing strategy, tools, coverage requirements |
-| `architecture` | No | Directory structure, patterns, constraints |
-| `globalConstraints` | No | Rules that apply to ALL stories |
-| `testUsers` | No | Test accounts for auth flows |
-| `metadata` | Yes | Created date, complexity estimate |
+| `feature` | Yes | Feature name, ideaFile, branch, status |
+| `metadata` | Yes | Created date, estimated stories, complexity |
 
 **Note:** URLs come from `.ralph/config.json`, not the PRD. Use `{config.urls.backend}` in testSteps.
 
 ### Story-Level Fields
 
+Each story is **self-contained** with all the context it needs. No global defaults — include only what's relevant to that story.
+
 | Field | Required | Description |
 |-------|----------|-------------|
 | `id` | Yes | Unique ID (TASK-001, TASK-002, etc.) |
@@ -378,16 +360,19 @@ Ralph will work through each story, running tests and committing as it goes."
 | `title` | Yes | Short description |
 | `priority` | No | Order of importance (1 = highest) |
 | `passes` | Yes | Always starts as `false` |
+| `techStack` | Yes | Technologies relevant to this story (auto-detect from project) |
+| `constraints` | No | Rules/constraints specific to this story |
 | `files` | Yes | create, modify, reuse arrays |
 | `acceptanceCriteria` | Yes | What must be true when done |
 | `errorHandling` | Yes | How to handle failures |
-| `testing` | Yes | Test types, approach, and files for this story |
+| `testing` | Yes | Test types, approach, runner, and files for this story |
 | `testSteps` | Yes | Executable shell commands |
 | `testUrl` | Frontend | URL to verify the feature |
 | `mcp` | Frontend | MCP tools for verification |
 | `contextFiles` | No | Files Claude should read (idea files, styleguides) |
 | `skills` | No | Relevant skills with usage hints |
 | `apiContract` | Backend | Expected request/response format |
+| `testUsers` | No | Test accounts (only for auth stories that need them) |
 | `prerequisites` | No | What must be running/ready |
 | `notes` | No | Human guidance for Claude |
 | `scale` | No | small, medium, large |
@@ -398,49 +383,22 @@ Ralph will work through each story, running tests and committing as it goes."
 
 ## Testing Strategy
 
-### PRD-Level Testing Config
-
-Define the overall testing strategy for the feature. **Auto-detect tools from project config files:**
+### Story-Level Testing Config
 
-```json
-"testing": {
-  "approach": "TDD",
-  "unit": {
-    "frontend": "vitest",
-    "backend": "pytest"
-  },
-  "integration": "playwright",
-  "e2e": "playwright",
-  "coverage": {
-    "minimum": 80,
-    "enforced": false
-  }
-}
-```
+Each story defines its own testing configuration. **Auto-detect tools from project config files** and include the relevant runner in each story:
 
 **Detection hints:**
 - Check `package.json` for `vitest`, `jest`, `playwright`, `cypress`
 - Check `pyproject.toml` for `pytest`
 - Check `go.mod` for Go projects (use `go test`)
 
-| Field | Values | Description |
-|-------|--------|-------------|
-| `approach` | `TDD`, `test-after` | Write tests first (TDD) or after implementation |
-| `unit.frontend` | `vitest`, `jest` | Frontend unit test runner (detect from package.json) |
-| `unit.backend` | `pytest`, `go test` | Backend unit test runner (detect from project) |
-| `integration` | `playwright`, `cypress` | Integration test tool |
-| `e2e` | `playwright`, `cypress` | End-to-end test tool |
-| `coverage.minimum` | `0-100` | Minimum coverage percentage |
-| `coverage.enforced` | `true/false` | Fail if coverage not met |
-
-### Story-Level Testing Config
-
-Specify what tests each story needs:
+**Note:** Coverage thresholds (`minimum`, `enforced`) belong in `.ralph/config.json`, not in the PRD.
 
 ```json
 "testing": {
   "types": ["unit", "integration"],
   "approach": "TDD",
+  "runner": "vitest",
   "files": {
     "unit": ["src/components/Dashboard.test.tsx"],
     "integration": ["tests/integration/dashboard.test.ts"],
@@ -452,7 +410,8 @@ Specify what tests each story needs:
 | Field | Description |
 |-------|-------------|
 | `types` | Required test types: `unit`, `integration`, `e2e` |
-| `approach` | Override PRD-level approach for this story |
+| `approach` | TDD or test-after for this story |
+| `runner` | Test runner command (vitest, jest, pytest, go test — detected from project) |
 | `files.unit` | Unit test files to create |
 | `files.integration` | Integration test files to create |
 | `files.e2e` | E2E test files to create |

package/.claude/skills/prd-check/SKILL.md

@@ -0,0 +1,48 @@
+---
+description: Run PRD validation to check story quality, test coverage, and structure.
+---
+
+# PRD Check
+
+Run PRD validation on demand to check story quality, test coverage, and structure before starting the autonomous loop.
+
+## Instructions
+
+When the user runs `/prd-check`, validate their PRD file.
+
+### Step 1: Check PRD Exists
+
+```bash
+ls -la .ralph/prd.json 2>/dev/null || echo "NOT_FOUND"
+```
+
+If no PRD exists, tell the user:
+> No PRD found at `.ralph/prd.json`. Generate one first with `/idea` or `/prd`.
+
+**STOP** if no PRD found.
+
+### Step 2: Run Validation (dry-run)
+
+Run validation without auto-fix so you can present results and let the user decide:
+
+```bash
+npx ralph prd-check --dry-run 2>&1
+```
+
+### Step 3: Present Results
+
+Show the validation output to the user. If there are issues, summarize them clearly.
+
+If issues were found, ask:
+> "Would you like me to fix these issues in the PRD?"
+
+**STOP and wait for user response.**
+
+If the user says yes, read `.ralph/prd.json`, fix the issues following PRD best practices (executable testSteps with curl/pytest/playwright, apiContract for backends, testUrl for frontends, security criteria for auth stories, pagination for list endpoints), and write the fixed file back.
+
+## Notes
+
+- This is the same validation that runs automatically at `ralph run` startup
+- `--dry-run` skips auto-fix so you have control over what changes
+- Custom checks in `.ralph/checks/prd/` are also evaluated
+- Run this before `ralph run` to catch and fix issues interactively

package/README.md

@@ -75,11 +75,14 @@ npx agentic-loop run         # Execute PRDs autonomously
 
 > **Tip:** Use two terminals. Plan with Claude in one, run Ralph in the other.
 
+For the full step-by-step walkthrough, see **[Getting Started](docs/GETTING-STARTED.md)**.
+
 ---
 
 ## Docs
 
-- **[Beginners Guide](docs/BEGINNERS.md)** - New to this? Start here (no coding experience required)
+- **[Getting Started](docs/GETTING-STARTED.md)** - Full walkthrough from zero to your first loop run
+- [Beginners Guide](docs/BEGINNERS.md) - New to this? Start here (no coding experience required)
 - [PRD Check](docs/PRD-CHECK.md) - Story validation before coding starts
 - [Code Check](docs/CODE-CHECK.md) - Verification pipeline after each story
 - [Customization](docs/CUSTOMIZATION.md) - Personalization and guardrails

package/bin/ralph.sh

@@ -148,6 +148,9 @@ main() {
     check)
       ralph_check "$@"
       ;;
+    prd-check|prdcheck)
+      ralph_prd_check "$@"
+      ;;
     verify)
       if [[ $# -lt 1 ]]; then
         print_error "Usage: ralph verify <story-id>"

package/dist/loopgram/prd-generator.d.ts

@@ -6,6 +6,8 @@ interface Story {
     acceptanceCriteria: string[];
     testSteps: string[];
     status: 'pending' | 'in_progress' | 'completed' | 'failed';
+    techStack?: Record<string, string>;
+    constraints?: string[];
 }
 /**
  * Generate PRD stories from a conversation

package/dist/loopgram/prd-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prd-generator.d.ts","sourceRoot":"","sources":["../../src/loopgram/prd-generator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAI1C,UAAU,KAAK;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,CAAC;CAC5D;AAmCD;;GAEG;AACH,wBAAsB,eAAe,CACnC,YAAY,EAAE,OAAO,EAAE,EACvB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,EAAE,CAAA;CAAE,CAAC,CAwChF;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,EAC1B,UAAU,EAAE,KAAK,EAAE,GAClB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA4CnD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG;IACjD,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CAwBP"}
+{"version":3,"file":"prd-generator.d.ts","sourceRoot":"","sources":["../../src/loopgram/prd-generator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAI1C,UAAU,KAAK;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAqCD;;GAEG;AACH,wBAAsB,eAAe,CACnC,YAAY,EAAE,OAAO,EAAE,EACvB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,EAAE,CAAA;CAAE,CAAC,CAwChF;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,EAC1B,UAAU,EAAE,KAAK,EAAE,GAClB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA4CnD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG;IACjD,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CAwBP"}

package/dist/loopgram/prd-generator.js

@@ -15,6 +15,8 @@ Output ONLY valid JSON in this exact format:
       "id": "kebab-case-id",
       "title": "Short title",
       "description": "What needs to be built",
+      "techStack": {"backend": "detected tech"},
+      "constraints": ["relevant rules for this story"],
       "acceptanceCriteria": ["Criterion 1", "Criterion 2"],
       "testSteps": ["npm test", "npm run lint"]
     }

package/dist/loopgram/prd-generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"prd-generator.js","sourceRoot":"","sources":["../../src/loopgram/prd-generator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prd-generator.js","sourceRoot":"","sources":["../../src/loopgram/prd-generator.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/ralph/hooks/protect-prd.sh

@@ -21,7 +21,7 @@ if [[ "$FILE_PATH" == *"prd.json"* ]]; then
     exit 2  # Exit code 2 = blocking error
   fi
 
-  # Allow all other prd.json edits (adding mcp, originalContext, fixing testSteps, etc.)
+  # Allow all other prd.json edits (adding mcp, constraints, fixing testSteps, etc.)
   echo '{"continue": true}'
   exit 0
 fi

package/ralph/loop.sh

@@ -181,9 +181,9 @@ run_loop() {
   local consecutive_timeouts=0
   local max_story_retries
   local max_timeouts=5  # Skip after 5 consecutive timeouts (likely too large/complex)
-  # Default to 15 retries - generous enough for transient issues, catches infinite loops
-  # Override with config.json: "maxStoryRetries": 25
-  max_story_retries=$(get_config '.maxStoryRetries' "15")
+  # Default to 8 retries - enough for transient issues, catches infinite loops
+  # Override with config.json: "maxStoryRetries": 12
+  max_story_retries=$(get_config '.maxStoryRetries' "8")
   local total_attempts=0
   local skipped_stories=()
   local start_time
@@ -265,7 +265,7 @@ run_loop() {
       "$RALPH_DIR/prd.json" > "$RALPH_DIR/prd.json.tmp" && mv "$RALPH_DIR/prd.json.tmp" "$RALPH_DIR/prd.json"
 
     # Circuit breaker: skip to next story after max retries (prevents infinite loops)
-    # Note: This is NOT meant to stop legitimate retrying - 15 attempts is generous.
+    # Note: This is NOT meant to stop legitimate retrying - 8 attempts is enough.
     # If a story consistently fails after this many tries, it likely needs manual review
     # (vague test steps, missing prerequisites, or fundamentally broken requirements).
     if [[ $consecutive_failures -gt $max_story_retries ]]; then
@@ -381,23 +381,42 @@ run_loop() {
     fi
 
     # Run Claude with crash detection and retry logic
-    local claude_output_log claude_exit_code max_crash_retries=3 crash_attempt=0
+    local claude_output_log claude_exit_code max_crash_retries=5 crash_attempt=0
     claude_output_log=$(create_temp_file ".log") || { rm -f "$prompt_file"; return 1; }
 
+    # Filter to hide ugly CLI crash messages from terminal (still captured in log)
+    # Strips: "This error originated...", "Error: No messages", stack traces
+    _filter_cli_noise() {
+      grep -v -E \
+        -e "This error originated either by throwing" \
+        -e "a catch block, or by rejecting a promise" \
+        -e "The promise rejected with the reason:" \
+        -e "Error: No messages returned" \
+        -e "at [A-Za-z0-9_]+ \(/\\\$bunfs/" \
+        -e "at processTicksAndRejections" \
+        -e "unhandled.*promise.*rejection" \
+        || true  # Don't fail if no lines pass filter
+    }
+
     while [[ $crash_attempt -lt $max_crash_retries ]]; do
       claude_exit_code=0
       # Use pipefail to capture Claude's exit code, not tee's
       set -o pipefail
-      cat "$prompt_file" | run_with_timeout "$timeout_seconds" claude "${claude_args[@]}" 2>&1 | tee "$claude_output_log" || claude_exit_code=$?
+      # Capture full output to log, show filtered output to terminal
+      cat "$prompt_file" | run_with_timeout "$timeout_seconds" claude "${claude_args[@]}" 2>&1 | tee "$claude_output_log" | _filter_cli_noise || claude_exit_code=$?
       set +o pipefail
 
-      # Check for recoverable CLI crashes
+      # Check for recoverable CLI crashes (transient API failures)
       if grep -qE "(No messages returned|unhandled.*promise.*rejection)" "$claude_output_log" 2>/dev/null; then
         ((crash_attempt++))
-        print_warning "Claude CLI crashed (attempt $crash_attempt/$max_crash_retries) - retrying..."
-        log_progress "$story" "CLI_CRASH" "Claude crashed, retry $crash_attempt"
+        # Exponential backoff: 5s, 10s, 20s, 40s, 80s
+        local backoff_seconds=$((5 * (2 ** (crash_attempt - 1))))
+        echo ""  # Clean line after any partial output
+        print_warning "API returned empty response - retrying in ${backoff_seconds}s (attempt $crash_attempt/$max_crash_retries)"
+        print_info "This is usually a transient issue with the Claude API"
+        log_progress "$story" "CLI_CRASH" "API empty response, retry $crash_attempt (backoff ${backoff_seconds}s)"
         session_started=false  # Reset session on crash
-        sleep 2  # Brief pause before retry
+        sleep "$backoff_seconds"
         continue
       fi
 
@@ -408,12 +427,13 @@ run_loop() {
     rm -f "$claude_output_log"
 
     if [[ $crash_attempt -ge $max_crash_retries ]]; then
-      print_error "Claude CLI crashed $max_crash_retries times - stopping loop"
-      log_progress "$story" "CLI_CRASH" "Gave up after $max_crash_retries crashes"
-      rm -f "$prompt_file"
       echo ""
-      echo "Claude CLI is unstable. Try again with: ralph run $story"
-      return 1
+      print_warning "Claude API unavailable after $max_crash_retries attempts"
+      print_info "Waiting 60s before retrying... (Ctrl+C to stop, then 'npx agentic-loop run' to restart)"
+      log_progress "$story" "CLI_CRASH" "API unavailable, waiting 60s before next iteration"
+      rm -f "$prompt_file"
+      sleep 60  # Longer cooldown before retrying
+      continue  # Continue main loop instead of stopping
     fi
 
     if [[ $claude_exit_code -ne 0 ]]; then
@@ -683,6 +703,8 @@ build_prompt() {
   echo "## Current Story: $story"
   echo ""
   echo "Read full story details from \`.ralph/prd.json\` - it contains everything you need:"
+  echo "- \`story.techStack\` - technologies relevant to this story"
+  echo "- \`story.constraints\` - rules for this story"
   echo "- \`story.files\` - which files to create/modify"
   echo "- \`story.acceptanceCriteria\` - what must be true"
   echo "- \`story.testSteps\` - verification commands"
@@ -691,8 +713,6 @@ build_prompt() {
   echo "- \`story.skills\` - relevant skills to reference"
   echo ""
   echo "Also read:"
-  echo "- \`prd.techStack\` - technologies in use"
-  echo "- \`prd.globalConstraints\` - rules for all stories"
   echo "- \`.ralph/config.json\` - URLs and directories"
 
   # Failure context if retrying