From 333a76535b01aca13fa5f6d958f04e08e875e6c4 Mon Sep 17 00:00:00 2001 From: Matt Van Horn Date: Thu, 19 Mar 2026 04:37:03 -0700 Subject: [PATCH] feat(commands): wire before/after hook events into specify and plan templates (#1886) * feat(commands): wire before/after hook events into specify and plan templates Replicates the hook evaluation pattern from tasks.md and implement.md (introduced in PR #1702) into the specify and plan command templates. This completes the hook lifecycle across all SDD phases. Changes: - specify.md: Add before_specify/after_specify hook blocks - plan.md: Add before_plan/after_plan hook blocks - EXTENSION-API-REFERENCE.md: Document new hook events - EXTENSION-USER-GUIDE.md: List all available hook events Fixes #1788 Co-Authored-By: Claude Opus 4.6 * Mark before_commit/after_commit as planned in extension docs These hook events are defined in the API reference but not yet wired into any core command template. Marking them as planned rather than removing them, since the infrastructure supports them. Co-Authored-By: Claude Opus 4.6 (1M context) * Fix hook enablement to default true when field is absent Matches HookExecutor.get_hooks_for_event() semantics where hooks without an explicit enabled field are treated as enabled. Co-Authored-By: Claude Opus 4.6 (1M context) * fix(docs): mark commit hooks as planned in user guide config example The yaml config comment listed before_commit/after_commit as "Available events" but they are not yet wired into core templates. Moved them to a separate "Planned" line, consistent with the API reference. Co-Authored-By: Claude Opus 4.6 * fix(commands): align enabled-filtering semantics across all hook templates tasks.md and implement.md previously said "Filter to only hooks where enabled: true", which would skip hooks that omit the enabled field. Updated to match specify.md/plan.md and HookExecutor's h.get('enabled', True) behavior: filter out only hooks where enabled is explicitly false. Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 --- extensions/EXTENSION-API-REFERENCE.md | 14 ++++-- extensions/EXTENSION-USER-GUIDE.md | 3 ++ templates/commands/implement.md | 4 +- templates/commands/plan.md | 63 +++++++++++++++++++++++++++ templates/commands/specify.md | 63 +++++++++++++++++++++++++++ templates/commands/tasks.md | 4 +- 6 files changed, 143 insertions(+), 8 deletions(-) diff --git a/extensions/EXTENSION-API-REFERENCE.md b/extensions/EXTENSION-API-REFERENCE.md index bd25d4bb..6be3d063 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 ae77860f..21313c0a 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 da58027d..9a91d2dc 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 00e83eab..4f1e9ed2 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 0713b68e..eeca4b58 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 9ad19963..4e204abc 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