Closed
Description
Problem
The framework ships bundled hooks, but authors lack one documented, host-aware contract for adding a hook.
Scope
- Extend the existing bundled-hooks section in
docs/ARCHITECTURE.mdwith the minimal hook contract, supported lifecycle mapping, and the boundary with Git hooks. - Link that section from
docs/CREATE_PLUGIN.md. - Correct
docs/GLOSSARY.md: Git pre-commit is not an agent lifecycle event.
Acceptance criteria
- An author can add a basic hook from
ARCHITECTURE.mdwithout reading an existing implementation. - Supported lifecycle events and per-host coverage are explicit.
- The agent-hook versus Git-pre-commit boundary is explicit.
-
CREATE_PLUGIN.mdlinks to the authoritative section. - The glossary no longer classifies pre-commit as an agent lifecycle event.
Prior art in this repo
ARCHITECTURE.mdalready inventories Context and Telemetry hooks, but does not define an authoring contract.- Context and Telemetry have declarative hooks; OpenCode uses a JavaScript plugin bridge.
- Claude Code Hooks documents more events than AIDD currently normalizes.
Out of scope
- Changing or adding a bundled hook.
- Installing Git pre-commit hooks or adding CI enforcement.
- Claiming lifecycle parity that a host has not demonstrated.
Metadata
Metadata
Assignees
Labels
No labels
Type
Fields
Priority
Medium
Projects
- StatusShow more project fieldsDone
Activity
blafourcade commentedon Jul 10, 2026
Partially covered on
next:docs/ARCHITECTURE.mdhas a🪝 Bundled hookstable (plugin, event, script, purpose) since #407.Remaining scope for this issue:
plugins/<plugin>/hooks/hooks.json).[-]docs: hooks documentation (and study tool-internal hooks vs pre-commit)[/-][+]docs(framework): hooks documentation, tool-internal vs pre-commit[/+]blafourcade commentedon Oct 29, 2026
Covered by the documentation rewrite merged in #1131.