From b743c9b6b35bb41cc179b325ff1b0e4b19aea07c Mon Sep 17 00:00:00 2001 From: root Date: Wed, 24 Jun 2026 10:54:15 +0800 Subject: [PATCH 1/5] docs: update preset composition strategy reference --- docs/reference/presets.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/presets.md b/docs/reference/presets.md index 4a613ffc00..79bd1ca6a9 100644 --- a/docs/reference/presets.md +++ b/docs/reference/presets.md @@ -137,9 +137,9 @@ catalogs: ## File Resolution -Presets can provide command files, template files (like `plan-template.md`), and script files. These are resolved at runtime using a **replace** strategy — the first match in the priority stack wins and is used entirely. Each file is looked up independently, so different files can come from different layers. +Presets can provide command files, template files (like `plan-template.md`), and script files. Each file is looked up independently, so different files can come from different layers. -> **Note:** Additional composition strategies (`append`, `prepend`, `wrap`) are planned for a future release. +By default, files use a **replace** strategy: the first match in the priority stack wins and is used entirely. Templates and commands can also use composition strategies: **prepend** places preset content before lower-priority content, **append** places it after lower-priority content, and **wrap** replaces `{CORE_TEMPLATE}` with lower-priority content. Scripts support **replace** and **wrap**; script wrappers use `$CORE_SCRIPT` as the placeholder. The resolution stack, from highest to lowest precedence: From 37ca589d45d55cb5582af19e0198febbf3b1a396 Mon Sep 17 00:00:00 2001 From: root Date: Thu, 25 Jun 2026 09:51:16 +0800 Subject: [PATCH 2/5] docs: clarify preset command composition timing --- docs/reference/presets.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/presets.md b/docs/reference/presets.md index 79bd1ca6a9..68612bef24 100644 --- a/docs/reference/presets.md +++ b/docs/reference/presets.md @@ -137,9 +137,9 @@ catalogs: ## File Resolution -Presets can provide command files, template files (like `plan-template.md`), and script files. Each file is looked up independently, so different files can come from different layers. +Presets can provide command files, template files (like `plan-template.md`), and script files. Template and script files are looked up independently through the runtime stack, so different files can come from different layers. -By default, files use a **replace** strategy: the first match in the priority stack wins and is used entirely. Templates and commands can also use composition strategies: **prepend** places preset content before lower-priority content, **append** places it after lower-priority content, and **wrap** replaces `{CORE_TEMPLATE}` with lower-priority content. Scripts support **replace** and **wrap**; script wrappers use `$CORE_SCRIPT` as the placeholder. +By default, files use a **replace** strategy: the first match in the priority stack wins and is used entirely. Templates can also use composition strategies: **prepend** places preset content before lower-priority content, **append** places it after lower-priority content, and **wrap** replaces `{CORE_TEMPLATE}` with lower-priority content. Commands support the same composition strategies during preset install, before they are registered with detected agents. Scripts support **replace** and **wrap**; script wrappers use `$CORE_SCRIPT` as the placeholder. The resolution stack, from highest to lowest precedence: @@ -148,7 +148,7 @@ The resolution stack, from highest to lowest precedence: 3. **Installed extensions** — sorted by priority 4. **Spec Kit core** — `.specify/templates/` -Commands are registered at install time (not resolved through the stack at runtime). +Commands are registered at install time, not resolved through the stack at runtime after registration. ### Resolution Stack From 756a3dfed7d6eb837cb45a6a436c6d99cea2aa4b Mon Sep 17 00:00:00 2001 From: root Date: Thu, 25 Jun 2026 20:55:01 +0800 Subject: [PATCH 3/5] docs: clarify preset command reconciliation timing --- docs/reference/presets.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/presets.md b/docs/reference/presets.md index 68612bef24..6524d40a84 100644 --- a/docs/reference/presets.md +++ b/docs/reference/presets.md @@ -139,7 +139,7 @@ catalogs: Presets can provide command files, template files (like `plan-template.md`), and script files. Template and script files are looked up independently through the runtime stack, so different files can come from different layers. -By default, files use a **replace** strategy: the first match in the priority stack wins and is used entirely. Templates can also use composition strategies: **prepend** places preset content before lower-priority content, **append** places it after lower-priority content, and **wrap** replaces `{CORE_TEMPLATE}` with lower-priority content. Commands support the same composition strategies during preset install, before they are registered with detected agents. Scripts support **replace** and **wrap**; script wrappers use `$CORE_SCRIPT` as the placeholder. +By default, files use a **replace** strategy: the first match in the priority stack wins and is used entirely. Templates and commands can also use composition strategies: **prepend** places preset content before lower-priority content, **append** places it after lower-priority content, and **wrap** replaces `{CORE_TEMPLATE}` with lower-priority content. Scripts support **replace** and **wrap**; script wrappers use `$CORE_SCRIPT` as the placeholder. The resolution stack, from highest to lowest precedence: @@ -148,7 +148,7 @@ The resolution stack, from highest to lowest precedence: 3. **Installed extensions** — sorted by priority 4. **Spec Kit core** — `.specify/templates/` -Commands are registered at install time, not resolved through the stack at runtime after registration. +Commands use the same stack order for composition, but the effective command content is written into detected agent directories during preset install and post-install/post-removal reconciliation. Agents do not re-resolve the stack each time they run a command. ### Resolution Stack From 073274c8d761687649c0a712df6467c1bbb9ceec Mon Sep 17 00:00:00 2001 From: root Date: Thu, 25 Jun 2026 21:38:01 +0800 Subject: [PATCH 4/5] docs: clarify preset file resolution behavior --- docs/reference/presets.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/presets.md b/docs/reference/presets.md index 6524d40a84..e20b188e44 100644 --- a/docs/reference/presets.md +++ b/docs/reference/presets.md @@ -137,7 +137,9 @@ catalogs: ## File Resolution -Presets can provide command files, template files (like `plan-template.md`), and script files. Template and script files are looked up independently through the runtime stack, so different files can come from different layers. +Presets can provide command files, template files (like `plan-template.md`), and script files. Each file name is evaluated independently against the priority stack, so different files can come from different layers. + +Templates and scripts are looked up from the stack when Spec Kit needs them. Commands use the same stack for replacement and composition, but are materialized into detected agent directories instead of being re-resolved by agents. During preset install, Spec Kit registers command files for the preset being installed; post-install and post-removal reconciliation then recalculates affected command names from the active stack and writes the effective content. Agents do not re-resolve the stack each time they run a command. By default, files use a **replace** strategy: the first match in the priority stack wins and is used entirely. Templates and commands can also use composition strategies: **prepend** places preset content before lower-priority content, **append** places it after lower-priority content, and **wrap** replaces `{CORE_TEMPLATE}` with lower-priority content. Scripts support **replace** and **wrap**; script wrappers use `$CORE_SCRIPT` as the placeholder. @@ -148,8 +150,6 @@ The resolution stack, from highest to lowest precedence: 3. **Installed extensions** — sorted by priority 4. **Spec Kit core** — `.specify/templates/` -Commands use the same stack order for composition, but the effective command content is written into detected agent directories during preset install and post-install/post-removal reconciliation. Agents do not re-resolve the stack each time they run a command. - ### Resolution Stack ```mermaid @@ -215,7 +215,7 @@ Run `specify preset resolve ` to trace the resolution stack and see which ### What's the difference between disabling and removing a preset? -**Disabling** (`specify preset disable`) keeps the preset installed but excludes its files from the resolution stack. Commands the preset registered remain available in your AI coding agent. This is useful for temporarily testing behavior without a preset, or comparing output with and without it. Re-enable anytime with `specify preset enable`. +**Disabling** (`specify preset disable`) keeps the preset installed but excludes it from future template and script resolution. Previously registered commands remain available in your AI coding agent until preset removal, so use removal when you need command changes to stop taking effect. Disabling is useful for temporarily testing template/script behavior without a preset, or comparing template/script output with and without it. Re-enable anytime with `specify preset enable`. **Removing** (`specify preset remove`) fully uninstalls the preset — deletes its files, unregisters its commands from your AI coding agent, and removes it from the registry. From a1ca80f9694416a7aaafdd38df88f39ba60ccb58 Mon Sep 17 00:00:00 2001 From: root Date: Thu, 25 Jun 2026 22:09:09 +0800 Subject: [PATCH 5/5] docs: clarify preset command reconciliation wording --- docs/reference/presets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/presets.md b/docs/reference/presets.md index e20b188e44..549177c1d6 100644 --- a/docs/reference/presets.md +++ b/docs/reference/presets.md @@ -139,7 +139,7 @@ catalogs: Presets can provide command files, template files (like `plan-template.md`), and script files. Each file name is evaluated independently against the priority stack, so different files can come from different layers. -Templates and scripts are looked up from the stack when Spec Kit needs them. Commands use the same stack for replacement and composition, but are materialized into detected agent directories instead of being re-resolved by agents. During preset install, Spec Kit registers command files for the preset being installed; post-install and post-removal reconciliation then recalculates affected command names from the active stack and writes the effective content. Agents do not re-resolve the stack each time they run a command. +Templates and scripts are looked up from the stack when Spec Kit needs them. Commands use the same stack for replacement and composition, but are materialized into detected agent directories instead of being re-resolved by agents. During preset install, Spec Kit registers command files for the preset being installed; post-install and post-removal reconciliation then recomputes and writes the effective command content for affected command names based on the active stack. Agents do not re-resolve the stack each time they run a command. By default, files use a **replace** strategy: the first match in the priority stack wins and is used entirely. Templates and commands can also use composition strategies: **prepend** places preset content before lower-priority content, **append** places it after lower-priority content, and **wrap** replaces `{CORE_TEMPLATE}` with lower-priority content. Scripts support **replace** and **wrap**; script wrappers use `$CORE_SCRIPT` as the placeholder.