Skip to content

README.md

Latest commit

 

History

History
142 lines (96 loc) · 6.17 KB

README.md

File metadata and controls

142 lines (96 loc) · 6.17 KB

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.

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

# 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):

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 by default, they don't merge. If two presets both provide spec-template with the default replace strategy, the one with the lowest priority number wins entirely. However, presets can use composition strategies to augment rather than replace content.

Composition Strategies

Presets can declare a strategy per template to control how content is combined:

provides:
  templates:
    - type: "template"
      name: "spec-template"
      file: "templates/spec-addendum.md"
      strategy: "append"        # adds content after the core template
Strategy Description
replace (default) Fully replaces the lower-priority template
prepend Places content before the resolved lower-priority template, separated by a blank line
append Places content after the resolved lower-priority template, separated by a blank line
wrap Content contains {CORE_TEMPLATE} placeholder (or $CORE_SCRIPT for scripts) replaced with the lower-priority content

Supported combinations:

Type replace prepend append wrap
template ✓ (default) ✓ ✓ ✓
command ✓ (default) ✓ ✓ ✓
script ✓ (default) — — ✓

Multiple composing presets chain recursively. For example, a security preset with prepend and a compliance preset with append will produce: security header + core content + compliance footer.

Catalog Management

Presets are discovered through catalogs. By default, Spec Kit uses the official and community catalogs:

Note

Community presets are independently created and maintained by their respective authors. GitHub and the Spec Kit maintainers may review pull requests that add entries to the community catalog for formatting, catalog structure, or policy compliance, but they do not review, audit, endorse, or support the preset code itself. Review preset source code before installation and use at your own discretion.

# 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/ 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:

  • Structural merge strategies — Parsing Markdown sections for per-section granularity (e.g., "replace only ## Security").
  • Conflict detection — specify preset lint / specify preset doctor for detecting composition conflicts.