mirror of
https://github.com/github/spec-kit.git
synced 2026-03-19 11:53:08 +00:00
feat(presets): pluggable preset system with template/command overrides, catalog, and resolver
- Rename 'template packs' to 'presets' to avoid naming collision with core templates - PresetManifest, PresetRegistry, PresetManager, PresetCatalog, PresetResolver in presets.py - Extract CommandRegistrar to agents.py as shared infrastructure - CLI: specify preset list/add/remove/search/resolve/info - CLI: specify preset catalog list/add/remove - --preset option on specify init - Priority-based preset stacking (--priority, lower = higher precedence) - Command overrides registered into all detected agent directories (17+ agents) - Extension command safety: skip registration if target extension not installed - Multi-catalog support: env var, project config, user config, built-in defaults - resolve_template() / Resolve-Template in bash/PowerShell scripts - Self-test preset: overrides all 6 core templates + 1 command - Scaffold with 4 examples: core/extension template and command overrides - Preset catalog (catalog.json, catalog.community.json) - Documentation: README.md, ARCHITECTURE.md, PUBLISHING.md - 110 preset tests, 253 total tests passing
This commit is contained in:
Manfred Riem
295
presets/PUBLISHING.md
Normal file
295
presets/PUBLISHING.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user