@codihaus/claude-skills 1.5.0 → 1.6.0

package/templates/hooks-guide.md

@@ -0,0 +1,372 @@
+# Claude Code Hooks Configuration Guide
+
+## Overview
+
+Hooks allow you to run commands automatically in response to Claude Code events. However, **poorly configured hooks can cause infinite retry loops** and block your workflow.
+
+## Hook Failure Problem
+
+**Symptom**: Hook fails repeatedly (>10 times) without stopping
+**Impact**:
+- Wastes resources
+- Slows down workflow
+- Can cause infinite loops
+- Blocks Claude from proceeding
+
+**Root Cause**: Missing retry limits and failure handling
+
+## Best Practices
+
+### 1. Always Add Retry Limits
+
+```json
+{
+  "postToolUse": [{
+    "matcher": {
+      "toolName": "Write|Edit",
+      "path": "plans/**/*.md"
+    },
+    "command": "bash .claude/scripts/safe-graph-update.sh $PATH",
+    "retries": {
+      "maxAttempts": 3,
+      "backoff": "exponential",
+      "failureAction": "warn"
+    },
+    "timeout": 5000
+  }]
+}
+```
+
+**Key Fields:**
+- `maxAttempts`: Stop after N failures (recommended: 2-3)
+- `backoff`: Wait strategy ("none", "linear", "exponential")
+- `failureAction`: What to do after max attempts
+  - `"warn"` - Show warning, continue (recommended)
+  - `"error"` - Stop and ask user for help
+  - `"ignore"` - Silent failure (not recommended)
+- `timeout`: Kill hook after N milliseconds (recommended: 5000-10000)
+
+### 2. Make Commands Fail Gracefully
+
+Always append `|| true` to prevent hook failures from blocking:
+
+```bash
+# Good - fails gracefully
+python3 scripts/graph.py --check-path $PATH || true
+
+# Bad - failure blocks Claude
+python3 scripts/graph.py --check-path $PATH
+```
+
+### 3. Add Timeout Guards
+
+Protect against hanging commands:
+
+```json
+{
+  "command": "timeout 10s python3 scripts/graph.py --check-path $PATH || true",
+  "timeout": 15000
+}
+```
+
+Double protection:
+- `timeout 10s` - Linux/macOS command-level timeout
+- `"timeout": 15000` - Claude Code timeout (slightly longer as buffer)
+
+### 4. Use Specific Path Matchers
+
+Match only the files that need processing to avoid unnecessary hook runs:
+
+| Pattern | Matches | Use Case |
+|---------|---------|----------|
+| `plans/**/*` | All files in plans/ | ❌ Too broad - includes images, xlsx, etc. |
+| `plans/**/*.md` | Only .md files in plans/ | ✅ Good - documentation only |
+| `plans/brd/**/*.md` | Only .md in plans/brd/ | ✅ More specific |
+| `*.md` | All .md files | ❌ Too broad - includes root README.md |
+| `**/*.md` | All .md files anywhere | ❌ Too broad - performance issue |
+
+**Why specificity matters:**
+```
+Bad: path: "plans/**/*"
+→ Triggers on: .md, .xlsx, .png, .json (wastes resources)
+→ Hook runs 100 times when only 20 needed
+
+Good: path: "plans/**/*.md"
+→ Triggers on: .md only
+→ Hook runs 20 times, saves 80% of executions
+```
+
+**Example - Multiple patterns:**
+```json
+{
+  "postToolUse": [
+    {
+      "matcher": {
+        "toolName": "Write|Edit",
+        "path": "plans/**/*.md"
+      },
+      "command": "bash .claude/scripts/safe-graph-update.sh $PATH"
+    },
+    {
+      "matcher": {
+        "toolName": "Write",
+        "path": "src/**/*.ts"
+      },
+      "command": "npm run lint-staged"
+    }
+  ]
+}
+```
+
+### 5. Keep Hooks Fast
+
+| Duration | Recommendation |
+|----------|----------------|
+| < 1s | Excellent |
+| 1-2s | Good |
+| 2-5s | Acceptable |
+| > 5s | Too slow - optimize or make async |
+
+**Slow hooks block your workflow.** If a hook needs > 5s, consider:
+- Running it on-demand instead of as a hook
+- Making it asynchronous
+- Optimizing the script
+
+### 5. Add Dependency Checks
+
+Check if required tools exist before running:
+
+```json
+{
+  "command": "command -v python3 >/dev/null 2>&1 && python3 scripts/graph.py --check-path $PATH || true"
+}
+```
+
+Or use a wrapper script:
+
+```bash
+#!/bin/bash
+# .claude/scripts/safe-graph-update.sh
+
+if ! command -v python3 &> /dev/null; then
+  echo "Python3 not found, skipping graph update"
+  exit 0
+fi
+
+if [ ! -f "scripts/graph.py" ]; then
+  echo "graph.py not found, skipping"
+  exit 0
+fi
+
+timeout 10s python3 scripts/graph.py --check-path "$1" || true
+```
+
+Then in hooks.json:
+```json
+{
+  "command": "bash .claude/scripts/safe-graph-update.sh $PATH"
+}
+```
+
+## Failure Action Strategy
+
+Choose the right `failureAction` based on hook criticality:
+
+| Hook Type | Criticality | Recommended Action |
+|-----------|-------------|-------------------|
+| Documentation updates (graph.py) | Low | `"warn"` - Show warning, continue |
+| Linting/formatting | Medium | `"warn"` - Show warning, continue |
+| Security checks | High | `"error"` - Stop and ask user |
+| Required validations | Critical | `"error"` - Stop and ask user |
+
+**Example - Non-critical hook:**
+```json
+{
+  "command": "python3 scripts/graph.py --check-path $PATH || true",
+  "retries": {
+    "maxAttempts": 3,
+    "failureAction": "warn"
+  }
+}
+```
+
+**Example - Critical hook:**
+```json
+{
+  "command": "npm run validate-security",
+  "retries": {
+    "maxAttempts": 2,
+    "failureAction": "error"
+  }
+}
+```
+
+## Debugging Hook Failures
+
+If a hook keeps failing:
+
+### 1. Check Hook Logs
+
+Claude Code logs hook output. Look for:
+```
+[Hook Failed] postToolUse: python3 scripts/graph.py
+Exit code: 1
+Stderr: ModuleNotFoundError: No module named 'networkx'
+```
+
+### 2. Test Command Manually
+
+Run the hook command directly:
+```bash
+cd /path/to/project
+python3 scripts/graph.py --check-path plans/brd/README.md
+```
+
+### 3. Common Issues
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `ModuleNotFoundError` | Missing Python package | Install: `pip3 install --user <package>` |
+| `command not found` | Tool not installed | Install tool or remove hook |
+| `Permission denied` | Script not executable | `chmod +x scripts/*.sh` |
+| `Timeout` | Script too slow | Optimize script or increase timeout |
+| `File not found` | Path mismatch | Check $PATH variable substitution |
+
+### 4. Temporary Disable
+
+To temporarily disable a problematic hook:
+
+```json
+{
+  "postToolUse": [
+    {
+      "matcher": {
+        "toolName": "Write|Edit",
+        "path": "plans/**/*"
+      },
+      "command": "python3 scripts/graph.py --check-path $PATH || true",
+      "enabled": false
+    }
+  ]
+}
+```
+
+Or delete `.claude/hooks.json` entirely (hooks are optional).
+
+## Example: Robust Hook Configuration
+
+```json
+{
+  "postToolUse": [
+    {
+      "matcher": {
+        "toolName": "Write|Edit",
+        "path": "plans/**/*"
+      },
+      "command": "bash .claude/scripts/safe-graph-update.sh $PATH",
+      "retries": {
+        "maxAttempts": 3,
+        "backoff": "exponential",
+        "failureAction": "warn"
+      },
+      "timeout": 10000,
+      "enabled": true
+    }
+  ],
+  "preToolUse": [],
+  "onError": []
+}
+```
+
+With `.claude/scripts/safe-graph-update.sh`:
+```bash
+#!/bin/bash
+set -e
+
+# Exit early if tools missing
+command -v python3 >/dev/null 2>&1 || exit 0
+
+# Exit early if script missing
+[ -f "scripts/graph.py" ] || exit 0
+
+# Run with timeout and graceful failure
+timeout 10s python3 scripts/graph.py --check-path "$1" || {
+  echo "Graph update failed (non-critical), continuing..."
+  exit 0
+}
+```
+
+## Migration Guide
+
+### Old Configuration (Problematic)
+
+```json
+{
+  "postToolUse": [{
+    "matcher": { "toolName": "Write|Edit", "path": "plans/**/*" },
+    "command": "python3 scripts/graph.py --check-path $PATH"
+  }]
+}
+```
+
+**Problems:**
+- ❌ No retry limit (infinite retries)
+- ❌ No timeout (can hang forever)
+- ❌ Failures block Claude
+- ❌ Too broad path matcher (triggers on images, xlsx, etc.)
+
+### New Configuration (Robust)
+
+```json
+{
+  "postToolUse": [{
+    "matcher": { "toolName": "Write|Edit", "path": "plans/**/*.md" },
+    "command": "bash .claude/scripts/safe-graph-update.sh $PATH",
+    "retries": {
+      "maxAttempts": 3,
+      "backoff": "exponential",
+      "failureAction": "warn"
+    },
+    "timeout": 5000
+  }]
+}
+```
+
+**Improvements:**
+- ✅ Max 3 retry attempts (stops infinite loops)
+- ✅ 5 second timeout per attempt (prevents hanging)
+- ✅ Exponential backoff between retries (less aggressive)
+- ✅ Warns but doesn't block on failure (non-blocking)
+- ✅ Specific path matcher `**/*.md` (only markdown files)
+- ✅ Safe wrapper script with multiple protections
+
+## When to Ask User for Help
+
+Configure `"failureAction": "error"` when:
+1. Hook has failed `maxAttempts` times
+2. Issue is not automatically fixable
+3. User intervention is needed
+4. Hook is critical to workflow
+
+Claude Code will then:
+1. Stop execution
+2. Show error message with hook details
+3. Ask: "Hook 'postToolUse:graph.py' failed 3 times. What would you like to do?"
+   - Fix and retry
+   - Skip this hook
+   - Disable hook permanently
+   - Continue without hook
+
+## Summary Checklist
+
+When configuring hooks, ensure:
+
+- [ ] `maxAttempts` set (2-3 recommended)
+- [ ] `timeout` set (5000-10000ms recommended)
+- [ ] `failureAction` appropriate for criticality
+- [ ] Command ends with `|| true` for graceful failure
+- [ ] Hook completes in < 2 seconds ideally
+- [ ] Dependencies checked before execution
+- [ ] Tested manually before committing
+
+**Remember**: Hooks are helpers, not requirements. It's better to have no hook than a broken one that blocks your workflow.

package/templates/scripts/safe-graph-update.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+#
+# Safe Graph Update Wrapper
+#
+# This script provides resilient execution of graph.py with:
+# - Dependency checking
+# - Graceful failure handling
+# - Timeout protection
+# - Clear error messages
+#
+
+set -e
+
+# Configuration
+TIMEOUT_SECONDS=10
+GRAPH_SCRIPT="scripts/graph.py"
+MAX_RETRIES=0  # Let Claude Code handle retries
+
+# Colors for output (optional)
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+# Check if Python3 is available
+if ! command -v python3 &> /dev/null; then
+    echo -e "${YELLOW}Python3 not found. Skipping graph update.${NC}" >&2
+    exit 0
+fi
+
+# Check if graph.py exists
+if [ ! -f "$GRAPH_SCRIPT" ]; then
+    echo -e "${YELLOW}$GRAPH_SCRIPT not found. Skipping graph update.${NC}" >&2
+    exit 0
+fi
+
+# Get the file path argument
+FILE_PATH="$1"
+
+if [ -z "$FILE_PATH" ]; then
+    echo -e "${YELLOW}No file path provided. Skipping graph update.${NC}" >&2
+    exit 0
+fi
+
+# Only update graph for .md files in plans/ directory
+if [[ ! "$FILE_PATH" =~ ^plans/.*\.md$ ]]; then
+    exit 0
+fi
+
+# Run graph.py with timeout
+if timeout "$TIMEOUT_SECONDS" python3 "$GRAPH_SCRIPT" --check-path "$FILE_PATH" 2>/dev/null; then
+    # Success - silent
+    exit 0
+else
+    EXIT_CODE=$?
+    if [ $EXIT_CODE -eq 124 ]; then
+        # Timeout
+        echo -e "${YELLOW}Graph update timed out after ${TIMEOUT_SECONDS}s (non-critical).${NC}" >&2
+    elif [ $EXIT_CODE -ne 0 ]; then
+        # Other error
+        echo -e "${YELLOW}Graph update failed with exit code $EXIT_CODE (non-critical).${NC}" >&2
+    fi
+    # Always exit 0 to prevent blocking Claude
+    exit 0
+fi