diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a60b7a0306..cf0686db1a 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,3 +1,8 @@ # Global code owner * @mnriem +# Community catalog files — explicit ownership for when global ownership expands +/extensions/catalog.community.json @mnriem +/integrations/catalog.community.json @mnriem +/presets/catalog.community.json @mnriem + diff --git a/.github/ISSUE_TEMPLATE/preset_submission.yml b/.github/ISSUE_TEMPLATE/preset_submission.yml index 3a1b963492..f80e9cbdc5 100644 --- a/.github/ISSUE_TEMPLATE/preset_submission.yml +++ b/.github/ISSUE_TEMPLATE/preset_submission.yml @@ -95,11 +95,18 @@ body: validations: required: true + - type: input + id: required-extensions + attributes: + label: Required Extensions (optional) + description: Comma-separated list of required extension IDs (e.g., aide) + placeholder: "e.g., aide, canon" + - type: textarea id: templates-provided attributes: label: Templates Provided - description: List the template overrides your preset provides + description: List the template overrides your preset provides (enter "None" if command-only) placeholder: | - spec-template.md — adds compliance section - plan-template.md — includes audit checkpoints @@ -110,10 +117,19 @@ body: - type: textarea id: commands-provided attributes: - label: Commands Provided (optional) - description: List any command overrides your preset provides + label: Commands Provided + description: List the command overrides your preset provides (enter "None" if template-only) placeholder: | - speckit.specify.md — customized for compliance workflows + validations: + required: true + + - type: input + id: scripts-count + attributes: + label: Number of Scripts (optional) + description: How many scripts does your preset provide? (leave empty if none) + placeholder: "e.g., 1" - type: textarea id: tags diff --git a/.github/workflows/catalog-assign.yml b/.github/workflows/catalog-assign.yml new file mode 100644 index 0000000000..4191bcc554 --- /dev/null +++ b/.github/workflows/catalog-assign.yml @@ -0,0 +1,59 @@ +name: "Catalog: Auto-assign submission" + +on: + issues: + types: [opened, labeled] + +jobs: + assign: + if: > + (github.event.action == 'opened' && ( + contains(github.event.issue.labels.*.name, 'extension-submission') || + contains(github.event.issue.labels.*.name, 'preset-submission') + )) || + (github.event.action == 'labeled' && ( + github.event.label.name == 'extension-submission' || + github.event.label.name == 'preset-submission' + )) + runs-on: ubuntu-latest + permissions: + issues: write + steps: + - uses: actions/github-script@v7 + with: + script: | + const issue = context.payload.issue; + const assigned = (issue.assignees || []).map(a => a.login); + const marker = ''; + + // Assign mnriem if not already assigned + if (!assigned.includes('mnriem')) { + try { + await github.rest.issues.addAssignees({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + assignees: ['mnriem'], + }); + } catch (e) { + console.log(`Warning: could not assign mnriem: ${e.message}`); + } + } + + // Post team notification if not already posted + const comments = await github.paginate( + github.rest.issues.listComments, + { + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + } + ); + if (!comments.some(c => c.body && c.body.includes(marker))) { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: marker + '\ncc @github/spec-kit-maintainers — new catalog submission for review.', + }); + } diff --git a/README.md b/README.md index 59d2fd5dec..55af0538a0 100644 --- a/README.md +++ b/README.md @@ -174,7 +174,7 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c ## 🧩 Community Extensions > [!NOTE] -> Community extensions are independently created and maintained by their respective authors. GitHub and the Spec Kit maintainers may review pull requests that add entries to the community catalog for formatting, catalog structure, or policy compliance, but they do **not review, audit, endorse, or support the extension code itself**. The Community Extensions website is also a third-party resource. Review extension source code before installation and use at your own discretion. +> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. The Community Extensions website is also a third-party resource. Review extension source code before installation and use at your own discretion. 🔍 **Browse and search community extensions on the [Community Extensions website](https://speckit-community.github.io/extensions/).** diff --git a/docs/community/presets.md b/docs/community/presets.md index 0bb7a7ab42..876f19f825 100644 --- a/docs/community/presets.md +++ b/docs/community/presets.md @@ -1,7 +1,7 @@ # Community Presets > [!NOTE] -> Community presets are independently created and maintained by their respective authors. GitHub and the Spec Kit maintainers may review pull requests that add entries to the community catalog for formatting, catalog structure, or policy compliance, but they do **not review, audit, endorse, or support the preset code itself**. Review preset source code before installation and use at your own discretion. +> Community presets are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the preset code itself**. Review preset source code before installation and use at your own discretion. The following community-contributed presets customize how Spec Kit behaves — overriding templates, commands, and terminology without changing any tooling. Presets are available in [`catalog.community.json`](https://github.com/github/spec-kit/blob/main/presets/catalog.community.json): diff --git a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md index dfc1125228..4ebbbf3e8f 100644 --- a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md +++ b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md @@ -528,11 +528,9 @@ specify extension add --from https://github.com/.../spec-kit-my Submit to the community catalog for public discovery: -1. **Fork** spec-kit repository -2. **Add entry** to `extensions/catalog.community.json` -3. **Update** the Community Extensions table in `README.md` with your extension -4. **Create PR** following the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) -5. **After merge**, your extension becomes available: +1. **Create a GitHub release** for your extension +2. **File an issue** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template +3. **After review**, a maintainer updates the catalog and your extension becomes available: - Users can browse `catalog.community.json` to discover your extension - Users copy the entry to their own `catalog.json` - Users install with: `specify extension add my-ext` (from their catalog) diff --git a/extensions/EXTENSION-PUBLISHING-GUIDE.md b/extensions/EXTENSION-PUBLISHING-GUIDE.md index 1433738743..be5b375241 100644 --- a/extensions/EXTENSION-PUBLISHING-GUIDE.md +++ b/extensions/EXTENSION-PUBLISHING-GUIDE.md @@ -7,9 +7,8 @@ This guide explains how to publish your extension to the Spec Kit extension cata 1. [Prerequisites](#prerequisites) 2. [Prepare Your Extension](#prepare-your-extension) 3. [Submit to Catalog](#submit-to-catalog) -4. [Verification Process](#verification-process) -5. [Release Workflow](#release-workflow) -6. [Best Practices](#best-practices) +4. [Release Workflow](#release-workflow) +5. [Best Practices](#best-practices) --- @@ -133,222 +132,46 @@ specify extension add --from https://github.com/your-org/spec-k Spec Kit uses a dual-catalog system. For details about how catalogs work, see the main [Extensions README](README.md#extension-catalogs). -**For extension publishing**: All community extensions should be added to `catalog.community.json`. Users browse this catalog and copy extensions they trust into their own `catalog.json`. +**For extension publishing**: All community extensions are listed in `extensions/catalog.community.json`. Users browse this catalog and copy extensions they trust into their own `catalog.json`. -### 1. Fork the spec-kit Repository +### How to Submit -```bash -# Fork on GitHub -# https://github.com/github/spec-kit/fork - -# Clone your fork -git clone https://github.com/YOUR-USERNAME/spec-kit.git -cd spec-kit -``` - -### 2. Add Extension to Community Catalog - -Edit `extensions/catalog.community.json` and add your extension: - -```json -{ - "schema_version": "1.0", - "updated_at": "2026-01-28T15:54:00Z", - "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json", - "extensions": { - "your-extension": { - "name": "Your Extension Name", - "id": "your-extension", - "description": "Brief description of your extension", - "author": "Your Name", - "version": "1.0.0", - "download_url": "https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip", - "repository": "https://github.com/your-org/spec-kit-your-extension", - "homepage": "https://github.com/your-org/spec-kit-your-extension", - "documentation": "https://github.com/your-org/spec-kit-your-extension/blob/main/docs/", - "changelog": "https://github.com/your-org/spec-kit-your-extension/blob/main/CHANGELOG.md", - "license": "MIT", - "requires": { - "speckit_version": ">=0.1.0", - "tools": [ - { - "name": "required-mcp-tool", - "version": ">=1.0.0", - "required": true - } - ] - }, - "provides": { - "commands": 3, - "hooks": 1 - }, - "tags": [ - "category", - "tool-name", - "feature" - ], - "verified": false, - "downloads": 0, - "stars": 0, - "created_at": "2026-01-28T00:00:00Z", - "updated_at": "2026-01-28T00:00:00Z" - } - } -} -``` - -**Important**: - -- Set `verified: false` (maintainers will verify) -- Set `downloads: 0` and `stars: 0` (auto-updated later) -- Use current timestamp for `created_at` and `updated_at` -- Update the top-level `updated_at` to current time +To submit your extension to the community catalog, file a new issue using the **[Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml)** template. The template collects all required metadata, including: -### 3. Update Community Extensions Table +- Extension ID, name, and version +- Description, author, and license +- Repository, download URL, and documentation links +- Required Spec Kit version and any tool dependencies +- Number of commands and hooks +- Tags and key features +- Testing confirmation -Add your extension to the Community Extensions table in the project root `README.md`: +> [!IMPORTANT] +> Do **not** open a pull request directly to edit `extensions/catalog.community.json`. All community extension submissions must go through the issue template so a maintainer can review the entry and update the catalog. -```markdown -| Your Extension Name | Brief description of what it does | `` | | [repo-name](https://github.com/your-org/spec-kit-your-extension) | -``` - -**(Table) Category** — pick the one that best fits your extension: - -- `docs` — reads, validates, or generates spec artifacts -- `code` — reviews, validates, or modifies source code -- `process` — orchestrates workflow across phases -- `integration` — syncs with external platforms -- `visibility` — reports on project health or progress - -**Effect** — choose one: - -- Read-only — produces reports without modifying files -- Read+Write — modifies files, creates artifacts, or updates specs - -Insert your extension in alphabetical order in the table. +### What Happens After You Submit -### 4. Submit Pull Request +1. Your issue is automatically labeled and assigned to a maintainer for review +2. A maintainer verifies that the catalog entry is complete and correctly formatted +3. Once approved, the maintainer adds your extension to `extensions/catalog.community.json` and the Community Extensions table in the README +4. Your extension becomes discoverable via `specify extension search` -```bash -# Create a branch -git checkout -b add-your-extension - -# Commit your changes -git add extensions/catalog.community.json README.md -git commit -m "Add your-extension to community catalog - -- Extension ID: your-extension -- Version: 1.0.0 -- Author: Your Name -- Description: Brief description -" +### What Maintainers Check -# Push to your fork -git push origin add-your-extension +- The catalog entry fields are complete and correctly formatted +- The download URL is accessible +- The repository exists and contains an `extension.yml` manifest -# Create Pull Request on GitHub -# https://github.com/github/spec-kit/compare -``` - -**Pull Request Template**: - -```markdown -## Extension Submission - -**Extension Name**: Your Extension Name -**Extension ID**: your-extension -**Version**: 1.0.0 -**Author**: Your Name -**Repository**: https://github.com/your-org/spec-kit-your-extension - -### Description -Brief description of what your extension does. - -### Checklist -- [x] Valid extension.yml manifest -- [x] README.md with installation and usage docs -- [x] LICENSE file included -- [x] GitHub release created (v1.0.0) -- [x] Extension tested on real project -- [x] All commands working -- [x] No security vulnerabilities -- [x] Added to extensions/catalog.community.json -- [x] Added to Community Extensions table in README.md - -### Testing -Tested on: -- macOS 13.0+ with spec-kit 0.1.0 -- Project: [Your test project] - -### Additional Notes -Any additional context or notes for reviewers. -``` +> [!NOTE] +> Maintainers do **not** review, audit, or test the extension code itself. ---- - -## Verification Process - -### What Happens After Submission - -1. **Automated Checks** (if available): - - Manifest validation - - Download URL accessibility - - Repository existence - - License file presence - -2. **Manual Review**: - - Code quality review - - Security audit - - Functionality testing - - Documentation review - -3. **Verification**: - - If approved, `verified: true` is set - - Extension appears in `specify extension search --verified` - -### Verification Criteria - -To be verified, your extension must: - -✅ **Functionality**: - -- Works as described in documentation -- All commands execute without errors -- No breaking changes to user workflows - -✅ **Security**: - -- No known vulnerabilities -- No malicious code -- Safe handling of user data -- Proper validation of inputs - -✅ **Code Quality**: - -- Clean, readable code -- Follows extension best practices -- Proper error handling -- Helpful error messages - -✅ **Documentation**: - -- Clear installation instructions -- Usage examples -- Troubleshooting section -- Accurate description +### Typical Review Timeline -✅ **Maintenance**: +- **Review**: 3-7 business days -- Active repository -- Responsive to issues -- Regular updates -- Semantic versioning followed +### Updating an Existing Extension -### Typical Review Timeline - -- **Automated checks**: Immediate (if implemented) -- **Manual review**: 3-7 business days -- **Verification**: After successful review +To update an extension that is already in the catalog (e.g., for a new version), file a new **[Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml)** issue with the updated version, download URL, and any other changed fields. Mention in the issue that this is an update to an existing entry. --- @@ -385,26 +208,7 @@ When releasing a new version: # Create release on GitHub ``` -4. **Update catalog**: - - ```bash - # Fork spec-kit repo (or update existing fork) - cd spec-kit - - # Update extensions/catalog.json - jq '.extensions["your-extension"].version = "1.1.0"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json - jq '.extensions["your-extension"].download_url = "https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.1.0.zip"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json - jq '.extensions["your-extension"].updated_at = "2026-02-15T00:00:00Z"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json - jq '.updated_at = "2026-02-15T00:00:00Z"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json - - # Submit PR - git checkout -b update-your-extension-v1.1.0 - git add extensions/catalog.json - git commit -m "Update your-extension to v1.1.0" - git push origin update-your-extension-v1.1.0 - ``` - -5. **Submit update PR** with changelog in description +4. **File an update submission** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template with the new version and download URL. Mention in the issue that this is an update to an existing entry. --- @@ -473,9 +277,9 @@ A: The main catalog is for public extensions only. For private extensions: - Users add your catalog: `specify extension add-catalog https://your-domain.com/catalog.json` - Not yet implemented - coming in Phase 4 -### Q: How long does verification take? +### Q: How long does review take? -A: Typically 3-7 business days for initial review. Updates to verified extensions are usually faster. +A: Typically 3-7 business days. Updates to existing extensions are usually faster. ### Q: What if my extension is rejected? @@ -483,11 +287,11 @@ A: You'll receive feedback on what needs to be fixed. Make the changes and resub ### Q: Can I update my extension anytime? -A: Yes, submit a PR to update the catalog with your new version. Verified status may be re-evaluated for major changes. +A: Yes, file a new [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) issue with the updated version and download URL. Mention that it is an update to an existing entry. ### Q: Do I need to be verified to be in the catalog? -A: No, unverified extensions are still searchable. Verification just adds trust and visibility. +A: No. All community extensions are listed in the catalog once their submission is reviewed and accepted. ### Q: Can extensions have paid features? @@ -536,7 +340,7 @@ A: Extensions should be free and open-source. Commercial support/services are al "hooks": "integer (optional)" }, "tags": ["array of strings (2-10 tags)"], - "verified": "boolean (default: false)", + "verified": "boolean (default: false, set by maintainers)", "downloads": "integer (auto-updated)", "stars": "integer (auto-updated)", "created_at": "string (ISO 8601 datetime)", diff --git a/extensions/README.md b/extensions/README.md index f535ba539a..4dc9e64f5c 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -25,13 +25,13 @@ specify extension search # Now uses your organization's catalog instead of the ### Community Reference Catalog (`catalog.community.json`) > [!NOTE] -> Community extensions are independently created and maintained by their respective authors. GitHub and the Spec Kit maintainers may review pull requests that add entries to the community catalog for formatting, catalog structure, or policy compliance, but they do **not review, audit, endorse, or support the extension code itself**. Review extension source code before installation and use at your own discretion. +> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. Review extension source code before installation and use at your own discretion. - **Purpose**: Browse available community-contributed extensions - **Status**: Active - contains extensions submitted by the community - **Location**: `extensions/catalog.community.json` - **Usage**: Reference catalog for discovering available extensions -- **Submission**: Open to community contributions via Pull Request +- **Submission**: Open to community contributions via [issue template](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) **How It Works:** @@ -72,7 +72,7 @@ specify extension add --from https://github.com/org/spec-kit-ex ## Available Community Extensions > [!NOTE] -> Community extensions are independently created and maintained by their respective authors. GitHub and the Spec Kit maintainers may review pull requests that add entries to the community catalog for formatting, catalog structure, or policy compliance, but they do **not review, audit, endorse, or support the extension code itself**. The Community Extensions website is also a third-party resource. Review extension source code before installation and use at your own discretion. +> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. The Community Extensions website is also a third-party resource. Review extension source code before installation and use at your own discretion. 🔍 **Browse and search community extensions on the [Community Extensions website](https://speckit-community.github.io/extensions/).** @@ -89,10 +89,8 @@ To add your extension to the community catalog: 1. **Prepare your extension** following the [Extension Development Guide](EXTENSION-DEVELOPMENT-GUIDE.md) 2. **Create a GitHub release** for your extension -3. **Submit a Pull Request** that: - - Adds your extension to `extensions/catalog.community.json` - - Updates this README with your extension in the Available Extensions table -4. **Wait for review** - maintainers will review and merge if criteria are met +3. **File an issue** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template with all required metadata +4. **Wait for review** — a maintainer will review the submission, update the catalog, and close the issue See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed step-by-step instructions. diff --git a/presets/README.md b/presets/README.md index abaeb27067..29cce64248 100644 --- a/presets/README.md +++ b/presets/README.md @@ -98,7 +98,7 @@ Multiple composing presets chain recursively. For example, a security preset wit Presets are discovered through catalogs. By default, Spec Kit uses the official and community catalogs: > [!NOTE] -> Community presets are independently created and maintained by their respective authors. GitHub and the Spec Kit maintainers may review pull requests that add entries to the community catalog for formatting, catalog structure, or policy compliance, but they do **not review, audit, endorse, or support the preset code itself**. Review preset source code before installation and use at your own discretion. +> Community presets are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the preset code itself**. Review preset source code before installation and use at your own discretion. ```bash # List active catalogs