π« 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.mdindex 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 SupportThis 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.mdindex 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### Changeddiff --git a/presets/ARCHITECTURE.md b/presets/ARCHITECTURE.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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++MITdiff --git a/presets/scaffold/commands/speckit.myext.myextcmd.md b/presets/scaffold/commands/speckit.myext.myextcmd.mdnew file mode 100644index 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.mdnew file mode 100644index 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.ymlnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 2diff --git a/presets/self-test/commands/speckit.specify.md b/presets/self-test/commands/speckit.specify.mdnew file mode 100644index 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.ymlnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 updateddiff --git a/presets/self-test/templates/constitution-template.md b/presets/self-test/templates/constitution-template.mdnew file mode 100644index 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 2diff --git a/presets/self-test/templates/plan-template.md b/presets/self-test/templates/plan-template.mdnew file mode 100644index 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 1diff --git a/presets/self-test/templates/spec-template.md b/presets/self-test/templates/spec-template.mdnew file mode 100644index 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 2diff --git a/presets/self-test/templates/tasks-template.md b/presets/self-test/templates/tasks-template.mdnew file mode 100644index 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.shindex 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.shindex 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; thenREPO_ROOT=$(git rev-parse --show-toplevel)@@ -307,9 +308,9 @@ fiFEATURE_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 shellprintf '# To persist: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME" >&2diff --git a/scripts/bash/setup-plan.sh b/scripts/bash/setup-plan.shindex 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 1mkdir -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" ]]; thencp "$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 existtouch "$IMPL_PLAN"fidiff --git a/scripts/powershell/common.ps1 b/scripts/powershell/common.ps1index 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.ps1index 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>$nullif ($LASTEXITCODE -eq 0) {@@ -276,9 +279,9 @@ if ($hasGit) {$featureDir = Join-Path $specsDir $branchNameNew-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-Nulldiff --git a/scripts/powershell/setup-plan.ps1 b/scripts/powershell/setup-plan.ps1index 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_GINew-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 -ForceWrite-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 existNew-Item -ItemType File -Path $paths.IMPL_PLAN -Force | Out-Null}diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.pyindex e7781b2b5..a45535aee 100644--- a/src/specify_cli/__init__.py+++ b/src/specify_cli/__init__.py@@ -34,7 +34,7 @@ import shleximport jsonimport yamlfrom pathlib import Path-from typing import Optional, Tuple+from typing import Any, Optional, Tupleimport typerimport 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/ patternAGENT_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 skillsspecify init --here --ai gemini --ai-skillsspecify 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.pynew file mode 100644index 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.pyindex 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 agentsif 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)@staticmethoddef 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 compatibilitycontext_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_linesdef 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.pynew file mode 100644index 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.pynew file mode 100644index 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", []) == []