hook-design

name	hook-design
description	Design PreToolUse/PostToolUse hooks for standards enforcement

Hook Design Skill

Integrate standards enforcement into your development workflow via hooks that trigger at specific events.

Context

Hooks are event handlers that run at key moments in the development cycle. PreToolUse hooks run before you execute a tool (write a file, run a command). PostToolUse hooks run after. This skill teaches you to design hooks that provide real-time standards feedback without being intrusive.

Domain Context

Hooks in claude-standards can be:

1. Command hooks — Shell scripts that run and report output
2. Prompt hooks — LLM evaluation with yes/no decisions
3. Agent hooks — Multi-turn verification with tool access

The most useful enforcement hooks are Agent hooks that run the Standards Enforcer against changed files.

Reference: levels/L3-enforcement/hooks/ and CLAUDE.md hook documentation

Instructions

1. Identify which tool events matter — What triggers should fire enforcement?

   • PreToolUse on Edit/Write — Before file changes saved
   • PostToolUse on Edit/Write — After file changes saved
   • PreToolUse on Bash — Before running shell commands
   • PostToolUse on Bash — After running commands
   • Think about: Which events represent "code work"? When is feedback most useful?
   • Deliverable: List of tool events to hook

2. Choose hook type — Command, prompt, or agent?

   • Command hook: Simple, fast, no context needed (e.g., run linter)
   • Prompt hook: Decision-making, yes/no answer (e.g., "Does this look right?")
   • Agent hook: Complex analysis, tool access (e.g., run Standards Enforcer)
   • For standards enforcement, Agent hooks are usually best
   • Deliverable: Hook type decision + justification

3. Write hook configuration — Define the hook in JSON or YAML

   • Event: PreToolUse or PostToolUse
   • Tool matcher: Edit, Write, Bash, etc.
   • Hook type: command, prompt, or agent
   • If agent: reference the Standards Enforcer agent
   • If command: shell script to run
   • Deliverable: Hook configuration file

4. Design trigger logic — When should hook actually fire?

   • Should it fire on every file change? (Can be too noisy)
   • Should it fire only on certain file patterns? (More focused)
   • Should it fire before or after change? (Before = prevention, after = detection)
   • Consider: Performance impact, signal-to-noise ratio
   • Deliverable: Hook trigger rules

5. Test with examples — Verify hook works as designed

   • Scenario 1: Compliant code → Hook should pass silently
   • Scenario 2: Code with WARNING → Hook should report and allow
   • Scenario 3: Code with ERROR → Hook should report and ask for confirmation
   • Run test scenarios
   • Deliverable: Test results showing hook works

6. Define escalation — What happens if hook finds violations?

   • Can user ignore (INFO level)? Yes
   • Can user override (WARN level)? With confirmation
   • Can user skip (ERROR level)? No, blocked
   • Document the user experience
   • Deliverable: Escalation policy document

Anti-Patterns

1. Hooks that fire on every operation — Productivity killer

   • Wrong: Hook on every Bash command (including cd, ls, etc.)
   • Right: Hook only on tool use that matters (Edit, Write, specific commands)
   • Impact: Hook fires 100x per session → user disables it
   • Guard: Test hook on realistic workflow; should fire <5 times per session

2. Hooks generating false positives — Creates distrust

   • Happens when: Standard rules are ambiguous or agent misunderstands
   • Example: Hook reports "unknown type found" for valid unknown type
   • Impact: User learns to ignore hook warnings
   • Guard: Test hook on many real code examples before deploying

3. Enforcement without standards to back it up — Rules seem arbitrary

   • Wrong: Hook enforces "max function length 30 lines" but no standard documents this
   • Right: Hook enforces rule from docs/standards/engineering/code-quality.md
   • Impact: User can't understand why hook is blocking them
   • Guard: Every hook check must cite a standard; user can read it

4. Hooks that slow down development — Performance regression

   • Happens when: Agent hook makes expensive analysis calls
   • Example: Hook runs full enforcement agent on every keystroke
   • Impact: Development becomes noticeably slower
   • Guard: Test hook performance on large code files; should complete <2 seconds

Further Reading

• levels/L3-enforcement/hooks/ — Reference hook configurations
• levels/L3-enforcement/agents/standards-enforcer.md — Enforcement agent to use with hooks
• CLAUDE.md section on hooks — Hook configuration format and options