mirror of
https://github.com/github/spec-kit.git
synced 2026-03-19 11:53:08 +00:00
497b5885e1
* docs: add Extensions & Presets section to README Add a new 'Making Spec Kit Your Own: Extensions & Presets' section that covers: - Layering diagram (Mermaid) showing resolution order - Extensions: what they are, when to use, examples - Presets: what they are, when to use, examples - When-to-use-which comparison table - Links to extensions/README.md and presets/README.md * docs: clarify project-local overrides in layering diagram Address review feedback: explain the project-local overrides layer shown in the diagram, and adjust the intro to acknowledge it as a third customization mechanism alongside extensions and presets. * docs: Clarify template vs command resolution in README - Separate template resolution (top-down, first-match-wins stack) from command registration (written directly into agent directories) - Update Mermaid diagram paths to use <preset-id> and <ext-id> placeholders consistent with existing documentation Addresses PR review feedback on #1898. * docs: Clarify install-time vs runtime resolution for commands and templates - README: label templates as runtime-resolved (stack walk) and commands as install-time (copied into agent directories, last-installed wins) - presets/README: add runtime note to template resolution, contrast with install-time command registration * docs: Address review — fix template copy wording, tighten command override description - presets/README: clarify that preset files are copied at install but template resolution still walks the stack at runtime - README: describe priority-based command resolution and automatic restoration on removal instead of vague 'replacing whatever was there'
118 lines
5.1 KiB
Markdown
118 lines
5.1 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.
|
|
|
|
Template resolution happens **at runtime** — although preset files are copied into `.specify/presets/<id>/` during installation, Spec Kit walks the resolution stack on every template lookup rather than merging templates into a single location.
|
|
|
|
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).
|
|
|
|
Unlike templates, command overrides are applied **at install time**. When a preset includes `type: "command"` entries, the commands are 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.
|