Skip to content

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

docs: document extensions.yml hook configuration (#3563)

Ehtasham Yasinb08d6658371d
diff --git a/docs/reference/extensions.md b/docs/reference/extensions.md
index 30f33eca0..783b17888 100644
--- a/docs/reference/extensions.md
+++ b/docs/reference/extensions.md
@@ -171,6 +171,63 @@ To set up configuration for a newly installed extension, copy the template:
cp .specify/extensions/<ext>/<ext>-config.template.yml \
.specify/extensions/<ext>/<ext>-config.yml
```
+## Project Extension and Hook Configuration
+
+Spec Kit stores project-level extension registration and hook configuration in:
+
+```text
+.specify/extensions.yml
+```
+The file contains installed extensions, global settings, and hooks that are surfaced before or after Spec Kit commands.
+
+```yaml
+installed:
+ - git
+ - my-extension
+
+settings:
+ auto_execute_hooks: true
+
+hooks:
+ before_implement:
+ - extension: git
+ command: speckit.git.commit
+ enabled: true
+ optional: true
+ priority: 10
+ prompt: "Commit outstanding changes before implementation?"
+ description: "Auto-commit before implementation"
+
+ after_implement:
+ - extension: my-extension
+ command: speckit.my-extension.verify
+ enabled: true
+ optional: false
+ priority: 5
+ description: "Run verification after implementation"
+```
+
+### Configuration fields
+
+The top-level `installed` list records extensions installed in the project. The `settings` mapping stores project-wide extension settings, and `hooks` groups hook registrations by event.
+
+`auto_execute_hooks` defaults to `true`, but is currently reserved and is not consulted when hooks are surfaced or invoked.
+
+Each hook entry supports the following fields:
+
+| Field | Description |
+| --- | --- |
+| `extension` | ID of the extension that registered the hook. |
+| `command` | Extension command associated with the hook. |
+| `enabled` | Whether the hook is active. Hooks with `enabled: false` are skipped. |
+| `optional` | Whether the hook is optional. If `true`, the hook is presented with its `prompt` and can be skipped; if `false`, the hook is emitted as an automatic hook (includes `EXECUTE_COMMAND` markers). |
+| `priority` | Priority metadata for the hook. Values must be integers >= 1; invalid values fall back to the default priority `10`. Current command templates surface hooks in their configured YAML order and do not sort them by `priority`. |
+| `prompt` | Message shown when asking whether to run an optional hook. |
+| `description` | Human-readable explanation of what the hook does. |
+| `condition` | Optional expression evaluated by `HookExecutor` (using `config.<path>` or `env.<VAR>` with `is set`, `==`, or `!=`). Current command templates do not evaluate conditions and skip hooks with a non-empty condition. |
+Hook event names identify when a hook is invoked. They generally use `before_<command>` or `after_<command>`, such as `before_implement`, `after_implement`, `before_tasks`, and `after_tasks`.
+
+`HookExecutor.get_hooks_for_event()` returns hooks ordered by `priority`, with lower values first. However, current command templates read hook lists directly and surface them in their configured YAML order rather than using priority ordering.
## FAQ