@amsterdamdatalabs/enact-extensions 0.1.42 → 0.1.47

package/extensions/plugin-dev/skills/hook-development/references/patterns.md

@@ -1,430 +0,0 @@
-# Common Hook Patterns
-
-This reference provides common, proven patterns for implementing Claude Code hooks. Use these patterns as starting points for typical hook use cases.
-
-## Pattern 1: Security Validation
-
-Block dangerous file writes using prompt-based hooks:
-
-```json
-{
-  "PreToolUse": [
-    {
-      "matcher": "Write|Edit",
-      "hooks": [
-        {
-          "type": "prompt",
-          "prompt": "File path: $TOOL_INPUT.file_path. Verify: 1) Not in /etc or system directories 2) Not .env or credentials 3) Path doesn't contain '..' traversal. Return 'approve' or 'deny'."
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Use for:** Preventing writes to sensitive files or system directories.
-
-## Pattern 2: Test Enforcement
-
-Ensure tests run before stopping:
-
-```json
-{
-  "Stop": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "prompt",
-          "prompt": "Review transcript. If code was modified (Write/Edit tools used), verify tests were executed. If no tests were run, block with reason 'Tests must be run after code changes'."
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Use for:** Enforcing quality standards and preventing incomplete work.
-
-## Pattern 3: Context Loading
-
-Load project-specific context at session start:
-
-```json
-{
-  "SessionStart": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh"
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Example script (load-context.sh):**
-
-```bash
-#!/bin/bash
-cd "$CLAUDE_PROJECT_DIR" || exit 1
-
-# Detect project type
-if [ -f "package.json" ]; then
-  echo "📦 Node.js project detected"
-  echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"
-elif [ -f "Cargo.toml" ]; then
-  echo "🦀 Rust project detected"
-  echo "export PROJECT_TYPE=rust" >> "$CLAUDE_ENV_FILE"
-fi
-```
-
-**Use for:** Automatically detecting and configuring project-specific settings.
-
-## Pattern 4: Notification Logging
-
-Log all notifications for audit or analysis:
-
-```json
-{
-  "Notification": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-notification.sh"
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Use for:** Tracking user notifications or integration with external logging systems.
-
-## Pattern 5: MCP Tool Monitoring
-
-Monitor and validate MCP tool usage:
-
-```json
-{
-  "PreToolUse": [
-    {
-      "matcher": "mcp__.*__delete.*",
-      "hooks": [
-        {
-          "type": "prompt",
-          "prompt": "Deletion operation detected. Verify: Is this deletion intentional? Can it be undone? Are there backups? Return 'approve' only if safe."
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Use for:** Protecting against destructive MCP operations.
-
-## Pattern 6: Build Verification
-
-Ensure project builds after code changes:
-
-```json
-{
-  "Stop": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "prompt",
-          "prompt": "Check if code was modified. If Write/Edit tools were used, verify the project was built (npm run build, cargo build, etc). If not built, block and request build."
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Use for:** Catching build errors before committing or stopping work.
-
-## Pattern 7: Permission Confirmation
-
-Ask user before dangerous operations:
-
-```json
-{
-  "PreToolUse": [
-    {
-      "matcher": "Bash",
-      "hooks": [
-        {
-          "type": "prompt",
-          "prompt": "Command: $TOOL_INPUT.command. If command contains 'rm', 'delete', 'drop', or other destructive operations, return 'ask' to confirm with user. Otherwise 'approve'."
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Use for:** User confirmation on potentially destructive commands.
-
-## Pattern 8: Code Quality Checks
-
-Run linters or formatters on file edits:
-
-```json
-{
-  "PostToolUse": [
-    {
-      "matcher": "Write|Edit",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-quality.sh"
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Example script (check-quality.sh):**
-
-```bash
-#!/bin/bash
-input=$(cat)
-file_path=$(echo "$input" | jq -r '.tool_input.file_path')
-
-# Run linter if applicable
-if [[ "$file_path" == *.js ]] || [[ "$file_path" == *.ts ]]; then
-  npx eslint "$file_path" 2>&1 || true
-fi
-```
-
-**Use for:** Automatic code quality enforcement.
-
-## Pattern Combinations
-
-Combine multiple patterns for comprehensive protection:
-
-```json
-{
-  "PreToolUse": [
-    {
-      "matcher": "Write|Edit",
-      "hooks": [
-        {
-          "type": "prompt",
-          "prompt": "Validate file write safety"
-        }
-      ]
-    },
-    {
-      "matcher": "Bash",
-      "hooks": [
-        {
-          "type": "prompt",
-          "prompt": "Validate bash command safety"
-        }
-      ]
-    }
-  ],
-  "Stop": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "prompt",
-          "prompt": "Verify tests run and build succeeded"
-        }
-      ]
-    }
-  ],
-  "SessionStart": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh"
-        }
-      ]
-    }
-  ]
-}
-```
-
-This provides multi-layered protection and automation.
-
-## Pattern 9: Temporarily Active Hooks
-
-Create hooks that only run when explicitly enabled via flag files:
-
-```bash
-#!/bin/bash
-# Hook only active when flag file exists
-FLAG_FILE="$CLAUDE_PROJECT_DIR/.enable-security-scan"
-
-if [ ! -f "$FLAG_FILE" ]; then
-  # Quick exit when disabled
-  exit 0
-fi
-
-# Flag present, run validation
-input=$(cat)
-file_path=$(echo "$input" | jq -r '.tool_input.file_path')
-
-# Run security scan
-security-scanner "$file_path"
-```
-
-**Activation:**
-
-```bash
-# Enable the hook
-touch .enable-security-scan
-
-# Disable the hook
-rm .enable-security-scan
-```
-
-**Use for:**
-
-- Temporary debugging hooks
-- Feature flags for development
-- Project-specific validation that's opt-in
-- Performance-intensive checks only when needed
-
-**Note:** Must restart Claude Code after creating/removing flag files for hooks to recognize changes.
-
-## Pattern 10: Configuration-Driven Hooks
-
-Use JSON configuration to control hook behavior:
-
-```bash
-#!/bin/bash
-CONFIG_FILE="$CLAUDE_PROJECT_DIR/.claude/my-plugin.local.json"
-
-# Read configuration
-if [ -f "$CONFIG_FILE" ]; then
-  strict_mode=$(jq -r '.strictMode // false' "$CONFIG_FILE")
-  max_file_size=$(jq -r '.maxFileSize // 1000000' "$CONFIG_FILE")
-else
-  # Defaults
-  strict_mode=false
-  max_file_size=1000000
-fi
-
-# Skip if not in strict mode
-if [ "$strict_mode" != "true" ]; then
-  exit 0
-fi
-
-# Apply configured limits
-input=$(cat)
-file_size=$(echo "$input" | jq -r '.tool_input.content | length')
-
-if [ "$file_size" -gt "$max_file_size" ]; then
-  echo '{"decision": "deny", "reason": "File exceeds configured size limit"}' >&2
-  exit 2
-fi
-```
-
-**Configuration file (.claude/my-plugin.local.json):**
-
-```json
-{
-  "strictMode": true,
-  "maxFileSize": 500000,
-  "allowedPaths": ["/tmp", "/home/user/projects"]
-}
-```
-
-**Use for:**
-
-- User-configurable hook behavior
-- Per-project settings
-- Team-specific rules
-- Dynamic validation criteria
-
-## Pattern 11: TeammateIdle Notification
-
-Send notifications when agent team teammates go idle:
-
-```json
-{
-  "TeammateIdle": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/notify-idle.sh"
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Example script (notify-idle.sh):**
-
-```bash
-#!/bin/bash
-input=$(cat)
-teammate=$(echo "$input" | jq -r '.teammate_name')
-team=$(echo "$input" | jq -r '.team_name')
-
-# Log or notify
-echo "Teammate $teammate in team $team went idle" >> /tmp/team-log.txt
-
-# Exit 0 to allow idle, exit 2 to keep teammate working
-exit 0
-```
-
-**Use for:** Monitoring team progress, logging teammate activity, enforcing work standards.
-
-## Pattern 12: Task Completion Verification
-
-Verify task quality before accepting completion:
-
-```json
-{
-  "TaskCompleted": [
-    {
-      "matcher": "*",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/verify-task.sh"
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Example script (verify-task.sh):**
-
-```bash
-#!/bin/bash
-input=$(cat)
-task_subject=$(echo "$input" | jq -r '.task_subject')
-
-# Check if tests were mentioned in the task
-if echo "$task_subject" | grep -qi "implement\|add\|create"; then
-  # Verify tests exist for implementation tasks
-  if [ ! -f "/tmp/tests-ran-$$" ]; then
-    echo "Implementation task completed without running tests" >&2
-    exit 2  # Block completion
-  fi
-fi
-
-exit 0
-```
-
-**Use for:** Enforcing quality gates, preventing premature task completion, team workflow standards.

package/extensions/plugin-dev/skills/hook-development/scripts/README.md

@@ -1,181 +0,0 @@
-# Hook Development Utility Scripts
-
-These scripts help validate, test, and lint hook implementations before deployment.
-
-## validate-hook-schema.sh
-
-Validates `hooks.json` configuration files for correct structure and common issues.
-
-**Usage:**
-
-```bash
-./validate-hook-schema.sh path/to/hooks.json
-```
-
-**Checks:**
-
-- Valid JSON syntax
-- Required fields present
-- Valid hook event names
-- Proper hook types (command/prompt)
-- Timeout values in valid ranges
-- Hardcoded path detection
-- Prompt hook event compatibility
-
-**Example:**
-
-```bash
-cd my-plugin
-./validate-hook-schema.sh hooks/hooks.json
-```
-
-## test-hook.sh
-
-Tests individual hook scripts with sample input before deploying to Claude Code.
-
-**Usage:**
-
-```bash
-./test-hook.sh [options] <hook-script> <test-input.json>
-```
-
-**Options:**
-
-- `-v, --verbose` - Show detailed execution information
-- `-t, --timeout N` - Set timeout in seconds (default: 60)
-- `--create-sample <event-type>` - Generate sample test input
-
-**Example:**
-
-```bash
-# Create sample test input
-./test-hook.sh --create-sample PreToolUse > test-input.json
-
-# Test a hook script
-./test-hook.sh my-hook.sh test-input.json
-
-# Test with verbose output and custom timeout
-./test-hook.sh -v -t 30 my-hook.sh test-input.json
-```
-
-**Features:**
-
-- Sets up proper environment variables (CLAUDE_PROJECT_DIR, CLAUDE_PLUGIN_ROOT)
-- Measures execution time
-- Validates output JSON
-- Shows exit codes and their meanings
-- Captures environment file output
-
-## hook-linter.sh
-
-Checks hook scripts for common issues and best practices violations.
-
-**Usage:**
-
-```bash
-./hook-linter.sh <hook-script.sh> [hook-script2.sh ...]
-```
-
-**Checks:**
-
-- Shebang presence
-- `set -euo pipefail` usage
-- Stdin input reading
-- Proper error handling
-- Variable quoting (injection prevention)
-- Exit code usage
-- Hardcoded paths
-- Long-running code detection
-- Error output to stderr
-- Input validation
-
-**Example:**
-
-```bash
-# Lint single script
-./hook-linter.sh ../examples/validate-write.sh
-
-# Lint multiple scripts
-./hook-linter.sh ../examples/*.sh
-```
-
-## Typical Workflow
-
-1. **Write your hook script**
-
-   ```bash
-   vim my-plugin/scripts/my-hook.sh
-   ```
-
-2. **Lint the script**
-
-   ```bash
-   ./hook-linter.sh my-plugin/scripts/my-hook.sh
-   ```
-
-3. **Create test input**
-
-   ```bash
-   ./test-hook.sh --create-sample PreToolUse > test-input.json
-   # Edit test-input.json as needed
-   ```
-
-4. **Test the hook**
-
-   ```bash
-   ./test-hook.sh -v my-plugin/scripts/my-hook.sh test-input.json
-   ```
-
-5. **Add to hooks.json**
-
-   ```bash
-   # Edit my-plugin/hooks/hooks.json
-   ```
-
-6. **Validate configuration**
-
-   ```bash
-   ./validate-hook-schema.sh my-plugin/hooks/hooks.json
-   ```
-
-7. **Test in Claude Code**
-   ```bash
-   claude --debug
-   ```
-
-## Tips
-
-- Always test hooks before deploying to avoid breaking user workflows
-- Use verbose mode (`-v`) to debug hook behavior
-- Check the linter output for security and best practice issues
-- Validate hooks.json after any changes
-- Create different test inputs for various scenarios (safe operations, dangerous operations, edge cases)
-
-## Common Issues
-
-### Hook doesn't execute
-
-Check:
-
-- Script has shebang (`#!/bin/bash`)
-- Script is executable (`chmod +x`)
-- Path in hooks.json is correct (use `${CLAUDE_PLUGIN_ROOT}`)
-
-### Hook times out
-
-- Reduce timeout in hooks.json
-- Optimize hook script performance
-- Remove long-running operations
-
-### Hook fails silently
-
-- Check exit codes (should be 0 or 2)
-- Ensure errors go to stderr (`>&2`)
-- Validate JSON output structure
-
-### Injection vulnerabilities
-
-- Always quote variables: `"$variable"`
-- Use `set -euo pipefail`
-- Validate all input fields
-- Run the linter to catch issues