This document describes the internal architecture of the Spec Kit extension system. It covers the core components that enable modular extensions: the ExtensionManager class, the registry structure, the manifest schema, and the command registration system.
For information about using extension management CLI commands, see Extension Management Commands. For details on the hook system, see Hook System. For configuration management, see Configuration Layers. For guidance on creating extensions, see Creating Extensions.
The extension system consists of four primary components that work together to provide a modular, extensible architecture.
Sources: CHANGELOG.md14-28 pyproject.toml13-14
The ExtensionManager class serves as the primary orchestrator for all extension operations. It is located in src/specify_cli/extensions.py and provides the API for installing, removing, enabling, disabling, and querying extensions.
| Responsibility | Methods | Description |
|---|---|---|
| Installation | add(), install_from_local(), install_from_url() | Validates manifest, copies files, updates registry |
| Removal | remove(), uninstall() | Cleans up files, unregisters commands, updates registry |
| State Management | enable(), disable() | Toggles extension active state without file removal |
| Query Operations | list(), get_info(), is_installed() | Retrieves extension information from registry |
| Version Management | check_version_compatibility() | Validates semantic versioning constraints |
| Command Registration | Delegates to CommandRegistrar | Registers commands with AI agents |
Sources: CHANGELOG.md14-28 CHANGELOG.md68-76
Extensions are defined by an extension.yml manifest file that declares metadata, commands, hooks, and configuration. The manifest uses a strict schema validated during installation.
| Field | Required | Type | Validation |
|---|---|---|---|
id | Yes | string | Must be lowercase, alphanumeric with hyphens |
name | Yes | string | Human-readable display name |
version | Yes | string | Must follow semantic versioning (X.Y.Z) |
description | Yes | string | Brief extension description |
author | No | string | Extension author name |
license | No | string | License identifier (e.g., MIT) |
repository | No | URL | Source repository URL |
min_speckit_version | No | string | Minimum compatible Spec Kit version |
commands | No | list | Command definitions |
hooks | No | list | Hook definitions |
config | No | object | Default configuration values |
The system uses the packaging library to validate semantic versioning constraints. During installation, the ExtensionManager checks that:
version field follows semantic versioning (MAJOR.MINOR.PATCH)min_speckit_version is specified, the current Spec Kit version satisfies the constraintSources: CHANGELOG.md16-17 CHANGELOG.md25 pyproject.toml14
The registry is a YAML file at .specify/extensions/.registry that tracks all installed extensions. It serves as the single source of truth for which extensions are present and their current state.
| Field | Type | Description |
|---|---|---|
version | string | Installed version (semantic version) |
installed_at | ISO 8601 timestamp | Installation date and time |
enabled | boolean | Whether extension is active |
path | string | Relative path to extension directory |
commands_registered | boolean | Whether commands are registered with agents |
agents | list of strings | AI agents where commands are registered |
Registry Persistence: The registry is read and parsed on every extension operation. After modifications, it is written back atomically to ensure consistency. The ExtensionManager uses pyyaml for serialization and deserialization.
Sources: CHANGELOG.md17 pyproject.toml13
The CommandRegistrar component handles the registration of extension commands with AI agents. It must accommodate the diverse conventions of 16+ supported AI agents.
The system uses the AGENT_CONFIG dictionary from src/specify_cli/__init__.py as the single source of truth for agent metadata. This includes:
"claude", "gemini").claude/commands/, .gemini/commands/)$ARGUMENTS or {{args}})The system automatically converts argument placeholders based on agent format:
| Agent Format | Placeholder Pattern | Example |
|---|---|---|
| Markdown | $ARGUMENTS | /speckit.jira.sync-status $ARGUMENTS |
| TOML | {{args}} | prompt = "Execute with: {{args}}" |
Automatic Detection: During installation, register_commands_for_all_agents() scans the project for agent-specific directories (.claude/, .gemini/, .github/agents/, etc.) and registers commands only for detected agents. This ensures commands are not registered for agents not in use.
Sources: CHANGELOG.md68-76 CHANGELOG.md27
Sources: CHANGELOG.md19-28 CHANGELOG.md68-76
The extension system uses a structured directory hierarchy within .specify/extensions/:
.specify/
└── extensions/
├── .registry # Registry file
├── .cache/ # Catalog cache (see 4.3)
└── {extension-id}/ # Per-extension directory
├── extension.yml # Manifest
├── commands/ # Command template files
│ ├── command1.md
│ └── command2.md
├── {extension-id}-config.yml # Project config (see 4.5)
├── local-config.yml # Local config (see 4.5, gitignored)
└── ... (other extension files)
Extension directories use the id field from the manifest. This ensures:
Sources: CHANGELOG.md17
The extension system uses semantic versioning to ensure compatibility between extensions and the Spec Kit core.
MAJOR.MINOR.PATCH format (e.g., 1.0.0, 2.3.1)pyproject.toml at runtimeThe packaging library (version 23.0+) provides PEP 440-compliant version parsing and comparison.
Sources: CHANGELOG.md25 pyproject.toml14
The extension system implements multiple validation layers to prevent invalid states.
| Validation | Location | Failure Behavior |
|---|---|---|
| Manifest exists | ExtensionManager.add() | Return error, halt installation |
| Manifest is valid YAML | Manifest parser | Return error, halt installation |
| Required fields present | Manifest validator | Return error, halt installation |
| Extension ID format | Manifest validator | Return error, halt installation |
| Version format | Manifest validator | Return error, halt installation |
| Version compatibility | ExtensionManager.check_version_compatibility() | Return error, halt installation |
| Extension ID unique | Registry check | Return error, halt installation |
| Command files exist | Command registration | Log warning, continue |
All extension operations return structured error information to the CLI for display to the user. Errors include:
Sources: CHANGELOG.md14-28
The extension system relies on the following external libraries:
| Library | Version | Purpose |
|---|---|---|
pyyaml | ≥6.0 | YAML parsing and serialization for manifests and registry |
packaging | ≥23.0 | Semantic version parsing and comparison |
These dependencies are declared in pyproject.toml and installed automatically with the specify-cli package.
Sources: pyproject.toml13-14 CHANGELOG.md28
Refresh this wiki