spec-kit/extensions/EXTENSION-USER-GUIDE.md

Extension User Guide

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

Table of Contents

1. Introduction
2. Getting Started
3. Finding Extensions
4. Installing Extensions
5. Using Extensions
6. Managing Extensions
7. Configuration
8. Troubleshooting
9. 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

Note: By default, specify extension search uses your organization's catalog (catalog.json). If the catalog is empty, you won't see any results. See Extension Catalogs to learn how to populate your catalog from the community reference catalog.

Browse All Extensions

specify extension search

Shows all extensions in your organization's 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:

1. Download the extension from GitHub
2. Validate the manifest
3. Check compatibility with your spec-kit version
4. Install to .specify/extensions/jira/
5. Register commands with your AI agent
6. 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):

1. Extension defaults (from extension.yml)
2. Project config (jira-config.yml)
3. Local overrides (jira-config.local.yml)
4. 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"

---

Extension Catalogs

For information about how Spec Kit's dual-catalog system works (catalog.json vs catalog.community.json), see the main Extensions README.

Organization Catalog Customization

Why Customize Your Catalog

Organizations customize their catalog.json 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:

1. Download extension ZIPs to internal file server
2. Create catalog pointing to internal URLs
3. 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:

1. Check spelling: specify extension search jira
2. Refresh catalog: specify extension search --help
3. Check internet connection
4. Extension may not be published yet

Configuration Not Found

Error: Jira configuration not found

Solutions:

1. Check if extension is installed: specify extension list

2. Create config from template:

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

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

Command Not Available

Issue: Extension command not appearing in AI agent

Solutions:

1. Check extension is enabled: specify extension list

2. Restart AI agent (Claude Code)

3. Check command file exists:

   ls .claude/commands/speckit.jira.*.md
   

4. Reinstall extension

Incompatible Version

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

Solutions:

1. Upgrade spec-kit:

   uv tool upgrade specify-cli
   

2. 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:

1. Check MCP server is installed
2. Check AI agent MCP configuration
3. Restart AI agent
4. Check extension requirements: specify extension info jira

Permission Denied

Error: Permission denied when accessing Jira

Solutions:

1. Check Jira credentials in MCP server config
2. Verify project permissions in Jira
3. 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:

1. Agree on which extensions to use
2. Commit extension configuration
3. Document extension usage in README
4. 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