mirror of
https://github.com/github/spec-kit.git
synced 2026-03-17 02:43:08 +00:00
69ee7a836e
* Initial plan * feat(templates): add pluggable template system with packs, catalog, resolver, and CLI commands Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com> * test(templates): add comprehensive unit tests for template pack system Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com> * feat(presets): pluggable preset system with template/command overrides, catalog, and resolver - Rename 'template packs' to 'presets' to avoid naming collision with core templates - PresetManifest, PresetRegistry, PresetManager, PresetCatalog, PresetResolver in presets.py - Extract CommandRegistrar to agents.py as shared infrastructure - CLI: specify preset list/add/remove/search/resolve/info - CLI: specify preset catalog list/add/remove - --preset option on specify init - Priority-based preset stacking (--priority, lower = higher precedence) - Command overrides registered into all detected agent directories (17+ agents) - Extension command safety: skip registration if target extension not installed - Multi-catalog support: env var, project config, user config, built-in defaults - resolve_template() / Resolve-Template in bash/PowerShell scripts - Self-test preset: overrides all 6 core templates + 1 command - Scaffold with 4 examples: core/extension template and command overrides - Preset catalog (catalog.json, catalog.community.json) - Documentation: README.md, ARCHITECTURE.md, PUBLISHING.md - 110 preset tests, 253 total tests passing * feat(presets): propagate command overrides to skills via init-options - Add save_init_options() / load_init_options() helpers that persist CLI flags from 'specify init' to .specify/init-options.json - PresetManager._register_skills() overwrites SKILL.md files when --ai-skills was used during init and corresponding skill dirs exist - PresetManager._unregister_skills() restores core template content on preset removal - registered_skills stored in preset registry metadata - 8 new tests covering skill override, skip conditions, and restore * fix: address PR check failures (ruff F541, CodeQL URL substring) - Remove extraneous f-prefix from two f-strings without placeholders - Replace substring URL check in test with startswith/endswith assertions to satisfy CodeQL incomplete URL substring sanitization rule * fix: address Copilot PR review comments - Move save_init_options() before preset install so skills propagation works during 'specify init --preset --ai-skills' - Clean up downloaded ZIP after successful preset install during init - Validate --from URL scheme (require HTTPS, HTTP only for localhost) - Expose unregister_commands() on extensions.py CommandRegistrar wrapper instead of reaching into private _registrar field - Use _get_merged_packs() for search() and get_pack_info() so all active catalogs are searched, not just the highest-priority one - Fix fetch_catalog() cache to verify cached URL matches current URL - Fix PresetResolver: script resolution uses .sh extension, consistent file extensions throughout resolve(), and resolve_with_source() delegates to resolve() to honor template_type parameter - Fix bash common.sh: fall through to directory scan when python3 returns empty preset list - Fix PowerShell Resolve-Template: filter out dot-folders and sort extensions deterministically * fix: narrow empty except blocks and add explanatory comments * fix: address Copilot PR review comments (round 2) - Fix init --preset error masking: distinguish "not found" from real errors - Fix bash resolve_template: skip hidden dirs in extensions (match Python/PS) - Fix temp dir leaks in tests: use temp_dir fixture instead of mkdtemp - Fix self-test catalog entry: add note that it's local-only (no download_url) - Fix Windows path issue in resolve_with_source: use Path.relative_to() - Fix skill restore path: use project's .specify/templates/commands/ not source tree - Add encoding="utf-8" to all file read/write in agents.py - Update test to set up core command templates for skill restoration * fix: remove self-test from catalog.json (local-only preset) * fix: address Copilot PR review comments (round 3) - Fix PS Resolve-Template fallback to skip dot-prefixed dirs (.cache) - Rename _catalog to _catalog_name for consistency with extension system - Enforce install_allowed policy in CLI preset add and download_pack() - Fix shell injection: pass registry path via env var instead of string interpolation * fix: correct PresetError docstring from template to preset * Removed CHANGELOG requirement * Applying review recommendations * Applying review recommendations * Applying review recommendations * Applying review recommendations --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>
116 lines
4.8 KiB
Markdown
116 lines
4.8 KiB
Markdown
# Presets
|
|
|
|
Presets are stackable, priority-ordered collections of template and command overrides for Spec Kit. They let you customize both the artifacts produced by the Spec-Driven Development workflow (specs, plans, tasks, checklists, constitutions) and the commands that guide the LLM in creating them — without forking or modifying core files.
|
|
|
|
## How It Works
|
|
|
|
When Spec Kit needs a template (e.g. `spec-template`), it walks a resolution stack:
|
|
|
|
1. `.specify/templates/overrides/` — project-local one-off overrides
|
|
2. `.specify/presets/<preset-id>/templates/` — installed presets (sorted by priority)
|
|
3. `.specify/extensions/<ext-id>/templates/` — extension-provided templates
|
|
4. `.specify/templates/` — core templates shipped with Spec Kit
|
|
|
|
If no preset is installed, core templates are used — exactly the same behavior as before presets existed.
|
|
|
|
For detailed resolution and command registration flows, see [ARCHITECTURE.md](ARCHITECTURE.md).
|
|
|
|
## Command Overrides
|
|
|
|
Presets can also override the commands that guide the SDD workflow. Templates define *what* gets produced (specs, plans, constitutions); commands define *how* the LLM produces them (the step-by-step instructions).
|
|
|
|
When a preset includes `type: "command"` entries, the commands are automatically registered into all detected agent directories (`.claude/commands/`, `.gemini/commands/`, etc.) in the correct format (Markdown or TOML with appropriate argument placeholders). When the preset is removed, the registered commands are cleaned up.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Search available presets
|
|
specify preset search
|
|
|
|
# Install a preset from the catalog
|
|
specify preset add healthcare-compliance
|
|
|
|
# Install from a local directory (for development)
|
|
specify preset add --dev ./my-preset
|
|
|
|
# Install with a specific priority (lower = higher precedence)
|
|
specify preset add healthcare-compliance --priority 5
|
|
|
|
# List installed presets
|
|
specify preset list
|
|
|
|
# See which template a name resolves to
|
|
specify preset resolve spec-template
|
|
|
|
# Get detailed info about a preset
|
|
specify preset info healthcare-compliance
|
|
|
|
# Remove a preset
|
|
specify preset remove healthcare-compliance
|
|
```
|
|
|
|
## Stacking Presets
|
|
|
|
Multiple presets can be installed simultaneously. The `--priority` flag controls which one wins when two presets provide the same template (lower number = higher precedence):
|
|
|
|
```bash
|
|
specify preset add enterprise-safe --priority 10 # base layer
|
|
specify preset add healthcare-compliance --priority 5 # overrides enterprise-safe
|
|
specify preset add pm-workflow --priority 1 # overrides everything
|
|
```
|
|
|
|
Presets **override**, they don't merge. If two presets both provide `spec-template`, the one with the lowest priority number wins entirely.
|
|
|
|
## Catalog Management
|
|
|
|
Presets are discovered through catalogs. By default, Spec Kit uses the official and community catalogs:
|
|
|
|
```bash
|
|
# List active catalogs
|
|
specify preset catalog list
|
|
|
|
# Add a custom catalog
|
|
specify preset catalog add https://example.com/catalog.json --name my-org --install-allowed
|
|
|
|
# Remove a catalog
|
|
specify preset catalog remove my-org
|
|
```
|
|
|
|
## Creating a Preset
|
|
|
|
See [scaffold/](scaffold/) for a scaffold you can copy to create your own preset.
|
|
|
|
1. Copy `scaffold/` to a new directory
|
|
2. Edit `preset.yml` with your preset's metadata
|
|
3. Add or replace templates in `templates/`
|
|
4. Test locally with `specify preset add --dev .`
|
|
5. Verify with `specify preset resolve spec-template`
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `SPECKIT_PRESET_CATALOG_URL` | Override the catalog URL (replaces all defaults) |
|
|
|
|
## Configuration Files
|
|
|
|
| File | Scope | Description |
|
|
|------|-------|-------------|
|
|
| `.specify/preset-catalogs.yml` | Project | Custom catalog stack for this project |
|
|
| `~/.specify/preset-catalogs.yml` | User | Custom catalog stack for all projects |
|
|
|
|
## Future Considerations
|
|
|
|
The following enhancements are under consideration for future releases:
|
|
|
|
- **Composition strategies** — Allow presets to declare a `strategy` per template instead of the default `replace`:
|
|
|
|
| Type | `replace` | `prepend` | `append` | `wrap` |
|
|
|------|-----------|-----------|----------|--------|
|
|
| **template** | ✓ (default) | ✓ | ✓ | ✓ |
|
|
| **command** | ✓ (default) | ✓ | ✓ | ✓ |
|
|
| **script** | ✓ (default) | — | — | ✓ |
|
|
|
|
For artifacts and commands (which are LLM directives), `wrap` would inject preset content before and after the core template using a `{CORE_TEMPLATE}` placeholder. For scripts, `wrap` would run custom logic before/after the core script via a `$CORE_SCRIPT` variable.
|
|
- **Script overrides** — Enable presets to provide alternative versions of core scripts (e.g. `create-new-feature.sh`) for workflow customization. A `strategy: "wrap"` option could allow presets to run custom logic before/after the core script without fully replacing it.
|