|
| 1 | +# Preset System Architecture |
| 2 | + |
| 3 | +This document describes the internal architecture of the preset system — how template resolution, command registration, and catalog management work under the hood. |
| 4 | + |
| 5 | +For usage instructions, see [README.md](README.md). |
| 6 | + |
| 7 | +## Template Resolution |
| 8 | + |
| 9 | +When Spec Kit needs a template (e.g. `spec-template`), the `PresetResolver` walks a priority stack and returns the first match: |
| 10 | + |
| 11 | +```mermaid |
| 12 | +flowchart TD |
| 13 | + A["resolve_template('spec-template')"] --> B{Override exists?} |
| 14 | + B -- Yes --> C[".specify/templates/overrides/spec-template.md"] |
| 15 | + B -- No --> D{Preset provides it?} |
| 16 | + D -- Yes --> E[".specify/presets/‹preset-id›/templates/spec-template.md"] |
| 17 | + D -- No --> F{Extension provides it?} |
| 18 | + F -- Yes --> G[".specify/extensions/‹ext-id›/templates/spec-template.md"] |
| 19 | + F -- No --> H[".specify/templates/spec-template.md"] |
| 20 | +
|
| 21 | + E -- "multiple presets?" --> I["lowest priority number wins"] |
| 22 | + I --> E |
| 23 | +
|
| 24 | + style C fill:#4caf50,color:#fff |
| 25 | + style E fill:#2196f3,color:#fff |
| 26 | + style G fill:#ff9800,color:#fff |
| 27 | + style H fill:#9e9e9e,color:#fff |
| 28 | +``` |
| 29 | + |
| 30 | +| Priority | Source | Path | Use case | |
| 31 | +|----------|--------|------|----------| |
| 32 | +| 1 (highest) | Override | `.specify/templates/overrides/` | One-off project-local tweaks | |
| 33 | +| 2 | Preset | `.specify/presets/<id>/templates/` | Shareable, stackable customizations | |
| 34 | +| 3 | Extension | `.specify/extensions/<id>/templates/` | Extension-provided templates | |
| 35 | +| 4 (lowest) | Core | `.specify/templates/` | Shipped defaults | |
| 36 | + |
| 37 | +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`. |
| 38 | + |
| 39 | +The resolution is implemented three times to ensure consistency: |
| 40 | +- **Python**: `PresetResolver` in `src/specify_cli/presets.py` |
| 41 | +- **Bash**: `resolve_template()` in `scripts/bash/common.sh` |
| 42 | +- **PowerShell**: `Resolve-Template` in `scripts/powershell/common.ps1` |
| 43 | + |
| 44 | +## Command Registration |
| 45 | + |
| 46 | +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`. |
| 47 | + |
| 48 | +```mermaid |
| 49 | +flowchart TD |
| 50 | + A["specify preset add my-preset"] --> B{Preset has type: command?} |
| 51 | + B -- No --> Z["done (templates only)"] |
| 52 | + B -- Yes --> C{Extension command?} |
| 53 | + C -- "speckit.myext.cmd\n(3+ dot segments)" --> D{Extension installed?} |
| 54 | + D -- No --> E["skip (extension not active)"] |
| 55 | + D -- Yes --> F["register command"] |
| 56 | + C -- "speckit.specify\n(core command)" --> F |
| 57 | + F --> G["detect agent directories"] |
| 58 | + G --> H[".claude/commands/"] |
| 59 | + G --> I[".gemini/commands/"] |
| 60 | + G --> J[".github/agents/"] |
| 61 | + G --> K["... (17+ agents)"] |
| 62 | + H --> L["write .md (Markdown format)"] |
| 63 | + I --> M["write .toml (TOML format)"] |
| 64 | + J --> N["write .agent.md + .prompt.md"] |
| 65 | +
|
| 66 | + style E fill:#ff5722,color:#fff |
| 67 | + style L fill:#4caf50,color:#fff |
| 68 | + style M fill:#4caf50,color:#fff |
| 69 | + style N fill:#4caf50,color:#fff |
| 70 | +``` |
| 71 | + |
| 72 | +### Extension safety check |
| 73 | + |
| 74 | +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. |
| 75 | + |
| 76 | +Core commands (e.g. `speckit.specify`, with only 2 segments) are always registered. |
| 77 | + |
| 78 | +### Agent format rendering |
| 79 | + |
| 80 | +The `CommandRegistrar` renders commands differently per agent: |
| 81 | + |
| 82 | +| Agent | Format | Extension | Arg placeholder | |
| 83 | +|-------|--------|-----------|-----------------| |
| 84 | +| Claude, Cursor, opencode, Windsurf, etc. | Markdown | `.md` | `$ARGUMENTS` | |
| 85 | +| Copilot | Markdown | `.agent.md` + `.prompt.md` | `$ARGUMENTS` | |
| 86 | +| Gemini, Qwen, Tabnine | TOML | `.toml` | `{{args}}` | |
| 87 | + |
| 88 | +### Cleanup on removal |
| 89 | + |
| 90 | +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. |
| 91 | + |
| 92 | +## Catalog System |
| 93 | + |
| 94 | +```mermaid |
| 95 | +flowchart TD |
| 96 | + A["specify preset search"] --> B["PresetCatalog.get_active_catalogs()"] |
| 97 | + B --> C{SPECKIT_PRESET_CATALOG_URL set?} |
| 98 | + C -- Yes --> D["single custom catalog"] |
| 99 | + C -- No --> E{.specify/preset-catalogs.yml exists?} |
| 100 | + E -- Yes --> F["project-level catalog stack"] |
| 101 | + E -- No --> G{"~/.specify/preset-catalogs.yml exists?"} |
| 102 | + G -- Yes --> H["user-level catalog stack"] |
| 103 | + G -- No --> I["built-in defaults"] |
| 104 | + I --> J["default (install allowed)"] |
| 105 | + I --> K["community (discovery only)"] |
| 106 | +
|
| 107 | + style D fill:#ff9800,color:#fff |
| 108 | + style F fill:#2196f3,color:#fff |
| 109 | + style H fill:#2196f3,color:#fff |
| 110 | + style J fill:#4caf50,color:#fff |
| 111 | + style K fill:#9e9e9e,color:#fff |
| 112 | +``` |
| 113 | + |
| 114 | +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. |
| 115 | + |
| 116 | +## Repository Layout |
| 117 | + |
| 118 | +``` |
| 119 | +presets/ |
| 120 | +├── ARCHITECTURE.md # This file |
| 121 | +├── PUBLISHING.md # Guide for submitting presets to the catalog |
| 122 | +├── README.md # User guide |
| 123 | +├── catalog.json # Official preset catalog |
| 124 | +├── catalog.community.json # Community preset catalog |
| 125 | +├── scaffold/ # Scaffold for creating new presets |
| 126 | +│ ├── preset.yml # Example manifest |
| 127 | +│ ├── README.md # Guide for customizing the scaffold |
| 128 | +│ ├── commands/ |
| 129 | +│ │ ├── speckit.specify.md # Core command override example |
| 130 | +│ │ └── speckit.myext.myextcmd.md # Extension command override example |
| 131 | +│ └── templates/ |
| 132 | +│ ├── spec-template.md # Core template override example |
| 133 | +│ └── myext-template.md # Extension template override example |
| 134 | +└── self-test/ # Self-test preset (overrides all core templates) |
| 135 | + ├── preset.yml |
| 136 | + ├── commands/ |
| 137 | + │ └── speckit.specify.md |
| 138 | + └── templates/ |
| 139 | + ├── spec-template.md |
| 140 | + ├── plan-template.md |
| 141 | + ├── tasks-template.md |
| 142 | + ├── checklist-template.md |
| 143 | + ├── constitution-template.md |
| 144 | + └── agent-file-template.md |
| 145 | +``` |
| 146 | + |
| 147 | +## Module Structure |
| 148 | + |
| 149 | +``` |
| 150 | +src/specify_cli/ |
| 151 | +├── agents.py # CommandRegistrar — shared infrastructure for writing |
| 152 | +│ # command files to agent directories |
| 153 | +├── presets.py # PresetManifest, PresetRegistry, PresetManager, |
| 154 | +│ # PresetCatalog, PresetCatalogEntry, PresetResolver |
| 155 | +└── __init__.py # CLI commands: specify preset list/add/remove/search/ |
| 156 | + # resolve/info, specify preset catalog list/add/remove |
| 157 | +``` |
0 commit comments