mirror of https://github.com/github/spec-kit.git synced 2026-03-20 20:33:08 +00:00

Files

Vianca M. 7d9361c716 docs: update publishing guide with Category and Effect columns (#1913 )

* docs: update publishing guide with Category and Effect columns

The README table now has Category and Effect columns (added in #1897),
but the publishing guide template still showed the old 3-column format.
Update to match so extension authors know to include both fields.

Made-with: Cursor

* docs: copilot comments

2026-03-20 13:45:25 -05:00

15 KiB

Raw Blame History

Extension Publishing Guide

This guide explains how to publish your extension to the Spec Kit extension catalog, making it discoverable by specify extension search.

Prerequisites
Prepare Your Extension
Submit to Catalog
Verification Process
Release Workflow
Best Practices

Prerequisites

Before publishing an extension, ensure you have:

Valid Extension: A working extension with a valid extension.yml manifest
Git Repository: Extension hosted on GitHub (or other public git hosting)
Documentation: README.md with installation and usage instructions
License: Open source license file (MIT, Apache 2.0, etc.)
Versioning: Semantic versioning (e.g., 1.0.0)
Testing: Extension tested on real projects

Prepare Your Extension

1. Extension Structure

Ensure your extension follows the standard structure:

your-extension/
├── extension.yml              # Required: Extension manifest
├── README.md                  # Required: Documentation
├── LICENSE                    # Required: License file
├── CHANGELOG.md               # Recommended: Version history
├── .gitignore                 # Recommended: Git ignore rules
│
├── commands/                  # Extension commands
│   ├── command1.md
│   └── command2.md
│
├── config-template.yml        # Config template (if needed)
│
└── docs/                      # Additional documentation
    ├── usage.md
    └── examples/

2. extension.yml Validation

Verify your manifest is valid:

schema_version: "1.0"

extension:
  id: "your-extension"           # Unique lowercase-hyphenated ID
  name: "Your Extension 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-your-extension"
  license: "MIT"
  homepage: "https://github.com/your-org/spec-kit-your-extension"

requires:
  speckit_version: ">=0.1.0"    # Required spec-kit version

provides:
  commands:                       # List all commands
    - name: "speckit.your-extension.command"
      file: "commands/command.md"
      description: "Command description"

tags:                             # 2-5 relevant tags
  - "category"
  - "tool-name"

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 100 characters)
✅ repository URL is valid and public
✅ All command files exist in the extension directory
✅ Tags are lowercase and descriptive

3. Create GitHub Release

Create a GitHub release for your extension version:

# Tag the release
git tag v1.0.0
git push origin v1.0.0

# Create release on GitHub
# Go to: https://github.com/your-org/spec-kit-your-extension/releases/new
# - Tag: v1.0.0
# - Title: v1.0.0 - Release Name
# - Description: Changelog/release notes

The release archive URL will be:

https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip

4. Test Installation

Test that users can install from your release:

# Test dev installation
specify extension add --dev /path/to/your-extension

# Test from GitHub archive
specify extension add --from https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip

Submit to Catalog

Understanding the Catalogs

Spec Kit uses a dual-catalog system. For details about how catalogs work, see the main Extensions README.

For extension publishing: All community extensions should be added to catalog.community.json. Users browse this catalog and copy extensions they trust into their own catalog.json.

1. Fork the spec-kit Repository

# Fork on GitHub
# https://github.com/github/spec-kit/fork

# Clone your fork
git clone https://github.com/YOUR-USERNAME/spec-kit.git
cd spec-kit

2. Add Extension to Community Catalog

Edit extensions/catalog.community.json and add your extension:

{
  "schema_version": "1.0",
  "updated_at": "2026-01-28T15:54:00Z",
  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
  "extensions": {
    "your-extension": {
      "name": "Your Extension Name",
      "id": "your-extension",
      "description": "Brief description of your extension",
      "author": "Your Name",
      "version": "1.0.0",
      "download_url": "https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip",
      "repository": "https://github.com/your-org/spec-kit-your-extension",
      "homepage": "https://github.com/your-org/spec-kit-your-extension",
      "documentation": "https://github.com/your-org/spec-kit-your-extension/blob/main/docs/",
      "changelog": "https://github.com/your-org/spec-kit-your-extension/blob/main/CHANGELOG.md",
      "license": "MIT",
      "requires": {
        "speckit_version": ">=0.1.0",
        "tools": [
          {
            "name": "required-mcp-tool",
            "version": ">=1.0.0",
            "required": true
          }
        ]
      },
      "provides": {
        "commands": 3,
        "hooks": 1
      },
      "tags": [
        "category",
        "tool-name",
        "feature"
      ],
      "verified": false,
      "downloads": 0,
      "stars": 0,
      "created_at": "2026-01-28T00:00:00Z",
      "updated_at": "2026-01-28T00:00:00Z"
    }
  }
}

Important:

Set verified: false (maintainers will verify)
Set downloads: 0 and stars: 0 (auto-updated later)
Use current timestamp for created_at and updated_at
Update the top-level updated_at to current time

3. Update Extensions README

Add your extension to the Available Extensions table in extensions/README.md:

| Your Extension Name | Brief description of what it does | `<category>` | <effect> | [repo-name](https://github.com/your-org/spec-kit-your-extension) |

(Table) Category — pick the one that best fits your extension:

docs — reads, validates, or generates spec artifacts
code — reviews, validates, or modifies source code
process — orchestrates workflow across phases
integration — syncs with external platforms
visibility — reports on project health or progress

Effect — choose one:

Read-only — produces reports without modifying files
Read+Write — modifies files, creates artifacts, or updates specs

Insert your extension in alphabetical order in the table.

4. Submit Pull Request

# Create a branch
git checkout -b add-your-extension

# Commit your changes
git add extensions/catalog.community.json extensions/README.md
git commit -m "Add your-extension to community catalog

- Extension ID: your-extension
- Version: 1.0.0
- Author: Your Name
- Description: Brief description
"

# Push to your fork
git push origin add-your-extension

# Create Pull Request on GitHub
# https://github.com/github/spec-kit/compare

Pull Request Template:

## Extension Submission

**Extension Name**: Your Extension Name
**Extension ID**: your-extension
**Version**: 1.0.0
**Author**: Your Name
**Repository**: https://github.com/your-org/spec-kit-your-extension

### Description
Brief description of what your extension does.

### Checklist
- [x] Valid extension.yml manifest
- [x] README.md with installation and usage docs
- [x] LICENSE file included
- [x] GitHub release created (v1.0.0)
- [x] Extension tested on real project
- [x] All commands working
- [x] No security vulnerabilities
- [x] Added to extensions/catalog.community.json
- [x] Added to extensions/README.md Available Extensions table

### Testing
Tested on:
- macOS 13.0+ with spec-kit 0.1.0
- Project: [Your test project]

### Additional Notes
Any additional context or notes for reviewers.

Verification Process

What Happens After Submission

Automated Checks (if available):
- Manifest validation
- Download URL accessibility
- Repository existence
- License file presence
Manual Review:
- Code quality review
- Security audit
- Functionality testing
- Documentation review
Verification:
- If approved, verified: true is set
- Extension appears in specify extension search --verified

Verification Criteria

To be verified, your extension must:

✅ Functionality:

Works as described in documentation
All commands execute without errors
No breaking changes to user workflows

✅ Security:

No known vulnerabilities
No malicious code
Safe handling of user data
Proper validation of inputs

✅ Code Quality:

Clean, readable code
Follows extension best practices
Proper error handling
Helpful error messages

✅ Documentation:

Clear installation instructions
Usage examples
Troubleshooting section
Accurate description

✅ Maintenance:

Active repository
Responsive to issues
Regular updates
Semantic versioning followed

Typical Review Timeline

Automated checks: Immediate (if implemented)
Manual review: 3-7 business days
Verification: After successful review

Release Workflow

Publishing New Versions

When releasing a new version:

Update version in extension.yml:

extension:
  version: "1.1.0"  # Updated version

Update CHANGELOG.md:

## [1.1.0] - 2026-02-15

### Added
- New feature X

### Fixed
- Bug fix Y

Create GitHub release:

git tag v1.1.0
git push origin v1.1.0
# Create release on GitHub

Update catalog:

# Fork spec-kit repo (or update existing fork)
cd spec-kit

# Update extensions/catalog.json
jq '.extensions["your-extension"].version = "1.1.0"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json
jq '.extensions["your-extension"].download_url = "https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.1.0.zip"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json
jq '.extensions["your-extension"].updated_at = "2026-02-15T00:00:00Z"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json
jq '.updated_at = "2026-02-15T00:00:00Z"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json

# Submit PR
git checkout -b update-your-extension-v1.1.0
git add extensions/catalog.json
git commit -m "Update your-extension to v1.1.0"
git push origin update-your-extension-v1.1.0

Submit update PR with changelog in description

Best Practices

Extension Design

Single Responsibility: Each extension should focus on one tool/integration
Clear Naming: Use descriptive, unambiguous names
Minimal Dependencies: Avoid unnecessary dependencies
Backward Compatibility: Follow semantic versioning strictly

Documentation

README.md Structure:
- Overview and features
- Installation instructions
- Configuration guide
- Usage examples
- Troubleshooting
- Contributing guidelines
Command Documentation:
- Clear description
- Prerequisites listed
- Step-by-step instructions
- Error handling guidance
- Examples
Configuration:
- Provide template file
- Document all options
- Include examples
- Explain defaults

Security

Input Validation: Validate all user inputs
No Hardcoded Secrets: Never include credentials
Safe Dependencies: Only use trusted dependencies
Audit Regularly: Check for vulnerabilities

Maintenance

Respond to Issues: Address issues within 1-2 weeks
Regular Updates: Keep dependencies updated
Changelog: Maintain detailed changelog
Deprecation: Give advance notice for breaking changes

Community

License: Use permissive open-source license (MIT, Apache 2.0)
Contributing: Welcome contributions
Code of Conduct: Be respectful and inclusive
Support: Provide ways to get help (issues, discussions, email)

FAQ

Q: Can I publish private/proprietary extensions?

A: The main catalog is for public extensions only. For private extensions:

Host your own catalog.json file
Users add your catalog: specify extension add-catalog https://your-domain.com/catalog.json
Not yet implemented - coming in Phase 4

Q: How long does verification take?

A: Typically 3-7 business days for initial review. Updates to verified extensions are usually faster.

Q: What if my extension is rejected?

A: You'll receive feedback on what needs to be fixed. Make the changes and resubmit.

Q: Can I update my extension anytime?

A: Yes, submit a PR to update the catalog with your new version. Verified status may be re-evaluated for major changes.

Q: Do I need to be verified to be in the catalog?

A: No, unverified extensions are still searchable. Verification just adds trust and visibility.

Q: Can extensions have paid features?

A: Extensions should be free and open-source. Commercial support/services are allowed, but core functionality must be free.

Support

Catalog Issues: https://github.com/statsperform/spec-kit/issues
Extension Template: https://github.com/statsperform/spec-kit-extension-template (coming soon)
Development Guide: See EXTENSION-DEVELOPMENT-GUIDE.md
Community: Discussions and Q&A

Appendix: Catalog Schema

Complete Catalog Entry Schema

{
  "name": "string (required)",
  "id": "string (required, unique)",
  "description": "string (required, <200 chars)",
  "author": "string (required)",
  "version": "string (required, semver)",
  "download_url": "string (required, valid URL)",
  "repository": "string (required, valid URL)",
  "homepage": "string (optional, valid URL)",
  "documentation": "string (optional, valid URL)",
  "changelog": "string (optional, valid URL)",
  "license": "string (required)",
  "requires": {
    "speckit_version": "string (required, version specifier)",
    "tools": [
      {
        "name": "string (required)",
        "version": "string (optional, version specifier)",
        "required": "boolean (default: false)"
      }
    ]
  },
  "provides": {
    "commands": "integer (optional)",
    "hooks": "integer (optional)"
  },
  "tags": ["array of strings (2-10 tags)"],
  "verified": "boolean (default: false)",
  "downloads": "integer (auto-updated)",
  "stars": "integer (auto-updated)",
  "created_at": "string (ISO 8601 datetime)",
  "updated_at": "string (ISO 8601 datetime)"
}

Valid Tags

Recommended tag categories:

Integration: jira, linear, github, gitlab, azure-devops
Category: issue-tracking, vcs, ci-cd, documentation, testing
Platform: atlassian, microsoft, google
Feature: automation, reporting, deployment, monitoring

Use 2-5 tags that best describe your extension.

Last Updated: 2026-01-28 Catalog Format Version: 1.0

15 KiB Raw Blame History