π« Toolkit to help you get started with SDD or any other process!
docs: Add Extensions & Presets section to README (#1898)
Manfred Riem497b5885e18e
diff --git a/README.md b/README.mdindex c958002bb..c70de1bae 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)@@ -326,6 +327,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.<br/>\*\*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 β **extensions** and **presets** β plus project-local overrides for one-off adjustments:++```mermaid+block-beta+ columns 1+ overrides["β¬ Highest priority\nProject-Local Overrides\n.specify/templates/overrides/"]+ presets["Presets β Customize core & extensions\n.specify/presets/<preset-id>/templates/"]+ extensions["Extensions β Add new capabilities\n.specify/extensions/<ext-id>/templates/"]+ 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** 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++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 <extension-name>+```++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 <preset-name>+```++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 PhilosophySpec-Driven Development is a structured process that emphasizes:diff --git a/presets/README.md b/presets/README.mdindex 2fb22a71f..f039b83d4 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 staIf no preset is installed, core templates are used β exactly the same behavior as before presets existed.+Template resolution happens **at runtime** β although preset files are copied into `.specify/presets/<id>/` 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).## Command OverridesPresets 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