Add community bundle submission path (#3162)

SiCar10mw · web-flow · commit b7e67f55bf7a · 2026-06-26T16:56:34.000-05:00
* Add community bundle submission path

* Address bundle submission review feedback

* Align bundle submission triage label

* Clarify bundle submission review scope

* Clarify community bundle catalog listing
diff --git a/.github/ISSUE_TEMPLATE/bundle_submission.yml b/.github/ISSUE_TEMPLATE/bundle_submission.yml
@@ -0,0 +1,293 @@
+name: Bundle Submission
+description: Submit your bundle metadata for community catalog validation
+title: "[Bundle]: Add "
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for contributing a bundle! This template captures metadata for maintainers to validate formatting, links, component resolution, and installation evidence. Maintainers do not audit, endorse, or support bundle code or installed components.
+
+        **Before submitting:**
+        - Review the [Bundles reference](https://github.com/github/spec-kit/blob/main/docs/reference/bundles.md)
+        - Ensure your bundle has a valid `bundle.yml` manifest
+        - Create a GitHub release with a versioned bundle artifact
+        - Test installation from a downloaded artifact: `specify bundle install ./your-bundle-1.0.0.zip`
+        - If you host a bundle catalog, test catalog installation with `specify bundle catalog add <catalog-url> --id <catalog-id> --policy install-allowed` and `specify bundle install <bundle-id>`
+        - If your bundle depends on components from non-default catalogs, document those catalog URLs and test installation from a clean project
+
+  - type: input
+    id: bundle-id
+    attributes:
+      label: Bundle ID
+      description: Unique bundle identifier; must start and end with a lowercase letter or digit and may contain lowercase letters, digits, dots, underscores, and hyphens between
+      placeholder: "e.g., security-governance-stack"
+    validations:
+      required: true
+
+  - type: input
+    id: bundle-name
+    attributes:
+      label: Bundle Name
+      description: Human-readable bundle name
+      placeholder: "e.g., Security Governance Stack"
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Semantic version number
+      placeholder: "e.g., 1.0.0"
+    validations:
+      required: true
+
+  - type: input
+    id: role
+    attributes:
+      label: Role or Team
+      description: Primary role, team, or persona this bundle provisions
+      placeholder: "e.g., security-engineer, product-manager, platform-team"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Brief description of the stack this bundle installs
+      placeholder: Installs a security governance stack with compliance presets, review commands, and evidence workflows
+    validations:
+      required: true
+
+  - type: input
+    id: author
+    attributes:
+      label: Author
+      description: Your name or organization
+      placeholder: "e.g., Jane Doe or Acme Corp"
+    validations:
+      required: true
+
+  - type: input
+    id: repository
+    attributes:
+      label: Repository URL
+      description: GitHub repository URL for your bundle source
+      placeholder: "https://github.com/your-org/spec-kit-bundle-your-bundle"
+    validations:
+      required: true
+
+  - type: input
+    id: download-url
+    attributes:
+      label: Download URL
+      description: URL to the versioned bundle artifact generated by `specify bundle build`
+      placeholder: "https://github.com/your-org/spec-kit-bundle-your-bundle/releases/download/v1.0.0/your-bundle-1.0.0.zip"
+    validations:
+      required: true
+
+  - type: input
+    id: documentation
+    attributes:
+      label: Documentation URL
+      description: Link to documentation that explains what the bundle installs and how to use it
+      placeholder: "https://github.com/your-org/spec-kit-bundle-your-bundle/blob/main/README.md"
+    validations:
+      required: true
+
+  - type: input
+    id: license
+    attributes:
+      label: License
+      description: Open source license type
+      placeholder: "e.g., MIT, Apache-2.0"
+    validations:
+      required: true
+
+  - type: input
+    id: speckit-version
+    attributes:
+      label: Required Spec Kit Version
+      description: Minimum Spec Kit version required by the bundle
+      placeholder: "e.g., >=0.9.0"
+    validations:
+      required: true
+
+  - type: input
+    id: integration
+    attributes:
+      label: Integration Target (optional)
+      description: Integration ID if the bundle pins one; leave empty if integration-agnostic
+      placeholder: "e.g., claude, copilot, gemini"
+
+  - type: textarea
+    id: components-provided
+    attributes:
+      label: Components Provided
+      description: List the extensions, presets, workflows, and steps this bundle installs
+      placeholder: |
+        - extensions: sicario-guard@0.5.1
+        - presets: sicario-core@0.5.1, sicario-ai-governance@0.5.1
+        - workflows: evidence-review@1.0.0
+        - steps: threat-model
+    validations:
+      required: true
+
+  - type: textarea
+    id: required-catalogs
+    attributes:
+      label: Required Component Catalogs
+      description: List any non-default catalogs users must add before this bundle can resolve its components; enter "None" if every component resolves from built-in or bundled catalogs
+      placeholder: |
+        - Presets: https://github.com/your-org/your-bundle/releases/download/v1.0.0/presets.json
+        - Extensions: https://github.com/your-org/your-bundle/releases/download/v1.0.0/extensions.json
+    validations:
+      required: true
+
+  - type: textarea
+    id: tags
+    attributes:
+      label: Tags
+      description: 2-5 relevant tags (lowercase, separated by commas)
+      placeholder: "security, governance, compliance"
+    validations:
+      required: true
+
+  - type: textarea
+    id: features
+    attributes:
+      label: Key Features
+      description: List the main capabilities this bundle provides
+      placeholder: |
+        - Installs evidence-first security governance templates
+        - Adds automated bundle verification commands
+        - Pins all components to release-tested versions
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: testing
+    attributes:
+      label: Testing Checklist
+      description: Confirm that your bundle has been tested
+      options:
+        - label: Validation succeeds with `specify bundle validate --path <bundle-directory>`
+          required: true
+        - label: Build succeeds with `specify bundle build --path <bundle-directory>` and produces the submitted artifact
+          required: true
+        - label: Bundle installs successfully from the built artifact
+          required: true
+        - label: The submitted distribution path was tested end to end, including bundle-ID installation from an install-allowed catalog when a catalog entry is proposed
+          required: true
+        - label: Installation was tested in a clean Spec Kit project
+          required: true
+        - label: Required component catalogs are documented and were included in testing, or no extra catalogs are required
+          required: true
+        - label: Documentation is complete and accurate
+          required: true
+
+  - type: checkboxes
+    id: requirements
+    attributes:
+      label: Submission Requirements
+      description: Verify your bundle meets all requirements
+      options:
+        - label: Valid `bundle.yml` manifest included
+          required: true
+        - label: README.md explains the bundle's intended role, installed components, and installation steps
+          required: true
+        - label: LICENSE file included
+          required: true
+        - label: GitHub release created with a version tag
+          required: true
+        - label: Bundle ID matches the manifest and follows naming conventions
+          required: true
+        - label: Every extension, preset, workflow, and step reference is pinned where the manifest requires a version
+          required: true
+
+  - type: textarea
+    id: testing-details
+    attributes:
+      label: Testing Details
+      description: Describe how you tested your bundle
+      placeholder: |
+        **Tested on:**
+        - macOS 15 with Spec Kit v0.9.0
+        - Ubuntu 24.04 with Spec Kit v0.9.0
+
+        **Test project:** [Link or description]
+
+        **Test scenarios:**
+        1. Added required catalogs
+        2. Validated bundle manifest
+        3. Built release artifact
+        4. Installed bundle in a clean project
+        5. Ran the installed commands or workflows
+    validations:
+      required: true
+
+  - type: textarea
+    id: example-usage
+    attributes:
+      label: Example Usage
+      description: Provide a simple example of installing and using your bundle
+      render: markdown
+      placeholder: |
+        ```bash
+        # Add any required component catalogs first
+        specify preset catalog add https://github.com/your-org/your-bundle/releases/download/v1.0.0/presets.json --name your-bundle --install-allowed
+        specify extension catalog add https://github.com/your-org/your-bundle/releases/download/v1.0.0/extensions.json --name your-bundle --install-allowed
+
+        # Install the downloaded bundle artifact
+        curl -L -o your-bundle-1.0.0.zip https://github.com/your-org/your-bundle/releases/download/v1.0.0/your-bundle-1.0.0.zip
+        specify bundle install ./your-bundle-1.0.0.zip
+
+        # Or test through an install-allowed bundle catalog
+        specify bundle catalog add https://github.com/your-org/your-bundle/releases/download/v1.0.0/bundles.json --id your-bundle-catalog --policy install-allowed
+        specify bundle install your-bundle
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: catalog-entry
+    attributes:
+      label: Proposed Catalog Entry
+      description: Provide the JSON entry that would appear under the top-level `bundles` object in a bundle catalog (helps reviewers)
+      render: json
+      placeholder: |
+        {
+          "your-bundle": {
+            "name": "Your Bundle",
+            "id": "your-bundle",
+            "version": "1.0.0",
+            "role": "security-engineer",
+            "description": "Brief description of the stack",
+            "author": "Your Name",
+            "license": "MIT",
+            "download_url": "https://github.com/your-org/your-bundle/releases/download/v1.0.0/your-bundle-1.0.0.zip",
+            "repository": "https://github.com/your-org/your-bundle",
+            "requires": {
+              "speckit_version": ">=0.9.0"
+            },
+            "provides": {
+              "extensions": 1,
+              "presets": 2,
+              "steps": 0,
+              "workflows": 1
+            },
+            "tags": ["security", "governance"],
+            "verified": false
+          }
+        }
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any other information that would help reviewers
+      placeholder: Screenshots, demo videos, links to related projects, dependency-resolution notes, etc.
diff --git a/README.md b/README.md
@@ -134,13 +134,14 @@ Explore community-contributed resources on the [Spec Kit docs site](https://gith
 
 - [Extensions](https://github.github.io/spec-kit/community/extensions.html) — commands, hooks, and capabilities
 - [Presets](https://github.github.io/spec-kit/community/presets.html) — template and terminology overrides
+- [Bundles](https://github.github.io/spec-kit/community/bundles.html) — role and team stacks composed from existing components
 - [Walkthroughs](https://github.github.io/spec-kit/community/walkthroughs.html) — end-to-end SDD scenarios
 - [Friends](https://github.github.io/spec-kit/community/friends.html) — projects that extend or build on Spec Kit
 
 > [!NOTE]
 > Community contributions are independently created and maintained by their respective authors. Review source code before installation and use at your own discretion.
 
-Want to contribute? See the [Extension Publishing Guide](extensions/EXTENSION-PUBLISHING-GUIDE.md) or the [Presets Publishing Guide](presets/PUBLISHING.md).
+Want to contribute? See the [Extension Publishing Guide](extensions/EXTENSION-PUBLISHING-GUIDE.md), the [Presets Publishing Guide](presets/PUBLISHING.md), or the [Community Bundles guide](docs/community/bundles.md).
 
 ## 🤖 Supported AI Coding Agent Integrations
 
@@ -262,8 +263,10 @@ built-in). Each source carries an install policy: `install-allowed` sources can
 be installed from, while `discovery-only` sources are visible in `search`/`info`
 but refuse installation. Manage the stack with `specify bundle catalog list|add|remove`.
 
-Authors validate and package bundles locally — there is no first-class publish;
-distribution is hosting the built artifact and adding a catalog entry:
+Authors validate and package bundles locally. Distribution is hosting the built
+artifact and adding a catalog source; community bundle submissions use the
+[Bundle Submission](https://github.com/github/spec-kit/issues/new?template=bundle_submission.yml)
+issue template so required component catalogs and install evidence can be reviewed:
 
 ```bash
 specify bundle validate --path ./my-bundle      # structural + reference checks
diff --git a/docs/community/bundles.md b/docs/community/bundles.md
@@ -0,0 +1,53 @@
+# Community Bundles
+
+> [!NOTE]
+> Community bundles are independently created and maintained by their respective authors. Maintainers only verify that submission metadata is complete and correctly formatted — they do **not review, audit, endorse, or support the bundle code or the components it installs**. Review bundle manifests, component catalogs, and source repositories before installation and use at your own discretion.
+
+Bundles compose existing Spec Kit components — extensions, presets, workflows, and steps — into a single role or team stack. They are useful when a user should be able to install a tested set of components together instead of following several separate install commands.
+
+Accepted community bundle entries will be listed here once a community bundle catalog is available. To submit a bundle for review, file a [Bundle Submission](https://github.com/github/spec-kit/issues/new?template=bundle_submission.yml) issue.
+
+## What to Submit
+
+A bundle submission should include:
+
+- A public repository with a valid `bundle.yml` manifest.
+- A versioned GitHub release with a bundle artifact created by `specify bundle build`.
+- Documentation that explains the intended role, installed components, required catalogs, and expected workflow.
+- A proposed catalog entry with bundle metadata and component counts.
+- Test evidence from a clean Spec Kit project.
+
+## Component Resolution
+
+A bundle catalog entry describes where to download the bundle artifact, but the bundle's component references still need to resolve when a user installs it. References can resolve from bundled components, already installed components, or active extension, preset, workflow, and step catalogs.
+
+If your bundle depends on components that are not available from the default Spec Kit catalogs, include the required catalog URLs in the submission and in your README. Test the full install path from a clean project with those catalogs added before submitting.
+
+For example:
+
+```bash
+specify preset catalog add https://example.com/presets.json --name example-bundle --install-allowed
+specify extension catalog add https://example.com/extensions.json --name example-bundle --install-allowed
+curl -L -o example-bundle-1.0.0.zip https://example.com/example-bundle-1.0.0.zip
+specify bundle install ./example-bundle-1.0.0.zip
+
+# Or install by id from an install-allowed bundle catalog.
+specify bundle catalog add https://example.com/bundles.json --id example-bundle-catalog --policy install-allowed
+specify bundle install example-bundle
+```
+
+## Review Scope
+
+Maintainers check that:
+
+- The submission fields are complete and correctly formatted.
+- The release artifact and documentation URLs are reachable.
+- The repository contains a `bundle.yml` manifest.
+- The submission clearly identifies any required component catalogs.
+- The proposed catalog entry uses the expected bundle catalog entry shape.
+
+Maintainers do not audit the behavior of installed extensions, presets, workflows, steps, or scripts. Users should review those components before installing a community bundle.
+
+## Updating a Bundle
+
+To update a submitted bundle, file another [Bundle Submission](https://github.com/github/spec-kit/issues/new?template=bundle_submission.yml) issue with the new version, download URL, changed component list, and updated test evidence. Mention that the issue updates an existing bundle entry.
diff --git a/docs/community/overview.md b/docs/community/overview.md
@@ -1,6 +1,6 @@
 # Community
 
-The Spec Kit community builds extensions, presets, walkthroughs, and companion projects that expand what you can do with Spec-Driven Development. All community contributions are independently created and maintained by their respective authors.
+The Spec Kit community builds extensions, presets, bundles, walkthroughs, and companion projects that expand what you can do with Spec-Driven Development. All community contributions are independently created and maintained by their respective authors.
 
 ## Extensions
 
@@ -14,6 +14,12 @@ Presets customize how Spec Kit behaves — overriding templates, commands, and t
 
 [Browse community presets →](presets.md)
 
+## Bundles
+
+Bundles compose extensions, presets, workflows, and steps into role or team stacks that can be installed together.
+
+[Browse community bundles →](bundles.md)
+
 ## Walkthroughs
 
 Step-by-step guides that show Spec-Driven Development in action across different scenarios, languages, and frameworks.
diff --git a/docs/reference/bundles.md b/docs/reference/bundles.md
diff --git a/docs/toc.yml b/docs/toc.yml
