Extension System

Relevant source files

• CHANGELOG.md
• pyproject.toml
• src/specify_cli/__init__.py

Purpose and Scope

The Extension System provides a modular architecture for adding commands and functionality to Spec Kit projects without bloating the core CLI. Extensions are self-contained packages that can register slash commands for AI agents, hook into workflow events, and provide configurable behaviors.

This page covers the overall architecture, components, and data flows of the extension system. For specific topics:

• Extension CLI commands (list, add, remove, etc.): see Extension Management Commands
• Internal implementation details: see Extension Architecture
• Discovering and searching extensions: see Extension Catalog and Discovery
• Lifecycle hooks and automation: see Hook System
• Configuration cascade: see Configuration Layers
• Creating your own extensions: see Creating Extensions

---

System Overview

Extensions are ZIP archives or directories containing:

1. An extension.yml manifest describing metadata, commands, hooks, and configuration
2. Command template files (.md or .toml) for AI agent integration
3. Optional configuration files and documentation

Extensions install into .specify/extensions/{extension-id}/ and register themselves in .specify/extensions/.registry for tracking enabled/disabled state and metadata.

Key Capabilities:

• Modular Commands: Add new /speckit.{extension}.* slash commands without modifying core
• Multi-Agent Support: Automatically generate agent-specific command files for 16+ AI assistants
• Lifecycle Hooks: Execute logic at workflow events (pre-plan, post-implement, etc.)
• Configuration Layers: Four-tier config cascade (defaults → project → local → environment)
• Semantic Versioning: Compatibility checks against spec-kit core version

Sources: CHANGELOG.md10-120 src/specify_cli/__init__.py1403-1410

---

Core Components

Component Architecture

Sources: src/specify_cli/__init__.py1434-1477 src/specify_cli/__init__.py1484-1709 CHANGELOG.md14-28

Component Responsibilities

Component	Location	Purpose
ExtensionManager	src/specify_cli/extensions.py	Orchestrates installation, removal, enable/disable operations
ExtensionRegistry	.specify/extensions/.registry	JSON file tracking installed extensions and their state
ExtensionCatalog	src/specify_cli/extensions.py	Fetches and caches central catalog from GitHub
HookExecutor	src/specify_cli/extensions.py	Executes lifecycle hooks with condition evaluation
CommandRegistrar	src/specify_cli/extensions.py	Generates agent-specific command files from templates
ConfigManager	src/specify_cli/extensions.py	Merges 4-layer configuration cascade

Sources: CHANGELOG.md15-27 CHANGELOG.md52-59

---

Extension Manifest Schema

Every extension requires an extension.yml manifest file defining its metadata, commands, hooks, and configuration defaults.

Manifest Structure

Key Fields:

• id: Must be unique, lowercase, hyphenated (used for directory names)
• version: Semantic version (MAJOR.MINOR.PATCH) for compatibility checks
• spec_kit_version: Version constraint (e.g., >=0.1.0, ^0.1.0) validated during install
• commands[].file: Path relative to extension root (supports .md and .toml)
• hooks[].condition: Optional condition expression for conditional execution
• config: Nested defaults merged with project/local/environment configs

Sources: CHANGELOG.md16-28 CHANGELOG.md78-87

---

File System Structure

Extensions install into a standardized directory structure within .specify/extensions/.

Directory Layout

.specify/
└── extensions/
    ├── .registry                           # JSON registry of installed extensions
    ├── .cache/                            # Temporary files
    │   ├── catalog.json                   # Cached extension catalog (1 hour TTL)
    │   └── downloads/                     # Temporary ZIP downloads
    ├── {extension-id}/                    # Installed extension
    │   ├── extension.yml                  # Manifest
    │   ├── commands/                      # Command templates
    │   │   ├── command1.md
    │   │   └── command2.toml
    │   ├── {extension-id}-config.yml      # Project config (committed)
    │   └── local-config.yml               # Local config (gitignored)
    └── {another-extension-id}/
        └── ...

Registry Format

The .registry file tracks all installed extensions:

Registry Operations:

• Created automatically on first extension install
• Updated atomically during install/remove/enable/disable
• enabled flag controls whether hooks execute and commands are visible

Sources: CHANGELOG.md17-18 CHANGELOG.md31-39

---

Installation Flow

Extensions can be installed from three sources: local directories, remote URLs, or the central catalog.

Installation Sources and Flow

Sources: src/specify_cli/__init__.py1477-1599 CHANGELOG.md19-28

Installation Methods

Method	Flag	Source	Validation	Use Case
Catalog	(default)	extensions/catalog.json	Full (signature, version)	Production installs
Local Dev	--dev	Local directory path	Manifest only	Extension development
Remote URL	--from URL	HTTPS URL (ZIP)	HTTPS + manifest	Custom/private extensions

Security Constraints:

• Remote URLs must use HTTPS (localhost HTTP allowed for testing)
• --from installs show warning about untrusted sources
• Semantic version compatibility checked against current spec-kit version

Sources: src/specify_cli/__init__.py1500-1551 src/specify_cli/__init__.py1519-1526

---

Command Registration

Extensions register slash commands that AI agents can execute. The CommandRegistrar generates agent-specific command files from templates.

Multi-Agent Command Generation

Sources: CHANGELOG.md68-76 src/specify_cli/__init__.py126-229

Command Template Processing

Command templates use YAML frontmatter for metadata:

Processing Steps:

1. Parse frontmatter to extract name, description, args
2. Detect installed agents via folder presence (.claude/, .gemini/, etc.)
3. Convert format based on agent requirements:
   • Markdown agents: Keep .md format
   • TOML agents (Gemini): Convert to .toml with description + prompt fields
4. Replace placeholders:
   • $ARGUMENTS → {{args}} for TOML agents
   • Keep $ARGUMENTS for Markdown agents
5. Write to agent-specific command directory

Sources: CHANGELOG.md68-76 CHANGELOG.md71-73

---

Hook System Overview

Hooks allow extensions to execute logic at specific workflow events without modifying core commands.

Hook Lifecycle Events

Sources: CHANGELOG.md52-59 CHANGELOG.md88-100

Hook Definition Example

Hook Execution:

1. AI agent finishes core command (e.g., /speckit.plan)
2. Agent calls HookExecutor.check_hooks_for_event('post-plan')
3. Executor filters hooks by condition (config values, environment variables)
4. Returns formatted messages for agent to display
5. Agent shows suggestions to user

Condition Syntax:

• config.key.path is set: Check if config value exists
• config.key == 'value': Equality check
• env.VAR is set: Environment variable exists
• env.VAR != 'value': Environment inequality

Sources: CHANGELOG.md88-94 CHANGELOG.md96-100

---

Configuration System Overview

Extensions use a four-layer configuration cascade with increasing precedence.

Configuration Layers

Sources: CHANGELOG.md78-87

Configuration Example

Layer 1 - Defaults (extension.yml):

Layer 2 - Project ({ext-id}-config.yml):

Layer 3 - Local (local-config.yml):

Layer 4 - Environment:

Final Merged Config:

Access Methods:

• ConfigManager.get_config(): Returns full merged config dict
• ConfigManager.get_value('jira.url'): Dot-notation path lookup
• ConfigManager.has_value('sync.auto_create'): Existence check

Sources: CHANGELOG.md78-87

---

Extension Lifecycle States

Extensions transition through several states during their lifecycle.

State Diagram

Sources: CHANGELOG.md60-67 src/specify_cli/__init__.py1434-1477

State Transitions

From State	Command	To State	Effect
Not Installed	add	Enabled	Install files, register commands, update registry
Enabled	disable	Disabled	Unregister commands, mark disabled in registry
Disabled	enable	Enabled	Re-register commands, mark enabled in registry
Enabled/Disabled	update	Same	Replace files, preserve config, maintain enabled state
Enabled/Disabled	remove	Not Installed	Delete files, unregister commands, remove from registry

Key Behaviors:

• disable: Preserves all files and configuration, only toggles visibility
• enable: Re-activates without reinstallation
• update: Preserves configuration across updates
• remove: Offers --keep-config flag to preserve configuration files

Sources: src/specify_cli/__init__.py1434-1477 CHANGELOG.md60-67

---

Extension Discovery Flow

Users discover extensions through the catalog system, which provides search, filtering, and metadata retrieval.

Catalog Discovery Flow

Sources: CHANGELOG.md30-40 src/specify_cli/__init__.py1600-1709

Catalog Structure

The central catalog is stored in extensions/catalog.json in the spec-kit repository:

Catalog Features:

• 1-hour local cache in .specify/extensions/.cache/catalog.json
• Search by query string across name, description, tags
• Filter by --tag, --author, --verified flags
• Version compatibility displayed for each extension

Sources: CHANGELOG.md31-39 src/specify_cli/__init__.py1600-1650

---

CLI Command Summary

All extension commands are subcommands of specify extension:

Command	Arguments	Purpose
list	[--available] [--all]	Show installed extensions or catalog
add	<name> [--dev] [--from URL]	Install extension from catalog, local, or URL
remove	<name> [--keep-config] [--force]	Uninstall extension
search	[query] [--tag] [--author] [--verified]	Search extension catalog
info	<name>	Show detailed extension information
update	<name>	Update extension to latest version
enable	<name>	Enable a disabled extension
disable	<name>	Disable extension without removing

For detailed command documentation, see Extension Management Commands.

Sources: src/specify_cli/__init__.py1405-1410 CHANGELOG.md19-27 CHANGELOG.md60-67