Initial commit

2025-11-29 18:19:59 +08:00
commit 9f60012661
14 changed files with 824 additions and 0 deletions
--- a/skills/scaffold-claude-feature/references/hooks.md
+++ b/skills/scaffold-claude-feature/references/hooks.md
@@ -0,0 +1,167 @@
+# Hooks Reference
+
+Quick reference for creating event hooks. For complete documentation, see @docs-claude/hooks-reference.md
+
+## Structure
+
+Add to settings.json:
+```json
+{
+  "hooks": {
+    "EventName": [
+      {
+        "matcher": "ToolPattern",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "your-command"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Location
+
+- Project: `.claude/settings.json`
+- Personal: `~/.claude/settings.json`
+- Local: `.claude/settings.local.json` (gitignored)
+
+## Hook Types
+
+- `"type": "command"` - Execute bash command
+- `"type": "prompt"` - LLM-based evaluation
+
+## Common Events
+
+- `PreToolUse` - Before tool runs (can block)
+- `PostToolUse` - After tool completes
+- `UserPromptSubmit` - Before processing user prompt
+- `Stop` - When Claude finishes
+- `SubagentStop` - When subagent finishes
+- `Notification` - On notifications
+- `SessionStart` - Session begins
+- `SessionEnd` - Session ends
+
+## Matchers
+
+**For PreToolUse/PostToolUse:**
+- `"Write"` - Exact match
+- `"Write|Edit"` - Multiple tools
+- `"Notebook.*"` - Regex pattern
+- `"*"` - All tools
+
+**For other events:** Omit matcher
+
+## Exit Codes (Command Type)
+
+- `0` - Success
+- `2` - Block action, show stderr to Claude
+- Other - Error, execution continues
+
+## Simple Examples
+
+**Format on write:**
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "prettier --write $file"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Prevent stopping:**
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-todos.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Validate bash commands:**
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python $CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Hook Input
+
+Hooks receive JSON via stdin:
+```json
+{
+  "session_id": "abc123",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Write",
+  "tool_input": { "file_path": "/path/to/file" }
+}
+```
+
+## Environment Variables
+
+- `$CLAUDE_PROJECT_DIR` - Project root path
+- `$CLAUDE_ENV_FILE` - SessionStart only, for env vars
+
+## Tips
+
+- Use `$CLAUDE_PROJECT_DIR` for project scripts
+- Test hooks with `claude --debug`
+- Exit code 2 blocks and sends stderr to Claude
+- Keep hooks fast (60s timeout default)
+- For complete API, see @docs-claude/hooks-reference.md
+
+## Prompt-Based Hooks
+
+Use LLM for intelligent decisions:
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Check if all tasks complete: $ARGUMENTS"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+LLM responds with: `{"decision": "approve"|"block", "reason": "..."}`