Skip to content

Commit 4d0368b

Browse files
stefaniukstefaniuk
committed
feat(agents): add pre-execution checks for extension hooks in all agents
- Implemented pre-execution checks for extension hooks in speckit.clarify, speckit.implement, speckit.plan, speckit.specify, speckit.tasks agents. - Updated the outline sections to include checks for `.specify/extensions.yml` and handle optional/mandatory hooks. - Enhanced the prompt files to reflect changes in execution requirements from GitHub Copilot to AI Assistant. - Version bump to 1.6.1 in prompt files.
1 parent 0106942 commit 4d0368b

14 files changed

+912
-382
lines changed

‎.claude/commands/speckit.checklist.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,10 @@ You **MUST** consider the user input before proceeding (if not empty).
9191
- Generate unique checklist filename:
9292
- Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
9393
- Format: `[domain].md`
94-
- If file exists, append to existing file
95-
- Number items sequentially starting from CHK001
96-
- Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists)
94+
- File handling behavior:
95+
- If file does NOT exist: Create new file and number items starting from CHK001
96+
- If file exists: Append new items to existing file, continuing from the last CHK ID (e.g., if last item is CHK015, start new items at CHK016)
97+
- Never delete or replace existing checklist content - always preserve and append
9798

9899
**CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
99100
Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
@@ -205,13 +206,13 @@ You **MUST** consider the user input before proceeding (if not empty).
205206

206207
6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
207208

208-
7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize:
209+
7. **Report**: Output full path to checklist file, item count, and summarize whether the run created a new file or appended to an existing one. Summarize:
209210
- Focus areas selected
210211
- Depth level
211212
- Actor/timing
212213
- Any explicit user-specified must-have items incorporated
213214

214-
**Important**: Each `/speckit.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows:
215+
**Important**: Each `/speckit.checklist` command invocation uses a short, descriptive checklist filename and either creates a new file or appends to an existing one. This allows:
215216

216217
- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
217218
- Simple, memorable filenames that indicate checklist purpose

‎.claude/commands/speckit.clarify.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ Execution steps:
8686
- Information is better deferred to planning phase (note internally)
8787

8888
3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
89-
- Maximum of 10 total questions across the whole session.
89+
- Maximum of 5 total questions across the whole session.
9090
- Each question must be answerable with EITHER:
9191
- A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
9292
- A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").

‎.claude/commands/speckit.implement.md‎

Lines changed: 82 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ You **MUST** adhere to the following mandatory requirements when implementing fe
1010
- **Output:** Working code with passing tests
1111
- **Verification:** Execute Show & Tell steps after each phase
1212

13-
**Base requirements:** Follow all rules in [copilot-instructions.md](/.github/copilot-instructions.md), particularly:
13+
**Base requirements:** Follow all rules in [CLAUDE.md](/.claude/CLAUDE.md), particularly:
1414

1515
- Repository Tooling
1616
- Test-Driven Development
@@ -28,10 +28,10 @@ You **MUST** adhere to the following mandatory requirements when implementing fe
2828
Before marking implementation as complete, verify:
2929

3030
- [ ] All tasks in `tasks.md` are completed
31-
- [ ] Each repository-template capability that was planned to be implemented using the skill at [.github/skills/repository-template/SKILL.md](/.github/skills/repository-template/SKILL.md) is completed
31+
- [ ] Each repository-template capability that was planned to be implemented using the skill at [.claude/skills/repository-template/SKILL.md](/.claude/skills/repository-template/SKILL.md) is completed
3232
- [ ] TDD was followed: tests written before implementation
3333
- [ ] All `Show & Tell` steps executed successfully for each phase
34-
- [ ] Repository-template capabilities are present and up to date (see [.github/skills/repository-template/SKILL.md](/.github/skills/repository-template/SKILL.md))
34+
- [ ] Repository-template capabilities are present and up to date (see [.claude/skills/repository-template/SKILL.md](/.claude/skills/repository-template/SKILL.md))
3535
- [ ] `make lint` and `make test` complete with zero errors and zero warnings
3636

3737
## User Input
@@ -42,6 +42,45 @@ $ARGUMENTS
4242

4343
You **MUST** consider the user input before proceeding (if not empty).
4444

45+
## Pre-Execution Checks
46+
47+
**Check for extension hooks (before implementation)**:
48+
49+
- Check if `.specify/extensions.yml` exists in the project root.
50+
- If it exists, read it and look for entries under the `hooks.before_implement` key
51+
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
52+
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
53+
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
54+
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
55+
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
56+
- For each executable hook, output the following based on its `optional` flag:
57+
- **Optional hook** (`optional: true`):
58+
59+
```
60+
## Extension Hooks
61+
62+
**Optional Pre-Hook**: {extension}
63+
Command: `/{command}`
64+
Description: {description}
65+
66+
Prompt: {prompt}
67+
To execute: `/{command}`
68+
```
69+
70+
- **Mandatory hook** (`optional: false`):
71+
72+
```
73+
## Extension Hooks
74+
75+
**Automatic Pre-Hook**: {extension}
76+
Executing: `/{command}`
77+
EXECUTE_COMMAND: {command}
78+
79+
Wait for the result of the hook command before proceeding to the Outline.
80+
```
81+
82+
- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
83+
4584
## Outline
4685
4786
1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. 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").
@@ -95,12 +134,12 @@ You **MUST** consider the user input before proceeding (if not empty).
95134
git rev-parse --git-dir 2>/dev/null
96135
```
97136
98-
- Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
99-
- Check if .eslintrc* exists → create/verify .eslintignore
100-
- Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns
101-
- Check if .prettierrc* exists → create/verify .prettierignore
137+
- Check if Dockerfile\* exists or Docker in plan.md → create/verify .dockerignore
138+
- Check if .eslintrc\* exists → create/verify .eslintignore
139+
- Check if eslint.config.\* exists → ensure the config's `ignores` entries cover required patterns
140+
- Check if .prettierrc\* exists → create/verify .prettierignore
102141
- Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
103-
- Check if terraform files (*.tf) exist → create/verify .terraformignore
142+
- Check if terraform files (\*.tf) exist → create/verify .terraformignore
104143
- Check if .helmignore needed (helm charts present) → create/verify .helmignore
105144
106145
**If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
@@ -117,7 +156,7 @@ You **MUST** consider the user input before proceeding (if not empty).
117156
- **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
118157
- **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
119158
- **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
120-
- **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `Makefile`, `config.log`, `.idea/`, `*.log`, `.env*`
159+
- **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `*.dll`, `autom4te.cache/`, `config.status`, `config.log`, `.idea/`, `*.log`, `.env*`
121160
- **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
122161
- **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
123162
- **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
@@ -137,7 +176,7 @@ You **MUST** consider the user input before proceeding (if not empty).
137176
138177
6. Execute implementation following the task plan:
139178
- **Phase-by-phase execution**: Complete each phase before moving to the next
140-
- **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
179+
- **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
141180
- **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
142181
- **File-based coordination**: Tasks affecting the same files must run sequentially
143182
- **Validation checkpoints**: Verify each phase completion before proceeding
@@ -166,6 +205,39 @@ You **MUST** consider the user input before proceeding (if not empty).
166205
167206
Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list.
168207
208+
1. **Check for extension hooks**: After completion validation, check if `.specify/extensions.yml` exists in the project root.
209+
- If it exists, read it and look for entries under the `hooks.after_implement` key
210+
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
211+
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
212+
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
213+
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
214+
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
215+
- For each executable hook, output the following based on its `optional` flag:
216+
- **Optional hook** (`optional: true`):
217+
218+
```
219+
## Extension Hooks
220+
221+
**Optional Hook**: {extension}
222+
Command: `/{command}`
223+
Description: {description}
224+
225+
Prompt: {prompt}
226+
To execute: `/{command}`
227+
```
228+
229+
- **Mandatory hook** (`optional: false`):
230+
231+
```
232+
## Extension Hooks
233+
234+
**Automatic Hook**: {extension}
235+
Executing: `/{command}`
236+
EXECUTE_COMMAND: {command}
237+
```
238+
239+
- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
240+
169241
---
170242
171243
> **Version**: 1.6.0

‎.claude/commands/speckit.plan.md‎

Lines changed: 81 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: Execute the implementation planning workflow using the plan template to generate design artifacts.
3-
handoffs:
3+
handoffs:
44
- label: Create Tasks
55
agent: speckit.tasks
66
prompt: Break the plan into tasks
@@ -18,7 +18,7 @@ You **MUST** adhere to the following mandatory requirements when creating a deve
1818
- **Output:** `plan.md` (implementation plan)
1919
- **Next phase:** Tasks generation (`/speckit.tasks`)
2020

21-
**Base requirements:** Follow all rules in [copilot-instructions.md](/.github/copilot-instructions.md), particularly:
21+
**Base requirements:** Follow all rules in [CLAUDE.md](/.claude/CLAUDE.md), particularly:
2222

2323
- Documentation ADRs
2424
- Toolchain Version
@@ -31,16 +31,16 @@ Each phase and user story in `plan.md` must include a `Show & Tell` subsection.
3131
1. Expanded with specific commands in `tasks.md` (next phase)
3232
2. Executed by the user during implementation to verify completion
3333

34-
### GitHub Copilot Execution Requirement (Mandatory)
34+
### AI Assistant Execution Requirement (Mandatory)
3535

36-
Show & Tell steps must be written so GitHub Copilot can execute and validate them without guessing.
36+
Show & Tell steps must be written so AI Assistant can execute and validate them without guessing.
3737

3838
- Use explicit, runnable commands, URLs, and API calls
3939
- Include an expected result for every step (output text, status code, or visible UI state)
4040
- Avoid vague language such as "check it works" or "verify manually"
4141
- State pass/fail criteria clearly so steps cannot be skipped or missed during `/speckit.implement`
4242

43-
During implementation, GitHub Copilot **MUST** execute every Show & Tell step and confirm the expected result before marking the phase or user story complete.
43+
During implementation, AI Assistant **MUST** execute every Show & Tell step and confirm the expected result before marking the phase or user story complete.
4444

4545
## Plan Completion Checklist (Mandatory)
4646

@@ -49,7 +49,7 @@ Before marking `plan.md` as complete, verify:
4949
- [ ] Plan addresses all requirements from `spec.md`
5050
- [ ] All architectural decisions have corresponding ADRs
5151
- [ ] Toolchain versions are specified, verified online during planning, and confirmed as the latest stable releases
52-
- [ ] Repository-template capabilities are planned using the skill at [.github/skills/repository-template/SKILL.md](/.github/skills/repository-template/SKILL.md), including at minimum:
52+
- [ ] Repository-template capabilities are planned using the skill at [.claude/skills/repository-template/SKILL.md](/.claude/skills/repository-template/SKILL.md), including at minimum:
5353
- [ ] Core Make System
5454
- [ ] Pre-commit Hooks
5555
- [ ] Secret Scanning
@@ -59,7 +59,7 @@ Before marking `plan.md` as complete, verify:
5959
- [ ] Tool Version Management
6060
- [ ] Each phase and user story includes a `Show & Tell` subsection
6161
- [ ] Show & Tell subsections are placed at the end of each phase or user story
62-
- [ ] Show & Tell steps are specific enough for GitHub Copilot to execute and validate without ambiguity
62+
- [ ] Show & Tell steps are specific enough for AI Assistant to execute and validate without ambiguity
6363
- [ ] Show & Tell steps define explicit expected outcomes and pass/fail criteria
6464

6565
## User Input
@@ -70,6 +70,45 @@ $ARGUMENTS
7070

7171
You **MUST** consider the user input before proceeding (if not empty).
7272

73+
## Pre-Execution Checks
74+
75+
**Check for extension hooks (before planning)**:
76+
77+
- Check if `.specify/extensions.yml` exists in the project root.
78+
- If it exists, read it and look for entries under the `hooks.before_plan` key
79+
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
80+
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
81+
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
82+
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
83+
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
84+
- For each executable hook, output the following based on its `optional` flag:
85+
- **Optional hook** (`optional: true`):
86+
87+
```
88+
## Extension Hooks
89+
90+
**Optional Pre-Hook**: {extension}
91+
Command: `/{command}`
92+
Description: {description}
93+
94+
Prompt: {prompt}
95+
To execute: `/{command}`
96+
```
97+
98+
- **Mandatory hook** (`optional: false`):
99+
100+
```
101+
## Extension Hooks
102+
103+
**Automatic Pre-Hook**: {extension}
104+
Executing: `/{command}`
105+
EXECUTE_COMMAND: {command}
106+
107+
Wait for the result of the hook command before proceeding to the Outline.
108+
```
109+
110+
- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
111+
73112
## Outline
74113
75114
1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` 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").
@@ -87,6 +126,39 @@ You **MUST** consider the user input before proceeding (if not empty).
87126
88127
4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
89128
129+
5. **Check for extension hooks**: After reporting, check if `.specify/extensions.yml` exists in the project root.
130+
- If it exists, read it and look for entries under the `hooks.after_plan` key
131+
- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
132+
- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
133+
- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
134+
- If the hook has no `condition` field, or it is null/empty, treat the hook as executable
135+
- If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
136+
- For each executable hook, output the following based on its `optional` flag:
137+
- **Optional hook** (`optional: true`):
138+
139+
```
140+
## Extension Hooks
141+
142+
**Optional Hook**: {extension}
143+
Command: `/{command}`
144+
Description: {description}
145+
146+
Prompt: {prompt}
147+
To execute: `/{command}`
148+
```
149+
150+
- **Mandatory hook** (`optional: false`):
151+
152+
```
153+
## Extension Hooks
154+
155+
**Automatic Hook**: {extension}
156+
Executing: `/{command}`
157+
EXECUTE_COMMAND: {command}
158+
```
159+
160+
- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
161+
90162
## Phases
91163
92164
### Phase 0: Outline & Research
@@ -134,7 +206,7 @@ You **MUST** consider the user input before proceeding (if not empty).
134206
- Add only new technology from current plan
135207
- Preserve manual additions between markers
136208

137-
**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
209+
**Output**: data-model.md, /contracts/\*, quickstart.md, agent-specific file
138210

139211
## Key rules
140212

@@ -143,5 +215,5 @@ You **MUST** consider the user input before proceeding (if not empty).
143215

144216
---
145217

146-
> **Version**: 1.6.0
218+
> **Version**: 1.6.1
147219
> **Last Amended**: 2026-03-01

0 commit comments

Comments
 (0)