[Feature]: First-party bugfix and assess bundles with bundled workflows

[markuswondrak]

Problem Statement

Spec Kit ships exactly one out-of-the-box workflow: the SDD cycle (speckit, auto-installed at init). The bug and assess extensions provide multi-step pipelines (assess → fix → test, and intake → research → define → shape → decide) that are ideal workflow candidates, but they can only be driven by manually invoking each command — with no gates, persisted state, or workflow resume. There is no orchestrated bug-fixing or idea-assessment path in stock Spec Kit.

Discussed and agreed in #4461: the fix follows the existing layering — workflows live in the workflow layer, bundles are the composition layer. No new contribution types.

Proposed Solution

Two first-party bundles, each pairing its extension with a bundled workflow:

1. Bundled workflows (parallel to workflows/speckit/):

   • workflows/bugfix/workflow.yml (id bugfix): speckit.bug.assess → gate "review the assessment before any code change" (reject aborts) → speckit.bug.fix → speckit.bug.test; inputs: report, slug
   • workflows/assess/workflow.yml (id assess): intake → research → define → shape → decide → gate on the verdict (stops there; the /speckit.specify handoff stays manual); inputs: idea, slug
   • Both registered in workflows/catalog.json and packaged with the CLI (core_pack) like speckit — nothing is auto-installed at init; the extensions stay opt-in, installation happens via bundle add.

2. First-party bundles:

   • bundles/bugfix/ — bundle.yml composing the bug extension + bugfix workflow (pinned versions, role developer)
   • bundles/assess/ — bundle.yml composing the assess extension + assess workflow
   • bundles/catalog.json listing both (repo-shipped first-party counterpart to catalog.community.json, verified: true)

3. First-party bundle catalog wiring: the reserved builtin://default catalog (currently empty) resolves entries from bundles/catalog.json — online from the repo, offline from the packaged snapshot (mirroring the community catalog pattern). Without this, specify bundle add bugfix cannot resolve by id.

specify bundle add bugfix then installs the extension and its orchestrated pipeline in one step; bundle update/remove provide the lifecycle coupling.

Alternatives Considered

• Extension-owned workflows via provides.workflows in extension.yml (rejected in Expose built-in extension flows as specify workflow pipelines (extension-owned workflows) #4461: duplicates the bundle layer inside the extension layer).
• git / agent-context extension workflows — deliberately excluded: git runs via lifecycle hooks, agent-context is a single hook-driven command, not a multi-step flow.
• Only registering the workflows in workflows/catalog.json without bundles — would leave the extension↔workflow coupling to the user and defeat the agreed composition layer.

Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

Not applicable

Use Cases

1. A user hits a bug and wants a guided, resumable pipeline: assess → human gate before any code change → fix → test, instead of invoking three commands in the right order by hand.
2. A team wants idea triage before SDD: run the assess pipeline with a review gate at the verdict, then hand surviving ideas to /speckit.specify manually.

Acceptance Criteria

• validate_workflow passes for both new workflow YAMLs; steps/gates/inputs match the schema in workflows/README.md
• workflows/catalog.json entries match the bundled YAMLs' ids/versions/urls; contract test mirrors test_wheel_bundled_presets.py for bundled workflows
• specify bundle validate bundles/bugfix --offline (and assess) passes with zero unresolved references
• specify bundle add bugfix in a fresh project installs the bug extension and registers the bugfix workflow (workflow info/run works: assess → gate → fix → test)
• specify bundle remove bugfix uninstalls both contributed components; independently-installed components are never removed (no collateral removals, FR-022)
• Both bundles' catalog pins match the shipped extension/workflow versions; automated consistency test
• Docs updated: docs/reference/bundles.md (first-party bundles + bundles/catalog.json), workflows/README.md (layout), bundle READMEs
• Existing behavior unchanged: speckit workflow auto-install, extension add/remove, and community catalogs behave identically before/after

Additional Context

• Discussion: Expose built-in extension flows as specify workflow pipelines (extension-owned workflows) #4461 (maintainer-approved shape: two first-party bundles composing existing pieces, bug/assess command surfaces unchanged)
• Related discussion specify preset update — feature parity with extension update #4415 for the acceptance-criteria-first workflow
• Out of scope (follow-up): fully offline bundle install --offline. Today the bundle manifest itself always resolves via its catalog download_url, and workflow add has no bundled-asset fallback — both would need packaged first-party bundle artifacts. Tracked separately once this feature lands.
• Open point for the PR: hosting of the bundle artifacts referenced by the bundles/catalog.json download_urls (e.g. CI-built release assets), to be decided during implementation.

[mnriem]

This is exactly the shape we agreed in #4461 — workflows in workflows/ parallel to speckit, bundles composing them, no new contribution type. Marking feature-go. If you'd like to implement it, I'll assign you: scope is the two workflows/{bugfix,assess}/workflow.yml + workflows/catalog.json registration + the two bundles, reusing the bug/assess command surfaces unchanged.

[markuswondrak]

Posted on behalf of @markuswondrak by opencode (model: glm-5.3).

Implementation is up in #4504 — branch feat/4495-firstparty-bugfix-assess-bundles. It follows the shape agreed in #4461: two bundled workflows (workflows/bugfix, workflows/assess) composed into first-party bundles (bundles/bugfix, bundles/assess) via a new repo-shipped bundles/catalog.json that the reserved builtin://default catalog resolves online and from the packaged wheel snapshot offline.