mirror of
https://github.com/github/spec-kit.git
synced 2026-03-19 20:03:07 +00:00
feat(presets): Pluggable preset system with catalog, resolver, and skills propagation (#1787)
* Initial plan * feat(templates): add pluggable template system with packs, catalog, resolver, and CLI commands Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com> * test(templates): add comprehensive unit tests for template pack system Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com> * 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 * feat(presets): propagate command overrides to skills via init-options - Add save_init_options() / load_init_options() helpers that persist CLI flags from 'specify init' to .specify/init-options.json - PresetManager._register_skills() overwrites SKILL.md files when --ai-skills was used during init and corresponding skill dirs exist - PresetManager._unregister_skills() restores core template content on preset removal - registered_skills stored in preset registry metadata - 8 new tests covering skill override, skip conditions, and restore * fix: address PR check failures (ruff F541, CodeQL URL substring) - Remove extraneous f-prefix from two f-strings without placeholders - Replace substring URL check in test with startswith/endswith assertions to satisfy CodeQL incomplete URL substring sanitization rule * fix: address Copilot PR review comments - Move save_init_options() before preset install so skills propagation works during 'specify init --preset --ai-skills' - Clean up downloaded ZIP after successful preset install during init - Validate --from URL scheme (require HTTPS, HTTP only for localhost) - Expose unregister_commands() on extensions.py CommandRegistrar wrapper instead of reaching into private _registrar field - Use _get_merged_packs() for search() and get_pack_info() so all active catalogs are searched, not just the highest-priority one - Fix fetch_catalog() cache to verify cached URL matches current URL - Fix PresetResolver: script resolution uses .sh extension, consistent file extensions throughout resolve(), and resolve_with_source() delegates to resolve() to honor template_type parameter - Fix bash common.sh: fall through to directory scan when python3 returns empty preset list - Fix PowerShell Resolve-Template: filter out dot-folders and sort extensions deterministically * fix: narrow empty except blocks and add explanatory comments * fix: address Copilot PR review comments (round 2) - Fix init --preset error masking: distinguish "not found" from real errors - Fix bash resolve_template: skip hidden dirs in extensions (match Python/PS) - Fix temp dir leaks in tests: use temp_dir fixture instead of mkdtemp - Fix self-test catalog entry: add note that it's local-only (no download_url) - Fix Windows path issue in resolve_with_source: use Path.relative_to() - Fix skill restore path: use project's .specify/templates/commands/ not source tree - Add encoding="utf-8" to all file read/write in agents.py - Update test to set up core command templates for skill restoration * fix: remove self-test from catalog.json (local-only preset) * fix: address Copilot PR review comments (round 3) - Fix PS Resolve-Template fallback to skip dot-prefixed dirs (.cache) - Rename _catalog to _catalog_name for consistency with extension system - Enforce install_allowed policy in CLI preset add and download_pack() - Fix shell injection: pass registry path via env var instead of string interpolation * fix: correct PresetError docstring from template to preset * Removed CHANGELOG requirement * Applying review recommendations * Applying review recommendations * Applying review recommendations * Applying review recommendations --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>
This commit is contained in:
Copilot
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