Add Community ExtensionSAFE

💫 Toolkit to help you get started with SDD or any other process!

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

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

```json
{
  "<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"`:

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

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

After editing, **validate the JSON** by running:

```bash
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:

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

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

```bash
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 

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Add Community Extension](https://modelsatlas.com/skills/github/add-community-extension/badge.svg)](https://modelsatlas.com/skills/github/add-community-extension/)

Not your listing, or something out of date? Claim or update your listing.