docs: Document dual-catalog system for extensions by mnriem · Pull Request #1689 · github/spec-kit

mnriem · 2026-02-25T18:56:36Z

Description

This PR documents the dual-catalog system for Spec Kit extensions, clarifying the distinction between catalog.json (curated) and catalog.community.json (reference).

Closes #1687

Changes

Documentation Updates

EXTENSION-DEVELOPMENT-GUIDE.md
- Changed "Option 3: Extension Catalog (Future)" to "Option 3: Community Reference Catalog"
- Clarified submission process to catalog.community.json
- Added discovery-review-curate workflow explanation
EXTENSION-PUBLISHING-GUIDE.md
- Added "Understanding the Catalogs" section explaining dual-catalog system
- Changed submission target from catalog.json to catalog.community.json
- Added step to update extensions/README.md
- Updated GitHub references (statsperform → github)
- Enhanced PR checklist with new requirements
EXTENSION-USER-GUIDE.md
- Added note about default catalog.json being empty
- Changed "Why the Default Catalog is Empty" to "Why Customize Your Catalog"
- Added reference to Extension Catalogs section
README.md
- Expanded from brief intro to comprehensive guide
- Added "Extension Catalogs" section explaining both catalog types
- Added "Making Extensions Available" with two options (curated vs direct URLs)
- Added "Installing Extensions" section
- Reorganized content for better flow
RFC-EXTENSION-SYSTEM.md
- Changed "Central Catalog" to "Dual Catalog System"
- Added detailed explanation of both catalog purposes
- Marked future catalog management commands as not yet implemented
- Added "Current Implementation: SPECKIT_CATALOG_URL" section with examples

Impact

Users: Clearer guidance on extension discovery and installation
Publishers: Better understanding of submission process
Organizations: Clear instructions for curating their own catalogs

Testing

All documentation changes reviewed for consistency
Links and references verified
Examples confirmed accurate
GitHub organization references updated

Type of Change

Documentation update
Bug fix
New feature
Breaking change

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

Copilot

Pull request overview

This PR updates Spec Kit’s extension documentation to clearly explain the dual-catalog model: an empty-by-default curated catalog.json used by the CLI, and a community reference catalog.community.json intended for discovery.

Changes:

Documented the curated vs community catalog split and the discover → review → curate workflow across extension docs.
Updated publishing/development guidance to submit to catalog.community.json and keep extensions/README.md in sync.
Expanded RFC and user docs with current catalog override behavior via SPECKIT_CATALOG_URL and marked proposed catalog-management commands as future.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
extensions/RFC-EXTENSION-SYSTEM.md	Documents the dual-catalog design and clarifies current vs future catalog configuration mechanisms.
extensions/README.md	Introduces an “Extension Catalogs” overview and new guidance for making extensions available/installed.
extensions/EXTENSION-USER-GUIDE.md	Adds guidance and pointers to the catalog model and customization flow.
extensions/EXTENSION-PUBLISHING-GUIDE.md	Updates publisher workflow to target `catalog.community.json` and adds README/table update requirements.
extensions/EXTENSION-DEVELOPMENT-GUIDE.md	Updates development guidance to reflect community catalog submission and curation flow.

Comments suppressed due to low confidence (1)

extensions/EXTENSION-USER-GUIDE.md:87

"Shows all extensions in your organization's catalog" is misleading with the current defaults (the default catalog URL is the upstream GitHub catalog.json, which is empty by design). Please align this sentence with the actual default behavior and/or mention SPECKIT_CATALOG_URL as the mechanism to use an organization-managed catalog.

Shows all extensions in your organization's catalog.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

extensions/README.md

extensions/EXTENSION-USER-GUIDE.md

extensions/RFC-EXTENSION-SYSTEM.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

extensions/README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-25T20:41:20Z

extensions/README.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


The text refers to "Available Extensions table" but the actual section title on line 69 is "Available Community Extensions". For clarity and consistency, consider updating this to "Available Community Extensions table".

Suggested change

- Updates this README with your extension in the Available Extensions table

- Updates this README with your extension in the Available Community Extensions table

Copilot · 2026-02-25T20:41:20Z

extensions/RFC-EXTENSION-SYSTEM.md

+
+Spec Kit uses two catalog files with different purposes:
+
+#### User Catalog (`catalog.json`)


The section title "User Catalog" in RFC-EXTENSION-SYSTEM.md (line 865) is inconsistent with "Your Catalog" used in README.md (line 9) for the same catalog.json file. Consider using consistent terminology across both documents. Recommend "Your Catalog" as it's clearer for organizational use.

Suggested change

#### User Catalog (`catalog.json`)

#### Your Catalog (`catalog.json`)

Copilot · 2026-02-25T20:41:20Z

extensions/EXTENSION-PUBLISHING-GUIDE.md

 - [x] All commands working
 - [x] No security vulnerabilities
+- [x] Added to extensions/catalog.community.json
+- [x] Added to extensions/README.md Available Extensions table


The checklist item refers to "Available Extensions table" but the actual section title in README.md is "Available Community Extensions" (line 69). For clarity and consistency, consider updating this to "Available Community Extensions table".

Suggested change

- [x] Added to extensions/README.md Available Extensions table

- [x] Added to extensions/README.md Available Community Extensions table

* 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. * Update extensions/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update extensions/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update extensions/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 25, 2026 18:56

Copilot started reviewing on behalf of mnriem February 25, 2026 18:57 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

Update extensions/README.md

8ab82e3

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 25, 2026 19:58

Copilot started reviewing on behalf of mnriem February 25, 2026 19:59 View session

Update extensions/README.md

f9a1fa1

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Feb 25, 2026

View reviewed changes

extensions/README.md Outdated Show resolved Hide resolved

extensions/README.md Show resolved Hide resolved

Update extensions/README.md

00ad727

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 25, 2026 20:37

Copilot started reviewing on behalf of mnriem February 25, 2026 20:38 View session

mnriem merged commit 56deda7 into github:main Feb 25, 2026
10 checks passed

mnriem deleted the docs/extension-dual-catalog-system branch February 25, 2026 20:39

Copilot AI reviewed Feb 25, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Document dual-catalog system for extensions#1689

docs: Document dual-catalog system for extensions#1689
mnriem merged 4 commits intogithub:mainfrom
mnriem:docs/extension-dual-catalog-system

mnriem commented Feb 25, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 25, 2026

Uh oh!

Copilot AI Feb 25, 2026

Uh oh!

Copilot AI Feb 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- Updates this README with your extension in the Available Extensions table
	- Updates this README with your extension in the Available Community Extensions table


		Spec Kit uses two catalog files with different purposes:

		#### User Catalog (`catalog.json`)

	#### User Catalog (`catalog.json`)
	#### Your Catalog (`catalog.json`)

	- [x] Added to extensions/README.md Available Extensions table
	- [x] Added to extensions/README.md Available Community Extensions table

Conversation

mnriem commented Feb 25, 2026

Description

Changes

Documentation Updates

Impact

Testing

Type of Change

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants