Skip to content

Commit 7a7843b

Browse files
authored
fix: promote post-execution hook dispatch to H2 with directive language (github#2713)
* fix: promote post-execution hook dispatch to H2 with directive language Restructure the after_* hook dispatch in all five core command templates (specify, clarify, implement, plan, tasks) to make hook execution structurally unmissable by LLMs during interactive slash-command flows. Changes applied consistently across all five templates: 1. Promote hook block from a final numbered step to a top-level '## Mandatory Post-Execution Hooks' H2, placed before the completion report. An H2 boundary is salient in a way that a numbered sub-step buried after 'Report completion' is not. 2. Use directive language for mandatory hooks: 'You MUST emit EXECUTE_COMMAND: for each mandatory hook' and 'You MUST complete this section before reporting completion to the user.' The previous conditional framing ('check if', 'based on its optional flag') buried the mandatory cases. 3. List mandatory hooks before optional hooks in the dispatch block, so the required action appears first. 4. Add a terminal '## Done When' verification checklist at the end of each template, including 'Extension hooks dispatched' as an explicit completion criterion. This gives the model a structured opportunity to verify completion before exiting. 5. Extract the completion report into its own '## Completion Report' H2 section, clearly separated from the hook dispatch. These changes preserve the interactive-vs-workflow distinction and do not introduce auto-run. They raise the reliability of the existing best-effort dispatch mechanism. Fixes github#2688 * fix: address review — narrow Done When wording and move to end of templates - Narrow the hooks checklist item from a broad condition to 'dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above' so it does not contradict the filtering rules for disabled hooks or hooks with non-empty conditions. - Move the Done When section to the actual end of specify.md, plan.md, and tasks.md so it does not signal premature completion before the agent reads required guidance sections (Quick Guidelines, Phases/Key rules, Task Generation Rules). * fix: update stale step 8 reference in specify.md validation flow The old 'proceed to step 8' pointed to the completion report step that was renumbered when hook dispatch was promoted to its own H2 section. Update the reference to point to 'Mandatory Post-Execution Hooks'.
1 parent 7e9d470 commit 7a7843b

5 files changed

Lines changed: 209 additions & 150 deletions

File tree

‎templates/commands/clarify.md‎

Lines changed: 29 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -197,14 +197,6 @@ Execution steps:
197197
198198
7. Write the updated spec back to `FEATURE_SPEC`.
199199
200-
8. Report completion (after questioning loop ends or early termination):
201-
- Number of questions asked & answered.
202-
- Path to updated spec.
203-
- Sections touched (list names).
204-
- Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
205-
- If any Outstanding or Deferred remain, recommend whether to proceed to `__SPECKIT_COMMAND_PLAN__` or run `__SPECKIT_COMMAND_CLARIFY__` again later post-plan.
206-
- Suggested next command.
207-
208200
Behavior rules:
209201
210202
- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
@@ -217,17 +209,27 @@ Behavior rules:
217209
218210
Context for prioritization: {ARGS}
219211
220-
## Post-Execution Checks
212+
## Mandatory Post-Execution Hooks
213+
214+
**You MUST complete this section before reporting completion to the user.**
221215
222-
**Check for extension hooks (after clarification)**:
223216
Check if `.specify/extensions.yml` exists in the project root.
224-
- If it exists, read it and look for entries under the `hooks.after_clarify` key
225-
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
217+
- If it does not exist, or no hooks are registered under `hooks.after_clarify`, skip to the Completion Report.
218+
- If it exists, read it and look for entries under the `hooks.after_clarify` key.
219+
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue to the Completion Report.
226220
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
227221
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
228222
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
229223
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
230224
- For each executable hook, output the following based on its `optional` flag:
225+
- **Mandatory hook** (`optional: false`) — **You MUST emit `EXECUTE_COMMAND:` for each mandatory hook**:
226+
```
227+
## Extension Hooks
228+
229+
**Automatic Hook**: {extension}
230+
Executing: `/{command}`
231+
EXECUTE_COMMAND: {command}
232+
```
231233
- **Optional hook** (`optional: true`):
232234
```
233235
## Extension Hooks
@@ -239,12 +241,19 @@ Check if `.specify/extensions.yml` exists in the project root.
239241
Prompt: {prompt}
240242
To execute: `/{command}`
241243
```
242-
- **Mandatory hook** (`optional: false`):
243-
```
244-
## Extension Hooks
245244
246-
**Automatic Hook**: {extension}
247-
Executing: `/{command}`
248-
EXECUTE_COMMAND: {command}
249-
```
250-
- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
245+
## Completion Report
246+
247+
Report completion (after questioning loop ends or early termination):
248+
- Number of questions asked & answered.
249+
- Path to updated spec.
250+
- Sections touched (list names).
251+
- Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
252+
- If any Outstanding or Deferred remain, recommend whether to proceed to `__SPECKIT_COMMAND_PLAN__` or run `__SPECKIT_COMMAND_CLARIFY__` again later post-plan.
253+
- Suggested next command.
254+
255+
## Done When
256+
257+
- [ ] Spec ambiguities identified and clarifications integrated into spec file
258+
- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
259+
- [ ] Completion reported to user with questions answered, sections touched, and coverage summary

‎templates/commands/implement.md‎

Lines changed: 43 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -168,35 +168,49 @@ You **MUST** consider the user input before proceeding (if not empty).
168168
- Check that implemented features match the original specification
169169
- Validate that tests pass and coverage meets requirements
170170
- Confirm the implementation follows the technical plan
171-
- Report final status with summary of completed work
172171
173172
Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `__SPECKIT_COMMAND_TASKS__` first to regenerate the task list.
174173
175-
10. **Check for extension hooks**: After completion validation, check if `.specify/extensions.yml` exists in the project root.
176-
- If it exists, read it and look for entries under the `hooks.after_implement` key
177-
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
178-
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
179-
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
180-
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
181-
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
182-
- For each executable hook, output the following based on its `optional` flag:
183-
- **Optional hook** (`optional: true`):
184-
```
185-
## Extension Hooks
186-
187-
**Optional Hook**: {extension}
188-
Command: `/{command}`
189-
Description: {description}
190-
191-
Prompt: {prompt}
192-
To execute: `/{command}`
193-
```
194-
- **Mandatory hook** (`optional: false`):
195-
```
196-
## Extension Hooks
197-
198-
**Automatic Hook**: {extension}
199-
Executing: `/{command}`
200-
EXECUTE_COMMAND: {command}
201-
```
202-
- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
174+
## Mandatory Post-Execution Hooks
175+
176+
**You MUST complete this section before reporting completion to the user.**
177+
178+
Check if `.specify/extensions.yml` exists in the project root.
179+
- If it does not exist, or no hooks are registered under `hooks.after_implement`, skip to the Completion Report.
180+
- If it exists, read it and look for entries under the `hooks.after_implement` key.
181+
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue to the Completion Report.
182+
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
183+
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
184+
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
185+
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
186+
- For each executable hook, output the following based on its `optional` flag:
187+
- **Mandatory hook** (`optional: false`) — **You MUST emit `EXECUTE_COMMAND:` for each mandatory hook**:
188+
```
189+
## Extension Hooks
190+
191+
**Automatic Hook**: {extension}
192+
Executing: `/{command}`
193+
EXECUTE_COMMAND: {command}
194+
```
195+
- **Optional hook** (`optional: true`):
196+
```
197+
## Extension Hooks
198+
199+
**Optional Hook**: {extension}
200+
Command: `/{command}`
201+
Description: {description}
202+
203+
Prompt: {prompt}
204+
To execute: `/{command}`
205+
```
206+
207+
## Completion Report
208+
209+
Report final status with summary of completed work.
210+
211+
## Done When
212+
213+
- [ ] All tasks in tasks.md completed and marked `[X]`
214+
- [ ] Implementation validated against specification, plan, and test coverage
215+
- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
216+
- [ ] Completion reported to user with summary of completed work

‎templates/commands/plan.md‎

Lines changed: 42 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -70,36 +70,42 @@ You **MUST** consider the user input before proceeding (if not empty).
7070
- Phase 1: Update agent context by running the agent script
7171
- Re-evaluate Constitution Check post-design
7272
73-
4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
74-
75-
5. **Check for extension hooks**: After reporting, check if `.specify/extensions.yml` exists in the project root.
76-
- If it exists, read it and look for entries under the `hooks.after_plan` key
77-
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
78-
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
79-
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
80-
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
81-
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
82-
- For each executable hook, output the following based on its `optional` flag:
83-
- **Optional hook** (`optional: true`):
84-
```
85-
## Extension Hooks
86-
87-
**Optional Hook**: {extension}
88-
Command: `/{command}`
89-
Description: {description}
90-
91-
Prompt: {prompt}
92-
To execute: `/{command}`
93-
```
94-
- **Mandatory hook** (`optional: false`):
95-
```
96-
## Extension Hooks
97-
98-
**Automatic Hook**: {extension}
99-
Executing: `/{command}`
100-
EXECUTE_COMMAND: {command}
101-
```
102-
- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
73+
## Mandatory Post-Execution Hooks
74+
75+
**You MUST complete this section before reporting completion to the user.**
76+
77+
Check if `.specify/extensions.yml` exists in the project root.
78+
- If it does not exist, or no hooks are registered under `hooks.after_plan`, skip to the Completion Report.
79+
- If it exists, read it and look for entries under the `hooks.after_plan` key.
80+
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue to the Completion Report.
81+
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
82+
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
83+
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
84+
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
85+
- For each executable hook, output the following based on its `optional` flag:
86+
- **Mandatory hook** (`optional: false`) — **You MUST emit `EXECUTE_COMMAND:` for each mandatory hook**:
87+
```
88+
## Extension Hooks
89+
90+
**Automatic Hook**: {extension}
91+
Executing: `/{command}`
92+
EXECUTE_COMMAND: {command}
93+
```
94+
- **Optional hook** (`optional: true`):
95+
```
96+
## Extension Hooks
97+
98+
**Optional Hook**: {extension}
99+
Command: `/{command}`
100+
Description: {description}
101+
102+
Prompt: {prompt}
103+
To execute: `/{command}`
104+
```
105+
106+
## Completion Report
107+
108+
Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
103109
104110
## Phases
105111
@@ -150,3 +156,9 @@ You **MUST** consider the user input before proceeding (if not empty).
150156

151157
- Use absolute paths for filesystem operations; use project-relative paths for references in documentation and agent context files
152158
- ERROR on gate failures or unresolved clarifications
159+
160+
## Done When
161+
162+
- [ ] Plan workflow executed and design artifacts generated
163+
- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
164+
- [ ] Completion reported to user with branch, plan path, and generated artifacts

‎templates/commands/specify.md‎

Lines changed: 47 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ Given that feature description, do this:
183183
184184
c. **Handle Validation Results**:
185185
186-
- **If all items pass**: Mark checklist complete and proceed to step 8
186+
- **If all items pass**: Mark checklist complete and proceed to the Mandatory Post-Execution Hooks section
187187
188188
- **If items fail (excluding [NEEDS CLARIFICATION])**:
189189
1. List the failing items and specific issues
@@ -228,40 +228,46 @@ Given that feature description, do this:
228228
229229
d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
230230
231-
8. **Report completion** to the user with:
232-
- `SPECIFY_FEATURE_DIRECTORY` — the feature directory path
233-
- `SPEC_FILE` — the spec file path
234-
- Checklist results summary
235-
- Readiness for the next phase (`__SPECKIT_COMMAND_CLARIFY__` or `__SPECKIT_COMMAND_PLAN__`)
236-
237-
9. **Check for extension hooks**: After reporting completion, check if `.specify/extensions.yml` exists in the project root.
238-
- If it exists, read it and look for entries under the `hooks.after_specify` key
239-
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
240-
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
241-
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
242-
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
243-
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
244-
- For each executable hook, output the following based on its `optional` flag:
245-
- **Optional hook** (`optional: true`):
246-
```
247-
## Extension Hooks
248-
249-
**Optional Hook**: {extension}
250-
Command: `/{command}`
251-
Description: {description}
252-
253-
Prompt: {prompt}
254-
To execute: `/{command}`
255-
```
256-
- **Mandatory hook** (`optional: false`):
257-
```
258-
## Extension Hooks
259-
260-
**Automatic Hook**: {extension}
261-
Executing: `/{command}`
262-
EXECUTE_COMMAND: {command}
263-
```
264-
- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
231+
## Mandatory Post-Execution Hooks
232+
233+
**You MUST complete this section before reporting completion to the user.**
234+
235+
Check if `.specify/extensions.yml` exists in the project root.
236+
- If it does not exist, or no hooks are registered under `hooks.after_specify`, skip to the Completion Report.
237+
- If it exists, read it and look for entries under the `hooks.after_specify` key.
238+
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue to the Completion Report.
239+
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
240+
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
241+
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
242+
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
243+
- For each executable hook, output the following based on its `optional` flag:
244+
- **Mandatory hook** (`optional: false`) — **You MUST emit `EXECUTE_COMMAND:` for each mandatory hook**:
245+
```
246+
## Extension Hooks
247+
248+
**Automatic Hook**: {extension}
249+
Executing: `/{command}`
250+
EXECUTE_COMMAND: {command}
251+
```
252+
- **Optional hook** (`optional: true`):
253+
```
254+
## Extension Hooks
255+
256+
**Optional Hook**: {extension}
257+
Command: `/{command}`
258+
Description: {description}
259+
260+
Prompt: {prompt}
261+
To execute: `/{command}`
262+
```
263+
264+
## Completion Report
265+
266+
Report completion to the user with:
267+
- `SPECIFY_FEATURE_DIRECTORY` — the feature directory path
268+
- `SPEC_FILE` — the spec file path
269+
- Checklist results summary
270+
- Readiness for the next phase (`__SPECKIT_COMMAND_CLARIFY__` or `__SPECKIT_COMMAND_PLAN__`)
265271
266272
**NOTE:** Branch creation is handled by the `before_specify` hook (git extension). Spec directory and file creation are always handled by this core command.
267273
@@ -325,3 +331,9 @@ Success criteria must be:
325331
- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
326332
- "React components render efficiently" (framework-specific)
327333
- "Redis cache hit rate above 80%" (technology-specific)
334+
335+
## Done When
336+
337+
- [ ] Specification written to `SPEC_FILE` and validated against quality checklist
338+
- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
339+
- [ ] Completion reported to user with feature directory, spec file path, and checklist results

0 commit comments

Comments
 (0)