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):

Check	How
Repository exists and is public	Fetch the repository URL
extension.yml manifest present	Confirm in repo file listing
README.md present	Confirm in repo file listing
LICENSE file present	Confirm in repo file listing
GitHub release exists matching version	Check releases on the repo page
Download URL is accessible	Verify it follows archive/refs/tags/vX.Y.Z.zip pattern and release exists
Extension ID is lowercase-with-hyphens only	Regex: ^[a-z][a-z0-9-]*$
Version follows semver	Format: X.Y.Z
Submission checklists are all checked	Confirm in issue body

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>",
    "description": "<description>",
    "author": "<author>",
    "version": "<version>",
    "download_url": "<download_url>",
    "repository": "<repository>",
    "homepage": "<homepage>",
    "documentation": "<documentation>",
    "changelog": "<changelog>",
    "license": "<license>",
    "category": "<category>",
    "effect": "<effect>",
    "requires": {
      "speckit_version": "<speckit_version>"
    },
    "provides": {
      "commands": <N>,
      "hooks": <N>
    },
    "tags": ["<tag1>", "<tag2>"],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "<today>T00:00:00Z",
    "updated_at": "<today>T00:00:00Z"
  }
}

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":

"tools": [{ "name": "<tool>", "required": false }]

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

After editing, validate the JSON by running:

python3 -c "import json; json.load(open('extensions/catalog.community.json')); print('Valid JSON')"

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:

| <Name> | <Description> | `<category>` | <Effect> | [<repo-name>](<repository-url>) |

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:

# New extension
git checkout -b add-<extension-id>-extension

# Update
git checkout -b update-<extension-id>-extension

git add extensions/catalog.community.json docs/community/extensions.md

# New extension
git commit -m "Add <Name> extension to community catalog

Add <id> extension submitted by @<issue-author> to:
- extensions/catalog.community.json (alphabetical order)
- docs/community/extensions.md community extensions table

Closes #<issue-number>"

# Update
git commit -m "Update <Name> extension to v<version>

Update <id> extension submitted by @<issue-author>:
- extensions/catalog.community.json (version, download_url, etc.)
- docs/community/extensions.md community extensions table

Closes #<issue-number>"

git push origin <branch-name>

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.