add-community-extension

name add-community-extension description Add a community extension to the Spec Kit catalog from a GitHub issue submission. USE FOR: processing extension submission issues, validating catalog entries, updating catalog.community.json and docs/community/extensions.md, creating PRs. DO NOT USE FOR: creating new extensions from scratch, or first-party extension work. argument-hint GitHub issue URL or number for the extension submission 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.