💫 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.mdindex bd25d4bb4..6be3d0633 100644--- a/extensions/EXTENSION-API-REFERENCE.md+++ b/extensions/EXTENSION-API-REFERENCE.md@@ -53,7 +53,7 @@ provides:required: boolean # Default: falsehooks: # 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 executeoptional: boolean # Default: trueprompt: 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 Configurationdiff --git a/extensions/EXTENSION-USER-GUIDE.md b/extensions/EXTENSION-USER-GUIDE.mdindex 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_commithooks:after_tasks:- extension: jiradiff --git a/templates/commands/implement.md b/templates/commands/implement.mdindex 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 task10. **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 implementationdiff --git a/templates/commands/plan.md b/templates/commands/plan.mdindex 00e83eabd..4f1e9ed29 100644--- a/templates/commands/plan.md+++ b/templates/commands/plan.md@@ -24,6 +24,40 @@ $ARGUMENTSYou **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+## Outline1. **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 & Researchdiff --git a/templates/commands/specify.md b/templates/commands/specify.mdindex 0713b68e4..eeca4b58c 100644--- a/templates/commands/specify.md+++ b/templates/commands/specify.md@@ -21,6 +21,40 @@ $ARGUMENTSYou **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+## OutlineThe 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 Guidelinesdiff --git a/templates/commands/tasks.md b/templates/commands/tasks.mdindex 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