π« 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.mdindex 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.mdindex 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 forkgit clone https://github.com/YOUR-USERNAME/spec-kit.gitcd 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 branchgit 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 cataloggit 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### TestingTested on:diff --git a/extensions/EXTENSION-USER-GUIDE.md b/extensions/EXTENSION-USER-GUIDE.mdindex 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```bashspecify 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 publicdiff --git a/extensions/README.md b/extensions/README.mdindex 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.mdindex 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