mirror of
https://github.com/github/spec-kit.git
synced 2026-03-17 19:03:08 +00:00
abf4aebdb3
- 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
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.
|