From 6adec7aad57f36552cfd3264bd2f18b3b5deb10e Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Wed, 18 Mar 2026 12:48:18 -0500 Subject: [PATCH 1/5] 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 --- README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/README.md b/README.md index b3c6235e5..dad26cf38 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ - [🚢 Community Walkthroughs](#-community-walkthroughs) - [πŸ€– Supported AI Agents](#-supported-ai-agents) - [πŸ”§ Specify CLI Reference](#-specify-cli-reference) +- [🧩 Making Spec Kit Your Own: Extensions & Presets](#-making-spec-kit-your-own-extensions--presets) - [πŸ“š Core Philosophy](#-core-philosophy) - [🌟 Development Phases](#-development-phases) - [🎯 Experimental Goals](#-experimental-goals) @@ -322,6 +323,68 @@ Additional commands for enhanced quality and validation: | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches.
\*\*Must be set in the context of the agent you're working with prior to using `/speckit.plan` or follow-up commands. | +## 🧩 Making Spec Kit Your Own: Extensions & Presets + +Spec Kit can be tailored to your needs through two complementary systems: + +```mermaid +block-beta + columns 1 + overrides["⬆ Highest priority\nProject-Local Overrides\n.specify/templates/overrides/"] + presets["Presets β€” Customize core & extensions\n.specify/presets/β€Ήpresetβ€Ί/"] + extensions["Extensions β€” Add new capabilities\n.specify/extensions/β€Ήextβ€Ί/"] + core["Spec Kit Core β€” Built-in SDD commands & templates\n.specify/templates/\n⬇ Lowest priority"] + + style overrides fill:transparent,stroke:#999 + style presets fill:transparent,stroke:#4a9eda + style extensions fill:transparent,stroke:#4a9e4a + style core fill:transparent,stroke:#e6a817 +``` + +Templates and commands resolve top-down: the first match wins. If no overrides or customizations exist, Spec Kit uses its core defaults. + +### Extensions β€” Add New Capabilities + +Use **extensions** when you need functionality that goes beyond Spec Kit's core. Extensions introduce new commands and templates β€” for example, adding domain-specific workflows that are not covered by the built-in SDD commands, integrating with external tools, or adding entirely new development phases. They expand *what Spec Kit can do*. + +```bash +# Search available extensions +specify extension search + +# Install an extension +specify extension add +``` + +For example, extensions could add Jira integration, post-implementation code review, V-Model test traceability, or project health diagnostics. + +See the [Extensions README](./extensions/README.md) for the full guide, the complete community catalog, and how to build and publish your own. + +### Presets β€” Customize Existing Workflows + +Use **presets** when you want to change *how* Spec Kit works without adding new capabilities. Presets override the templates and commands that ship with the core *and* with installed extensions β€” for example, enforcing a compliance-oriented spec format, using domain-specific terminology, or applying organizational standards to plans and tasks. They customize the artifacts and instructions that Spec Kit and its extensions produce. + +```bash +# Search available presets +specify preset search + +# Install a preset +specify preset add +``` + +For example, presets could restructure spec templates to require regulatory traceability, adapt the workflow to fit the methodology you use (e.g., Agile, Kanban, Waterfall, jobs-to-be-done, or domain-driven design), add mandatory security review gates to plans, enforce test-first task ordering, or localize the entire workflow to a different language. The [pirate-speak demo](https://github.com/mnriem/spec-kit-pirate-speak-preset-demo) shows just how deep the customization can go. Multiple presets can be stacked with priority ordering. + +See the [Presets README](./presets/README.md) for the full guide, including resolution order, priority, and how to create your own. + +### When to Use Which + +| Goal | Use | +| --- | --- | +| Add a brand-new command or workflow | Extension | +| Customize the format of specs, plans, or tasks | Preset | +| Integrate an external tool or service | Extension | +| Enforce organizational or regulatory standards | Preset | +| Ship reusable domain-specific templates | Either β€” presets for template overrides, extensions for templates bundled with new commands | + ## πŸ“š Core Philosophy Spec-Driven Development is a structured process that emphasizes: From c34127b44068c792e0ea97701630ab57a17c919b Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Wed, 18 Mar 2026 13:12:12 -0500 Subject: [PATCH 2/5] 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. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dad26cf38..dd1f896c4 100644 --- a/README.md +++ b/README.md @@ -325,7 +325,7 @@ Additional commands for enhanced quality and validation: ## 🧩 Making Spec Kit Your Own: Extensions & Presets -Spec Kit can be tailored to your needs through two complementary systems: +Spec Kit can be tailored to your needs through two complementary systems β€” **extensions** and **presets** β€” plus project-local overrides for one-off adjustments: ```mermaid block-beta @@ -341,7 +341,7 @@ block-beta style core fill:transparent,stroke:#e6a817 ``` -Templates and commands resolve top-down: the first match wins. If no overrides or customizations exist, Spec Kit uses its core defaults. +Templates and commands 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. If no overrides or customizations exist, Spec Kit uses its core defaults. ### Extensions β€” Add New Capabilities From 3ecab63c7a3a15f1373c4d28acde60ac6555ec33 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Wed, 18 Mar 2026 13:32:30 -0500 Subject: [PATCH 3/5] 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 and placeholders consistent with existing documentation Addresses PR review feedback on #1898. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index dd1f896c4..2464d18ad 100644 --- a/README.md +++ b/README.md @@ -331,8 +331,8 @@ Spec Kit can be tailored to your needs through two complementary systems β€” **e block-beta columns 1 overrides["⬆ Highest priority\nProject-Local Overrides\n.specify/templates/overrides/"] - presets["Presets β€” Customize core & extensions\n.specify/presets/β€Ήpresetβ€Ί/"] - extensions["Extensions β€” Add new capabilities\n.specify/extensions/β€Ήextβ€Ί/"] + presets["Presets β€” Customize core & extensions\n.specify/presets//templates/"] + extensions["Extensions β€” Add new capabilities\n.specify/extensions//templates/"] core["Spec Kit Core β€” Built-in SDD commands & templates\n.specify/templates/\n⬇ Lowest priority"] style overrides fill:transparent,stroke:#999 @@ -341,7 +341,7 @@ block-beta style core fill:transparent,stroke:#e6a817 ``` -Templates and commands 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. If no overrides or customizations exist, Spec Kit uses its core defaults. +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. ### Extensions β€” Add New Capabilities From 934a05c0eb4ebab72dae4d9e52ca66ab32adef22 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Wed, 18 Mar 2026 13:42:32 -0500 Subject: [PATCH 4/5] 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 --- README.md | 2 +- presets/README.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2464d18ad..12c97a14e 100644 --- a/README.md +++ b/README.md @@ -341,7 +341,7 @@ block-beta style core fill:transparent,stroke:#e6a817 ``` -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. +**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. ### Extensions β€” Add New Capabilities diff --git a/presets/README.md b/presets/README.md index 2fb22a71f..11c67b974 100644 --- a/presets/README.md +++ b/presets/README.md @@ -13,13 +13,15 @@ When Spec Kit needs a template (e.g. `spec-template`), it walks a resolution sta If no preset is installed, core templates are used β€” exactly the same behavior as before presets existed. +Template resolution happens **at runtime** β€” nothing is copied; Spec Kit walks the stack on every lookup. + 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. +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 From 24b7d1ded33bbd1d90fb5f21b234a4b237b61901 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Wed, 18 Mar 2026 13:56:15 -0500 Subject: [PATCH 5/5] =?UTF-8?q?docs:=20Address=20review=20=E2=80=94=20fix?= =?UTF-8?q?=20template=20copy=20wording,=20tighten=20command=20override=20?= =?UTF-8?q?description?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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' --- README.md | 2 +- presets/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 12c97a14e..b69aa1091 100644 --- a/README.md +++ b/README.md @@ -341,7 +341,7 @@ block-beta style core fill:transparent,stroke:#e6a817 ``` -**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. +**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 written into agent directories (e.g., `.claude/commands/`). If multiple presets or extensions provide the same command, the highest-priority version wins. On removal, the next-highest-priority version is restored automatically. If no overrides or customizations exist, Spec Kit uses its core defaults. ### Extensions β€” Add New Capabilities diff --git a/presets/README.md b/presets/README.md index 11c67b974..f039b83d4 100644 --- a/presets/README.md +++ b/presets/README.md @@ -13,7 +13,7 @@ When Spec Kit needs a template (e.g. `spec-template`), it walks a resolution sta If no preset is installed, core templates are used β€” exactly the same behavior as before presets existed. -Template resolution happens **at runtime** β€” nothing is copied; Spec Kit walks the stack on every lookup. +Template resolution happens **at runtime** β€” although preset files are copied into `.specify/presets//` 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).