tamirs-superpowers / rules

---
description: "Constraints and patterns for editing hook scripts — use when modifying hooks/*.sh or hooks/hooks.json"
alwaysApply: false
globs: "hooks/**/*"
---

# Hooks guide

Hooks are shell scripts registered in `hooks/hooks.json` and run at lifecycle events with JSON on stdin. **Cursor does not load `hooks/hooks.json`** — Claude Code and Codex do. Editing a hook from Cursor is normal; relying on one firing in a Cursor session is not. Check `core/capabilities/platforms.json` before assuming hook support anywhere.

Script standards (non-blocking stdin, no `echo` in hooks, dependency detection): `rules/dev/user-facing-script-standards.md`.

## Critical rule

**Never modify `hooks/lib/worktree-common.sh`** without:

1. `shellcheck hooks/lib/worktree-common.sh`
2. Manually testing `capture-task-slug.sh` and `worktree-create.sh`

It is sourced by multiple hooks — a syntax error there silently breaks all worktree behavior.

## hooks.json format

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "bash hooks/my-hook.sh" }]
      }
    ]
  }
}
```

## Writing a hook

- Must pass `shellcheck` — `make lint` before committing
- Parse stdin JSON with `jq`; never block when stdin is empty or an idle TTY
- Never use `echo` — stray stdout corrupts hook response parsing. Use `printf` or the helpers in `hooks/lib/`
- Exit 0 = allow; non-zero = deny (PreToolUse)

The authoritative list of wired events is `hooks/hooks.json` itself — read it rather than a copy that drifts.

`scripts/github-mcp.sh` launches the GitHub MCP server via `.mcp.json`; it is **not** a lifecycle hook and does not belong in `hooks.json`.