vibe-and-thrive 1.5.0 → 1.6.0

package/.claude/commands/idea.md

@@ -130,9 +130,19 @@ Break the idea into small, executable PRDs following the JSON structure below.
    mkdir -p .ralph
    ```
 
-2. Write to `.ralph/prd.json`
+2. Write to `.ralph/prd.json` ensuring:
+   - Valid JSON syntax
+   - `feature.name` is set (not null/empty)
+   - `feature.status` is "pending"
+   - `stories` array is not empty
+   - Each story has `id`, `title`, and `passes: false`
+
+3. Validate the PRD was written correctly:
+   ```bash
+   jq -e '.feature.name and (.stories | length > 0) and (.stories | all(.id and .title and .passes == false))' .ralph/prd.json && echo "PRD valid" || echo "PRD invalid"
+   ```
 
-3. Say: "I've created the PRD with {N} stories in `.ralph/prd.json`.
+4. Say: "I've created the PRD with {N} stories in `.ralph/prd.json`.
 
    Review and let me know:
    - **'approved'** - Ready for `npx ralph run`

package/README.md

@@ -37,13 +37,20 @@ See More for on how the [RALPH loop](docs/RALPH.md) works in this repo
 - Optional: [Playwright](https://playwright.dev/) for browser verification (installed automatically by `/tour`)
 
 
-## Step 0: Install 
+## Step 0: Install
 
 ```bash
 cd [your-project]
 npm install vibe-and-thrive
 ```
-This automatically sets up slash commands, pre-commit hooks, to make the Ralph loop autonomous.
+
+This automatically 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 ralph hooks`.
 
 ## Step 1: Start claude (--dangerously-skip-permissions is optional)
 
@@ -148,6 +155,58 @@ vibe-and-thrive/
 | **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 ralph hooks --force
+
+# Or reinstall global hooks (if using vibe-and-thrive source repo)
+/path/to/vibe-and-thrive/ralph/hooks/install.sh --global --force
+```
+
+### 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 ralph hooks --force
+```
+
+### Team members getting hook errors
+
+`.claude/settings.json` contains machine-specific paths and should not be committed to git. The postinstall script automatically adds it to `.gitignore`. Each team member's hooks are configured when they run `npm install`.
+
+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, `npx ralph hooks` installs it automatically. On Linux:
+
+```bash
+# Ubuntu/Debian
+sudo apt install jq
+
+# Fedora/RHEL
+sudo dnf install jq
+
+# Then install hooks
+npx ralph hooks
+```
+
+---
+
 ## License
 
 MIT - see [LICENSE](LICENSE)

package/bin/postinstall.sh

@@ -16,6 +16,17 @@ PKG_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 # npm runs postinstall from package dir, we need project root
 PROJECT_ROOT="$(cd "$PKG_ROOT/../.." && pwd)"
 
+# Verify we're in a valid project (has package.json), not a global install
+if [[ ! -f "$PROJECT_ROOT/package.json" ]]; then
+  # Might be global install or npm link - skip silently
+  exit 0
+fi
+
+# Don't run in the vibe-and-thrive package itself
+if [[ -f "$PROJECT_ROOT/package.json" ]] && grep -q '"name": "vibe-and-thrive"' "$PROJECT_ROOT/package.json" 2>/dev/null; then
+  exit 0
+fi
+
 # Change to project root for setup
 cd "$PROJECT_ROOT" || exit 0
 
@@ -55,8 +66,41 @@ EOF
 }
 
 install_ralph() {
-  if [[ ! -d ".ralph" ]] && [[ -f "$PKG_ROOT/bin/ralph.sh" ]]; then
-    "$PKG_ROOT/bin/ralph.sh" init > /dev/null 2>&1 || true
+  # Just create the directory structure - don't run full init
+  # Users will run /idea or ralph prd to generate a PRD
+  mkdir -p ".ralph/archive" ".ralph/screenshots"
+
+  # Copy config template based on detected project type
+  if [[ ! -f ".ralph/config.json" ]]; then
+    local config_template=""
+    if [[ -f "manage.py" ]] || [[ -f "pyproject.toml" ]]; then
+      config_template="$PKG_ROOT/templates/config/python.json"
+    elif [[ -d "frontend" ]] && [[ -d "backend" || -d "core" ]]; then
+      config_template="$PKG_ROOT/templates/config/fullstack.json"
+    elif [[ -f "package.json" ]]; then
+      config_template="$PKG_ROOT/templates/config/node.json"
+    fi
+
+    if [[ -n "$config_template" ]] && [[ -f "$config_template" ]]; then
+      cp "$config_template" ".ralph/config.json"
+    else
+      # Fall back to minimal config
+      echo '{"checks": {"build": true, "lint": true, "test": true}}' > ".ralph/config.json"
+    fi
+  fi
+
+  # Copy signs template if available, otherwise create empty
+  if [[ ! -f ".ralph/signs.json" ]]; then
+    if [[ -f "$PKG_ROOT/templates/signs.json" ]]; then
+      cp "$PKG_ROOT/templates/signs.json" ".ralph/signs.json"
+    else
+      echo '{"signs": []}' > ".ralph/signs.json"
+    fi
+  fi
+
+  # Create PROMPT.md if missing
+  if [[ ! -f "PROMPT.md" ]] && [[ -f "$PKG_ROOT/templates/PROMPT.md" ]]; then
+    cp "$PKG_ROOT/templates/PROMPT.md" "PROMPT.md"
   fi
 }
 
@@ -80,24 +124,60 @@ configure_mcp() {
   }' "$claude_json" > "$tmp" && mv "$tmp" "$claude_json"
 }
 
-install_claude_hooks() {
-  # Skip if jq not available
-  command -v jq &>/dev/null || return 0
+install_jq_if_missing() {
+  # Try to install jq automatically
+  if [[ "$OSTYPE" == "darwin"* ]] && command -v brew &>/dev/null; then
+    # macOS with Homebrew - doesn't need sudo
+    echo "  Installing jq via Homebrew..."
+    brew install jq >/dev/null 2>&1 && return 0
+  fi
 
+  # For other systems, warn instead of using sudo during npm install
+  echo "  ⚠️  jq not installed - Claude Code hooks not configured"
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    echo "     Run: brew install jq && npx ralph hooks"
+  elif command -v apt-get &>/dev/null; then
+    echo "     Run: sudo apt install jq && npx ralph hooks"
+  else
+    echo "     Install jq and run: npx ralph hooks"
+  fi
+  return 1
+}
+
+install_claude_hooks() {
   local settings_file=".claude/settings.json"
   local hooks_dir="$PKG_ROOT/ralph/hooks"
 
   # Skip if hooks directory doesn't exist
   [[ ! -d "$hooks_dir" ]] && return 0
 
+  # Auto-install jq if missing (or warn if can't auto-install)
+  if ! command -v jq &>/dev/null; then
+    install_jq_if_missing || return 0
+  fi
+
   # Ensure .claude directory exists
   mkdir -p ".claude"
 
   # Create settings file if it doesn't exist
   [[ ! -f "$settings_file" ]] && echo '{}' > "$settings_file"
 
-  # Skip if hooks already configured
-  jq -e '.hooks' "$settings_file" > /dev/null 2>&1 && return 0
+  # Check if hooks are already configured AND valid
+  if jq -e '.hooks' "$settings_file" > /dev/null 2>&1; then
+    # Get the first hook command path to check if it's valid
+    local existing_hook
+    existing_hook=$(jq -r '.hooks.SessionStart[0].hooks[0].command // empty' "$settings_file" 2>/dev/null)
+
+    if [[ -n "$existing_hook" ]]; then
+      if [[ -x "$existing_hook" ]]; then
+        # Hooks exist and are valid, skip
+        return 0
+      else
+        # Hooks configured but invalid - reinstall
+        echo "  ⚠️  Existing Claude Code hooks are invalid, reinstalling..."
+      fi
+    fi
+  fi
 
   # Build hooks config
   local hooks_config
@@ -198,6 +278,24 @@ generate_claude_md() {
   [[ -f "pytest.ini" ]] && testing="${testing:+$testing + }pytest"
   [[ -f "pyproject.toml" ]] && grep -q "pytest" pyproject.toml 2>/dev/null && testing="${testing:+$testing + }pytest"
 
+  # Detect Python package manager (check root and common backend paths)
+  local python_runner=""
+  local api_dir=""
+  [[ -d "apps/api" ]] && api_dir="apps/api"
+  [[ -d "backend" ]] && api_dir="backend"
+  [[ -d "api" ]] && api_dir="api"
+
+  # Check for uv (uv.lock)
+  if [[ -f "uv.lock" ]] || [[ -n "$api_dir" && -f "$api_dir/uv.lock" ]]; then
+    python_runner="uv run python"
+  # Check for poetry (poetry.lock)
+  elif [[ -f "poetry.lock" ]] || [[ -n "$api_dir" && -f "$api_dir/poetry.lock" ]]; then
+    python_runner="poetry run python"
+  # Check for pipenv (Pipfile.lock)
+  elif [[ -f "Pipfile.lock" ]] || [[ -n "$api_dir" && -f "$api_dir/Pipfile.lock" ]]; then
+    python_runner="pipenv run python"
+  fi
+
   # Detect structure
   [[ -d "src/components" || -d "${fe_dir}/src/components" || -d "${fe_dir}/components" ]] && structure="- Components: \`src/components/\` or \`${fe_dir}/\`"
   [[ -d "src/hooks" || -d "${fe_dir}/src/hooks" ]] && structure="${structure:+$structure
@@ -217,6 +315,7 @@ ${framework:+- Framework: $framework}
 ${language:+- Language: $language}
 ${styling:+- Styling: $styling}
 ${testing:+- Testing: $testing}
+${python_runner:+- Python: Use \`$python_runner\` (not bare \`python\`)}
 
 ${structure:+### Project Structure
 $structure}
@@ -249,6 +348,7 @@ ensure_gitignore() {
     ".ralph/screenshots/"
     ".ralph/archive/"
     ".backups/"
+    ".claude/settings.json"
   )
 
   if [[ ! -f ".gitignore" ]]; then
@@ -282,10 +382,13 @@ echo ""
 if [[ -n "${CLAUDECODE:-}" ]]; then
   echo "  [CLAUDE: Run the /tour slash command to help the user get started]"
 else
-  echo "  Start Claude Code and type /tour:"
+  echo "  Next steps:"
+  echo ""
+  echo "    claude                        # Start Claude Code"
+  echo "    /idea 'your feature'          # Generate a PRD"
+  echo "    ralph run                     # Execute autonomously"
   echo ""
-  echo "    claude"
-  echo "    /tour"
+  echo "  Or type /tour for a guided walkthrough."
 fi
 
 echo ""

package/bin/ralph.sh

@@ -32,10 +32,14 @@ PROMPT_FILE="${PROMPT_FILE:-PROMPT.md}"
 # Export for use in sourced files
 export RALPH_DIR PROMPT_FILE RALPH_LIB RALPH_TEMPLATES
 
-# Ensure setup ran (in case postinstall was skipped)
-if [[ ! -f ".pre-commit-config.yaml" ]] || [[ ! -d ".ralph" ]]; then
-  echo "First run - setting up vibe-and-thrive..."
-  bash "$SCRIPT_DIR/postinstall.sh" 2>/dev/null || true
+# Ensure minimal setup exists (in case postinstall was skipped or global install)
+if [[ ! -d ".ralph" ]]; then
+  mkdir -p ".ralph/archive" ".ralph/screenshots"
+  [[ ! -f ".ralph/config.json" ]] && echo '{"checks": {"build": true, "lint": true, "test": true}}' > ".ralph/config.json"
+  [[ ! -f ".ralph/signs.json" ]] && echo '{"signs": []}' > ".ralph/signs.json"
+fi
+if [[ ! -f "PROMPT.md" ]] && [[ -f "$RALPH_TEMPLATES/PROMPT.md" ]]; then
+  cp "$RALPH_TEMPLATES/PROMPT.md" "PROMPT.md"
 fi
 
 # Source function libraries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-and-thrive",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Ship quality code faster with AI - RALPH autonomous loop, Claude Code hooks, and pre-commit checks",
   "author": "Allie Jones <allie@allthrive.ai>",
   "license": "MIT",
@@ -79,6 +79,6 @@
     "eslint": "^9.0.0",
     "playwright": "^1.40.0",
     "typescript": "^5.0.0",
-    "vitest": "^2.0.0"
+    "vitest": "^4.0.18"
   }
 }

package/ralph/hooks/install.sh

@@ -1,26 +1,79 @@
 #!/usr/bin/env bash
 # install.sh - Install Ralph hooks into Claude Code settings
 #
-# Usage: ./install.sh [--global]
+# Usage: ./install.sh [--global] [--force]
 #   --global: Install to ~/.claude/settings.json (applies to all projects)
+#   --force:  Reinstall even if hooks already configured
 #   Default: Install to .claude/settings.json (project-level)
 
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-VIBE_PATH="$(cd "$SCRIPT_DIR/../../.." && pwd)"
 
 # Parse args
 SETTINGS_FILE=".claude/settings.json"
-if [[ "${1:-}" == "--global" ]]; then
-  SETTINGS_FILE="$HOME/.claude/settings.json"
-fi
+FORCE=false
+
+for arg in "$@"; do
+  case $arg in
+    --global)
+      SETTINGS_FILE="$HOME/.claude/settings.json"
+      ;;
+    --force)
+      FORCE=true
+      ;;
+  esac
+done
 
 # Colors
+RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 NC='\033[0m'
 
+# Auto-install jq if missing
+install_jq() {
+  echo -e "${YELLOW}jq not found, installing...${NC}"
+
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    # macOS
+    if command -v brew &>/dev/null; then
+      brew install jq
+    else
+      echo -e "${RED}Error: Homebrew not found. Install jq manually:${NC}"
+      echo "  brew install jq"
+      echo "  Or: https://jqlang.github.io/jq/download/"
+      exit 1
+    fi
+  elif command -v apt-get &>/dev/null; then
+    # Debian/Ubuntu
+    sudo apt-get update -qq && sudo apt-get install -y jq
+  elif command -v dnf &>/dev/null; then
+    # Fedora/RHEL 8+
+    sudo dnf install -y jq
+  elif command -v yum &>/dev/null; then
+    # CentOS/RHEL 7
+    sudo yum install -y jq
+  elif command -v pacman &>/dev/null; then
+    # Arch
+    sudo pacman -S --noconfirm jq
+  elif command -v apk &>/dev/null; then
+    # Alpine
+    sudo apk add jq
+  else
+    echo -e "${RED}Error: Could not detect package manager.${NC}"
+    echo "Install jq manually: https://jqlang.github.io/jq/download/"
+    exit 1
+  fi
+
+  echo -e "${GREEN}✓ jq installed${NC}"
+}
+
+# Check for jq, install if missing
+if ! command -v jq &>/dev/null; then
+  install_jq
+fi
+
 echo "Installing Ralph hooks..."
 echo "  Hooks path: $SCRIPT_DIR"
 echo "  Settings: $SETTINGS_FILE"
@@ -34,6 +87,20 @@ if [[ ! -f "$SETTINGS_FILE" ]]; then
   echo '{}' > "$SETTINGS_FILE"
 fi
 
+# Check if hooks already configured and valid
+if [[ "$FORCE" != "true" ]] && jq -e '.hooks' "$SETTINGS_FILE" > /dev/null 2>&1; then
+  existing_hook=$(jq -r '.hooks.SessionStart[0].hooks[0].command // empty' "$SETTINGS_FILE" 2>/dev/null)
+
+  if [[ -n "$existing_hook" && -x "$existing_hook" ]]; then
+    echo -e "${YELLOW}Hooks already configured and valid.${NC}"
+    echo "Use --force to reinstall."
+    exit 0
+  else
+    echo -e "${YELLOW}Existing hooks are invalid, reinstalling...${NC}"
+    echo ""
+  fi
+fi
+
 # Build hooks config with actual path
 HOOKS_CONFIG=$(cat <<EOF
 {

package/ralph/init.sh

@@ -2,12 +2,6 @@
 # init.sh - Initialize ralph in a project
 
 ralph_init() {
-  if [[ -d "$RALPH_DIR" ]]; then
-    print_info "Ralph already initialized in this directory."
-    print_info "Run 'ralph status' to see current state."
-    return 0
-  fi
-
   echo "Initializing ralph..."
 
   # Create directory structure
@@ -18,26 +12,32 @@ ralph_init() {
   project_type=$(detect_project_type)
   echo "Detected project type: $project_type"
 
-  # Copy config template based on project type
-  local config_template="$RALPH_TEMPLATES/config/${project_type}.json"
-  if [[ -f "$config_template" ]]; then
-    cp "$config_template" "$RALPH_DIR/config.json"
-  else
-    # Fall back to minimal config
-    cp "$RALPH_TEMPLATES/config/minimal.json" "$RALPH_DIR/config.json"
+  # Copy config template based on project type (only if missing)
+  if [[ ! -f "$RALPH_DIR/config.json" ]]; then
+    local config_template="$RALPH_TEMPLATES/config/${project_type}.json"
+    if [[ -f "$config_template" ]]; then
+      cp "$config_template" "$RALPH_DIR/config.json"
+    else
+      # Fall back to minimal config
+      cp "$RALPH_TEMPLATES/config/minimal.json" "$RALPH_DIR/config.json"
+    fi
   fi
 
-  # Create signs with defaults
-  if [[ -f "$RALPH_TEMPLATES/signs.json" ]]; then
-    cp "$RALPH_TEMPLATES/signs.json" "$RALPH_DIR/signs.json"
-  else
-    echo '{"signs": []}' > "$RALPH_DIR/signs.json"
+  # Create signs with defaults (only if missing)
+  if [[ ! -f "$RALPH_DIR/signs.json" ]]; then
+    if [[ -f "$RALPH_TEMPLATES/signs.json" ]]; then
+      cp "$RALPH_TEMPLATES/signs.json" "$RALPH_DIR/signs.json"
+    else
+      echo '{"signs": []}' > "$RALPH_DIR/signs.json"
+    fi
   fi
 
-  # Create empty progress log
-  local timestamp
-  timestamp=$(date -Iseconds 2>/dev/null || date +%Y-%m-%dT%H:%M:%S)
-  echo "[$timestamp] INIT Ralph initialized" > "$RALPH_DIR/progress.txt"
+  # Create progress log (only if missing)
+  if [[ ! -f "$RALPH_DIR/progress.txt" ]]; then
+    local timestamp
+    timestamp=$(date -Iseconds 2>/dev/null || date +%Y-%m-%dT%H:%M:%S)
+    echo "[$timestamp] INIT Ralph initialized" > "$RALPH_DIR/progress.txt"
+  fi
 
   # Copy PROMPT.md template if it doesn't exist in project
   if [[ ! -f "PROMPT.md" ]]; then

package/ralph/loop.sh

@@ -24,18 +24,27 @@ run_loop() {
 
   # Validate prerequisites
   check_dependencies
-  require_file "$RALPH_DIR/prd.json" "No PRD found. Run 'ralph prd' first."
-  require_file "$PROMPT_FILE" "PROMPT.md not found. Run 'ralph init' first."
 
-  # Validate PRD is valid JSON
-  if ! jq -e . "$RALPH_DIR/prd.json" >/dev/null 2>&1; then
-    print_error "prd.json is not valid JSON. Please fix or regenerate it."
-    return 1
+  if [[ ! -f "$RALPH_DIR/prd.json" ]]; then
+    print_error "No PRD found."
+    echo ""
+    echo "Create one with:"
+    echo "  /idea 'your feature description'   # thorough (recommended)"
+    echo "  ralph prd 'your feature'           # quick"
+    echo ""
+    exit 1
+  fi
+
+  if [[ ! -f "$PROMPT_FILE" ]]; then
+    print_error "PROMPT.md not found."
+    echo ""
+    echo "Create it with: ralph init"
+    echo ""
+    exit 1
   fi
 
-  # Validate PRD has required structure
-  if ! jq -e '.stories' "$RALPH_DIR/prd.json" >/dev/null 2>&1; then
-    print_error "prd.json is missing 'stories' array. Please fix or regenerate it."
+  # Validate PRD structure
+  if ! validate_prd "$RALPH_DIR/prd.json"; then
     return 1
   fi
 
@@ -74,7 +83,6 @@ run_loop() {
     fi
 
     if [[ -z "$story" ]]; then
-      print_success "All stories complete!"
       send_notification "✅ Ralph finished: All stories passed!"
       archive_feature
       return 0
@@ -180,7 +188,12 @@ run_loop() {
         local title
         title=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .title' "$RALPH_DIR/prd.json")
         git add -A
-        git commit -m "feat($story): $title" || true
+        # First commit attempt - pre-commit hooks may auto-fix files
+        if ! git commit -m "feat($story): $title" 2>/dev/null; then
+          # If failed, stage the auto-fixed files and retry once
+          git add -A
+          git commit -m "feat($story): $title" 2>/dev/null || true
+        fi
       fi
 
       log_progress "$story" "COMPLETED"
@@ -383,30 +396,32 @@ build_prompt() {
   fi
 }
 
-# Archive completed feature
+# Mark feature as complete (keep PRD for appending new stories)
 archive_feature() {
   local feature_name
   feature_name=$(jq -r '.feature.name' "$RALPH_DIR/prd.json")
 
   print_success "Feature '$feature_name' complete!"
 
-  # Archive the PRD
-  local archive_dir="$RALPH_DIR/archive"
-  mkdir -p "$archive_dir"
-
-  local timestamp
-  timestamp=$(date +%Y%m%d-%H%M%S)
-  mv "$RALPH_DIR/prd.json" "$archive_dir/prd-${timestamp}.json"
+  # Update status to complete (don't archive - user may want to append stories)
+  update_json "$RALPH_DIR/prd.json" '.feature.status = "complete"'
 
   # Final commit if git available
   if command -v git &>/dev/null && [[ -d ".git" ]]; then
     git add -A
-    git commit -m "feat: complete $feature_name" || true
+    if ! git commit -m "feat: complete $feature_name" 2>/dev/null; then
+      # Retry after pre-commit auto-fixes
+      git add -A
+      git commit -m "feat: complete $feature_name" 2>/dev/null || true
+    fi
   fi
 
-  log_progress "FEATURE" "ARCHIVED" "$feature_name"
+  log_progress "FEATURE" "COMPLETE" "$feature_name"
 
   echo ""
-  echo "PRD archived to: $archive_dir/prd-${timestamp}.json"
-  echo "Run 'ralph prd' to start a new feature."
+  echo "All stories passed! PRD kept at: $RALPH_DIR/prd.json"
+  echo ""
+  echo "Next:"
+  echo "  /idea 'new feature'     # Add more stories (will append)"
+  echo "  ralph status            # See completed stories"
 }

package/ralph/prd.sh

@@ -254,9 +254,24 @@ ralph_prd_accept() {
   # Ensure .ralph directory exists
   mkdir -p "$RALPH_DIR"
 
+  # Normalize the PRD before saving:
+  # - Ensure all stories have passes: false
+  # - Ensure all stories have id and title
+  # - Set status to pending
+  prd_json=$(echo "$prd_json" | jq '
+    .feature.status = "pending" |
+    .stories = [.stories[] | . + {passes: (.passes // false)}]
+  ')
+
   # Save
   echo "$prd_json" > "$RALPH_DIR/prd.json"
 
+  # Run full validation
+  if ! validate_prd "$RALPH_DIR/prd.json"; then
+    rm -f "$RALPH_DIR/prd.json"
+    return 1
+  fi
+
   # Show summary
   local name stories complexity
   name=$(echo "$prd_json" | jq -r '.feature.name')

package/ralph/utils.sh

@@ -333,6 +333,77 @@ send_notification() {
   return 0
 }
 
+# Validate PRD structure
+# Returns 0 if valid, 1 if invalid with helpful error messages
+validate_prd() {
+  local prd_file="$1"
+
+  # Check file exists
+  if [[ ! -f "$prd_file" ]]; then
+    print_error "PRD file not found: $prd_file"
+    return 1
+  fi
+
+  # Check valid JSON
+  if ! jq -e . "$prd_file" >/dev/null 2>&1; then
+    print_error "prd.json is not valid JSON."
+    echo ""
+    echo "Fix it manually or regenerate with:"
+    echo "  /idea 'your feature'"
+    echo ""
+    return 1
+  fi
+
+  # Check for stories array
+  if ! jq -e '.stories' "$prd_file" >/dev/null 2>&1; then
+    print_error "prd.json is missing 'stories' array."
+    echo ""
+    echo "Regenerate with: /idea 'your feature'"
+    echo ""
+    return 1
+  fi
+
+  # Check stories is not empty
+  local story_count
+  story_count=$(jq '.stories | length' "$prd_file" 2>/dev/null || echo "0")
+  if [[ "$story_count" == "0" ]]; then
+    print_error "prd.json has no stories."
+    echo ""
+    echo "Regenerate with: /idea 'your feature'"
+    echo ""
+    return 1
+  fi
+
+  # Check each story has required fields
+  local invalid_stories
+  invalid_stories=$(jq -r '.stories[] | select(.id == null or .id == "" or .title == null or .title == "") | .id // "unnamed"' "$prd_file" 2>/dev/null)
+  if [[ -n "$invalid_stories" ]]; then
+    print_error "Some stories are missing required fields (id, title):"
+    echo "$invalid_stories" | head -5
+    echo ""
+    echo "Fix the PRD or regenerate with: /idea 'your feature'"
+    echo ""
+    return 1
+  fi
+
+  # Check stories have passes field (initialize if missing)
+  local missing_passes
+  missing_passes=$(jq '[.stories[] | select(.passes == null)] | length' "$prd_file" 2>/dev/null || echo "0")
+  if [[ "$missing_passes" != "0" ]]; then
+    print_info "Initializing $missing_passes stories with passes=false..."
+    update_json "$prd_file" '(.stories[] | select(.passes == null) | .passes) = false'
+  fi
+
+  # Check feature name exists
+  local feature_name
+  feature_name=$(jq -r '.feature.name // empty' "$prd_file" 2>/dev/null)
+  if [[ -z "$feature_name" ]]; then
+    print_warning "PRD is missing feature name (will show as 'unnamed')"
+  fi
+
+  return 0
+}
+
 # Run migrations if new migration files were created during story
 run_migrations_if_needed() {
   local pre_sha="$1"

package/ralph/verify.sh

@@ -333,7 +333,7 @@ run_unit_tests() {
 run_auto_fix() {
   echo "    Auto-fixing lint issues..."
 
-  # Python: ruff fix
+  # Python: ruff fix (auto-fix what we can)
   if command -v ruff &>/dev/null; then
     ruff check --fix . 2>/dev/null || true
   fi
@@ -374,24 +374,67 @@ run_auto_fix() {
   fi
 }
 
+# Verify lint passes after auto-fix (catch unfixable errors)
+verify_lint() {
+  local failed=0
+
+  # Python: ruff lint check
+  if command -v ruff &>/dev/null && [[ -f "pyproject.toml" || -f "ruff.toml" ]]; then
+    echo -n "    Ruff lint check... "
+    if ruff check . --quiet 2>/dev/null; then
+      print_success "passed"
+    else
+      print_error "failed"
+      echo ""
+      echo "    Unfixable lint errors:"
+      ruff check . 2>/dev/null | head -20 | sed 's/^/      /'
+      failed=1
+    fi
+  fi
+
+  # Check for monorepo backend directories
+  for api_dir in "apps/api" "backend" "api"; do
+    if [[ -d "$api_dir" ]] && [[ -f "$api_dir/pyproject.toml" || -f "$api_dir/ruff.toml" ]]; then
+      echo -n "    Ruff lint check ($api_dir)... "
+      if (cd "$api_dir" && ruff check . --quiet 2>/dev/null); then
+        print_success "passed"
+      else
+        print_error "failed"
+        echo ""
+        echo "    Unfixable lint errors in $api_dir:"
+        (cd "$api_dir" && ruff check . 2>/dev/null) | head -20 | sed 's/^/      /'
+        failed=1
+      fi
+    fi
+  done
+
+  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
+  fi
+
+  # Config-based checks are optional
   if [[ ! -f "$config" ]]; then
-    echo "    (no config.json, skipping)"
+    echo "    (no config.json for additional checks)"
     return 0
   fi
 
-  # Auto-fix lint issues before checking
-  run_auto_fix
-
   # 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)
 
   if [[ -z "$check_names" ]]; then
-    echo "    (no checks configured)"
+    echo "    (no additional checks configured)"
     return 0
   fi