agentic-loop 3.0.0 → 3.1.0

package/README.md

@@ -2,237 +2,89 @@
 
 **Autonomous AI coding loop for Claude Code.**
 
-A toolkit for implementing [RALPH](https://ghuntley.com/ralph/) with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that helps you go from idea to shipped code.
+You describe what you want to build. Claude Code writes a PRD (Product Requirements Document) with small, testable stories. Ralph executes each story automatically - coding, testing, and committing in a loop until everything passes.
 
-> **Optimized for:** Python, TypeScript, React, Go/Hugo, and Docker projects. Auto-detects ports from `docker-compose.yml`, Vite, Next.js, Hugo, FastAPI, and more.
-
-> You focus on what matters: your ideas. Brainstorm with `/idea`, then let Ralph handle the rest - coding, testing, and committing in an iterative loop until everything passes.
-
-### This repo helps you customize your code output, run autonomous coding loops, and adds guardrails to ensure good code little and often:
-#### Customize
-- **`/my-dna`** - Add your own voice and values to your claude.md (This helps you personalize your experience and output)
-- **`/styleguide`** - Generate a UI component reference for consistent design (Stop AI from generating everything in purple add your unique style in an html and then reference it)
-
-#### Autonomous Code Loops with RALPH principles
-Run this in the terminal not in a claude cli session. It will use your claude subscription not an API key.
-- **`npx agentic-loop run`** - RALPH Autonomous loop: Brainstorm ideas → turn ideas into atomic prds → implement → verify → commit → repeat
-- **`npx agentic-loop run --fast`** - Fast mode: skips code review for quicker iterations (~2-3 min/story vs 5-8 min)
-
-#### Guardrails
-- **`/vibe-check`** - manually run the same automated tests and guardrail checks at any time
-- **`/review`** - manually run the same automated Security-focused code review with OWASP checks
-- **Pre-commit hooks** - Automatically block secrets, hardcoded URLs, and security issues with precommit hooks from entering into your git repo. Catch and fix issues before your CI/CD does
-- **Claude Code hooks** - Real-time warnings while coding (debug statements, secrets, hardcoded URLs)
+> **Optimized for:** Python, TypeScript, React, Go/Hugo, and Docker projects.
 
 ---
-See More for on how the [RALPH loop](docs/RALPH.md) works in this repo
 
----
+## What It Does
+
+**Brainstorm ideas with `/idea`**
+Describe a feature in plain English. Claude asks clarifying questions, explores your codebase, and generates a PRD with atomic stories that can be implemented one at a time.
 
+**Execute with Ralph**
+Ralph reads the PRD and implements each story autonomously. It spawns Claude, runs verification (lint, tests, browser checks), and either commits on success or retries with error context on failure.
 
-## Getting Started
+**Customize your output**
+- `/my-dna` - Add your voice and values so the code reflects your style
+- `/styleguide` - Generate a UI component reference for consistent design
 
-### Prerequisites
+**Built-in guardrails**
+- `/vibe-check`, `/review` - On-demand quality and security checks
+- Pre-commit hooks - Block secrets, hardcoded URLs, debug statements
+- Claude Code hooks - Real-time warnings while coding
 
-- Node.js 18+
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and authenticated
-- `jq` (for config management): `brew install jq` or `apt install jq`
-- Optional: [Playwright](https://playwright.dev/) for browser verification (installed automatically by `/tour`)
+---
 
+## Quick Start
 
-## Step 0: Install
+**Prerequisites:** Node.js 18+, [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI, `jq` (`brew install jq`)
 
 ```bash
-cd [your-project]
 npm install agentic-loop
 npx agentic-loop setup
 ```
 
-This sets up:
-- Slash commands (`/idea`, `/review`, etc.)
-- Pre-commit hooks (secrets, URLs, debug statements)
-- Claude Code hooks (real-time warnings)
-- Ralph configuration files
-
-> **Note:** Claude Code hooks require `jq`. On macOS with Homebrew, it's installed automatically. On Linux, if you see a warning, run `sudo apt install jq` (or your package manager) then `npx agentic-loop setup`.
-
-## Step 1: Start claude (--dangerously-skip-permissions is optional)
-
+**Terminal 1 - Claude Code:**
 ```bash
 claude --dangerously-skip-permissions
+/tour                    # Guided walkthrough (recommended first time)
+/idea 'your feature'     # Generate a PRD
 ```
 
-## Step 1b: Optional run tour and customizations
-Inside of a claude session run
-```
- /tour
-```
-1. The tour auto-detects your project settings and walks you through the workflow.
-2. You can set up your own styleguide for all your frontend work to reference. I highly recommend you do this.
-3. run /my-dna to add your own writing style, core values, and things you want represented in your application so that your app represents you and what you want.
-
-### Step 2: Brainstorm Your Idea
-
-```
-/idea [describe your next feature]
-```
-
-Claude asks clarifying questions, explores your codebase, then generates:
-- `docs/ideas/your-feature.md` - The documented idea
-- `.ralph/prd.json` - Atomic stories for Ralph
-
-Review and approve when prompted.
-
-> **Note:** If Claude skips writing to `docs/ideas/`, tell it: "Please write the idea to docs/ideas/ and generate the PRD as the /idea command specifies"
-
-### Step 3: Execute with Ralph
-
-Type `/exit` or open a new terminal, then run:
-
+**Terminal 2 - Ralph Loop:**
 ```bash
-# Standard mode (with code review)
-npx agentic-loop run
-
-# Fast mode (skip code review, ~2x faster)
-npx agentic-loop run --fast
-
-# Limit iterations
-npx agentic-loop run --max 10
+npx agentic-loop run       # Execute PRDs autonomously
+npx agentic-loop run --fast  # Skip code review (~2x faster)
 ```
 
-Ralph loops through stories one at a time, writes tests, verifies, and commits.
+> **Tip:** Use two terminals. Plan with Claude in one, run Ralph in the other.
 
-> **Pro tip:** Use two terminals - plan with Claude in one, run Ralph in another.
->
-> **Performance:** Fast mode skips the AI code review step, running lint and tests in parallel. Use it when iterating quickly on known-good patterns.
+---
 
-## Ralph Details
+## How Ralph Works
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                        RALPH LOOP                           │
 ├─────────────────────────────────────────────────────────────┤
-│                                                             │
 │  1. Read prd.json → find next story where passes=false      │
 │  2. Build prompt (story + context + failures + signs)       │
 │  3. Spawn Claude with prompt                                │
-│  4. Run verification:                                       │
-│     - Code review (skipped in --fast mode)                  │
-│     - Lint + tests (run in parallel)                        │
-│     - Playwright/API tests                                  │
-│     - Browser validation                                    │
+│  4. Run verification (lint, tests, browser, code review)    │
 │  5. Pass? → commit, next story                              │
 │     Fail? → save error, retry with failure context          │
 │  6. Repeat until all stories pass                           │
-│                                                             │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### Performance Options
-
-| Flag | Effect | Best For |
-|------|--------|----------|
-| `--fast` | Skip code review, parallel lint+tests | Rapid iteration, trusted patterns |
-| `--max N` | Limit to N iterations | Preventing runaway loops |
-| (default) | Full verification with code review | Production-quality code |
-
----
-
-## Documentation
-
-| Doc | Description |
-|-----|-------------|
-| [How Ralph Works](docs/RALPH.md) | Architecture, config, troubleshooting |
-| [Cheatsheet](docs/CHEATSHEET.md) | All commands, quick reference |
-| [Workflow Guide](docs/WORKFLOW.md) | End-to-end development process |
-| [Hooks Reference](docs/HOOKS.md) | Pre-commit and Claude Code hooks |
-| [Bad Patterns](docs/BAD-PATTERNS.md) | AI code issues to avoid |
-| [Prompting Guide](docs/PROMPTING-GUIDE.md) | Writing effective PROMPT.md |
-| [TDD Guide](docs/TDD.md) | Test-driven development with Ralph |
-| [Styleguide](docs/STYLEGUIDE.md) | Creating UI component references |
-| [Contributing](docs/CONTRIBUTING.md) | How to contribute |
+**What's a PRD?**
+A JSON file (`.ralph/prd.json`) containing your feature broken into small stories. Each story has acceptance criteria, test steps, and a test URL. Ralph implements them one by one.
 
-## Project Structure
-
-```
-agentic-loop/
-├── .claude/commands/       # Slash commands (/idea, /review, etc.)
-├── ralph/                  # Autonomous loop (Bash)
-│   ├── hooks/              # Claude Code hooks (real-time warnings)
-│   ├── browser-verify/     # Playwright verification
-│   └── setup/              # Setup wizards (/tour)
-├── src/                    # Pre-commit checks (TypeScript)
-│   └── checks/             # Check implementations (secrets, urls, etc.)
-├── templates/              # Files for user projects
-│   ├── PROMPT.md           # Base prompt for Ralph sessions
-│   ├── config/             # Project type configs (node, python)
-│   ├── optional/           # Extra configs (eslint, vscode, etc.)
-│   └── examples/           # Example CLAUDE.md files by stack
-├── docs/                   # Documentation
-└── bin/                    # CLI entry points (agentic-loop, vibe-check)
-```
-
-### Three Layers of Quality Checks
-
-| Layer | When | What |
-|-------|------|------|
-| **Slash commands** | In Claude Code CLI | `/vibe-check`, `/review` - on-demand checks |
-| **Claude Code hooks** | While Claude writes code | Real-time warnings (debug statements, secrets) |
-| **Pre-commit hooks** | At `git commit` | Blocks secrets, URLs, debug statements |
-
----
-
-## Troubleshooting
-
-### "SessionStart: startup hook error"
-
-This means Claude Code hooks are configured but the hook scripts can't be found. Fix with:
-
-```bash
-# Reinstall project hooks
-npx agentic-loop setup
-```
-
-### Hooks not working after moving project
-
-Claude Code hooks use absolute paths. After moving a project or cloning on a new machine, reinstall hooks:
-
-```bash
-npx agentic-loop setup
-```
-
-### Team members getting hook errors
-
-`.claude/settings.json` contains machine-specific paths and should not be committed to git. The setup script automatically adds it to `.gitignore`. Each team member's hooks are configured when they run `npx agentic-loop setup`.
-
-If `.claude/settings.json` was accidentally committed:
-```bash
-git rm --cached .claude/settings.json
-echo ".claude/settings.json" >> .gitignore
-git commit -m "Remove machine-specific settings from git"
-```
-
-### jq not installed
-
-Claude Code hooks require `jq` for JSON manipulation. On macOS with Homebrew, the setup installs it automatically. On Linux:
-
-```bash
-# Ubuntu/Debian
-sudo apt install jq
-
-# Fedora/RHEL
-sudo dnf install jq
-
-# Then run setup
-npx agentic-loop setup
-```
+**What are Signs?**
+Patterns Ralph learns from failures. If Ralph keeps making the same mistake, add a sign: `npx agentic-loop sign "Always use camelCase for API fields" backend`. Future stories will see this guidance.
 
 ---
 
-## License
+## Docs
 
-MIT - see [LICENSE](LICENSE)
+- [How Ralph Works](docs/RALPH.md) - Architecture, config, verification pipeline
+- [Cheatsheet](docs/CHEATSHEET.md) - All commands at a glance
+- [Hooks Reference](docs/HOOKS.md) - Pre-commit and Claude Code hooks
+- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and fixes
+- [Contributing](docs/CONTRIBUTING.md) - How to contribute
 
 ---
 
-Built by [AllThrive AI](https://allthrive.ai)
+MIT License - [AllThrive AI](https://allthrive.ai)

package/package.json

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

package/ralph/init.sh

@@ -196,7 +196,7 @@ auto_configure_project() {
       # Extract port from web/frontend service: "5173:5173" -> 5173
       web_port=$(grep -A 20 -E '^\s*(web|frontend|client|ui):' "$compose_file" 2>/dev/null | \
                  grep -E '^\s*-\s*"?[0-9]+:[0-9]+"?' | head -1 | \
-                 grep -oE '[0-9]+:' | head -1 | tr -d ':')
+                 grep -oE '[0-9]+:' | head -1 | tr -d ':' || true)
     fi
   done
 
@@ -206,7 +206,7 @@ auto_configure_project() {
                        "apps/frontend/vite.config.ts" "frontend/vite.config.ts"; do
       if [[ -f "$vite_config" ]]; then
         # Look for port: 3000 or port: '3000'
-        web_port=$(grep -E 'port\s*[=:]\s*[0-9]+' "$vite_config" 2>/dev/null | grep -oE '[0-9]{4}' | head -1)
+        web_port=$(grep -E 'port\s*[=:]\s*[0-9]+' "$vite_config" 2>/dev/null | grep -oE '[0-9]{4}' | head -1 || true)
         [[ -z "$web_port" ]] && web_port="5173"  # Vite's documented default
         break
       fi
@@ -217,7 +217,7 @@ auto_configure_project() {
   if [[ -z "$web_port" ]]; then
     for hugo_config in "hugo.toml" "hugo.yaml" "hugo.json" "config.toml"; do
       if [[ -f "$hugo_config" ]] && [[ -d "content" || -d "layouts" || -d "themes" ]]; then
-        web_port=$(grep -E 'port\s*=' "$hugo_config" 2>/dev/null | grep -oE '[0-9]+' | head -1)
+        web_port=$(grep -E 'port\s*=' "$hugo_config" 2>/dev/null | grep -oE '[0-9]+' | head -1 || true)
         [[ -z "$web_port" ]] && web_port="1313"  # Hugo's documented default
         break
       fi
@@ -233,7 +233,7 @@ auto_configure_project() {
         local pkg_dir
         pkg_dir=$(dirname "$next_config")
         if [[ -f "$pkg_dir/package.json" ]]; then
-          web_port=$(grep -E '"dev".*-p\s*[0-9]+' "$pkg_dir/package.json" 2>/dev/null | grep -oE '\-p\s*[0-9]+' | grep -oE '[0-9]+')
+          web_port=$(grep -E '"dev".*-p\s*[0-9]+' "$pkg_dir/package.json" 2>/dev/null | grep -oE '\-p\s*[0-9]+' | grep -oE '[0-9]+' || true)
         fi
         [[ -z "$web_port" ]] && web_port="3000"  # Next.js documented default
         break
@@ -244,7 +244,7 @@ auto_configure_project() {
   # Priority 5: Generic package.json port detection
   if [[ -z "$web_port" && -f "package.json" ]]; then
     # Look for explicit port in scripts: --port 3000, -p 3000, :3000
-    web_port=$(grep -E '"(dev|start|serve)"' package.json 2>/dev/null | grep -oE '(--port|-p|:)[[:space:]]*[0-9]{4}' | grep -oE '[0-9]{4}' | head -1)
+    web_port=$(grep -E '"(dev|start|serve)"' package.json 2>/dev/null | grep -oE '(--port|-p|:)[[:space:]]*[0-9]{4}' | grep -oE '[0-9]{4}' | head -1 || true)
   fi
 
   if [[ -n "$web_port" ]]; then
@@ -306,14 +306,14 @@ auto_configure_project() {
       # Extract port from api/backend service: "8000:8000" -> 8000
       api_port=$(grep -A 20 -E '^\s*(api|backend|server|app):' "$compose_file" 2>/dev/null | \
                  grep -E '^\s*-\s*"?[0-9]+:[0-9]+"?' | head -1 | \
-                 grep -oE '[0-9]+:' | head -1 | tr -d ':')
+                 grep -oE '[0-9]+:' | head -1 | tr -d ':' || true)
     fi
   done
 
   # Priority 2: Dockerfile EXPOSE directive
   if [[ -n "$backend_dir" && -z "$api_port" ]]; then
     if [[ -f "$backend_dir/Dockerfile" ]]; then
-      api_port=$(grep -i "^EXPOSE" "$backend_dir/Dockerfile" 2>/dev/null | head -1 | grep -oE '[0-9]+' | head -1)
+      api_port=$(grep -i "^EXPOSE" "$backend_dir/Dockerfile" 2>/dev/null | head -1 | grep -oE '[0-9]+' | head -1 || true)
     fi
   fi
 
@@ -322,11 +322,11 @@ auto_configure_project() {
     if [[ -f "$backend_dir/pyproject.toml" ]] || [[ -f "$backend_dir/requirements.txt" ]]; then
       # Check pyproject.toml for port config
       if [[ -f "$backend_dir/pyproject.toml" ]]; then
-        api_port=$(grep -E 'port\s*=' "$backend_dir/pyproject.toml" 2>/dev/null | grep -oE '[0-9]+' | head -1)
+        api_port=$(grep -E 'port\s*=' "$backend_dir/pyproject.toml" 2>/dev/null | grep -oE '[0-9]+' | head -1 || true)
       fi
       # Check for uvicorn command with --port
       if [[ -z "$api_port" && -f "$backend_dir/Makefile" ]]; then
-        api_port=$(grep -E 'uvicorn.*--port' "$backend_dir/Makefile" 2>/dev/null | grep -oE '\-\-port[[:space:]]*[0-9]+' | grep -oE '[0-9]+' | head -1)
+        api_port=$(grep -E 'uvicorn.*--port' "$backend_dir/Makefile" 2>/dev/null | grep -oE '\-\-port[[:space:]]*[0-9]+' | grep -oE '[0-9]+' | head -1 || true)
       fi
       # Uvicorn/FastAPI default
       [[ -z "$api_port" ]] && api_port="8000"
@@ -335,7 +335,7 @@ auto_configure_project() {
 
   # Priority 4: Node backend - check package.json for port
   if [[ -n "$backend_dir" && -z "$api_port" && -f "$backend_dir/package.json" ]]; then
-    api_port=$(grep -E '"(dev|start|serve)"' "$backend_dir/package.json" 2>/dev/null | grep -oE '(--port|-p|:)[[:space:]]*[0-9]{4}' | grep -oE '[0-9]{4}' | head -1)
+    api_port=$(grep -E '"(dev|start|serve)"' "$backend_dir/package.json" 2>/dev/null | grep -oE '(--port|-p|:)[[:space:]]*[0-9]{4}' | grep -oE '[0-9]{4}' | head -1 || true)
   fi
 
   if [[ -n "$api_port" ]]; then
@@ -415,7 +415,7 @@ ralph_status() {
   else
     # Check for misplaced PRD in subdirectories
     local found_prd
-    found_prd=$(find . -path "./.ralph" -prune -o -name "prd.json" -path "*/.ralph/prd.json" -print 2>/dev/null | head -1)
+    found_prd=$(find . -path "./.ralph" -prune -o -name "prd.json" -path "*/.ralph/prd.json" -print 2>/dev/null | head -1 || true)
 
     if [[ -n "$found_prd" ]]; then
       print_warning "PRD found in wrong location: $found_prd"

package/ralph/loop.sh

@@ -347,6 +347,11 @@ run_loop() {
       rm -f "$RALPH_DIR/last_migration_failure.log"
       rm -f "$RALPH_DIR/last_review_failure.json"
       rm -f "$RALPH_DIR/last_test_failure.log"
+      rm -f "$RALPH_DIR/last_lint_failure.log"
+      rm -f "$RALPH_DIR/last_typescript_failure.log"
+      rm -f "$RALPH_DIR/last_build_failure.log"
+      rm -f "$RALPH_DIR/last_go_failure.log"
+      rm -f "$RALPH_DIR/last_rust_failure.log"
       rm -f "$RALPH_DIR/last_playwright_failure.log"
       rm -f "$RALPH_DIR/last_browser_failure.json"
       rm -f "$RALPH_DIR/last_precommit_failure.log"

package/ralph/verify/lint.sh

@@ -47,9 +47,13 @@ run_auto_fix() {
   fi
 }
 
-# Verify lint passes after auto-fix (catch unfixable errors)
+# Verify lint passes after auto-fix (catch remaining errors that need manual fix)
 verify_lint() {
   local failed=0
+  local lint_log="$RALPH_DIR/last_lint_failure.log"
+
+  # Clear previous lint failure log
+  rm -f "$lint_log"
 
   # Python: ruff lint check
   if command -v ruff &>/dev/null && [[ -f "pyproject.toml" || -f "ruff.toml" ]]; then
@@ -59,8 +63,14 @@ verify_lint() {
     else
       print_error "failed"
       echo ""
-      echo "    Unfixable lint errors:"
-      ruff check . 2>/dev/null | head -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+      echo "    Lint errors (auto-fix couldn't resolve - Claude should fix these):"
+      local lint_output
+      lint_output=$(ruff check . 2>/dev/null | head -"$MAX_LINT_ERROR_LINES")
+      echo "$lint_output" | sed 's/^/      /'
+      {
+        echo "Lint errors in root directory:"
+        echo "$lint_output"
+      } >> "$lint_log"
       failed=1
     fi
   fi
@@ -78,16 +88,288 @@ verify_lint() {
       else
         print_error "failed"
         echo ""
-        echo "    Unfixable lint errors in $api_dir:"
-        (cd "$api_dir" && ruff check . 2>/dev/null) | head -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+        echo "    Lint errors in $api_dir (auto-fix couldn't resolve - Claude should fix these):"
+        local lint_output
+        lint_output=$(cd "$api_dir" && ruff check . 2>/dev/null | head -"$MAX_LINT_ERROR_LINES")
+        echo "$lint_output" | sed 's/^/      /'
+        {
+          echo ""
+          echo "Lint errors in $api_dir:"
+          echo "$lint_output"
+        } >> "$lint_log"
         failed=1
       fi
     fi
   done <<< "$api_dirs"
 
+  # JavaScript/TypeScript: ESLint check (root)
+  if [[ -f "package.json" ]] && command -v npx &>/dev/null; then
+    if grep -q '"eslint"' package.json 2>/dev/null || [[ -f ".eslintrc.js" ]] || [[ -f "eslint.config.js" ]]; then
+      echo -n "    ESLint check... "
+      local eslint_output
+      if eslint_output=$(npx eslint . --max-warnings 0 2>&1); then
+        print_success "passed"
+      else
+        # Check if it's real errors or just warnings
+        if echo "$eslint_output" | grep -qE "✖ [0-9]+ problems? \([1-9]"; then
+          print_error "failed"
+          echo ""
+          echo "    ESLint errors:"
+          echo "$eslint_output" | tail -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+          {
+            echo ""
+            echo "ESLint errors in root:"
+            echo "$eslint_output"
+          } >> "$lint_log"
+          failed=1
+        else
+          print_success "passed (warnings only)"
+        fi
+      fi
+    fi
+  fi
+
+  # Check frontend directories (monorepo support)
+  local fe_dirs
+  fe_dirs=$(get_frontend_dirs)
+
+  while IFS= read -r fe_dir; do
+    [[ -z "$fe_dir" ]] && continue
+    [[ ! -f "$fe_dir/package.json" ]] && continue
+    grep -q '"eslint"' "$fe_dir/package.json" 2>/dev/null || continue
+
+    echo -n "    ESLint check ($fe_dir)... "
+    local eslint_output
+    if eslint_output=$(cd "$fe_dir" && npx eslint . --max-warnings 0 2>&1); then
+      print_success "passed"
+    else
+      if echo "$eslint_output" | grep -qE "✖ [0-9]+ problems? \([1-9]"; then
+        print_error "failed"
+        echo ""
+        echo "    ESLint errors in $fe_dir:"
+        echo "$eslint_output" | tail -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+        {
+          echo ""
+          echo "ESLint errors in $fe_dir:"
+          echo "$eslint_output"
+        } >> "$lint_log"
+        failed=1
+      else
+        print_success "passed (warnings only)"
+      fi
+    fi
+  done <<< "$fe_dirs"
+
   return $failed
 }
 
+# Verify TypeScript types compile
+verify_typescript() {
+  local failed=0
+  local ts_log="$RALPH_DIR/last_typescript_failure.log"
+
+  # Clear previous failure log
+  rm -f "$ts_log"
+
+  # Check root tsconfig
+  if [[ -f "tsconfig.json" ]] && command -v npx &>/dev/null; then
+    echo -n "    TypeScript typecheck... "
+    local ts_output
+    if ts_output=$(npx tsc --noEmit 2>&1); then
+      print_success "passed"
+    else
+      print_error "failed"
+      echo ""
+      echo "    TypeScript errors:"
+      echo "$ts_output" | head -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+      # Save for retry context
+      {
+        echo "TypeScript errors in root:"
+        echo "$ts_output"
+      } >> "$ts_log"
+      failed=1
+    fi
+  fi
+
+  # Check frontend directories (monorepo support)
+  local fe_dirs
+  fe_dirs=$(get_frontend_dirs)
+
+  while IFS= read -r fe_dir; do
+    [[ -z "$fe_dir" ]] && continue
+    [[ ! -f "$fe_dir/tsconfig.json" ]] && continue
+
+    echo -n "    TypeScript typecheck ($fe_dir)... "
+    local ts_output
+    if ts_output=$(cd "$fe_dir" && npx tsc --noEmit 2>&1); then
+      print_success "passed"
+    else
+      print_error "failed"
+      echo ""
+      echo "    TypeScript errors in $fe_dir:"
+      echo "$ts_output" | head -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+      # Save for retry context
+      {
+        echo ""
+        echo "TypeScript errors in $fe_dir:"
+        echo "$ts_output"
+      } >> "$ts_log"
+      failed=1
+    fi
+  done <<< "$fe_dirs"
+
+  return $failed
+}
+
+# Verify npm build succeeds (catches bundling/SSR issues)
+verify_build() {
+  local failed=0
+  local build_log="$RALPH_DIR/last_build_failure.log"
+
+  # Clear previous failure log
+  rm -f "$build_log"
+
+  # Check root package.json for build script
+  if [[ -f "package.json" ]] && grep -q '"build"' package.json 2>/dev/null; then
+    echo -n "    npm build... "
+    local build_output
+    if build_output=$(npm run build 2>&1); then
+      print_success "passed"
+    else
+      print_error "failed"
+      echo ""
+      echo "    Build errors:"
+      echo "$build_output" | tail -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+      # Save for retry context
+      {
+        echo "Build errors in root:"
+        echo "$build_output"
+      } >> "$build_log"
+      failed=1
+    fi
+  fi
+
+  # Check frontend directories (monorepo support)
+  local fe_dirs
+  fe_dirs=$(get_frontend_dirs)
+
+  while IFS= read -r fe_dir; do
+    [[ -z "$fe_dir" ]] && continue
+    [[ ! -f "$fe_dir/package.json" ]] && continue
+    # Skip if no build script
+    grep -q '"build"' "$fe_dir/package.json" 2>/dev/null || continue
+
+    echo -n "    npm build ($fe_dir)... "
+    local build_output
+    if build_output=$(cd "$fe_dir" && npm run build 2>&1); then
+      print_success "passed"
+    else
+      print_error "failed"
+      echo ""
+      echo "    Build errors in $fe_dir:"
+      echo "$build_output" | tail -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+      # Save for retry context
+      {
+        echo ""
+        echo "Build errors in $fe_dir:"
+        echo "$build_output"
+      } >> "$build_log"
+      failed=1
+    fi
+  done <<< "$fe_dirs"
+
+  return $failed
+}
+
+# Verify Go code compiles and passes vet
+verify_go() {
+  local go_log="$RALPH_DIR/last_go_failure.log"
+
+  # Skip if not a Go project
+  [[ ! -f "go.mod" ]] && return 0
+  command -v go &>/dev/null || return 0
+
+  # Clear previous failure log
+  rm -f "$go_log"
+
+  # Go vet (catches common mistakes)
+  echo -n "    Go vet... "
+  local vet_output
+  if vet_output=$(go vet ./... 2>&1); then
+    print_success "passed"
+  else
+    print_error "failed"
+    echo ""
+    echo "    Go vet errors:"
+    echo "$vet_output" | head -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+    {
+      echo "Go vet errors:"
+      echo "$vet_output"
+    } >> "$go_log"
+    return 1
+  fi
+
+  # Go build (catches compile errors)
+  echo -n "    Go build... "
+  local build_output
+  if build_output=$(go build ./... 2>&1); then
+    print_success "passed"
+  else
+    print_error "failed"
+    echo ""
+    echo "    Go build errors:"
+    echo "$build_output" | head -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+    {
+      echo ""
+      echo "Go build errors:"
+      echo "$build_output"
+    } >> "$go_log"
+    return 1
+  fi
+
+  return 0
+}
+
+# Verify Rust code with clippy
+verify_rust() {
+  local rust_log="$RALPH_DIR/last_rust_failure.log"
+
+  # Skip if not a Rust project
+  [[ ! -f "Cargo.toml" ]] && return 0
+  command -v cargo &>/dev/null || return 0
+
+  # Clear previous failure log
+  rm -f "$rust_log"
+
+  # Cargo clippy (Rust's official linter - catches more than cargo check)
+  echo -n "    Cargo clippy... "
+  local clippy_output
+  if clippy_output=$(cargo clippy --all-targets --all-features -- -D warnings 2>&1); then
+    print_success "passed"
+    return 0
+  fi
+
+  # Check if clippy is installed
+  if echo "$clippy_output" | grep -q "can't find.*clippy"; then
+    echo -n "not installed, trying cargo check... "
+    if clippy_output=$(cargo check 2>&1); then
+      print_success "passed"
+      return 0
+    fi
+  fi
+
+  # Failed
+  print_error "failed"
+  echo ""
+  echo "    Rust errors:"
+  echo "$clippy_output" | head -"$MAX_LINT_ERROR_LINES" | sed 's/^/      /'
+  {
+    echo "Rust errors:"
+    echo "$clippy_output"
+  } >> "$rust_log"
+  return 1
+}
+
 # Check FastAPI endpoints have Pydantic response models (for Swagger docs)
 run_fastapi_response_check() {
   # Use RALPH_LIB which points to the ralph/ directory
@@ -137,205 +419,152 @@ run_fastapi_response_check() {
   return $failed
 }
 
-# Run all checks defined in config.json
-run_configured_checks() {
-  local config="$RALPH_DIR/config.json"
-
-  # ALWAYS run auto-fix and lint verification, even without config.json
-  run_auto_fix
-
-  # Verify lint passes after auto-fix (catch unfixable errors)
-  if ! verify_lint; then
-    return 1
+# Check if a verification step is enabled in config
+# Values: true, false, "final" (only on last story)
+check_enabled() {
+  local check_name="$1"
+  local default="${2:-true}"
+  local value
+  value=$(get_config ".checks.$check_name" "$default")
+
+  # Handle "final" - only run on last story
+  if [[ "$value" == "final" ]]; then
+    local remaining
+    remaining=$(jq '[.stories[] | select(.passes==false)] | length' "$RALPH_DIR/prd.json" 2>/dev/null || echo "1")
+    [[ "$remaining" -eq 1 ]]
+    return
   fi
 
-  # Auto-detect and run FastAPI response model check
-  run_fastapi_response_check
-
-  # Run pre-commit hooks if available (catches errors before commit attempt)
-  if command -v pre-commit &>/dev/null && [[ -f ".pre-commit-config.yaml" ]]; then
-    echo -n "    pre-commit hooks... "
-    local precommit_log="$RALPH_DIR/last_precommit_failure.log"
-
-    # Helper function: check if pre-commit output has REAL errors (not just file modifications or warnings)
-    has_real_errors() {
-      local log_file="$1"
-
-      # If all "Failed" hooks only have "files were modified" - not real errors
-      # Real errors have patterns like: "error:", "Error:", numbered errors "✖ N problems (N errors"
-      # But ESLint "0 errors, N warnings" is NOT a real error
-
-      # Check for actual error indicators (not warnings-only)
-      if grep -qE "^error:|: error:|Error:|SyntaxError|TypeError|NameError" "$log_file" 2>/dev/null; then
-        return 0  # Has real errors
-      fi
-
-      # Check ESLint output - fail only if errors > 0
-      if grep -qE "✖ [0-9]+ problems? \([1-9][0-9]* errors?" "$log_file" 2>/dev/null; then
-        return 0  # Has real ESLint errors
-      fi
-
-      # Check ruff output - actual errors have file:line:col: error pattern
-      if grep -qE "^[^:]+:[0-9]+:[0-9]+: [EF][0-9]+" "$log_file" 2>/dev/null; then
-        return 0  # Has real ruff errors
-      fi
-
-      # Check for hooks that failed for reasons OTHER than file modification
-      # Get all "Failed" hooks and check if any DON'T have "files were modified"
-      local failed_hooks
-      failed_hooks=$(grep -B 5 "^- hook id:" "$log_file" | grep -B 1 "Failed" | grep "hook id:" | sed 's/.*hook id: //' 2>/dev/null)
-
-      while IFS= read -r hook_id; do
-        [[ -z "$hook_id" ]] && continue
-        # Check if this hook's failure section contains "files were modified"
-        if ! grep -A 3 "hook id: $hook_id" "$log_file" | grep -q "files were modified"; then
-          # This hook failed for a real reason
-          return 0
-        fi
-      done <<< "$failed_hooks"
-
-      return 1  # No real errors found
-    }
-
-    # Run pre-commit up to 3 times to handle auto-fix chains
-    local max_attempts=3
-    local attempt=1
-    local passed=false
-
-    while [[ $attempt -le $max_attempts ]]; do
-      if pre-commit run --all-files > "$precommit_log" 2>&1; then
-        passed=true
-        break
-      fi
+  [[ "$value" == "true" ]]
+}
 
-      # Check if failure is due to file modifications (auto-fix)
-      if grep -q "files were modified by this hook" "$precommit_log"; then
-        # Check if there are also REAL errors (not just file mods)
-        if has_real_errors "$precommit_log"; then
-          # Real errors exist - fail
-          break
-        fi
+# Run all checks based on config.json flags
+run_configured_checks() {
+  # ALWAYS run auto-fix (harmless, just formats code)
+  run_auto_fix
 
-        # Only file modifications - stage and retry
-        if [[ $attempt -lt $max_attempts ]]; then
-          echo -n "auto-fixing (attempt $attempt)... "
-          git add -A 2>/dev/null || true
-          ((attempt++))
-          continue
-        else
-          # Max attempts reached, but only file mods - consider it passed
-          # Some hooks (like backup-database) always modify files
-          echo -n "auto-fix complete... "
-          git add -A 2>/dev/null || true
-          passed=true
-          break
-        fi
-      else
-        # Failed without "files were modified" - check for real errors
-        if has_real_errors "$precommit_log"; then
-          break  # Real errors
-        else
-          # No real errors detected (warnings only, etc.)
-          passed=true
-          break
-        fi
-      fi
+  # Lint check (ruff for Python, eslint for JS/TS)
+  if check_enabled "lint"; then
+    if ! verify_lint; then
+      return 1
+    fi
+  fi
 
-      ((attempt++))
-    done
+  # TypeScript type checking
+  if check_enabled "typecheck"; then
+    if ! verify_typescript; then
+      return 1
+    fi
+  fi
 
-    if [[ "$passed" == "true" ]]; then
-      if [[ $attempt -gt 1 ]]; then
-        print_success "passed (after auto-fix)"
-      else
-        print_success "passed"
-      fi
-      rm -f "$precommit_log"
-    else
-      print_error "failed"
-      echo ""
-      echo "    Pre-commit hook errors:"
-      # Show actual errors, not just "Failed" status lines
-      grep -E "^error:|: error:|Error:|SyntaxError|✖ [0-9]+ problems|^[^:]+:[0-9]+:[0-9]+:" "$precommit_log" | head -"$MAX_ERROR_PREVIEW_LINES" | sed 's/^/      /'
-      # If no errors shown, show more context
-      if ! grep -qE "^error:|: error:|Error:|SyntaxError|✖ [0-9]+ problems" "$precommit_log"; then
-        echo "    Full output:"
-        tail -30 "$precommit_log" | sed 's/^/      /'
-      fi
+  # Build verification (npm build, go build, cargo build)
+  if check_enabled "build"; then
+    if ! verify_build; then
+      return 1
+    fi
+    if ! verify_go; then
+      return 1
+    fi
+    if ! verify_rust; then
       return 1
     fi
   fi
 
-  # Config-based checks are optional
-  if [[ ! -f "$config" ]]; then
-    echo "    (no config.json for additional checks)"
-    return 0
+  # FastAPI response model check
+  if check_enabled "fastapi" "false"; then
+    run_fastapi_response_check
   fi
 
-  # Get list of check names (excluding 'test' which we run separately)
-  local check_names
-  check_names=$(jq -r '.checks | keys[] | select(. != "test")' "$config" 2>/dev/null)
+  # Run pre-commit hooks if available (catches errors before commit attempt)
+  run_precommit_hooks
 
-  if [[ -z "$check_names" ]]; then
-    echo "    (no additional checks configured)"
-    return 0
-  fi
+  return 0
+}
 
-  local all_passed=0
+# Run pre-commit hooks with auto-fix retry logic
+run_precommit_hooks() {
+  # Skip if pre-commit not available
+  command -v pre-commit &>/dev/null || return 0
+  [[ -f ".pre-commit-config.yaml" ]] || return 0
 
-  while IFS= read -r check_name; do
-    [[ -z "$check_name" ]] && continue
+  echo -n "    pre-commit hooks... "
+  local precommit_log="$RALPH_DIR/last_precommit_failure.log"
 
-    local cmd
-    cmd=$(jq -r ".checks[\"$check_name\"] // empty" "$config")
+  # Helper function: check if pre-commit output has REAL errors
+  has_real_errors() {
+    local log_file="$1"
 
-    if [[ -z "$cmd" || "$cmd" == "null" ]]; then
-      continue
+    # Check for actual error indicators (not warnings-only)
+    if grep -qE "^error:|: error:|Error:|SyntaxError|TypeError|NameError" "$log_file" 2>/dev/null; then
+      return 0
     fi
 
-    # Check if command exists
-    local first_word
-    first_word=$(echo "$cmd" | awk '{print $1}')
+    # Check ESLint output - fail only if errors > 0
+    if grep -qE "✖ [0-9]+ problems? \([1-9][0-9]* errors?" "$log_file" 2>/dev/null; then
+      return 0
+    fi
 
-    if [[ "$first_word" == "cd" ]]; then
-      local actual_cmd
-      actual_cmd=$(echo "$cmd" | sed 's/.*&& *//' | awk '{print $1}')
-      if [[ -n "$actual_cmd" ]] && ! command -v "$actual_cmd" &>/dev/null; then
-        echo "    Skipping $check_name ($actual_cmd not found)"
-        continue
-      fi
-    elif ! command -v "$first_word" &>/dev/null; then
-      echo "    Skipping $check_name ($first_word not found)"
-      continue
+    # Check ruff output - actual errors have file:line:col: error pattern
+    if grep -qE "^[^:]+:[0-9]+:[0-9]+: [EF][0-9]+" "$log_file" 2>/dev/null; then
+      return 0
     fi
 
-    if ! run_check "$check_name" "$cmd"; then
-      all_passed=1
+    return 1
+  }
+
+  # Run pre-commit up to 3 times to handle auto-fix chains
+  local max_attempts=3
+  local attempt=1
+  local passed=false
+
+  while [[ $attempt -le $max_attempts ]]; do
+    if pre-commit run --all-files > "$precommit_log" 2>&1; then
+      passed=true
+      break
     fi
-  done <<< "$check_names"
 
-  return $all_passed
-}
+    # Check if failure is due to file modifications (auto-fix)
+    if grep -q "files were modified by this hook" "$precommit_log"; then
+      if has_real_errors "$precommit_log"; then
+        break  # Real errors exist
+      fi
 
-# Run a single check
-run_check() {
-  local name="$1"
-  local cmd="$2"
-  local log_file
-  log_file=$(create_temp_file ".log") || return 1
+      # Only file modifications - stage and retry
+      if [[ $attempt -lt $max_attempts ]]; then
+        echo -n "auto-fixing (attempt $attempt)... "
+        git add -A 2>/dev/null || true
+        ((attempt++))
+        continue
+      else
+        git add -A 2>/dev/null || true
+        passed=true
+        break
+      fi
+    else
+      if has_real_errors "$precommit_log"; then
+        break
+      else
+        passed=true
+        break
+      fi
+    fi
 
-  echo -n "    $name... "
+    ((attempt++))
+  done
 
-  if safe_exec "$cmd" "$log_file"; then
-    print_success "passed"
-    rm -f "$log_file"
+  if [[ "$passed" == "true" ]]; then
+    [[ $attempt -gt 1 ]] && print_success "passed (after auto-fix)" || print_success "passed"
+    rm -f "$precommit_log"
     return 0
   else
     print_error "failed"
     echo ""
-    echo "    Output (last $MAX_LOG_LINES lines):"
-    tail -"$MAX_LOG_LINES" "$log_file" | sed 's/^/      /'
-    rm -f "$log_file"
+    echo "    Pre-commit hook errors:"
+    grep -E "^error:|: error:|Error:|SyntaxError|✖ [0-9]+ problems|^[^:]+:[0-9]+:[0-9]+:" "$precommit_log" 2>/dev/null | head -"$MAX_ERROR_PREVIEW_LINES" | sed 's/^/      /'
+    if ! grep -qE "^error:|: error:|Error:|SyntaxError|✖ [0-9]+ problems" "$precommit_log" 2>/dev/null; then
+      echo "    Full output:"
+      tail -30 "$precommit_log" | sed 's/^/      /'
+    fi
     return 1
   fi
 }

package/ralph/verify.sh

@@ -239,6 +239,72 @@ save_failure_context() {
       echo ""
     fi
 
+    if [[ -f "$RALPH_DIR/last_lint_failure.log" ]]; then
+      echo "--- Lint Failure ---"
+      echo "Fix these lint errors. The auto-fixer couldn't resolve them, but you can:"
+      echo ""
+      cat "$RALPH_DIR/last_lint_failure.log"
+      echo ""
+      echo "Common fixes:"
+      echo "  - E722 bare except: Change 'except:' to 'except Exception:'"
+      echo "  - F401 unused import: Remove the unused import"
+      echo "  - F841 unused variable: Remove or use the variable"
+      echo ""
+    fi
+
+    if [[ -f "$RALPH_DIR/last_typescript_failure.log" ]]; then
+      echo "--- TypeScript Failure ---"
+      echo "Fix these TypeScript type errors:"
+      echo ""
+      cat "$RALPH_DIR/last_typescript_failure.log"
+      echo ""
+      echo "Common fixes:"
+      echo "  - TS2322: Type mismatch - ensure assigned value matches expected type"
+      echo "  - TS2339: Property not found - check spelling or add to interface"
+      echo "  - TS2345: Argument type mismatch - cast or fix the argument type"
+      echo "  - TS7006: Implicit any - add explicit type annotation"
+      echo ""
+    fi
+
+    if [[ -f "$RALPH_DIR/last_build_failure.log" ]]; then
+      echo "--- Build Failure ---"
+      echo "Fix these build errors:"
+      echo ""
+      cat "$RALPH_DIR/last_build_failure.log"
+      echo ""
+      echo "Common causes:"
+      echo "  - Import errors: Check file paths and exports"
+      echo "  - SSR issues (Next.js): Use dynamic imports for client-only code"
+      echo "  - Missing dependencies: Run npm install"
+      echo ""
+    fi
+
+    if [[ -f "$RALPH_DIR/last_go_failure.log" ]]; then
+      echo "--- Go Failure ---"
+      echo "Fix these Go errors:"
+      echo ""
+      cat "$RALPH_DIR/last_go_failure.log"
+      echo ""
+      echo "Common fixes:"
+      echo "  - Unused variable: Remove or use with _ prefix"
+      echo "  - Undefined: Check imports and spelling"
+      echo "  - Type mismatch: Ensure types align or use type assertion"
+      echo ""
+    fi
+
+    if [[ -f "$RALPH_DIR/last_rust_failure.log" ]]; then
+      echo "--- Rust Failure ---"
+      echo "Fix these Rust errors:"
+      echo ""
+      cat "$RALPH_DIR/last_rust_failure.log"
+      echo ""
+      echo "Common fixes:"
+      echo "  - Unused variable: Prefix with _ or remove"
+      echo "  - Borrow checker: Check ownership and lifetimes"
+      echo "  - Missing trait: Add #[derive(...)] or impl"
+      echo ""
+    fi
+
     if [[ -f "$RALPH_DIR/last_precommit_failure.log" ]]; then
       echo "--- Pre-commit / Lint Failure ---"
       echo "Fix these errors before the story can be completed:"

package/templates/config/fullstack.json

@@ -37,11 +37,11 @@
   },
 
   "checks": {
-    "typescript": "cd frontend && npx tsc --noEmit",
-    "lint": "ruff check .",
-    "lintFrontend": "cd frontend && npm run lint",
-    "test": "python manage.py test --keepdb --parallel",
-    "testFrontend": "cd frontend && npm test"
+    "lint": true,
+    "typecheck": true,
+    "build": "final",
+    "test": true,
+    "fastapi": true
   },
 
   "api": {

package/templates/config/go.json

@@ -35,9 +35,11 @@
   },
 
   "checks": {
-    "build": "go build ./...",
-    "lint": "golangci-lint run",
-    "test": "go test ./..."
+    "lint": true,
+    "typecheck": false,
+    "build": true,
+    "test": true,
+    "fastapi": false
   },
 
   "api": {

package/templates/config/minimal.json

@@ -34,7 +34,13 @@
     "pattern": ""
   },
 
-  "checks": {},
+  "checks": {
+    "lint": true,
+    "typecheck": true,
+    "build": "final",
+    "test": true,
+    "fastapi": false
+  },
 
   "api": {
     "baseUrl": "http://localhost:3000",

package/templates/config/node.json

@@ -35,9 +35,11 @@
   },
 
   "checks": {
-    "typescript": "npx tsc --noEmit",
-    "lint": "npm run lint",
-    "test": "npm test"
+    "lint": true,
+    "typecheck": true,
+    "build": "final",
+    "test": true,
+    "fastapi": false
   },
 
   "api": {

package/templates/config/python.json

@@ -35,9 +35,11 @@
   },
 
   "checks": {
-    "lint": "ruff check .",
-    "typecheck": "mypy .",
-    "test": "pytest"
+    "lint": true,
+    "typecheck": false,
+    "build": false,
+    "test": true,
+    "fastapi": true
   },
 
   "api": {

package/templates/config/rust.json

@@ -35,9 +35,11 @@
   },
 
   "checks": {
-    "build": "cargo build",
-    "lint": "cargo clippy -- -D warnings",
-    "test": "cargo test"
+    "lint": true,
+    "typecheck": false,
+    "build": true,
+    "test": true,
+    "fastapi": false
   },
 
   "api": {