hook-factory

# Hook Factory v2.0

**Generate production-ready Claude Code hooks with interactive Q&A, automated installation, and enhanced validation.**

## What This Skill Does

Hook Factory v2.0 is a comprehensive hook generation system with three modes:

1. **Interactive Mode** (NEW!) - 7-question guided flow with smart defaults
2. **Natural Language** - Describe what you want in plain English
3. **Template Mode** - Direct generation from 10 production templates

**Key Features:**
- **Interactive Q&A** - 7 questions with validation and smart defaults
- **Automated Installation** - Python and Bash installers with backup/rollback
- **Enhanced Validation** - Secrets detection, event-specific rules, command validation
- **10 Templates** - Covering 7 event types (PostToolUse, SubagentStop, SessionStart, PreToolUse, UserPromptSubmit, Stop, PrePush)
- **Comprehensive Safety** - Tool detection, silent failure, atomic operations
- **macOS/Linux Support** - Production-ready for Unix environments

## When to Use This Skill

Use hook-factory when you want to:

- Auto-format code after editing
- Automatically stage files with git
- Run tests when agents complete
- Load project context at session start
- Create custom workflow automation
- Learn how hooks work through examples

## Capabilities

### Three Generation Modes

**1. Interactive Mode (Recommended)**
```bash
python3 hook_factory.py -i
```
- 7-question guided flow
- Smart defaults based on event type
- Input validation and safety warnings
- Optional auto-install

**2. Natural Language Mode**
```bash
python3 hook_factory.py -r "auto-format Python files after editing"
```
- Simple keyword matching
- Quick generation for common patterns

**3. Template Mode (Advanced)**
```bash
python3 hook_factory.py -t post_tool_use_format -l python
```
- Direct template selection
- Full customization control

### Supported Hook Templates (10 Total)

**Formatting & Code Quality:**
1. **post_tool_use_format** - Auto-format after editing (Python, JS, TS, Rust, Go)
2. **post_tool_use_git_add** - Auto-stage files with git

**Testing & Validation:**
3. **subagent_stop_test_runner** - Run tests when agent completes
4. **pre_tool_use_validation** - Validate before tool execution
5. **pre_push_validation** - Check before git push

**Session Management:**
6. **session_start_load_context** - Load context at session start
7. **stop_session_cleanup** - Cleanup at session end

**User Interaction:**
8. **user_prompt_submit_preprocessor** - Pre-process user prompts
9. **notify_user_desktop** - Desktop notifications (macOS/Linux)

**Security:**
10. **security_scan_code** - Security scanning with semgrep/bandit

### Languages Supported

- Python (black formatter, pytest)
- JavaScript (prettier, jest)
- TypeScript (prettier, jest)
- Rust (rustfmt, cargo test)
- Go (gofmt, go test)

### Enhanced Validation (v2.0)

**4-Layer Validation System:**

1. **Structure Validation** - JSON syntax, required fields, types
2. **Safety Validation** - No destructive ops, tool detection, silent failure
3. **Matcher Validation** - Valid glob patterns, tool names, file paths
4. **Event-Specific Validation** - Rules per event type (PreToolUse, SessionStart, etc.)

**NEW in v2.0:**
- ✅ **Secrets Detection** - AWS keys, JWT tokens, API keys, private keys (20+ patterns)
- ✅ **Event-Specific Rules** - PreToolUse must have tool matcher, SessionStart read-only, etc.
- ✅ **Command Validation** - Bash syntax, Unix commands, path validation, dangerous operations
- ✅ **macOS/Linux Validation** - Platform-specific command checks

### Safety Features

Every generated hook includes:
- ✅ Tool detection (checks if required tools are installed)
- ✅ Silent failure mode (never interrupts your workflow)
- ✅ Appropriate timeout settings (5s-120s based on event type)
- ✅ No destructive operations
- ✅ Comprehensive validation before generation
- ✅ Clear documentation and troubleshooting guides
- ✅ Automatic backup during installation

## How to Invoke

### Natural Language Requests

Simply describe what you want the hook to do:

```
"I want to auto-format Python files after editing"
"Create a hook that runs tests when agents complete"
"Auto-add files to git after editing"
"Load my TODO.md at session start"
```

### Explicit Template Selection

If you know which template you want:

```
"Generate a hook using the post_tool_use_format template for JavaScript"
"Create a test runner hook for Rust"
```

### List Available Templates

```
"Show me all available hook templates"
"List hook templates"
```

## Example Interactions

### Example 1: Auto-Format Python

**You:** "I need a hook to auto-format my Python code after editing"

**Hook Factory:**
- Detects template: `post_tool_use_format`
- Detects language: Python
- Generates hook with black formatter
- Validates configuration
- Saves to `generated-hooks/auto-format-code-after-editing-python/`
- Creates `hook.json` and `README.md`

### Example 2: Git Auto-Add

**You:** "Automatically stage files with git when I edit them"

**Hook Factory:**
- Detects template: `post_tool_use_git_add`
- Generates git auto-add hook
- Validates git commands
- Saves to `generated-hooks/auto-add-files-to-git-after-editing/`

### Example 3: Test Runner

**You:** "Run my JavaScript tests after the agent finishes coding"

**Hook Factory:**
- Detects template: `subagent_stop_test_runner`
- Detects language: JavaScript
- Configures jest/npm test
- Saves to `generated-hooks/run-tests-when-agent-completes-javascript/`

## Output Structure

For each hook, Hook Factory creates:

```
generated-hooks/
└── [hook-name]/
    ├── hook.json        # Complete hook configuration (validated)
    └── README.md        # Installation guide, usage, troubleshooting
```

### hook.json

Valid JSON configuration ready to copy into your Claude Code settings:

```json
{
  "matcher": {
    "tool_names": ["Write", "Edit"]
  },
  "hooks": [
    {
      "type": "command",
      "command": "if ! command -v black &> /dev/null; then\n    exi