ros/spec-kit
1
0
Fork 0
mirror of https://github.com/github/spec-kit.git synced 2026-03-16 18:33:07 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
5daaf23651f5f440eee5547625a9fc2f7d259e46
spec-kit/extensions
History
Copilot ee922cbde9 feat(extensions): support multiple active catalogs simultaneously (#1720) 
* Initial plan

* feat(extensions): implement multi-catalog stack support

- Add CatalogEntry dataclass to represent catalog entries
- Add get_active_catalogs() reading SPECKIT_CATALOG_URL, project config,
  user config, or built-in default stack (org-approved + community)
- Add _load_catalog_config() to parse .specify/extension-catalogs.yml
- Add _validate_catalog_url() HTTPS validation helper
- Add _fetch_single_catalog() with per-URL caching, backward-compat for DEFAULT_CATALOG_URL
- Add _get_merged_extensions() that merges all catalogs (priority wins on conflict)
- Update search() and get_extension_info() to use merged results
  annotated with _catalog_name and _install_allowed
- Update clear_cache() to also remove per-URL hash cache files
- Add extension_catalogs CLI command to list active catalogs
- Add catalog add/remove sub-commands for .specify/extension-catalogs.yml
- Update extension_add to enforce install_allowed=false policy
- Update extension_search to show source catalog per result
- Update extension_info to show source catalog with install_allowed status
- Add 13 new tests covering catalog stack, merge conflict resolution,
  install_allowed enforcement, and catalog metadata

Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

* docs: update RFC, user guide, and API reference for multi-catalog support

- RFC: replace FUTURE FEATURE section with full implementation docs,
  add catalog stack resolution order, config file examples, merge
  conflict resolution, and install_allowed behavior
- EXTENSION-USER-GUIDE.md: add multi-catalog section with CLI examples
  for catalogs/catalog-add/catalog-remove, update catalog config docs
- EXTENSION-API-REFERENCE.md: add CatalogEntry class docs, update
  ExtensionCatalog docs with new methods and result annotations,
  add catalog CLI commands (catalogs, catalog add, catalog remove)

Also fix extension_catalogs command to correctly show "Using built-in
default catalog stack" when config file exists but has empty catalogs

Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

* Potential fix for pull request finding 'Empty except'

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

* fix: remove extraneous f-string prefixes (ruff F541)

Remove f-prefix from strings with no placeholders in catalog_remove
and extension_search commands.

Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

* fix: address PR review feedback for multi-catalog support

- Rename 'org-approved' catalog to 'default'
- Move 'catalogs' command to 'catalog list' for consistency
- Add 'description' field to CatalogEntry dataclass
- Add --description option to 'catalog add' CLI command
- Align install_allowed default to False in _load_catalog_config
- Add user-level config detection in catalog list footer
- Fix _load_catalog_config docstring (document ValidationError)
- Fix test isolation for test_search_by_tag, test_search_by_query,
  test_search_verified_only, test_get_extension_info
- Update version to 0.1.14 and CHANGELOG
- Update all docs (RFC, User Guide, API Reference)

* fix: wrap _load_catalog_config() calls in catalog_list with try/except

- Check SPECKIT_CATALOG_URL first (matching get_active_catalogs() resolution order)
- Wrap both _load_catalog_config() calls in try/except ValidationError so a
  malformed config file cannot crash `specify extension catalog list` after
  the active catalogs have already been printed successfully

Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
2026-03-09 14:30:27 -05:00
..
template
Add modular extension system (#1551)
2026-02-10 14:27:20 -06:00
catalog.community.json
Add Understanding extension to community catalog (#1778)
2026-03-09 10:18:41 -05:00
catalog.json
Add modular extension system (#1551)
2026-02-10 14:27:20 -06:00
EXTENSION-API-REFERENCE.md
feat(extensions): support multiple active catalogs simultaneously (#1720)
2026-03-09 14:30:27 -05:00
EXTENSION-DEVELOPMENT-GUIDE.md
docs: Document dual-catalog system for extensions (#1689)
2026-02-25 14:38:56 -06:00
EXTENSION-PUBLISHING-GUIDE.md
docs: Document dual-catalog system for extensions (#1689)
2026-02-25 14:38:56 -06:00
EXTENSION-USER-GUIDE.md
feat(extensions): support multiple active catalogs simultaneously (#1720)
2026-03-09 14:30:27 -05:00
README.md
Add Understanding extension to community catalog (#1778)
2026-03-09 10:18:41 -05:00
RFC-EXTENSION-SYSTEM.md
feat(extensions): support multiple active catalogs simultaneously (#1720)
2026-03-09 14:30:27 -05:00

README.md

Spec Kit Extensions

Extension system for Spec Kit - add new functionality without bloating the core framework.

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:

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

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:

Extension Purpose URL
Azure DevOps Integration Sync user stories and tasks to Azure DevOps work items using OAuth authentication spec-kit-azure-devops
Cleanup Extension Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues, and generates analysis for large issues spec-kit-cleanup
Fleet Orchestrator Orchestrate a full feature lifecycle with human-in-the-loop gates across all SpecKit phases spec-kit-fleet
Jira Integration Create Jira Epics, Stories, and Issues from spec-kit specifications and task breakdowns with configurable hierarchy and custom field support spec-kit-jira
Ralph Loop Autonomous implementation loop using AI agent CLI spec-kit-ralph
Retrospective Extension Post-implementation retrospective with spec adherence scoring, drift analysis, and human-gated spec updates spec-kit-retrospective
Review Extension Post-implementation comprehensive code review with specialized agents for code quality, comments, tests, error handling, type design, and simplification spec-kit-review
Spec Sync Detect and resolve drift between specs and implementation. AI-assisted resolution with human approval spec-kit-sync
Understanding Automated requirements quality analysis — 31 deterministic metrics against IEEE/ISO standards with experimental energy-based ambiguity detection understanding
V-Model Extension Pack Enforces V-Model paired generation of development specs and test specs with full traceability spec-kit-v-model
Verify Extension Post-implementation quality gate that validates implemented code against specification artifacts spec-kit-verify

Adding Your Extension

Submission Process

To add your extension to the community catalog:

  1. Prepare your extension following the Extension Development Guide
  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 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:

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