Repository navigation
[Feature]: Hook events for the bundled bug extension commands #4799
Description
Activity
Can you separate this into 2 issues?
- the hooks
- the rest
- changed the title
[-][Feature]: Hook events for the bundled `bug` extension (log intake as a pre-assess step)[/-][+][Feature]: Hook events for the bundled `bug` extension commands[/+]on Oct 1, 2026 Feature assessment — hook-events-bug-extension · Stage 1/5: Intake
Idea Intake: Hook events for the bundled bug extension commands
- Slug: hook-events-bug-extension
- Created: 2026-10-01T17:44:31Z
- Source: github.com/[Feature]: Hook events for the bundled
bugextension commands #4799 and its issue comments - Type: improvement
Idea (as captured)
Core commands (
plan,tasks,implement, ...) check.specify/extensions.ymlforbefore_*/after_*hooks. The three commands in the bundledbugextension (speckit.bug.assess,speckit.bug.fix,speckit.bug.test) do not, and no*_bug_*events are defined. That leaves other extensions no way to add a step to the bug workflow. A manifest that registers abefore_bug_assesspasses validation, but the hook never fires.Add the standard hook-check block to each bug command for
before_bug_assess/after_bug_assess,before_bug_fix/after_bug_fix, andbefore_bug_test/after_bug_test. The assess pre-hook should run after slug resolution and prerequisites, before ingest; the post-hook should run after the report is written. Apply the equivalent surrounding hooks to fix and test. With no hooks registered, behavior should remain unchanged.Acceptance criteria include updating
EXTENSION-API-REFERENCE.md, preserving no-hook output, and enabling use cases such as preprocessing evidence, synchronizing with an issue tracker, and sending notifications.Issue comments add that the request was split so this issue covers hook events, while the
evidence.mdconvention and log-reduction motivation moved to #4804.Restated
The bundled bug extension should expose lifecycle hook events around its assess, fix, and test commands, using the existing extension hook mechanism and preserving current behavior when no hooks are configured.
Origin & Context
- Raised by: alexcpn (GitHub issue author)
- Trigger: A reported gap in extension lifecycle coverage: registered bug hooks pass manifest validation but are not invoked; the issue was later narrowed to hook events at a maintainer's request.
First-Glance Unknowns
- [NEEDS CLARIFICATION: Which exact hook-check block and event documentation wording should be considered canonical if core command templates have diverged?]
- [NEEDS CLARIFICATION: What automated tests are expected to prove hook ordering and unchanged output with no hooks?]
- [NEEDS CLARIFICATION: Should hook event names be added to any machine-readable event registry in addition to the API reference?]
Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4799 · copilot · gpt52codex · 5.99 AIC · ⌖ 8.12 AIC · ⊞ 24K · ◷
Feature assessment — hook-events-bug-extension · Stage 2/5: Research
Idea Research: Hook events for the bundled bug extension commands
- Slug: hook-events-bug-extension
- Created: 2026-10-01T17:44:31Z
- Evidence confidence (overall): medium
Users & Demand
- The issue author describes a concrete extension-author need: a manifest can register
before_bug_assess, but the event does not fire, preventing other extensions from inserting workflow steps — [source: GitHub issue [Feature]: Hook events for the bundledbugextension commands #4799] (confidence: high). - The issue lists preprocessing evidence, issue-tracker synchronization, and post-test notifications as use cases, but these are stated examples rather than observed usage or measured demand — [source: GitHub issue [Feature]: Hook events for the bundled
bugextension commands #4799] (confidence: medium). - A maintainer comment requested splitting hooks from the
evidence.mdconvention, and a follow-up comment states that this issue was narrowed to hook events. That is stakeholder signal for a bounded request, not demand volume — [source: issue comments on [Feature]: Hook events for the bundledbugextension commands #4799] (confidence: high).
Prior Art
- Core command templates already document a repeated lifecycle-hook pattern that reads
.specify/extensions.ymlbefore and after command work;templates/commands/plan.mdis a direct internal precedent — [source:templates/commands/plan.md] (confidence: high). - The extension API reference defines the hook manifest shape,
HookExecutor, and standard core events, but its Hook Events list contains nobefore_bug_*orafter_bug_*events — [source:extensions/EXTENSION-API-REFERENCE.md] (confidence: high). - The bundled bug manifest declares the three bug commands but no hooks, and its README explicitly says the extension registers no hooks — [source:
extensions/bug/extension.yml,extensions/bug/README.md] (confidence: high). - Existing bundled bug-extension tests cover manifest/layout, catalog registration, resolution, installation, and command names; they do not establish bug-command hook ordering or no-hook output — [source:
tests/extensions/bug/test_bug_extension.py] (confidence: high).
Market & Context
- Within this repository, the current alternative is for extensions to lack lifecycle integration around the bug workflow or to use separate, command-specific workarounds; the issue says no standard event is available — [source: GitHub issue [Feature]: Hook events for the bundled
bugextension commands #4799] (confidence: medium). - The requested behavior follows the project's existing extension-hook convention rather than introducing a separate integration model — [source:
templates/commands/plan.md,extensions/EXTENSION-API-REFERENCE.md] (confidence: high). - External market or competitor evidence was not supplied and was not necessary to understand this repository-scoped request — [ASSUMPTION] (confidence: low).
Data & Constraints
- Hook checks are command-template instructions, so event placement and wording are part of the agent-facing command contract; the issue explicitly requires
before_bug_assessafter slug resolution/prerequisites and before ingest, with the matching post-hook after the artifact is written — [source: GitHub issue [Feature]: Hook events for the bundledbugextension commands #4799] (confidence: high). - The API reference currently describes standard events as core-defined and the hook configuration accepts arbitrary event keys in the manifest schema; whether a separate machine-readable event registry exists is not established by the inspected files — [source:
extensions/EXTENSION-API-REFERENCE.md] (confidence: medium). - No-hook behavior must remain unchanged, and the issue requests documentation plus automated coverage for ordering and compatibility — [source: GitHub issue [Feature]: Hook events for the bundled
bugextension commands #4799] (confidence: high). - No usage volume, performance budget, or compatibility matrix for installed agents was provided — [NEEDS CLARIFICATION: define the minimum supported command-template/test coverage across integrations] (confidence: low).
Evidence Against the Idea
- Demand evidence is limited to one issue and its comments; there are no counts of affected extensions, users, or failed workflows — [source: issue [Feature]: Hook events for the bundled
bugextension commands #4799 and comments] (confidence: high). - The change spans command prose, API documentation, and tests; if hook execution is only prompt-driven, small wording or placement mistakes could create inconsistent behavior across agents — [source:
templates/commands/plan.md, issue acceptance criteria] (confidence: medium). - The issue does not identify a canonical shared include or reusable helper for the hook-check block, so duplicating it across three commands could increase maintenance drift — [NEEDS CLARIFICATION: confirm the intended reuse/duplication pattern] (confidence: medium).
Gaps & Open Questions
- [NEEDS CLARIFICATION: Which exact existing command template should be the canonical hook block for bug commands?]
- [NEEDS CLARIFICATION: Are
before_bug_*andafter_bug_*event names intentionally free-form, or must they be registered in code in addition to the API reference?] - [NEEDS CLARIFICATION: What positive and negative tests can execute or validate command-template hook behavior without an LLM?]
- [NEEDS CLARIFICATION: What integrations, if any, must be checked for parity beyond the source command templates?]
Sources
- GitHub issue [Feature]: Hook events for the bundled
bugextension commands #4799 (host: github.com, policy: allowlisted) - Issue comments on [Feature]: Hook events for the bundled
bugextension commands #4799 (host: github.com, policy: allowlisted) templates/commands/plan.md(repository source)extensions/EXTENSION-API-REFERENCE.md(repository source)extensions/bug/extension.yml(repository source)extensions/bug/README.md(repository source)tests/extensions/bug/test_bug_extension.py(repository source)
Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4799 · copilot · gpt52codex · 5.99 AIC · ⌖ 8.12 AIC · ⊞ 24K · ◷
Feature assessment — hook-events-bug-extension · Stage 3/5: Problem
Problem Definition: Hook events for the bundled bug extension commands
- Slug: hook-events-bug-extension
- Created: 2026-10-01T17:44:31Z
- Inputs used: intake.md | research.md
Problem Statement
Extension authors cannot reliably augment the bundled bug workflow at its assess, fix, or test boundaries because the commands do not expose the standard lifecycle-hook checks that core commands expose. A hook declaration may be accepted in configuration while producing no workflow step, leaving bug-related integrations without a supported extension point.
Affected Users & Stakeholders
- Users: Extension authors — cannot add preprocessing, synchronization, or notification steps around bug commands through the established hook model (intake.md, research.md).
- Users: Teams using the bundled bug workflow — may need separate workarounds for integrations that depend on bug lifecycle boundaries (issue [Feature]: Hook events for the bundled
bugextension commands #4799). - Stakeholders: Spec Kit maintainers — own the consistency of command contracts and extension API documentation.
- Stakeholders: Agent integration maintainers — may be affected by command-template wording and behavior across supported agents ([NEEDS CLARIFICATION: identify the required integration matrix]).
Goals
- Make the supported lifecycle boundaries of the bundled bug workflow understandable and dependable to extension authors.
- Ensure configured lifecycle steps can be associated with the assess, fix, and test phases at the requested boundaries.
- Preserve the current experience and output when no lifecycle steps are configured.
- Keep the command contract and extension API reference aligned.
Non-Goals
- Defining or implementing the separate
evidence.mdconvention moved to issue [Feature]:evidence.mdconvention forspeckit.bug.assess(pre-digested inputs such as reduced logs) #4804. - Designing a new hook execution engine, manifest format, or external integration protocol.
- Changing the substantive bug assess, fix, or test workflow beyond exposing lifecycle boundaries.
- Measuring or guaranteeing demand across external users without data.
Success Metrics
- All six requested lifecycle boundaries are documented and represented in the three bundled bug command contracts (baseline: 0 documented bug events; target: 6).
- A configured hook is recognized at the required pre/post boundary for each phase in deterministic command-template or equivalent automated coverage (baseline: no bug-command coverage; target: assess, fix, and test positive coverage plus negative/no-hook coverage).
- With no hooks configured, existing command output and flow remain unchanged in regression coverage (baseline: current behavior; target: no observed difference).
- The API reference lists all six event names and their timing ([NEEDS CLARIFICATION: define whether another registry must also be updated]).
Cost of Inaction
Without a supported boundary, extensions that need to participate in the bug workflow remain unable to do so through the standard mechanism. They may duplicate workflow logic or operate outside the lifecycle, while configuration that appears valid can continue to create false expectations. The size of this cost is not quantified because no usage data was supplied.
Open Questions
- [NEEDS CLARIFICATION: What is the canonical source or reusable form of the existing hook-check block?]
- [NEEDS CLARIFICATION: Are the six event names sufficient, or must they be registered in a machine-readable event catalog?]
- [NEEDS CLARIFICATION: Which agent integrations require explicit parity tests?]
- [NEEDS CLARIFICATION: What exact deterministic tests prove execution order without relying on an LLM?]
Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4799 · copilot · gpt52codex · 5.99 AIC · ⌖ 8.12 AIC · ⊞ 24K · ◷
Feature assessment — hook-events-bug-extension · Stage 4/5: Concept
Concept: Hook events for the bundled bug extension commands
- Slug: hook-events-bug-extension
- Created: 2026-10-01T17:44:31Z
- Recommended option: Option A — Mirror the established lifecycle contract
Options
Option A — Mirror the established lifecycle contract
- Sketch: Treat assess, fix, and test as first-class lifecycle boundaries under the existing extension-hook convention. Expose the requested pre/post moments in the command contracts, describe them in the API reference, and add focused coverage that proves placement and unchanged no-hook behavior.
- Appetite: small
- Trade-offs: This is the smallest change aligned with the issue and existing core precedent, with low conceptual risk. It depends on the current hook-check wording being portable and may duplicate text across command templates.
- Rabbit holes: Trying to refactor all command templates at once; expanding the request to the separate evidence workflow; assuming a machine-readable registry is required without evidence.
Option B — Introduce a shared bug-workflow hook contract
- Sketch: Define a more formal shared contract for all bug lifecycle events, with one documented source of truth and explicit validation that bug event names are supported wherever hooks are described.
- Appetite: medium
- Trade-offs: Better long-term consistency and less wording drift, but broader than the stated request and potentially affects extension validation, installed command behavior, and multiple integrations.
- Rabbit holes: Changing manifest validation semantics; introducing a new event registry; requiring migrations or compatibility handling for existing extension configurations.
Option C — Do not add bug lifecycle hooks
- Sketch: Keep the current bug commands unchanged and document that extensions must integrate outside the bundled bug workflow or wait for a future extension point.
- Appetite: small
- Trade-offs: Avoids implementation and compatibility risk, but leaves the reported gap unresolved and preserves the mismatch between accepted-looking configuration and unavailable bug boundaries.
- Rabbit holes: Ad hoc integrations that duplicate bug workflow logic and create inconsistent behavior across extensions.
Recommendation
Recommend Option A. It directly addresses the stated problem using the repository's existing lifecycle-hook precedent, fits a small appetite, and can be evaluated against the issue's measurable boundaries: six events documented, correct pre/post placement, and no change when no hooks are configured. Option B should be reconsidered only if specification work confirms a separate machine-readable registry or validation change is required.
Out of Scope (for the recommended option)
- The
evidence.mdconvention and log-reduction work moved to [Feature]:evidence.mdconvention forspeckit.bug.assess(pre-digested inputs such as reduced logs) #4804. - A new hook engine, new manifest schema, or general redesign of extension registration.
- External integrations, notifications, issue-tracker adapters, or evidence processing themselves.
- Broad refactoring of every command template or agent integration unless required to preserve the existing contract.
Assumptions to Validate
- The established hook-check block in core command templates is the intended behavioral and wording precedent for the bug commands.
- The six requested event names can be supported as command-contract events without changes to a separate registry.
- Focused source-template and extension tests can prove ordering and no-hook compatibility deterministically.
- The requested lifecycle boundaries are useful enough to justify the small maintenance cost despite the absence of usage-volume data.
Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4799 · copilot · gpt52codex · 5.99 AIC · ⌖ 8.12 AIC · ⊞ 24K · ◷
Feature assessment — hook-events-bug-extension · Stage 5/5: Decision — verdict go
Decision: Hook events for the bundled bug extension commands
- Slug: hook-events-bug-extension
- Decided: 2026-10-01T17:44:31Z
- Verdict: go
- Artifacts reviewed: intake.md | research.md | problem.md | concept.md
Scorecard
Criterion Rating Justification Problem validity strong The issue identifies a concrete mismatch between accepted hook configuration and the absence of bug-command lifecycle checks; repository inspection confirms the bug commands and API reference lack the requested events. Evidence strength adequate The issue/comments plus internal templates, API reference, manifest, README, and tests provide cited evidence for the gap, though there is no usage-volume or external-demand data. Value vs. inaction adequate The small change would give extension authors supported bug-workflow boundaries and remove false expectations; the cost of inaction is real but unquantified. Feasibility / appetite strong The recommended option mirrors an existing core command convention and is bounded to three command contracts, documentation, and focused tests. Strategic fit strong The request improves consistency with the existing extension system and its documented lifecycle-hook model. Risk posture adequate Main risks—template drift, event-registration ambiguity, and agent-parity coverage—are identified; they can be bounded during specification, but are not fully resolved here. Verdict & Rationale
Go. The problem is specific and grounded in both the issue and repository artifacts, the evidence is adequate rather than assumption-only, and Option A provides a small, coherent path that fits the existing extension model. The open questions concern implementation boundaries and validation details, not whether the underlying gap exists; they should be carried into specification and resolved before implementation.
If go — Handoff to
/speckit-specify- Problem: Extension authors cannot reliably augment the bundled bug workflow because its assess, fix, and test commands expose no standard lifecycle-hook boundaries.
- Chosen approach: Mirror the established lifecycle contract by exposing the six requested pre/post events in the three bug command contracts, documenting their timing, and adding focused positive and no-hook regression coverage.
- In scope / out of scope: In scope are the bundled bug command templates, the extension API reference, and deterministic tests for event placement and unchanged no-hook behavior. Out of scope are the separate
evidence.mdwork, a new hook engine or manifest schema, external adapters, and broad command refactoring. - Success metrics: Six events are documented and represented; pre/post placement is covered for assess, fix, and test; no-hook behavior remains unchanged; documentation and command contracts agree.
- Carried-forward open questions:
- [NEEDS CLARIFICATION: Confirm the canonical/reusable form of the existing hook-check block.]
- [NEEDS CLARIFICATION: Confirm whether a machine-readable event registry must also be updated.]
- [NEEDS CLARIFICATION: Identify required agent-integration parity tests.]
- [NEEDS CLARIFICATION: Define deterministic tests for execution order without relying on an LLM.]
Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #4799 · copilot · gpt52codex · 5.99 AIC · ⌖ 8.12 AIC · ⊞ 24K · ◷
- added a commit that references this issue
on Oct 8, 2026
Problem Statement
Core commands (
plan,tasks,implement, …) check.specify/extensions.ymlfor
before_*/after_*hooks. The three commands in the bundledbugextension (
speckit.bug.assess,speckit.bug.fix,speckit.bug.test) do not,and no
*_bug_*events are defined. That leaves other extensions no way to adda step to the bug workflow. A manifest that registers
before_bug_assesspassesvalidation, but the hook never fires.
Proposed Solution
Add the standard hook-check block (the same block
templates/commands/plan.mduses) to each bug command, for these events:
before_bug_assessBUG_SLUG/BUG_DIRexist), before Execution → Ingestafter_bug_assessassessment.mdis writtenbefore_bug_fix/after_bug_fixfix.mdbefore_bug_test/after_bug_testtest.mdbefore_bug_assesshas to run after slug resolution rather than at the topof the command, because a pre-hook needs to know
BUG_DIRto write into. Thisuses the handoff the bug commands already rely on: "downstream commands in the
same session may reuse [the slug] from context without re-prompting."
With no hooks registered, behavior is exactly as today.
Alternatives Considered
assess, before slug resolution. That isconsistent with core commands, but the hook would have nowhere to write and
would have to guess the slug.
Component
Extensions: bundled
bugextension (extensions/bug/)AI Agent (if applicable)
All. Hooks are plain command-template instructions.
Use Cases
export, symbolicate a core dump (see [Feature]:
evidence.mdconvention forspeckit.bug.assess(pre-digested inputs such as reduced logs) #4804 for one concrete case).after_bug_assess.after_bug_test.Acceptance Criteria
speckit.bug.{assess,fix,test}check.specify/extensions.ymlfor theirbefore_*/after_*events using the same block as core commands.before_bug_assessfires afterBUG_DIRexists and before Ingest.EXTENSION-API-REFERENCE.md.I'm happy to send the PR.
Additional Context
bugextension).evidence.mdconvention is now [Feature]:evidence.mdconvention forspeckit.bug.assess(pre-digested inputs such as reduced logs) #4804.AI Disclosure
Drafted with Claude Code (Claude Opus 5.5) from my notes. I reviewed it.