Skip to content

fix(converge): run the completion hooks before converge reports finished - #5452

Open
shaktimaan00 wants to merge 2 commits into
github:mainfrom
shaktimaan00:feat/5339-hook-feature-dir
Open

shaktimaan00 wants to merge 2 commits into
github:mainfrom
shaktimaan00:feat/5339-hook-feature-dir

Conversation

@shaktimaan00

@shaktimaan00 shaktimaan00 commented Nov 16, 2026 •

Copy link
Copy Markdown

Converge can finish without ever running the hooks registered under hooks.after_converge, so an extension that
wants to mark the feature complete, or update a board, has nothing to listen to — the second half of #5339.

Step 9 now says it must run before the command reports convergence finished, and says why: those hooks are the only
completion signal converge produces.

The first half, SPECKIT_FEATURE_DIR, is dropped

Earlier commits on this branch put SPECKIT_FEATURE_DIR: {FEATURE_DIR} in nine templates, in the extensions docs and
in a template test. Reviewing that against the code, the value is not needed and, in the pre-hook blocks, cannot even
be filled:

  • Nothing fills the placeholder in a pre-hook. In plan.md the blocks sit under Pre-Execution Checks (line 25)
    and run before Outline 1. Setup (line 64) resolves FEATURE_DIR, so an agent would emit the literal
    {FEATURE_DIR}. The same holds for the pre-hooks in tasks, implement, checklist, analyze, clarify and
    converge.

  • The renderer that formats hook blocks is not the templates. HookExecutor.format_hook_message
    (src/specify_cli/extensions/__init__.py) is what produces a block for an agent at runtime, and it gained nothing.

  • The resolver already answers the question. check_prerequisites --paths-only reports FEATURE_DIR from
    SPECIFY_FEATURE_DIRECTORY when set, else from .specify/feature.json, and --paths-only does not persist
    anything:

    $ python3 .specify/scripts/python/check_prerequisites.py --paths-only
    FEATURE_DIR: /demo/specs/003-user-auth
    $ SPECIFY_FEATURE_DIRECTORY=specs/009-other python3 .specify/scripts/python/check_prerequisites.py --paths-only
    FEATURE_DIR: /demo/specs/009-other
    $ # neither set
    ERROR: Feature directory not found. Set SPECIFY_FEATURE_DIRECTORY or run the specify command to create
           .specify/feature.json.
    

    So before_specify and constitution already get an explicit error rather than a value to guess from, and a third
    name next to SPECIFY_FEATURE_DIRECTORY and FEATURE_DIR buys nothing.

Gates

Text-only change in one template. The tests that read the templates as text
(tests/test_command_template_hooks.py, tests/integrations) fail identically on this branch's parent in the
container used here — 807 failures on both sides — so nothing regressed; the only difference is the 11
SPECKIT_FEATURE_DIR template tests this PR added and I have removed.

Part of #5339

A hook that needs the feature it belongs to has to derive it from the branch
name or .specify/feature.json. Every rendered hook block now carries
SPECKIT_FEATURE_DIR: the FEATURE_DIR the command's setup script resolves
before the hooks run. It resolves to nothing for before_specify, where the
directory does not exist yet.

after_converge already existed, but converge's step 9 reads as optional next
to the "Mandatory Post-Execution Hooks" sections the other commands carry, so
an agent can report the handoff and never run it. It is now framed as
mandatory, without reordering, so the event still fires when converge finishes.

Refs github#5339

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Hooks reference undefined or unresolved FEATURE_DIR values across multiple workflows, risking missing or stale feature context, while constitution hooks lack defined behavior when no feature exists.

3 open issues
What changed in this PR

This PR addresses #5339 by adding feature-directory context to Spec Kit’s core command hook blocks and making the existing after_converge hook check explicitly mandatory before completion.

Changes:

  • Add SPECKIT_FEATURE_DIR to all four hook blocks in nine command templates.
  • Document hook context and the empty before_specify case.
  • Add template assertions for context fields, the empty case, and mandatory converge post-hooks.
File Description
tests/​test_command_template_hooks.py Add assertions for hook context and completion instructions.
templates/​commands/​tasks.md Add feature context to task hook blocks.
templates/​commands/​specify.md Add feature context and explain empty pre-hook values.
templates/​commands/​plan.md Add feature context to planning hook blocks.
templates/​commands/​implement.md Add feature context to implementation hook blocks.
templates/​commands/​converge.md Add feature context and mandatory post-hook instructions.
templates/​commands/​constitution.md Add feature context to constitution hook blocks.
templates/​commands/​clarify.md Add feature context to clarification hook blocks.
templates/​commands/​checklist.md Add feature context to checklist hook blocks.
templates/​commands/​analyze.md Add feature context to analysis hook blocks.
docs/​extensions/​api.md Document hook context delivery and empty-value semantics.

Review effort: Balanced (adaptive)

Comment thread templates/commands/constitution.md Resolved
Comment thread templates/commands/plan.md Resolved
Comment thread templates/commands/specify.md Resolved
@mnriem mnriem added the triage-nice-to-have Verdict: evidence-backed fix or greenlit feature — land after review label Nov 16, 2026
@mnriem

mnriem commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator

Could you provide a concrete example showing why the existing SPECIFY_FEATURE_DIRECTORY environment override and feature-directory resolver are insufficient for these hooks? The resolver already uses that override before falling back to .specify/feature.json, so extensions should not need to guess from branch names. This PR adds SPECKIT_FEATURE_DIR as prompt text rather than an environment variable, and it is not yet clear what failure that fixes. There are also unresolved context cases: pre-hooks run before setup obtains FEATURE_DIR, constitution does not establish a feature directory, and specify uses SPECIFY_FEATURE_DIRECTORY rather than FEATURE_DIR. Before adding another context name across the core templates, could you demonstrate a failing hook invocation and show that this change fixes it? The converge completion wording can be assessed separately.

AI disclosure: Prepared for @mnriem using GitHub Copilot (GPT-6.1 Sol), interactively at the user's request; AI inspected the PR and repository and drafted this comment.

…letion step

The pre-hook blocks this added sit under "Pre-Execution Checks", which run
before Outline step 1 resolves FEATURE_DIR, so `SPECKIT_FEATURE_DIR:
{FEATURE_DIR}` in plan, tasks, implement, checklist, analyze, clarify and
converge was a placeholder nothing fills. The renderer that actually formats
hook blocks for an agent is HookExecutor.format_hook_message, where this change
added nothing.

A hook can already resolve its feature directory: check_prerequisites
--paths-only reports FEATURE_DIR from .specify/feature.json, or from
SPECIFY_FEATURE_DIRECTORY when that is set, and fails with a clear error when
neither exists. The resolver covers the case, so a second name next to
SPECIFY_FEATURE_DIRECTORY and FEATURE_DIR is not needed.

Keep the converge change: step 9 now has to run before the command reports
convergence finished, which is the completion signal the issue asked for.

Refs github#5339
Copilot AI adaptive review requested due to automatic review settings November 17, 2026 03:59
@shaktimaan00 shaktimaan00 changed the title feat(hooks): pass SPECKIT_FEATURE_DIR to every extension hook block fix(converge): run the completion hooks before converge reports finished Nov 17, 2026
@shaktimaan00

Copy link
Copy Markdown
Author

You're right, and the demonstration settles it against the change rather than for it. I have dropped the feature-dir half, so the net diff on this branch is now the converge completion step only.

What I checked, in this branch's container:

1. The pre-hook blocks this added cannot be filled. In plan.md the blocks sit under Pre-Execution Checks (line 25) and run before Outline 1. Setup (line 64) resolves FEATURE_DIR, so SPECKIT_FEATURE_DIR: {FEATURE_DIR} would be emitted as literal text. Same for the pre-hooks in tasks, implement, checklist, analyze, clarify and converge.

2. The renderer that formats hook blocks is not the templates. HookExecutor.format_hook_message (src/specify_cli/extensions/__init__.py:6086) is what produces a block for an agent at runtime, and this PR never touched it. A before_plan block from it today:

## Extension Hooks

Hooks available for event 'before_plan':

**Optional Hook**: demo
Command: `/speckit.demo.hook`
Description: demo pre-hook that needs the feature directory

Prompt: Write the plan into the feature directory named here.
To execute: `/speckit.demo.hook`

3. A hook can already get the directory — your point exactly. With .specify/feature.json in the project:

$ python3 .specify/scripts/python/check_prerequisites.py --paths-only
REPO_ROOT: /demo
BRANCH: 003-user-auth
FEATURE_DIR: /demo/specs/003-user-auth

With the override, which wins over feature.json and is not persisted by --paths-only:

$ SPECIFY_FEATURE_DIRECTORY=specs/009-other python3 .specify/scripts/python/check_prerequisites.py --paths-only
FEATURE_DIR: /demo/specs/009-other

And with neither set, the case you flagged for constitution and before_specify, it already fails loudly instead of guessing:

$ python3 .specify/scripts/python/check_prerequisites.py --paths-only
ERROR: Feature directory not found. Set SPECIFY_FEATURE_DIRECTORY or run the specify command to create .specify/feature.json.
ERROR: Failed to resolve feature paths

So the resolver covers it, and an empty SPECKIT_FEATURE_DIR would have been a second way to say "no feature" next to an error the resolver already raises.

What is left is the part you said could be assessed separately: converge step 9 has to run before the command reports convergence finished, which is the completion signal the other half of #5339 asks for. Text-only, and the template-text tests still pass (tests/test_command_template_hooks.py green; the template/integration selection fails identically against this branch's parent in this container).

If you would rather have the directory available to a hook without shelling out to a script, the place for it is one call in HookExecutor.format_hook_message using the existing FEATURE_DIR name — say the word and I will follow up with that instead of the nine-template version.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The diff only makes after_converge mandatory, omitting the SPECKIT_FEATURE_DIR propagation, Hook Context documentation, and regression tests claimed by the PR.

1 open issue
3 resolved since last review

Review effort: Balanced (adaptive)

Comment on lines +244 to +246
**You MUST complete this section before reporting converge as finished.** These hooks are the
only completion signal this command produces, so a run that ends without them has not told
anything downstream that convergence finished.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

triage-nice-to-have Verdict: evidence-backed fix or greenlit feature — land after review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants