[Feature]: First-party bugfix and assess bundles with bundled workflows
- Ngôn ngữ chính
- Python
- Star
- 137k
- Fork
- 12.3k
- Merge trung bình
- 2 ngày 12 giờ
- Pull request đã merge (30 ngày)
- 159
Mô tả
### 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 #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: #4461 (maintainer-approved shape: two first-party bundles composing existing pieces, bug/assess command surfaces unchanged)
- Related discussion #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.
Hướng dẫn đóng góp
Hướng nghiên cứu
Start with the existing workflow and bundle layers, especially workflows/speckit/, workflows/catalog.json, bundles/catalog.community.json, and the bundle and workflow validation tests. Read workflows/README.md and docs/reference/bundles.md, then trace bundle add/remove and the builtin://default catalog resolution. Done means both workflows and bundles validate, install and remove together without collateral changes, catalog consistency passes, and the requested docs are updated.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- python
- Lĩnh vực
- cli, documentation, tooling
- Loại issue
- Tính năng
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức độ hoạt động
- Sôi nổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 45/100