From 74873d92f7fa0d080bb3775823f96c1d32f73c3f Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Wed, 25 Feb 2026 12:54:00 -0600 Subject: [PATCH 1/4] docs: Document dual-catalog system for extensions - Clarify distinction between catalog.json (curated) and catalog.community.json (reference) - Update EXTENSION-DEVELOPMENT-GUIDE.md to explain community catalog submission - Update EXTENSION-PUBLISHING-GUIDE.md with dual-catalog workflow - Update EXTENSION-USER-GUIDE.md with catalog selection guidance - Expand README.md with comprehensive catalog explanation - Update RFC-EXTENSION-SYSTEM.md with dual-catalog design and current implementation - Change GitHub references from statsperform to github - Add SPECKIT_CATALOG_URL environment variable documentation This clarifies how organizations can curate their own catalog while browsing community-contributed extensions for discovery. --- extensions/EXTENSION-DEVELOPMENT-GUIDE.md | 20 ++-- extensions/EXTENSION-PUBLISHING-GUIDE.md | 34 +++++-- extensions/EXTENSION-USER-GUIDE.md | 12 ++- extensions/README.md | 113 +++++++++++++++++++++- extensions/RFC-EXTENSION-SYSTEM.md | 75 ++++++++++++-- 5 files changed, 221 insertions(+), 33 deletions(-) diff --git a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md index ff7a3aabe5..f86beb62bb 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 10eacbf909..39b744b2e1 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 802026231f..f5b5befaf5 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 0be853a40b..aad931d60a 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**: Your organization's curated catalog of approved extensions +- **Default State**: Empty by design - you populate it with extensions you trust +- **Location**: `extensions/catalog.json` in the spec-kit repo +- **Usage**: The `specify extension` commands use this catalog by default +- **Override**: Set `SPECKIT_CATALOG_URL` environment variable to use a different catalog +- **Customization**: Copy extensions from the community catalog or add your own + +**Example override:** +```bash +# Point to your organization's catalog +export SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json" +specify extension search # Now uses your custom catalog +``` + +### 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 ` 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 # Install by name + +# Direct from URL (bypasses catalog) +specify extension add --from https://github.com///archive/refs/tags/.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 3bfa0ea060..248e6275aa 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 ` (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 From 8ab82e381c1c82e492b16d90c1cf31d0a9639644 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Wed, 25 Feb 2026 13:58:57 -0600 Subject: [PATCH 2/4] Update extensions/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- extensions/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/extensions/README.md b/extensions/README.md index aad931d60a..1f1e6de409 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -8,18 +8,18 @@ Spec Kit provides two catalog files with different purposes: ### Your Catalog (`catalog.json`) -- **Purpose**: Your organization's curated catalog of approved extensions -- **Default State**: Empty by design - you populate it with extensions you trust -- **Location**: `extensions/catalog.json` in the spec-kit repo -- **Usage**: The `specify extension` commands use this catalog by default -- **Override**: Set `SPECKIT_CATALOG_URL` environment variable to use a different catalog -- **Customization**: Copy extensions from the community catalog or add your own +- **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 -# Point to your organization's catalog +# 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 custom catalog +specify extension search # Now uses your organization's catalog instead of the upstream default ``` ### Community Reference Catalog (`catalog.community.json`) From f9a1fa18396958e40fe5048f06a4f77dc298ecc6 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Wed, 25 Feb 2026 14:00:39 -0600 Subject: [PATCH 3/4] Update extensions/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- extensions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/README.md b/extensions/README.md index 1f1e6de409..68baa2b697 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -100,7 +100,7 @@ Before submitting, ensure: - ✅ GitHub release created with semantic version (e.g., v1.0.0) - ✅ Extension tested on a real project - ✅ All commands working as documented -- ✅Installing Extensions +- ✅ Installing extensions Once extensions are available (either in your catalog or via direct URL), install them: From 00ad7271ad2dcedeeae8bde2e1d4c72e98529d59 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Wed, 25 Feb 2026 14:37:30 -0600 Subject: [PATCH 4/4] Update extensions/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- extensions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/README.md b/extensions/README.md index 68baa2b697..574144a4d1 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -100,8 +100,8 @@ Before submitting, ensure: - ✅ GitHub release created with semantic version (e.g., v1.0.0) - ✅ Extension tested on a real project - ✅ All commands working as documented -- ✅ Installing extensions +## Installing Extensions Once extensions are available (either in your catalog or via direct URL), install them: ```bash