hook-management

What this skill does

# Hooks Meta Skill

## 🚨 MANDATORY: Invoke docs-management First

> **STOP - Before providing ANY response about Claude Code hooks:**
>
> 1. **INVOKE** `docs-management` skill
> 2. **QUERY** using keywords: hooks, PreToolUse, PostToolUse, hook events, hook configuration, or related topics
> 3. **BASE** all responses EXCLUSIVELY on official documentation loaded
>
> **Skipping this step results in outdated or incorrect information.**

### Verification Checkpoint

Before responding, verify:

- [ ] Did I invoke docs-management skill?
- [ ] Did official documentation load?
- [ ] Is my response based EXCLUSIVELY on official docs?

If ANY checkbox is unchecked, STOP and invoke docs-management first.

## Overview

Central authority for managing Claude Code hooks in this repository. Automates enforcement of critical repository rules that were previously manual in CLAUDE.md.

**Architecture:** Vertical slice organization with externalized configuration, multi-language support, immediate config reload, and comprehensive testing.

## When to Use This Skill

**Keywords:** hooks, hook management, automation, validation, enforcement, PreToolUse, PostToolUse, SessionStart, SessionEnd, Setup hook, hook configuration, plugin hooks, local hooks, CLAUDE_HOOK_ENABLED, hook environment variables, enable hook, disable hook, --init, --init-only, --maintenance

**Use this skill when:**

- Adding new hooks to the repository
- Modifying existing hook behavior
- Troubleshooting hook issues
- Disabling/enabling hooks
- Understanding what hooks are active
- Configuring hook enforcement levels

## 🚨 CRITICAL: Official Hooks Documentation

**For ALL Claude Code hooks capabilities, configuration patterns, and syntax, you MUST use the docs-management skill.**

### What to Delegate to docs-management

> ⚠️ **STALENESS WARNING:** Do NOT hardcode hook event names, decision values, or environment variables.
> ALWAYS query docs-management for the authoritative list of hook capabilities.

**Query Patterns for Official Hook Documentation:**

| Topic | Query Pattern | What You'll Find |
| --- | --- | --- |
| Hook event types | "hooks.md hook events", "hook event types" | Complete list of available events |
| Hook configuration | "hooks.md configuration syntax" | JSON structure and required fields |
| Matchers | "hooks.md matchers tool names" | Tool matching patterns |
| Decision control | "hooks.md decision control", "hook return values" | Valid decision values and behavior |
| Exit codes | "hooks.md exit codes" | Exit code meanings |
| JSON output | "hooks.md JSON output schema" | Output schema for hook responses |
| Environment variables | "hooks.md environment variables" | Available env vars in hooks |
| Command vs prompt hooks | "hooks.md command prompt based" | Hook type differences |
| Plugin hooks | "hooks.md plugin hooks integration" | Plugin-specific patterns |

**Example queries:**

```text
docs-management: "hooks.md hook event types"
docs-management: "hooks.md decision control values"
docs-management: "hooks.md environment variables available"
```

**Frontmatter Hooks (v2.1.x):**

- Keywords: `frontmatter hooks`, `skill hooks`, `agent hooks`, `command hooks`, `once true`
- Use case: Defining hooks in skill/agent/command YAML frontmatter (not just .claude/hooks/)

**SessionStart Hook Input (v2.1.2+):**

- Keywords: `SessionStart`, `agent_type`, `--agent flag`
- Use case: SessionStart hooks receive `agent_type` field when invoked with `--agent` CLI flag
- Note: This field is documented in CHANGELOG v2.1.2 but may not yet be in official hooks.md - query docs-management for current state

**PreToolUse additionalContext Return (v2.1.9+):**

- Keywords: `PreToolUse`, `additionalContext`, `hook return`, `context injection`
- Use case: PreToolUse hooks can return an `additionalContext` field to provide additional context to the model
- Query pattern: `docs-management: "hooks.md PreToolUse additionalContext return"`

**Setup Hook Event (v2.1.10+):**

- Keywords: `Setup hook`, `Setup event`, `--init`, `--init-only`, `--maintenance`, `repository setup`
- Use case: Setup hooks run during repository initialization/maintenance via CLI flags
- Triggers: `--init`, `--init-only`, or `--maintenance` CLI flags
- Query pattern: `docs-management: "hooks.md Setup hook event"`

### What This Skill Provides

**Organization-specific implementation:**

- Directory structure and conventions
- Configuration management patterns
- Shared utilities (json, path, git, config helpers)
- Active hooks inventory
- Multi-language implementation strategy
- Troubleshooting for this repository's hooks

## Quick Decision Tree

**What do you want to do?**

1. **Understand design principles** → See [Design Principles](references/architecture/design-principles.md)
2. **View active hooks** → See [Active Hooks](references/inventory/active-hooks.md)
3. **Manage hook lifecycle** (enable/disable/modify) → See [Hook Lifecycle](references/inventory/hook-lifecycle.md)
4. **Configure hooks** → See [Configuration Guide](references/configuration/hook-config-guide.md)
5. **Create new hook** → See [Creating Hooks Workflow](references/development/creating-hooks-workflow.md)
6. **Test hooks** → See [Testing Guide](references/development/testing-guide.md)
7. **Follow best practices** → See [Best Practices](references/development/best-practices.md)
8. **Troubleshoot issues** → See [Common Issues](references/troubleshooting/common-issues.md)
9. **Debug hooks** → See [Debugging Guide](references/troubleshooting/debugging-guide.md)
10. **Official hooks documentation** → Use docs-management skill with keywords above
11. **Create/configure plugin hooks** → Use `plugin-development` skill (see below)

### Plugin Hooks Delegation

**If you're working with plugin hooks** (hooks bundled in a Claude Code plugin), use the `plugin-development` skill instead. Plugin hooks use a different configuration pattern:

| Aspect | Local Hooks (this skill) | Plugin Hooks |
| --- | --- | --- |
| Location | `.claude/hooks/` directory | Plugin `hooks/hooks.json` |
| Configuration | YAML files (`config.yaml`) | Environment variables |
| Consumer Control | Edit config files directly | Via `settings.json` `env` section |

**For plugin hooks:** Invoke `plugin-development` skill and see the Plugin Hook Configuration section.

## Reference Loading Guide

**All references in this skill are conditional load** - they are loaded only when needed based on the workflow you're following.

### When to Load Each Reference

**Architecture References** (load when understanding design):

- `references/architecture/design-principles.md` → When understanding vertical slice, DRY, config-over-hardcoding principles
- `references/architecture/multi-language-strategy.md` → When implementing or migrating to Python/TypeScript

**Inventory References** (load when working with hooks):

- `references/inventory/active-hooks.md` → When reviewing what hooks are active and their configurations
- `references/inventory/hook-lifecycle.md` → When enabling/disabling hooks or changing enforcement modes

**Configuration References** (load when configuring):

- `references/configuration/hook-config-guide.md` → When modifying global.yaml or config.yaml files

**Development References** (load when creating/testing):

- `references/development/creating-hooks-workflow.md` → When creating a new hook from scratch
- `references/development/testing-guide.md` → When writing tests for hooks
- `references/development/best-practices.md` → When ensuring code quality and following patterns

**Troubleshooting References** (load when debugging):

- `references/troubleshooting/common-issues.md` → When encountering problems (hook not running, config not applying, etc.)
- `references/troubleshooting/debugging-guide.md` → When performing advanced debugging or profiling

### Progressive Disclosure Strategy

#### Layer 1: Always in Context

- SKILL.md (this file) - Navigation hub and decision trees

#### Layer 2: Load on Dema