You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Hooks: pass the feature folder, and signal when converge finishes #5339
Hooks don't know their feature folder. A before_plan or after_tasks hook has to work out which specs/<feature> it is for from the branch name or .specify/feature.json. Passing it in, for example as SPECKIT_FEATURE_DIR, would remove the guessing. For before_specify the folder doesn't exist yet, so it could be empty there.
Nothing fires when converge finishes. Tools that want to mark a feature complete, or update a board, have no event to listen to.
Both would let extensions like SpecKit Companion and reconcile drop workarounds. Happy to open a PR for the first one if it fits.
AI disclosure: drafted with Claude Code (Claude Opus 5.5, default settings); I checked it before posting.
Opened #5452 for this: feat(hooks): pass SPECKIT_FEATURE_DIR to every extension hook block.
Every rendered hook block now carries SPECKIT_FEATURE_DIR, the FEATURE_DIR the command's setup
script already resolves, so a before_plan/after_tasks hook no longer has to guess the folder from
the branch name or .specify/feature.json. One line per block in the nine command templates that
surface hooks, so it is in the installed skills too. For before_specify it resolves to nothing, and specify.md says that in the pre-hook section, as you described.
On the second point: hooks.after_converge already exists (since /speckit.converge landed in #3001) and fires in converge's step 9. What was missing is the framing — the other five commands
carry a ## Mandatory Post-Execution Hooks section that says the agent must run them before
reporting completion, while converge's step 9 reads as ordinary prose after the handoff. #5452 makes
that step mandatory without moving it, so the event still fires when converge finishes. If you were
seeing something different from that, it is worth saying so on the PR and I will look again.
Changed: templates/commands/{specify,plan,tasks,implement,analyze,clarify,checklist,constitution,converge}.md, docs/extensions/api.md (a new ### Hook Context subsection) and tests/test_command_template_hooks.py
(text-level regression: one test per template, plus the empty case and the converge framing; the 11
new tests fail on main and pass with the change).
Ran: pytest tests/test_command_template_hooks.py 30 passed; hooks/extensions/integrations suites
4036 passed, 8 skipped; full pytest tests -q -n 4 16234 passed with the same 11 parity failures that
fail on main in my container; ruff check src tests clean. Also scaffolded a project with specify init --non-interactive and confirmed the installed SKILL.md files carry the line.
Review welcome — the mechanical 36-line template part is the bit worth a skim for wording.
hook handlers (for example before_plan, after_tasks) do not receive an explicit feature-directory context value and must infer it indirectly; 2) there is no hook signal at converge completion.
Follow-up comment links PR #5452 and states hooks.after_converge already exists, with missing framing in converge docs/templates being the practical gap.
Symptom
Extension hooks are surfaced/executed without explicit feature-folder context, forcing extensions to derive feature path indirectly (for example from .specify/feature.json), while users expect a direct context value. Separately, converge does define after_converge, but its template framing is weaker than other commands, so completion-hook behavior can be interpreted as optional/less explicit.
Reproduction
Register an extension hook under hooks.after_tasks (or hooks.before_plan) in .specify/extensions.yml that requires feature-folder context to operate deterministically.
Run the corresponding command template flow and inspect hook invocation/context output.
Observe there is no explicit SPECKIT_FEATURE_DIR context in the hook message/execution contract, so hook logic must infer feature directory from persisted state.
For converge, inspect templates/commands/converge.md: it defines hooks.after_converge, but does not use the same mandatory post-execution framing/checklist pattern used in templates like plan.md/tasks.md.
[NEEDS CLARIFICATION: a concrete failing extension example (repo/command output) demonstrating incorrect behavior, not just missing explicit context.]
Suspected Code Paths
src/specify_cli/extensions/__init__.py:6087-6130 — format_hook_message() renders hook blocks (optional/automatic) from hook metadata (extension, command, prompt, description) and does not include feature-directory context.
src/specify_cli/extensions/__init__.py:6174-6196 — execute_hook() returns hook execution metadata (command, invocation, extension, optional, description, prompt) with no feature-directory field.
templates/commands/plan.md:62,74-104 and templates/commands/tasks.md:63,95-125 — templates resolve FEATURE_DIR during setup, then define hook blocks without passing feature-dir context into those blocks.
templates/commands/converge.md:242-252 — contains after_converge hook check and outcome reporting, but no ## Mandatory Post-Execution Hooks section equivalent to other templates.
Root Cause Hypothesis
The hook contract currently treats hooks as command references plus human-facing prompt/description, not as context-rich invocations. Feature directory is resolved in command setup phases, but that value is not propagated into hook message/execution payloads. For converge, the event exists (after_converge) but the template structure differs from the stronger mandatory framing used elsewhere, creating ambiguity about guaranteed dispatch timing. Confidence: medium.
Proposed Remediation
Preferred: Standardize hook context payload across command templates and hook execution helpers by including the resolved feature directory where available (for example, SPECKIT_FEATURE_DIR), and make converge use the same mandatory post-execution hook framing/checklist language used by plan/tasks/specify/implement. For before_specify, explicitly document/emit empty or unset feature-dir context until the directory exists.
This preserves backward compatibility (existing hooks still work) while removing inference workarounds and reducing ambiguity.
Alternatives:
Add only documentation (no runtime/template change) describing .specify/feature.json as the supported source of truth. Trade-off: keeps extension workarounds and does not solve context propagation.
Add context only in docs-level hook blocks without changing HookExecutor metadata. Trade-off: weaker consistency between template contract and implementation helper APIs.
Files likely to change:
src/specify_cli/extensions/__init__.py
templates/commands/specify.md
templates/commands/plan.md
templates/commands/tasks.md
templates/commands/implement.md
templates/commands/clarify.md
templates/commands/analyze.md
templates/commands/checklist.md
templates/commands/constitution.md
templates/commands/converge.md
docs/extensions/api.md
tests/test_command_template_hooks.py
Tests to add or update:
Template text tests asserting hook blocks include feature-dir context where applicable and explicitly empty/unset behavior for before_specify.
Regression tests for converge template requiring mandatory post-execution hook framing parity with other commands.
Hook executor tests validating new context fields are surfaced consistently in formatted messages and execution metadata.
Risks & Considerations
Prompt/template compatibility drift across integrations if only a subset of templates are updated.
Potential confusion between “resolved feature directory” and branch naming if documentation is not explicit.
Low runtime risk; this is primarily contract clarity and context propagation.
Open Questions
[NEEDS CLARIFICATION: Should SPECKIT_FEATURE_DIR be guaranteed for all before_*/after_* hooks except before_specify, or only for a subset?]
[NEEDS CLARIFICATION: Is empty string or missing env var the preferred contract for before_specify?]
[NEEDS CLARIFICATION: Should converge adopt the exact same “Mandatory Post-Execution Hooks” heading/checklist wording as other command templates for strict consistency?]
Activity
shaktimaan00 commentedon Nov 16, 2026
Opened #5452 for this: feat(hooks): pass SPECKIT_FEATURE_DIR to every extension hook block.
Every rendered hook block now carries
SPECKIT_FEATURE_DIR, theFEATURE_DIRthe command's setupscript already resolves, so a
before_plan/after_taskshook no longer has to guess the folder fromthe branch name or
.specify/feature.json. One line per block in the nine command templates thatsurface hooks, so it is in the installed skills too. For
before_specifyit resolves to nothing, andspecify.mdsays that in the pre-hook section, as you described.On the second point:
hooks.after_convergealready exists (since/speckit.convergelanded in#3001) and fires in converge's step 9. What was missing is the framing — the other five commands
carry a
## Mandatory Post-Execution Hookssection that says the agent must run them beforereporting completion, while converge's step 9 reads as ordinary prose after the handoff. #5452 makes
that step mandatory without moving it, so the event still fires when converge finishes. If you were
seeing something different from that, it is worth saying so on the PR and I will look again.
Changed:
templates/commands/{specify,plan,tasks,implement,analyze,clarify,checklist,constitution,converge}.md,docs/extensions/api.md(a new### Hook Contextsubsection) andtests/test_command_template_hooks.py(text-level regression: one test per template, plus the empty case and the converge framing; the 11
new tests fail on
mainand pass with the change).Ran:
pytest tests/test_command_template_hooks.py30 passed; hooks/extensions/integrations suites4036 passed, 8 skipped; full
pytest tests -q -n 416234 passed with the same 11 parity failures thatfail on
mainin my container;ruff check src testsclean. Also scaffolded a project withspecify init --non-interactiveand confirmed the installedSKILL.mdfiles carry the line.Review welcome — the mechanical 36-line template part is the bit worth a skim for wording.
github-actions commentedon Nov 16, 2026
Bug assessment — hooks-feature-folder-converge: Likely valid, needs reproduction · severity low
Bug Assessment: Hooks: pass the feature folder, and signal when converge finishes
Report (summarized)
Issue by @alfredoperez reports two gaps:
before_plan,after_tasks) do not receive an explicit feature-directory context value and must infer it indirectly; 2) there is no hook signal at converge completion.Follow-up comment links PR #5452 and states
hooks.after_convergealready exists, with missing framing in converge docs/templates being the practical gap.Symptom
Extension hooks are surfaced/executed without explicit feature-folder context, forcing extensions to derive feature path indirectly (for example from
.specify/feature.json), while users expect a direct context value. Separately, converge does defineafter_converge, but its template framing is weaker than other commands, so completion-hook behavior can be interpreted as optional/less explicit.Reproduction
hooks.after_tasks(orhooks.before_plan) in.specify/extensions.ymlthat requires feature-folder context to operate deterministically.SPECKIT_FEATURE_DIRcontext in the hook message/execution contract, so hook logic must infer feature directory from persisted state.templates/commands/converge.md: it defineshooks.after_converge, but does not use the same mandatory post-execution framing/checklist pattern used in templates likeplan.md/tasks.md.[NEEDS CLARIFICATION: a concrete failing extension example (repo/command output) demonstrating incorrect behavior, not just missing explicit context.]
Suspected Code Paths
src/specify_cli/extensions/__init__.py:6087-6130—format_hook_message()renders hook blocks (optional/automatic) from hook metadata (extension,command,prompt,description) and does not include feature-directory context.src/specify_cli/extensions/__init__.py:6174-6196—execute_hook()returns hook execution metadata (command,invocation,extension,optional,description,prompt) with no feature-directory field.templates/commands/plan.md:62,74-104andtemplates/commands/tasks.md:63,95-125— templates resolveFEATURE_DIRduring setup, then define hook blocks without passing feature-dir context into those blocks.templates/commands/converge.md:242-252— containsafter_convergehook check and outcome reporting, but no## Mandatory Post-Execution Hookssection equivalent to other templates.Root Cause Hypothesis
The hook contract currently treats hooks as command references plus human-facing prompt/description, not as context-rich invocations. Feature directory is resolved in command setup phases, but that value is not propagated into hook message/execution payloads. For converge, the event exists (
after_converge) but the template structure differs from the stronger mandatory framing used elsewhere, creating ambiguity about guaranteed dispatch timing. Confidence: medium.Proposed Remediation
Preferred: Standardize hook context payload across command templates and hook execution helpers by including the resolved feature directory where available (for example,
SPECKIT_FEATURE_DIR), and make converge use the same mandatory post-execution hook framing/checklist language used by plan/tasks/specify/implement. Forbefore_specify, explicitly document/emit empty or unset feature-dir context until the directory exists.This preserves backward compatibility (existing hooks still work) while removing inference workarounds and reducing ambiguity.
Alternatives:
.specify/feature.jsonas the supported source of truth. Trade-off: keeps extension workarounds and does not solve context propagation.HookExecutormetadata. Trade-off: weaker consistency between template contract and implementation helper APIs.Files likely to change:
src/specify_cli/extensions/__init__.pytemplates/commands/specify.mdtemplates/commands/plan.mdtemplates/commands/tasks.mdtemplates/commands/implement.mdtemplates/commands/clarify.mdtemplates/commands/analyze.mdtemplates/commands/checklist.mdtemplates/commands/constitution.mdtemplates/commands/converge.mddocs/extensions/api.mdtests/test_command_template_hooks.pyTests to add or update:
before_specify.Risks & Considerations
Open Questions
SPECKIT_FEATURE_DIRbe guaranteed for allbefore_*/after_*hooks exceptbefore_specify, or only for a subset?]before_specify?]refactor: drop the hook feature-dir injection, keep the converge comp…