Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

feat(presets): Pluggable preset system with catalog, resolver, and skills propagation (#1787)

Copilot69ee7a836e25
diff --git a/AGENTS.md b/AGENTS.md
index 82b444b14..8f0742eb8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,10 +10,6 @@ The toolkit supports multiple AI coding assistants, allowing teams to use their
---
-## General practices
-
-- Any changes to `__init__.py` for the Specify CLI require a version rev in `pyproject.toml` and addition of entries to `CHANGELOG.md`.
-
## Adding New Agent Support
This section explains how to add support for new AI agents/assistants to the Specify CLI. Use this guide as a reference when integrating new AI tools into the Spec-Driven Development workflow.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 536b80847..89918e4c4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,27 @@ Recent changes to the Specify CLI and templates are documented here.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [Unreleased]
+
+### Added
+
+- feat(presets): Pluggable preset system with preset catalog and template resolver
+- Preset manifest (`preset.yml`) with validation for artifact, command, and script types
+- `PresetManifest`, `PresetRegistry`, `PresetManager`, `PresetCatalog`, `PresetResolver` classes in `src/specify_cli/presets.py`
+- CLI commands: `specify preset search`, `specify preset add`, `specify preset list`, `specify preset remove`, `specify preset resolve`, `specify preset info`
+- CLI commands: `specify preset catalog list`, `specify preset catalog add`, `specify preset catalog remove` for multi-catalog management
+- `PresetCatalogEntry` dataclass and multi-catalog support mirroring the extension catalog system
+- `--preset` option for `specify init` to install presets during initialization
+- Priority-based preset resolution: presets with lower priority number win (`--priority` flag)
+- `resolve_template()` / `Resolve-Template` helpers in bash and PowerShell common scripts
+- Template resolution priority stack: overrides β†’ presets β†’ extensions β†’ core
+- Preset catalog files (`presets/catalog.json`, `presets/catalog.community.json`)
+- Preset scaffold directory (`presets/scaffold/`)
+- Scripts updated to use template resolution instead of hardcoded paths
+- feat(presets): Preset command overrides now propagate to agent skills when `--ai-skills` was used during init
+- feat: `specify init` persists CLI options to `.specify/init-options.json` for downstream operations
+- feat(extensions): support `.extensionignore` to exclude files/folders during `specify extension add` (#1781)
+
## [0.2.1] - 2026-03-11
### Changed
@@ -51,13 +72,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- fix: release-trigger uses release branch + PR instead of direct push to main (#1733)
- fix: Split release process to sync pyproject.toml version with git tags (#1732)
-
-## [Unreleased]
-
-### Added
-
-- feat(extensions): support `.extensionignore` to exclude files/folders during `specify extension add` (#1781)
-
## [0.2.0] - 2026-03-09
### Changed
diff --git a/presets/ARCHITECTURE.md b/presets/ARCHITECTURE.md
new file mode 100644
index 000000000..d0e654781
--- /dev/null
+++ b/presets/ARCHITECTURE.md
@@ -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
+```
diff --git a/presets/PUBLISHING.md b/presets/PUBLISHING.md
new file mode 100644
index 000000000..5e91c4b78
--- /dev/null
+++ b/presets/PUBLISHING.md
@@ -0,0 +1,295 @@
+# Preset Publishing Guide
+
+This guide explains how to publish your preset to the Spec Kit preset catalog, making it discoverable by `specify preset search`.
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Prepare Your Preset](#prepare-your-preset)
+3. [Submit to Catalog](#submit-to-catalog)
+4. [Verification Process](#verification-process)
+5. [Release Workflow](#release-workflow)
+6. [Best Practices](#best-practices)
+
+---
+
+## Prerequisites
+
+Before publishing a preset, ensure you have:
+
+1. **Valid Preset**: A working preset with a valid `preset.yml` manifest
+2. **Git Repository**: Preset hosted on GitHub (or other public git hosting)
+3. **Documentation**: README.md with description and usage instructions
+4. **License**: Open source license file (MIT, Apache 2.0, etc.)
+5. **Versioning**: Semantic versioning (e.g., 1.0.0)
+6. **Testing**: Preset tested on real projects with `specify preset add --dev`
+
+---
+
+## Prepare Your Preset
+
+### 1. Preset Structure
+
+Ensure your preset follows the standard structure:
+
+```text
+your-preset/
+β”œβ”€β”€ preset.yml # Required: Preset manifest
+β”œβ”€β”€ README.md # Required: Documentation
+β”œβ”€β”€ LICENSE # Required: License file
+β”œβ”€β”€ CHANGELOG.md # Recommended: Version history
+β”‚
+β”œβ”€β”€ templates/ # Template overrides
+β”‚ β”œβ”€β”€ spec-template.md
+β”‚ β”œβ”€β”€ plan-template.md
+β”‚ └── ...
+β”‚
+└── commands/ # Command overrides (optional)
+ └── speckit.specify.md
+```
+
+Start from the [scaffold](scaffold/) if you're creating a new preset.
+
+### 2. preset.yml Validation
+
+Verify your manifest is valid:
+
+```yaml
+schema_version: "1.0"
+
+preset:
+ id: "your-preset" # Unique lowercase-hyphenated ID
+ name: "Your Preset Name" # Human-readable name
+ version: "1.0.0" # Semantic version
+ description: "Brief description (one sentence)"
+ author: "Your Name or Organization"
+ repository: "https://github.com/your-org/spec-kit-preset-your-preset"
+ license: "MIT"
+
+requires:
+ speckit_version: ">=0.1.0" # Required spec-kit version
+
+provides:
+ templates:
+ - type: "template"
+ name: "spec-template"
+ file: "templates/spec-template.md"
+ description: "Custom spec template"
+ replaces: "spec-template"
+
+tags: # 2-5 relevant tags
+ - "category"
+ - "workflow"
+```
+
+**Validation Checklist**:
+
+- βœ… `id` is lowercase with hyphens only (no underscores, spaces, or special characters)
+- βœ… `version` follows semantic versioning (X.Y.Z)
+- βœ… `description` is concise (under 200 characters)
+- βœ… `repository` URL is valid and public
+- βœ… All template and command files exist in the preset directory
+- βœ… Template names are lowercase with hyphens only
+- βœ… Command names use dot notation (e.g. `speckit.specify`)
+- βœ… Tags are lowercase and descriptive
+
+### 3. Test Locally
+
+```bash
+# Install from local directory
+specify preset add --dev /path/to/your-preset
+
+# Verify templates resolve from your preset
+specify preset resolve spec-template
+
+# Verify preset info
+specify preset info your-preset
+
+# List installed presets
+specify preset list
+
+# Remove when done testing
+specify preset remove your-preset
+```
+
+If your preset includes command overrides, verify they appear in the agent directories:
+
+```bash
+# Check Claude commands (if using Claude)
+ls .claude/commands/speckit.*.md
+
+# Check Copilot commands (if using Copilot)
+ls .github/agents/speckit.*.agent.md
+
+# Check Gemini commands (if using Gemini)
+ls .gemini/commands/speckit.*.toml
+```
+
+### 4. Create GitHub Release
+
+Create a GitHub release for your preset version:
+
+```bash
+# Tag the release
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+The release archive URL will be:
+
+```text
+https://github.com/your-org/spec-kit-preset-your-preset/archive/refs/tags/v1.0.0.zip
+```
+
+### 5. Test Installation from Archive
+
+```bash
+specify preset add --from https://github.com/your-org/spec-kit-preset-your-preset/archive/refs/tags/v1.0.0.zip
+```
+
+---
+
+## Submit to Catalog
+
+### Understanding the Catalogs
+
+Spec Kit uses a dual-catalog system:
+
+- **`catalog.json`** β€” Official, verified presets (install allowed by default)
+- **`catalog.community.json`** β€” Community-contributed presets (discovery only by default)
+
+All community presets should be submitted to `catalog.community.json`.
+
+### 1. Fork the spec-kit Repository
+
+```bash
+git clone https://github.com/YOUR-USERNAME/spec-kit.git
+cd spec-kit
+```
+
+### 2. Add Preset to Community Catalog
+
+Edit `presets/catalog.community.json` and add your preset.
+
+> **⚠️ Entries must be sorted alphabetically by preset ID.** Insert your preset in the correct position within the `"presets"` object.
+
+```json
+{
+ "schema_version": "1.0",
+ "updated_at": "2026-03-10T00:00:00Z",
+ "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json",
+ "presets": {
+ "your-preset": {
+ "name": "Your Preset Name",
+ "description": "Brief description of what your preset provides",
+ "author": "Your Name",
+ "version": "1.0.0",
+ "download_url": "https://github.com/your-org/spec-kit-preset-your-preset/archive/refs/tags/v1.0.0.zip",
+ "repository": "https://github.com/your-org/spec-kit-preset-your-preset",
+ "license": "MIT",
+ "requires": {
+ "speckit_version": ">=0.1.0"
+ },
+ "provides": {
+ "templates": 3,
+ "commands": 1
+ },
+ "tags": [
+ "category",
+ "workflow"
+ ],
+ "created_at": "2026-03-10T00:00:00Z",
+ "updated_at": "2026-03-10T00:00:00Z"
+ }
+ }
+}
+```
+
+### 3. Submit Pull Request
+
+```bash
+git checkout -b add-your-preset
+git add presets/catalog.community.json
+git commit -m "Add your-preset to community catalog
+
+- Preset ID: your-preset
+- Version: 1.0.0
+- Author: Your Name
+- Description: Brief description
+"
+git push origin add-your-preset
+```
+
+**Pull Request Checklist**:
+
+```markdown
+## Preset Submission
+
+**Preset Name**: Your Preset Name
+**Preset ID**: your-preset
+**Version**: 1.0.0
+**Repository**: https://github.com/your-org/spec-kit-preset-your-preset
+
+### Checklist
+- [ ] Valid preset.yml manifest
+- [ ] README.md with description and usage
+- [ ] LICENSE file included
+- [ ] GitHub release created
+- [ ] Preset tested with `specify preset add --dev`
+- [ ] Templates resolve correctly (`specify preset resolve`)
+- [ ] Commands register to agent directories (if applicable)
+- [ ] Commands match template sections (command + template are coherent)
+- [ ] Added to presets/catalog.community.json
+```
+
+---
+
+## Verification Process
+
+After submission, maintainers will review:
+
+1. **Manifest validation** β€” valid `preset.yml`, all files exist
+2. **Template quality** β€” templates are useful and well-structured
+3. **Command coherence** β€” commands reference sections that exist in templates
+4. **Security** β€” no malicious content, safe file operations
+5. **Documentation** β€” clear README explaining what the preset does
+
+Once verified, `verified: true` is set and the preset appears in `specify preset search`.
+
+---
+
+## Release Workflow
+
+When releasing a new version:
+
+1. Update `version` in `preset.yml`
+2. Update CHANGELOG.md
+3. Tag and push: `git tag v1.1.0 && git push origin v1.1.0`
+4. Submit PR to update `version` and `download_url` in `presets/catalog.community.json`
+
+---
+
+## Best Practices
+
+### Template Design
+
+- **Keep sections clear** β€” use headings and placeholder text the LLM can replace
+- **Match commands to templates** β€” if your preset overrides a command, make sure it references the sections in your template
+- **Document customization points** β€” use HTML comments to guide users on what to change
+
+### Naming
+
+- Preset IDs should be descriptive: `healthcare-compliance`, `enterprise-safe`, `startup-lean`
+- Avoid generic names: `my-preset`, `custom`, `test`
+
+### Stacking
+
+- Design presets to work well when stacked with others
+- Only override templates you need to change
+- Document which templates and commands your preset modifies
+
+### Command Overrides
+
+- Only override commands when the workflow needs to change, not just the output format
+- If you only need different template sections, a template override is sufficient
+- Test command overrides with multiple agents (Claude, Gemini, Copilot)
diff --git a/presets/README.md b/presets/README.md
new file mode 100644
index 000000000..2fb22a71f
--- /dev/null
+++ b/presets/README.md
@@ -0,0 +1,115 @@
+# Presets
+
+Presets are stackable, priority-ordered collections of template and command overrides for Spec Kit. They let you customize both the artifacts produced by the Spec-Driven Development workflow (specs, plans, tasks, checklists, constitutions) and the commands that guide the LLM in creating them β€” without forking or modifying core files.
+
+## How It Works
+
+When Spec Kit needs a template (e.g. `spec-template`), it walks a resolution stack:
+
+1. `.specify/templates/overrides/` β€” project-local one-off overrides
+2. `.specify/presets/<preset-id>/templates/` β€” installed presets (sorted by priority)
+3. `.specify/extensions/<ext-id>/templates/` β€” extension-provided templates
+4. `.specify/templates/` β€” core templates shipped with Spec Kit
+
+If no preset is installed, core templates are used β€” exactly the same behavior as before presets existed.
+
+For detailed resolution and command registration flows, see [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Command Overrides
+
+Presets 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.
+
+## Quick Start
+
+```bash
+# Search available presets
+specify preset search
+
+# Install a preset from the catalog
+specify preset add healthcare-compliance
+
+# Install from a local directory (for development)
+specify preset add --dev ./my-preset
+
+# Install with a specific priority (lower = higher precedence)
+specify preset add healthcare-compliance --priority 5
+
+# List installed presets
+specify preset list
+
+# See which template a name resolves to
+specify preset resolve spec-template
+
+# Get detailed info about a preset
+specify preset info healthcare-compliance
+
+# Remove a preset
+specify preset remove healthcare-compliance
+```
+
+## Stacking Presets
+
+Multiple presets can be installed simultaneously. The `--priority` flag controls which one wins when two presets provide the same template (lower number = higher precedence):
+
+```bash
+specify preset add enterprise-safe --priority 10 # base layer
+specify preset add healthcare-compliance --priority 5 # overrides enterprise-safe
+specify preset add pm-workflow --priority 1 # overrides everything
+```
+
+Presets **override**, they don't merge. If two presets both provide `spec-template`, the one with the lowest priority number wins entirely.
+
+## Catalog Management
+
+Presets are discovered through catalogs. By default, Spec Kit uses the official and community catalogs:
+
+```bash
+# List active catalogs
+specify preset catalog list
+
+# Add a custom catalog
+specify preset catalog add https://example.com/catalog.json --name my-org --install-allowed
+
+# Remove a catalog
+specify preset catalog remove my-org
+```
+
+## Creating a Preset
+
+See [scaffold/](scaffold/) for a scaffold you can copy to create your own preset.
+
+1. Copy `scaffold/` to a new directory
+2. Edit `preset.yml` with your preset's metadata
+3. Add or replace templates in `templates/`
+4. Test locally with `specify preset add --dev .`
+5. Verify with `specify preset resolve spec-template`
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SPECKIT_PRESET_CATALOG_URL` | Override the catalog URL (replaces all defaults) |
+
+## Configuration Files
+
+| File | Scope | Description |
+|------|-------|-------------|
+| `.specify/preset-catalogs.yml` | Project | Custom catalog stack for this project |
+| `~/.specify/preset-catalogs.yml` | User | Custom catalog stack for all projects |
+
+## Future Considerations
+
+The following enhancements are under consideration for future releases:
+
+- **Composition strategies** β€” Allow presets to declare a `strategy` per template instead of the default `replace`:
+
+ | Type | `replace` | `prepend` | `append` | `wrap` |
+ |------|-----------|-----------|----------|--------|
+ | **template** | βœ“ (default) | βœ“ | βœ“ | βœ“ |
+ | **command** | βœ“ (default) | βœ“ | βœ“ | βœ“ |
+ | **script** | βœ“ (default) | β€” | β€” | βœ“ |
+
+ For artifacts and commands (which are LLM directives), `wrap` would inject preset content before and after the core template using a `{CORE_TEMPLATE}` placeholder. For scripts, `wrap` would run custom logic before/after the core script via a `$CORE_SCRIPT` variable.
+- **Script overrides** β€” Enable presets to provide alternative versions of core scripts (e.g. `create-new-feature.sh`) for workflow customization. A `strategy: "wrap"` option could allow presets to run custom logic before/after the core script without fully replacing it.
diff --git a/presets/catalog.community.json b/presets/catalog.community.json
new file mode 100644
index 000000000..368f208b7
--- /dev/null
+++ b/presets/catalog.community.json
@@ -0,0 +1,6 @@
+{
+ "schema_version": "1.0",
+ "updated_at": "2026-03-09T00:00:00Z",
+ "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json",
+ "presets": {}
+}
diff --git a/presets/catalog.json b/presets/catalog.json
new file mode 100644
index 000000000..ca40f8528
--- /dev/null
+++ b/presets/catalog.json
@@ -0,0 +1,6 @@
+{
+ "schema_version": "1.0",
+ "updated_at": "2026-03-10T00:00:00Z",
+ "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.json",
+ "presets": {}
+}
diff --git a/presets/scaffold/README.md b/presets/scaffold/README.md
new file mode 100644
index 000000000..b30a1ab6a
--- /dev/null
+++ b/presets/scaffold/README.md
@@ -0,0 +1,46 @@
+# My Preset
+
+A custom preset for Spec Kit. Copy this directory and customize it to create your own.
+
+## Templates Included
+
+| Template | Type | Description |
+|----------|------|-------------|
+| `spec-template` | template | Custom feature specification template (overrides core and extensions) |
+| `myext-template` | template | Override of the myext extension's report template |
+| `speckit.specify` | command | Custom specification command (overrides core) |
+| `speckit.myext.myextcmd` | command | Override of the myext extension's myextcmd command |
+
+## Development
+
+1. Copy this directory: `cp -r presets/scaffold my-preset`
+2. Edit `preset.yml` β€” set your preset's ID, name, description, and templates
+3. Add or modify templates in `templates/`
+4. Test locally: `specify preset add --dev ./my-preset`
+5. Verify resolution: `specify preset resolve spec-template`
+6. Remove when done testing: `specify preset remove my-preset`
+
+## Manifest Reference (`preset.yml`)
+
+Required fields:
+- `schema_version` β€” always `"1.0"`
+- `preset.id` β€” lowercase alphanumeric with hyphens
+- `preset.name` β€” human-readable name
+- `preset.version` β€” semantic version (e.g. `1.0.0`)
+- `preset.description` β€” brief description
+- `requires.speckit_version` β€” version constraint (e.g. `>=0.1.0`)
+- `provides.templates` β€” list of templates with `type`, `name`, and `file`
+
+## Template Types
+
+- **template** β€” Document scaffolds (spec-template.md, plan-template.md, tasks-template.md, etc.)
+- **command** β€” AI agent workflow prompts (e.g. speckit.specify, speckit.plan)
+- **script** β€” Custom scripts (reserved for future use)
+
+## Publishing
+
+See the [Preset Publishing Guide](../PUBLISHING.md) for details on submitting to the catalog.
+
+## License
+
+MIT
diff --git a/presets/scaffold/commands/speckit.myext.myextcmd.md b/presets/scaffold/commands/speckit.myext.myextcmd.md
new file mode 100644
index 000000000..5adef240b
--- /dev/null
+++ b/presets/scaffold/commands/speckit.myext.myextcmd.md
@@ -0,0 +1,20 @@
+---
+description: "Override of the myext extension's myextcmd command"
+---
+
+<!-- Preset override for speckit.myext.myextcmd -->
+
+You are following a customized version of the myext extension's myextcmd command.
+
+When executing this command:
+
+1. Read the user's input from $ARGUMENTS
+2. Follow the standard myextcmd workflow
+3. Additionally, apply the following customizations from this preset:
+ - Add compliance checks before proceeding
+ - Include audit trail entries in the output
+
+> CUSTOMIZE: Replace the instructions above with your own.
+> This file overrides the command that the "myext" extension provides.
+> When this preset is installed, all agents (Claude, Gemini, Copilot, etc.)
+> will use this version instead of the extension's original.
diff --git a/presets/scaffold/commands/speckit.specify.md b/presets/scaffold/commands/speckit.specify.md
new file mode 100644
index 000000000..7926cc138
--- /dev/null
+++ b/presets/scaffold/commands/speckit.specify.md
@@ -0,0 +1,23 @@
+---
+description: "Create a feature specification (preset override)"
+scripts:
+ sh: scripts/bash/create-new-feature.sh "{ARGS}"
+ ps: scripts/powershell/create-new-feature.ps1 "{ARGS}"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+Given the feature description above:
+
+1. **Create the feature branch** by running the script:
+ - Bash: `{SCRIPT} --json --short-name "<short-name>" "<description>"`
+ - The JSON output contains BRANCH_NAME and SPEC_FILE paths.
+
+2. **Read the spec-template** to see the sections you need to fill.
+
+3. **Write the specification** to SPEC_FILE, replacing the placeholders in each section
+ (Overview, Requirements, Acceptance Criteria) with details from the user's description.
diff --git a/presets/scaffold/preset.yml b/presets/scaffold/preset.yml
new file mode 100644
index 000000000..975a92a41
--- /dev/null
+++ b/presets/scaffold/preset.yml
@@ -0,0 +1,91 @@
+schema_version: "1.0"
+
+preset:
+ # CUSTOMIZE: Change 'my-preset' to your preset ID (lowercase, hyphen-separated)
+ id: "my-preset"
+
+ # CUSTOMIZE: Human-readable name for your preset
+ name: "My Preset"
+
+ # CUSTOMIZE: Update version when releasing (semantic versioning: X.Y.Z)
+ version: "1.0.0"
+
+ # CUSTOMIZE: Brief description (under 200 characters)
+ description: "Brief description of what your preset provides"
+
+ # CUSTOMIZE: Your name or organization name
+ author: "Your Name"
+
+ # CUSTOMIZE: GitHub repository URL (create before publishing)
+ repository: "https://github.com/your-org/spec-kit-preset-my-preset"
+
+ # REVIEW: License (MIT is recommended for open source)
+ license: "MIT"
+
+# Requirements for this preset
+requires:
+ # CUSTOMIZE: Minimum spec-kit version required
+ speckit_version: ">=0.1.0"
+
+# Templates provided by this preset
+provides:
+ templates:
+ # CUSTOMIZE: Define your template overrides
+ # Templates are document scaffolds (spec-template.md, plan-template.md, etc.)
+ - type: "template"
+ name: "spec-template"
+ file: "templates/spec-template.md"
+ description: "Custom feature specification template"
+ replaces: "spec-template" # Which core template this overrides (optional)
+
+ # ADD MORE TEMPLATES: Copy this block for each template
+ # - type: "template"
+ # name: "plan-template"
+ # file: "templates/plan-template.md"
+ # description: "Custom plan template"
+ # replaces: "plan-template"
+
+ # OVERRIDE EXTENSION TEMPLATES:
+ # Presets sit above extensions in the resolution stack, so you can
+ # override templates provided by any installed extension.
+ # For example, if the "myext" extension provides a spec-template,
+ # the preset's version above will take priority automatically.
+
+ # Override a template provided by the "myext" extension:
+ - type: "template"
+ name: "myext-template"
+ file: "templates/myext-template.md"
+ description: "Override myext's report template"
+ replaces: "myext-template"
+
+ # Command overrides (AI agent workflow prompts)
+ # Presets can override both core and extension commands.
+ # Commands are automatically registered into all detected agent
+ # directories (.claude/commands/, .gemini/commands/, etc.)
+
+ # Override a core command:
+ - type: "command"
+ name: "speckit.specify"
+ file: "commands/speckit.specify.md"
+ description: "Custom specification command"
+ replaces: "speckit.specify"
+
+ # Override an extension command (e.g. from the "myext" extension):
+ - type: "command"
+ name: "speckit.myext.myextcmd"
+ file: "commands/speckit.myext.myextcmd.md"
+ description: "Override myext's myextcmd command with custom workflow"
+ replaces: "speckit.myext.myextcmd"
+
+ # Script templates (reserved for future use)
+ # - type: "script"
+ # name: "create-new-feature"
+ # file: "scripts/bash/create-new-feature.sh"
+ # description: "Custom feature creation script"
+ # replaces: "create-new-feature"
+
+# CUSTOMIZE: Add relevant tags (2-5 recommended)
+# Used for discovery in catalog
+tags:
+ - "example"
+ - "preset"
diff --git a/presets/scaffold/templates/myext-template.md b/presets/scaffold/templates/myext-template.md
new file mode 100644
index 000000000..2b4f5a3fe
--- /dev/null
+++ b/presets/scaffold/templates/myext-template.md
@@ -0,0 +1,24 @@
+# MyExt Report
+
+> This template overrides the one provided by the "myext" extension.
+> Customize it to match your needs.
+
+## Summary
+
+Brief summary of the report.
+
+## Details
+
+- Detail 1
+- Detail 2
+
+## Actions
+
+- [ ] Action 1
+- [ ] Action 2
+
+<!--
+ CUSTOMIZE: This template takes priority over the myext extension's
+ version of myext-template. The extension's original is still available
+ if you remove this preset.
+-->
diff --git a/presets/scaffold/templates/spec-template.md b/presets/scaffold/templates/spec-template.md
new file mode 100644
index 000000000..432bca3cc
--- /dev/null
+++ b/presets/scaffold/templates/spec-template.md
@@ -0,0 +1,18 @@
+# Feature Specification: [FEATURE NAME]
+
+**Created**: [DATE]
+**Status**: Draft
+
+## Overview
+
+[Brief description of the feature]
+
+## Requirements
+
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
diff --git a/presets/self-test/commands/speckit.specify.md b/presets/self-test/commands/speckit.specify.md
new file mode 100644
index 000000000..d5e2c7488
--- /dev/null
+++ b/presets/self-test/commands/speckit.specify.md
@@ -0,0 +1,15 @@
+---
+description: "Self-test override of the specify command"
+---
+
+<!-- preset:self-test -->
+
+You are following the self-test preset's version of the specify command.
+
+When creating a specification, follow this process:
+
+1. Read the user's requirements from $ARGUMENTS
+2. Create a specification document using the spec-template
+3. Include all standard sections plus the self-test marker
+
+> This command is provided by the self-test preset.
diff --git a/presets/self-test/preset.yml b/presets/self-test/preset.yml
new file mode 100644
index 000000000..82c7b068a
--- /dev/null
+++ b/presets/self-test/preset.yml
@@ -0,0 +1,61 @@
+schema_version: "1.0"
+
+preset:
+ id: "self-test"
+ name: "Self-Test Preset"
+ version: "1.0.0"
+ description: "A preset that overrides all core templates for testing purposes"
+ author: "github"
+ repository: "https://github.com/github/spec-kit"
+ license: "MIT"
+
+requires:
+ speckit_version: ">=0.1.0"
+
+provides:
+ templates:
+ - type: "template"
+ name: "spec-template"
+ file: "templates/spec-template.md"
+ description: "Self-test spec template"
+ replaces: "spec-template"
+
+ - type: "template"
+ name: "plan-template"
+ file: "templates/plan-template.md"
+ description: "Self-test plan template"
+ replaces: "plan-template"
+
+ - type: "template"
+ name: "tasks-template"
+ file: "templates/tasks-template.md"
+ description: "Self-test tasks template"
+ replaces: "tasks-template"
+
+ - type: "template"
+ name: "checklist-template"
+ file: "templates/checklist-template.md"
+ description: "Self-test checklist template"
+ replaces: "checklist-template"
+
+ - type: "template"
+ name: "constitution-template"
+ file: "templates/constitution-template.md"
+ description: "Self-test constitution template"
+ replaces: "constitution-template"
+
+ - type: "template"
+ name: "agent-file-template"
+ file: "templates/agent-file-template.md"
+ description: "Self-test agent file template"
+ replaces: "agent-file-template"
+
+ - type: "command"
+ name: "speckit.specify"
+ file: "commands/speckit.specify.md"
+ description: "Self-test override of the specify command"
+ replaces: "speckit.specify"
+
+tags:
+ - "testing"
+ - "self-test"
diff --git a/presets/self-test/templates/agent-file-template.md b/presets/self-test/templates/agent-file-template.md
new file mode 100644
index 000000000..7b9267bad
--- /dev/null
+++ b/presets/self-test/templates/agent-file-template.md
@@ -0,0 +1,9 @@
+# Agent File (Self-Test Preset)
+
+<!-- preset:self-test -->
+
+> This template is provided by the self-test preset.
+
+## Agent Instructions
+
+Follow these guidelines when working on this project.
diff --git a/presets/self-test/templates/checklist-template.md b/presets/self-test/templates/checklist-template.md
new file mode 100644
index 000000000..c761eb029
--- /dev/null
+++ b/presets/self-test/templates/checklist-template.md
@@ -0,0 +1,15 @@
+# Checklist (Self-Test Preset)
+
+<!-- preset:self-test -->
+
+> This template is provided by the self-test preset.
+
+## Pre-Implementation
+
+- [ ] Spec reviewed
+- [ ] Plan approved
+
+## Post-Implementation
+
+- [ ] Tests passing
+- [ ] Documentation updated
diff --git a/presets/self-test/templates/constitution-template.md b/presets/self-test/templates/constitution-template.md
new file mode 100644
index 000000000..0c53211fb
--- /dev/null
+++ b/presets/self-test/templates/constitution-template.md
@@ -0,0 +1,15 @@
+# Constitution (Self-Test Preset)
+
+<!-- preset:self-test -->
+
+> This template is provided by the self-test preset.
+
+## Principles
+
+1. Principle 1
+2. Principle 2
+
+## Guidelines
+
+- Guideline 1
+- Guideline 2
diff --git a/presets/self-test/templates/plan-template.md b/presets/self-test/templates/plan-template.md
new file mode 100644
index 000000000..5cdaa0a41
--- /dev/null
+++ b/presets/self-test/templates/plan-template.md
@@ -0,0 +1,22 @@
+# Implementation Plan (Self-Test Preset)
+
+<!-- preset:self-test -->
+
+> This template is provided by the self-test preset.
+
+## Approach
+
+Describe the implementation approach.
+
+## Steps
+
+1. Step 1
+2. Step 2
+
+## Dependencies
+
+- Dependency 1
+
+## Risks
+
+- Risk 1
diff --git a/presets/self-test/templates/spec-template.md b/presets/self-test/templates/spec-template.md
new file mode 100644
index 000000000..a54956f16
--- /dev/null
+++ b/presets/self-test/templates/spec-template.md
@@ -0,0 +1,23 @@
+# Feature Specification (Self-Test Preset)
+
+<!-- preset:self-test -->
+
+> This template is provided by the self-test preset.
+
+## Overview
+
+Brief description of the feature.
+
+## Requirements
+
+- Requirement 1
+- Requirement 2
+
+## Design
+
+Describe the design approach.
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
diff --git a/presets/self-test/templates/tasks-template.md b/presets/self-test/templates/tasks-template.md
new file mode 100644
index 000000000..80fa4c5fa
--- /dev/null
+++ b/presets/self-test/templates/tasks-template.md
@@ -0,0 +1,17 @@
+# Tasks (Self-Test Preset)
+
+<!-- preset:self-test -->
+
+> This template is provided by the self-test preset.
+
+## Task List
+
+- [ ] Task 1
+- [ ] Task 2
+
+## Estimation
+
+| Task | Estimate |
+|------|----------|
+| Task 1 | TBD |
+| Task 2 | TBD |
diff --git a/scripts/bash/common.sh b/scripts/bash/common.sh
index 7161f43b5..52e363e6d 100644
--- a/scripts/bash/common.sh
+++ b/scripts/bash/common.sh
@@ -175,3 +175,79 @@ json_escape() {
check_file() { [[ -f "$1" ]] && echo " βœ“ $2" || echo " βœ— $2"; }
check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo " βœ“ $2" || echo " βœ— $2"; }
+# Resolve a template name to a file path using the priority stack:
+# 1. .specify/templates/overrides/
+# 2. .specify/presets/<preset-id>/templates/ (sorted by priority from .registry)
+# 3. .specify/extensions/<ext-id>/templates/
+# 4. .specify/templates/ (core)
+resolve_template() {
+ local template_name="$1"
+ local repo_root="$2"
+ local base="$repo_root/.specify/templates"
+
+ # Priority 1: Project overrides
+ local override="$base/overrides/${template_name}.md"
+ [ -f "$override" ] && echo "$override" && return 0
+
+ # Priority 2: Installed presets (sorted by priority from .registry)
+ local presets_dir="$repo_root/.specify/presets"
+ if [ -d "$presets_dir" ]; then
+ local registry_file="$presets_dir/.registry"
+ if [ -f "$registry_file" ] && command -v python3 >/dev/null 2>&1; then
+ # Read preset IDs sorted by priority (lower number = higher precedence)
+ local sorted_presets
+ sorted_presets=$(SPECKIT_REGISTRY="$registry_file" python3 -c "
+import json, sys, os
+try:
+ with open(os.environ['SPECKIT_REGISTRY']) as f:
+ data = json.load(f)
+ presets = data.get('presets', {})
+ for pid, meta in sorted(presets.items(), key=lambda x: x[1].get('priority', 10)):
+ print(pid)
+except Exception:
+ sys.exit(1)
+" 2>/dev/null)
+ if [ $? -eq 0 ] && [ -n "$sorted_presets" ]; then
+ while IFS= read -r preset_id; do
+ local candidate="$presets_dir/$preset_id/templates/${template_name}.md"
+ [ -f "$candidate" ] && echo "$candidate" && return 0
+ done <<< "$sorted_presets"
+ else
+ # python3 returned empty list β€” fall through to directory scan
+ for preset in "$presets_dir"/*/; do
+ [ -d "$preset" ] || continue
+ local candidate="$preset/templates/${template_name}.md"
+ [ -f "$candidate" ] && echo "$candidate" && return 0
+ done
+ fi
+ else
+ # Fallback: alphabetical directory order (no python3 available)
+ for preset in "$presets_dir"/*/; do
+ [ -d "$preset" ] || continue
+ local candidate="$preset/templates/${template_name}.md"
+ [ -f "$candidate" ] && echo "$candidate" && return 0
+ done
+ fi
+ fi
+
+ # Priority 3: Extension-provided templates
+ local ext_dir="$repo_root/.specify/extensions"
+ if [ -d "$ext_dir" ]; then
+ for ext in "$ext_dir"/*/; do
+ [ -d "$ext" ] || continue
+ # Skip hidden directories (e.g. .backup, .cache)
+ case "$(basename "$ext")" in .*) continue;; esac
+ local candidate="$ext/templates/${template_name}.md"
+ [ -f "$candidate" ] && echo "$candidate" && return 0
+ done
+ fi
+
+ # Priority 4: Core templates
+ local core="$base/${template_name}.md"
+ [ -f "$core" ] && echo "$core" && return 0
+
+ # Return success with empty output so callers using set -e don't abort;
+ # callers check [ -n "$TEMPLATE" ] to detect "not found".
+ return 0
+}
+
diff --git a/scripts/bash/create-new-feature.sh b/scripts/bash/create-new-feature.sh
index 725f84c85..0823cca27 100644
--- a/scripts/bash/create-new-feature.sh
+++ b/scripts/bash/create-new-feature.sh
@@ -177,6 +177,7 @@ json_escape() {
# to searching for repository markers so the workflow still functions in repositories that
# were initialised with --no-git.
SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
if git rev-parse --show-toplevel >/dev/null 2>&1; then
REPO_ROOT=$(git rev-parse --show-toplevel)
@@ -307,9 +308,9 @@ fi
FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
mkdir -p "$FEATURE_DIR"
-TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md"
+TEMPLATE=$(resolve_template "spec-template" "$REPO_ROOT")
SPEC_FILE="$FEATURE_DIR/spec.md"
-if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
+if [ -n "$TEMPLATE" ] && [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
# Inform the user how to persist the feature variable in their own shell
printf '# To persist: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME" >&2
diff --git a/scripts/bash/setup-plan.sh b/scripts/bash/setup-plan.sh
index 60cf372cb..2a044c679 100644
--- a/scripts/bash/setup-plan.sh
+++ b/scripts/bash/setup-plan.sh
@@ -39,12 +39,12 @@ check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
mkdir -p "$FEATURE_DIR"
# Copy plan template if it exists
-TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
-if [[ -f "$TEMPLATE" ]]; then
+TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT")
+if [[ -n "$TEMPLATE" ]] && [[ -f "$TEMPLATE" ]]; then
cp "$TEMPLATE" "$IMPL_PLAN"
echo "Copied plan template to $IMPL_PLAN"
else
- echo "Warning: Plan template not found at $TEMPLATE"
+ echo "Warning: Plan template not found"
# Create a basic plan file if template doesn't exist
touch "$IMPL_PLAN"
fi
diff --git a/scripts/powershell/common.ps1 b/scripts/powershell/common.ps1
index b0be27354..3d6a77f29 100644
--- a/scripts/powershell/common.ps1
+++ b/scripts/powershell/common.ps1
@@ -135,3 +135,70 @@ function Test-DirHasFiles {
}
}
+# Resolve a template name to a file path using the priority stack:
+# 1. .specify/templates/overrides/
+# 2. .specify/presets/<preset-id>/templates/ (sorted by priority from .registry)
+# 3. .specify/extensions/<ext-id>/templates/
+# 4. .specify/templates/ (core)
+function Resolve-Template {
+ param(
+ [Parameter(Mandatory=$true)][string]$TemplateName,
+ [Parameter(Mandatory=$true)][string]$RepoRoot
+ )
+
+ $base = Join-Path $RepoRoot '.specify/templates'
+
+ # Priority 1: Project overrides
+ $override = Join-Path $base "overrides/$TemplateName.md"
+ if (Test-Path $override) { return $override }
+
+ # Priority 2: Installed presets (sorted by priority from .registry)
+ $presetsDir = Join-Path $RepoRoot '.specify/presets'
+ if (Test-Path $presetsDir) {
+ $registryFile = Join-Path $presetsDir '.registry'
+ $sortedPresets = @()
+ if (Test-Path $registryFile) {
+ try {
+ $registryData = Get-Content $registryFile -Raw | ConvertFrom-Json
+ $presets = $registryData.presets
+ if ($presets) {
+ $sortedPresets = $presets.PSObject.Properties |
+ Sort-Object { if ($null -ne $_.Value.priority) { $_.Value.priority } else { 10 } } |
+ ForEach-Object { $_.Name }
+ }
+ } catch {
+ # Fallback: alphabetical directory order
+ $sortedPresets = @()
+ }
+ }
+
+ if ($sortedPresets.Count -gt 0) {
+ foreach ($presetId in $sortedPresets) {
+ $candidate = Join-Path $presetsDir "$presetId/templates/$TemplateName.md"
+ if (Test-Path $candidate) { return $candidate }
+ }
+ } else {
+ # Fallback: alphabetical directory order
+ foreach ($preset in Get-ChildItem -Path $presetsDir -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -notlike '.*' }) {
+ $candidate = Join-Path $preset.FullName "templates/$TemplateName.md"
+ if (Test-Path $candidate) { return $candidate }
+ }
+ }
+ }
+
+ # Priority 3: Extension-provided templates
+ $extDir = Join-Path $RepoRoot '.specify/extensions'
+ if (Test-Path $extDir) {
+ foreach ($ext in Get-ChildItem -Path $extDir -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -notlike '.*' } | Sort-Object Name) {
+ $candidate = Join-Path $ext.FullName "templates/$TemplateName.md"
+ if (Test-Path $candidate) { return $candidate }
+ }
+ }
+
+ # Priority 4: Core templates
+ $core = Join-Path $base "$TemplateName.md"
+ if (Test-Path $core) { return $core }
+
+ return $null
+}
+
diff --git a/scripts/powershell/create-new-feature.ps1 b/scripts/powershell/create-new-feature.ps1
index 172b5bc7d..31acbe295 100644
--- a/scripts/powershell/create-new-feature.ps1
+++ b/scripts/powershell/create-new-feature.ps1
@@ -141,6 +141,9 @@ if (-not $fallbackRoot) {
exit 1
}
+# Load common functions (includes Resolve-Template)
+. "$PSScriptRoot/common.ps1"
+
try {
$repoRoot = git rev-parse --show-toplevel 2>$null
if ($LASTEXITCODE -eq 0) {
@@ -276,9 +279,9 @@ if ($hasGit) {
$featureDir = Join-Path $specsDir $branchName
New-Item -ItemType Directory -Path $featureDir -Force | Out-Null
-$template = Join-Path $repoRoot '.specify/templates/spec-template.md'
+$template = Resolve-Template -TemplateName 'spec-template' -RepoRoot $repoRoot
$specFile = Join-Path $featureDir 'spec.md'
-if (Test-Path $template) {
+if ($template -and (Test-Path $template)) {
Copy-Item $template $specFile -Force
} else {
New-Item -ItemType File -Path $specFile | Out-Null
diff --git a/scripts/powershell/setup-plan.ps1 b/scripts/powershell/setup-plan.ps1
index d0ed582fa..ee09094bf 100644
--- a/scripts/powershell/setup-plan.ps1
+++ b/scripts/powershell/setup-plan.ps1
@@ -32,12 +32,12 @@ if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit $paths.HAS_GI
New-Item -ItemType Directory -Path $paths.FEATURE_DIR -Force | Out-Null
# Copy plan template if it exists, otherwise note it or create empty file
-$template = Join-Path $paths.REPO_ROOT '.specify/templates/plan-template.md'
-if (Test-Path $template) {
+$template = Resolve-Template -TemplateName 'plan-template' -RepoRoot $paths.REPO_ROOT
+if ($template -and (Test-Path $template)) {
Copy-Item $template $paths.IMPL_PLAN -Force
Write-Output "Copied plan template to $($paths.IMPL_PLAN)"
} else {
- Write-Warning "Plan template not found at $template"
+ Write-Warning "Plan template not found"
# Create a basic plan file if template doesn't exist
New-Item -ItemType File -Path $paths.IMPL_PLAN -Force | Out-Null
}
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py
index e7781b2b5..a45535aee 100644
--- a/src/specify_cli/__init__.py
+++ b/src/specify_cli/__init__.py
@@ -34,7 +34,7 @@ import shlex
import json
import yaml
from pathlib import Path
-from typing import Optional, Tuple
+from typing import Any, Optional, Tuple
import typer
import httpx
@@ -1067,6 +1067,36 @@ def ensure_constitution_from_template(project_path: Path, tracker: StepTracker |
else:
console.print(f"[yellow]Warning: Could not initialize constitution: {e}[/yellow]")
+
+INIT_OPTIONS_FILE = ".specify/init-options.json"
+
+
+def save_init_options(project_path: Path, options: dict[str, Any]) -> None:
+ """Persist the CLI options used during ``specify init``.
+
+ Writes a small JSON file to ``.specify/init-options.json`` so that
+ later operations (e.g. preset install) can adapt their behaviour
+ without scanning the filesystem.
+ """
+ dest = project_path / INIT_OPTIONS_FILE
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ dest.write_text(json.dumps(options, indent=2, sort_keys=True))
+
+
+def load_init_options(project_path: Path) -> dict[str, Any]:
+ """Load the init options previously saved by ``specify init``.
+
+ Returns an empty dict if the file does not exist or cannot be parsed.
+ """
+ path = project_path / INIT_OPTIONS_FILE
+ if not path.exists():
+ return {}
+ try:
+ return json.loads(path.read_text())
+ except (json.JSONDecodeError, OSError):
+ return {}
+
+
# Agent-specific skill directory overrides for agents whose skills directory
# doesn't follow the standard <agent_folder>/skills/ pattern
AGENT_SKILLS_DIR_OVERRIDES = {
@@ -1300,6 +1330,7 @@ def init(
debug: bool = typer.Option(False, "--debug", help="Show verbose diagnostic output for network and extraction failures"),
github_token: str = typer.Option(None, "--github-token", help="GitHub token to use for API requests (or set GH_TOKEN or GITHUB_TOKEN environment variable)"),
ai_skills: bool = typer.Option(False, "--ai-skills", help="Install Prompt.MD templates as agent skills (requires --ai)"),
+ preset: str = typer.Option(None, "--preset", help="Install a preset during initialization (by preset ID)"),
):
"""
Initialize a new Specify project from the latest template.
@@ -1328,6 +1359,7 @@ def init(
specify init my-project --ai claude --ai-skills # Install agent skills
specify init --here --ai gemini --ai-skills
specify init my-project --ai generic --ai-commands-dir .myagent/commands/ # Unsupported agent
+ specify init my-project --ai claude --preset healthcare-compliance # With preset
"""
show_banner()
@@ -1589,6 +1621,50 @@ def init(
else:
tracker.skip("git", "--no-git flag")
+ # Persist the CLI options so later operations (e.g. preset add)
+ # can adapt their behaviour without re-scanning the filesystem.
+ # Must be saved BEFORE preset install so _get_skills_dir() works.
+ save_init_options(project_path, {
+ "ai": selected_ai,
+ "ai_skills": ai_skills,
+ "ai_commands_dir": ai_commands_dir,
+ "here": here,
+ "preset": preset,
+ "script": selected_script,
+ "speckit_version": get_speckit_version(),
+ })
+
+ # Install preset if specified
+ if preset:
+ try:
+ from .presets import PresetManager, PresetCatalog, PresetError
+ preset_manager = PresetManager(project_path)
+ speckit_ver = get_speckit_version()
+
+ # Try local directory first, then catalog
+ local_path = Path(preset).resolve()
+ if local_path.is_dir() and (local_path / "preset.yml").exists():
+ preset_manager.install_from_directory(local_path, speckit_ver)
+ else:
+ preset_catalog = PresetCatalog(project_path)
+ pack_info = preset_catalog.get_pack_info(preset)
+ if not pack_info:
+ console.print(f"[yellow]Warning:[/yellow] Preset '{preset}' not found in catalog. Skipping.")
+ else:
+ try:
+ zip_path = preset_catalog.download_pack(preset)
+ preset_manager.install_from_zip(zip_path, speckit_ver)
+ # Clean up downloaded ZIP to avoid cache accumulation
+ try:
+ zip_path.unlink(missing_ok=True)
+ except OSError:
+ # Best-effort cleanup; failure to delete is non-fatal
+ pass
+ except PresetError as preset_err:
+ console.print(f"[yellow]Warning:[/yellow] Failed to install preset '{preset}': {preset_err}")
+ except Exception as preset_err:
+ console.print(f"[yellow]Warning:[/yellow] Failed to install preset: {preset_err}")
+
tracker.complete("final", "project ready")
except Exception as e:
tracker.error("final", str(e))
@@ -1826,6 +1902,20 @@ catalog_app = typer.Typer(
)
extension_app.add_typer(catalog_app, name="catalog")
+preset_app = typer.Typer(
+ name="preset",
+ help="Manage spec-kit presets",
+ add_completion=False,
+)
+app.add_typer(preset_app, name="preset")
+
+preset_catalog_app = typer.Typer(
+ name="catalog",
+ help="Manage preset catalogs",
+ add_completion=False,
+)
+preset_app.add_typer(preset_catalog_app, name="catalog")
+
def get_speckit_version() -> str:
"""Get current spec-kit version."""
@@ -1848,6 +1938,490 @@ def get_speckit_version() -> str:
return "unknown"
+# ===== Preset Commands =====
+
+
+@preset_app.command("list")
+def preset_list():
+ """List installed presets."""
+ from .presets import PresetManager
+
+ project_root = Path.cwd()
+
+ specify_dir = project_root / ".specify"
+ if not specify_dir.exists():
+ console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+ console.print("Run this command from a spec-kit project root")
+ raise typer.Exit(1)
+
+ manager = PresetManager(project_root)
+ installed = manager.list_installed()
+
+ if not installed:
+ console.print("[yellow]No presets installed.[/yellow]")
+ console.print("\nInstall a preset with:")
+ console.print(" [cyan]specify preset add <pack-name>[/cyan]")
+ return
+
+ console.print("\n[bold cyan]Installed Presets:[/bold cyan]\n")
+ for pack in installed:
+ status = "[green]enabled[/green]" if pack.get("enabled", True) else "[red]disabled[/red]"
+ pri = pack.get('priority', 10)
+ console.print(f" [bold]{pack['name']}[/bold] ({pack['id']}) v{pack['version']} β€” {status} β€” priority {pri}")
+ console.print(f" {pack['description']}")
+ if pack.get("tags"):
+ tags_str = ", ".join(pack["tags"])
+ console.print(f" [dim]Tags: {tags_str}[/dim]")
+ console.print(f" [dim]Templates: {pack['template_count']}[/dim]")
+ console.print()
+
+
+@preset_app.command("add")
+def preset_add(
+ pack_id: str = typer.Argument(None, help="Preset ID to install from catalog"),
+ from_url: str = typer.Option(None, "--from", help="Install from a URL (ZIP file)"),
+ dev: str = typer.Option(None, "--dev", help="Install from local directory (development mode)"),
+ priority: int = typer.Option(10, "--priority", help="Resolution priority (lower = higher precedence, default 10)"),
+):
+ """Install a preset."""
+ from .presets import (
+ PresetManager,
+ PresetCatalog,
+ PresetError,
+ PresetValidationError,
+ PresetCompatibilityError,
+ )
+
+ project_root = Path.cwd()
+
+ specify_dir = project_root / ".specify"
+ if not specify_dir.exists():
+ console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+ console.print("Run this command from a spec-kit project root")
+ raise typer.Exit(1)
+
+ manager = PresetManager(project_root)
+ speckit_version = get_speckit_version()
+
+ try:
+ if dev:
+ dev_path = Path(dev).resolve()
+ if not dev_path.exists():
+ console.print(f"[red]Error:[/red] Directory not found: {dev}")
+ raise typer.Exit(1)
+
+ console.print(f"Installing preset from [cyan]{dev_path}[/cyan]...")
+ manifest = manager.install_from_directory(dev_path, speckit_version, priority)
+ console.print(f"[green]βœ“[/green] Preset '{manifest.name}' v{manifest.version} installed (priority {priority})")
+
+ elif from_url:
+ # Validate URL scheme before downloading
+ from urllib.parse import urlparse as _urlparse
+ _parsed = _urlparse(from_url)
+ _is_localhost = _parsed.hostname in ("localhost", "127.0.0.1", "::1")
+ if _parsed.scheme != "https" and not (_parsed.scheme == "http" and _is_localhost):
+ console.print(f"[red]Error:[/red] URL must use HTTPS (got {_parsed.scheme}://). HTTP is only allowed for localhost.")
+ raise typer.Exit(1)
+
+ console.print(f"Installing preset from [cyan]{from_url}[/cyan]...")
+ import urllib.request
+ import urllib.error
+ import tempfile
+
+ with tempfile.TemporaryDirectory() as tmpdir:
+ zip_path = Path(tmpdir) / "preset.zip"
+ try:
+ with urllib.request.urlopen(from_url, timeout=60) as response:
+ zip_path.write_bytes(response.read())
+ except urllib.error.URLError as e:
+ console.print(f"[red]Error:[/red] Failed to download: {e}")
+ raise typer.Exit(1)
+
+ manifest = manager.install_from_zip(zip_path, speckit_version, priority)
+
+ console.print(f"[green]βœ“[/green] Preset '{manifest.name}' v{manifest.version} installed (priority {priority})")
+
+ elif pack_id:
+ catalog = PresetCatalog(project_root)
+ pack_info = catalog.get_pack_info(pack_id)
+
+ if not pack_info:
+ console.print(f"[red]Error:[/red] Preset '{pack_id}' not found in catalog")
+ raise typer.Exit(1)
+
+ if not pack_info.get("_install_allowed", True):
+ catalog_name = pack_info.get("_catalog_name", "unknown")
+ console.print(f"[red]Error:[/red] Preset '{pack_id}' is from the '{catalog_name}' catalog which is discovery-only (install not allowed).")
+ console.print("Add the catalog with --install-allowed or install from the preset's repository directly with --from.")
+ raise typer.Exit(1)
+
+ console.print(f"Installing preset [cyan]{pack_info.get('name', pack_id)}[/cyan]...")
+
+ try:
+ zip_path = catalog.download_pack(pack_id)
+ manifest = manager.install_from_zip(zip_path, speckit_version, priority)
+ console.print(f"[green]βœ“[/green] Preset '{manifest.name}' v{manifest.version} installed (priority {priority})")
+ finally:
+ if 'zip_path' in locals() and zip_path.exists():
+ zip_path.unlink(missing_ok=True)
+ else:
+ console.print("[red]Error:[/red] Specify a preset ID, --from URL, or --dev path")
+ raise typer.Exit(1)
+
+ except PresetCompatibilityError as e:
+ console.print(f"[red]Compatibility Error:[/red] {e}")
+ raise typer.Exit(1)
+ except PresetValidationError as e:
+ console.print(f"[red]Validation Error:[/red] {e}")
+ raise typer.Exit(1)
+ except PresetError as e:
+ console.print(f"[red]Error:[/red] {e}")
+ raise typer.Exit(1)
+
+
+@preset_app.command("remove")
+def preset_remove(
+ pack_id: str = typer.Argument(..., help="Preset ID to remove"),
+):
+ """Remove an installed preset."""
+ from .presets import PresetManager
+
+ project_root = Path.cwd()
+
+ specify_dir = project_root / ".specify"
+ if not specify_dir.exists():
+ console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+ console.print("Run this command from a spec-kit project root")
+ raise typer.Exit(1)
+
+ manager = PresetManager(project_root)
+
+ if not manager.registry.is_installed(pack_id):
+ console.print(f"[red]Error:[/red] Preset '{pack_id}' is not installed")
+ raise typer.Exit(1)
+
+ if manager.remove(pack_id):
+ console.print(f"[green]βœ“[/green] Preset '{pack_id}' removed successfully")
+ else:
+ console.print(f"[red]Error:[/red] Failed to remove preset '{pack_id}'")
+ raise typer.Exit(1)
+
+
+@preset_app.command("search")
+def preset_search(
+ query: str = typer.Argument(None, help="Search query"),
+ tag: str = typer.Option(None, "--tag", help="Filter by tag"),
+ author: str = typer.Option(None, "--author", help="Filter by author"),
+):
+ """Search for presets in the catalog."""
+ from .presets import PresetCatalog, PresetError
+
+ project_root = Path.cwd()
+
+ specify_dir = project_root / ".specify"
+ if not specify_dir.exists():
+ console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+ console.print("Run this command from a spec-kit project root")
+ raise typer.Exit(1)
+
+ catalog = PresetCatalog(project_root)
+
+ try:
+ results = catalog.search(query=query, tag=tag, author=author)
+ except PresetError as e:
+ console.print(f"[red]Error:[/red] {e}")
+ raise typer.Exit(1)
+
+ if not results:
+ console.print("[yellow]No presets found matching your criteria.[/yellow]")
+ return
+
+ console.print(f"\n[bold cyan]Presets ({len(results)} found):[/bold cyan]\n")
+ for pack in results:
+ console.print(f" [bold]{pack.get('name', pack['id'])}[/bold] ({pack['id']}) v{pack.get('version', '?')}")
+ console.print(f" {pack.get('description', '')}")
+ if pack.get("tags"):
+ tags_str = ", ".join(pack["tags"])
+ console.print(f" [dim]Tags: {tags_str}[/dim]")
+ console.print()
+
+
+@preset_app.command("resolve")
+def preset_resolve(
+ template_name: str = typer.Argument(..., help="Template name to resolve (e.g., spec-template)"),
+):
+ """Show which template will be resolved for a given name."""
+ from .presets import PresetResolver
+
+ project_root = Path.cwd()
+
+ specify_dir = project_root / ".specify"
+ if not specify_dir.exists():
+ console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+ console.print("Run this command from a spec-kit project root")
+ raise typer.Exit(1)
+
+ resolver = PresetResolver(project_root)
+ result = resolver.resolve_with_source(template_name)
+
+ if result:
+ console.print(f" [bold]{template_name}[/bold]: {result['path']}")
+ console.print(f" [dim](from: {result['source']})[/dim]")
+ else:
+ console.print(f" [yellow]{template_name}[/yellow]: not found")
+ console.print(" [dim]No template with this name exists in the resolution stack[/dim]")
+
+
+@preset_app.command("info")
+def preset_info(
+ pack_id: str = typer.Argument(..., help="Preset ID to get info about"),
+):
+ """Show detailed information about a preset."""
+ from .presets import PresetCatalog, PresetManager, PresetError
+
+ project_root = Path.cwd()
+
+ specify_dir = project_root / ".specify"
+ if not specify_dir.exists():
+ console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+ console.print("Run this command from a spec-kit project root")
+ raise typer.Exit(1)
+
+ # Check if installed locally first
+ manager = PresetManager(project_root)
+ local_pack = manager.get_pack(pack_id)
+
+ if local_pack:
+ console.print(f"\n[bold cyan]Preset: {local_pack.name}[/bold cyan]\n")
+ console.print(f" ID: {local_pack.id}")
+ console.print(f" Version: {local_pack.version}")
+ console.print(f" Description: {local_pack.description}")
+ if local_pack.author:
+ console.print(f" Author: {local_pack.author}")
+ if local_pack.tags:
+ console.print(f" Tags: {', '.join(local_pack.tags)}")
+ console.print(f" Templates: {len(local_pack.templates)}")
+ for tmpl in local_pack.templates:
+ console.print(f" - {tmpl['name']} ({tmpl['type']}): {tmpl.get('description', '')}")
+ repo = local_pack.data.get("preset", {}).get("repository")
+ if repo:
+ console.print(f" Repository: {repo}")
+ license_val = local_pack.data.get("preset", {}).get("license")
+ if license_val:
+ console.print(f" License: {license_val}")
+ console.print("\n [green]Status: installed[/green]")
+ console.print()
+ return
+
+ # Fall back to catalog
+ catalog = PresetCatalog(project_root)
+ try:
+ pack_info = catalog.get_pack_info(pack_id)
+ except PresetError:
+ pack_info = None
+
+ if not pack_info:
+ console.print(f"[red]Error:[/red] Preset '{pack_id}' not found (not installed and not in catalog)")
+ raise typer.Exit(1)
+
+ console.print(f"\n[bold cyan]Preset: {pack_info.get('name', pack_id)}[/bold cyan]\n")
+ console.print(f" ID: {pack_info['id']}")
+ console.print(f" Version: {pack_info.get('version', '?')}")
+ console.print(f" Description: {pack_info.get('description', '')}")
+ if pack_info.get("author"):
+ console.print(f" Author: {pack_info['author']}")
+ if pack_info.get("tags"):
+ console.print(f" Tags: {', '.join(pack_info['tags'])}")
+ if pack_info.get("repository"):
+ console.print(f" Repository: {pack_info['repository']}")
+ if pack_info.get("license"):
+ console.print(f" License: {pack_info['license']}")
+ console.print("\n [yellow]Status: not installed[/yellow]")
+ console.print(f" Install with: [cyan]specify preset add {pack_id}[/cyan]")
+ console.print()
+
+
+# ===== Preset Catalog Commands =====
+
+
+@preset_catalog_app.command("list")
+def preset_catalog_list():
+ """List all active preset catalogs."""
+ from .presets import PresetCatalog, PresetValidationError
+
+ project_root = Path.cwd()
+
+ specify_dir = project_root / ".specify"
+ if not specify_dir.exists():
+ console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+ console.print("Run this command from a spec-kit project root")
+ raise typer.Exit(1)
+
+ catalog = PresetCatalog(project_root)
+
+ try:
+ active_catalogs = catalog.get_active_catalogs()
+ except PresetValidationError as e:
+ console.print(f"[red]Error:[/red] {e}")
+ raise typer.Exit(1)
+
+ console.print("\n[bold cyan]Active Preset Catalogs:[/bold cyan]\n")
+ for entry in active_catalogs:
+ install_str = (
+ "[green]install allowed[/green]"
+ if entry.install_allowed
+ else "[yellow]discovery only[/yellow]"
+ )
+ console.print(f" [bold]{entry.name}[/bold] (priority {entry.priority})")
+ if entry.description:
+ console.print(f" {entry.description}")
+ console.print(f" URL: {entry.url}")
+ console.print(f" Install: {install_str}")
+ console.print()
+
+ config_path = project_root / ".specify" / "preset-catalogs.yml"
+ user_config_path = Path.home() / ".specify" / "preset-catalogs.yml"
+ if os.environ.get("SPECKIT_PRESET_CATALOG_URL"):
+ console.print("[dim]Catalog configured via SPECKIT_PRESET_CATALOG_URL environment variable.[/dim]")
+ else:
+ try:
+ proj_loaded = config_path.exists() and catalog._load_catalog_config(config_path) is not None
+ except PresetValidationError:
+ proj_loaded = False
+ if proj_loaded:
+ console.print(f"[dim]Config: {config_path.relative_to(project_root)}[/dim]")
+ else:
+ try:
+ user_loaded = user_config_path.exists() and catalog._load_catalog_config(user_config_path) is not None
+ except PresetValidationError:
+ user_loaded = False
+ if user_loaded:
+ console.print("[dim]Config: ~/.specify/preset-catalogs.yml[/dim]")
+ else:
+ console.print("[dim]Using built-in default catalog stack.[/dim]")
+ console.print(
+ "[dim]Add .specify/preset-catalogs.yml to customize.[/dim]"
+ )
+
+
+@preset_catalog_app.command("add")
+def preset_catalog_add(
+ url: str = typer.Argument(help="Catalog URL (must use HTTPS)"),
+ name: str = typer.Option(..., "--name", help="Catalog name"),
+ priority: int = typer.Option(10, "--priority", help="Priority (lower = higher priority)"),
+ install_allowed: bool = typer.Option(
+ False, "--install-allowed/--no-install-allowed",
+ help="Allow presets from this catalog to be installed",
+ ),
+ description: str = typer.Option("", "--description", help="Description of the catalog"),
+):
+ """Add a catalog to .specify/preset-catalogs.yml."""
+ from .presets import PresetCatalog, PresetValidationError
+
+ project_root = Path.cwd()
+
+ specify_dir = project_root / ".specify"
+ if not specify_dir.exists():
+ console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+ console.print("Run this command from a spec-kit project root")
+ raise typer.Exit(1)
+
+ # Validate URL
+ tmp_catalog = PresetCatalog(project_root)
+ try:
+ tmp_catalog._validate_catalog_url(url)
+ except PresetValidationError as e:
+ console.print(f"[red]Error:[/red] {e}")
+ raise typer.Exit(1)
+
+ config_path = specify_dir / "preset-catalogs.yml"
+
+ # Load existing config
+ if config_path.exists():
+ try:
+ config = yaml.safe_load(config_path.read_text()) or {}
+ except Exception as e:
+ console.print(f"[red]Error:[/red] Failed to read {config_path}: {e}")
+ raise typer.Exit(1)
+ else:
+ config = {}
+
+ catalogs = config.get("catalogs", [])
+ if not isinstance(catalogs, list):
+ console.print("[red]Error:[/red] Invalid catalog config: 'catalogs' must be a list.")
+ raise typer.Exit(1)
+
+ # Check for duplicate name
+ for existing in catalogs:
+ if isinstance(existing, dict) and existing.get("name") == name:
+ console.print(f"[yellow]Warning:[/yellow] A catalog named '{name}' already exists.")
+ console.print("Use 'specify preset catalog remove' first, or choose a different name.")
+ raise typer.Exit(1)
+
+ catalogs.append({
+ "name": name,
+ "url": url,
+ "priority": priority,
+ "install_allowed": install_allowed,
+ "description": description,
+ })
+
+ config["catalogs"] = catalogs
+ config_path.write_text(yaml.dump(config, default_flow_style=False, sort_keys=False))
+
+ install_label = "install allowed" if install_allowed else "discovery only"
+ console.print(f"\n[green]βœ“[/green] Added catalog '[bold]{name}[/bold]' ({install_label})")
+ console.print(f" URL: {url}")
+ console.print(f" Priority: {priority}")
+ console.print(f"\nConfig saved to {config_path.relative_to(project_root)}")
+
+
+@preset_catalog_app.command("remove")
+def preset_catalog_remove(
+ name: str = typer.Argument(help="Catalog name to remove"),
+):
+ """Remove a catalog from .specify/preset-catalogs.yml."""
+ project_root = Path.cwd()
+
+ specify_dir = project_root / ".specify"
+ if not specify_dir.exists():
+ console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+ console.print("Run this command from a spec-kit project root")
+ raise typer.Exit(1)
+
+ config_path = specify_dir / "preset-catalogs.yml"
+ if not config_path.exists():
+ console.print("[red]Error:[/red] No preset catalog config found. Nothing to remove.")
+ raise typer.Exit(1)
+
+ try:
+ config = yaml.safe_load(config_path.read_text()) or {}
+ except Exception:
+ console.print("[red]Error:[/red] Failed to read preset catalog config.")
+ raise typer.Exit(1)
+
+ catalogs = config.get("catalogs", [])
+ if not isinstance(catalogs, list):
+ console.print("[red]Error:[/red] Invalid catalog config: 'catalogs' must be a list.")
+ raise typer.Exit(1)
+ original_count = len(catalogs)
+ catalogs = [c for c in catalogs if isinstance(c, dict) and c.get("name") != name]
+
+ if len(catalogs) == original_count:
+ console.print(f"[red]Error:[/red] Catalog '{name}' not found.")
+ raise typer.Exit(1)
+
+ config["catalogs"] = catalogs
+ config_path.write_text(yaml.dump(config, default_flow_style=False, sort_keys=False))
+
+ console.print(f"[green]βœ“[/green] Removed catalog '{name}'")
+ if not catalogs:
+ console.print("\n[dim]No catalogs remain in config. Built-in defaults will be used.[/dim]")
+
+
+# ===== Extension Commands =====
+
+
def _resolve_installed_extension(
argument: str,
installed_extensions: list,
diff --git a/src/specify_cli/agents.py b/src/specify_cli/agents.py
new file mode 100644
index 000000000..9927daee8
--- /dev/null
+++ b/src/specify_cli/agents.py
@@ -0,0 +1,422 @@
+"""
+Agent Command Registrar for Spec Kit
+
+Shared infrastructure for registering commands with AI agents.
+Used by both the extension system and the preset system to write
+command files into agent-specific directories in the correct format.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Any
+
+import yaml
+
+
+class CommandRegistrar:
+ """Handles registration of commands with AI agents.
+
+ Supports writing command files in Markdown or TOML format to the
+ appropriate agent directory, with correct argument placeholders
+ and companion files (e.g. Copilot .prompt.md).
+ """
+
+ # Agent configurations with directory, format, and argument placeholder
+ AGENT_CONFIGS = {
+ "claude": {
+ "dir": ".claude/commands",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "gemini": {
+ "dir": ".gemini/commands",
+ "format": "toml",
+ "args": "{{args}}",
+ "extension": ".toml"
+ },
+ "copilot": {
+ "dir": ".github/agents",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".agent.md"
+ },
+ "cursor": {
+ "dir": ".cursor/commands",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "qwen": {
+ "dir": ".qwen/commands",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "opencode": {
+ "dir": ".opencode/command",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "codex": {
+ "dir": ".codex/prompts",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "windsurf": {
+ "dir": ".windsurf/workflows",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "kilocode": {
+ "dir": ".kilocode/workflows",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "auggie": {
+ "dir": ".augment/commands",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "roo": {
+ "dir": ".roo/commands",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "codebuddy": {
+ "dir": ".codebuddy/commands",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "qodercli": {
+ "dir": ".qoder/commands",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "kiro-cli": {
+ "dir": ".kiro/prompts",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "amp": {
+ "dir": ".agents/commands",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "shai": {
+ "dir": ".shai/commands",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "tabnine": {
+ "dir": ".tabnine/agent/commands",
+ "format": "toml",
+ "args": "{{args}}",
+ "extension": ".toml"
+ },
+ "bob": {
+ "dir": ".bob/commands",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md"
+ },
+ "kimi": {
+ "dir": ".kimi/skills",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": "/SKILL.md"
+ }
+ }
+
+ @staticmethod
+ def parse_frontmatter(content: str) -> tuple[dict, str]:
+ """Parse YAML frontmatter from Markdown content.
+
+ Args:
+ content: Markdown content with YAML frontmatter
+
+ Returns:
+ Tuple of (frontmatter_dict, body_content)
+ """
+ if not content.startswith("---"):
+ return {}, content
+
+ # Find second ---
+ end_marker = content.find("---", 3)
+ if end_marker == -1:
+ return {}, content
+
+ frontmatter_str = content[3:end_marker].strip()
+ body = content[end_marker + 3:].strip()
+
+ try:
+ frontmatter = yaml.safe_load(frontmatter_str) or {}
+ except yaml.YAMLError:
+ frontmatter = {}
+
+ return frontmatter, body
+
+ @staticmethod
+ def render_frontmatter(fm: dict) -> str:
+ """Render frontmatter dictionary as YAML.
+
+ Args:
+ fm: Frontmatter dictionary
+
+ Returns:
+ YAML-formatted frontmatter with delimiters
+ """
+ if not fm:
+ return ""
+
+ yaml_str = yaml.dump(fm, default_flow_style=False, sort_keys=False)
+ return f"---\n{yaml_str}---\n"
+
+ def _adjust_script_paths(self, frontmatter: dict) -> dict:
+ """Adjust script paths from extension-relative to repo-relative.
+
+ Args:
+ frontmatter: Frontmatter dictionary
+
+ Returns:
+ Modified frontmatter with adjusted paths
+ """
+ if "scripts" in frontmatter:
+ for key in frontmatter["scripts"]:
+ script_path = frontmatter["scripts"][key]
+ if script_path.startswith("../../scripts/"):
+ frontmatter["scripts"][key] = f".specify/scripts/{script_path[14:]}"
+ return frontmatter
+
+ def render_markdown_command(
+ self,
+ frontmatter: dict,
+ body: str,
+ source_id: str,
+ context_note: str = None
+ ) -> str:
+ """Render command in Markdown format.
+
+ Args:
+ frontmatter: Command frontmatter
+ body: Command body content
+ source_id: Source identifier (extension or preset ID)
+ context_note: Custom context comment (default: <!-- Source: {source_id} -->)
+
+ Returns:
+ Formatted Markdown command file content
+ """
+ if context_note is None:
+ context_note = f"\n<!-- Source: {source_id} -->\n"
+ return self.render_frontmatter(frontmatter) + "\n" + context_note + body
+
+ def render_toml_command(
+ self,
+ frontmatter: dict,
+ body: str,
+ source_id: str
+ ) -> str:
+ """Render command in TOML format.
+
+ Args:
+ frontmatter: Command frontmatter
+ body: Command body content
+ source_id: Source identifier (extension or preset ID)
+
+ Returns:
+ Formatted TOML command file content
+ """
+ toml_lines = []
+
+ if "description" in frontmatter:
+ desc = frontmatter["description"].replace('"', '\\"')
+ toml_lines.append(f'description = "{desc}"')
+ toml_lines.append("")
+
+ toml_lines.append(f"# Source: {source_id}")
+ toml_lines.append("")
+
+ toml_lines.append('prompt = """')
+ toml_lines.append(body)
+ toml_lines.append('"""')
+
+ return "\n".join(toml_lines)
+
+ def _convert_argument_placeholder(self, content: str, from_placeholder: str, to_placeholder: str) -> str:
+ """Convert argument placeholder format.
+
+ Args:
+ content: Command content
+ from_placeholder: Source placeholder (e.g., "$ARGUMENTS")
+ to_placeholder: Target placeholder (e.g., "{{args}}")
+
+ Returns:
+ Content with converted placeholders
+ """
+ return content.replace(from_placeholder, to_placeholder)
+
+ def register_commands(
+ self,
+ agent_name: str,
+ commands: List[Dict[str, Any]],
+ source_id: str,
+ source_dir: Path,
+ project_root: Path,
+ context_note: str = None
+ ) -> List[str]:
+ """Register commands for a specific agent.
+
+ Args:
+ agent_name: Agent name (claude, gemini, copilot, etc.)
+ commands: List of command info dicts with 'name', 'file', and optional 'aliases'
+ source_id: Identifier of the source (extension or preset ID)
+ source_dir: Directory containing command source files
+ project_root: Path to project root
+ context_note: Custom context comment for markdown output
+
+ Returns:
+ List of registered command names
+
+ Raises:
+ ValueError: If agent is not supported
+ """
+ if agent_name not in self.AGENT_CONFIGS:
+ raise ValueError(f"Unsupported agent: {agent_name}")
+
+ agent_config = self.AGENT_CONFIGS[agent_name]
+ commands_dir = project_root / agent_config["dir"]
+ commands_dir.mkdir(parents=True, exist_ok=True)
+
+ registered = []
+
+ for cmd_info in commands:
+ cmd_name = cmd_info["name"]
+ cmd_file = cmd_info["file"]
+
+ source_file = source_dir / cmd_file
+ if not source_file.exists():
+ continue
+
+ content = source_file.read_text(encoding="utf-8")
+ frontmatter, body = self.parse_frontmatter(content)
+
+ frontmatter = self._adjust_script_paths(frontmatter)
+
+ body = self._convert_argument_placeholder(
+ body, "$ARGUMENTS", agent_config["args"]
+ )
+
+ if agent_config["format"] == "markdown":
+ output = self.render_markdown_command(frontmatter, body, source_id, context_note)
+ elif agent_config["format"] == "toml":
+ output = self.render_toml_command(frontmatter, body, source_id)
+ else:
+ raise ValueError(f"Unsupported format: {agent_config['format']}")
+
+ dest_file = commands_dir / f"{cmd_name}{agent_config['extension']}"
+ dest_file.parent.mkdir(parents=True, exist_ok=True)
+ dest_file.write_text(output, encoding="utf-8")
+
+ if agent_name == "copilot":
+ self.write_copilot_prompt(project_root, cmd_name)
+
+ registered.append(cmd_name)
+
+ for alias in cmd_info.get("aliases", []):
+ alias_file = commands_dir / f"{alias}{agent_config['extension']}"
+ alias_file.parent.mkdir(parents=True, exist_ok=True)
+ alias_file.write_text(output, encoding="utf-8")
+ if agent_name == "copilot":
+ self.write_copilot_prompt(project_root, alias)
+ registered.append(alias)
+
+ return registered
+
+ @staticmethod
+ def write_copilot_prompt(project_root: Path, cmd_name: str) -> None:
+ """Generate a companion .prompt.md file for a Copilot agent command.
+
+ Args:
+ project_root: Path to project root
+ cmd_name: Command name (e.g. 'speckit.my-ext.example')
+ """
+ prompts_dir = project_root / ".github" / "prompts"
+ prompts_dir.mkdir(parents=True, exist_ok=True)
+ prompt_file = prompts_dir / f"{cmd_name}.prompt.md"
+ prompt_file.write_text(f"---\nagent: {cmd_name}\n---\n", encoding="utf-8")
+
+ def register_commands_for_all_agents(
+ self,
+ commands: List[Dict[str, Any]],
+ source_id: str,
+ source_dir: Path,
+ project_root: Path,
+ context_note: str = None
+ ) -> Dict[str, List[str]]:
+ """Register commands for all detected agents in the project.
+
+ Args:
+ commands: List of command info dicts
+ source_id: Identifier of the source (extension or preset ID)
+ source_dir: Directory containing command source files
+ project_root: Path to project root
+ context_note: Custom context comment for markdown output
+
+ Returns:
+ Dictionary mapping agent names to list of registered commands
+ """
+ results = {}
+
+ for agent_name, agent_config in self.AGENT_CONFIGS.items():
+ agent_dir = project_root / agent_config["dir"].split("/")[0]
+
+ if agent_dir.exists():
+ try:
+ registered = self.register_commands(
+ agent_name, commands, source_id, source_dir, project_root,
+ context_note=context_note
+ )
+ if registered:
+ results[agent_name] = registered
+ except ValueError:
+ continue
+
+ return results
+
+ def unregister_commands(
+ self,
+ registered_commands: Dict[str, List[str]],
+ project_root: Path
+ ) -> None:
+ """Remove previously registered command files from agent directories.
+
+ Args:
+ registered_commands: Dict mapping agent names to command name lists
+ project_root: Path to project root
+ """
+ for agent_name, cmd_names in registered_commands.items():
+ if agent_name not in self.AGENT_CONFIGS:
+ continue
+
+ agent_config = self.AGENT_CONFIGS[agent_name]
+ commands_dir = project_root / agent_config["dir"]
+
+ for cmd_name in cmd_names:
+ cmd_file = commands_dir / f"{cmd_name}{agent_config['extension']}"
+ if cmd_file.exists():
+ cmd_file.unlink()
+
+ if agent_name == "copilot":
+ prompt_file = project_root / ".github" / "prompts" / f"{cmd_name}.prompt.md"
+ if prompt_file.exists():
+ prompt_file.unlink()
diff --git a/src/specify_cli/extensions.py b/src/specify_cli/extensions.py
index 156daff6a..0dfd40b7c 100644
--- a/src/specify_cli/extensions.py
+++ b/src/specify_cli/extensions.py
@@ -578,23 +578,7 @@ class ExtensionManager:
# Unregister commands from all AI agents
if registered_commands:
registrar = CommandRegistrar()
- for agent_name, cmd_names in registered_commands.items():
- if agent_name not in registrar.AGENT_CONFIGS:
- continue
-
- agent_config = registrar.AGENT_CONFIGS[agent_name]
- commands_dir = self.project_root / agent_config["dir"]
-
- for cmd_name in cmd_names:
- cmd_file = commands_dir / f"{cmd_name}{agent_config['extension']}"
- if cmd_file.exists():
- cmd_file.unlink()
-
- # Also remove companion .prompt.md for Copilot
- if agent_name == "copilot":
- prompt_file = self.project_root / ".github" / "prompts" / f"{cmd_name}.prompt.md"
- if prompt_file.exists():
- prompt_file.unlink()
+ registrar.unregister_commands(registered_commands, self.project_root)
if keep_config:
# Preserve config files, only remove non-config files
@@ -718,255 +702,47 @@ def version_satisfies(current: str, required: str) -> bool:
class CommandRegistrar:
- """Handles registration of extension commands with AI agents."""
-
- # Agent configurations with directory, format, and argument placeholder
- AGENT_CONFIGS = {
- "claude": {
- "dir": ".claude/commands",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "gemini": {
- "dir": ".gemini/commands",
- "format": "toml",
- "args": "{{args}}",
- "extension": ".toml"
- },
- "copilot": {
- "dir": ".github/agents",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".agent.md"
- },
- "cursor": {
- "dir": ".cursor/commands",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "qwen": {
- "dir": ".qwen/commands",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "opencode": {
- "dir": ".opencode/command",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "codex": {
- "dir": ".codex/prompts",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "windsurf": {
- "dir": ".windsurf/workflows",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "kilocode": {
- "dir": ".kilocode/rules",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "auggie": {
- "dir": ".augment/rules",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "roo": {
- "dir": ".roo/commands",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "codebuddy": {
- "dir": ".codebuddy/commands",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "qodercli": {
- "dir": ".qoder/commands",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "kiro-cli": {
- "dir": ".kiro/prompts",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "amp": {
- "dir": ".agents/commands",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "shai": {
- "dir": ".shai/commands",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "tabnine": {
- "dir": ".tabnine/agent/commands",
- "format": "toml",
- "args": "{{args}}",
- "extension": ".toml"
- },
- "bob": {
- "dir": ".bob/commands",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": ".md"
- },
- "kimi": {
- "dir": ".kimi/skills",
- "format": "markdown",
- "args": "$ARGUMENTS",
- "extension": "/SKILL.md"
- }
- }
-
- @staticmethod
- def parse_frontmatter(content: str) -> tuple[dict, str]:
- """Parse YAML frontmatter from Markdown content.
-
- Args:
- content: Markdown content with YAML frontmatter
+ """Handles registration of extension commands with AI agents.
- Returns:
- Tuple of (frontmatter_dict, body_content)
- """
- if not content.startswith("---"):
- return {}, content
+ This is a backward-compatible wrapper around the shared CommandRegistrar
+ in agents.py. Extension-specific methods accept ExtensionManifest objects
+ and delegate to the generic API.
+ """
- # Find second ---
- end_marker = content.find("---", 3)
- if end_marker == -1:
- return {}, content
+ # Re-export AGENT_CONFIGS at class level for direct attribute access
+ from .agents import CommandRegistrar as _AgentRegistrar
+ AGENT_CONFIGS = _AgentRegistrar.AGENT_CONFIGS
- frontmatter_str = content[3:end_marker].strip()
- body = content[end_marker + 3:].strip()
+ def __init__(self):
+ from .agents import CommandRegistrar as _Registrar
+ self._registrar = _Registrar()
- try:
- frontmatter = yaml.safe_load(frontmatter_str) or {}
- except yaml.YAMLError:
- frontmatter = {}
-
- return frontmatter, body
+ # Delegate static/utility methods
+ @staticmethod
+ def parse_frontmatter(content: str) -> tuple[dict, str]:
+ from .agents import CommandRegistrar as _Registrar
+ return _Registrar.parse_frontmatter(content)
@staticmethod
def render_frontmatter(fm: dict) -> str:
- """Render frontmatter dictionary as YAML.
-
- Args:
- fm: Frontmatter dictionary
-
- Returns:
- YAML-formatted frontmatter with delimiters
- """
- if not fm:
- return ""
-
- yaml_str = yaml.dump(fm, default_flow_style=False, sort_keys=False)
- return f"---\n{yaml_str}---\n"
-
- def _adjust_script_paths(self, frontmatter: dict) -> dict:
- """Adjust script paths from extension-relative to repo-relative.
-
- Args:
- frontmatter: Frontmatter dictionary
+ from .agents import CommandRegistrar as _Registrar
+ return _Registrar.render_frontmatter(fm)
- Returns:
- Modified frontmatter with adjusted paths
- """
- if "scripts" in frontmatter:
- for key in frontmatter["scripts"]:
- script_path = frontmatter["scripts"][key]
- if script_path.startswith("../../scripts/"):
- frontmatter["scripts"][key] = f".specify/scripts/{script_path[14:]}"
- return frontmatter
-
- def _render_markdown_command(
- self,
- frontmatter: dict,
- body: str,
- ext_id: str
- ) -> str:
- """Render command in Markdown format.
-
- Args:
- frontmatter: Command frontmatter
- body: Command body content
- ext_id: Extension ID
+ @staticmethod
+ def _write_copilot_prompt(project_root, cmd_name: str) -> None:
+ from .agents import CommandRegistrar as _Registrar
+ _Registrar.write_copilot_prompt(project_root, cmd_name)
- Returns:
- Formatted Markdown command file content
- """
+ def _render_markdown_command(self, frontmatter, body, ext_id):
+ # Preserve extension-specific comment format for backward compatibility
context_note = f"\n<!-- Extension: {ext_id} -->\n<!-- Config: .specify/extensions/{ext_id}/ -->\n"
- return self.render_frontmatter(frontmatter) + "\n" + context_note + body
-
- def _render_toml_command(
- self,
- frontmatter: dict,
- body: str,
- ext_id: str
- ) -> str:
- """Render command in TOML format.
-
- Args:
- frontmatter: Command frontmatter
- body: Command body content
- ext_id: Extension ID
-
- Returns:
- Formatted TOML command file content
- """
- # TOML format for Gemini/Qwen
- toml_lines = []
-
- # Add description if present
- if "description" in frontmatter:
- # Escape quotes in description
- desc = frontmatter["description"].replace('"', '\\"')
- toml_lines.append(f'description = "{desc}"')
- toml_lines.append("")
-
- # Add extension context as comments
- toml_lines.append(f"# Extension: {ext_id}")
- toml_lines.append(f"# Config: .specify/extensions/{ext_id}/")
- toml_lines.append("")
-
- # Add prompt content
- toml_lines.append('prompt = """')
- toml_lines.append(body)
- toml_lines.append('"""')
+ return self._registrar.render_frontmatter(frontmatter) + "\n" + context_note + body
- return "\n".join(toml_lines)
-
- def _convert_argument_placeholder(self, content: str, from_placeholder: str, to_placeholder: str) -> str:
- """Convert argument placeholder format.
-
- Args:
- content: Command content
- from_placeholder: Source placeholder (e.g., "$ARGUMENTS")
- to_placeholder: Target placeholder (e.g., "{{args}}")
-
- Returns:
- Content with converted placeholders
- """
- return content.replace(from_placeholder, to_placeholder)
+ def _render_toml_command(self, frontmatter, body, ext_id):
+ # Preserve extension-specific context comments for backward compatibility
+ base = self._registrar.render_toml_command(frontmatter, body, ext_id)
+ context_lines = f"# Extension: {ext_id}\n# Config: .specify/extensions/{ext_id}/\n"
+ return base.rstrip("\n") + "\n" + context_lines
def register_commands_for_agent(
self,
@@ -975,96 +751,14 @@ class CommandRegistrar:
extension_dir: Path,
project_root: Path
) -> List[str]:
- """Register extension commands for a specific agent.
-
- Args:
- agent_name: Agent name (claude, gemini, copilot, etc.)
- manifest: Extension manifest
- extension_dir: Path to extension directory
- project_root: Path to project root
-
- Returns:
- List of registered command names
-
- Raises:
- ExtensionError: If agent is not supported
- """
+ """Register extension commands for a specific agent."""
if agent_name not in self.AGENT_CONFIGS:
raise ExtensionError(f"Unsupported agent: {agent_name}")
-
- agent_config = self.AGENT_CONFIGS[agent_name]
- commands_dir = project_root / agent_config["dir"]
- commands_dir.mkdir(parents=True, exist_ok=True)
-
- registered = []
-
- for cmd_info in manifest.commands:
- cmd_name = cmd_info["name"]
- cmd_file = cmd_info["file"]
-
- # Read source command file
- source_file = extension_dir / cmd_file
- if not source_file.exists():
- continue
-
- content = source_file.read_text()
- frontmatter, body = self.parse_frontmatter(content)
-
- # Adjust script paths
- frontmatter = self._adjust_script_paths(frontmatter)
-
- # Convert argument placeholders
- body = self._convert_argument_placeholder(
- body, "$ARGUMENTS", agent_config["args"]
- )
-
- # Render in agent-specific format
- if agent_config["format"] == "markdown":
- output = self._render_markdown_command(frontmatter, body, manifest.id)
- elif agent_config["format"] == "toml":
- output = self._render_toml_command(frontmatter, body, manifest.id)
- else:
- raise ExtensionError(f"Unsupported format: {agent_config['format']}")
-
- # Write command file
- dest_file = commands_dir / f"{cmd_name}{agent_config['extension']}"
- dest_file.parent.mkdir(parents=True, exist_ok=True)
- dest_file.write_text(output)
-
- # Generate companion .prompt.md for Copilot agents
- if agent_name == "copilot":
- self._write_copilot_prompt(project_root, cmd_name)
-
- registered.append(cmd_name)
-
- # Register aliases
- for alias in cmd_info.get("aliases", []):
- alias_file = commands_dir / f"{alias}{agent_config['extension']}"
- alias_file.parent.mkdir(parents=True, exist_ok=True)
- alias_file.write_text(output)
- # Generate companion .prompt.md for alias too
- if agent_name == "copilot":
- self._write_copilot_prompt(project_root, alias)
- registered.append(alias)
-
- return registered
-
- @staticmethod
- def _write_copilot_prompt(project_root: Path, cmd_name: str) -> None:
- """Generate a companion .prompt.md file for a Copilot agent command.
-
- Copilot requires a .prompt.md file in .github/prompts/ that references
- the corresponding .agent.md file in .github/agents/ via an ``agent:``
- frontmatter field.
-
- Args:
- project_root: Path to project root
- cmd_name: Command name (used as the file stem, e.g. 'speckit.my-ext.example')
- """
- prompts_dir = project_root / ".github" / "prompts"
- prompts_dir.mkdir(parents=True, exist_ok=True)
- prompt_file = prompts_dir / f"{cmd_name}.prompt.md"
- prompt_file.write_text(f"---\nagent: {cmd_name}\n---\n")
+ context_note = f"\n<!-- Extension: {manifest.id} -->\n<!-- Config: .specify/extensions/{manifest.id}/ -->\n"
+ return self._registrar.register_commands(
+ agent_name, manifest.commands, manifest.id, extension_dir, project_root,
+ context_note=context_note
+ )
def register_commands_for_all_agents(
self,
@@ -1072,35 +766,20 @@ class CommandRegistrar:
extension_dir: Path,
project_root: Path
) -> Dict[str, List[str]]:
- """Register extension commands for all detected agents.
-
- Args:
- manifest: Extension manifest
- extension_dir: Path to extension directory
- project_root: Path to project root
-
- Returns:
- Dictionary mapping agent names to list of registered commands
- """
- results = {}
-
- # Detect which agents are present in the project
- for agent_name, agent_config in self.AGENT_CONFIGS.items():
- agent_dir = project_root / agent_config["dir"].split("/")[0]
-
- # Register if agent directory exists
- if agent_dir.exists():
- try:
- registered = self.register_commands_for_agent(
- agent_name, manifest, extension_dir, project_root
- )
- if registered:
- results[agent_name] = registered
- except ExtensionError:
- # Skip agent on error
- continue
+ """Register extension commands for all detected agents."""
+ context_note = f"\n<!-- Extension: {manifest.id} -->\n<!-- Config: .specify/extensions/{manifest.id}/ -->\n"
+ return self._registrar.register_commands_for_all_agents(
+ manifest.commands, manifest.id, extension_dir, project_root,
+ context_note=context_note
+ )
- return results
+ def unregister_commands(
+ self,
+ registered_commands: Dict[str, List[str]],
+ project_root: Path
+ ) -> None:
+ """Remove previously registered command files from agent directories."""
+ self._registrar.unregister_commands(registered_commands, project_root)
def register_commands_for_claude(
self,
@@ -1108,16 +787,7 @@ class CommandRegistrar:
extension_dir: Path,
project_root: Path
) -> List[str]:
- """Register extension commands for Claude Code agent.
-
- Args:
- manifest: Extension manifest
- extension_dir: Path to extension directory
- project_root: Path to project root
-
- Returns:
- List of registered command names
- """
+ """Register extension commands for Claude Code agent."""
return self.register_commands_for_agent("claude", manifest, extension_dir, project_root)
diff --git a/src/specify_cli/presets.py b/src/specify_cli/presets.py
new file mode 100644
index 000000000..151963379
--- /dev/null
+++ b/src/specify_cli/presets.py
@@ -0,0 +1,1530 @@
+"""
+Preset Manager for Spec Kit
+
+Handles installation, removal, and management of Spec Kit presets.
+Presets are self-contained, versioned collections of templates
+(artifact, command, and script templates) that can be installed to
+customize the Spec-Driven Development workflow.
+"""
+
+import json
+import hashlib
+import os
+import tempfile
+import zipfile
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Dict, List, Any
+from datetime import datetime, timezone
+import re
+
+import yaml
+from packaging import version as pkg_version
+from packaging.specifiers import SpecifierSet, InvalidSpecifier
+
+
+@dataclass
+class PresetCatalogEntry:
+ """Represents a single entry in the preset catalog stack."""
+ url: str
+ name: str
+ priority: int
+ install_allowed: bool
+ description: str = ""
+
+
+class PresetError(Exception):
+ """Base exception for preset-related errors."""
+ pass
+
+
+class PresetValidationError(PresetError):
+ """Raised when preset manifest validation fails."""
+ pass
+
+
+class PresetCompatibilityError(PresetError):
+ """Raised when preset is incompatible with current environment."""
+ pass
+
+
+VALID_PRESET_TEMPLATE_TYPES = {"template", "command", "script"}
+
+
+class PresetManifest:
+ """Represents and validates a preset manifest (preset.yml)."""
+
+ SCHEMA_VERSION = "1.0"
+ REQUIRED_FIELDS = ["schema_version", "preset", "requires", "provides"]
+
+ def __init__(self, manifest_path: Path):
+ """Load and validate preset manifest.
+
+ Args:
+ manifest_path: Path to preset.yml file
+
+ Raises:
+ PresetValidationError: If manifest is invalid
+ """
+ self.path = manifest_path
+ self.data = self._load_yaml(manifest_path)
+ self._validate()
+
+ def _load_yaml(self, path: Path) -> dict:
+ """Load YAML file safely."""
+ try:
+ with open(path, 'r') as f:
+ return yaml.safe_load(f) or {}
+ except yaml.YAMLError as e:
+ raise PresetValidationError(f"Invalid YAML in {path}: {e}")
+ except FileNotFoundError:
+ raise PresetValidationError(f"Manifest not found: {path}")
+
+ def _validate(self):
+ """Validate manifest structure and required fields."""
+ # Check required top-level fields
+ for field in self.REQUIRED_FIELDS:
+ if field not in self.data:
+ raise PresetValidationError(f"Missing required field: {field}")
+
+ # Validate schema version
+ if self.data["schema_version"] != self.SCHEMA_VERSION:
+ raise PresetValidationError(
+ f"Unsupported schema version: {self.data['schema_version']} "
+ f"(expected {self.SCHEMA_VERSION})"
+ )
+
+ # Validate preset metadata
+ pack = self.data["preset"]
+ for field in ["id", "name", "version", "description"]:
+ if field not in pack:
+ raise PresetValidationError(f"Missing preset.{field}")
+
+ # Validate pack ID format
+ if not re.match(r'^[a-z0-9-]+$', pack["id"]):
+ raise PresetValidationError(
+ f"Invalid preset ID '{pack['id']}': "
+ "must be lowercase alphanumeric with hyphens only"
+ )
+
+ # Validate semantic version
+ try:
+ pkg_version.Version(pack["version"])
+ except pkg_version.InvalidVersion:
+ raise PresetValidationError(f"Invalid version: {pack['version']}")
+
+ # Validate requires section
+ requires = self.data["requires"]
+ if "speckit_version" not in requires:
+ raise PresetValidationError("Missing requires.speckit_version")
+
+ # Validate provides section
+ provides = self.data["provides"]
+ if "templates" not in provides or not provides["templates"]:
+ raise PresetValidationError(
+ "Preset must provide at least one template"
+ )
+
+ # Validate templates
+ for tmpl in provides["templates"]:
+ if "type" not in tmpl or "name" not in tmpl or "file" not in tmpl:
+ raise PresetValidationError(
+ "Template missing 'type', 'name', or 'file'"
+ )
+
+ if tmpl["type"] not in VALID_PRESET_TEMPLATE_TYPES:
+ raise PresetValidationError(
+ f"Invalid template type '{tmpl['type']}': "
+ f"must be one of {sorted(VALID_PRESET_TEMPLATE_TYPES)}"
+ )
+
+ # Validate file path safety: must be relative, no parent traversal
+ file_path = tmpl["file"]
+ normalized = os.path.normpath(file_path)
+ if os.path.isabs(normalized) or normalized.startswith(".."):
+ raise PresetValidationError(
+ f"Invalid template file path '{file_path}': "
+ "must be a relative path within the preset directory"
+ )
+
+ # Validate template name format
+ if tmpl["type"] == "command":
+ # Commands use dot notation (e.g. speckit.specify)
+ if not re.match(r'^[a-z0-9.-]+$', tmpl["name"]):
+ raise PresetValidationError(
+ f"Invalid command name '{tmpl['name']}': "
+ "must be lowercase alphanumeric with hyphens and dots only"
+ )
+ else:
+ if not re.match(r'^[a-z0-9-]+$', tmpl["name"]):
+ raise PresetValidationError(
+ f"Invalid template name '{tmpl['name']}': "
+ "must be lowercase alphanumeric with hyphens only"
+ )
+
+ @property
+ def id(self) -> str:
+ """Get preset ID."""
+ return self.data["preset"]["id"]
+
+ @property
+ def name(self) -> str:
+ """Get preset name."""
+ return self.data["preset"]["name"]
+
+ @property
+ def version(self) -> str:
+ """Get preset version."""
+ return self.data["preset"]["version"]
+
+ @property
+ def description(self) -> str:
+ """Get preset description."""
+ return self.data["preset"]["description"]
+
+ @property
+ def author(self) -> str:
+ """Get preset author."""
+ return self.data["preset"].get("author", "")
+
+ @property
+ def requires_speckit_version(self) -> str:
+ """Get required spec-kit version range."""
+ return self.data["requires"]["speckit_version"]
+
+ @property
+ def templates(self) -> List[Dict[str, Any]]:
+ """Get list of provided templates."""
+ return self.data["provides"]["templates"]
+
+ @property
+ def tags(self) -> List[str]:
+ """Get preset tags."""
+ return self.data.get("tags", [])
+
+ def get_hash(self) -> str:
+ """Calculate SHA256 hash of manifest file."""
+ with open(self.path, 'rb') as f:
+ return f"sha256:{hashlib.sha256(f.read()).hexdigest()}"
+
+
+class PresetRegistry:
+ """Manages the registry of installed presets."""
+
+ REGISTRY_FILE = ".registry"
+ SCHEMA_VERSION = "1.0"
+
+ def __init__(self, packs_dir: Path):
+ """Initialize registry.
+
+ Args:
+ packs_dir: Path to .specify/presets/ directory
+ """
+ self.packs_dir = packs_dir
+ self.registry_path = packs_dir / self.REGISTRY_FILE
+ self.data = self._load()
+
+ def _load(self) -> dict:
+ """Load registry from disk."""
+ if not self.registry_path.exists():
+ return {
+ "schema_version": self.SCHEMA_VERSION,
+ "presets": {}
+ }
+
+ try:
+ with open(self.registry_path, 'r') as f:
+ return json.load(f)
+ except (json.JSONDecodeError, FileNotFoundError):
+ return {
+ "schema_version": self.SCHEMA_VERSION,
+ "presets": {}
+ }
+
+ def _save(self):
+ """Save registry to disk."""
+ self.packs_dir.mkdir(parents=True, exist_ok=True)
+ with open(self.registry_path, 'w') as f:
+ json.dump(self.data, f, indent=2)
+
+ def add(self, pack_id: str, metadata: dict):
+ """Add preset to registry.
+
+ Args:
+ pack_id: Preset ID
+ metadata: Pack metadata (version, source, etc.)
+ """
+ self.data["presets"][pack_id] = {
+ **metadata,
+ "installed_at": datetime.now(timezone.utc).isoformat()
+ }
+ self._save()
+
+ def remove(self, pack_id: str):
+ """Remove preset from registry.
+
+ Args:
+ pack_id: Preset ID
+ """
+ if pack_id in self.data["presets"]:
+ del self.data["presets"][pack_id]
+ self._save()
+
+ def get(self, pack_id: str) -> Optional[dict]:
+ """Get preset metadata from registry.
+
+ Args:
+ pack_id: Preset ID
+
+ Returns:
+ Pack metadata or None if not found
+ """
+ return self.data["presets"].get(pack_id)
+
+ def list(self) -> Dict[str, dict]:
+ """Get all installed presets.
+
+ Returns:
+ Dictionary of pack_id -> metadata
+ """
+ return self.data["presets"]
+
+ def list_by_priority(self) -> List[tuple]:
+ """Get all installed presets sorted by priority.
+
+ Lower priority number = higher precedence (checked first).
+
+ Returns:
+ List of (pack_id, metadata) tuples sorted by priority
+ """
+ packs = self.data["presets"]
+ return sorted(
+ packs.items(),
+ key=lambda item: item[1].get("priority", 10),
+ )
+
+ def is_installed(self, pack_id: str) -> bool:
+ """Check if preset is installed.
+
+ Args:
+ pack_id: Preset ID
+
+ Returns:
+ True if pack is installed
+ """
+ return pack_id in self.data["presets"]
+
+
+class PresetManager:
+ """Manages preset lifecycle: installation, removal, updates."""
+
+ def __init__(self, project_root: Path):
+ """Initialize preset manager.
+
+ Args:
+ project_root: Path to project root directory
+ """
+ self.project_root = project_root
+ self.presets_dir = project_root / ".specify" / "presets"
+ self.registry = PresetRegistry(self.presets_dir)
+
+ def check_compatibility(
+ self,
+ manifest: PresetManifest,
+ speckit_version: str
+ ) -> bool:
+ """Check if preset is compatible with current spec-kit version.
+
+ Args:
+ manifest: Preset manifest
+ speckit_version: Current spec-kit version
+
+ Returns:
+ True if compatible
+
+ Raises:
+ PresetCompatibilityError: If pack is incompatible
+ """
+ required = manifest.requires_speckit_version
+ current = pkg_version.Version(speckit_version)
+
+ try:
+ specifier = SpecifierSet(required)
+ if current not in specifier:
+ raise PresetCompatibilityError(
+ f"Preset requires spec-kit {required}, "
+ f"but {speckit_version} is installed.\n"
+ f"Upgrade spec-kit with: uv tool install specify-cli --force"
+ )
+ except InvalidSpecifier:
+ raise PresetCompatibilityError(
+ f"Invalid version specifier: {required}"
+ )
+
+ return True
+
+ def _register_commands(
+ self,
+ manifest: PresetManifest,
+ preset_dir: Path
+ ) -> Dict[str, List[str]]:
+ """Register preset command overrides with all detected AI agents.
+
+ Scans the preset's templates for type "command", reads each command
+ file, and writes it to every detected agent directory using the
+ CommandRegistrar from the agents module.
+
+ Args:
+ manifest: Preset manifest
+ preset_dir: Installed preset directory
+
+ Returns:
+ Dictionary mapping agent names to lists of registered command names
+ """
+ command_templates = [
+ t for t in manifest.templates if t.get("type") == "command"
+ ]
+ if not command_templates:
+ return {}
+
+ # Filter out extension command overrides if the extension isn't installed.
+ # Command names follow the pattern: speckit.<ext-id>.<cmd-name>
+ # Core commands (e.g. speckit.specify) have only one dot β€” always register.
+ extensions_dir = self.project_root / ".specify" / "extensions"
+ filtered = []
+ for cmd in command_templates:
+ parts = cmd["name"].split(".")
+ if len(parts) >= 3 and parts[0] == "speckit":
+ ext_id = parts[1]
+ if not (extensions_dir / ext_id).is_dir():
+ continue
+ filtered.append(cmd)
+
+ if not filtered:
+ return {}
+
+ try:
+ from .agents import CommandRegistrar
+ except ImportError:
+ return {}
+
+ registrar = CommandRegistrar()
+ return registrar.register_commands_for_all_agents(
+ filtered, manifest.id, preset_dir, self.project_root
+ )
+
+ def _unregister_commands(self, registered_commands: Dict[str, List[str]]) -> None:
+ """Remove previously registered command files from agent directories.
+
+ Args:
+ registered_commands: Dict mapping agent names to command name lists
+ """
+ try:
+ from .agents import CommandRegistrar
+ except ImportError:
+ return
+
+ registrar = CommandRegistrar()
+ registrar.unregister_commands(registered_commands, self.project_root)
+
+ def _get_skills_dir(self) -> Optional[Path]:
+ """Return the skills directory if ``--ai-skills`` was used during init.
+
+ Reads ``.specify/init-options.json`` to determine whether skills
+ are enabled and which agent was selected, then delegates to
+ the module-level ``_get_skills_dir()`` helper for the concrete path.
+
+ Returns:
+ The skills directory ``Path``, or ``None`` if skills were not
+ enabled or the init-options file is missing.
+ """
+ from . import load_init_options, _get_skills_dir
+
+ opts = load_init_options(self.project_root)
+ if not opts.get("ai_skills"):
+ return None
+
+ agent = opts.get("ai")
+ if not agent:
+ return None
+
+ skills_dir = _get_skills_dir(self.project_root, agent)
+ if not skills_dir.is_dir():
+ return None
+
+ return skills_dir
+
+ def _register_skills(
+ self,
+ manifest: "PresetManifest",
+ preset_dir: Path,
+ ) -> List[str]:
+ """Generate SKILL.md files for preset command overrides.
+
+ For every command template in the preset, checks whether a
+ corresponding skill already exists in any detected skills
+ directory. If so, the skill is overwritten with content derived
+ from the preset's command file. This ensures that presets that
+ override commands also propagate to the agentskills.io skill
+ layer when ``--ai-skills`` was used during project initialisation.
+
+ Args:
+ manifest: Preset manifest.
+ preset_dir: Installed preset directory.
+
+ Returns:
+ List of skill names that were written (for registry storage).
+ """
+ command_templates = [
+ t for t in manifest.templates if t.get("type") == "command"
+ ]
+ if not command_templates:
+ return []
+
+ # Filter out extension command overrides if the extension isn't installed,
+ # matching the same logic used by _register_commands().
+ extensions_dir = self.project_root / ".specify" / "extensions"
+ filtered = []
+ for cmd in command_templates:
+ parts = cmd["name"].split(".")
+ if len(parts) >= 3 and parts[0] == "speckit":
+ ext_id = parts[1]
+ if not (extensions_dir / ext_id).is_dir():
+ continue
+ filtered.append(cmd)
+
+ if not filtered:
+ return []
+
+ skills_dir = self._get_skills_dir()
+ if not skills_dir:
+ return []
+
+ from . import SKILL_DESCRIPTIONS, load_init_options
+
+ opts = load_init_options(self.project_root)
+ selected_ai = opts.get("ai", "")
+
+ written: List[str] = []
+
+ for cmd_tmpl in filtered:
+ cmd_name = cmd_tmpl["name"]
+ cmd_file_rel = cmd_tmpl["file"]
+ source_file = preset_dir / cmd_file_rel
+ if not source_file.exists():
+ continue
+
+ # Derive the short command name (e.g. "specify" from "speckit.specify")
+ short_name = cmd_name
+ if short_name.startswith("speckit."):
+ short_name = short_name[len("speckit."):]
+ # Kimi CLI discovers skills by directory name and invokes them as
+ # /skill:<name> β€” use dot separator to match packaging convention.
+ if selected_ai == "kimi":
+ skill_name = f"speckit.{short_name}"
+ else:
+ skill_name = f"speckit-{short_name}"
+
+ # Only overwrite if the skill already exists (i.e. --ai-skills was used)
+ skill_subdir = skills_dir / skill_name
+ if not skill_subdir.exists():
+ continue
+
+ # Parse the command file
+ content = source_file.read_text(encoding="utf-8")
+ if content.startswith("---"):
+ parts = content.split("---", 2)
+ if len(parts) >= 3:
+ frontmatter = yaml.safe_load(parts[1])
+ if not isinstance(frontmatter, dict):
+ frontmatter = {}
+ body = parts[2].strip()
+ else:
+ frontmatter = {}
+ body = content
+ else:
+ frontmatter = {}
+ body = content
+
+ original_desc = frontmatter.get("description", "")
+ enhanced_desc = SKILL_DESCRIPTIONS.get(
+ short_name,
+ original_desc or f"Spec-kit workflow command: {short_name}",
+ )
+
+ frontmatter_data = {
+ "name": skill_name,
+ "description": enhanced_desc,
+ "compatibility": "Requires spec-kit project structure with .specify/ directory",
+ "metadata": {
+ "author": "github-spec-kit",
+ "source": f"preset:{manifest.id}",
+ },
+ }
+ frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
+ skill_content = (
+ f"---\n"
+ f"{frontmatter_text}\n"
+ f"---\n\n"
+ f"# Speckit {short_name.title()} Skill\n\n"
+ f"{body}\n"
+ )
+
+ skill_file = skill_subdir / "SKILL.md"
+ skill_file.write_text(skill_content, encoding="utf-8")
+ written.append(skill_name)
+
+ return written
+
+ def _unregister_skills(self, skill_names: List[str], preset_dir: Path) -> None:
+ """Restore original SKILL.md files after a preset is removed.
+
+ For each skill that was overridden by the preset, attempts to
+ regenerate the skill from the core command template. If no core
+ template exists, the skill directory is removed.
+
+ Args:
+ skill_names: List of skill names written by the preset.
+ preset_dir: The preset's installed directory (may already be deleted).
+ """
+ if not skill_names:
+ return
+
+ skills_dir = self._get_skills_dir()
+ if not skills_dir:
+ return
+
+ from . import SKILL_DESCRIPTIONS
+
+ # Locate core command templates from the project's installed templates
+ core_templates_dir = self.project_root / ".specify" / "templates" / "commands"
+
+ for skill_name in skill_names:
+ # Derive command name from skill name (speckit-specify -> specify)
+ short_name = skill_name
+ if short_name.startswith("speckit-"):
+ short_name = short_name[len("speckit-"):]
+ elif short_name.startswith("speckit."):
+ short_name = short_name[len("speckit."):]
+
+ skill_subdir = skills_dir / skill_name
+ skill_file = skill_subdir / "SKILL.md"
+ if not skill_file.exists():
+ continue
+
+ # Try to find the core command template
+ core_file = core_templates_dir / f"{short_name}.md" if core_templates_dir.exists() else None
+ if core_file and not core_file.exists():
+ core_file = None
+
+ if core_file:
+ # Restore from core template
+ content = core_file.read_text(encoding="utf-8")
+ if content.startswith("---"):
+ parts = content.split("---", 2)
+ if len(parts) >= 3:
+ frontmatter = yaml.safe_load(parts[1])
+ if not isinstance(frontmatter, dict):
+ frontmatter = {}
+ body = parts[2].strip()
+ else:
+ frontmatter = {}
+ body = content
+ else:
+ frontmatter = {}
+ body = content
+
+ original_desc = frontmatter.get("description", "")
+ enhanced_desc = SKILL_DESCRIPTIONS.get(
+ short_name,
+ original_desc or f"Spec-kit workflow command: {short_name}",
+ )
+
+ frontmatter_data = {
+ "name": skill_name,
+ "description": enhanced_desc,
+ "compatibility": "Requires spec-kit project structure with .specify/ directory",
+ "metadata": {
+ "author": "github-spec-kit",
+ "source": f"templates/commands/{short_name}.md",
+ },
+ }
+ frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
+ skill_content = (
+ f"---\n"
+ f"{frontmatter_text}\n"
+ f"---\n\n"
+ f"# Speckit {short_name.title()} Skill\n\n"
+ f"{body}\n"
+ )
+ skill_file.write_text(skill_content, encoding="utf-8")
+ else:
+ # No core template β€” remove the skill entirely
+ shutil.rmtree(skill_subdir)
+
+ def install_from_directory(
+ self,
+ source_dir: Path,
+ speckit_version: str,
+ priority: int = 10,
+ ) -> PresetManifest:
+ """Install preset from a local directory.
+
+ Args:
+ source_dir: Path to preset directory
+ speckit_version: Current spec-kit version
+ priority: Resolution priority (lower = higher precedence, default 10)
+
+ Returns:
+ Installed preset manifest
+
+ Raises:
+ PresetValidationError: If manifest is invalid
+ PresetCompatibilityError: If pack is incompatible
+ """
+ manifest_path = source_dir / "preset.yml"
+ manifest = PresetManifest(manifest_path)
+
+ self.check_compatibility(manifest, speckit_version)
+
+ if self.registry.is_installed(manifest.id):
+ raise PresetError(
+ f"Preset '{manifest.id}' is already installed. "
+ f"Use 'specify preset remove {manifest.id}' first."
+ )
+
+ dest_dir = self.presets_dir / manifest.id
+ if dest_dir.exists():
+ shutil.rmtree(dest_dir)
+
+ shutil.copytree(source_dir, dest_dir)
+
+ # Register command overrides with AI agents
+ registered_commands = self._register_commands(manifest, dest_dir)
+
+ # Update corresponding skills when --ai-skills was previously used
+ registered_skills = self._register_skills(manifest, dest_dir)
+
+ self.registry.add(manifest.id, {
+ "version": manifest.version,
+ "source": "local",
+ "manifest_hash": manifest.get_hash(),
+ "enabled": True,
+ "priority": priority,
+ "registered_commands": registered_commands,
+ "registered_skills": registered_skills,
+ })
+
+ return manifest
+
+ def install_from_zip(
+ self,
+ zip_path: Path,
+ speckit_version: str,
+ priority: int = 10,
+ ) -> PresetManifest:
+ """Install preset from ZIP file.
+
+ Args:
+ zip_path: Path to preset ZIP file
+ speckit_version: Current spec-kit version
+
+ Returns:
+ Installed preset manifest
+
+ Raises:
+ PresetValidationError: If manifest is invalid
+ PresetCompatibilityError: If pack is incompatible
+ """
+ with tempfile.TemporaryDirectory() as tmpdir:
+ temp_path = Path(tmpdir)
+
+ with zipfile.ZipFile(zip_path, 'r') as zf:
+ temp_path_resolved = temp_path.resolve()
+ for member in zf.namelist():
+ member_path = (temp_path / member).resolve()
+ try:
+ member_path.relative_to(temp_path_resolved)
+ except ValueError:
+ raise PresetValidationError(
+ f"Unsafe path in ZIP archive: {member} "
+ "(potential path traversal)"
+ )
+ zf.extractall(temp_path)
+
+ pack_dir = temp_path
+ manifest_path = pack_dir / "preset.yml"
+
+ if not manifest_path.exists():
+ subdirs = [d for d in temp_path.iterdir() if d.is_dir()]
+ if len(subdirs) == 1:
+ pack_dir = subdirs[0]
+ manifest_path = pack_dir / "preset.yml"
+
+ if not manifest_path.exists():
+ raise PresetValidationError(
+ "No preset.yml found in ZIP file"
+ )
+
+ return self.install_from_directory(pack_dir, speckit_version, priority)
+
+ def remove(self, pack_id: str) -> bool:
+ """Remove an installed preset.
+
+ Args:
+ pack_id: Preset ID
+
+ Returns:
+ True if pack was removed
+ """
+ if not self.registry.is_installed(pack_id):
+ return False
+
+ # Unregister commands from AI agents
+ metadata = self.registry.get(pack_id)
+ registered_commands = metadata.get("registered_commands", {}) if metadata else {}
+ if registered_commands:
+ self._unregister_commands(registered_commands)
+
+ # Restore original skills when preset is removed
+ registered_skills = metadata.get("registered_skills", []) if metadata else []
+ pack_dir = self.presets_dir / pack_id
+ if registered_skills:
+ self._unregister_skills(registered_skills, pack_dir)
+
+ if pack_dir.exists():
+ shutil.rmtree(pack_dir)
+
+ self.registry.remove(pack_id)
+ return True
+
+ def list_installed(self) -> List[Dict[str, Any]]:
+ """List all installed presets with metadata.
+
+ Returns:
+ List of preset metadata dictionaries
+ """
+ result = []
+
+ for pack_id, metadata in self.registry.list().items():
+ pack_dir = self.presets_dir / pack_id
+ manifest_path = pack_dir / "preset.yml"
+
+ try:
+ manifest = PresetManifest(manifest_path)
+ result.append({
+ "id": pack_id,
+ "name": manifest.name,
+ "version": metadata["version"],
+ "description": manifest.description,
+ "enabled": metadata.get("enabled", True),
+ "installed_at": metadata.get("installed_at"),
+ "template_count": len(manifest.templates),
+ "tags": manifest.tags,
+ "priority": metadata.get("priority", 10),
+ })
+ except PresetValidationError:
+ result.append({
+ "id": pack_id,
+ "name": pack_id,
+ "version": metadata.get("version", "unknown"),
+ "description": "⚠️ Corrupted preset",
+ "enabled": False,
+ "installed_at": metadata.get("installed_at"),
+ "template_count": 0,
+ "tags": [],
+ "priority": metadata.get("priority", 10),
+ })
+
+ return result
+
+ def get_pack(self, pack_id: str) -> Optional[PresetManifest]:
+ """Get manifest for an installed preset.
+
+ Args:
+ pack_id: Preset ID
+
+ Returns:
+ Preset manifest or None if not installed
+ """
+ if not self.registry.is_installed(pack_id):
+ return None
+
+ pack_dir = self.presets_dir / pack_id
+ manifest_path = pack_dir / "preset.yml"
+
+ try:
+ return PresetManifest(manifest_path)
+ except PresetValidationError:
+ return None
+
+
+class PresetCatalog:
+ """Manages preset catalog fetching, caching, and searching.
+
+ Supports multi-catalog stacks with priority-based resolution,
+ mirroring the extension catalog system.
+ """
+
+ DEFAULT_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.json"
+ COMMUNITY_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json"
+ CACHE_DURATION = 3600 # 1 hour in seconds
+
+ def __init__(self, project_root: Path):
+ """Initialize preset catalog manager.
+
+ Args:
+ project_root: Root directory of the spec-kit project
+ """
+ self.project_root = project_root
+ self.presets_dir = project_root / ".specify" / "presets"
+ self.cache_dir = self.presets_dir / ".cache"
+ self.cache_file = self.cache_dir / "catalog.json"
+ self.cache_metadata_file = self.cache_dir / "catalog-metadata.json"
+
+ def _validate_catalog_url(self, url: str) -> None:
+ """Validate that a catalog URL uses HTTPS (localhost HTTP allowed).
+
+ Args:
+ url: URL to validate
+
+ Raises:
+ PresetValidationError: If URL is invalid or uses non-HTTPS scheme
+ """
+ from urllib.parse import urlparse
+
+ parsed = urlparse(url)
+ is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
+ if parsed.scheme != "https" and not (
+ parsed.scheme == "http" and is_localhost
+ ):
+ raise PresetValidationError(
+ f"Catalog URL must use HTTPS (got {parsed.scheme}://). "
+ "HTTP is only allowed for localhost."
+ )
+ if not parsed.netloc:
+ raise PresetValidationError(
+ "Catalog URL must be a valid URL with a host."
+ )
+
+ def _load_catalog_config(self, config_path: Path) -> Optional[List[PresetCatalogEntry]]:
+ """Load catalog stack configuration from a YAML file.
+
+ Args:
+ config_path: Path to preset-catalogs.yml
+
+ Returns:
+ Ordered list of PresetCatalogEntry objects, or None if file
+ doesn't exist or contains no valid catalog entries.
+
+ Raises:
+ PresetValidationError: If any catalog entry has an invalid URL,
+ the file cannot be parsed, or a priority value is invalid.
+ """
+ if not config_path.exists():
+ return None
+ try:
+ data = yaml.safe_load(config_path.read_text()) or {}
+ except (yaml.YAMLError, OSError) as e:
+ raise PresetValidationError(
+ f"Failed to read catalog config {config_path}: {e}"
+ )
+ if not isinstance(data, dict):
+ raise PresetValidationError(
+ f"Invalid catalog config {config_path}: expected a mapping at root, got {type(data).__name__}"
+ )
+ catalogs_data = data.get("catalogs", [])
+ if not catalogs_data:
+ return None
+ if not isinstance(catalogs_data, list):
+ raise PresetValidationError(
+ f"Invalid catalog config: 'catalogs' must be a list, got {type(catalogs_data).__name__}"
+ )
+ entries: List[PresetCatalogEntry] = []
+ for idx, item in enumerate(catalogs_data):
+ if not isinstance(item, dict):
+ raise PresetValidationError(
+ f"Invalid catalog entry at index {idx}: expected a mapping, got {type(item).__name__}"
+ )
+ url = str(item.get("url", "")).strip()
+ if not url:
+ continue
+ self._validate_catalog_url(url)
+ try:
+ priority = int(item.get("priority", idx + 1))
+ except (TypeError, ValueError):
+ raise PresetValidationError(
+ f"Invalid priority for catalog '{item.get('name', idx + 1)}': "
+ f"expected integer, got {item.get('priority')!r}"
+ )
+ raw_install = item.get("install_allowed", False)
+ if isinstance(raw_install, str):
+ install_allowed = raw_install.strip().lower() in ("true", "yes", "1")
+ else:
+ install_allowed = bool(raw_install)
+ entries.append(PresetCatalogEntry(
+ url=url,
+ name=str(item.get("name", f"catalog-{idx + 1}")),
+ priority=priority,
+ install_allowed=install_allowed,
+ description=str(item.get("description", "")),
+ ))
+ entries.sort(key=lambda e: e.priority)
+ return entries if entries else None
+
+ def get_active_catalogs(self) -> List[PresetCatalogEntry]:
+ """Get the ordered list of active preset catalogs.
+
+ Resolution order:
+ 1. SPECKIT_PRESET_CATALOG_URL env var β€” single catalog replacing all defaults
+ 2. Project-level .specify/preset-catalogs.yml
+ 3. User-level ~/.specify/preset-catalogs.yml
+ 4. Built-in default stack (default + community)
+
+ Returns:
+ List of PresetCatalogEntry objects sorted by priority (ascending)
+
+ Raises:
+ PresetValidationError: If a catalog URL is invalid
+ """
+ import sys
+
+ # 1. SPECKIT_PRESET_CATALOG_URL env var replaces all defaults
+ if env_value := os.environ.get("SPECKIT_PRESET_CATALOG_URL"):
+ catalog_url = env_value.strip()
+ self._validate_catalog_url(catalog_url)
+ if catalog_url != self.DEFAULT_CATALOG_URL:
+ if not getattr(self, "_non_default_catalog_warning_shown", False):
+ print(
+ "Warning: Using non-default preset catalog. "
+ "Only use catalogs from sources you trust.",
+ file=sys.stderr,
+ )
+ self._non_default_catalog_warning_shown = True
+ return [PresetCatalogEntry(url=catalog_url, name="custom", priority=1, install_allowed=True, description="Custom catalog via SPECKIT_PRESET_CATALOG_URL")]
+
+ # 2. Project-level config overrides all defaults
+ project_config_path = self.project_root / ".specify" / "preset-catalogs.yml"
+ catalogs = self._load_catalog_config(project_config_path)
+ if catalogs is not None:
+ return catalogs
+
+ # 3. User-level config
+ user_config_path = Path.home() / ".specify" / "preset-catalogs.yml"
+ catalogs = self._load_catalog_config(user_config_path)
+ if catalogs is not None:
+ return catalogs
+
+ # 4. Built-in default stack
+ return [
+ PresetCatalogEntry(url=self.DEFAULT_CATALOG_URL, name="default", priority=1, install_allowed=True, description="Built-in catalog of installable presets"),
+ PresetCatalogEntry(url=self.COMMUNITY_CATALOG_URL, name="community", priority=2, install_allowed=False, description="Community-contributed presets (discovery only)"),
+ ]
+
+ def get_catalog_url(self) -> str:
+ """Get the primary catalog URL.
+
+ Returns the URL of the highest-priority catalog. Kept for backward
+ compatibility. Use get_active_catalogs() for full multi-catalog support.
+
+ Returns:
+ URL of the primary catalog
+ """
+ active = self.get_active_catalogs()
+ return active[0].url if active else self.DEFAULT_CATALOG_URL
+
+ def _get_cache_paths(self, url: str):
+ """Get cache file paths for a given catalog URL.
+
+ For the DEFAULT_CATALOG_URL, uses legacy cache files for backward
+ compatibility. For all other URLs, uses URL-hash-based cache files.
+
+ Returns:
+ Tuple of (cache_file_path, cache_metadata_path)
+ """
+ if url == self.DEFAULT_CATALOG_URL:
+ return self.cache_file, self.cache_metadata_file
+ url_hash = hashlib.sha256(url.encode()).hexdigest()[:16]
+ return (
+ self.cache_dir / f"catalog-{url_hash}.json",
+ self.cache_dir / f"catalog-{url_hash}-metadata.json",
+ )
+
+ def _is_url_cache_valid(self, url: str) -> bool:
+ """Check if cached catalog for a specific URL is still valid."""
+ cache_file, metadata_file = self._get_cache_paths(url)
+ if not cache_file.exists() or not metadata_file.exists():
+ return False
+ try:
+ metadata = json.loads(metadata_file.read_text())
+ cached_at = datetime.fromisoformat(metadata.get("cached_at", ""))
+ if cached_at.tzinfo is None:
+ cached_at = cached_at.replace(tzinfo=timezone.utc)
+ age_seconds = (
+ datetime.now(timezone.utc) - cached_at
+ ).total_seconds()
+ return age_seconds < self.CACHE_DURATION
+ except (json.JSONDecodeError, ValueError, KeyError, TypeError):
+ return False
+
+ def _fetch_single_catalog(self, entry: PresetCatalogEntry, force_refresh: bool = False) -> Dict[str, Any]:
+ """Fetch a single catalog with per-URL caching.
+
+ Args:
+ entry: PresetCatalogEntry describing the catalog to fetch
+ force_refresh: If True, bypass cache
+
+ Returns:
+ Catalog data dictionary
+
+ Raises:
+ PresetError: If catalog cannot be fetched
+ """
+ cache_file, metadata_file = self._get_cache_paths(entry.url)
+
+ if not force_refresh and self._is_url_cache_valid(entry.url):
+ try:
+ return json.loads(cache_file.read_text())
+ except json.JSONDecodeError:
+ pass
+
+ try:
+ import urllib.request
+ import urllib.error
+
+ with urllib.request.urlopen(entry.url, timeout=10) as response:
+ catalog_data = json.loads(response.read())
+
+ if (
+ "schema_version" not in catalog_data
+ or "presets" not in catalog_data
+ ):
+ raise PresetError("Invalid preset catalog format")
+
+ self.cache_dir.mkdir(parents=True, exist_ok=True)
+ cache_file.write_text(json.dumps(catalog_data, indent=2))
+ metadata = {
+ "cached_at": datetime.now(timezone.utc).isoformat(),
+ "catalog_url": entry.url,
+ }
+ metadata_file.write_text(json.dumps(metadata, indent=2))
+
+ return catalog_data
+
+ except (ImportError, Exception) as e:
+ if isinstance(e, PresetError):
+ raise
+ raise PresetError(
+ f"Failed to fetch preset catalog from {entry.url}: {e}"
+ )
+
+ def _get_merged_packs(self, force_refresh: bool = False) -> Dict[str, Dict[str, Any]]:
+ """Fetch and merge presets from all active catalogs.
+
+ Higher-priority catalogs (lower priority number) win on ID conflicts.
+
+ Returns:
+ Merged dictionary of pack_id -> pack_data
+ """
+ active_catalogs = self.get_active_catalogs()
+ merged: Dict[str, Dict[str, Any]] = {}
+
+ for entry in reversed(active_catalogs):
+ try:
+ data = self._fetch_single_catalog(entry, force_refresh)
+ for pack_id, pack_data in data.get("presets", {}).items():
+ pack_data_with_catalog = {**pack_data, "_catalog_name": entry.name, "_install_allowed": entry.install_allowed}
+ merged[pack_id] = pack_data_with_catalog
+ except PresetError:
+ continue
+
+ return merged
+
+ def is_cache_valid(self) -> bool:
+ """Check if cached catalog is still valid.
+
+ Returns:
+ True if cache exists and is within cache duration
+ """
+ if not self.cache_file.exists() or not self.cache_metadata_file.exists():
+ return False
+
+ try:
+ metadata = json.loads(self.cache_metadata_file.read_text())
+ cached_at = datetime.fromisoformat(metadata.get("cached_at", ""))
+ if cached_at.tzinfo is None:
+ cached_at = cached_at.replace(tzinfo=timezone.utc)
+ age_seconds = (
+ datetime.now(timezone.utc) - cached_at
+ ).total_seconds()
+ return age_seconds < self.CACHE_DURATION
+ except (json.JSONDecodeError, ValueError, KeyError, TypeError):
+ return False
+
+ def fetch_catalog(self, force_refresh: bool = False) -> Dict[str, Any]:
+ """Fetch preset catalog from URL or cache.
+
+ Args:
+ force_refresh: If True, bypass cache and fetch from network
+
+ Returns:
+ Catalog data dictionary
+
+ Raises:
+ PresetError: If catalog cannot be fetched
+ """
+ catalog_url = self.get_catalog_url()
+
+ if not force_refresh and self.is_cache_valid():
+ try:
+ metadata = json.loads(self.cache_metadata_file.read_text())
+ if metadata.get("catalog_url") == catalog_url:
+ return json.loads(self.cache_file.read_text())
+ except (json.JSONDecodeError, OSError):
+ # Cache is corrupt or unreadable; fall through to network fetch
+ pass
+
+ try:
+ import urllib.request
+ import urllib.error
+
+ with urllib.request.urlopen(catalog_url, timeout=10) as response:
+ catalog_data = json.loads(response.read())
+
+ if (
+ "schema_version" not in catalog_data
+ or "presets" not in catalog_data
+ ):
+ raise PresetError("Invalid preset catalog format")
+
+ self.cache_dir.mkdir(parents=True, exist_ok=True)
+ self.cache_file.write_text(json.dumps(catalog_data, indent=2))
+
+ metadata = {
+ "cached_at": datetime.now(timezone.utc).isoformat(),
+ "catalog_url": catalog_url,
+ }
+ self.cache_metadata_file.write_text(
+ json.dumps(metadata, indent=2)
+ )
+
+ return catalog_data
+
+ except (ImportError, Exception) as e:
+ if isinstance(e, PresetError):
+ raise
+ raise PresetError(
+ f"Failed to fetch preset catalog from {catalog_url}: {e}"
+ )
+
+ def search(
+ self,
+ query: Optional[str] = None,
+ tag: Optional[str] = None,
+ author: Optional[str] = None,
+ ) -> List[Dict[str, Any]]:
+ """Search catalog for presets.
+
+ Searches across all active catalogs (merged by priority) so that
+ community and custom catalogs are included in results.
+
+ Args:
+ query: Search query (searches name, description, tags)
+ tag: Filter by specific tag
+ author: Filter by author name
+
+ Returns:
+ List of matching preset metadata
+ """
+ try:
+ packs = self._get_merged_packs()
+ except PresetError:
+ return []
+
+ results = []
+
+ for pack_id, pack_data in packs.items():
+ if author and pack_data.get("author", "").lower() != author.lower():
+ continue
+
+ if tag and tag.lower() not in [
+ t.lower() for t in pack_data.get("tags", [])
+ ]:
+ continue
+
+ if query:
+ query_lower = query.lower()
+ searchable_text = " ".join(
+ [
+ pack_data.get("name", ""),
+ pack_data.get("description", ""),
+ pack_id,
+ ]
+ + pack_data.get("tags", [])
+ ).lower()
+
+ if query_lower not in searchable_text:
+ continue
+
+ results.append({**pack_data, "id": pack_id})
+
+ return results
+
+ def get_pack_info(
+ self, pack_id: str
+ ) -> Optional[Dict[str, Any]]:
+ """Get detailed information about a specific preset.
+
+ Searches across all active catalogs (merged by priority).
+
+ Args:
+ pack_id: ID of the preset
+
+ Returns:
+ Pack metadata or None if not found
+ """
+ try:
+ packs = self._get_merged_packs()
+ except PresetError:
+ return None
+
+ if pack_id in packs:
+ return {**packs[pack_id], "id": pack_id}
+ return None
+
+ def download_pack(
+ self, pack_id: str, target_dir: Optional[Path] = None
+ ) -> Path:
+ """Download preset ZIP from catalog.
+
+ Args:
+ pack_id: ID of the preset to download
+ target_dir: Directory to save ZIP file (defaults to cache directory)
+
+ Returns:
+ Path to downloaded ZIP file
+
+ Raises:
+ PresetError: If pack not found or download fails
+ """
+ import urllib.request
+ import urllib.error
+
+ pack_info = self.get_pack_info(pack_id)
+ if not pack_info:
+ raise PresetError(
+ f"Preset '{pack_id}' not found in catalog"
+ )
+
+ if not pack_info.get("_install_allowed", True):
+ catalog_name = pack_info.get("_catalog_name", "unknown")
+ raise PresetError(
+ f"Preset '{pack_id}' is from the '{catalog_name}' catalog which does not allow installation. "
+ f"Use --from with the preset's repository URL instead."
+ )
+
+ download_url = pack_info.get("download_url")
+ if not download_url:
+ raise PresetError(
+ f"Preset '{pack_id}' has no download URL"
+ )
+
+ from urllib.parse import urlparse
+
+ parsed = urlparse(download_url)
+ is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
+ if parsed.scheme != "https" and not (
+ parsed.scheme == "http" and is_localhost
+ ):
+ raise PresetError(
+ f"Preset download URL must use HTTPS: {download_url}"
+ )
+
+ if target_dir is None:
+ target_dir = self.cache_dir / "downloads"
+ target_dir.mkdir(parents=True, exist_ok=True)
+
+ version = pack_info.get("version", "unknown")
+ zip_filename = f"{pack_id}-{version}.zip"
+ zip_path = target_dir / zip_filename
+
+ try:
+ with urllib.request.urlopen(download_url, timeout=60) as response:
+ zip_data = response.read()
+
+ zip_path.write_bytes(zip_data)
+ return zip_path
+
+ except urllib.error.URLError as e:
+ raise PresetError(
+ f"Failed to download preset from {download_url}: {e}"
+ )
+ except IOError as e:
+ raise PresetError(f"Failed to save preset ZIP: {e}")
+
+ def clear_cache(self):
+ """Clear all catalog cache files, including per-URL hashed caches."""
+ if self.cache_dir.exists():
+ for f in self.cache_dir.iterdir():
+ if f.is_file() and f.name.startswith("catalog"):
+ f.unlink(missing_ok=True)
+
+
+class PresetResolver:
+ """Resolves template names to file paths using a priority stack.
+
+ Resolution order:
+ 1. .specify/templates/overrides/ - Project-local overrides
+ 2. .specify/presets/<preset-id>/ - Installed presets
+ 3. .specify/extensions/<ext-id>/templates/ - Extension-provided templates
+ 4. .specify/templates/ - Core templates (shipped with Spec Kit)
+ """
+
+ def __init__(self, project_root: Path):
+ """Initialize preset resolver.
+
+ Args:
+ project_root: Path to project root directory
+ """
+ self.project_root = project_root
+ self.templates_dir = project_root / ".specify" / "templates"
+ self.presets_dir = project_root / ".specify" / "presets"
+ self.overrides_dir = self.templates_dir / "overrides"
+ self.extensions_dir = project_root / ".specify" / "extensions"
+
+ def resolve(
+ self,
+ template_name: str,
+ template_type: str = "template",
+ ) -> Optional[Path]:
+ """Resolve a template name to its file path.
+
+ Walks the priority stack and returns the first match.
+
+ Args:
+ template_name: Template name (e.g., "spec-template")
+ template_type: Template type ("template", "command", or "script")
+
+ Returns:
+ Path to the resolved template file, or None if not found
+ """
+ # Determine subdirectory based on template type
+ if template_type == "template":
+ subdirs = ["templates", ""]
+ elif template_type == "command":
+ subdirs = ["commands"]
+ elif template_type == "script":
+ subdirs = ["scripts"]
+ else:
+ subdirs = [""]
+
+ # Determine file extension based on template type
+ ext = ".md"
+ if template_type == "script":
+ ext = ".sh" # scripts use .sh; callers can also check .ps1
+
+ # Priority 1: Project-local overrides
+ if template_type == "script":
+ override = self.overrides_dir / "scripts" / f"{template_name}{ext}"
+ else:
+ override = self.overrides_dir / f"{template_name}{ext}"
+ if override.exists():
+ return override
+
+ # Priority 2: Installed presets (sorted by priority β€” lower number wins)
+ if self.presets_dir.exists():
+ registry = PresetRegistry(self.presets_dir)
+ for pack_id, _metadata in registry.list_by_priority():
+ pack_dir = self.presets_dir / pack_id
+ for subdir in subdirs:
+ if subdir:
+ candidate = pack_dir / subdir / f"{template_name}{ext}"
+ else:
+ candidate = pack_dir / f"{template_name}{ext}"
+ if candidate.exists():
+ return candidate
+
+ # Priority 3: Extension-provided templates
+ if self.extensions_dir.exists():
+ for ext_dir in sorted(self.extensions_dir.iterdir()):
+ if not ext_dir.is_dir() or ext_dir.name.startswith("."):
+ continue
+ for subdir in subdirs:
+ if subdir:
+ candidate = ext_dir / subdir / f"{template_name}{ext}"
+ else:
+ candidate = ext_dir / "templates" / f"{template_name}{ext}"
+ if candidate.exists():
+ return candidate
+
+ # Priority 4: Core templates
+ if template_type == "template":
+ core = self.templates_dir / f"{template_name}.md"
+ if core.exists():
+ return core
+ elif template_type == "command":
+ core = self.templates_dir / "commands" / f"{template_name}.md"
+ if core.exists():
+ return core
+ elif template_type == "script":
+ core = self.templates_dir / "scripts" / f"{template_name}{ext}"
+ if core.exists():
+ return core
+
+ return None
+
+ def resolve_with_source(
+ self,
+ template_name: str,
+ template_type: str = "template",
+ ) -> Optional[Dict[str, str]]:
+ """Resolve a template name and return source attribution.
+
+ Args:
+ template_name: Template name (e.g., "spec-template")
+ template_type: Template type ("template", "command", or "script")
+
+ Returns:
+ Dictionary with 'path' and 'source' keys, or None if not found
+ """
+ # Delegate to resolve() for the actual lookup, then determine source
+ resolved = self.resolve(template_name, template_type)
+ if resolved is None:
+ return None
+
+ resolved_str = str(resolved)
+
+ # Determine source attribution
+ if str(self.overrides_dir) in resolved_str:
+ return {"path": resolved_str, "source": "project override"}
+
+ if str(self.presets_dir) in resolved_str and self.presets_dir.exists():
+ registry = PresetRegistry(self.presets_dir)
+ for pack_id, _metadata in registry.list_by_priority():
+ pack_dir = self.presets_dir / pack_id
+ try:
+ resolved.relative_to(pack_dir)
+ meta = registry.get(pack_id)
+ version = meta.get("version", "?") if meta else "?"
+ return {
+ "path": resolved_str,
+ "source": f"{pack_id} v{version}",
+ }
+ except ValueError:
+ continue
+
+ if self.extensions_dir.exists():
+ for ext_dir in sorted(self.extensions_dir.iterdir()):
+ if not ext_dir.is_dir() or ext_dir.name.startswith("."):
+ continue
+ try:
+ resolved.relative_to(ext_dir)
+ return {
+ "path": resolved_str,
+ "source": f"extension:{ext_dir.name}",
+ }
+ except ValueError:
+ continue
+
+ return {"path": resolved_str, "source": "core"}
diff --git a/tests/test_presets.py b/tests/test_presets.py
new file mode 100644
index 000000000..3ad70c6d1
--- /dev/null
+++ b/tests/test_presets.py
@@ -0,0 +1,1712 @@
+"""
+Unit tests for the preset system.
+
+Tests cover:
+- Preset manifest validation
+- Preset registry operations
+- Preset manager installation/removal
+- Template catalog search
+- Template resolver priority stack
+- Extension-provided templates
+"""
+
+import pytest
+import json
+import tempfile
+import shutil
+import zipfile
+from pathlib import Path
+from datetime import datetime, timezone
+
+import yaml
+
+from specify_cli.presets import (
+ PresetManifest,
+ PresetRegistry,
+ PresetManager,
+ PresetCatalog,
+ PresetCatalogEntry,
+ PresetResolver,
+ PresetError,
+ PresetValidationError,
+ PresetCompatibilityError,
+ VALID_PRESET_TEMPLATE_TYPES,
+)
+
+
+# ===== Fixtures =====
+
+
+def temp_dir():
+ """Create a temporary directory for tests."""
+ tmpdir = tempfile.mkdtemp()
+ yield Path(tmpdir)
+ shutil.rmtree(tmpdir)
+
+
+def valid_pack_data():
+ """Valid preset manifest data."""
+ return {
+ "schema_version": "1.0",
+ "preset": {
+ "id": "test-pack",
+ "name": "Test Preset",
+ "version": "1.0.0",
+ "description": "A test preset",
+ "author": "Test Author",
+ "repository": "https://github.com/test/test-pack",
+ "license": "MIT",
+ },
+ "requires": {
+ "speckit_version": ">=0.1.0",
+ },
+ "provides": {
+ "templates": [
+ {
+ "type": "template",
+ "name": "spec-template",
+ "file": "templates/spec-template.md",
+ "description": "Custom spec template",
+ "replaces": "spec-template",
+ }
+ ]
+ },
+ "tags": ["testing", "example"],
+ }
+
+
+def pack_dir(temp_dir, valid_pack_data):
+ """Create a complete preset directory structure."""
+ p_dir = temp_dir / "test-pack"
+ p_dir.mkdir()
+
+ # Write manifest
+ manifest_path = p_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+
+ # Create templates directory
+ templates_dir = p_dir / "templates"
+ templates_dir.mkdir()
+
+ # Write template file
+ tmpl_file = templates_dir / "spec-template.md"
+ tmpl_file.write_text("# Custom Spec Template\n\nThis is a custom template.\n")
+
+ return p_dir
+
+
+def project_dir(temp_dir):
+ """Create a mock spec-kit project directory."""
+ proj_dir = temp_dir / "project"
+ proj_dir.mkdir()
+
+ # Create .specify directory
+ specify_dir = proj_dir / ".specify"
+ specify_dir.mkdir()
+
+ # Create templates directory with core templates
+ templates_dir = specify_dir / "templates"
+ templates_dir.mkdir()
+
+ # Create core spec-template
+ core_spec = templates_dir / "spec-template.md"
+ core_spec.write_text("# Core Spec Template\n")
+
+ # Create core plan-template
+ core_plan = templates_dir / "plan-template.md"
+ core_plan.write_text("# Core Plan Template\n")
+
+ # Create commands subdirectory
+ commands_dir = templates_dir / "commands"
+ commands_dir.mkdir()
+
+ return proj_dir
+
+
+# ===== PresetManifest Tests =====
+
+
+class TestPresetManifest:
+ """Test PresetManifest validation and parsing."""
+
+ def test_valid_manifest(self, pack_dir):
+ """Test loading a valid manifest."""
+ manifest = PresetManifest(pack_dir / "preset.yml")
+ assert manifest.id == "test-pack"
+ assert manifest.name == "Test Preset"
+ assert manifest.version == "1.0.0"
+ assert manifest.description == "A test preset"
+ assert manifest.author == "Test Author"
+ assert manifest.requires_speckit_version == ">=0.1.0"
+ assert len(manifest.templates) == 1
+ assert manifest.tags == ["testing", "example"]
+
+ def test_missing_manifest(self, temp_dir):
+ """Test that missing manifest raises error."""
+ with pytest.raises(PresetValidationError, match="Manifest not found"):
+ PresetManifest(temp_dir / "nonexistent.yml")
+
+ def test_invalid_yaml(self, temp_dir):
+ """Test that invalid YAML raises error."""
+ bad_file = temp_dir / "bad.yml"
+ bad_file.write_text(": invalid: yaml: {{{")
+ with pytest.raises(PresetValidationError, match="Invalid YAML"):
+ PresetManifest(bad_file)
+
+ def test_missing_schema_version(self, temp_dir, valid_pack_data):
+ """Test missing schema_version field."""
+ del valid_pack_data["schema_version"]
+ manifest_path = temp_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+ with pytest.raises(PresetValidationError, match="Missing required field: schema_version"):
+ PresetManifest(manifest_path)
+
+ def test_wrong_schema_version(self, temp_dir, valid_pack_data):
+ """Test unsupported schema version."""
+ valid_pack_data["schema_version"] = "2.0"
+ manifest_path = temp_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+ with pytest.raises(PresetValidationError, match="Unsupported schema version"):
+ PresetManifest(manifest_path)
+
+ def test_missing_pack_id(self, temp_dir, valid_pack_data):
+ """Test missing preset.id field."""
+ del valid_pack_data["preset"]["id"]
+ manifest_path = temp_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+ with pytest.raises(PresetValidationError, match="Missing preset.id"):
+ PresetManifest(manifest_path)
+
+ def test_invalid_pack_id_format(self, temp_dir, valid_pack_data):
+ """Test invalid pack ID format."""
+ valid_pack_data["preset"]["id"] = "Invalid_ID"
+ manifest_path = temp_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+ with pytest.raises(PresetValidationError, match="Invalid preset ID"):
+ PresetManifest(manifest_path)
+
+ def test_invalid_version(self, temp_dir, valid_pack_data):
+ """Test invalid semantic version."""
+ valid_pack_data["preset"]["version"] = "not-a-version"
+ manifest_path = temp_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+ with pytest.raises(PresetValidationError, match="Invalid version"):
+ PresetManifest(manifest_path)
+
+ def test_missing_speckit_version(self, temp_dir, valid_pack_data):
+ """Test missing requires.speckit_version."""
+ del valid_pack_data["requires"]["speckit_version"]
+ manifest_path = temp_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+ with pytest.raises(PresetValidationError, match="Missing requires.speckit_version"):
+ PresetManifest(manifest_path)
+
+ def test_no_templates_provided(self, temp_dir, valid_pack_data):
+ """Test pack with no templates."""
+ valid_pack_data["provides"]["templates"] = []
+ manifest_path = temp_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+ with pytest.raises(PresetValidationError, match="must provide at least one template"):
+ PresetManifest(manifest_path)
+
+ def test_invalid_template_type(self, temp_dir, valid_pack_data):
+ """Test template with invalid type."""
+ valid_pack_data["provides"]["templates"][0]["type"] = "invalid"
+ manifest_path = temp_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+ with pytest.raises(PresetValidationError, match="Invalid template type"):
+ PresetManifest(manifest_path)
+
+ def test_valid_template_types(self):
+ """Test that all expected template types are valid."""
+ assert "template" in VALID_PRESET_TEMPLATE_TYPES
+ assert "command" in VALID_PRESET_TEMPLATE_TYPES
+ assert "script" in VALID_PRESET_TEMPLATE_TYPES
+
+ def test_template_missing_required_fields(self, temp_dir, valid_pack_data):
+ """Test template missing required fields."""
+ valid_pack_data["provides"]["templates"] = [{"type": "template"}]
+ manifest_path = temp_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+ with pytest.raises(PresetValidationError, match="missing 'type', 'name', or 'file'"):
+ PresetManifest(manifest_path)
+
+ def test_invalid_template_name_format(self, temp_dir, valid_pack_data):
+ """Test template with invalid name format."""
+ valid_pack_data["provides"]["templates"][0]["name"] = "Invalid Name"
+ manifest_path = temp_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+ with pytest.raises(PresetValidationError, match="Invalid template name"):
+ PresetManifest(manifest_path)
+
+ def test_get_hash(self, pack_dir):
+ """Test manifest hash calculation."""
+ manifest = PresetManifest(pack_dir / "preset.yml")
+ hash_val = manifest.get_hash()
+ assert hash_val.startswith("sha256:")
+ assert len(hash_val) > 10
+
+ def test_multiple_templates(self, temp_dir, valid_pack_data):
+ """Test pack with multiple templates of different types."""
+ valid_pack_data["provides"]["templates"] = [
+ {"type": "template", "name": "spec-template", "file": "templates/spec-template.md"},
+ {"type": "template", "name": "plan-template", "file": "templates/plan-template.md"},
+ {"type": "command", "name": "specify", "file": "commands/specify.md"},
+ {"type": "script", "name": "create-new-feature", "file": "scripts/create-new-feature.sh"},
+ ]
+ manifest_path = temp_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+ manifest = PresetManifest(manifest_path)
+ assert len(manifest.templates) == 4
+
+
+# ===== PresetRegistry Tests =====
+
+
+class TestPresetRegistry:
+ """Test PresetRegistry operations."""
+
+ def test_empty_registry(self, temp_dir):
+ """Test empty registry initialization."""
+ packs_dir = temp_dir / "packs"
+ packs_dir.mkdir()
+ registry = PresetRegistry(packs_dir)
+ assert registry.list() == {}
+ assert not registry.is_installed("test-pack")
+
+ def test_add_and_get(self, temp_dir):
+ """Test adding and retrieving a pack."""
+ packs_dir = temp_dir / "packs"
+ packs_dir.mkdir()
+ registry = PresetRegistry(packs_dir)
+
+ registry.add("test-pack", {"version": "1.0.0", "source": "local"})
+ assert registry.is_installed("test-pack")
+
+ metadata = registry.get("test-pack")
+ assert metadata is not None
+ assert metadata["version"] == "1.0.0"
+ assert "installed_at" in metadata
+
+ def test_remove(self, temp_dir):
+ """Test removing a pack."""
+ packs_dir = temp_dir / "packs"
+ packs_dir.mkdir()
+ registry = PresetRegistry(packs_dir)
+
+ registry.add("test-pack", {"version": "1.0.0"})
+ assert registry.is_installed("test-pack")
+
+ registry.remove("test-pack")
+ assert not registry.is_installed("test-pack")
+
+ def test_remove_nonexistent(self, temp_dir):
+ """Test removing a pack that doesn't exist."""
+ packs_dir = temp_dir / "packs"
+ packs_dir.mkdir()
+ registry = PresetRegistry(packs_dir)
+ registry.remove("nonexistent") # Should not raise
+
+ def test_list(self, temp_dir):
+ """Test listing all packs."""
+ packs_dir = temp_dir / "packs"
+ packs_dir.mkdir()
+ registry = PresetRegistry(packs_dir)
+
+ registry.add("pack-a", {"version": "1.0.0"})
+ registry.add("pack-b", {"version": "2.0.0"})
+
+ all_packs = registry.list()
+ assert len(all_packs) == 2
+ assert "pack-a" in all_packs
+ assert "pack-b" in all_packs
+
+ def test_persistence(self, temp_dir):
+ """Test that registry data persists across instances."""
+ packs_dir = temp_dir / "packs"
+ packs_dir.mkdir()
+
+ # Add with first instance
+ registry1 = PresetRegistry(packs_dir)
+ registry1.add("test-pack", {"version": "1.0.0"})
+
+ # Load with second instance
+ registry2 = PresetRegistry(packs_dir)
+ assert registry2.is_installed("test-pack")
+
+ def test_corrupted_registry(self, temp_dir):
+ """Test recovery from corrupted registry file."""
+ packs_dir = temp_dir / "packs"
+ packs_dir.mkdir()
+
+ registry_file = packs_dir / ".registry"
+ registry_file.write_text("not valid json{{{")
+
+ registry = PresetRegistry(packs_dir)
+ assert registry.list() == {}
+
+ def test_get_nonexistent(self, temp_dir):
+ """Test getting a nonexistent pack."""
+ packs_dir = temp_dir / "packs"
+ packs_dir.mkdir()
+ registry = PresetRegistry(packs_dir)
+ assert registry.get("nonexistent") is None
+
+
+# ===== PresetManager Tests =====
+
+
+class TestPresetManager:
+ """Test PresetManager installation and removal."""
+
+ def test_install_from_directory(self, project_dir, pack_dir):
+ """Test installing a preset from a directory."""
+ manager = PresetManager(project_dir)
+ manifest = manager.install_from_directory(pack_dir, "0.1.5")
+
+ assert manifest.id == "test-pack"
+ assert manager.registry.is_installed("test-pack")
+
+ # Verify files are copied
+ installed_dir = project_dir / ".specify" / "presets" / "test-pack"
+ assert installed_dir.exists()
+ assert (installed_dir / "preset.yml").exists()
+ assert (installed_dir / "templates" / "spec-template.md").exists()
+
+ def test_install_already_installed(self, project_dir, pack_dir):
+ """Test installing an already-installed pack raises error."""
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(pack_dir, "0.1.5")
+
+ with pytest.raises(PresetError, match="already installed"):
+ manager.install_from_directory(pack_dir, "0.1.5")
+
+ def test_install_incompatible(self, project_dir, temp_dir, valid_pack_data):
+ """Test installing an incompatible pack raises error."""
+ valid_pack_data["requires"]["speckit_version"] = ">=99.0.0"
+ incompat_dir = temp_dir / "incompat-pack"
+ incompat_dir.mkdir()
+ manifest_path = incompat_dir / "preset.yml"
+ with open(manifest_path, 'w') as f:
+ yaml.dump(valid_pack_data, f)
+ (incompat_dir / "templates").mkdir()
+ (incompat_dir / "templates" / "spec-template.md").write_text("test")
+
+ manager = PresetManager(project_dir)
+ with pytest.raises(PresetCompatibilityError):
+ manager.install_from_directory(incompat_dir, "0.1.5")
+
+ def test_install_from_zip(self, project_dir, pack_dir, temp_dir):
+ """Test installing from a ZIP file."""
+ zip_path = temp_dir / "test-pack.zip"
+ with zipfile.ZipFile(zip_path, 'w') as zf:
+ for file_path in pack_dir.rglob('*'):
+ if file_path.is_file():
+ arcname = file_path.relative_to(pack_dir)
+ zf.write(file_path, arcname)
+
+ manager = PresetManager(project_dir)
+ manifest = manager.install_from_zip(zip_path, "0.1.5")
+ assert manifest.id == "test-pack"
+ assert manager.registry.is_installed("test-pack")
+
+ def test_install_from_zip_nested(self, project_dir, pack_dir, temp_dir):
+ """Test installing from ZIP with nested directory."""
+ zip_path = temp_dir / "test-pack.zip"
+ with zipfile.ZipFile(zip_path, 'w') as zf:
+ for file_path in pack_dir.rglob('*'):
+ if file_path.is_file():
+ arcname = Path("test-pack-v1.0.0") / file_path.relative_to(pack_dir)
+ zf.write(file_path, arcname)
+
+ manager = PresetManager(project_dir)
+ manifest = manager.install_from_zip(zip_path, "0.1.5")
+ assert manifest.id == "test-pack"
+
+ def test_install_from_zip_no_manifest(self, project_dir, temp_dir):
+ """Test installing from ZIP without manifest raises error."""
+ zip_path = temp_dir / "bad.zip"
+ with zipfile.ZipFile(zip_path, 'w') as zf:
+ zf.writestr("readme.txt", "no manifest here")
+
+ manager = PresetManager(project_dir)
+ with pytest.raises(PresetValidationError, match="No preset.yml found"):
+ manager.install_from_zip(zip_path, "0.1.5")
+
+ def test_remove(self, project_dir, pack_dir):
+ """Test removing a preset."""
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(pack_dir, "0.1.5")
+ assert manager.registry.is_installed("test-pack")
+
+ result = manager.remove("test-pack")
+ assert result is True
+ assert not manager.registry.is_installed("test-pack")
+
+ installed_dir = project_dir / ".specify" / "presets" / "test-pack"
+ assert not installed_dir.exists()
+
+ def test_remove_nonexistent(self, project_dir):
+ """Test removing a pack that doesn't exist."""
+ manager = PresetManager(project_dir)
+ result = manager.remove("nonexistent")
+ assert result is False
+
+ def test_list_installed(self, project_dir, pack_dir):
+ """Test listing installed packs."""
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(pack_dir, "0.1.5")
+
+ installed = manager.list_installed()
+ assert len(installed) == 1
+ assert installed[0]["id"] == "test-pack"
+ assert installed[0]["name"] == "Test Preset"
+ assert installed[0]["version"] == "1.0.0"
+ assert installed[0]["template_count"] == 1
+
+ def test_list_installed_empty(self, project_dir):
+ """Test listing when no packs installed."""
+ manager = PresetManager(project_dir)
+ assert manager.list_installed() == []
+
+ def test_get_pack(self, project_dir, pack_dir):
+ """Test getting a specific installed pack."""
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(pack_dir, "0.1.5")
+
+ pack = manager.get_pack("test-pack")
+ assert pack is not None
+ assert pack.id == "test-pack"
+
+ def test_get_pack_not_installed(self, project_dir):
+ """Test getting a non-installed pack returns None."""
+ manager = PresetManager(project_dir)
+ assert manager.get_pack("nonexistent") is None
+
+ def test_check_compatibility_valid(self, pack_dir, temp_dir):
+ """Test compatibility check with valid version."""
+ manager = PresetManager(temp_dir)
+ manifest = PresetManifest(pack_dir / "preset.yml")
+ assert manager.check_compatibility(manifest, "0.1.5") is True
+
+ def test_check_compatibility_invalid(self, pack_dir, temp_dir):
+ """Test compatibility check with invalid specifier."""
+ manager = PresetManager(temp_dir)
+ manifest = PresetManifest(pack_dir / "preset.yml")
+ manifest.data["requires"]["speckit_version"] = "not-a-specifier"
+ with pytest.raises(PresetCompatibilityError, match="Invalid version specifier"):
+ manager.check_compatibility(manifest, "0.1.5")
+
+ def test_install_with_priority(self, project_dir, pack_dir):
+ """Test installing a pack with custom priority."""
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(pack_dir, "0.1.5", priority=5)
+
+ metadata = manager.registry.get("test-pack")
+ assert metadata is not None
+ assert metadata["priority"] == 5
+
+ def test_install_default_priority(self, project_dir, pack_dir):
+ """Test that default priority is 10."""
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(pack_dir, "0.1.5")
+
+ metadata = manager.registry.get("test-pack")
+ assert metadata is not None
+ assert metadata["priority"] == 10
+
+ def test_list_installed_includes_priority(self, project_dir, pack_dir):
+ """Test that list_installed includes priority."""
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(pack_dir, "0.1.5", priority=3)
+
+ installed = manager.list_installed()
+ assert len(installed) == 1
+ assert installed[0]["priority"] == 3
+
+
+class TestRegistryPriority:
+ """Test registry priority sorting."""
+
+ def test_list_by_priority(self, temp_dir):
+ """Test that list_by_priority sorts by priority number."""
+ packs_dir = temp_dir / "packs"
+ packs_dir.mkdir()
+ registry = PresetRegistry(packs_dir)
+
+ registry.add("pack-high", {"version": "1.0.0", "priority": 1})
+ registry.add("pack-low", {"version": "1.0.0", "priority": 20})
+ registry.add("pack-mid", {"version": "1.0.0", "priority": 10})
+
+ sorted_packs = registry.list_by_priority()
+ assert len(sorted_packs) == 3
+ assert sorted_packs[0][0] == "pack-high"
+ assert sorted_packs[1][0] == "pack-mid"
+ assert sorted_packs[2][0] == "pack-low"
+
+ def test_list_by_priority_default(self, temp_dir):
+ """Test that packs without priority default to 10."""
+ packs_dir = temp_dir / "packs"
+ packs_dir.mkdir()
+ registry = PresetRegistry(packs_dir)
+
+ registry.add("pack-a", {"version": "1.0.0"}) # no priority, defaults to 10
+ registry.add("pack-b", {"version": "1.0.0", "priority": 5})
+
+ sorted_packs = registry.list_by_priority()
+ assert sorted_packs[0][0] == "pack-b"
+ assert sorted_packs[1][0] == "pack-a"
+
+
+# ===== PresetResolver Tests =====
+
+
+class TestPresetResolver:
+ """Test PresetResolver priority stack."""
+
+ def test_resolve_core_template(self, project_dir):
+ """Test resolving a core template."""
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve("spec-template")
+ assert result is not None
+ assert result.name == "spec-template.md"
+ assert "Core Spec Template" in result.read_text()
+
+ def test_resolve_nonexistent(self, project_dir):
+ """Test resolving a nonexistent template returns None."""
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve("nonexistent-template")
+ assert result is None
+
+ def test_resolve_higher_priority_pack_wins(self, project_dir, temp_dir, valid_pack_data):
+ """Test that a pack with lower priority number wins over higher number."""
+ manager = PresetManager(project_dir)
+
+ # Create pack A (priority 10 β€” lower precedence)
+ pack_a_dir = temp_dir / "pack-a"
+ pack_a_dir.mkdir()
+ data_a = {**valid_pack_data}
+ data_a["preset"] = {**valid_pack_data["preset"], "id": "pack-a", "name": "Pack A"}
+ with open(pack_a_dir / "preset.yml", 'w') as f:
+ yaml.dump(data_a, f)
+ (pack_a_dir / "templates").mkdir()
+ (pack_a_dir / "templates" / "spec-template.md").write_text("# From Pack A\n")
+
+ # Create pack B (priority 1 β€” higher precedence)
+ pack_b_dir = temp_dir / "pack-b"
+ pack_b_dir.mkdir()
+ data_b = {**valid_pack_data}
+ data_b["preset"] = {**valid_pack_data["preset"], "id": "pack-b", "name": "Pack B"}
+ with open(pack_b_dir / "preset.yml", 'w') as f:
+ yaml.dump(data_b, f)
+ (pack_b_dir / "templates").mkdir()
+ (pack_b_dir / "templates" / "spec-template.md").write_text("# From Pack B\n")
+
+ # Install A first (priority 10), B second (priority 1)
+ manager.install_from_directory(pack_a_dir, "0.1.5", priority=10)
+ manager.install_from_directory(pack_b_dir, "0.1.5", priority=1)
+
+ # Pack B should win because lower priority number
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve("spec-template")
+ assert result is not None
+ assert "From Pack B" in result.read_text()
+
+ def test_resolve_override_takes_priority(self, project_dir):
+ """Test that project overrides take priority over core."""
+ # Create override
+ overrides_dir = project_dir / ".specify" / "templates" / "overrides"
+ overrides_dir.mkdir(parents=True)
+ override = overrides_dir / "spec-template.md"
+ override.write_text("# Override Spec Template\n")
+
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve("spec-template")
+ assert result is not None
+ assert "Override Spec Template" in result.read_text()
+
+ def test_resolve_pack_takes_priority_over_core(self, project_dir, pack_dir):
+ """Test that installed packs take priority over core templates."""
+ # Install the pack
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(pack_dir, "0.1.5")
+
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve("spec-template")
+ assert result is not None
+ assert "Custom Spec Template" in result.read_text()
+
+ def test_resolve_override_takes_priority_over_pack(self, project_dir, pack_dir):
+ """Test that overrides take priority over installed packs."""
+ # Install the pack
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(pack_dir, "0.1.5")
+
+ # Create override
+ overrides_dir = project_dir / ".specify" / "templates" / "overrides"
+ overrides_dir.mkdir(parents=True)
+ override = overrides_dir / "spec-template.md"
+ override.write_text("# Override Spec Template\n")
+
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve("spec-template")
+ assert result is not None
+ assert "Override Spec Template" in result.read_text()
+
+ def test_resolve_extension_provided_templates(self, project_dir):
+ """Test resolving templates provided by extensions."""
+ # Create extension with templates
+ ext_dir = project_dir / ".specify" / "extensions" / "my-ext"
+ ext_templates_dir = ext_dir / "templates"
+ ext_templates_dir.mkdir(parents=True)
+ ext_template = ext_templates_dir / "custom-template.md"
+ ext_template.write_text("# Extension Custom Template\n")
+
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve("custom-template")
+ assert result is not None
+ assert "Extension Custom Template" in result.read_text()
+
+ def test_resolve_pack_over_extension(self, project_dir, pack_dir, temp_dir, valid_pack_data):
+ """Test that pack templates take priority over extension templates."""
+ # Create extension with templates
+ ext_dir = project_dir / ".specify" / "extensions" / "my-ext"
+ ext_templates_dir = ext_dir / "templates"
+ ext_templates_dir.mkdir(parents=True)
+ ext_template = ext_templates_dir / "spec-template.md"
+ ext_template.write_text("# Extension Spec Template\n")
+
+ # Install a pack with the same template
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(pack_dir, "0.1.5")
+
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve("spec-template")
+ assert result is not None
+ # Pack should win over extension
+ assert "Custom Spec Template" in result.read_text()
+
+ def test_resolve_with_source_core(self, project_dir):
+ """Test resolve_with_source for core template."""
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve_with_source("spec-template")
+ assert result is not None
+ assert result["source"] == "core"
+ assert "spec-template.md" in result["path"]
+
+ def test_resolve_with_source_override(self, project_dir):
+ """Test resolve_with_source for override template."""
+ overrides_dir = project_dir / ".specify" / "templates" / "overrides"
+ overrides_dir.mkdir(parents=True)
+ override = overrides_dir / "spec-template.md"
+ override.write_text("# Override\n")
+
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve_with_source("spec-template")
+ assert result is not None
+ assert result["source"] == "project override"
+
+ def test_resolve_with_source_pack(self, project_dir, pack_dir):
+ """Test resolve_with_source for pack template."""
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(pack_dir, "0.1.5")
+
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve_with_source("spec-template")
+ assert result is not None
+ assert "test-pack" in result["source"]
+ assert "v1.0.0" in result["source"]
+
+ def test_resolve_with_source_extension(self, project_dir):
+ """Test resolve_with_source for extension-provided template."""
+ ext_dir = project_dir / ".specify" / "extensions" / "my-ext"
+ ext_templates_dir = ext_dir / "templates"
+ ext_templates_dir.mkdir(parents=True)
+ ext_template = ext_templates_dir / "unique-template.md"
+ ext_template.write_text("# Unique\n")
+
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve_with_source("unique-template")
+ assert result is not None
+ assert result["source"] == "extension:my-ext"
+
+ def test_resolve_with_source_not_found(self, project_dir):
+ """Test resolve_with_source for nonexistent template."""
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve_with_source("nonexistent")
+ assert result is None
+
+ def test_resolve_skips_hidden_extension_dirs(self, project_dir):
+ """Test that hidden directories in extensions are skipped."""
+ ext_dir = project_dir / ".specify" / "extensions" / ".backup"
+ ext_templates_dir = ext_dir / "templates"
+ ext_templates_dir.mkdir(parents=True)
+ ext_template = ext_templates_dir / "hidden-template.md"
+ ext_template.write_text("# Hidden\n")
+
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve("hidden-template")
+ assert result is None
+
+
+# ===== PresetCatalog Tests =====
+
+
+class TestPresetCatalog:
+ """Test template catalog functionality."""
+
+ def test_default_catalog_url(self, project_dir):
+ """Test default catalog URL."""
+ catalog = PresetCatalog(project_dir)
+ assert catalog.DEFAULT_CATALOG_URL.startswith("https://")
+ assert catalog.DEFAULT_CATALOG_URL.endswith("/presets/catalog.json")
+
+ def test_community_catalog_url(self, project_dir):
+ """Test community catalog URL."""
+ catalog = PresetCatalog(project_dir)
+ assert "presets/catalog.community.json" in catalog.COMMUNITY_CATALOG_URL
+
+ def test_cache_validation_no_cache(self, project_dir):
+ """Test cache validation when no cache exists."""
+ catalog = PresetCatalog(project_dir)
+ assert catalog.is_cache_valid() is False
+
+ def test_cache_validation_valid(self, project_dir):
+ """Test cache validation with valid cache."""
+ catalog = PresetCatalog(project_dir)
+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+
+ catalog.cache_file.write_text(json.dumps({
+ "schema_version": "1.0",
+ "presets": {},
+ }))
+ catalog.cache_metadata_file.write_text(json.dumps({
+ "cached_at": datetime.now(timezone.utc).isoformat(),
+ }))
+
+ assert catalog.is_cache_valid() is True
+
+ def test_cache_validation_expired(self, project_dir):
+ """Test cache validation with expired cache."""
+ catalog = PresetCatalog(project_dir)
+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+
+ catalog.cache_file.write_text(json.dumps({
+ "schema_version": "1.0",
+ "presets": {},
+ }))
+ catalog.cache_metadata_file.write_text(json.dumps({
+ "cached_at": "2020-01-01T00:00:00+00:00",
+ }))
+
+ assert catalog.is_cache_valid() is False
+
+ def test_cache_validation_corrupted(self, project_dir):
+ """Test cache validation with corrupted metadata."""
+ catalog = PresetCatalog(project_dir)
+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+
+ catalog.cache_file.write_text("not json")
+ catalog.cache_metadata_file.write_text("not json")
+
+ assert catalog.is_cache_valid() is False
+
+ def test_clear_cache(self, project_dir):
+ """Test clearing the cache."""
+ catalog = PresetCatalog(project_dir)
+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+ catalog.cache_file.write_text("{}")
+ catalog.cache_metadata_file.write_text("{}")
+
+ catalog.clear_cache()
+
+ assert not catalog.cache_file.exists()
+ assert not catalog.cache_metadata_file.exists()
+
+ def test_search_with_cached_data(self, project_dir):
+ """Test search with cached catalog data."""
+ catalog = PresetCatalog(project_dir)
+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+
+ catalog_data = {
+ "schema_version": "1.0",
+ "presets": {
+ "safe-agile": {
+ "name": "SAFe Agile Templates",
+ "description": "SAFe-aligned templates",
+ "author": "agile-community",
+ "version": "1.0.0",
+ "tags": ["safe", "agile"],
+ },
+ "healthcare": {
+ "name": "Healthcare Compliance",
+ "description": "HIPAA-compliant templates",
+ "author": "healthcare-org",
+ "version": "1.0.0",
+ "tags": ["healthcare", "hipaa"],
+ },
+ }
+ }
+
+ catalog.cache_file.write_text(json.dumps(catalog_data))
+ catalog.cache_metadata_file.write_text(json.dumps({
+ "cached_at": datetime.now(timezone.utc).isoformat(),
+ }))
+
+ # Search by query
+ results = catalog.search(query="agile")
+ assert len(results) == 1
+ assert results[0]["id"] == "safe-agile"
+
+ # Search by tag
+ results = catalog.search(tag="hipaa")
+ assert len(results) == 1
+ assert results[0]["id"] == "healthcare"
+
+ # Search by author
+ results = catalog.search(author="agile-community")
+ assert len(results) == 1
+
+ # Search all
+ results = catalog.search()
+ assert len(results) == 2
+
+ def test_get_pack_info(self, project_dir):
+ """Test getting info for a specific pack."""
+ catalog = PresetCatalog(project_dir)
+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+
+ catalog_data = {
+ "schema_version": "1.0",
+ "presets": {
+ "test-pack": {
+ "name": "Test Pack",
+ "version": "1.0.0",
+ },
+ }
+ }
+
+ catalog.cache_file.write_text(json.dumps(catalog_data))
+ catalog.cache_metadata_file.write_text(json.dumps({
+ "cached_at": datetime.now(timezone.utc).isoformat(),
+ }))
+
+ info = catalog.get_pack_info("test-pack")
+ assert info is not None
+ assert info["name"] == "Test Pack"
+ assert info["id"] == "test-pack"
+
+ assert catalog.get_pack_info("nonexistent") is None
+
+ def test_validate_catalog_url_https(self, project_dir):
+ """Test that HTTPS URLs are accepted."""
+ catalog = PresetCatalog(project_dir)
+ catalog._validate_catalog_url("https://example.com/catalog.json")
+
+ def test_validate_catalog_url_http_rejected(self, project_dir):
+ """Test that HTTP URLs are rejected."""
+ catalog = PresetCatalog(project_dir)
+ with pytest.raises(PresetValidationError, match="must use HTTPS"):
+ catalog._validate_catalog_url("http://example.com/catalog.json")
+
+ def test_validate_catalog_url_localhost_http_allowed(self, project_dir):
+ """Test that HTTP is allowed for localhost."""
+ catalog = PresetCatalog(project_dir)
+ catalog._validate_catalog_url("http://localhost:8080/catalog.json")
+ catalog._validate_catalog_url("http://127.0.0.1:8080/catalog.json")
+
+ def test_env_var_catalog_url(self, project_dir, monkeypatch):
+ """Test catalog URL from environment variable."""
+ monkeypatch.setenv("SPECKIT_PRESET_CATALOG_URL", "https://custom.example.com/catalog.json")
+ catalog = PresetCatalog(project_dir)
+ assert catalog.get_catalog_url() == "https://custom.example.com/catalog.json"
+
+
+# ===== Integration Tests =====
+
+
+class TestIntegration:
+ """Integration tests for complete preset workflows."""
+
+ def test_full_install_resolve_remove_cycle(self, project_dir, pack_dir):
+ """Test complete lifecycle: install β†’ resolve β†’ remove."""
+ # Install
+ manager = PresetManager(project_dir)
+ manifest = manager.install_from_directory(pack_dir, "0.1.5")
+ assert manifest.id == "test-pack"
+
+ # Resolve β€” pack template should win over core
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve("spec-template")
+ assert result is not None
+ assert "Custom Spec Template" in result.read_text()
+
+ # Remove
+ manager.remove("test-pack")
+
+ # Resolve β€” should fall back to core
+ result = resolver.resolve("spec-template")
+ assert result is not None
+ assert "Core Spec Template" in result.read_text()
+
+ def test_override_beats_pack_beats_extension_beats_core(self, project_dir, pack_dir):
+ """Test the full priority stack: override > pack > extension > core."""
+ resolver = PresetResolver(project_dir)
+
+ # Core should resolve
+ result = resolver.resolve_with_source("spec-template")
+ assert result["source"] == "core"
+
+ # Add extension template
+ ext_dir = project_dir / ".specify" / "extensions" / "my-ext"
+ ext_templates_dir = ext_dir / "templates"
+ ext_templates_dir.mkdir(parents=True)
+ (ext_templates_dir / "spec-template.md").write_text("# Extension\n")
+
+ result = resolver.resolve_with_source("spec-template")
+ assert result["source"] == "extension:my-ext"
+
+ # Install pack β€” should win over extension
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(pack_dir, "0.1.5")
+
+ result = resolver.resolve_with_source("spec-template")
+ assert "test-pack" in result["source"]
+
+ # Add override β€” should win over pack
+ overrides_dir = project_dir / ".specify" / "templates" / "overrides"
+ overrides_dir.mkdir(parents=True)
+ (overrides_dir / "spec-template.md").write_text("# Override\n")
+
+ result = resolver.resolve_with_source("spec-template")
+ assert result["source"] == "project override"
+
+ def test_install_from_zip_then_resolve(self, project_dir, pack_dir, temp_dir):
+ """Test installing from ZIP and then resolving."""
+ # Create ZIP
+ zip_path = temp_dir / "test-pack.zip"
+ with zipfile.ZipFile(zip_path, 'w') as zf:
+ for file_path in pack_dir.rglob('*'):
+ if file_path.is_file():
+ arcname = file_path.relative_to(pack_dir)
+ zf.write(file_path, arcname)
+
+ # Install
+ manager = PresetManager(project_dir)
+ manager.install_from_zip(zip_path, "0.1.5")
+
+ # Resolve
+ resolver = PresetResolver(project_dir)
+ result = resolver.resolve("spec-template")
+ assert result is not None
+ assert "Custom Spec Template" in result.read_text()
+
+
+# ===== PresetCatalogEntry Tests =====
+
+
+class TestPresetCatalogEntry:
+ """Test PresetCatalogEntry dataclass."""
+
+ def test_create_entry(self):
+ """Test creating a catalog entry."""
+ entry = PresetCatalogEntry(
+ url="https://example.com/catalog.json",
+ name="test",
+ priority=1,
+ install_allowed=True,
+ description="Test catalog",
+ )
+ assert entry.url == "https://example.com/catalog.json"
+ assert entry.name == "test"
+ assert entry.priority == 1
+ assert entry.install_allowed is True
+ assert entry.description == "Test catalog"
+
+ def test_default_description(self):
+ """Test default empty description."""
+ entry = PresetCatalogEntry(
+ url="https://example.com/catalog.json",
+ name="test",
+ priority=1,
+ install_allowed=False,
+ )
+ assert entry.description == ""
+
+
+# ===== Multi-Catalog Tests =====
+
+
+class TestPresetCatalogMultiCatalog:
+ """Test multi-catalog support in PresetCatalog."""
+
+ def test_default_active_catalogs(self, project_dir):
+ """Test that default catalogs are returned when no config exists."""
+ catalog = PresetCatalog(project_dir)
+ active = catalog.get_active_catalogs()
+ assert len(active) == 2
+ assert active[0].name == "default"
+ assert active[0].priority == 1
+ assert active[0].install_allowed is True
+ assert active[1].name == "community"
+ assert active[1].priority == 2
+ assert active[1].install_allowed is False
+
+ def test_env_var_overrides_catalogs(self, project_dir, monkeypatch):
+ """Test that SPECKIT_PRESET_CATALOG_URL env var overrides defaults."""
+ monkeypatch.setenv(
+ "SPECKIT_PRESET_CATALOG_URL",
+ "https://custom.example.com/catalog.json",
+ )
+ catalog = PresetCatalog(project_dir)
+ active = catalog.get_active_catalogs()
+ assert len(active) == 1
+ assert active[0].name == "custom"
+ assert active[0].url == "https://custom.example.com/catalog.json"
+ assert active[0].install_allowed is True
+
+ def test_project_config_overrides_defaults(self, project_dir):
+ """Test that project-level config overrides built-in defaults."""
+ config_path = project_dir / ".specify" / "preset-catalogs.yml"
+ config_path.write_text(yaml.dump({
+ "catalogs": [
+ {
+ "name": "my-catalog",
+ "url": "https://my.example.com/catalog.json",
+ "priority": 1,
+ "install_allowed": True,
+ }
+ ]
+ }))
+
+ catalog = PresetCatalog(project_dir)
+ active = catalog.get_active_catalogs()
+ assert len(active) == 1
+ assert active[0].name == "my-catalog"
+ assert active[0].url == "https://my.example.com/catalog.json"
+
+ def test_load_catalog_config_nonexistent(self, project_dir):
+ """Test loading config from nonexistent file returns None."""
+ catalog = PresetCatalog(project_dir)
+ result = catalog._load_catalog_config(
+ project_dir / ".specify" / "nonexistent.yml"
+ )
+ assert result is None
+
+ def test_load_catalog_config_empty(self, project_dir):
+ """Test loading empty config returns None."""
+ config_path = project_dir / ".specify" / "preset-catalogs.yml"
+ config_path.write_text("")
+
+ catalog = PresetCatalog(project_dir)
+ result = catalog._load_catalog_config(config_path)
+ assert result is None
+
+ def test_load_catalog_config_invalid_yaml(self, project_dir):
+ """Test loading invalid YAML raises error."""
+ config_path = project_dir / ".specify" / "preset-catalogs.yml"
+ config_path.write_text(": invalid: {{{")
+
+ catalog = PresetCatalog(project_dir)
+ with pytest.raises(PresetValidationError, match="Failed to read"):
+ catalog._load_catalog_config(config_path)
+
+ def test_load_catalog_config_not_a_list(self, project_dir):
+ """Test that non-list catalogs key raises error."""
+ config_path = project_dir / ".specify" / "preset-catalogs.yml"
+ config_path.write_text(yaml.dump({"catalogs": "not-a-list"}))
+
+ catalog = PresetCatalog(project_dir)
+ with pytest.raises(PresetValidationError, match="must be a list"):
+ catalog._load_catalog_config(config_path)
+
+ def test_load_catalog_config_invalid_entry(self, project_dir):
+ """Test that non-dict entry raises error."""
+ config_path = project_dir / ".specify" / "preset-catalogs.yml"
+ config_path.write_text(yaml.dump({"catalogs": ["not-a-dict"]}))
+
+ catalog = PresetCatalog(project_dir)
+ with pytest.raises(PresetValidationError, match="expected a mapping"):
+ catalog._load_catalog_config(config_path)
+
+ def test_load_catalog_config_http_url_rejected(self, project_dir):
+ """Test that HTTP URLs are rejected."""
+ config_path = project_dir / ".specify" / "preset-catalogs.yml"
+ config_path.write_text(yaml.dump({
+ "catalogs": [
+ {
+ "name": "bad",
+ "url": "http://insecure.example.com/catalog.json",
+ "priority": 1,
+ }
+ ]
+ }))
+
+ catalog = PresetCatalog(project_dir)
+ with pytest.raises(PresetValidationError, match="must use HTTPS"):
+ catalog._load_catalog_config(config_path)
+
+ def test_load_catalog_config_priority_sorting(self, project_dir):
+ """Test that catalogs are sorted by priority."""
+ config_path = project_dir / ".specify" / "preset-catalogs.yml"
+ config_path.write_text(yaml.dump({
+ "catalogs": [
+ {
+ "name": "low-priority",
+ "url": "https://low.example.com/catalog.json",
+ "priority": 10,
+ "install_allowed": False,
+ },
+ {
+ "name": "high-priority",
+ "url": "https://high.example.com/catalog.json",
+ "priority": 1,
+ "install_allowed": True,
+ },
+ ]
+ }))
+
+ catalog = PresetCatalog(project_dir)
+ entries = catalog._load_catalog_config(config_path)
+ assert entries is not None
+ assert len(entries) == 2
+ assert entries[0].name == "high-priority"
+ assert entries[1].name == "low-priority"
+
+ def test_load_catalog_config_invalid_priority(self, project_dir):
+ """Test that invalid priority raises error."""
+ config_path = project_dir / ".specify" / "preset-catalogs.yml"
+ config_path.write_text(yaml.dump({
+ "catalogs": [
+ {
+ "name": "bad",
+ "url": "https://example.com/catalog.json",
+ "priority": "not-a-number",
+ }
+ ]
+ }))
+
+ catalog = PresetCatalog(project_dir)
+ with pytest.raises(PresetValidationError, match="Invalid priority"):
+ catalog._load_catalog_config(config_path)
+
+ def test_load_catalog_config_install_allowed_string(self, project_dir):
+ """Test that install_allowed accepts string values."""
+ config_path = project_dir / ".specify" / "preset-catalogs.yml"
+ config_path.write_text(yaml.dump({
+ "catalogs": [
+ {
+ "name": "test",
+ "url": "https://example.com/catalog.json",
+ "priority": 1,
+ "install_allowed": "true",
+ }
+ ]
+ }))
+
+ catalog = PresetCatalog(project_dir)
+ entries = catalog._load_catalog_config(config_path)
+ assert entries is not None
+ assert entries[0].install_allowed is True
+
+ def test_get_catalog_url_uses_highest_priority(self, project_dir):
+ """Test that get_catalog_url returns URL of highest priority catalog."""
+ config_path = project_dir / ".specify" / "preset-catalogs.yml"
+ config_path.write_text(yaml.dump({
+ "catalogs": [
+ {
+ "name": "secondary",
+ "url": "https://secondary.example.com/catalog.json",
+ "priority": 5,
+ },
+ {
+ "name": "primary",
+ "url": "https://primary.example.com/catalog.json",
+ "priority": 1,
+ },
+ ]
+ }))
+
+ catalog = PresetCatalog(project_dir)
+ assert catalog.get_catalog_url() == "https://primary.example.com/catalog.json"
+
+ def test_cache_paths_default_url(self, project_dir):
+ """Test cache paths for default catalog URL use legacy locations."""
+ catalog = PresetCatalog(project_dir)
+ cache_file, metadata_file = catalog._get_cache_paths(
+ PresetCatalog.DEFAULT_CATALOG_URL
+ )
+ assert cache_file == catalog.cache_file
+ assert metadata_file == catalog.cache_metadata_file
+
+ def test_cache_paths_custom_url(self, project_dir):
+ """Test cache paths for custom URLs use hash-based files."""
+ catalog = PresetCatalog(project_dir)
+ cache_file, metadata_file = catalog._get_cache_paths(
+ "https://custom.example.com/catalog.json"
+ )
+ assert cache_file != catalog.cache_file
+ assert "catalog-" in cache_file.name
+ assert cache_file.name.endswith(".json")
+
+ def test_url_cache_valid(self, project_dir):
+ """Test URL-specific cache validation."""
+ catalog = PresetCatalog(project_dir)
+ url = "https://custom.example.com/catalog.json"
+ cache_file, metadata_file = catalog._get_cache_paths(url)
+
+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+ cache_file.write_text(json.dumps({"schema_version": "1.0", "presets": {}}))
+ metadata_file.write_text(json.dumps({
+ "cached_at": datetime.now(timezone.utc).isoformat(),
+ }))
+
+ assert catalog._is_url_cache_valid(url) is True
+
+ def test_url_cache_expired(self, project_dir):
+ """Test URL-specific cache expiration."""
+ catalog = PresetCatalog(project_dir)
+ url = "https://custom.example.com/catalog.json"
+ cache_file, metadata_file = catalog._get_cache_paths(url)
+
+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+ cache_file.write_text(json.dumps({"schema_version": "1.0", "presets": {}}))
+ metadata_file.write_text(json.dumps({
+ "cached_at": "2020-01-01T00:00:00+00:00",
+ }))
+
+ assert catalog._is_url_cache_valid(url) is False
+
+
+# ===== Self-Test Preset Tests =====
+
+
+SELF_TEST_PRESET_DIR = Path(__file__).parent.parent / "presets" / "self-test"
+
+CORE_TEMPLATE_NAMES = [
+ "spec-template",
+ "plan-template",
+ "tasks-template",
+ "checklist-template",
+ "constitution-template",
+ "agent-file-template",
+]
+
+
+class TestSelfTestPreset:
+ """Tests using the self-test preset that ships with the repo."""
+
+ def test_self_test_preset_exists(self):
+ """Verify the self-test preset directory and manifest exist."""
+ assert SELF_TEST_PRESET_DIR.exists()
+ assert (SELF_TEST_PRESET_DIR / "preset.yml").exists()
+
+ def test_self_test_manifest_valid(self):
+ """Verify the self-test preset manifest is valid."""
+ manifest = PresetManifest(SELF_TEST_PRESET_DIR / "preset.yml")
+ assert manifest.id == "self-test"
+ assert manifest.name == "Self-Test Preset"
+ assert manifest.version == "1.0.0"
+ assert len(manifest.templates) == 7 # 6 templates + 1 command
+
+ def test_self_test_provides_all_core_templates(self):
+ """Verify the self-test preset provides an override for every core template."""
+ manifest = PresetManifest(SELF_TEST_PRESET_DIR / "preset.yml")
+ provided_names = {t["name"] for t in manifest.templates}
+ for name in CORE_TEMPLATE_NAMES:
+ assert name in provided_names, f"Self-test preset missing template: {name}"
+
+ def test_self_test_template_files_exist(self):
+ """Verify that all declared template files actually exist on disk."""
+ manifest = PresetManifest(SELF_TEST_PRESET_DIR / "preset.yml")
+ for tmpl in manifest.templates:
+ tmpl_path = SELF_TEST_PRESET_DIR / tmpl["file"]
+ assert tmpl_path.exists(), f"Missing template file: {tmpl['file']}"
+
+ def test_self_test_templates_have_marker(self):
+ """Verify each template contains the preset:self-test marker."""
+ for name in CORE_TEMPLATE_NAMES:
+ tmpl_path = SELF_TEST_PRESET_DIR / "templates" / f"{name}.md"
+ content = tmpl_path.read_text()
+ assert "preset:self-test" in content, f"{name}.md missing preset:self-test marker"
+
+ def test_install_self_test_preset(self, project_dir):
+ """Test installing the self-test preset from its directory."""
+ manager = PresetManager(project_dir)
+ manifest = manager.install_from_directory(SELF_TEST_PRESET_DIR, "0.1.5")
+ assert manifest.id == "self-test"
+ assert manager.registry.is_installed("self-test")
+
+ def test_self_test_overrides_all_core_templates(self, project_dir):
+ """Test that installing self-test overrides every core template."""
+ # Set up core templates in the project
+ templates_dir = project_dir / ".specify" / "templates"
+ for name in CORE_TEMPLATE_NAMES:
+ (templates_dir / f"{name}.md").write_text(f"# Core {name}\n")
+
+ # Install self-test preset
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(SELF_TEST_PRESET_DIR, "0.1.5")
+
+ # Every core template should now resolve from the preset
+ resolver = PresetResolver(project_dir)
+ for name in CORE_TEMPLATE_NAMES:
+ result = resolver.resolve(name)
+ assert result is not None, f"{name} did not resolve"
+ content = result.read_text()
+ assert "preset:self-test" in content, (
+ f"{name} resolved but not from self-test preset"
+ )
+
+ def test_self_test_resolve_with_source(self, project_dir):
+ """Test that resolve_with_source attributes templates to self-test."""
+ templates_dir = project_dir / ".specify" / "templates"
+ for name in CORE_TEMPLATE_NAMES:
+ (templates_dir / f"{name}.md").write_text(f"# Core {name}\n")
+
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(SELF_TEST_PRESET_DIR, "0.1.5")
+
+ resolver = PresetResolver(project_dir)
+ for name in CORE_TEMPLATE_NAMES:
+ result = resolver.resolve_with_source(name)
+ assert result is not None, f"{name} did not resolve"
+ assert "self-test" in result["source"], (
+ f"{name} source is '{result['source']}', expected self-test"
+ )
+
+ def test_self_test_removal_restores_core(self, project_dir):
+ """Test that removing self-test falls back to core templates."""
+ templates_dir = project_dir / ".specify" / "templates"
+ for name in CORE_TEMPLATE_NAMES:
+ (templates_dir / f"{name}.md").write_text(f"# Core {name}\n")
+
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(SELF_TEST_PRESET_DIR, "0.1.5")
+ manager.remove("self-test")
+
+ resolver = PresetResolver(project_dir)
+ for name in CORE_TEMPLATE_NAMES:
+ result = resolver.resolve_with_source(name)
+ assert result is not None
+ assert result["source"] == "core"
+
+ def test_self_test_not_in_catalog(self):
+ """Verify the self-test preset is NOT in the catalog (it's local-only)."""
+ catalog_path = Path(__file__).parent.parent / "presets" / "catalog.json"
+ catalog_data = json.loads(catalog_path.read_text())
+ assert "self-test" not in catalog_data["presets"]
+
+ def test_self_test_has_command(self):
+ """Verify the self-test preset includes a command override."""
+ manifest = PresetManifest(SELF_TEST_PRESET_DIR / "preset.yml")
+ commands = [t for t in manifest.templates if t["type"] == "command"]
+ assert len(commands) >= 1
+ assert commands[0]["name"] == "speckit.specify"
+
+ def test_self_test_command_file_exists(self):
+ """Verify the self-test command file exists on disk."""
+ cmd_path = SELF_TEST_PRESET_DIR / "commands" / "speckit.specify.md"
+ assert cmd_path.exists()
+ content = cmd_path.read_text()
+ assert "preset:self-test" in content
+
+ def test_self_test_registers_commands_for_claude(self, project_dir):
+ """Test that installing self-test registers commands in .claude/commands/."""
+ # Create Claude agent directory to simulate Claude being set up
+ claude_dir = project_dir / ".claude" / "commands"
+ claude_dir.mkdir(parents=True)
+
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(SELF_TEST_PRESET_DIR, "0.1.5")
+
+ # Check the command was registered
+ cmd_file = claude_dir / "speckit.specify.md"
+ assert cmd_file.exists(), "Command not registered in .claude/commands/"
+ content = cmd_file.read_text()
+ assert "preset:self-test" in content
+
+ def test_self_test_registers_commands_for_gemini(self, project_dir):
+ """Test that installing self-test registers commands in .gemini/commands/ as TOML."""
+ # Create Gemini agent directory
+ gemini_dir = project_dir / ".gemini" / "commands"
+ gemini_dir.mkdir(parents=True)
+
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(SELF_TEST_PRESET_DIR, "0.1.5")
+
+ # Check the command was registered in TOML format
+ cmd_file = gemini_dir / "speckit.specify.toml"
+ assert cmd_file.exists(), "Command not registered in .gemini/commands/"
+ content = cmd_file.read_text()
+ assert "prompt" in content # TOML format has a prompt field
+ assert "{{args}}" in content # Gemini uses {{args}} placeholder
+
+ def test_self_test_unregisters_commands_on_remove(self, project_dir):
+ """Test that removing self-test cleans up registered commands."""
+ claude_dir = project_dir / ".claude" / "commands"
+ claude_dir.mkdir(parents=True)
+
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(SELF_TEST_PRESET_DIR, "0.1.5")
+
+ cmd_file = claude_dir / "speckit.specify.md"
+ assert cmd_file.exists()
+
+ manager.remove("self-test")
+ assert not cmd_file.exists(), "Command not cleaned up after preset removal"
+
+ def test_self_test_no_commands_without_agent_dirs(self, project_dir):
+ """Test that no commands are registered when no agent dirs exist."""
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(SELF_TEST_PRESET_DIR, "0.1.5")
+
+ metadata = manager.registry.get("self-test")
+ assert metadata["registered_commands"] == {}
+
+ def test_extension_command_skipped_when_extension_missing(self, project_dir, temp_dir):
+ """Test that extension command overrides are skipped if the extension isn't installed."""
+ claude_dir = project_dir / ".claude" / "commands"
+ claude_dir.mkdir(parents=True)
+
+ preset_dir = temp_dir / "ext-override-preset"
+ preset_dir.mkdir()
+ (preset_dir / "commands").mkdir()
+ (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(
+ "---\ndescription: Override fakeext cmd\n---\nOverridden content"
+ )
+ manifest_data = {
+ "schema_version": "1.0",
+ "preset": {
+ "id": "ext-override",
+ "name": "Ext Override",
+ "version": "1.0.0",
+ "description": "Test",
+ },
+ "requires": {"speckit_version": ">=0.1.0"},
+ "provides": {
+ "templates": [
+ {
+ "type": "command",
+ "name": "speckit.fakeext.cmd",
+ "file": "commands/speckit.fakeext.cmd.md",
+ "description": "Override fakeext cmd",
+ }
+ ]
+ },
+ }
+ with open(preset_dir / "preset.yml", "w") as f:
+ yaml.dump(manifest_data, f)
+
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(preset_dir, "0.1.5")
+
+ # Extension not installed β€” command should NOT be registered
+ cmd_file = claude_dir / "speckit.fakeext.cmd.md"
+ assert not cmd_file.exists(), "Command registered for missing extension"
+ metadata = manager.registry.get("ext-override")
+ assert metadata["registered_commands"] == {}
+
+ def test_extension_command_registered_when_extension_present(self, project_dir, temp_dir):
+ """Test that extension command overrides ARE registered when the extension is installed."""
+ claude_dir = project_dir / ".claude" / "commands"
+ claude_dir.mkdir(parents=True)
+ (project_dir / ".specify" / "extensions" / "fakeext").mkdir(parents=True)
+
+ preset_dir = temp_dir / "ext-override-preset2"
+ preset_dir.mkdir()
+ (preset_dir / "commands").mkdir()
+ (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(
+ "---\ndescription: Override fakeext cmd\n---\nOverridden content"
+ )
+ manifest_data = {
+ "schema_version": "1.0",
+ "preset": {
+ "id": "ext-override2",
+ "name": "Ext Override",
+ "version": "1.0.0",
+ "description": "Test",
+ },
+ "requires": {"speckit_version": ">=0.1.0"},
+ "provides": {
+ "templates": [
+ {
+ "type": "command",
+ "name": "speckit.fakeext.cmd",
+ "file": "commands/speckit.fakeext.cmd.md",
+ "description": "Override fakeext cmd",
+ }
+ ]
+ },
+ }
+ with open(preset_dir / "preset.yml", "w") as f:
+ yaml.dump(manifest_data, f)
+
+ manager = PresetManager(project_dir)
+ manager.install_from_directory(preset_dir, "0.1.5")
+
+ cmd_file = claude_dir / "speckit.fakeext.cmd.md"
+ assert cmd_file.exists(), "Command not registered despite extension being present"
+
+
+# ===== Init Options and Skills Tests =====
+
+
+class TestInitOptions:
+ """Tests for save_init_options / load_init_options helpers."""
+
+ def test_save_and_load_round_trip(self, project_dir):
+ from specify_cli import save_init_options, load_init_options
+
+ opts = {"ai": "claude", "ai_skills": True, "here": False}
+ save_init_options(project_dir, opts)
+
+ loaded = load_init_options(project_dir)
+ assert loaded["ai"] == "claude"
+ assert loaded["ai_skills"] is True
+
+ def test_load_returns_empty_when_missing(self, project_dir):
+ from specify_cli import load_init_options
+
+ assert load_init_options(project_dir) == {}
+
+ def test_load_returns_empty_on_invalid_json(self, project_dir):
+ from specify_cli import load_init_options
+
+ opts_file = project_dir / ".specify" / "init-options.json"
+ opts_file.parent.mkdir(parents=True, exist_ok=True)
+ opts_file.write_text("{bad json")
+
+ assert load_init_options(project_dir) == {}
+
+
+class TestPresetSkills:
+ """Tests for preset skill registration and unregistration."""
+
+ def _write_init_options(self, project_dir, ai="claude", ai_skills=True):
+ from specify_cli import save_init_options
+
+ save_init_options(project_dir, {"ai": ai, "ai_skills": ai_skills})
+
+ def _create_skill(self, skills_dir, skill_name, body="original body"):
+ skill_dir = skills_dir / skill_name
+ skill_dir.mkdir(parents=True, exist_ok=True)
+ (skill_dir / "SKILL.md").write_text(
+ f"---\nname: {skill_name}\n---\n\n{body}\n"
+ )
+ return skill_dir
+
+ def test_skill_overridden_on_preset_install(self, project_dir, temp_dir):
+ """When --ai-skills was used, a preset command override should update the skill."""
+ # Simulate --ai-skills having been used: write init-options + create skill
+ self._write_init_options(project_dir, ai="claude")
+ skills_dir = project_dir / ".claude" / "skills"
+ self._create_skill(skills_dir, "speckit-specify")
+
+ # Also create the claude commands dir so commands get registered
+ (project_dir / ".claude" / "commands").mkdir(parents=True, exist_ok=True)
+
+ # Install self-test preset (has a command override for speckit.specify)
+ manager = PresetManager(project_dir)
+ SELF_TEST_DIR = Path(__file__).parent.parent / "presets" / "self-test"
+ manager.install_from_directory(SELF_TEST_DIR, "0.1.5")
+
+ skill_file = skills_dir / "speckit-specify" / "SKILL.md"
+ assert skill_file.exists()
+ content = skill_file.read_text()
+ assert "preset:self-test" in content, "Skill should reference preset source"
+
+ # Verify it was recorded in registry
+ metadata = manager.registry.get("self-test")
+ assert "speckit-specify" in metadata.get("registered_skills", [])
+
+ def test_skill_not_updated_when_ai_skills_disabled(self, project_dir, temp_dir):
+ """When --ai-skills was NOT used, preset install should not touch skills."""
+ self._write_init_options(project_dir, ai="claude", ai_skills=False)
+ skills_dir = project_dir / ".claude" / "skills"
+ self._create_skill(skills_dir, "speckit-specify", body="untouched")
+
+ (project_dir / ".claude" / "commands").mkdir(parents=True, exist_ok=True)
+
+ manager = PresetManager(project_dir)
+ SELF_TEST_DIR = Path(__file__).parent.parent / "presets" / "self-test"
+ manager.install_from_directory(SELF_TEST_DIR, "0.1.5")
+
+ skill_file = skills_dir / "speckit-specify" / "SKILL.md"
+ content = skill_file.read_text()
+ assert "untouched" in content, "Skill should not be modified when ai_skills=False"
+
+ def test_skill_not_updated_without_init_options(self, project_dir, temp_dir):
+ """When no init-options.json exists, preset install should not touch skills."""
+ skills_dir = project_dir / ".claude" / "skills"
+ self._create_skill(skills_dir, "speckit-specify", body="untouched")
+
+ (project_dir / ".claude" / "commands").mkdir(parents=True, exist_ok=True)
+
+ manager = PresetManager(project_dir)
+ SELF_TEST_DIR = Path(__file__).parent.parent / "presets" / "self-test"
+ manager.install_from_directory(SELF_TEST_DIR, "0.1.5")
+
+ skill_file = skills_dir / "speckit-specify" / "SKILL.md"
+ content = skill_file.read_text()
+ assert "untouched" in content
+
+ def test_skill_restored_on_preset_remove(self, project_dir, temp_dir):
+ """When a preset is removed, skills should be restored from core templates."""
+ self._write_init_options(project_dir, ai="claude")
+ skills_dir = project_dir / ".claude" / "skills"
+ self._create_skill(skills_dir, "speckit-specify")
+
+ (project_dir / ".claude" / "commands").mkdir(parents=True, exist_ok=True)
+
+ # Set up core command template in the project so restoration works
+ core_cmds = project_dir / ".specify" / "templates" / "commands"
+ core_cmds.mkdir(parents=True, exist_ok=True)
+ (core_cmds / "specify.md").write_text("---\ndescription: Core specify command\n---\n\nCore specify body\n")
+
+ manager = PresetManager(project_dir)
+ SELF_TEST_DIR = Path(__file__).parent.parent / "presets" / "self-test"
+ manager.install_from_directory(SELF_TEST_DIR, "0.1.5")
+
+ # Verify preset content is in the skill
+ skill_file = skills_dir / "speckit-specify" / "SKILL.md"
+ assert "preset:self-test" in skill_file.read_text()
+
+ # Remove the preset
+ manager.remove("self-test")
+
+ # Skill should be restored (core specify.md template exists)
+ assert skill_file.exists(), "Skill should still exist after preset removal"
+ content = skill_file.read_text()
+ assert "preset:self-test" not in content, "Preset content should be gone"
+ assert "templates/commands/specify.md" in content, "Should reference core template"
+
+ def test_no_skills_registered_when_no_skill_dir_exists(self, project_dir, temp_dir):
+ """Skills should not be created when no existing skill dir is found."""
+ self._write_init_options(project_dir, ai="claude")
+ # Don't create skills dir β€” simulate --ai-skills never created them
+
+ (project_dir / ".claude" / "commands").mkdir(parents=True, exist_ok=True)
+
+ manager = PresetManager(project_dir)
+ SELF_TEST_DIR = Path(__file__).parent.parent / "presets" / "self-test"
+ manager.install_from_directory(SELF_TEST_DIR, "0.1.5")
+
+ metadata = manager.registry.get("self-test")
+ assert metadata.get("registered_skills", []) == []