Extension System

The extension system allows you to add new functionality to Spec Kit without bloating the core framework. Extensions are modular packages that integrate seamlessly with your AI coding agent.

Overview

Extensions enable you to:

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

Extensions are loaded on-demand and only when their commands are used, so they won’t slow down Spec Kit.

Extension Catalogs

Spec Kit uses a dual-catalog system to give organizations full control over available extensions:

Your Catalog (`catalog.json`)

Purpose: Default upstream catalog used by the Specify CLI
Default State: Empty by design - you or your organization populate it with trusted extensions
Location: extensions/catalog.json in the GitHub-hosted spec-kit repo
Customization: Copy entries from the community catalog or add your own extensions

# Point to your organization's catalog
export SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json"
specify extension search  # Now uses your catalog

Community Reference Catalog (`catalog.community.json`)

Purpose: Browse available community-contributed extensions
Status: Active - contains extensions submitted by the community
Location: extensions/catalog.community.json
Usage: Reference catalog for discovering extensions
Submission: Open to community contributions via Pull Request

Finding Extensions

By default, specify extension search uses your organization’s catalog. If empty, you won’t see results. See Organization Catalog Customization to populate it.

specify extension search

Get Extension Details

specify extension info jira

Shows:

Description and requirements
Commands provided
Hooks available
Documentation links
Installation status

Installing Extensions

From Catalog

# Install by name
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

From URL

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

From Local Directory

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

Installation Output Example

✓ 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
  • speckit.jira.sync-status - Sync task completion status to Jira

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

Using Extensions

Extension Commands

Extensions add commands to your AI agent:

# In Claude Code, opencode, or other AI agent
/speckit.jira.specstoissues

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

Extension Configuration

Most extensions require configuration:

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

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

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 - gitignored)
Environment variables (SPECKIT_JIRA_*)

Example:

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.

Extension Hooks

Some extensions provide hooks that execute after core commands:

# 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

specify extension list

Example 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

specify extension update

Disable/Enable

specify extension disable jira
# Commands no longer available, hooks won't execute

Remove Extension

specify extension remove jira

Organization Catalog Customization

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"
      },
      "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",
      "tags": ["internal", "proprietary"],
      "verified": true
    }
  }
}

2. Host the Catalog

Options for hosting:

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

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

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

Available Community Extensions

The following extensions are available in catalog.community.json:

Extension	Purpose
V-Model Extension Pack	Enforces V-Model paired generation of development specs and test specs with full traceability
Cleanup Extension	Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues

To use community extensions, copy their entries from catalog.community.json to your organization’s catalog.json.

Creating Extensions

See the Extension Development Guide for detailed instructions on creating your own extensions.

Quick Start

schema_version: "1.0"

extension:
  id: "my-ext"
  name: "My Extension"
  version: "1.0.0"
  description: "My custom extension"
  author: "Your Name"
  repository: "https://github.com/you/spec-kit-my-ext"
  license: "MIT"

requires:
  speckit_version: ">=0.1.0"

provides:
  commands:
    - name: "speckit.my-ext.hello"
      file: "commands/hello.md"
      description: "Say hello"

Test Locally

cd /path/to/spec-kit-project
specify extension add --dev /path/to/my-extension

Best Practices

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)

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

Team Workflows

For teams:

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

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 && ...

Security

Never commit secrets: Use environment variables
Validate input: Sanitize user arguments
Document permissions: What files/APIs are accessed
Review extensions: Always review extension code before installing

Troubleshooting

Extension Not Found

Error: Extension 'jira' not found in catalogSolutions:

Check spelling: specify extension search jira
Verify catalog URL is set correctly
Check internet connection
Extension may not be in your catalog yet

Configuration Not Found

Error: Jira configuration not foundSolutions:

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 agentSolutions:

Check extension is enabled: specify extension list
Restart AI agent (Claude Code, opencode, etc.)
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.0Solutions:

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

Environment Variables

Variable	Description	Default
`SPECKIT_CATALOG_URL`	Override extension catalog URL	GitHub-hosted catalog
`GH_TOKEN` / `GITHUB_TOKEN`	GitHub API token for downloads	None
`SPECKIT_{EXTENSION}_*`	Extension-specific configuration	Extension defaults

Get Started

Core Concepts

CLI Reference

Slash Commands

AI Agents

Advanced

Overview

Extension Catalogs

Your Catalog (`catalog.json`)

Community Reference Catalog (`catalog.community.json`)

Finding Extensions

Get Extension Details

Installing Extensions

From Catalog

From URL

From Local Directory

Using Extensions

Extension Commands

Extension Configuration

Extension Hooks

Managing Extensions

List Installed

Update Extensions

Disable/Enable

Remove Extension

Organization Catalog Customization

Setting Up a Custom Catalog

Available Community Extensions

Creating Extensions

Quick Start

Test Locally

Best Practices

Version Control

Team Workflows

Environment-Specific Config

Security

Troubleshooting

Environment Variables

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Reference

Slash Commands

AI Agents

Advanced

​Overview

​Extension Catalogs

​Your Catalog (catalog.json)

​Community Reference Catalog (catalog.community.json)

​Finding Extensions

​Get Extension Details

​Installing Extensions

​From Catalog

​From URL

​From Local Directory

​Using Extensions

​Extension Commands

​Extension Configuration

​Extension Hooks

​Managing Extensions

​List Installed

​Update Extensions

​Disable/Enable

​Remove Extension

​Organization Catalog Customization

​Setting Up a Custom Catalog

​Available Community Extensions

​Creating Extensions

​Quick Start

​Test Locally

​Best Practices

​Version Control

​Team Workflows

​Environment-Specific Config

​Security

​Troubleshooting

​Environment Variables

​Related Resources

Build docs developers (and LLMs) love

Overview

Extension Catalogs

Your Catalog (`catalog.json`)

Community Reference Catalog (`catalog.community.json`)

Finding Extensions

Get Extension Details

Installing Extensions

From Catalog

From URL

From Local Directory

Using Extensions

Extension Commands

Extension Configuration

Extension Hooks

Managing Extensions

List Installed

Update Extensions

Disable/Enable

Remove Extension

Organization Catalog Customization

Setting Up a Custom Catalog

Available Community Extensions

Creating Extensions

Quick Start

Test Locally

Best Practices

Version Control

Team Workflows

Environment-Specific Config

Security

Troubleshooting

Environment Variables

Related Resources