feat: wire after_specify and after_plan hook events into command templates#1825
Open
davidniu-0914 wants to merge 2 commits intogithub:mainfrom
Open
feat: wire after_specify and after_plan hook events into command templates#1825davidniu-0914 wants to merge 2 commits intogithub:mainfrom
after_specify and after_plan hook events into command templates#1825davidniu-0914 wants to merge 2 commits intogithub:mainfrom
Conversation
…lan (github#1788) - Update EXTENSION-API-REFERENCE.md to reflect current hook implementation status. - Add before_tasks and before_implement hooks to EXTENSION-DEVELOPMENT-GUIDE.md. - Standardize CRITICAL execution instructions for mandatory hooks across all templates (specify, plan, tasks, implement). - Sync documentation versions and pyproject.toml to 0.2.1 to match upstream. - Update Last Updated dates in extension guides.
mnriem
approved these changes
Mar 13, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Spec Kit command templates and extension documentation so that the lifecycle hook events for before_specify/after_specify and before_plan/after_plan are represented consistently alongside existing hook points, and bumps the project/docs version to 0.2.1.
Changes:
- Add pre- and post- hook instructions for
specifyandplancommand templates (before_*andafter_*events). - Strengthen “mandatory hook” execution instructions across core templates (add explicit CRITICAL “execute immediately” language).
- Bump version to
0.2.1and update extension guides + changelog accordingly.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| templates/commands/specify.md | Adds before_specify and after_specify hook instructions + CRITICAL execution requirements. |
| templates/commands/plan.md | Adds before_plan and after_plan hook instructions + CRITICAL execution requirements. |
| templates/commands/tasks.md | Adds CRITICAL execution requirement wording for mandatory hooks. |
| templates/commands/implement.md | Adds CRITICAL execution requirement wording for mandatory hooks. |
| src/specify_cli/extensions.py | Updates docstrings/examples for hook event names to include specify/plan events. |
| pyproject.toml | Bumps package version to 0.2.1. |
| extensions/EXTENSION-USER-GUIDE.md | Updates stated minimum/version references and last-updated metadata. |
| extensions/EXTENSION-DEVELOPMENT-GUIDE.md | Expands documented hook points to include specify/plan + before_implement, updates examples. |
| extensions/EXTENSION-API-REFERENCE.md | Documents additional standard hook events and adds CRITICAL mandatory-hook instruction. |
| CHANGELOG.md | Adds an Unreleased entry for the new hook wiring. |
Comments suppressed due to low confidence (2)
templates/commands/plan.md:87
- The post-plan hook filtering here will drop hooks that omit
enabled(which are enabled by default inHookExecutor) and will skip all hooks that setcondition, even though the codebase supports condition evaluation. This makes conditional hooks impossible to trigger from the template-driven workflow.
- Filter to only hooks where `enabled: true`
- 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:
templates/commands/specify.md:33
- Hook filtering in the template doesn’t match the actual hook config behavior in
HookExecutor: hooks default to enabled when theenabledfield is missing (h.get('enabled', True)), so instructing the agent to keep onlyenabled: truewould incorrectly drop hooks without an explicitenabledkey. Also, skipping hooks with a non-emptyconditionmeans conditional hooks will never run from the template flow even though the codebase supports condition evaluation; consider treating conditions as evaluatable (same rules asHookExecutor.should_execute_hook) or at least not skipping them outright.
- Filter to only hooks where `enabled: true`
- 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
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+218
to
+223
| - Filter to only hooks where `enabled: true` | ||
| - 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`): |
Comment on lines
+33
to
+38
| - Filter to only hooks where `enabled: true` | ||
| - 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`): |
mnriem
requested changes
Mar 13, 2026
Collaborator
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback. If not applicable, please explain why
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR aligns the extension hooks documentation and command templates for the specify and plan commands, resolving Issue #1788. It ensures that all core command templates (specify.md, plan.md, tasks.md,
implement.md) contain consistent CRITICAL execution instructions for mandatory hooks, preventing AI agents from proceeding before hook execution. Additionally, it synchronizes the project version to 0.2.1 across
pyproject.toml and all extension guides to match the upstream repository.
Testing
AI Disclosure
This PR was prepared with the assistance of Gemini CLI to synchronize version numbers across multiple files, standardize hook instructions in markdown templates for behavioral consistency, and ensure
documentation accuracy relative to the implemented features.