Repository navigation
[Feature]: Allow bundles to reuse other bundles’ component declarations #5047
Description
Component: Bundles
Problem Statement
A bundle.yml can declare extensions, presets, steps, and workflows, but cannot reference another bundle.
This means publishers cannot offer a combined setup that reuses existing, independently maintained bundles without copying their component lists. Users can install several bundles separately, but there is no single manifest declaring that combined setup.
For example, an organization could publish a shared team-base bundle and want a team-security bundle to include that setup plus additional components. This is an illustrative use case: today, the publisher must duplicate the base declarations or document multiple installation commands.
The gap is reuse of published composition, not an inability to express the final component set. Duplicated lists must be maintained separately when the base bundle changes.
Proposed Solution
Allow a bundle to reference a specific version of another bundle. Resolve those references into an explicit component plan before installation, using the existing primitive installers and conflict checks.
Illustrative syntax—the field name and placement are open for discussion:
provides:
bundles:
- id: team-base
version: 1.2.0
extensions:
- id: secure-design
version: 0.4.0For an initial version, require exact version pins for referenced bundles. This avoids silently changing a parent’s composition when a child publishes a new release.
Suggested semantics
- Manifest expansion: Expand referenced bundles into the parent’s component plan. Prefer this over introducing independently installed child-bundle records for the first version, subject to maintainer agreement.
- Transparent preview:
bundle infoshows the resolved components and which bundle references introduced them. - Existing constraints remain effective: Validate referenced bundles’ integration and Spec Kit version requirements, and preserve their declared tool/MCP requirements in the resulting plan.
- Compatible overlap: When multiple references introduce the same component, install it once if its version, source, and applicable preset settings agree. Reject incompatible requirements before installation.
- Cycle detection: Reject direct and indirect cycles with an error showing the reference chain. Reject duplicate references within a manifest without treating compatible shared dependencies across different bundles as duplicates.
- Catalog policy: Resolve referenced bundles through the existing catalog precedence, release verification, and install-policy rules. A reference must not bypass these protections.
- Lifecycle: Record the resolved references and component requirements. Removal must preserve independently installed components and components still required by other installed bundles.
- Updates: Updating or refreshing the parent follows the references pinned in its selected manifest. It must not independently advance a referenced bundle to its latest release. Components dropped from the expanded plan follow existing removal protections.
This remains a distribution and composition feature. It adds no new runtime primitive, standalone skill/instruction management, or extension-owned workflows.
Alternatives Considered
- Copy component lists into each bundle: Supported today, but requires publishers to maintain duplicate declarations.
- Document multiple bundle installations: Avoids duplication, but does not provide one declarative, installable combined setup.
- Generate flattened manifests at publication time: Could solve the authoring problem without recursive installation-time resolution. This is a viable alternative if runtime references would add too much lifecycle complexity.
Use Cases
- Organization-wide defaults reused by team-specific bundles.
- Existing bundles, such as
bugfixandassess, combined into a larger development setup. - Independently maintained community bundles reused without copying their internal component inventories.
Acceptance Criteria
- A bundle can reference an exact version of another bundle using an agreed manifest field.
- Validation and installation resolve the same expanded component plan.
- Preview output identifies referenced bundles, their versions, and the components they introduce.
- Cycles, duplicate direct references, incompatible component requirements, and incompatible integration/version constraints produce actionable errors.
- Compatible components shared through multiple references are installed only once.
- Install, update, refresh, and removal preserve existing independent-install and shared-component protections.
- Parent updates respect referenced-bundle pins rather than implicitly following latest releases.
- Existing manifests without bundle references retain their behavior.
- Positive and negative tests cover expansion, conflicts, cycles, shared dependencies, and lifecycle behavior.
- Bundle documentation explains reference resolution, provenance, and lifecycle semantics.
Open Design Questions
- Should the manifest use
provides.bundles,includes, or another field? - Is manifest expansion sufficient, or is there a demonstrated need for independently tracked child bundles?
- Would build-time flattening provide the desired reuse with less complexity than installation-time resolution?
- Are additional graph-size or nesting limits needed beyond cycle detection?
Additional Context
In discussion #4291, the maintainer invited focused proposals for gaps in composing existing Spec Kit primitives. In discussion #4461, he emphasized that composition belongs in the bundle layer rather than in extensions.
This proposal aims to preserve that separation. Those statements provide relevant architectural context, not prior approval of bundle-to-bundle references.
AI Disclosure
Drafted with GitHub Copilot CLI using Claude Sonnet 5.5, then researched, reviewed, and revised using GPT-6 Astra in an interactive, user-directed session. AI assistance covered the issue wording, repository inspection, and review of relevant maintainer discussions. No implementation changes were made.
Activity
github-actions commentedon Oct 21, 2026
Feature assessment — bundle-reference-reuse · Stage 1/5: Intake
Idea Intake: Bundle-to-bundle composition reuse
Idea (as captured)
Restated
The request proposes adding bundle-level composition so a bundle manifest can reuse other published bundles by exact version pin instead of duplicating component declarations. The expanded effective plan should remain transparent and governed by current validation, catalog policy, conflict detection, and lifecycle safety rules.
Origin & Context
First-Glance Unknowns
provides.bundles,includes, or another key).]bundle info(component-level vs per-reference summaries).]github-actions commentedon Oct 21, 2026
Feature assessment — bundle-reference-reuse · Stage 2/5: Research
Idea Research: Bundle-to-bundle composition reuse
Users & Demand
Prior Art
extensions,presets,steps,workflows) and does not define a bundle-reference kind, which supports the issue claim that bundle-to-bundle composition is not currently first-class inbundle.yml. — [source: src/specify_cli/bundles/manifest.py#L21,L73-L76 | cited] (confidence: high)Market & Context
Data & Constraints
install_policyplus “highest-precedence source wins” behavior. Reference resolution must preserve these constraints to avoid policy bypass. — [source: src/specify_cli/bundles/catalogs.py#L4,L275 and src/specify_cli/bundles/catalog_stack.py#L87 | cited] (confidence: high)Evidence Against the Idea
Gaps & Open Questions
bundle infoto keep expanded plans debuggable (per-reference contribution mapping, conflict origin chain, both)?]provides.bundles) or a new top-level key (includes) with separate validation semantics?]Sources
github-actions commentedon Oct 21, 2026
Feature assessment — bundle-reference-reuse · Stage 3/5: Problem
Problem Definition: Reusable bundle composition without duplication
Problem Statement
Bundle publishers who need layered setups (shared base plus team-specific variants) currently must duplicate component declarations or ask users to run multiple install commands, creating maintenance churn and inconsistent composition over time. This matters now because Spec Kit positions bundles as the composition layer, but currently captures composition only at the primitive-component list level, not at reusable bundle-of-bundles level.
Affected Users & Stakeholders
Goals
Non-Goals
Success Metrics
Cost of Inaction
If this is not addressed, organizations continue paying ongoing maintenance cost to duplicate and synchronize component lists manually, while users continue relying on procedural multi-install instructions instead of a single reusable composition artifact. Over time this raises drift risk, weakens provenance clarity for composed setups, and may discourage adoption of bundle-based distribution for shared standards.
Open Questions
provides.bundles,includes, or other)?]github-actions commentedon Oct 21, 2026
Feature assessment — bundle-reference-reuse · Stage 4/5: Concept
Concept: Reusable composition for bundle publishers
Options
Option A — Publish-time composition flattening
Option B — Runtime recursive bundle references
bundle info/install/update, with provenance showing which reference introduced each component.Option C — Status quo plus documentation guidance (do nothing product-wise)
Recommendation
Recommend Option A as the best balance between the stated problem and current evidence. It directly addresses duplication and single-command composition goals while minimizing risk to existing install-policy/conflict/lifecycle guarantees that are already tightly coupled to flat resolved component plans. It also preserves an incremental path: prove demand and operational outcomes first, then evaluate whether runtime recursion is necessary.
Out of Scope (for the recommended option)
Assumptions to Validate
github-actions commentedon Oct 21, 2026
Feature assessment — bundle-reference-reuse · Stage 5/5: Decision — verdict needs-clarification
Decision: Bundle composition reuse assessment
Scorecard
Verdict & Rationale
needs-clarification. The problem is real and strategically aligned, and at least one plausible option exists; however, key shaping decisions that determine risk and scope are unresolved, and current demand evidence is not yet broad enough to justify a confident
go. Advancing now would likely force specification work to answer foundational product questions mid-stream, increasing rework risk.If needs-clarification
bundle infoand install output provide for referenced/flattened composition sources?]If go — Handoff to
/speckit-specifyNot applicable for this verdict.
mnriem commentedon Oct 21, 2026
@markuswondrak I ran the assessment to surface the questions. I was thinking along the lines of some combination of what presets as well as workflows already deliver for the bundle resolver here. Thoughts?
markuswondrak commentedon Oct 21, 2026
We had this discussion earlier that day and the problem is, that if I want to provide a bundle A that is based on other bundles B and C, I would only be able to do that if I copy all primitives hold by B and C into my own bundle yaml.
After that I as bundle A provider must now take care to keep All those extension versions aligned and make sure if B or C adds extensions, presets,... To their bundles, I need to add them as well.
I thought of like referencing another pom.xml and get those transitive dependencies automatically.
mnriem commentedon Oct 21, 2026
So at minimum a bundle should be able to be a bundle of references with or without itself own content?
markuswondrak commentedon Oct 21, 2026
Yes I think so. Just to align bundles to each other and ship it as one curated set of packages.
Our concrete problem was, that we wanted to include the default
bugfixbundle into our own, but figured this is not possible and we would need to list extension and workflow.Sidenote: This would also be helpful for local installations, that could just list all bundles (or other primitives) a spec-kit project uses.
mnriem commentedon Oct 21, 2026
Generally speaking everything that can be installed locally should work so if we have gaps we should address them one at a time
markuswondrak commentedon Oct 22, 2026
Proposed resolutions for the open design questions, from a design discussion on this issue's scope (@markuswondrak with an AI agent). Feedback welcome, especially from @mnriem.
Issue's open questions
provides.bundles: [{id, version, source?}]. It matches the existingprovides.<kind>lists parsed inmanifest.py;sourcekeeps its meaning as a catalog name (not a URL), verified against the winning bundle catalog.validate,info,install,updateandrefresh, and a plain localbundle.ymlthat references other bundles keeps working without a build step. Exact pins keep resolution deterministic. A lockfile-style embedded plan inbundle buildcould come later as an optimization.Details settled in the thread
{id, version, source?}and resolved through bundled, installed and catalog sources; direct paths and URLs exist only as separate CLI routes (--from). Bundle references follow the same model. A local parentbundle.ymlcan still reference catalog bundles such asbugfix.bundle info: a short per-reference summary plus per-component origin (shortest chain), with overrides marked inline, for examplesecure-design 0.5.0 (parent; overrides 0.4.0 from team-base). Flat bundles keep today's output.Still open (maintainer)
triage-nice-to-have).AI disclosure: Posted by @markuswondrak's account on his behalf. Written by pi (coding agent), provider github-copilot, model claude-sonnet-5.5, reasoning level high, in a supervised interactive session. The agent read the issue thread,
src/specify_cli/bundles/manifest.py,records.pyanddocs/reference/bundles.md, and drafted this summary of decisions that @markuswondrak reviewed and approved in conversation. No code was changed or tested.mnriem commentedon Oct 22, 2026
Go for it. We'll address anything that comes up as a concern during our review phase. Thanks for all the great work!