add-community-extension

Add Community Extension

Process an extension submission issue and add or update it in the community catalog.

When to Use

• A new [Extension] submission issue is filed
• An existing extension submits an update issue (new version, changed metadata)
• You need to add or update a community extension in extensions/catalog.community.json and docs/community/extensions.md

Procedure

1. Fetch the submission issue

Read the GitHub issue to extract all metadata:

• Extension ID, name, version, description, author
• Repository URL, download URL, homepage, documentation, changelog
• License, required spec-kit version, optional tool dependencies
• Number of commands and hooks
• Tags

2. Validate against publishing rules

Check all of the following (per extensions/EXTENSION-PUBLISHING-GUIDE.md):

3. Determine if this is an add or update

Search extensions/catalog.community.json for the extension ID.

• Not found → this is a new addition. Proceed to step 4.
• Found → this is an update. Proceed to step 4 but replace the existing entry in-place instead of inserting.

4. Add or update extensions/catalog.community.json

New extension: Insert the entry in alphabetical order by extension ID.

Update: Replace the existing entry in-place. Update only the fields that changed (typically version, download_url, description, provides, requires, tags, updated_at). Preserve created_at and downloads/stars from the existing entry.

Use the existing entries as the format template. Required fields:

{
  "<id>": {
    "name": "<name>",
    "id": "<id>"

Category — free-form string; common values: docs, code, process, integration, visibility Effect — one of: read-only, read-write

If the extension has optional tool dependencies, add a "tools" array inside "requires":

Also update the top-level "updated_at" timestamp in the catalog.

After editing, validate the JSON by running:

5. Add or update docs/community/extensions.md community extensions table

New extension: Insert a new row into the # Community Extensions table in alphabetical order by extension name.

Update: Find the existing row and update the description or other changed fields in-place.

Determine the category and effect from the extension's behavior:

Category — free-form; common values: docs, code, process, integration, visibility Effect — write canonical values read-only or read-write in extension.yml and catalog.community.json; use Read-only/Read+Write only for the docs table display

6. Commit, push, and open PR

Use add- for new extensions, update- for updates:

Then create a PR to upstream (github/spec-kit) with:

• Title: Add <Name> extension to community catalog (or Update <Name> extension to v<version>)
• Body: Include validation summary, Closes #<issue-number>, and cc @<issue-author>
• Head: <fork-owner>:<branch-name>
• Base: main

Common Pitfalls

• Alphabetical order matters — entries must be sorted by ID in the JSON and by name in the docs table.
• Don't forget the catalog updated_at — the top-level timestamp in catalog.community.json must be refreshed.
• Validate JSON after editing — a trailing comma or missing brace will break the catalog.
• Use Closes not Fixes — Closes #N is the correct keyword for submission issues.
• Match the proposed entry but verify — the issue may include a proposed JSON block, but always validate field values against the actual repository state.
• Preserve created_at on updates — keep the original created_at value; only change updated_at.
• Preserve downloads and stars on updates — these reflect usage metrics and must not be reset.