Decisions
- Pending: Which hook has the highest value to implement first?
- Pending: Should protect-files block or just warn?
- Pending: Should verify-tests be agent-based (can inspect code) or command-based (just runs test suite)?
User Tasks
FR-011: Hook Scripts
Summary
Implement hook scripts that automate checks and actions around Claude Code tool usage.
Problem / Motivation
Several repetitive safeguards and automations (file protection, format validation, session context) could be handled automatically via hooks instead of relying on manual discipline. CLAUDE.md defines rules like “show recent changes at session start” and “always test before presenting as done” — hooks can enforce these.
Proposed Solution
Implement hooks registered in .claude/settings.json that trigger on tool events.
Planned Hooks
PreToolUse:
- protect-files — Block edits to sensitive files (.env, secrets, CLAUDE.md, settings.json)
- validate-feature-format — Ensure feature request files follow the template
PostToolUse:
- auto-format — Run formatter after file edits
- sync-overview — Update feature-dashboard.md after feature file changes
SessionStart:
- session-recap (matcher:
startup|resume) — Auto-inject recent git commits + modified vault files into context - rehydrate-context (matcher:
compact) — After context compaction, re-inject key project state
UserPromptSubmit:
- inject-date — Inject the current date into context so Claude always knows today’s date
Stop:
- auto-changelog — Append session summary to daily changelog
- verify-tests (agent-based) — Check if tests pass before Claude presents code work as done
SessionEnd:
- suggest-next-step — Auto-write a next-step note to
vault/90_inbox/before session ends
Open Questions
- Which hook has the highest value to implement first?
- Should protect-files block or just warn?
- Should verify-tests be agent-based (can inspect code) or command-based (just runs test suite)?
Phase Overview
| Phase | Description | Status |
|---|---|---|
| Phase 1 | High-value quick wins (session-recap, inject-date, protect-files) | — |
| Phase 2 | Enforcement hooks (verify-tests, validate-feature-format) | — |
| Phase 3 | Automation hooks (sync-overview, auto-changelog, suggest-next-step) | — |
Phase 1: Quick Wins —
Goal: Implement the highest-value hooks that improve daily workflow immediately.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
| session-recap | Inject recent git log + vault changes at session start | opus | — |
| inject-date | Inject current date via UserPromptSubmit | opus | — |
| protect-files | Block edits to protected paths | opus | — |
| rehydrate-context | Re-inject state after compaction | opus | — |
Phase 2: Enforcement —
Goal: Add hooks that enforce project rules automatically.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
| verify-tests | Agent-based test check before presenting work as done | opus | — |
| validate-feature-format | Check FR files against template on edit | opus | — |
Phase 3: Automation —
Goal: Automate routine tasks that currently require manual effort.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
| sync-overview | Auto-update feature-dashboard after FR changes | opus | — |
| auto-changelog | Write changelog entry at session end | opus | — |
| suggest-next-step | Write next-step note at session end | opus | — |
| auto-format | Run formatter after file edits | opus | — |
| decision-log-reminder | At session end, check if significant decisions were made but not logged in decision-log.md. Prompt user to log them. | opus | — |
| design-doc-check | When FR moves to done, check if it contains complex architecture worth extracting to 00_system/designs/. Prompt user. | opus | — |
Acceptance Criteria:
- At least one hook is working and registered
- Hook README documents only existing (implemented) hooks
- Session-recap automates the manual “show recent changes” convention
Notes:
- Sound-alert is already handled by global user settings — not a project hook.
- Moved from
.claude/hooks/README.mdwhich previously contained plans inline. - See Claude Code docs for all hook types: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Notification, Stop, SessionEnd, PreCompact, and more.
Prerequisites / Gap Analysis
Requirements
| Requirement | Description |
|---|---|
| REQ-1 | .claude/settings.json must support hook registration |
| REQ-2 | Hook scripts must be executable bash/python |
Current State
| Component | Status | Details |
|---|---|---|
.claude/settings.json | done | Exists with hook support |
.claude/hooks/ directory | done | Exists, README present |
| Implemented hooks | — | None implemented yet |
Gap (What’s missing?)
| Gap | Effort | Blocker? |
|---|---|---|
| All hook scripts | Med | No |
Test
Manual tests
| Test | Expected | Owner | Actual | Last |
|---|---|---|---|---|
| session-recap fires on startup | Recent changes shown | mv | pending | - |
| inject-date injects correct date | Today’s date in context | mv | pending | - |
| protect-files blocks protected edit | Edit rejected with message | mv | pending | - |
AI-verified tests
| Scenario | Expected behavior | Verification method |
|---|---|---|
| … | … | … |
E2E tests
| Scenario | Assertion |
|---|---|
| … | … |
Integration tests
| Component | Coverage |
|---|---|
| … | … |
Unit tests
| Component | Tests | Coverage |
|---|---|---|
| … | … | … |
History
| Date | Event | Details |
|---|---|---|
| 2026-02-27 | Created | Extracted from hooks README |
| 2026-02-27 | Expanded | Added SessionStart, SessionEnd, UserPromptSubmit, verify-tests hooks; reorganized phases |
| 2026-02-27 | Renumbered | From FR-024 to FR-011 |
| 2026-02-28 | Reformatted | Aligned to feature-request template |
References
- FR-003 (Protected Files System) — protect-files hook
- FR-010 (Testing Infrastructure) — verify-tests hook
- FR-027 (Feature Overview Sync Check) — sync-overview hook