[Feature]: Hook events for the bundled `bug` extension commands

[alexcpn]

Problem Statement

Core commands (plan, tasks, implement, …) check .specify/extensions.yml
for before_* / after_* hooks. The three commands in the bundled bug
extension (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 before_bug_assess passes
validation, but the hook never fires.

Proposed Solution

Add the standard hook-check block (the same block templates/commands/plan.md
uses) to each bug command, for these events:

Event	Where it fires
before_bug_assess	After Slug Resolution/Prerequisites (so BUG_SLUG / BUG_DIR exist), before Execution → Ingest
after_bug_assess	After assessment.md is written
before_bug_fix / after_bug_fix	Around fix.md
before_bug_test / after_bug_test	Around test.md

before_bug_assess has to run after slug resolution rather than at the top
of the command, because a pre-hook needs to know BUG_DIR to write into. This
uses 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

• Hook at the very top of assess, before slug resolution. That is
  consistent with core commands, but the hook would have nowhere to write and
  would have to guess the slug.

Component

Extensions: bundled bug extension (extensions/bug/)

AI Agent (if applicable)

All. Hooks are plain command-template instructions.

Use Cases

• Intake before assess: reduce an attached log, fetch a trace or a Sentry
  export, symbolicate a core dump (see [Feature]: evidence.md convention for speckit.bug.assess (pre-digested inputs such as reduced logs) #4804 for one concrete case).
• Jira or issue-tracker sync after after_bug_assess.
• Notifications after after_bug_test.

Acceptance Criteria

• speckit.bug.{assess,fix,test} check .specify/extensions.yml for their
  before_* / after_* events using the same block as core commands.
• before_bug_assess fires after BUG_DIR exists and before Ingest.
• The new events are listed under Hook Events in
  EXTENSION-API-REFERENCE.md.
• With no hooks registered, the command output is unchanged.

I'm happy to send the PR.

Additional Context

• Builds on feat(extensions): add bundled bug triage workflow extension #2870 / feat(extensions): add bundled bug triage workflow extension #2871 (the bundled bug extension).
• Split from the original version of this issue at a maintainer's request. The
  evidence.md convention is now [Feature]: evidence.md convention for speckit.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.

[mnriem]

Can you separate this into 2 issues?

1. the hooks
2. the rest

[alexcpn]

Done. I've narrowed this issue to the hook events and moved the evidence.md convention (with the log-reduction motivation) to #4804.

[github-actions]

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 bug extension commands #4799 and its issue comments
• Type: improvement

Idea (as captured)

Core commands (plan, tasks, implement, ...) check .specify/extensions.yml for before_* / after_* hooks. The three commands in the bundled bug extension (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 a before_bug_assess passes 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, and before_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.md convention 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 · ◷

[github-actions]

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 bundled bug extension 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 bug extension commands #4799] (confidence: medium).
• A maintainer comment requested splitting hooks from the evidence.md convention, 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 bundled bug extension commands #4799] (confidence: high).

Prior Art

• Core command templates already document a repeated lifecycle-hook pattern that reads .specify/extensions.yml before and after command work; templates/commands/plan.md is 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 no before_bug_* or after_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 bug extension 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_assess after slug resolution/prerequisites and before ingest, with the matching post-hook after the artifact is written — [source: GitHub issue [Feature]: Hook events for the bundled bug extension 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 bug extension 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 bug extension 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_* and after_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 bug extension commands #4799 (host: github.com, policy: allowlisted)
• Issue comments on [Feature]: Hook events for the bundled bug extension 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 · ◷

[github-actions]

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 bug extension 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.md convention moved to issue [Feature]: evidence.md convention for speckit.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 · ◷

[github-actions]

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.md convention and log-reduction work moved to [Feature]: evidence.md convention for speckit.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 · ◷

[github-actions]

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.md work, 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 · ◷