Summary
Add a bundled bug extension that provides a three-stage bug triage workflow any AI coding agent can drive:
speckit.bug.assess — read a bug report (pasted text or URL), judge whether it is a real bug, locate suspected code paths, and propose a remediation.
speckit.bug.fix — apply the proposed remediation and record exactly what changed.
speckit.bug.test — re-run the reproduction and any added tests, then record the verification result.
Each stage writes a Markdown report into a per-bug directory:
.specify/bugs/<slug>/
├── assessment.md # speckit.bug.assess
├── fix.md # speckit.bug.fix
└── test.md # speckit.bug.test
Motivation
Spec Kit currently has strong scaffolding for new work (specs, plans, tasks) but no opinionated, repeatable flow for triaging incoming bug reports. Today each agent reinvents this loop ad-hoc. A bundled extension gives users:
- A consistent on-disk artifact trail per bug, suitable for review and audit.
- A clean handoff between agents/sessions — any agent can resume from the per-bug directory.
- A neutral output location (
.specify/bugs/<slug>/) that does not collide with feature branches or specs.
Design
Slug conventions
A slug is the per-bug directory name and is the only handle the three commands share.
- User-provided: any shape the user wants, normalized to lowercase kebab-case (e.g.
login-timeout, cve-2026-001, oauth-redirect-500). No timestamps or numbers are appended automatically.
- Asked for: interactively,
speckit.bug.assess asks for a slug when none is supplied, suggesting a kebab-case default derived from the bug summary.
- Automated: when no human is available, the agent generates a slug itself. The generated slug MUST produce a unique directory — if
.specify/bugs/<slug>/ already exists, the agent appends the shortest disambiguating suffix (-2, -3, …) or a short date (-20260605). Existing directories are never overwritten.
Guardrails
speckit.bug.assess and speckit.bug.test never modify source code; they read the repository and write only inside .specify/bugs/<slug>/.
speckit.bug.fix is the only command that edits source code, scoped to the files listed in the assessment unless new evidence requires expanding scope (logged under Deviations from Assessment in fix.md).
- No command overwrites an existing report file without explicit confirmation; in automated mode it refuses and picks a new unique slug.
- Verification results are not over-claimed: reproductions that were not actually performed are reported as
partial or not-run, never verified.
Packaging
Mirrors the layout of the existing bundled extensions (extensions/git/, extensions/agent-context/):
extensions/bug/extension.yml — manifest (id, version, three commands)
extensions/bug/commands/speckit.bug.{assess,fix,test}.md
extensions/bug/README.md
- Registered in
extensions/catalog.json (alphabetical: between agent-context and git)
- Wheel mapping added to
pyproject.toml → specify_cli/core_pack/extensions/bug
Scope (this issue)
- Bundled extension only; no new CLI commands, no new core machinery.
- Uses the existing extension registration / skills pipeline — no test changes required beyond what the generic extension tests already cover.
Out of scope
- Triage UI / dashboard over
.specify/bugs/.
- Cross-linking bugs to feature specs or tasks.
- Automated reproduction harness.
Acceptance criteria
Summary
Add a bundled
bugextension that provides a three-stage bug triage workflow any AI coding agent can drive:speckit.bug.assess— read a bug report (pasted text or URL), judge whether it is a real bug, locate suspected code paths, and propose a remediation.speckit.bug.fix— apply the proposed remediation and record exactly what changed.speckit.bug.test— re-run the reproduction and any added tests, then record the verification result.Each stage writes a Markdown report into a per-bug directory:
Motivation
Spec Kit currently has strong scaffolding for new work (specs, plans, tasks) but no opinionated, repeatable flow for triaging incoming bug reports. Today each agent reinvents this loop ad-hoc. A bundled extension gives users:
.specify/bugs/<slug>/) that does not collide with feature branches or specs.Design
Slug conventions
A slug is the per-bug directory name and is the only handle the three commands share.
login-timeout,cve-2026-001,oauth-redirect-500). No timestamps or numbers are appended automatically.speckit.bug.assessasks for a slug when none is supplied, suggesting a kebab-case default derived from the bug summary..specify/bugs/<slug>/already exists, the agent appends the shortest disambiguating suffix (-2,-3, …) or a short date (-20260605). Existing directories are never overwritten.Guardrails
speckit.bug.assessandspeckit.bug.testnever modify source code; they read the repository and write only inside.specify/bugs/<slug>/.speckit.bug.fixis the only command that edits source code, scoped to the files listed in the assessment unless new evidence requires expanding scope (logged under Deviations from Assessment infix.md).partialornot-run, neververified.Packaging
Mirrors the layout of the existing bundled extensions (
extensions/git/,extensions/agent-context/):extensions/bug/extension.yml— manifest (id, version, three commands)extensions/bug/commands/speckit.bug.{assess,fix,test}.mdextensions/bug/README.mdextensions/catalog.json(alphabetical: betweenagent-contextandgit)pyproject.toml→specify_cli/core_pack/extensions/bugScope (this issue)
Out of scope
.specify/bugs/.Acceptance criteria
specify extension add buginstalls the three commands and a per-bug directory is created on firstspeckit.bug.assessrun.