Skip to content

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

feat(commands): wire before/after hook events into specify and plan templates (#1886)

Matt Van Horn333a76535b01
diff --git a/extensions/EXTENSION-API-REFERENCE.md b/extensions/EXTENSION-API-REFERENCE.md
index bd25d4bb4..6be3d0633 100644
--- a/extensions/EXTENSION-API-REFERENCE.md
+++ b/extensions/EXTENSION-API-REFERENCE.md
@@ -53,7 +53,7 @@ provides:
required: boolean # Default: false
hooks: # Optional, event hooks
- event_name: # e.g., "after_tasks", "after_implement"
+ event_name: # e.g., "after_specify", "after_plan", "after_tasks", "after_implement"
command: string # Command to execute
optional: boolean # Default: true
prompt: string # Prompt text for optional hooks
@@ -108,7 +108,7 @@ defaults: # Optional, default configuration values
#### `hooks`
- **Type**: object
-- **Keys**: Event names (e.g., `after_tasks`, `after_implement`, `before_commit`)
+- **Keys**: Event names (e.g., `after_specify`, `after_plan`, `after_tasks`, `after_implement`, `before_commit`)
- **Description**: Hooks that execute at lifecycle events
- **Events**: Defined by core spec-kit commands
@@ -551,10 +551,16 @@ hooks:
Standard events (defined by core):
+- `before_specify` - Before specification generation
+- `after_specify` - After specification generation
+- `before_plan` - Before implementation planning
+- `after_plan` - After implementation planning
+- `before_tasks` - Before task generation
- `after_tasks` - After task generation
+- `before_implement` - Before implementation
- `after_implement` - After implementation
-- `before_commit` - Before git commit
-- `after_commit` - After git commit
+- `before_commit` - Before git commit *(planned - not yet wired into core templates)*
+- `after_commit` - After git commit *(planned - not yet wired into core templates)*
### Hook Configuration
diff --git a/extensions/EXTENSION-USER-GUIDE.md b/extensions/EXTENSION-USER-GUIDE.md
index ae77860fe..21313c0ac 100644
--- a/extensions/EXTENSION-USER-GUIDE.md
+++ b/extensions/EXTENSION-USER-GUIDE.md
@@ -387,6 +387,9 @@ settings:
auto_execute_hooks: true
# Hook configuration
+# Available events: before_specify, after_specify, before_plan, after_plan,
+# before_tasks, after_tasks, before_implement, after_implement
+# Planned (not yet wired into core templates): before_commit, after_commit
hooks:
after_tasks:
- extension: jira
diff --git a/templates/commands/implement.md b/templates/commands/implement.md
index da58027d0..9a91d2dc4 100644
--- a/templates/commands/implement.md
+++ b/templates/commands/implement.md
@@ -19,7 +19,7 @@ You **MUST** consider the user input before proceeding (if not empty).
- Check if `.specify/extensions.yml` exists in the project root.
- If it exists, read it and look for entries under the `hooks.before_implement` key
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-- Filter to only hooks where `enabled: true`
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
@@ -174,7 +174,7 @@ Note: This command assumes a complete task breakdown exists in tasks.md. If task
10. **Check for extension hooks**: After completion validation, check if `.specify/extensions.yml` exists in the project root.
- If it exists, read it and look for entries under the `hooks.after_implement` key
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
- - Filter to only hooks where `enabled: true`
+ - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
diff --git a/templates/commands/plan.md b/templates/commands/plan.md
index 00e83eabd..4f1e9ed29 100644
--- a/templates/commands/plan.md
+++ b/templates/commands/plan.md
@@ -24,6 +24,40 @@ $ARGUMENTS
You **MUST** consider the user input before proceeding (if not empty).
+## Pre-Execution Checks
+
+**Check for extension hooks (before planning)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_plan` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+ - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+ - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+ - **Optional hook** (`optional: true`):
+ ```
+ ## Extension Hooks
+
+ **Optional Pre-Hook**: {extension}
+ Command: `/{command}`
+ Description: {description}
+
+ Prompt: {prompt}
+ To execute: `/{command}`
+ ```
+ - **Mandatory hook** (`optional: false`):
+ ```
+ ## Extension Hooks
+
+ **Automatic Pre-Hook**: {extension}
+ Executing: `/{command}`
+ EXECUTE_COMMAND: {command}
+
+ Wait for the result of the hook command before proceeding to the Outline.
+ ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
## Outline
1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
@@ -41,6 +75,35 @@ You **MUST** consider the user input before proceeding (if not empty).
4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
+5. **Check for extension hooks**: After reporting, check if `.specify/extensions.yml` exists in the project root.
+ - If it exists, read it and look for entries under the `hooks.after_plan` key
+ - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+ - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+ - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+ - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+ - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+ - For each executable hook, output the following based on its `optional` flag:
+ - **Optional hook** (`optional: true`):
+ ```
+ ## Extension Hooks
+
+ **Optional Hook**: {extension}
+ Command: `/{command}`
+ Description: {description}
+
+ Prompt: {prompt}
+ To execute: `/{command}`
+ ```
+ - **Mandatory hook** (`optional: false`):
+ ```
+ ## Extension Hooks
+
+ **Automatic Hook**: {extension}
+ Executing: `/{command}`
+ EXECUTE_COMMAND: {command}
+ ```
+ - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
## Phases
### Phase 0: Outline & Research
diff --git a/templates/commands/specify.md b/templates/commands/specify.md
index 0713b68e4..eeca4b58c 100644
--- a/templates/commands/specify.md
+++ b/templates/commands/specify.md
@@ -21,6 +21,40 @@ $ARGUMENTS
You **MUST** consider the user input before proceeding (if not empty).
+## Pre-Execution Checks
+
+**Check for extension hooks (before specification)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_specify` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+ - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+ - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- For each executable hook, output the following based on its `optional` flag:
+ - **Optional hook** (`optional: true`):
+ ```
+ ## Extension Hooks
+
+ **Optional Pre-Hook**: {extension}
+ Command: `/{command}`
+ Description: {description}
+
+ Prompt: {prompt}
+ To execute: `/{command}`
+ ```
+ - **Mandatory hook** (`optional: false`):
+ ```
+ ## Extension Hooks
+
+ **Automatic Pre-Hook**: {extension}
+ Executing: `/{command}`
+ EXECUTE_COMMAND: {command}
+
+ Wait for the result of the hook command before proceeding to the Outline.
+ ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
## Outline
The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{ARGS}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
@@ -176,6 +210,35 @@ Given that feature description, do this:
7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
+8. **Check for extension hooks**: After reporting completion, check if `.specify/extensions.yml` exists in the project root.
+ - If it exists, read it and look for entries under the `hooks.after_specify` key
+ - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+ - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+ - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+ - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+ - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+ - For each executable hook, output the following based on its `optional` flag:
+ - **Optional hook** (`optional: true`):
+ ```
+ ## Extension Hooks
+
+ **Optional Hook**: {extension}
+ Command: `/{command}`
+ Description: {description}
+
+ Prompt: {prompt}
+ To execute: `/{command}`
+ ```
+ - **Mandatory hook** (`optional: false`):
+ ```
+ ## Extension Hooks
+
+ **Automatic Hook**: {extension}
+ Executing: `/{command}`
+ EXECUTE_COMMAND: {command}
+ ```
+ - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
## Quick Guidelines
diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md
index 9ad199634..4e204abc1 100644
--- a/templates/commands/tasks.md
+++ b/templates/commands/tasks.md
@@ -28,7 +28,7 @@ You **MUST** consider the user input before proceeding (if not empty).
- Check if `.specify/extensions.yml` exists in the project root.
- If it exists, read it and look for entries under the `hooks.before_tasks` key
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
-- Filter to only hooks where `enabled: true`
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
@@ -100,7 +100,7 @@ You **MUST** consider the user input before proceeding (if not empty).
6. **Check for extension hooks**: After tasks.md is generated, check if `.specify/extensions.yml` exists in the project root.
- If it exists, read it and look for entries under the `hooks.after_tasks` key
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
- - Filter to only hooks where `enabled: true`
+ - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation