ros/spec-kit
1
0
Fork 0
mirror of https://github.com/github/spec-kit.git synced 2026-03-18 03:13:07 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
a177a1a6d1493cd72adb7c0354a8e3a05453daf5
spec-kit/extensions
History
Michal Bachorik d2ecf6560d feat(extensions,presets): add priority-based resolution ordering (#1855) 
* feat(extensions,presets): add priority-based resolution ordering

Add priority field to extension and preset registries for deterministic
template resolution when multiple sources provide the same template.

Extensions:
- Add `list_by_priority()` method to ExtensionRegistry
- Add `--priority` option to `extension add` command
- Add `extension set-priority` command
- Show priority in `extension list` and `extension info`
- Preserve priority during `extension update`
- Update RFC documentation

Presets:
- Add `preset set-priority` command
- Show priority in `preset info` output
- Use priority ordering in PresetResolver for extensions

Both systems:
- Lower priority number = higher precedence (default: 10)
- Backwards compatible with legacy entries (missing priority defaults to 10)
- Comprehensive test coverage including backwards compatibility

Closes #1845
Closes #1854

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: address code review feedback

- list_by_priority(): add secondary sort by ID for deterministic ordering,
  return deep copies to prevent mutation
- install_from_directory/zip: validate priority >= 1 early
- extension add CLI: validate --priority >= 1 before install
- PresetRegistry.update(): preserve installed_at timestamp
- Test assertions: use exact source string instead of substring match

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: address additional review feedback

- PresetResolver: add fallback to directory scanning when registry is
  empty/corrupted for robustness and backwards compatibility
- PresetRegistry.update(): add guard to prevent injecting installed_at
  when absent in existing entry (mirrors ExtensionRegistry behavior)
- RFC: update extension list example to match actual CLI output format

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: restore defensive code and RFC descriptions lost in rebase

- Restore defensive code in list_by_priority() with .get() and isinstance check
- Restore detailed --from URL and --dev option descriptions in RFC

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: add defensive code to presets list_by_priority()

- Add .get() and isinstance check for corrupted/empty registry
- Move copy import to module level (remove local import)
- Matches defensive pattern used in extensions.py

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: address reviewer feedback on priority resolution

- Rename _normalize_priority to normalize_priority (public API)
- Add comprehensive tests for normalize_priority function (9 tests)
- Filter non-dict metadata entries in list_by_priority() methods
- Fix extension priority resolution to merge registered and unregistered
  extensions into unified sorted list (unregistered get implicit priority 10)
- Add tests for extension priority resolution ordering (4 tests)

The key fix ensures unregistered extensions with implicit priority 10
correctly beat registered extensions with priority > 10, and vice versa.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: DRY refactor and strengthen test assertions

- Extract _get_all_extensions_by_priority() helper in PresetResolver
  to eliminate duplicated extension list construction
- Add priority=10 assertion to test_legacy_extension_without_priority_field
- Add priority=10 assertion to test_legacy_preset_without_priority_field

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: add isinstance(dict) checks for corrupted registry entries

Add defensive checks throughout CLI commands and manager methods
to handle cases where registry entries may be corrupted (non-dict
values). This prevents AttributeError when calling .get() on
non-dict metadata.

Locations fixed:
- __init__.py: preset/extension info, set-priority, enable/disable,
  upgrade commands
- extensions.py: list_installed()
- presets.py: list_installed()

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: normalize priority display to match resolution behavior

Use normalize_priority() for all priority display in CLI commands
to ensure displayed values match actual resolution behavior when
registry data is corrupted/hand-edited.

Locations fixed:
- extensions.py: list_installed()
- presets.py: list_installed(), PresetResolver
- __init__.py: preset info, extension info, set-priority commands

Also added GraphQL query for unresolved PR comments to CLAUDE.md.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: repair corrupted priority values in set-priority commands

Changed set-priority commands to check if the raw stored value is
already a valid int equal to the requested priority before skipping.
This ensures corrupted values (e.g., "high") get repaired even when
setting to the default priority (10).

Also removed CLAUDE.md that was accidentally added to the repo.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: harden registry update methods against corrupted entries

- Normalize priority when restoring during extension update to prevent
  propagating corrupted values (e.g., "high", 0, negative)
- Add isinstance(dict) checks in ExtensionRegistry.update() and
  PresetRegistry.update() to handle corrupted entries (string/list)
  that would cause TypeError on merge

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: use safe fallback for version in list_installed()

When registry entry is corrupted (non-dict), metadata becomes {} after
the isinstance check. Use metadata.get("version", manifest.version)
instead of metadata["version"] to avoid KeyError.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: iamaeroplane <michal.bachorik@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-03-17 09:44:34 -05:00
..
selftest
Add /selftest.extension core extension to test other extensions (#1758)
2026-03-13 07:26:01 -05:00
template
Add modular extension system (#1551)
2026-02-10 14:27:20 -06:00
catalog.community.json
Add cognitive-squad to community extension catalog (#1870)
2026-03-16 17:10:37 -05:00
catalog.json
Add /selftest.extension core extension to test other extensions (#1758)
2026-03-13 07:26:01 -05: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
feat(extensions): support .extensionignore to exclude files during install (#1781)
2026-03-10 12:02:04 -05: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
docs: add catalog cli help documentation (#1793) (#1794)
2026-03-11 06:54:07 -05:00
README.md
Add cognitive-squad to community extension catalog (#1870)
2026-03-16 17:10:37 -05:00
RFC-EXTENSION-SYSTEM.md
feat(extensions,presets): add priority-based resolution ordering (#1855)
2026-03-17 09:44:34 -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
Archive Extension Archive merged features into main project memory. spec-kit-archive
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
Cognitive Squad 19-function cognitive agent squad for autonomous pre-code analysis — 7 core agents, 7 specialists, 4 learning functions with feedback loop cognitive-squad
DocGuard — CDD Enforcement Canonical-Driven Development enforcement. Validates, scores, and traces project documentation with automated checks, AI-driven workflows, and spec-kit hooks. Zero dependencies. spec-kit-docguard
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
Project Health Check Diagnose a Spec Kit project and report health issues across structure, agents, features, scripts, extensions, and git spec-kit-doctor
Project Status Show current SDD workflow progress — active feature, artifact status, task completion, workflow phase, and extensions summary spec-kit-status
Ralph Loop Autonomous implementation loop using AI agent CLI spec-kit-ralph
Reconcile Extension Reconcile implementation drift by surgically updating feature artifacts. spec-kit-reconcile
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.