Create Hook

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.

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

Workflow

Phase -1: Iron Law Interlock (Blocking)

This phase is required and cannot be skipped.

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)

1. Capture evidence:

   [E1] Command: pytest tests/hooks/test_${hook_name}.py -v
   Output: FAILED - FileNotFoundError
   Status: RED - 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?

1. 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?

1. 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?

1. Validate the design - Present in sections:

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

1. Document the design:

• Write to docs/plans/YYYY-MM-DD- -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)

1. Hook event type:

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

1. Hook type:

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

1. Matcher pattern (for PreToolUse/PostToolUse):

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

1. 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