/create-hook

name: create-hook
description: Create hooks with brainstorming and security-first design
usage: /create-hook [hook-description] [--skip-brainstorm] [--plugin <name>] [--event <type>]

Create Hook Command

Creates new hooks through a structured workflow: **iron-law → brainstorm → design → scaffold → validate**. Uses Socratic questioning to refine rough ideas into well-designed, secure hooks before generating any files.

**Important**: This workflow enforces the Iron Law. You cannot create hook files without first creating and running failing tests. See [Iron Law Interlock](../shared-modules/iron-law-interlock.md).

When To Use

Use this command when you need to:

• Creating a new hook from scratch
• Need security-first design guidance
• Want structured workflow for hook development with Socratic questioning

When NOT To Use

Avoid this command if:

• Evaluating existing hooks - use /hooks-eval instead
• Deciding where to place hooks - use hook-scope-guide skill
• Validating hook security - use /validate-hook instead

Usage

# Start with brainstorming (recommended)
/create-hook "detect when user shares sensitive files"

# Skip brainstorming if design is clear
/create-hook secret-detector --skip-brainstorm --event PreToolUse

# Create in specific plugin
/create-hook "auto-format on save" --plugin sanctum --event PostToolUse

Hook Event Types

| Event | When It Fires | Common Use Cases | |-------|---------------|------------------| | `UserPromptSubmit` | User submits a prompt | Input validation, context injection | | `PreToolUse` | Before tool execution | Security checks, blocking dangerous ops | | `PostToolUse` | After tool completes | Logging, post-processing, notifications | | `Notification` | Claude sends notification | Custom alerts, sound effects | | `Stop` | Session/task ends | Cleanup, summaries, checkpoints | | `SubagentStop` | Subagent completes | Aggregation, reporting | | `TeammateIdle` | Teammate agent becomes idle | Work assignment, load balancing | | `TaskCompleted` | Task finishes execution | Coordination, chaining, reporting | | `PreCompact` | Before context compaction | Backup, preservation | | `SessionStart` | Session begins | Context loading, initialization |

Workflow

Phase -1: Iron Law Interlock (Blocking)

**This phase is required and cannot be skipped.**

Before any file creation, satisfy the Iron Law interlock. See [iron-law-interlock.md](../shared-modules/iron-law-interlock.md) for full details.

Quick Reference

1. **Create test file FIRST**: `tests/hooks/test_${hook_name}.py` 2. **Write structural tests**: Hook file exists, valid JSON/Python, registered correctly 3. **Run tests - capture RED state**:

   pytest tests/hooks/test_${hook_name}.py -v
   # Expected: FAILED (hook does not exist)

4. **Capture evidence**:

   [E1] Command: pytest tests/hooks/test_${hook_name}.py -v
   Output: FAILED - FileNotFoundError
   Status: RED - Interlock satisfied

5. **TodoWrite**: `proof:iron-law-red`, `proof:iron-law-interlock-satisfied`

**Only after completing Phase -1 may you proceed.**

---

Phase 0: Brainstorming (Default)

Before creating any files, refine the hook concept through collaborative dialogue.

**Invoke the brainstorming skill:**

Use superpowers:brainstorming to refine this hook idea before scaffolding.

The brainstorming phase will:

1. **Understand the purpose** - One question at a time:

• What behavior do you want to intercept or modify?
• Which hook event is appropriate? (present options with trade-offs)
• Should this block, modify, or observe?
• What data do you need from the hook payload?

2. **Explore security implications**:

• What could go wrong if this hook misbehaves?
• What input validation is needed?
• Are there timeout considerations?
• Should this hook be blocking or non-blocking?

3. **Design the implementation**:

• JSON declarative hook vs. executable script?
• If script: Python, Bash, or other?
• What shared utilities might this need?
• How will errors be handled?

4. **Validate the design** - Present in sections:

• Hook configuration (JSON structure)
• Script logic (if applicable)
• Error handling approach
• Testing strategy

5. **Document the design**:

• Write to `docs/plans/YYYY-MM-DD-<hook-name>-design.md`
• Include security considerations
• Commit the design document

**Skip brainstorming** with `--skip-brainstorm` only when:

• You have a written design document already
• The hook is a simple copy of an existing pattern
• You're making a minor modification to existing hooks

Phase 1: Gather Requirements

After brainstorming (or with `--skip-brainstorm`), the command prompts for:

1. **Hook name** (if not provided)

• Must be kebab-case
• Descriptive of function (e.g., `secret-detector`, `format-on-save`)
• No generic names (`my-hook`, `test-hook`)

2. **Hook event type**:

• One of the 8 supported events
• Explain the choice based on timing needs

3. **Hook type**:

• `declarative` (JSON only): Simple matchers and conditions
• `script` (Python): Complex logic, external dependencies
• `script` (Bash): Shell operations, simple transformations

4. **Matcher pattern** (for PreToolUse/PostToolUse):

• Tool name regex (e.g., `Read|Write|Edit`)
• Leave empty for all tools

5. **Timeout** (for scripts):

• Default: 10 seconds
• Maximum: 60 seconds (with justification)

Phase 2: Security Review

Before scaffolding, validate security considerations:

Security Checklist:
  [ ] Input validation for all payload fields
  [ ] No shell injection vulnerabilities
  [ ] No path traversal vulnerabilities
  [ ] Timeout configured appropriately
  [ ] Error handling doesn't leak secrets
  [ ] Logging doesn't capture sensitive data

Phase 3: Create Hook Structure

**For declarative hooks:**

hooks/
├── hooks.json           # Add hook configuration
└── ${hoo