Skip to content

docs(framework): hooks documentation, tool-internal vs pre-commit #303

Closed

Description

@blafourcade

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.md with 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.md without 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.md links to the authoritative section.
  • The glossary no longer classifies pre-commit as an agent lifecycle event.

Prior art in this repo

  • ARCHITECTURE.md already 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.

Activity

  1. blafourcade commented on Jul 10, 2026

    @blafourcade
    ContributorAuthor

    Partially covered on next: docs/ARCHITECTURE.md has a 🪝 Bundled hooks table (plugin, event, script, purpose) since #407.

    Remaining scope for this issue:

    • Document the hook lifecycle events themselves, not just the two hooks that exist.
    • Document how a plugin author opts in (plugins/<plugin>/hooks/hooks.json).
    • The explicit contrast with pre-commit hooks, and why tool-internal hooks are preferred (enterprises often refuse pre-commit).
  2. changed the title [-]docs: hooks documentation (and study tool-internal hooks vs pre-commit)[/-] [+]docs(framework): hooks documentation, tool-internal vs pre-commit[/+] on Jul 10, 2026
  3. added theissue type on Jul 10, 2026
  4. blafourcade commented on Oct 29, 2026

    @blafourcade
    ContributorAuthor

    Covered by the documentation rewrite merged in #1131.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Fields

    Priority

    Medium

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions