Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

docs: Document dual-catalog system for extensions (#1689)

Manfred Riem56deda7be399
diff --git a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
index ff7a3aabe..f86beb62b 100644
--- a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
+++ b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
@@ -456,18 +456,20 @@ Users install with:
specify extension add --from https://github.com/.../spec-kit-my-ext-1.0.0.zip
```
-### Option 3: Extension Catalog (Future)
+### Option 3: Community Reference Catalog
-Submit to official catalog:
+Submit to the community catalog for public discovery:
1. **Fork** spec-kit repository
-2. **Add entry** to `extensions/catalog.json`
-3. **Create PR**
-4. **After merge**, users can install with:
-
- ```bash
- specify extension add my-ext # No URL needed!
- ```
+2. **Add entry** to `extensions/catalog.community.json`
+3. **Update** `extensions/README.md` with your extension
+4. **Create PR** following the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md)
+5. **After merge**, 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)
+
+See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed submission instructions.
---
diff --git a/extensions/EXTENSION-PUBLISHING-GUIDE.md b/extensions/EXTENSION-PUBLISHING-GUIDE.md
index 10eacbf90..39b744b2e 100644
--- a/extensions/EXTENSION-PUBLISHING-GUIDE.md
+++ b/extensions/EXTENSION-PUBLISHING-GUIDE.md
@@ -129,26 +129,32 @@ specify extension add --from https://github.com/your-org/spec-kit-your-extension
## Submit to Catalog
+### Understanding the Catalogs
+
+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`.
+
### 1. Fork the spec-kit Repository
```bash
# Fork on GitHub
-# https://github.com/statsperform/spec-kit/fork
+# 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 Catalog
+### 2. Add Extension to Community Catalog
-Edit `extensions/catalog.json` and add your extension:
+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/statsperform/spec-kit/main/extensions/catalog.json",
+ "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
"extensions": {
"your-extension": {
"name": "Your Extension Name",
@@ -198,15 +204,25 @@ Edit `extensions/catalog.json` and add your extension:
- Use current timestamp for `created_at` and `updated_at`
- Update the top-level `updated_at` to current time
-### 3. Submit Pull Request
+### 3. Update Extensions README
+
+Add your extension to the Available Extensions table in `extensions/README.md`:
+
+```markdown
+| Your Extension Name | Brief description of what it does | [repo-name](https://github.com/your-org/spec-kit-your-extension) |
+```
+
+Insert your extension in alphabetical order in the table.
+
+### 4. Submit Pull Request
```bash
# Create a branch
git checkout -b add-your-extension
# Commit your changes
-git add extensions/catalog.json
-git commit -m "Add your-extension to catalog
+git add extensions/catalog.community.json extensions/README.md
+git commit -m "Add your-extension to community catalog
- Extension ID: your-extension
- Version: 1.0.0
@@ -218,7 +234,7 @@ git commit -m "Add your-extension to catalog
git push origin add-your-extension
# Create Pull Request on GitHub
-# https://github.com/statsperform/spec-kit/compare
+# https://github.com/github/spec-kit/compare
```
**Pull Request Template**:
@@ -243,6 +259,8 @@ Brief description of what your extension does.
- [x] Extension tested on real project
- [x] All commands working
- [x] No security vulnerabilities
+- [x] Added to extensions/catalog.community.json
+- [x] Added to extensions/README.md Available Extensions table
### Testing
Tested on:
diff --git a/extensions/EXTENSION-USER-GUIDE.md b/extensions/EXTENSION-USER-GUIDE.md
index 802026231..f5b5befaf 100644
--- a/extensions/EXTENSION-USER-GUIDE.md
+++ b/extensions/EXTENSION-USER-GUIDE.md
@@ -76,13 +76,15 @@ vim .specify/extensions/jira/jira-config.yml
## Finding Extensions
+**Note**: By default, `specify extension search` uses your organization's catalog (`catalog.json`). If the catalog is empty, you won't see any results. See [Extension Catalogs](#extension-catalogs) to learn how to populate your catalog from the community reference catalog.
+
### Browse All Extensions
```bash
specify extension search
```
-Shows all available extensions in the catalog.
+Shows all extensions in your organization's catalog.
### Search by Keyword
@@ -415,11 +417,15 @@ export SPECKIT_CATALOG_URL="https://example.com/staging/catalog.json"
---
+## Extension Catalogs
+
+For information about how Spec Kit's dual-catalog system works (`catalog.json` vs `catalog.community.json`), see the main [Extensions README](README.md#extension-catalogs).
+
## Organization Catalog Customization
-### Why the Default Catalog is Empty
+### Why Customize Your Catalog
-The default spec-kit catalog ships empty by design. This allows organizations to:
+Organizations customize their `catalog.json` to:
- **Control available extensions** - Curate which extensions your team can install
- **Host private extensions** - Internal tools that shouldn't be public
diff --git a/extensions/README.md b/extensions/README.md
index 0be853a40..574144a4d 100644
--- a/extensions/README.md
+++ b/extensions/README.md
@@ -1,8 +1,74 @@
-# Spec Kit Community Extensions
+# Spec Kit Extensions
-Community-contributed extensions for [Spec Kit](https://github.com/github/spec-kit).
+Extension system for [Spec Kit](https://github.com/github/spec-kit) - add new functionality without bloating the core framework.
-## Available Extensions
+## Extension Catalogs
+
+Spec Kit provides two catalog files with different purposes:
+
+### Your Catalog (`catalog.json`)
+
+- **Purpose**: Default upstream catalog of extensions used by the Spec Kit CLI
+- **Default State**: Empty by design in the upstream project - you or your organization populate a fork/copy with extensions you trust
+- **Location (upstream)**: `extensions/catalog.json` in the GitHub-hosted spec-kit repo
+- **CLI Default**: The `specify extension` commands use the upstream catalog URL by default, unless overridden
+- **Org Catalog**: Point `SPECKIT_CATALOG_URL` at your organization's fork or hosted catalog JSON to use it instead of the upstream default
+- **Customization**: Copy entries from the community catalog into your org catalog, or add your own extensions directly
+
+**Example override:**
+```bash
+# Override the default upstream catalog with your organization's catalog
+export SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json"
+specify extension search # Now uses your organization's catalog instead of the upstream default
+```
+
+### Community Reference Catalog (`catalog.community.json`)
+
+- **Purpose**: Browse available community-contributed extensions
+- **Status**: Active - contains extensions submitted by the community
+- **Location**: `extensions/catalog.community.json`
+- **Usage**: Reference catalog for discovering available extensions
+- **Submission**: Open to community contributions via Pull Request
+
+**How It Works:**
+
+## Making Extensions Available
+
+You control which extensions your team can discover and install:
+
+### Option 1: Curated Catalog (Recommended for Organizations)
+
+Populate your `catalog.json` with approved extensions:
+
+1. **Discover** extensions from various sources:
+ - Browse `catalog.community.json` for community extensions
+ - Find private/internal extensions in your organization's repos
+ - Discover extensions from trusted third parties
+2. **Review** extensions and choose which ones you want to make available
+3. **Add** those extension entries to your own `catalog.json`
+4. **Team members** can now discover and install them:
+ - `specify extension search` shows your curated catalog
+ - `specify extension add <name>` installs from your catalog
+
+**Benefits**: Full control over available extensions, team consistency, organizational approval workflow
+
+**Example**: Copy an entry from `catalog.community.json` to your `catalog.json`, then your team can discover and install it by name.
+
+### Option 2: Direct URLs (For Ad-hoc Use)
+
+Skip catalog curation - team members install directly using URLs:
+
+```bash
+specify extension add --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip
+```
+
+**Benefits**: Quick for one-off testing or private extensions
+
+**Tradeoff**: Extensions installed this way won't appear in `specify extension search` for other team members unless you also add them to your `catalog.json`.
+
+## Available Community Extensions
+
+The following community-contributed extensions are available in [`catalog.community.json`](catalog.community.json):
| Extension | Purpose | URL |
|-----------|---------|-----|
@@ -11,4 +77,43 @@ Community-contributed extensions for [Spec Kit](https://github.com/github/spec-k
## Adding Your Extension
-See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for instructions on how to submit your extension to the community catalog.
+### Submission Process
+
+To add your extension to the community catalog:
+
+1. **Prepare your extension** following the [Extension Development Guide](EXTENSION-DEVELOPMENT-GUIDE.md)
+2. **Create a GitHub release** for your extension
+3. **Submit a Pull Request** that:
+ - Adds your extension to `extensions/catalog.community.json`
+ - Updates this README with your extension in the Available Extensions table
+4. **Wait for review** - maintainers will review and merge if criteria are met
+
+See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed step-by-step instructions.
+
+### Submission Checklist
+
+Before submitting, ensure:
+
+- βœ… Valid `extension.yml` manifest
+- βœ… Complete README with installation and usage instructions
+- βœ… LICENSE file included
+- βœ… GitHub release created with semantic version (e.g., v1.0.0)
+- βœ… Extension tested on a real project
+- βœ… All commands working as documented
+
+## Installing Extensions
+Once extensions are available (either in your catalog or via direct URL), install them:
+
+```bash
+# From your curated catalog (by name)
+specify extension search # See what's in your catalog
+specify extension add <extension-name> # Install by name
+
+# Direct from URL (bypasses catalog)
+specify extension add --from https://github.com/<org>/<repo>/archive/refs/tags/<version>.zip
+
+# List installed extensions
+specify extension list
+```
+
+For more information, see the [Extension User Guide](EXTENSION-USER-GUIDE.md).
diff --git a/extensions/RFC-EXTENSION-SYSTEM.md b/extensions/RFC-EXTENSION-SYSTEM.md
index 3bfa0ea06..248e6275a 100644
--- a/extensions/RFC-EXTENSION-SYSTEM.md
+++ b/extensions/RFC-EXTENSION-SYSTEM.md
@@ -858,11 +858,41 @@ def should_execute_hook(hook: dict, config: dict) -> bool:
## Extension Discovery & Catalog
-### Central Catalog
+### Dual Catalog System
+
+Spec Kit uses two catalog files with different purposes:
+
+#### User Catalog (`catalog.json`)
**URL**: `https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json`
-**Format**:
+- **Purpose**: Organization's curated catalog of approved extensions
+- **Default State**: Empty by design - users populate with extensions they trust
+- **Usage**: Default catalog used by `specify extension` CLI commands
+- **Control**: Organizations maintain their own fork/version for their teams
+
+#### Community Reference Catalog (`catalog.community.json`)
+
+**URL**: `https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json`
+
+- **Purpose**: Reference catalog of available community-contributed extensions
+- **Verification**: Community extensions may have `verified: false` initially
+- **Status**: Active - open for community contributions
+- **Submission**: Via Pull Request following the Extension Publishing Guide
+- **Usage**: Browse to discover extensions, then copy to your `catalog.json`
+
+**How It Works:**
+
+1. **Discover**: Browse `catalog.community.json` to find available extensions
+2. **Review**: Evaluate extensions for security, quality, and organizational fit
+3. **Curate**: Copy approved extension entries from community catalog to your `catalog.json`
+4. **Install**: Use `specify extension add <name>` (pulls from your curated catalog)
+
+This approach gives organizations full control over which extensions are available to their teams while maintaining a shared community resource for discovery.
+
+### Catalog Format
+
+**Format** (same for both catalogs):
```json
{
@@ -931,25 +961,52 @@ specify extension info jira
### Custom Catalogs
-Organizations can host private catalogs:
+**⚠️ FUTURE FEATURE - NOT YET IMPLEMENTED**
+
+The following catalog management commands are proposed design concepts but are not yet available in the current implementation:
```bash
-# Add custom catalog
+# Add custom catalog (FUTURE - NOT AVAILABLE)
specify extension add-catalog https://internal.company.com/spec-kit/catalog.json
-# Set as default
+# Set as default (FUTURE - NOT AVAILABLE)
specify extension set-catalog --default https://internal.company.com/spec-kit/catalog.json
-# List catalogs
+# List catalogs (FUTURE - NOT AVAILABLE)
specify extension catalogs
```
-**Catalog priority**:
+**Proposed catalog priority** (future design):
-1. Project-specific catalog (`.specify/extension-catalogs.yml`)
-2. User-level catalog (`~/.specify/extension-catalogs.yml`)
+1. Project-specific catalog (`.specify/extension-catalogs.yml`) - *not implemented*
+2. User-level catalog (`~/.specify/extension-catalogs.yml`) - *not implemented*
3. Default GitHub catalog
+#### Current Implementation: SPECKIT_CATALOG_URL
+
+**The currently available method** for using custom catalogs is the `SPECKIT_CATALOG_URL` environment variable:
+
+```bash
+# Point to your organization's catalog
+export SPECKIT_CATALOG_URL="https://internal.company.com/spec-kit/catalog.json"
+
+# All extension commands now use your custom catalog
+specify extension search # Uses custom catalog
+specify extension add jira # Installs from custom catalog
+```
+
+**Requirements:**
+- URL must use HTTPS (HTTP only allowed for localhost testing)
+- Catalog must follow the standard catalog.json schema
+- Must be publicly accessible or accessible within your network
+
+**Example for testing:**
+```bash
+# Test with localhost during development
+export SPECKIT_CATALOG_URL="http://localhost:8000/catalog.json"
+specify extension search
+```
+
---
## CLI Commands