Skip to content

💫 Toolkit to help you get started with SDD or any other process!

docs: distinguish extension events from hooks (#5026)

Manfred Riemfe44f49b667b
diff --git a/README.md b/README.md
index 1bd6a2c10..68267b5b5 100644
--- a/README.md
+++ b/README.md
@@ -44,7 +44,8 @@ Spec Kit combines ready-to-use processes with composable mechanisms:
| Connect to or switch between coding agents | [Integration](https://github.github.io/spec-kit/reference/integrations.html) |
| Add a command, quality gate, or complete process | [Extension](https://github.github.io/spec-kit/reference/extensions.html) |
| Connect a process to an external tool or service | [Extension](https://github.github.io/spec-kit/reference/extensions.html) |
-| React to coding-agent lifecycle events | [Extension event hook](https://github.github.io/spec-kit/reference/extensions.html#project-extension-and-hook-configuration) |
+| React to coding-agent lifecycle events | [Extension runtime event](https://github.github.io/spec-kit/reference/extensions.html#extension-runtime-events) |
+| Run extension commands before or after Spec Kit commands | [Extension hook](https://github.github.io/spec-kit/reference/extensions.html#project-extension-and-hook-configuration) |
| Adapt templates, commands, terminology, or methodology | [Preset](https://github.github.io/spec-kit/reference/presets.html) |
| Enforce organizational or regulatory standards | [Preset](https://github.github.io/spec-kit/reference/presets.html) |
| Override a template for one project | [Project-local override](https://github.github.io/spec-kit/guides/customization.html#project-local-overrides-and-resolution) |
diff --git a/docs/reference/extensions.md b/docs/reference/extensions.md
index 676428a07..4c93f94db 100644
--- a/docs/reference/extensions.md
+++ b/docs/reference/extensions.md
@@ -294,6 +294,33 @@ cp .specify/extensions/<ext>/<ext>-config.template.yml \
.specify/extensions/<ext>/<ext>-config.yml
```
+## Extension Runtime Events
+
+Extensions can react to coding-agent lifecycle events by declaring a top-level
+`events` mapping in `extension.yml`:
+
+```yaml
+events:
+ session_start:
+ command: speckit.my-extension.initialize
+ pre_tool_use:
+ command: speckit.my-extension.validate
+```
+
+Event declarations are integration-agnostic. Spec Kit refreshes every installed
+event-capable integration, and each integration translates the canonical event
+names into its coding agent's native event configuration. Supported canonical
+events are `session_start`, `pre_tool_use`, `post_tool_use`,
+`user_prompt_submit`, `stop`, and `session_end`; each integration may support
+only a subset.
+
+Runtime events are distinct from extension hooks. Events react to the coding
+agent's lifecycle and execute the referenced command template's `scripts`
+entry directly. The referenced command must therefore provide a runnable
+script; its Markdown instructions are not sent to the coding agent. Hooks
+instead surface extension commands before or after Spec Kit commands such as
+`plan`, `tasks`, and `implement`.
+
## Project Extension and Hook Configuration
Spec Kit stores project-level extension registration and hook configuration in: