docs: Add Extensions & Presets section to README#1898
Merged
mnriem merged 5 commits intogithub:mainfrom Mar 18, 2026
Merged
Conversation
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
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new README section explaining how to customize Spec Kit via extensions and presets, aiming to help users understand where to install customizations and how precedence works.
Changes:
- Adds a new “Making Spec Kit Your Own: Extensions & Presets” section to README.
- Introduces a Mermaid diagram and guidance on when to use extensions vs presets.
- Adds basic CLI examples for searching/adding extensions and presets, with links to the detailed guides.
Comments suppressed due to low confidence (1)
README.md:345
- “Templates and commands resolve top-down: the first match wins” appears to describe one shared resolution mechanism, but only templates have an explicit resolver/override stack (including
.specify/templates/overrides/). Command overrides are registered into agent directories during preset/extension install and don’t participate in the.specify/templates/overrides/lookup. Please clarify this sentence so it’s accurate about what the priority stack applies to (templates), and describe command override behavior separately (e.g., presets/extensions overwrite registered command files by priority).
Templates and commands resolve top-down: the first match wins. If no overrides or customizations exist, Spec Kit uses its core defaults.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new README section explaining how to customize Spec Kit via extensions, presets, and project-local overrides, to help users understand customization options and where they live in the .specify/ structure.
Changes:
- Adds a new “Making Spec Kit Your Own: Extensions & Presets” section, including a Mermaid diagram and guidance on when to use each system.
- Updates the README Table of Contents to link to the new section.
Comments suppressed due to low confidence (1)
README.md:336
- In the diagram, the preset/extension paths and placeholders are inconsistent with the rest of the repo’s documentation about template resolution (e.g.
.specify/presets/<preset-id>/templates/and.specify/extensions/<ext-id>/templates/). As written,.specify/presets/‹preset›/and.specify/extensions/‹ext›/are ambiguous (root vs templates) and use different placeholder naming than existing docs. Consider updating these labels to match the established paths/placeholders so readers can copy/paste and find the right directories.
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"]
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Separate template resolution (top-down, first-match-wins stack) from command registration (written directly into agent directories) - Update Mermaid diagram paths to use <preset-id> and <ext-id> placeholders consistent with existing documentation Addresses PR review feedback on github#1898.
…plates - 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
Contributor
There was a problem hiding this comment.
Pull request overview
Adds introductory documentation explaining how to customize Spec Kit via extensions, presets, and project-local template overrides, and clarifies template-vs-command override behavior.
Changes:
- Added a new “Making Spec Kit Your Own: Extensions & Presets” section to the root README, including a mermaid diagram and usage guidance.
- Clarified in
presets/README.mdthat template resolution happens at runtime and command overrides are applied at install time.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| README.md | Adds an overview section describing the customization stack (core → extensions → presets → overrides) and basic CLI usage. |
| presets/README.md | Refines explanation of runtime template resolution vs install-time command registration for presets. |
Comments suppressed due to low confidence (1)
presets/README.md:24
- “When the preset is removed, the registered commands are cleaned up” could be misleading: removal unlinks the command files that were written at install time, but it does not restore any previous versions that may have been overwritten by the preset (e.g., from core/other presets/extensions). Consider adding a note that users may need to reinstall the desired source to re-register those commands.
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.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…rride description - 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'
Contributor
There was a problem hiding this comment.
Pull request overview
Adds documentation to help users understand how to customize Spec Kit via extensions, presets, and project-local overrides, including a resolution-order diagram and usage guidance.
Changes:
- Adds a new README section explaining extensions vs. presets, including a Mermaid layering diagram and a comparison table.
- Updates the presets README to clarify that template resolution is runtime-based, while command overrides are applied at install time.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| README.md | Adds “Making Spec Kit Your Own: Extensions & Presets” section and links it from the Table of Contents. |
| presets/README.md | Clarifies runtime template resolution and install-time command override behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a new "Making Spec Kit Your Own: Extensions & Presets" section to the README covering: