mirror of https://github.com/github/spec-kit.git synced 2026-03-17 02:43:08 +00:00

Files

Santosh Bhavani 525cdc17ec Fix version command in documentation (#1685 )

Co-authored-by: Santosh Bhavani <sb@mac-mini-i7.local>

2026-02-25 08:20:18 -06:00

20 KiB

Raw Blame History

Extension User Guide

Complete guide for using Spec Kit extensions to enhance your workflow.

Introduction
Getting Started
Finding Extensions
Installing Extensions
Using Extensions
Managing Extensions
Configuration
Troubleshooting
Best Practices

Introduction

What are Extensions?

Extensions are modular packages that add new commands and functionality to Spec Kit without bloating the core framework. They allow you to:

Integrate with external tools (Jira, Linear, GitHub, etc.)
Automate repetitive tasks with hooks
Customize workflows for your team
Share solutions across projects

Why Use Extensions?

Clean Core: Keeps spec-kit lightweight and focused
Optional Features: Only install what you need
Community Driven: Anyone can create and share extensions
Version Controlled: Extensions are versioned independently

Getting Started

Prerequisites

Spec Kit version 0.1.0 or higher
A spec-kit project (directory with .specify/ folder)

Check Your Version

specify version
# Should show 0.1.0 or higher

First Extension

Let's install the Jira extension as an example:

# 1. Search for the extension
specify extension search jira

# 2. Get detailed information
specify extension info jira

# 3. Install it
specify extension add jira

# 4. Configure it
vim .specify/extensions/jira/jira-config.yml

# 5. Use it
# (Commands are now available in Claude Code)
/speckit.jira.specstoissues

Finding Extensions

Browse All Extensions

specify extension search

Shows all available extensions in the catalog.

Search by Keyword

# Search for "jira"
specify extension search jira

# Search for "issue tracking"
specify extension search issue

Filter by Tag

# Find all issue-tracking extensions
specify extension search --tag issue-tracking

# Find all Atlassian tools
specify extension search --tag atlassian

Filter by Author

# Extensions by Stats Perform
specify extension search --author "Stats Perform"

Show Verified Only

# Only show verified extensions
specify extension search --verified

Get Extension Details

# Detailed information
specify extension info jira

Shows:

Description
Requirements
Commands provided
Hooks available
Links (documentation, repository, changelog)
Installation status

Installing Extensions

Install from Catalog

# By name (from catalog)
specify extension add jira

This will:

Download the extension from GitHub
Validate the manifest
Check compatibility with your spec-kit version
Install to .specify/extensions/jira/
Register commands with your AI agent
Create config template

Install from URL

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

Install from Local Directory (Development)

# For testing or development
specify extension add --dev /path/to/extension

Installation Output

✓ Extension installed successfully!

Jira Integration (v1.0.0)
  Create Jira Epics, Stories, and Issues from spec-kit artifacts

Provided commands:
  • speckit.jira.specstoissues - Create Jira hierarchy from spec and tasks
  • speckit.jira.discover-fields - Discover Jira custom fields for configuration
  • speckit.jira.sync-status - Sync task completion status to Jira

⚠  Configuration may be required
   Check: .specify/extensions/jira/

Using Extensions

Using Extension Commands

Extensions add commands that appear in your AI agent (Claude Code):

# In Claude Code
> /speckit.jira.specstoissues

# Or use short alias (if provided)
> /speckit.specstoissues

Extension Configuration

Most extensions require configuration:

# 1. Find the config file
ls .specify/extensions/jira/

# 2. Copy template to config
cp .specify/extensions/jira/jira-config.template.yml \
   .specify/extensions/jira/jira-config.yml

# 3. Edit configuration
vim .specify/extensions/jira/jira-config.yml

# 4. Use the extension
# (Commands will now work with your config)

Extension Hooks

Some extensions provide hooks that execute after core commands:

Example: Jira extension hooks into /speckit.tasks

# Run core command
> /speckit.tasks

# Output includes:
## Extension Hooks

**Optional Hook**: jira
Command: `/speckit.jira.specstoissues`
Description: Automatically create Jira hierarchy after task generation

Prompt: Create Jira issues from tasks?
To execute: `/speckit.jira.specstoissues`

You can then choose to run the hook or skip it.

Managing Extensions

List Installed Extensions

specify extension list

Output:

Installed Extensions:

  ✓ Jira Integration (v1.0.0)
     Create Jira Epics, Stories, and Issues from spec-kit artifacts
     Commands: 3 | Hooks: 1 | Status: Enabled

Update Extensions

# Check for updates (all extensions)
specify extension update

# Update specific extension
specify extension update jira

Output:

🔄 Checking for updates...

Updates available:

  • jira: 1.0.0 → 1.1.0

Update these extensions? [y/N]:

Disable Extension Temporarily

# Disable without removing
specify extension disable jira

✓ Extension 'jira' disabled

Commands will no longer be available. Hooks will not execute.
To re-enable: specify extension enable jira

Re-enable Extension

specify extension enable jira

✓ Extension 'jira' enabled

Remove Extension

# Remove extension (with confirmation)
specify extension remove jira

# Keep configuration when removing
specify extension remove jira --keep-config

# Force removal (no confirmation)
specify extension remove jira --force

Configuration

Configuration Files

Extensions can have multiple configuration files:

.specify/extensions/jira/
├── jira-config.yml           # Main config (version controlled)
├── jira-config.local.yml     # Local overrides (gitignored)
└── jira-config.template.yml  # Template (reference)

Configuration Layers

Configuration is merged in this order (highest priority last):

Extension defaults (from extension.yml)
Project config (jira-config.yml)
Local overrides (jira-config.local.yml)
Environment variables (SPECKIT_JIRA_*)

Example: Jira Configuration

Project config (.specify/extensions/jira/jira-config.yml):

project:
  key: "MSATS"

defaults:
  epic:
    labels: ["spec-driven"]

Local override (.specify/extensions/jira/jira-config.local.yml):

project:
  key: "MYTEST"  # Override for local development

Environment variable:

export SPECKIT_JIRA_PROJECT_KEY="DEVTEST"

Final resolved config uses DEVTEST from environment variable.

Project-Wide Extension Settings

File: .specify/extensions.yml

# Extensions installed in this project
installed:
  - jira
  - linear

# Global settings
settings:
  auto_execute_hooks: true

# Hook configuration
hooks:
  after_tasks:
    - extension: jira
      command: speckit.jira.specstoissues
      enabled: true
      optional: true
      prompt: "Create Jira issues from tasks?"

Core Environment Variables

In addition to extension-specific environment variables (SPECKIT_{EXT_ID}_*), spec-kit supports core environment variables:

Variable	Description	Default
`SPECKIT_CATALOG_URL`	Override the extension catalog URL	GitHub-hosted catalog
`GH_TOKEN` / `GITHUB_TOKEN`	GitHub API token for downloads	None

Example: Using a custom catalog for testing

# Point to a local or alternative catalog
export SPECKIT_CATALOG_URL="http://localhost:8000/catalog.json"

# Or use a staging catalog
export SPECKIT_CATALOG_URL="https://example.com/staging/catalog.json"

Organization Catalog Customization

Why the Default Catalog is Empty

The default spec-kit catalog ships empty by design. This allows organizations to:

Control available extensions - Curate which extensions your team can install
Host private extensions - Internal tools that shouldn't be public
Customize for compliance - Meet security/audit requirements
Support air-gapped environments - Work without internet access

Setting Up a Custom Catalog

1. Create Your Catalog File

Create a catalog.json file with your extensions:

{
  "schema_version": "1.0",
  "updated_at": "2026-02-03T00:00:00Z",
  "catalog_url": "https://your-org.com/spec-kit/catalog.json",
  "extensions": {
    "jira": {
      "name": "Jira Integration",
      "id": "jira",
      "description": "Create Jira issues from spec-kit artifacts",
      "author": "Your Organization",
      "version": "2.1.0",
      "download_url": "https://github.com/your-org/spec-kit-jira/archive/refs/tags/v2.1.0.zip",
      "repository": "https://github.com/your-org/spec-kit-jira",
      "license": "MIT",
      "requires": {
        "speckit_version": ">=0.1.0",
        "tools": [
          {"name": "atlassian-mcp-server", "required": true}
        ]
      },
      "provides": {
        "commands": 3,
        "hooks": 1
      },
      "tags": ["jira", "atlassian", "issue-tracking"],
      "verified": true
    },
    "internal-tool": {
      "name": "Internal Tool Integration",
      "id": "internal-tool",
      "description": "Connect to internal company systems",
      "author": "Your Organization",
      "version": "1.0.0",
      "download_url": "https://internal.your-org.com/extensions/internal-tool-1.0.0.zip",
      "repository": "https://github.internal.your-org.com/spec-kit-internal",
      "license": "Proprietary",
      "requires": {
        "speckit_version": ">=0.1.0"
      },
      "provides": {
        "commands": 2
      },
      "tags": ["internal", "proprietary"],
      "verified": true
    }
  }
}

2. Host the Catalog

Options for hosting your catalog:

Method	URL Example	Use Case
GitHub Pages	`https://your-org.github.io/spec-kit-catalog/catalog.json`	Public or org-visible
Internal web server	`https://internal.company.com/spec-kit/catalog.json`	Corporate network
S3/Cloud storage	`https://s3.amazonaws.com/your-bucket/catalog.json`	Cloud-hosted teams
Local file server	`http://localhost:8000/catalog.json`	Development/testing

Security requirement: URLs must use HTTPS (except localhost for testing).

3. Configure Your Environment

Option A: Environment variable (recommended for CI/CD)

# In ~/.bashrc, ~/.zshrc, or CI pipeline
export SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json"

Option B: Per-project configuration

Create .env or set in your shell before running spec-kit commands:

SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json" specify extension search

4. Verify Configuration

# Search should now show your catalog's extensions
specify extension search

# Install from your catalog
specify extension add jira

Catalog JSON Schema

Required fields for each extension entry:

Field	Type	Required	Description
`name`	string	Yes	Human-readable name
`id`	string	Yes	Unique identifier (lowercase, hyphens)
`version`	string	Yes	Semantic version (X.Y.Z)
`download_url`	string	Yes	URL to ZIP archive
`repository`	string	Yes	Source code URL
`description`	string	No	Brief description
`author`	string	No	Author/organization
`license`	string	No	SPDX license identifier
`requires.speckit_version`	string	No	Version constraint
`requires.tools`	array	No	Required external tools
`provides.commands`	number	No	Number of commands
`provides.hooks`	number	No	Number of hooks
`tags`	array	No	Search tags
`verified`	boolean	No	Verification status

Use Cases

Private/Internal Extensions

Host proprietary extensions that integrate with internal systems:

{
  "internal-auth": {
    "name": "Internal SSO Integration",
    "download_url": "https://artifactory.company.com/spec-kit/internal-auth-1.0.0.zip",
    "verified": true
  }
}

Curated Team Catalog

Limit which extensions your team can install:

{
  "extensions": {
    "jira": { "..." },
    "github": { "..." }
  }
}

Only jira and github will appear in specify extension search.

Air-Gapped Environments

For networks without internet access:

Download extension ZIPs to internal file server
Create catalog pointing to internal URLs
Host catalog on internal web server

{
  "jira": {
    "download_url": "https://files.internal/spec-kit/jira-2.1.0.zip"
  }
}

Development/Testing

Test new extensions before publishing:

# Start local server
python -m http.server 8000 --directory ./my-catalog/

# Point spec-kit to local catalog
export SPECKIT_CATALOG_URL="http://localhost:8000/catalog.json"

# Test installation
specify extension add my-new-extension

Combining with Direct Installation

You can still install extensions not in your catalog using --from:

# From catalog
specify extension add jira

# Direct URL (bypasses catalog)
specify extension add --from https://github.com/someone/spec-kit-ext/archive/v1.0.0.zip

# Local development
specify extension add --dev /path/to/extension

Note: Direct URL installation shows a security warning since the extension isn't from your configured catalog.

Troubleshooting

Extension Not Found

Error: `Extension 'jira' not found in catalog

Solutions:

Check spelling: specify extension search jira
Refresh catalog: specify extension search --help
Check internet connection
Extension may not be published yet

Configuration Not Found

Error: Jira configuration not found

Solutions:

Check if extension is installed: specify extension list

Create config from template:

cp .specify/extensions/jira/jira-config.template.yml \
   .specify/extensions/jira/jira-config.yml

Reinstall extension: specify extension remove jira && specify extension add jira

Command Not Available

Issue: Extension command not appearing in AI agent

Solutions:

Check extension is enabled: specify extension list
Restart AI agent (Claude Code)
Check command file exists:
```
ls .claude/commands/speckit.jira.*.md
```
Reinstall extension

Incompatible Version

Error: Extension requires spec-kit >=0.2.0, but you have 0.1.0

Solutions:

Upgrade spec-kit:
```
uv tool upgrade specify-cli
```

Install older version of extension:

specify extension add --from https://github.com/org/ext/archive/v1.0.0.zip

MCP Tool Not Available

Error: Tool 'jira-mcp-server/epic_create' not found

Solutions:

Check MCP server is installed
Check AI agent MCP configuration
Restart AI agent
Check extension requirements: specify extension info jira

Permission Denied

Error: Permission denied when accessing Jira

Solutions:

Check Jira credentials in MCP server config
Verify project permissions in Jira
Test MCP server connection independently

Best Practices

1. Version Control

Do commit:

.specify/extensions.yml (project extension config)
.specify/extensions/*/jira-config.yml (project config)

Don't commit:

.specify/extensions/.cache/ (catalog cache)
.specify/extensions/.backup/ (config backups)
.specify/extensions/*/*.local.yml (local overrides)
.specify/extensions/.registry (installation state)

Add to .gitignore:

.specify/extensions/.cache/
.specify/extensions/.backup/
.specify/extensions/*/*.local.yml
.specify/extensions/.registry

2. Team Workflows

For teams:

Agree on which extensions to use
Commit extension configuration
Document extension usage in README
Keep extensions updated together

Example README section:

## Extensions

This project uses:
- **jira** (v1.0.0) - Jira integration
  - Config: `.specify/extensions/jira/jira-config.yml`
  - Requires: jira-mcp-server

To install: `specify extension add jira`

3. Local Development

Use local config for development:

# .specify/extensions/jira/jira-config.local.yml
project:
  key: "DEVTEST"  # Your test project

defaults:
  task:
    custom_fields:
      customfield_10002: 1  # Lower story points for testing

4. Environment-Specific Config

Use environment variables for CI/CD:

# .github/workflows/deploy.yml
env:
  SPECKIT_JIRA_PROJECT_KEY: ${{ secrets.JIRA_PROJECT }}

- name: Create Jira Issues
  run: specify extension add jira && ...

5. Extension Updates

Check for updates regularly:

# Weekly or before major releases
specify extension update

Pin versions for stability:

# .specify/extensions.yml
installed:
  - id: jira
    version: "1.0.0"  # Pin to specific version

6. Minimal Extensions

Only install extensions you actively use:

Reduces complexity
Faster command loading
Less configuration

7. Documentation

Document extension usage in your project:

# PROJECT.md

## Working with Jira

After creating tasks, sync to Jira:
1. Run `/speckit.tasks` to generate tasks
2. Run `/speckit.jira.specstoissues` to create Jira issues
3. Run `/speckit.jira.sync-status` to update status

FAQ

Q: Can I use multiple extensions at once?

A: Yes! Extensions are designed to work together. Install as many as you need.

Q: Do extensions slow down spec-kit?

A: No. Extensions are loaded on-demand and only when their commands are used.

Q: Can I create private extensions?

A: Yes. Install with --dev or --from and keep private. Public catalog submission is optional.

Q: How do I know if an extension is safe?

A: Look for the ✓ Verified badge. Verified extensions are reviewed by maintainers. Always review extension code before installing.

Q: Can extensions modify spec-kit core?

A: No. Extensions can only add commands and hooks. They cannot modify core functionality.

Q: What happens if two extensions have the same command name?

A: Extensions use namespaced commands (speckit.{extension}.{command}), so conflicts are very rare. The extension system will warn you if conflicts occur.

Q: Can I contribute to existing extensions?

A: Yes! Most extensions are open source. Check the repository link in specify extension info {extension}.

Q: How do I report extension bugs?

A: Go to the extension's repository (shown in specify extension info) and create an issue.

Q: Can extensions work offline?

A: Once installed, extensions work offline. However, some extensions may require internet for their functionality (e.g., Jira requires Jira API access).

Q: How do I backup my extension configuration?

A: Extension configs are in .specify/extensions/{extension}/. Back up this directory or commit configs to git.

Support

Extension Issues: Report to extension repository (see specify extension info)
Spec Kit Issues: https://github.com/statsperform/spec-kit/issues
Extension Catalog: https://github.com/statsperform/spec-kit/tree/main/extensions
Documentation: See EXTENSION-DEVELOPMENT-GUIDE.md and EXTENSION-PUBLISHING-GUIDE.md

Last Updated: 2026-01-28 Spec Kit Version: 0.1.0

20 KiB Raw Blame History

Extension User Guide

Table of Contents

Introduction

What are Extensions?

Why Use Extensions?

Getting Started

Prerequisites

Check Your Version

First Extension

Finding Extensions

Browse All Extensions

Search by Keyword

Filter by Tag

Filter by Author

Show Verified Only

Get Extension Details

Installing Extensions

Install from Catalog

Install from URL

Install from Local Directory (Development)

Installation Output

Using Extensions

Using Extension Commands

Extension Configuration

Extension Hooks

Managing Extensions

List Installed Extensions

Update Extensions

Disable Extension Temporarily

Re-enable Extension

Remove Extension

Configuration

Configuration Files

Configuration Layers

Example: Jira Configuration

Project-Wide Extension Settings

Core Environment Variables

Example: Using a custom catalog for testing

Organization Catalog Customization

Why the Default Catalog is Empty

Setting Up a Custom Catalog

1. Create Your Catalog File

2. Host the Catalog

3. Configure Your Environment

Option A: Environment variable (recommended for CI/CD)

Option B: Per-project configuration

4. Verify Configuration

Catalog JSON Schema

Use Cases

Private/Internal Extensions

Curated Team Catalog

Air-Gapped Environments

Development/Testing

Combining with Direct Installation

Troubleshooting

Extension Not Found

Configuration Not Found

Command Not Available

Incompatible Version

MCP Tool Not Available

Permission Denied

Best Practices

1. Version Control

2. Team Workflows

3. Local Development

4. Environment-Specific Config

5. Extension Updates

6. Minimal Extensions

7. Documentation

FAQ

Q: Can I use multiple extensions at once?

Q: Do extensions slow down spec-kit?

Q: Can I create private extensions?

Q: How do I know if an extension is safe?

Q: Can extensions modify spec-kit core?

Q: What happens if two extensions have the same command name?

Q: Can I contribute to existing extensions?

Q: How do I report extension bugs?

Q: Can extensions work offline?

20 KiB

Raw Blame History