CodeVetter · Repo Unpack · Extension points
github/spec-kit
The repo is essentially a plugin framework. Five registration seams exist: (1) `INTEGRATION_REGISTRY` for AI agents via small class-attr subclasses of four base classes; (2) `STEP_REGISTRY`/`StepBase` for workflow step types, including project-local dynamically-loaded custom steps; (3) extension packages (`extension.yml`) adding commands/hooks/events/config; (4) presets (`preset.yml`) overriding templates via priority-resolved `replaces:` entries; (5) bundles (`bundle.yml`) packaging all of the above. All five are discoverable/installable through per-domain catalog stacks that users can extend with custom catalog URLs.
- New AI-agent integrations plug in via `INTEGRATION_REGISTRY`: create `src/specify_cli/integrations/<pkg>/__init__.py` with a class setting `key`, `config`, `registrar_config`, then add one import + one `_register()` call (both alphabetical) in `_register_builtins()`; package dirs use underscores while `key` keeps the hyphenated CLI name.
- Four integration base classes cover the output formats — `MarkdownIntegration`, `TomlIntegration`, `YamlIntegration`, `SkillsIntegration`, or `IntegrationBase` for fully custom setup (e.g. Copilot's dual skills/commands layouts) — with documented override points: `setup()`, `teardown()`, `command_filename()`, `options()`, `post_process_command_content()`, `effective_invoke_separator()`.
- Per-integration CLI flags are declared via `IntegrationOption` entries returned from `options()` and consumed through `--integration-options` (e.g. codex `--skills`, copilot `--commands`, generic `--commands-dir`); `options()` auto-adds `--events` when the integration declares `CANONICAL_TO_NATIVE` + `events_config_file`.
- `specify integration scaffold` generates a new integration subpackage from templates (`command_scaffold.py` + `_command_scaffold_generation.py`), giving a code-level entry point for the documented 'add an integration in 5 steps' flow.
- Workflow step types plug into `STEP_REGISTRY` (`type_key` → `StepBase` subclass); beyond the 11 builtins, `load_custom_steps` imports project-local step packages from `.specify/workflows/steps/<pkg>/` defined by `step.yml` (`step.type_key`) + `__init__.py` (`StepBase` subclass).
- Extensions are self-contained packages declared by `extension.yml` (`schema_version`, `extension` metadata, `requires`, `provides.commands|config|templates|scripts`, `hooks.<before|after>_<command>`, `events`, `config.defaults`) — validated by `ExtensionManifest` and installed by `ExtensionManager`; `extensions/template/` is the starter scaffold.
- Presets override core behavior declaratively: `preset.yml` `provides.templates` entries with `replaces: "speckit.<cmd>"` substitute command/template/script artifacts, and `PresetResolver` composes the stack by priority (lower number wins) — e.g. `lean` replaces the five core commands with minimal variants.
- Bundles (`bundle.yml`) compose extensions, presets, workflows, and step types into one installable unit (`specify bundle install`); first-party `bugfix` and `assess` bundles plus a community catalog JSON ship in the wheel for offline discovery.
- Every domain (integrations, extensions, presets, workflows, bundles) supports user-added remote catalogs through `catalog add/list/remove` commands backed by `CatalogStackBase` entries with `url`, `priority`, and `install_allowed` flags — so organizations can host private catalogs.
- Workflow overlays (`workflows/overlays/` composer + `workflow overlay` command group) let projects layer modifications onto installed workflows without forking them — merge, layer_sources, and schema modules define the overlay pipeline.
- Agent-native runtime events plug in per-integration: a class declaring `CANONICAL_TO_NATIVE` (canonical snake_case events → native hook names) and `events_config_file` automatically gets `--events` support and native hook emission via `install_integration_events`; canonical events are session_start, pre_tool_use, post_tool_use, session_end, user_prompt_submit, stop.
- The `agent-context` extension owns all context-file (CLAUDE.md/AGENTS.md) management as a fully opt-in, generic component driven by `agent-context-config.yml` markers — deliberately keeping context-file knowledge out of the CLI/registry so new integrations add nothing for it.