Skip to content

Commit ecd7ac4

Browse files
committed
feat: improve catalog submission templates and CODEOWNERS
Simplify the community catalog submission flow to use issue templates with manual maintainer review (no automation scripts or workflows). - Add explicit CODEOWNERS entries for catalog.community.json files so submissions are automatically assigned to a maintainer for review - Improve preset submission template: - Add 'Required Extensions' optional field - Make 'Templates Provided' optional (supports command-only presets) - Add 'Number of Scripts' optional field The existing extension and preset issue templates already collect all required catalog metadata. Maintainers review submissions and manually update the catalog JSON files. Closes #2400
1 parent 9483e5c commit ecd7ac4

9 files changed

Lines changed: 83 additions & 161 deletions

File tree

.github/CODEOWNERS

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
11
# Global code owner
22
* @mnriem
33

4+
# Community catalog files — explicit ownership for when global ownership expands
5+
/extensions/catalog.community.json @mnriem
6+
/integrations/catalog.community.json @mnriem
7+
/presets/catalog.community.json @mnriem
8+

.github/ISSUE_TEMPLATE/preset_submission.yml

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -95,17 +95,22 @@ body:
9595
validations:
9696
required: true
9797

98+
- type: input
99+
id: required-extensions
100+
attributes:
101+
label: Required Extensions (optional)
102+
description: Comma-separated list of required extension IDs (e.g., aide)
103+
placeholder: "e.g., aide, canon"
104+
98105
- type: textarea
99106
id: templates-provided
100107
attributes:
101-
label: Templates Provided
102-
description: List the template overrides your preset provides
108+
label: Templates Provided (optional)
109+
description: List the template overrides your preset provides (leave empty for command-only presets)
103110
placeholder: |
104111
- spec-template.md — adds compliance section
105112
- plan-template.md — includes audit checkpoints
106113
- checklist-template.md — HIPAA compliance checklist
107-
validations:
108-
required: true
109114
110115
- type: textarea
111116
id: commands-provided
@@ -115,6 +120,13 @@ body:
115120
placeholder: |
116121
- speckit.specify.md — customized for compliance workflows
117122
123+
- type: input
124+
id: scripts-count
125+
attributes:
126+
label: Number of Scripts (optional)
127+
description: How many scripts does your preset provide? (leave empty if none)
128+
placeholder: "e.g., 1"
129+
118130
- type: textarea
119131
id: tags
120132
attributes:
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: "Catalog: Auto-assign submission"
2+
3+
on:
4+
issues:
5+
types: [opened]
6+
7+
jobs:
8+
assign:
9+
if: >
10+
contains(github.event.issue.labels.*.name, 'extension-submission') ||
11+
contains(github.event.issue.labels.*.name, 'preset-submission')
12+
runs-on: ubuntu-latest
13+
permissions:
14+
issues: write
15+
steps:
16+
- uses: actions/github-script@v7
17+
with:
18+
script: |
19+
// Assign default maintainer and notify the team
20+
await github.rest.issues.addAssignees({
21+
owner: context.repo.owner,
22+
repo: context.repo.repo,
23+
issue_number: context.issue.number,
24+
assignees: ['mnriem'],
25+
});
26+
27+
await github.rest.issues.createComment({
28+
owner: context.repo.owner,
29+
repo: context.repo.repo,
30+
issue_number: context.issue.number,
31+
body: 'cc @github/spec-kit-maintainers — new catalog submission for review.',
32+
});

README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c
174174
## 🧩 Community Extensions
175175

176176
> [!NOTE]
177-
> 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.
177+
> 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.
178178
179179
🔍 **Browse and search community extensions on the [Community Extensions website](https://speckit-community.github.io/extensions/).**
180180

docs/community/presets.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Community Presets
22

33
> [!NOTE]
4-
> 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.
4+
> 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.
55
66
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):
77

extensions/EXTENSION-DEVELOPMENT-GUIDE.md

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -528,11 +528,9 @@ specify extension add <extension-name> --from https://github.com/.../spec-kit-my
528528

529529
Submit to the community catalog for public discovery:
530530

531-
1. **Fork** spec-kit repository
532-
2. **Add entry** to `extensions/catalog.community.json`
533-
3. **Update** the Community Extensions table in `README.md` with your extension
534-
4. **Create PR** following the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md)
535-
5. **After merge**, your extension becomes available:
531+
1. **Create a GitHub release** for your extension
532+
2. **File an issue** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template
533+
3. **After review**, a maintainer updates the catalog and your extension becomes available:
536534
- Users can browse `catalog.community.json` to discover your extension
537535
- Users copy the entry to their own `catalog.json`
538536
- Users install with: `specify extension add my-ext` (from their catalog)

extensions/EXTENSION-PUBLISHING-GUIDE.md

Lines changed: 19 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -133,156 +133,33 @@ specify extension add <extension-name> --from https://github.com/your-org/spec-k
133133

134134
Spec Kit uses a dual-catalog system. For details about how catalogs work, see the main [Extensions README](README.md#extension-catalogs).
135135

136-
**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`.
136+
**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`.
137137

138-
### 1. Fork the spec-kit Repository
138+
### How to Submit
139139

140-
```bash
141-
# Fork on GitHub
142-
# https://github.com/github/spec-kit/fork
143-
144-
# Clone your fork
145-
git clone https://github.com/YOUR-USERNAME/spec-kit.git
146-
cd spec-kit
147-
```
140+
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:
148141

149-
### 2. Add Extension to Community Catalog
142+
- Extension ID, name, and version
143+
- Description, author, and license
144+
- Repository, download URL, and documentation links
145+
- Required Spec Kit version and any tool dependencies
146+
- Number of commands and hooks
147+
- Tags and key features
148+
- Testing confirmation
150149

151-
Edit `extensions/catalog.community.json` and add your extension:
150+
> [!IMPORTANT]
151+
> Do **not** open a pull request directly to edit the catalog JSON. All community extension submissions must go through the issue template so a maintainer can review the metadata and update the catalog.
152152

153-
```json
154-
{
155-
"schema_version": "1.0",
156-
"updated_at": "2026-01-28T15:54:00Z",
157-
"catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
158-
"extensions": {
159-
"your-extension": {
160-
"name": "Your Extension Name",
161-
"id": "your-extension",
162-
"description": "Brief description of your extension",
163-
"author": "Your Name",
164-
"version": "1.0.0",
165-
"download_url": "https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip",
166-
"repository": "https://github.com/your-org/spec-kit-your-extension",
167-
"homepage": "https://github.com/your-org/spec-kit-your-extension",
168-
"documentation": "https://github.com/your-org/spec-kit-your-extension/blob/main/docs/",
169-
"changelog": "https://github.com/your-org/spec-kit-your-extension/blob/main/CHANGELOG.md",
170-
"license": "MIT",
171-
"requires": {
172-
"speckit_version": ">=0.1.0",
173-
"tools": [
174-
{
175-
"name": "required-mcp-tool",
176-
"version": ">=1.0.0",
177-
"required": true
178-
}
179-
]
180-
},
181-
"provides": {
182-
"commands": 3,
183-
"hooks": 1
184-
},
185-
"tags": [
186-
"category",
187-
"tool-name",
188-
"feature"
189-
],
190-
"verified": false,
191-
"downloads": 0,
192-
"stars": 0,
193-
"created_at": "2026-01-28T00:00:00Z",
194-
"updated_at": "2026-01-28T00:00:00Z"
195-
}
196-
}
197-
}
198-
```
199-
200-
**Important**:
201-
202-
- Set `verified: false` (maintainers will verify)
203-
- Set `downloads: 0` and `stars: 0` (auto-updated later)
204-
- Use current timestamp for `created_at` and `updated_at`
205-
- Update the top-level `updated_at` to current time
206-
207-
### 3. Update Community Extensions Table
208-
209-
Add your extension to the Community Extensions table in the project root `README.md`:
210-
211-
```markdown
212-
| Your Extension Name | Brief description of what it does | `<category>` | <effect> | [repo-name](https://github.com/your-org/spec-kit-your-extension) |
213-
```
153+
### What Happens After You Submit
214154

215-
**(Table) Category** — pick the one that best fits your extension:
155+
1. Your issue is automatically labeled and assigned to a maintainer for review
156+
2. A maintainer verifies that the metadata is complete and the download URL is accessible
157+
3. Once approved, the maintainer adds your extension to `extensions/catalog.community.json` and the Community Extensions table in the README
158+
4. Your extension becomes discoverable via `specify extension search`
216159

217-
- `docs` — reads, validates, or generates spec artifacts
218-
- `code` — reviews, validates, or modifies source code
219-
- `process` — orchestrates workflow across phases
220-
- `integration` — syncs with external platforms
221-
- `visibility` — reports on project health or progress
160+
### Updating an Existing Extension
222161

223-
**Effect** — choose one:
224-
225-
- Read-only — produces reports without modifying files
226-
- Read+Write — modifies files, creates artifacts, or updates specs
227-
228-
Insert your extension in alphabetical order in the table.
229-
230-
### 4. Submit Pull Request
231-
232-
```bash
233-
# Create a branch
234-
git checkout -b add-your-extension
235-
236-
# Commit your changes
237-
git add extensions/catalog.community.json README.md
238-
git commit -m "Add your-extension to community catalog
239-
240-
- Extension ID: your-extension
241-
- Version: 1.0.0
242-
- Author: Your Name
243-
- Description: Brief description
244-
"
245-
246-
# Push to your fork
247-
git push origin add-your-extension
248-
249-
# Create Pull Request on GitHub
250-
# https://github.com/github/spec-kit/compare
251-
```
252-
253-
**Pull Request Template**:
254-
255-
```markdown
256-
## Extension Submission
257-
258-
**Extension Name**: Your Extension Name
259-
**Extension ID**: your-extension
260-
**Version**: 1.0.0
261-
**Author**: Your Name
262-
**Repository**: https://github.com/your-org/spec-kit-your-extension
263-
264-
### Description
265-
Brief description of what your extension does.
266-
267-
### Checklist
268-
- [x] Valid extension.yml manifest
269-
- [x] README.md with installation and usage docs
270-
- [x] LICENSE file included
271-
- [x] GitHub release created (v1.0.0)
272-
- [x] Extension tested on real project
273-
- [x] All commands working
274-
- [x] No security vulnerabilities
275-
- [x] Added to extensions/catalog.community.json
276-
- [x] Added to Community Extensions table in README.md
277-
278-
### Testing
279-
Tested on:
280-
- macOS 13.0+ with spec-kit 0.1.0
281-
- Project: [Your test project]
282-
283-
### Additional Notes
284-
Any additional context or notes for reviewers.
285-
```
162+
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.
286163

287164
---
288165

extensions/README.md

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,13 @@ specify extension search # Now uses your organization's catalog instead of the
2525
### Community Reference Catalog (`catalog.community.json`)
2626

2727
> [!NOTE]
28-
> 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.
28+
> 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.
2929
3030
- **Purpose**: Browse available community-contributed extensions
3131
- **Status**: Active - contains extensions submitted by the community
3232
- **Location**: `extensions/catalog.community.json`
3333
- **Usage**: Reference catalog for discovering available extensions
34-
- **Submission**: Open to community contributions via Pull Request
34+
- **Submission**: Open to community contributions via [issue template](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml)
3535

3636
**How It Works:**
3737

@@ -72,7 +72,7 @@ specify extension add <extension-name> --from https://github.com/org/spec-kit-ex
7272
## Available Community Extensions
7373

7474
> [!NOTE]
75-
> 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.
75+
> 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.
7676
7777
🔍 **Browse and search community extensions on the [Community Extensions website](https://speckit-community.github.io/extensions/).**
7878

@@ -89,10 +89,8 @@ To add your extension to the community catalog:
8989

9090
1. **Prepare your extension** following the [Extension Development Guide](EXTENSION-DEVELOPMENT-GUIDE.md)
9191
2. **Create a GitHub release** for your extension
92-
3. **Submit a Pull Request** that:
93-
- Adds your extension to `extensions/catalog.community.json`
94-
- Updates this README with your extension in the Available Extensions table
95-
4. **Wait for review** - maintainers will review and merge if criteria are met
92+
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
93+
4. **Wait for review** — a maintainer will review the submission, update the catalog, and close the issue
9694

9795
See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed step-by-step instructions.
9896

presets/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ Multiple composing presets chain recursively. For example, a security preset wit
9898
Presets are discovered through catalogs. By default, Spec Kit uses the official and community catalogs:
9999

100100
> [!NOTE]
101-
> 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.
101+
> 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.
102102

103103
```bash
104104
# List active catalogs

0 commit comments

Comments
 (0)