The specify bundle command group manages the lifecycle of Bundles: curated, versioned stacks of Spec Kit primitives (extensions, presets, workflows, and steps). Bundles act as a distribution and composition layer that allows teams to provision a complete role-oriented environment (e.g., "Business Analyst" or "Security Engineer") in a single operation docs/reference/bundles.md1-6
A bundle is defined by a bundle.yml manifest docs/reference/bundles.md5-6 When installed, the system resolves all declared components, performs conflict detection (specifically for the active integration), and applies each component idempotently docs/reference/bundles.md44-47 The system tracks these installations via a provenance record system to allow for clean updates and removals without collateral damage to components required by other bundles docs/reference/bundles.md69-70
search) src/specify_cli/commands/bundle/__init__.py142-148info) src/specify_cli/commands/bundle/__init__.py194-200install) docs/reference/bundles.md46-47update) src/specify_cli/commands/bundle/__init__.py314-320remove) docs/reference/bundles.md69-70validate), and packaging (build) docs/reference/bundles.md96-120Sources: docs/reference/bundles.md1-70 src/specify_cli/commands/bundle/__init__.py1-29
The bundle system utilizes a service-layer architecture that separates CLI command logic from the core installation engine src/specify_cli/commands/bundle/__init__.py1-7
The following diagram maps the logical bundle operations to the internal code entities and data structures.
Title: Bundle System Architecture Mapping
Sources: src/specify_cli/commands/bundle/__init__.py25-36 src/specify_cli/bundler/commands_impl/catalog_config.py1-6 src/specify_cli/bundler/models/records.py23 src/specify_cli/bundler/services/packager.py18
When a user searches for or inspects a bundle, the system builds a CatalogStack which merges built-in, user, and project-scoped catalogs src/specify_cli/commands/bundle/__init__.py58-63
Title: Catalog Data Flow and Trust Validation
Sources: src/specify_cli/commands/bundle/__init__.py58-83 src/specify_cli/bundler/commands_impl/catalog_config.py15-21
The bundle.yml is the core configuration file for a bundle. It defines metadata, requirements, and the components to be installed.
The system validates manifests using specify bundle validate. This command ensures the YAML structure is correct and that component references are resolvable tests/contract/test_bundle_cli.py128-145
| Field | Description |
|---|---|
schema_version | Version of the bundle schema. |
id | Unique identifier (lowercase, alphanumeric, dots/hyphens). |
version | Semantic version of the bundle. |
role | Target persona (e.g., security-engineer). |
requires | Constraints such as speckit version or a specific integration. |
provides | Declared components (extensions, presets, workflows, steps). |
Sources: docs/reference/bundles.md98-108 tests/contract/test_bundle_cli.py128-165
Lists matching bundles across the active catalog stack src/specify_cli/commands/bundle/__init__.py142-148
stack.search(query) and renders a list with trust badges src/specify_cli/commands/bundle/__init__.py151-192Shows full metadata and the fully expanded component set that install would apply src/specify_cli/commands/bundle/__init__.py194-200
Installs a bundle's full component set through each primitive's machinery docs/reference/bundles.md44-47
_run_init src/specify_cli/commands/bundle/__init__.py92-126--integration selects the integration when initializing a new project docs/reference/bundles.md46-47Re-resolves a bundle and refreshes its components docs/reference/bundles.md59-61
Uninstalls only the components this bundle contributed, leaving any component that another installed bundle still needs docs/reference/bundles.md69-70
Reports whether a bundle.yml is well-formed and whether every declared component reference resolves docs/reference/bundles.md107-108
Produces a single versioned, distributable .zip artifact docs/reference/bundles.md120
build_bundle from the packager service tests/contract/test_bundle_cli.py167-175Manages bundle catalog sources via subcommands: add, remove, list src/specify_cli/commands/bundle/__init__.py31-36
Sources: src/specify_cli/commands/bundle/__init__.py142-320 docs/reference/bundles.md7-120 src/specify_cli/bundler/commands_impl/catalog_config.py1-180
The system maintains .specify/bundles/.records.json to track which bundle "owns" which installed component. This is critical for the remove command to avoid collateral damage (removing a component used by another bundle) docs/reference/bundles.md69-70
Conflict detection primarily focuses on the active_integration. If a bundle requires claude but the project is initialized with copilot, the bundler will refuse to install unless an override is provided or the project is switched docs/reference/bundles.md46-47
The CLI uses a StepTracker (from _console.py) to render hierarchical installation steps with status symbols (● for done, ○ for running/pending) src/specify_cli/_console.py41-124 On Windows, the Live display uses transient=False to avoid hanging legacy console hosts src/specify_cli/_console.py200-201
Sources: src/specify_cli/_console.py41-201 docs/reference/bundles.md46-70 src/specify_cli/bundler/models/records.py23
Refresh this wiki