From 70aafeca5d6fe909c3006a59694177580d97bff9 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:22:16 -0500 Subject: [PATCH 1/2] docs: distinguish extension events from hooks Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: bbf74d70-31fd-4ffd-96aa-dd4459cddbfb --- README.md | 3 ++- docs/reference/extensions.md | 24 ++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e06db3ec49..57df72ae72 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 676428a079..7112c76659 100644 --- a/docs/reference/extensions.md +++ b/docs/reference/extensions.md @@ -294,6 +294,30 @@ cp .specify/extensions//-config.template.yml \ .specify/extensions//-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 + matcher: "write|edit" +``` + +Spec Kit translates these canonical event names into the active integration's +agent-native event configuration. Supported canonical events are +`session_start`, `pre_tool_use`, `post_tool_use`, `user_prompt_submit`, `stop`, +and `session_end`; the active coding-agent integration may support only a +subset. + +Runtime events are distinct from extension hooks. Events react to the coding +agent's lifecycle, while hooks 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: From 6a4a85380a32d7e0cf99ffe3e585c8e924afc945 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 19 Oct 2026 12:47:28 -0500 Subject: [PATCH 2/2] docs: clarify runtime event translation Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: bbf74d70-31fd-4ffd-96aa-dd4459cddbfb --- docs/reference/extensions.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/reference/extensions.md b/docs/reference/extensions.md index 7112c76659..4c93f94dbe 100644 --- a/docs/reference/extensions.md +++ b/docs/reference/extensions.md @@ -305,18 +305,21 @@ events: command: speckit.my-extension.initialize pre_tool_use: command: speckit.my-extension.validate - matcher: "write|edit" ``` -Spec Kit translates these canonical event names into the active integration's -agent-native event configuration. Supported canonical events are -`session_start`, `pre_tool_use`, `post_tool_use`, `user_prompt_submit`, `stop`, -and `session_end`; the active coding-agent integration may support only a -subset. +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, while hooks surface extension commands before or after Spec -Kit commands such as `plan`, `tasks`, and `implement`. +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