mirror of
https://github.com/github/spec-kit.git
synced 2026-03-18 19:33:09 +00:00
feat(presets): pluggable preset system with template/command overrides, catalog, and resolver
- Rename 'template packs' to 'presets' to avoid naming collision with core templates - PresetManifest, PresetRegistry, PresetManager, PresetCatalog, PresetResolver in presets.py - Extract CommandRegistrar to agents.py as shared infrastructure - CLI: specify preset list/add/remove/search/resolve/info - CLI: specify preset catalog list/add/remove - --preset option on specify init - Priority-based preset stacking (--priority, lower = higher precedence) - Command overrides registered into all detected agent directories (17+ agents) - Extension command safety: skip registration if target extension not installed - Multi-catalog support: env var, project config, user config, built-in defaults - resolve_template() / Resolve-Template in bash/PowerShell scripts - Self-test preset: overrides all 6 core templates + 1 command - Scaffold with 4 examples: core/extension template and command overrides - Preset catalog (catalog.json, catalog.community.json) - Documentation: README.md, ARCHITECTURE.md, PUBLISHING.md - 110 preset tests, 253 total tests passing
This commit is contained in:
Manfred Riem
157
presets/ARCHITECTURE.md
Normal file
157
presets/ARCHITECTURE.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# Preset System Architecture
|
||||
|
||||
This document describes the internal architecture of the preset system — how template resolution, command registration, and catalog management work under the hood.
|
||||
|
||||
For usage instructions, see [README.md](README.md).
|
||||
|
||||
## Template Resolution
|
||||
|
||||
When Spec Kit needs a template (e.g. `spec-template`), the `PresetResolver` walks a priority stack and returns the first match:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["resolve_template('spec-template')"] --> B{Override exists?}
|
||||
B -- Yes --> C[".specify/templates/overrides/spec-template.md"]
|
||||
B -- No --> D{Preset provides it?}
|
||||
D -- Yes --> E[".specify/presets/‹preset-id›/templates/spec-template.md"]
|
||||
D -- No --> F{Extension provides it?}
|
||||
F -- Yes --> G[".specify/extensions/‹ext-id›/templates/spec-template.md"]
|
||||
F -- No --> H[".specify/templates/spec-template.md"]
|
||||
|
||||
E -- "multiple presets?" --> I["lowest priority number wins"]
|
||||
I --> E
|
||||
|
||||
style C fill:#4caf50,color:#fff
|
||||
style E fill:#2196f3,color:#fff
|
||||
style G fill:#ff9800,color:#fff
|
||||
style H fill:#9e9e9e,color:#fff
|
||||
```
|
||||
|
||||
| Priority | Source | Path | Use case |
|
||||
|----------|--------|------|----------|
|
||||
| 1 (highest) | Override | `.specify/templates/overrides/` | One-off project-local tweaks |
|
||||
| 2 | Preset | `.specify/presets/<id>/templates/` | Shareable, stackable customizations |
|
||||
| 3 | Extension | `.specify/extensions/<id>/templates/` | Extension-provided templates |
|
||||
| 4 (lowest) | Core | `.specify/templates/` | Shipped defaults |
|
||||
|
||||
When multiple presets are installed, they're sorted by their `priority` field (lower number = higher precedence). This is set via `--priority` on `specify preset add`.
|
||||
|
||||
The resolution is implemented three times to ensure consistency:
|
||||
- **Python**: `PresetResolver` in `src/specify_cli/presets.py`
|
||||
- **Bash**: `resolve_template()` in `scripts/bash/common.sh`
|
||||
- **PowerShell**: `Resolve-Template` in `scripts/powershell/common.ps1`
|
||||
|
||||
## Command Registration
|
||||
|
||||
When a preset is installed with `type: "command"` entries, the `PresetManager` registers them into all detected agent directories using the shared `CommandRegistrar` from `src/specify_cli/agents.py`.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["specify preset add my-preset"] --> B{Preset has type: command?}
|
||||
B -- No --> Z["done (templates only)"]
|
||||
B -- Yes --> C{Extension command?}
|
||||
C -- "speckit.myext.cmd\n(3+ dot segments)" --> D{Extension installed?}
|
||||
D -- No --> E["skip (extension not active)"]
|
||||
D -- Yes --> F["register command"]
|
||||
C -- "speckit.specify\n(core command)" --> F
|
||||
F --> G["detect agent directories"]
|
||||
G --> H[".claude/commands/"]
|
||||
G --> I[".gemini/commands/"]
|
||||
G --> J[".github/agents/"]
|
||||
G --> K["... (17+ agents)"]
|
||||
H --> L["write .md (Markdown format)"]
|
||||
I --> M["write .toml (TOML format)"]
|
||||
J --> N["write .agent.md + .prompt.md"]
|
||||
|
||||
style E fill:#ff5722,color:#fff
|
||||
style L fill:#4caf50,color:#fff
|
||||
style M fill:#4caf50,color:#fff
|
||||
style N fill:#4caf50,color:#fff
|
||||
```
|
||||
|
||||
### Extension safety check
|
||||
|
||||
Command names follow the pattern `speckit.<ext-id>.<cmd-name>`. When a command has 3+ dot segments, the system extracts the extension ID and checks if `.specify/extensions/<ext-id>/` exists. If the extension isn't installed, the command is skipped — preventing orphan files referencing non-existent extensions.
|
||||
|
||||
Core commands (e.g. `speckit.specify`, with only 2 segments) are always registered.
|
||||
|
||||
### Agent format rendering
|
||||
|
||||
The `CommandRegistrar` renders commands differently per agent:
|
||||
|
||||
| Agent | Format | Extension | Arg placeholder |
|
||||
|-------|--------|-----------|-----------------|
|
||||
| Claude, Cursor, opencode, Windsurf, etc. | Markdown | `.md` | `$ARGUMENTS` |
|
||||
| Copilot | Markdown | `.agent.md` + `.prompt.md` | `$ARGUMENTS` |
|
||||
| Gemini, Qwen, Tabnine | TOML | `.toml` | `{{args}}` |
|
||||
|
||||
### Cleanup on removal
|
||||
|
||||
When `specify preset remove` is called, the registered commands are read from the registry metadata and the corresponding files are deleted from each agent directory, including Copilot companion `.prompt.md` files.
|
||||
|
||||
## Catalog System
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["specify preset search"] --> B["PresetCatalog.get_active_catalogs()"]
|
||||
B --> C{SPECKIT_PRESET_CATALOG_URL set?}
|
||||
C -- Yes --> D["single custom catalog"]
|
||||
C -- No --> E{.specify/preset-catalogs.yml exists?}
|
||||
E -- Yes --> F["project-level catalog stack"]
|
||||
E -- No --> G{"~/.specify/preset-catalogs.yml exists?"}
|
||||
G -- Yes --> H["user-level catalog stack"]
|
||||
G -- No --> I["built-in defaults"]
|
||||
I --> J["default (install allowed)"]
|
||||
I --> K["community (discovery only)"]
|
||||
|
||||
style D fill:#ff9800,color:#fff
|
||||
style F fill:#2196f3,color:#fff
|
||||
style H fill:#2196f3,color:#fff
|
||||
style J fill:#4caf50,color:#fff
|
||||
style K fill:#9e9e9e,color:#fff
|
||||
```
|
||||
|
||||
Catalogs are fetched with a 1-hour cache (per-URL, SHA256-hashed cache files). Each catalog entry has a `priority` (for merge ordering) and `install_allowed` flag.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
```
|
||||
presets/
|
||||
├── ARCHITECTURE.md # This file
|
||||
├── PUBLISHING.md # Guide for submitting presets to the catalog
|
||||
├── README.md # User guide
|
||||
├── catalog.json # Official preset catalog
|
||||
├── catalog.community.json # Community preset catalog
|
||||
├── scaffold/ # Scaffold for creating new presets
|
||||
│ ├── preset.yml # Example manifest
|
||||
│ ├── README.md # Guide for customizing the scaffold
|
||||
│ ├── commands/
|
||||
│ │ ├── speckit.specify.md # Core command override example
|
||||
│ │ └── speckit.myext.myextcmd.md # Extension command override example
|
||||
│ └── templates/
|
||||
│ ├── spec-template.md # Core template override example
|
||||
│ └── myext-template.md # Extension template override example
|
||||
└── self-test/ # Self-test preset (overrides all core templates)
|
||||
├── preset.yml
|
||||
├── commands/
|
||||
│ └── speckit.specify.md
|
||||
└── templates/
|
||||
├── spec-template.md
|
||||
├── plan-template.md
|
||||
├── tasks-template.md
|
||||
├── checklist-template.md
|
||||
├── constitution-template.md
|
||||
└── agent-file-template.md
|
||||
```
|
||||
|
||||
## Module Structure
|
||||
|
||||
```
|
||||
src/specify_cli/
|
||||
├── agents.py # CommandRegistrar — shared infrastructure for writing
|
||||
│ # command files to agent directories
|
||||
├── presets.py # PresetManifest, PresetRegistry, PresetManager,
|
||||
│ # PresetCatalog, PresetCatalogEntry, PresetResolver
|
||||
└── __init__.py # CLI commands: specify preset list/add/remove/search/
|
||||
# resolve/info, specify preset catalog list/add/remove
|
||||
```
|
||||
Reference in New Issue
Block a user