π« Toolkit to help you get started with SDD or any other process!
Preset System Architecture
This document describes the internal architecture of the preset system β how template resolution, command registration, and catalog management work under the hood.
For usage instructions, see README.md.
Template Resolution
When Spec Kit needs a template (e.g. spec-template), the PresetResolver walks a priority stack and returns the first match:
flowchart TD
A["resolve_template('spec-template')"] --> B{Override exists?}
B -- Yes --> C[".specify/templates/overrides/spec-template.md"]
B -- No --> D{Preset provides it?}
D -- Yes --> E[".specify/presets/βΉpreset-idβΊ/templates/spec-template.md"]
D -- No --> F{Extension provides it?}
F -- Yes --> G[".specify/extensions/βΉext-idβΊ/templates/spec-template.md"]
F -- No --> H[".specify/templates/spec-template.md"]
E -- "multiple presets?" --> I["lowest priority number wins"]
I --> E
style C fill:#4caf50,color:#fff
style E fill:#2196f3,color:#fff
style G fill:#ff9800,color:#fff
style H fill:#9e9e9e,color:#fff
| Priority | Source | Path | Use case |
|---|---|---|---|
| 1 (highest) | Override | .specify/templates/overrides/ |
One-off project-local tweaks |
| 2 | Preset | .specify/presets/<id>/templates/ |
Shareable, stackable customizations |
| 3 | Extension | .specify/extensions/<id>/templates/ |
Extension-provided templates |
| 4 (lowest) | Core | .specify/templates/ |
Shipped defaults |
When multiple presets are installed, they're sorted by their priority field (lower number = higher precedence). This is set via --priority on specify preset add.
The resolution is implemented three times to ensure consistency:
- Python:
PresetResolverinsrc/specify_cli/presets.py - Bash:
resolve_template()inscripts/bash/common.sh - PowerShell:
Resolve-Templateinscripts/powershell/common.ps1
Composition Strategies
Templates, commands, and scripts support a strategy field that controls how a preset's content is combined with lower-priority content instead of fully replacing it:
| Strategy | Description | Templates | Commands | Scripts |
|---|---|---|---|---|
replace (default) |
Fully replaces lower-priority content | β | β | β |
prepend |
Places content before lower-priority content (separated by a blank line) | β | β | β |
append |
Places content after lower-priority content (separated by a blank line) | β | β | β |
wrap |
Content contains {CORE_TEMPLATE} (templates/commands) or $CORE_SCRIPT (scripts) placeholder replaced with lower-priority content |
β | β | β |
Composition is recursive β multiple composing presets chain. The PresetResolver.resolve_content() method walks the full priority stack bottom-up and applies each layer's strategy.
Content resolution functions for composition:
- Python:
PresetResolver.resolve_content()insrc/specify_cli/presets.py(templates, commands, and scripts) - Bash:
resolve_template_content()inscripts/bash/common.sh(templates only; command/script composition is handled by the Python resolver) - PowerShell:
Resolve-TemplateContentinscripts/powershell/common.ps1(templates only; command/script composition is handled by the Python resolver)
Constitution lifecycle
Initialization resolves constitution-template through the full stack and seeds
.specify/memory/constitution.md once. Existing files are preserved byte-for-byte. On subsequent
/constitution runs, the command resolves the current composed template at runtime and uses the live
constitution as the source of project-specific values and amendments.
Preset installation, removal, enablement, disablement, and priority changes do not materialize
constitution-template by default. When the enabled preset registry contains constitution-sync,
those operations may reconcile the live file, but only if its provenance hash proves it is still
generated content. Missing files may be seeded when the preset is installed; authored or edited
constitutions are never overwritten.
Command Registration
When a preset is installed with type: "command" entries, the PresetManager registers them into all detected agent directories using the shared CommandRegistrar from src/specify_cli/agents.py.
flowchart TD
A["specify preset add my-preset"] --> B{Preset has type: command?}
B -- No --> Z["done (templates only)"]
B -- Yes --> C{Extension command?}
C -- "speckit.myext.cmd\n(3+ dot segments)" --> D{Extension installed?}
D -- No --> E["skip (extension not active)"]
D -- Yes --> F["register command"]
C -- "speckit.specify\n(core command)" --> F
F --> G["detect agent directories"]
G --> H[".claude/commands/"]
G --> I[".gemini/commands/"]
G --> J[".github/agents/"]
G --> K["... (17+ agents)"]
H --> L["write .md (Markdown format)"]
I --> M["write .toml (TOML format)"]
J --> N["write .agent.md + .prompt.md"]
style E fill:#ff5722,color:#fff
style L fill:#4caf50,color:#fff
style M fill:#4caf50,color:#fff
style N fill:#4caf50,color:#fff
Extension safety check
Command names follow the pattern speckit.<ext-id>.<cmd-name>. When a command has 3+ dot segments, the system extracts the extension ID and checks if .specify/extensions/<ext-id>/ exists. If the extension isn't installed, the command is skipped β preventing orphan files referencing non-existent extensions.
Core commands (e.g. speckit.specify, with only 2 segments) are always registered.
Agent format rendering
The CommandRegistrar renders commands differently per agent:
| Agent | Format | Extension | Arg placeholder |
|---|---|---|---|
| Claude, Kilo Code, opencode, etc. | Markdown | .md |
$ARGUMENTS |
| Copilot | Markdown | .agent.md + .prompt.md |
$ARGUMENTS |
| Gemini, Qwen, Tabnine | TOML | .toml |
{{args}} |
Cleanup on removal
When specify preset remove is called, the registered commands are read from the registry metadata and the corresponding files are deleted from each agent directory, including Copilot companion .prompt.md files.
Catalog System
flowchart TD
A["specify preset search"] --> B["PresetCatalog.get_active_catalogs()"]
B --> C{SPECKIT_PRESET_CATALOG_URL set?}
C -- Yes --> D["single custom catalog"]
C -- No --> E{.specify/preset-catalogs.yml exists?}
E -- Yes --> F["project-level catalog stack"]
E -- No --> G{"~/.specify/preset-catalogs.yml exists?"}
G -- Yes --> H["user-level catalog stack"]
G -- No --> I["built-in defaults"]
I --> J["default (install allowed)"]
I --> K["community (discovery only)"]
style D fill:#ff9800,color:#fff
style F fill:#2196f3,color:#fff
style H fill:#2196f3,color:#fff
style J fill:#4caf50,color:#fff
style K fill:#9e9e9e,color:#fff
Catalogs are fetched with a 1-hour cache (per-URL, SHA256-hashed cache files). Each catalog entry has a priority (for merge ordering) and install_allowed flag.
Repository Layout
presets/
βββ ARCHITECTURE.md # This file
βββ PUBLISHING.md # Guide for submitting presets to the catalog
βββ README.md # User guide
βββ catalog.json # Official preset catalog
βββ catalog.community.json # Community preset catalog
βββ scaffold/ # Scaffold for creating new presets
β βββ preset.yml # Example manifest
β βββ README.md # Guide for customizing the scaffold
β βββ commands/
β β βββ speckit.specify.md # Core command override example
β β βββ speckit.myext.myextcmd.md # Extension command override example
β βββ templates/
β βββ spec-template.md # Core template override example
β βββ myext-template.md # Extension template override example
βββ self-test/ # Self-test preset (overrides all core templates)
βββ preset.yml
βββ commands/
β βββ speckit.specify.md
βββ templates/
βββ spec-template.md
βββ plan-template.md
βββ tasks-template.md
βββ checklist-template.md
βββ constitution-template.md
Module Structure
src/specify_cli/
βββ agents.py # CommandRegistrar β shared infrastructure for writing
β # command files to agent directories
βββ presets.py # PresetManifest, PresetRegistry, PresetManager,
β # PresetCatalog, PresetCatalogEntry, PresetResolver
βββ __init__.py # CLI commands: specify preset list/add/remove/search/
# resolve/info, specify preset catalog list/add/remove