feat: improve catalog submission templates and CODEOWNERS

mnriem · mnriem · commit ef7ebb193aa1 · 2026-05-05T15:45:20.000-05:00
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
diff --git 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
@@ -95,17 +95,27 @@ 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: markdown
+    attributes:
+      value: |
+        **At least one** of Templates Provided or Commands Provided must be filled in.
+
   - type: textarea
     id: templates-provided
     attributes:
-      label: Templates Provided
-      description: List the template overrides your preset provides
+      label: Templates Provided (optional)
+      description: List the template overrides your preset provides (leave empty for command-only presets)
       placeholder: |
         - spec-template.md — adds compliance section
         - plan-template.md — includes audit checkpoints
         - checklist-template.md — HIPAA compliance checklist
-    validations:
-      required: true
 
   - type: textarea
     id: commands-provided
@@ -115,6 +125,13 @@ body:
       placeholder: |
         - speckit.specify.md — customized for compliance workflows
 
+  - 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
     attributes:
diff --git a/.github/workflows/catalog-assign.yml b/.github/workflows/catalog-assign.yml
@@ -0,0 +1,32 @@
+name: "Catalog: Auto-assign submission"
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  assign:
+    if: >
+      contains(github.event.issue.labels.*.name, 'extension-submission') ||
+      contains(github.event.issue.labels.*.name, 'preset-submission')
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            // Assign default maintainer and notify the team
+            await github.rest.issues.addAssignees({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              assignees: ['mnriem'],
+            });
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: 'cc @github/spec-kit-maintainers — new catalog submission for review.',
+            });
diff --git 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
@@ -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
@@ -528,11 +528,9 @@ specify extension add <extension-name> --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
@@ -133,222 +133,46 @@ specify extension add <extension-name> --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 | `<category>` | <effect> | [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 +209,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.
 
 ---
 
diff --git a/extensions/README.md b/extensions/README.md
diff --git a/presets/README.md b/presets/README.md
