Skip to content

Commit 934a05c

Browse files
committed
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
1 parent 3ecab63 commit 934a05c

2 files changed

Lines changed: 4 additions & 2 deletions

File tree

README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -341,7 +341,7 @@ block-beta
341341
style core fill:transparent,stroke:#e6a817
342342
```
343343

344-
Templates resolve top-down: the first match wins. Project-local overrides (`.specify/templates/overrides/`) let you make one-off adjustments for a single project without creating a full preset. Commands work differently — presets and extensions register their command files directly into agent directories (e.g., `.claude/commands/`), overwriting any earlier version. If no overrides or customizations exist, Spec Kit uses its core defaults.
344+
**Templates** are resolved at **runtime** — Spec Kit walks the stack top-down and uses the first match. Project-local overrides (`.specify/templates/overrides/`) let you make one-off adjustments for a single project without creating a full preset. **Commands** are applied at **install time** — when you run `specify extension add` or `specify preset add`, command files are copied into agent directories (e.g., `.claude/commands/`), replacing whatever was there before; the last-installed version is the one the agent sees. Commands are cleaned up on removal. If no overrides or customizations exist, Spec Kit uses its core defaults.
345345

346346
### Extensions — Add New Capabilities
347347

presets/README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,15 @@ When Spec Kit needs a template (e.g. `spec-template`), it walks a resolution sta
1313

1414
If no preset is installed, core templates are used — exactly the same behavior as before presets existed.
1515

16+
Template resolution happens **at runtime** — nothing is copied; Spec Kit walks the stack on every lookup.
17+
1618
For detailed resolution and command registration flows, see [ARCHITECTURE.md](ARCHITECTURE.md).
1719

1820
## Command Overrides
1921

2022
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).
2123

22-
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.
24+
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.
2325

2426
## Quick Start
2527

0 commit comments

Comments
 (0)