Skip to content

Hooks: pass the feature folder, and signal when converge finishes #5339

Backlog

Description

@alfredoperez

Two small gaps extensions work around today:

  1. 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.
  2. 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.

Activity

  1. added
    triage-nice-to-haveVerdict: evidence-backed fix or greenlit feature — land after review
    on Nov 9, 2026
  2. shaktimaan00 commented on Nov 16, 2026

    @shaktimaan00

    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.

  3. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    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:

    1. 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

    1. Register an extension hook under hooks.after_tasks (or hooks.before_plan) in .specify/extensions.yml that requires feature-folder context to operate deterministically.
    2. Run the corresponding command template flow and inspect hook invocation/context output.
    3. 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.
    4. 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?]

    Generated by 🐛 Assess Bug from Labeled Issue for #5339 · copilot · gpt53codex · 33.9 AIC · ⌖ 0.664 AIC · ⊞ 24.2K · ◷

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions