fix: include 'src/**' path in release workflow triggers (#1646 )

Co-authored-by: Manfred Riem <mnriem@users.noreply.github.com>
chore(deps): bump github/codeql-action from 3 to 4 (#1635 )
2026-03-17 19:03:08 +00:00 · 2026-02-20 09:46:29 -06:00 · 2026-02-19 16:31:23 -06:00 · 2026-02-19 16:21:58 -06:00 · 2026-02-19 15:49:34 -06:00 · 2026-02-19 13:24:41 -06:00
40 changed files with 10079 additions and 46 deletions
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,22 @@
+## Description
+
+<!-- What does this PR do? Why is it needed? -->
+
+## Testing
+
+<!-- How did you test your changes? -->
+
+- [ ] Tested locally with `uv run specify --help`
+- [ ] Ran existing tests with `uv sync && uv run pytest`
+- [ ] Tested with a sample project (if applicable)
+
+## AI Disclosure
+
+<!-- Per our Contributing guidelines, AI assistance must be disclosed. -->
+<!-- See: https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#ai-contributions-in-spec-kit -->
+
+- [ ] I **did not** use AI assistance for this contribution
+- [ ] I **did** use AI assistance (describe below)
+
+<!-- If you used AI, briefly describe how (e.g., "Code generated by Copilot", "Consulted ChatGPT for approach"): -->
+
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
--- a/.github/workflows/codeql.yml
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,32 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'actions', 'python' ]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -17,4 +17,6 @@ jobs:
      - name: Run markdownlint-cli2
        uses: DavidAnson/markdownlint-cli2-action@v19
        with:
-          globs: '**/*.md'
+          globs: |
+            '**/*.md'
+            !extensions/**/*.md
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -6,6 +6,7 @@ on:
    paths:
      - 'memory/**'
      - 'scripts/**'
+      - 'src/**'
      - 'templates/**'
      - '.github/workflows/**'
  workflow_dispatch:
--- a/.github/workflows/scripts/create-github-release.sh
+++ b/.github/workflows/scripts/create-github-release.sh
@@ -48,6 +48,8 @@ gh release create "$VERSION" \
  .genreleases/spec-kit-template-shai-ps-"$VERSION".zip \
  .genreleases/spec-kit-template-q-sh-"$VERSION".zip \
  .genreleases/spec-kit-template-q-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-agy-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-agy-ps-"$VERSION".zip \
  .genreleases/spec-kit-template-bob-sh-"$VERSION".zip \
  .genreleases/spec-kit-template-bob-ps-"$VERSION".zip \
  --title "Spec Kit Templates - $VERSION_NO_V" \
--- a/.github/workflows/scripts/create-release-packages.sh
+++ b/.github/workflows/scripts/create-release-packages.sh
@@ -34,7 +34,8 @@ rewrite_paths() {
  sed -E \
    -e 's@(/?)memory/@.specify/memory/@g' \
    -e 's@(/?)scripts/@.specify/scripts/@g' \
-    -e 's@(/?)templates/@.specify/templates/@g'
+    -e 's@(/?)templates/@.specify/templates/@g' \
+    -e 's@\.specify\.specify/@.specify/@g'
 }

 generate_commands() {
@@ -214,6 +215,9 @@ build_variant() {
    q)
      mkdir -p "$base_dir/.amazonq/prompts"
      generate_commands q md "\$ARGUMENTS" "$base_dir/.amazonq/prompts" "$script" ;;
+    agy)
+      mkdir -p "$base_dir/.agent/workflows"
+      generate_commands agy md "\$ARGUMENTS" "$base_dir/.agent/workflows" "$script" ;;
    bob)
      mkdir -p "$base_dir/.bob/commands"
      generate_commands bob md "\$ARGUMENTS" "$base_dir/.bob/commands" "$script" ;;
@@ -223,7 +227,7 @@ build_variant() {
 }

 # Determine agent list
-ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf codex kilocode auggie roo codebuddy amp shai q bob qoder)
+ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf codex kilocode auggie roo codebuddy amp shai q agy bob qoder)
 ALL_SCRIPTS=(sh ps)

 norm_list() {
--- a/.github/workflows/stale.yml
+++ b/.github/workflows/stale.yml
@@ -0,0 +1,42 @@
+name: 'Close stale issues and PRs'
+
+on:
+  schedule:
+    - cron: '0 0 * * *' # Run daily at midnight UTC
+  workflow_dispatch: # Allow manual triggering
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v10
+        with:
+          # Days of inactivity before an issue or PR becomes stale
+          days-before-stale: 150
+          # Days of inactivity before a stale issue or PR is closed (after being marked stale)
+          days-before-close: 30
+          
+          # Stale issue settings
+          stale-issue-message: 'This issue has been automatically marked as stale because it has not had any activity for 150 days. It will be closed in 30 days if no further activity occurs.'
+          close-issue-message: 'This issue has been automatically closed due to inactivity (180 days total). If you believe this issue is still relevant, please reopen it or create a new issue.'
+          stale-issue-label: 'stale'
+          
+          # Stale PR settings
+          stale-pr-message: 'This pull request has been automatically marked as stale because it has not had any activity for 150 days. It will be closed in 30 days if no further activity occurs.'
+          close-pr-message: 'This pull request has been automatically closed due to inactivity (180 days total). If you believe this PR is still relevant, please reopen it or create a new PR.'
+          stale-pr-label: 'stale'
+          
+          # Exempt issues and PRs with these labels from being marked as stale
+          exempt-issue-labels: 'pinned,security'
+          exempt-pr-labels: 'pinned,security'
+          
+          # Only issues or PRs with all of these labels are checked
+          # Leave empty to check all issues and PRs
+          any-of-labels: ''
+          
+          # Operations per run (helps avoid rate limits)
+          operations-per-run: 100
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -0,0 +1,50 @@
+name: Test & Lint Python
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Run ruff check
+        run: uvx ruff check src/
+
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra test
+
+      - name: Run tests
+        run: uv run pytest
--- a/.gitignore
+++ b/.gitignore
@@ -44,3 +44,9 @@ env/
 .genreleases/
 *.zip
 sdd-*/
+docs/dev
+
+# Extension system
+.specify/extensions/.cache/
+.specify/extensions/.backup/
+.specify/extensions/*/local-config.yml
--- a/.markdownlint-cli2.jsonc
+++ b/.markdownlint-cli2.jsonc
@@ -19,7 +19,9 @@
    },
    "MD050": {
      "style": "asterisk"
-    }
+    },
+    "MD036": false,
+    "MD060": false
  },
  "ignores": [
    ".genreleases/"
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,11 +2,141 @@

 <!-- markdownlint-disable MD024 -->

+
 All notable changes to the Specify CLI and templates are documented here.

 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+## [0.1.1] - 2026-02-13
+
+### Added
+
+- **Agent Skills Installation**: New `--ai-skills` CLI option to install Prompt.MD templates as agent skills following [agentskills.io specification](https://agentskills.io/specification)
+  - Skills are installed to agent-specific directories (e.g., `.claude/skills/`, `.gemini/skills/`, `.github/skills/`)
+  - Codex uses `.agents/skills/` following Codex agent directory conventions
+  - Default fallback directory is `.agents/skills/` for agents without a specific mapping
+  - Requires `--ai` flag to be specified
+  - Converts all 9 spec-kit command templates (specify, plan, tasks, implement, analyze, clarify, constitution, checklist, taskstoissues) to properly formatted SKILL.md files
+  - **New projects**: command files are not installed when `--ai-skills` is used (skills replace commands)
+  - **Existing repos** (`--here`): pre-existing command files are preserved — no breaking changes
+  - `pyyaml` dependency (already present) used for YAML frontmatter parsing
+- **Unit tests** for `install_ai_skills`, `_get_skills_dir`, and `--ai-skills` CLI validation (51 test cases covering all 18 supported agents)
+
+## [0.1.0] - 2026-01-28
+
+### Added
+
+- **Extension System**: Introduced modular extension architecture for Spec Kit
+  - Extensions are self-contained packages that add commands and functionality without bloating core
+  - Extension manifest schema (`extension.yml`) with validation
+  - Extension registry (`.specify/extensions/.registry`) for tracking installed extensions
+  - Extension manager module (`src/specify_cli/extensions.py`) for installation/removal
+  - New CLI commands:
+    - `specify extension list` - List installed extensions
+    - `specify extension add` - Install extension from local directory or URL
+    - `specify extension remove` - Uninstall extension
+    - `specify extension search` - Search extension catalog
+    - `specify extension info` - Show detailed extension information
+  - Semantic versioning compatibility checks
+  - Support for extension configuration files
+  - Command registration system for AI agents (Claude support initially)
+  - Added dependencies: `pyyaml>=6.0`, `packaging>=23.0`
+
+- **Extension Catalog**: Extension discovery and distribution system
+  - Central catalog (`extensions/catalog.json`) for published extensions
+  - Extension catalog manager (`ExtensionCatalog` class) with:
+    - Catalog fetching from GitHub
+    - 1-hour local caching for performance
+    - Search by query, tag, author, or verification status
+    - Extension info retrieval
+  - Catalog cache stored in `.specify/extensions/.cache/`
+  - Search and info commands with rich console output
+  - Added 9 catalog-specific unit tests (100% pass rate)
+
+- **Jira Extension**: First official extension for Jira integration
+  - Extension ID: `jira`
+  - Version: 1.0.0
+  - 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
+  - Comprehensive documentation (README, usage guide, examples)
+  - MIT licensed
+
+- **Hook System**: Extension lifecycle hooks for automation
+  - `HookExecutor` class for managing extension hooks
+  - Hooks registered in `.specify/extensions.yml`
+  - Hook registration during extension installation
+  - Hook unregistration during extension removal
+  - Support for optional and mandatory hooks
+  - Hook execution messages for AI agent integration
+  - Condition support for conditional hook execution (placeholder)
+
+- **Extension Management**: Advanced extension management commands
+  - `specify extension update` - Check and update extensions to latest version
+  - `specify extension enable` - Enable a disabled extension
+  - `specify extension disable` - Disable extension without removing it
+  - Version comparison with catalog
+  - Update notifications
+  - Preserve configuration during updates
+
+- **Multi-Agent Support**: Extensions now work with all supported AI agents (Phase 6)
+  - Automatic detection and registration for all agents in project
+  - Support for 16+ AI agents (Claude, Gemini, Copilot, Cursor, Qwen, and more)
+  - Agent-specific command formats (Markdown and TOML)
+  - Automatic argument placeholder conversion ($ARGUMENTS → {{args}})
+  - Commands registered for all detected agents during installation
+  - Multi-agent command unregistration on extension removal
+  - `CommandRegistrar.register_commands_for_agent()` method
+  - `CommandRegistrar.register_commands_for_all_agents()` method
+
+- **Configuration Layers**: Full configuration cascade system (Phase 6)
+  - **Layer 1**: Defaults from extension manifest (`extension.yml`)
+  - **Layer 2**: Project config (`.specify/extensions/{ext-id}/{ext-id}-config.yml`)
+  - **Layer 3**: Local config (`.specify/extensions/{ext-id}/local-config.yml`, gitignored)
+  - **Layer 4**: Environment variables (`SPECKIT_{EXT_ID}_{KEY}` pattern)
+  - Recursive config merging with proper precedence
+  - `ConfigManager` class for programmatic config access
+  - `get_config()`, `get_value()`, `has_value()` methods
+  - Support for nested configuration paths with dot-notation
+
+- **Hook Condition Evaluation**: Smart hook execution based on runtime conditions (Phase 6)
+  - Config conditions: `config.key.path is set`, `config.key == 'value'`, `config.key != 'value'`
+  - Environment conditions: `env.VAR is set`, `env.VAR == 'value'`, `env.VAR != 'value'`
+  - Automatic filtering of hooks based on condition evaluation
+  - Safe fallback behavior on evaluation errors
+  - Case-insensitive pattern matching
+
+- **Hook Integration**: Agent-level hook checking and execution (Phase 6)
+  - `check_hooks_for_event()` method for AI agents to query hooks after core commands
+  - Condition-aware hook filtering before execution
+  - `enable_hooks()` and `disable_hooks()` methods per extension
+  - Formatted hook messages for agent display
+  - `execute_hook()` method for hook execution information
+
+- **Documentation Suite**: Comprehensive documentation for users and developers
+  - **EXTENSION-USER-GUIDE.md**: Complete user guide with installation, usage, configuration, and troubleshooting
+  - **EXTENSION-API-REFERENCE.md**: Technical API reference with manifest schema, Python API, and CLI commands
+  - **EXTENSION-PUBLISHING-GUIDE.md**: Publishing guide for extension authors
+  - **RFC-EXTENSION-SYSTEM.md**: Extension architecture design document
+
+- **Extension Template**: Starter template in `extensions/template/` for creating new extensions
+  - Fully commented `extension.yml` manifest template
+  - Example command file with detailed explanations
+  - Configuration template with all options
+  - Complete project structure (README, LICENSE, CHANGELOG, .gitignore)
+  - EXAMPLE-README.md showing final documentation format
+
+- **Unit Tests**: Comprehensive test suite with 39 tests covering all extension system components
+  - Test coverage: 83% of extension module code
+  - Test dependencies: `pytest>=7.0`, `pytest-cov>=4.0`
+  - Configured pytest in `pyproject.toml`
+
+### Changed
+
+- Version bumped to 0.1.0 (minor release for new feature)
+
 ## [0.0.22] - 2025-11-07

 - Support for VS Code/Copilot agents, and moving away from prompts to proper agents with hand-offs.
--- a/README.md
+++ b/README.md
@@ -31,7 +31,6 @@
 - [📖 Learn More](#-learn-more)
 - [📋 Detailed Process](#-detailed-process)
 - [🔍 Troubleshooting](#-troubleshooting)
- [👥 Maintainers](#-maintainers)
 - [💬 Support](#-support)
 - [🙏 Acknowledgements](#-acknowledgements)
 - [📄 License](#-license)
@@ -162,6 +161,7 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c
 | [Roo Code](https://roocode.com/)                                                     | ✅      |                                                                                                                                           |
 | [SHAI (OVHcloud)](https://github.com/ovh/shai)                                       | ✅      |                                                                                                                                           |
 | [Windsurf](https://windsurf.com/)                                                    | ✅      |                                                                                                                                           |
+| [Antigravity (agy)](https://agy.ai/)                                                 | ✅      |                                                                                                                                           |

 ## 🔧 Specify CLI Reference

@@ -179,7 +179,7 @@ The `specify` command supports the following options:
 | Argument/Option        | Type     | Description                                                                                                                                                                                  |
 | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `<project-name>`       | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory)                                                                                           |
-| `--ai`                 | Option   | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `shai`, `q`, `bob`, or `qoder` |
+| `--ai`                 | Option   | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `shai`, `q`, `agy`, `bob`, or `qoder` |
 | `--script`             | Option   | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell)                                                                                                                                  |
 | `--ignore-agent-tools` | Flag     | Skip checks for AI agent tools like Claude Code                                                                                                                                              |
 | `--no-git`             | Flag     | Skip git repository initialization                                                                                                                                                           |
@@ -188,6 +188,7 @@ The `specify` command supports the following options:
 | `--skip-tls`           | Flag     | Skip SSL/TLS verification (not recommended)                                                                                                                                                  |
 | `--debug`              | Flag     | Enable detailed debug output for troubleshooting                                                                                                                                             |
 | `--github-token`       | Option   | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable)                                                                                                                    |
+| `--ai-skills`          | Flag     | Install Prompt.MD templates as agent skills in agent-specific `skills/` directory (requires `--ai`)                                                                                          |

 ### Examples

@@ -238,6 +239,12 @@ specify init my-project --ai claude --debug
 # Use GitHub token for API requests (helpful for corporate environments)
 specify init my-project --ai claude --github-token ghp_your_token_here

+# Install agent skills with the project
+specify init my-project --ai claude --ai-skills
+
+# Initialize in current directory with agent skills
+specify init --here --ai gemini --ai-skills
+
 # Check system requirements
 specify check
 ```
@@ -636,11 +643,6 @@ echo "Cleaning up..."
 rm gcm-linux_amd64.2.6.1.deb
 ```

-## 👥 Maintainers
-
- Den Delimarsky ([@localden](https://github.com/localden))
- John Lam ([@jflam](https://github.com/jflam))
-
 ## 💬 Support

 For support, please open a [GitHub issue](https://github.com/github/spec-kit/issues/new). We welcome bug reports, feature requests, and questions about using Spec-Driven Development.
--- a/extensions/EXTENSION-API-REFERENCE.md
+++ b/extensions/EXTENSION-API-REFERENCE.md
@@ -0,0 +1,714 @@
+# Extension API Reference
+
+Technical reference for Spec Kit extension system APIs and manifest schema.
+
+## Table of Contents
+
+1. [Extension Manifest](#extension-manifest)
+2. [Python API](#python-api)
+3. [Command File Format](#command-file-format)
+4. [Configuration Schema](#configuration-schema)
+5. [Hook System](#hook-system)
+6. [CLI Commands](#cli-commands)
+
+---
+
+## Extension Manifest
+
+### Schema Version 1.0
+
+File: `extension.yml`
+
+```yaml
+schema_version: "1.0"  # Required
+
+extension:
+  id: string           # Required, pattern: ^[a-z0-9-]+$
+  name: string         # Required, human-readable name
+  version: string      # Required, semantic version (X.Y.Z)
+  description: string  # Required, brief description (<200 chars)
+  author: string       # Required
+  repository: string   # Required, valid URL
+  license: string      # Required (e.g., "MIT", "Apache-2.0")
+  homepage: string     # Optional, valid URL
+
+requires:
+  speckit_version: string  # Required, version specifier (>=X.Y.Z)
+  tools:                   # Optional, array of tool requirements
+    - name: string         # Tool name
+      version: string      # Optional, version specifier
+      required: boolean    # Optional, default: false
+
+provides:
+  commands:              # Required, at least one command
+    - name: string       # Required, pattern: ^speckit\.[a-z0-9-]+\.[a-z0-9-]+$
+      file: string       # Required, relative path to command file
+      description: string # Required
+      aliases: [string]  # Optional, array of alternate names
+
+  config:                # Optional, array of config files
+    - name: string       # Config file name
+      template: string   # Template file path
+      description: string
+      required: boolean  # Default: false
+
+hooks:                   # Optional, event hooks
+  event_name:            # e.g., "after_tasks", "after_implement"
+    command: string      # Command to execute
+    optional: boolean    # Default: true
+    prompt: string       # Prompt text for optional hooks
+    description: string  # Hook description
+    condition: string    # Optional, condition expression
+
+tags:                    # Optional, array of tags (2-10 recommended)
+  - string
+
+defaults:                # Optional, default configuration values
+  key: value             # Any YAML structure
+```
+
+### Field Specifications
+
+#### `extension.id`
+
+- **Type**: string
+- **Pattern**: `^[a-z0-9-]+$`
+- **Description**: Unique extension identifier
+- **Examples**: `jira`, `linear`, `azure-devops`
+- **Invalid**: `Jira`, `my_extension`, `extension.id`
+
+#### `extension.version`
+
+- **Type**: string
+- **Format**: Semantic versioning (X.Y.Z)
+- **Description**: Extension version
+- **Examples**: `1.0.0`, `0.9.5`, `2.1.3`
+- **Invalid**: `v1.0`, `1.0`, `1.0.0-beta`
+
+#### `requires.speckit_version`
+
+- **Type**: string
+- **Format**: Version specifier
+- **Description**: Required spec-kit version range
+- **Examples**:
+  - `>=0.1.0` - Any version 0.1.0 or higher
+  - `>=0.1.0,<2.0.0` - Version 0.1.x or 1.x
+  - `==0.1.0` - Exactly 0.1.0
+- **Invalid**: `0.1.0`, `>= 0.1.0` (space), `latest`
+
+#### `provides.commands[].name`
+
+- **Type**: string
+- **Pattern**: `^speckit\.[a-z0-9-]+\.[a-z0-9-]+$`
+- **Description**: Namespaced command name
+- **Format**:  `speckit.{extension-id}.{command-name}`
+- **Examples**: `speckit.jira.specstoissues`, `speckit.linear.sync`
+- **Invalid**: `jira.specstoissues`, `speckit.command`, `speckit.jira.CreateIssues`
+
+#### `hooks`
+
+- **Type**: object
+- **Keys**: Event names (e.g., `after_tasks`, `after_implement`, `before_commit`)
+- **Description**: Hooks that execute at lifecycle events
+- **Events**: Defined by core spec-kit commands
+
+---
+
+## Python API
+
+### ExtensionManifest
+
+**Module**: `specify_cli.extensions`
+
+```python
+from specify_cli.extensions import ExtensionManifest
+
+manifest = ExtensionManifest(Path("extension.yml"))
+```
+
+**Properties**:
+
+```python
+manifest.id                        # str: Extension ID
+manifest.name                      # str: Extension name
+manifest.version                   # str: Version
+manifest.description               # str: Description
+manifest.requires_speckit_version  # str: Required spec-kit version
+manifest.commands                  # List[Dict]: Command definitions
+manifest.hooks                     # Dict: Hook definitions
+```
+
+**Methods**:
+
+```python
+manifest.get_hash()  # str: SHA256 hash of manifest file
+```
+
+**Exceptions**:
+
+```python
+ValidationError       # Invalid manifest structure
+CompatibilityError    # Incompatible with current spec-kit version
+```
+
+### ExtensionRegistry
+
+**Module**: `specify_cli.extensions`
+
+```python
+from specify_cli.extensions import ExtensionRegistry
+
+registry = ExtensionRegistry(extensions_dir)
+```
+
+**Methods**:
+
+```python
+# Add extension to registry
+registry.add(extension_id: str, metadata: dict)
+
+# Remove extension from registry
+registry.remove(extension_id: str)
+
+# Get extension metadata
+metadata = registry.get(extension_id: str)  # Optional[dict]
+
+# List all extensions
+extensions = registry.list()  # Dict[str, dict]
+
+# Check if installed
+is_installed = registry.is_installed(extension_id: str)  # bool
+```
+
+**Registry Format**:
+
+```json
+{
+  "schema_version": "1.0",
+  "extensions": {
+    "jira": {
+      "version": "1.0.0",
+      "source": "catalog",
+      "manifest_hash": "sha256...",
+      "enabled": true,
+      "registered_commands": ["speckit.jira.specstoissues", ...],
+      "installed_at": "2026-01-28T..."
+    }
+  }
+}
+```
+
+### ExtensionManager
+
+**Module**: `specify_cli.extensions`
+
+```python
+from specify_cli.extensions import ExtensionManager
+
+manager = ExtensionManager(project_root)
+```
+
+**Methods**:
+
+```python
+# Install from directory
+manifest = manager.install_from_directory(
+    source_dir: Path,
+    speckit_version: str,
+    register_commands: bool = True
+)  # Returns: ExtensionManifest
+
+# Install from ZIP
+manifest = manager.install_from_zip(
+    zip_path: Path,
+    speckit_version: str
+)  # Returns: ExtensionManifest
+
+# Remove extension
+success = manager.remove(
+    extension_id: str,
+    keep_config: bool = False
+)  # Returns: bool
+
+# List installed extensions
+extensions = manager.list_installed()  # List[Dict]
+
+# Get extension manifest
+manifest = manager.get_extension(extension_id: str)  # Optional[ExtensionManifest]
+
+# Check compatibility
+manager.check_compatibility(
+    manifest: ExtensionManifest,
+    speckit_version: str
+)  # Raises: CompatibilityError if incompatible
+```
+
+### ExtensionCatalog
+
+**Module**: `specify_cli.extensions`
+
+```python
+from specify_cli.extensions import ExtensionCatalog
+
+catalog = ExtensionCatalog(project_root)
+```
+
+**Methods**:
+
+```python
+# Fetch catalog
+catalog_data = catalog.fetch_catalog(force_refresh: bool = False)  # Dict
+
+# Search extensions
+results = catalog.search(
+    query: Optional[str] = None,
+    tag: Optional[str] = None,
+    author: Optional[str] = None,
+    verified_only: bool = False
+)  # Returns: List[Dict]
+
+# Get extension info
+ext_info = catalog.get_extension_info(extension_id: str)  # Optional[Dict]
+
+# Check cache validity
+is_valid = catalog.is_cache_valid()  # bool
+
+# Clear cache
+catalog.clear_cache()
+```
+
+### HookExecutor
+
+**Module**: `specify_cli.extensions`
+
+```python
+from specify_cli.extensions import HookExecutor
+
+hook_executor = HookExecutor(project_root)
+```
+
+**Methods**:
+
+```python
+# Get project config
+config = hook_executor.get_project_config()  # Dict
+
+# Save project config
+hook_executor.save_project_config(config: Dict)
+
+# Register hooks
+hook_executor.register_hooks(manifest: ExtensionManifest)
+
+# Unregister hooks
+hook_executor.unregister_hooks(extension_id: str)
+
+# Get hooks for event
+hooks = hook_executor.get_hooks_for_event(event_name: str)  # List[Dict]
+
+# Check if hook should execute
+should_run = hook_executor.should_execute_hook(hook: Dict)  # bool
+
+# Format hook message
+message = hook_executor.format_hook_message(
+    event_name: str,
+    hooks: List[Dict]
+)  # str
+```
+
+### CommandRegistrar
+
+**Module**: `specify_cli.extensions`
+
+```python
+from specify_cli.extensions import CommandRegistrar
+
+registrar = CommandRegistrar()
+```
+
+**Methods**:
+
+```python
+# Register commands for Claude Code
+registered = registrar.register_commands_for_claude(
+    manifest: ExtensionManifest,
+    extension_dir: Path,
+    project_root: Path
+)  # Returns: List[str] (command names)
+
+# Parse frontmatter
+frontmatter, body = registrar.parse_frontmatter(content: str)
+
+# Render frontmatter
+yaml_text = registrar.render_frontmatter(frontmatter: Dict)  # str
+```
+
+---
+
+## Command File Format
+
+### Universal Command Format
+
+**File**: `commands/{command-name}.md`
+
+```markdown
+---
+description: "Command description"
+tools:
+  - 'mcp-server/tool_name'
+  - 'other-mcp-server/other_tool'
+---
+
+# Command Title
+
+Command documentation in Markdown.
+
+## Prerequisites
+
+1. Requirement 1
+2. Requirement 2
+
+## User Input
+
+$ARGUMENTS
+
+## Steps
+
+### Step 1: Description
+
+Instruction text...
+
+\`\`\`bash
+# Shell commands
+\`\`\`
+
+### Step 2: Another Step
+
+More instructions...
+
+## Configuration Reference
+
+Information about configuration options.
+
+## Notes
+
+Additional notes and tips.
+```
+
+### Frontmatter Fields
+
+```yaml
+description: string   # Required, brief command description
+tools: [string]       # Optional, MCP tools required
+```
+
+### Special Variables
+
+- `$ARGUMENTS` - Placeholder for user-provided arguments
+- Extension context automatically injected:
+
+  ```markdown
+  <!-- Extension: {extension-id} -->
+  <!-- Config: .specify/extensions/{extension-id}/ -->
+  ```
+
+---
+
+## Configuration Schema
+
+### Extension Config File
+
+**File**: `.specify/extensions/{extension-id}/{extension-id}-config.yml`
+
+Extensions define their own config schema. Common patterns:
+
+```yaml
+# Connection settings
+connection:
+  url: string
+  api_key: string
+
+# Project settings
+project:
+  key: string
+  workspace: string
+
+# Feature flags
+features:
+  enabled: boolean
+  auto_sync: boolean
+
+# Defaults
+defaults:
+  labels: [string]
+  assignee: string
+
+# Custom fields
+field_mappings:
+  internal_name: "external_field_id"
+```
+
+### Config Layers
+
+1. **Extension Defaults** (from `extension.yml` `defaults` section)
+2. **Project Config** (`{extension-id}-config.yml`)
+3. **Local Override** (`{extension-id}-config.local.yml`, gitignored)
+4. **Environment Variables** (`SPECKIT_{EXTENSION}_*`)
+
+### Environment Variable Pattern
+
+Format: `SPECKIT_{EXTENSION}_{KEY}`
+
+Examples:
+
+- `SPECKIT_JIRA_PROJECT_KEY`
+- `SPECKIT_LINEAR_API_KEY`
+- `SPECKIT_GITHUB_TOKEN`
+
+---
+
+## Hook System
+
+### Hook Definition
+
+**In extension.yml**:
+
+```yaml
+hooks:
+  after_tasks:
+    command: "speckit.jira.specstoissues"
+    optional: true
+    prompt: "Create Jira issues from tasks?"
+    description: "Automatically create Jira hierarchy"
+    condition: null
+```
+
+### Hook Events
+
+Standard events (defined by core):
+
+- `after_tasks` - After task generation
+- `after_implement` - After implementation
+- `before_commit` - Before git commit
+- `after_commit` - After git commit
+
+### Hook Configuration
+
+**In `.specify/extensions.yml`**:
+
+```yaml
+hooks:
+  after_tasks:
+    - extension: jira
+      command: speckit.jira.specstoissues
+      enabled: true
+      optional: true
+      prompt: "Create Jira issues from tasks?"
+      description: "..."
+      condition: null
+```
+
+### Hook Message Format
+
+```markdown
+## Extension Hooks
+
+**Optional Hook**: {extension}
+Command: `/{command}`
+Description: {description}
+
+Prompt: {prompt}
+To execute: `/{command}`
+```
+
+Or for mandatory hooks:
+
+```markdown
+**Automatic Hook**: {extension}
+Executing: `/{command}`
+EXECUTE_COMMAND: {command}
+```
+
+---
+
+## CLI Commands
+
+### extension list
+
+**Usage**: `specify extension list [OPTIONS]`
+
+**Options**:
+
+- `--available` - Show available extensions from catalog
+- `--all` - Show both installed and available
+
+**Output**: List of installed extensions with metadata
+
+### extension add
+
+**Usage**: `specify extension add EXTENSION [OPTIONS]`
+
+**Options**:
+
+- `--from URL` - Install from custom URL
+- `--dev PATH` - Install from local directory
+- `--version VERSION` - Install specific version
+- `--no-register` - Skip command registration
+
+**Arguments**:
+
+- `EXTENSION` - Extension name or URL
+
+### extension remove
+
+**Usage**: `specify extension remove EXTENSION [OPTIONS]`
+
+**Options**:
+
+- `--keep-config` - Preserve config files
+- `--force` - Skip confirmation
+
+**Arguments**:
+
+- `EXTENSION` - Extension ID
+
+### extension search
+
+**Usage**: `specify extension search [QUERY] [OPTIONS]`
+
+**Options**:
+
+- `--tag TAG` - Filter by tag
+- `--author AUTHOR` - Filter by author
+- `--verified` - Show only verified extensions
+
+**Arguments**:
+
+- `QUERY` - Optional search query
+
+### extension info
+
+**Usage**: `specify extension info EXTENSION`
+
+**Arguments**:
+
+- `EXTENSION` - Extension ID
+
+### extension update
+
+**Usage**: `specify extension update [EXTENSION]`
+
+**Arguments**:
+
+- `EXTENSION` - Optional, extension ID (default: all)
+
+### extension enable
+
+**Usage**: `specify extension enable EXTENSION`
+
+**Arguments**:
+
+- `EXTENSION` - Extension ID
+
+### extension disable
+
+**Usage**: `specify extension disable EXTENSION`
+
+**Arguments**:
+
+- `EXTENSION` - Extension ID
+
+---
+
+## Exceptions
+
+### ValidationError
+
+Raised when extension manifest validation fails.
+
+```python
+from specify_cli.extensions import ValidationError
+
+try:
+    manifest = ExtensionManifest(path)
+except ValidationError as e:
+    print(f"Invalid manifest: {e}")
+```
+
+### CompatibilityError
+
+Raised when extension is incompatible with current spec-kit version.
+
+```python
+from specify_cli.extensions import CompatibilityError
+
+try:
+    manager.check_compatibility(manifest, "0.1.0")
+except CompatibilityError as e:
+    print(f"Incompatible: {e}")
+```
+
+### ExtensionError
+
+Base exception for all extension-related errors.
+
+```python
+from specify_cli.extensions import ExtensionError
+
+try:
+    manager.install_from_directory(path, "0.1.0")
+except ExtensionError as e:
+    print(f"Extension error: {e}")
+```
+
+---
+
+## Version Functions
+
+### version_satisfies
+
+Check if a version satisfies a specifier.
+
+```python
+from specify_cli.extensions import version_satisfies
+
+# True if 1.2.3 satisfies >=1.0.0,<2.0.0
+satisfied = version_satisfies("1.2.3", ">=1.0.0,<2.0.0")  # bool
+```
+
+---
+
+## File System Layout
+
+```text
+.specify/
+├── extensions/
+│   ├── .registry               # Extension registry (JSON)
+│   ├── .cache/                 # Catalog cache
+│   │   ├── catalog.json
+│   │   └── catalog-metadata.json
+│   ├── .backup/                # Config backups
+│   │   └── {ext}-{config}.yml
+│   ├── {extension-id}/         # Extension directory
+│   │   ├── extension.yml       # Manifest
+│   │   ├── {ext}-config.yml    # User config
+│   │   ├── {ext}-config.local.yml  # Local overrides (gitignored)
+│   │   ├── {ext}-config.template.yml  # Template
+│   │   ├── commands/           # Command files
+│   │   │   └── *.md
+│   │   ├── scripts/            # Helper scripts
+│   │   │   └── *.sh
+│   │   ├── docs/               # Documentation
+│   │   └── README.md
+│   └── extensions.yml          # Project extension config
+└── scripts/                    # (existing spec-kit)
+
+.claude/
+└── commands/
+    └── speckit.{ext}.{cmd}.md  # Registered commands
+```
+
+---
+
+*Last Updated: 2026-01-28*
+*API Version: 1.0*
+*Spec Kit Version: 0.1.0*
--- a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
+++ b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
@@ -0,0 +1,649 @@
+# Extension Development Guide
+
+A guide for creating Spec Kit extensions.
+
+---
+
+## Quick Start
+
+### 1. Create Extension Directory
+
+```bash
+mkdir my-extension
+cd my-extension
+```
+
+### 2. Create `extension.yml` Manifest
+
+```yaml
+schema_version: "1.0"
+
+extension:
+  id: "my-ext"                          # Lowercase, alphanumeric + hyphens only
+  name: "My Extension"
+  version: "1.0.0"                      # Semantic versioning
+  description: "My custom extension"
+  author: "Your Name"
+  repository: "https://github.com/you/spec-kit-my-ext"
+  license: "MIT"
+
+requires:
+  speckit_version: ">=0.1.0"            # Minimum spec-kit version
+  tools:                                # Optional: External tools required
+    - name: "my-tool"
+      required: true
+      version: ">=1.0.0"
+  commands:                             # Optional: Core commands needed
+    - "speckit.tasks"
+
+provides:
+  commands:
+    - name: "speckit.my-ext.hello"      # Must follow pattern: speckit.{ext-id}.{cmd}
+      file: "commands/hello.md"
+      description: "Say hello"
+      aliases: ["speckit.hello"]        # Optional aliases
+
+  config:                               # Optional: Config files
+    - name: "my-ext-config.yml"
+      template: "my-ext-config.template.yml"
+      description: "Extension configuration"
+      required: false
+
+hooks:                                  # Optional: Integration hooks
+  after_tasks:
+    command: "speckit.my-ext.hello"
+    optional: true
+    prompt: "Run hello command?"
+
+tags:                                   # Optional: For catalog search
+  - "example"
+  - "utility"
+```
+
+### 3. Create Commands Directory
+
+```bash
+mkdir commands
+```
+
+### 4. Create Command File
+
+**File**: `commands/hello.md`
+
+```markdown
+---
+description: "Say hello command"
+tools:                              # Optional: AI tools this command uses
+  - 'some-tool/function'
+scripts:                            # Optional: Helper scripts
+  sh: ../../scripts/bash/helper.sh
+  ps: ../../scripts/powershell/helper.ps1
+---
+
+# Hello Command
+
+This command says hello!
+
+## User Input
+
+$ARGUMENTS
+
+## Steps
+
+1. Greet the user
+2. Show extension is working
+
+```bash
+echo "Hello from my extension!"
+echo "Arguments: $ARGUMENTS"
+```
+
+## Extension Configuration
+
+Load extension config from `.specify/extensions/my-ext/my-ext-config.yml`.
+
+### 5. Test Locally
+
+```bash
+cd /path/to/spec-kit-project
+specify extension add --dev /path/to/my-extension
+```
+
+### 6. Verify Installation
+
+```bash
+specify extension list
+
+# Should show:
+#  ✓ My Extension (v1.0.0)
+#     My custom extension
+#     Commands: 1 | Hooks: 1 | Status: Enabled
+```
+
+### 7. Test Command
+
+If using Claude:
+
+```bash
+claude
+> /speckit.my-ext.hello world
+```
+
+The command will be available in `.claude/commands/speckit.my-ext.hello.md`.
+
+---
+
+## Manifest Schema Reference
+
+### Required Fields
+
+#### `schema_version`
+
+Extension manifest schema version. Currently: `"1.0"`
+
+#### `extension`
+
+Extension metadata block.
+
+**Required sub-fields**:
+
+- `id`: Extension identifier (lowercase, alphanumeric, hyphens)
+- `name`: Human-readable name
+- `version`: Semantic version (e.g., "1.0.0")
+- `description`: Short description
+
+**Optional sub-fields**:
+
+- `author`: Extension author
+- `repository`: Source code URL
+- `license`: SPDX license identifier
+- `homepage`: Extension homepage URL
+
+#### `requires`
+
+Compatibility requirements.
+
+**Required sub-fields**:
+
+- `speckit_version`: Semantic version specifier (e.g., ">=0.1.0,<2.0.0")
+
+**Optional sub-fields**:
+
+- `tools`: External tools required (array of tool objects)
+- `commands`: Core spec-kit commands needed (array of command names)
+- `scripts`: Core scripts required (array of script names)
+
+#### `provides`
+
+What the extension provides.
+
+**Required sub-fields**:
+
+- `commands`: Array of command objects (must have at least one)
+
+**Command object**:
+
+- `name`: Command name (must match `speckit.{ext-id}.{command}`)
+- `file`: Path to command file (relative to extension root)
+- `description`: Command description (optional)
+- `aliases`: Alternative command names (optional, array)
+
+### Optional Fields
+
+#### `hooks`
+
+Integration hooks for automatic execution.
+
+Available hook points:
+
+- `after_tasks`: After `/speckit.tasks` completes
+- `after_implement`: After `/speckit.implement` completes (future)
+
+Hook object:
+
+- `command`: Command to execute (must be in `provides.commands`)
+- `optional`: If true, prompt user before executing
+- `prompt`: Prompt text for optional hooks
+- `description`: Hook description
+- `condition`: Execution condition (future)
+
+#### `tags`
+
+Array of tags for catalog discovery.
+
+#### `defaults`
+
+Default extension configuration values.
+
+#### `config_schema`
+
+JSON Schema for validating extension configuration.
+
+---
+
+## Command File Format
+
+### Frontmatter (YAML)
+
+```yaml
+---
+description: "Command description"          # Required
+tools:                                      # Optional
+  - 'tool-name/function'
+scripts:                                    # Optional
+  sh: ../../scripts/bash/helper.sh
+  ps: ../../scripts/powershell/helper.ps1
+---
+```
+
+### Body (Markdown)
+
+Use standard Markdown with special placeholders:
+
+- `$ARGUMENTS`: User-provided arguments
+- `{SCRIPT}`: Replaced with script path during registration
+
+**Example**:
+
+````markdown
+## Steps
+
+1. Parse arguments
+2. Execute logic
+
+```bash
+args="$ARGUMENTS"
+echo "Running with args: $args"
+```
+````
+
+### Script Path Rewriting
+
+Extension commands use relative paths that get rewritten during registration:
+
+**In extension**:
+
+```yaml
+scripts:
+  sh: ../../scripts/bash/helper.sh
+```
+
+**After registration**:
+
+```yaml
+scripts:
+  sh: .specify/scripts/bash/helper.sh
+```
+
+This allows scripts to reference core spec-kit scripts.
+
+---
+
+## Configuration Files
+
+### Config Template
+
+**File**: `my-ext-config.template.yml`
+
+```yaml
+# My Extension Configuration
+# Copy this to my-ext-config.yml and customize
+
+# Example configuration
+api:
+  endpoint: "https://api.example.com"
+  timeout: 30
+
+features:
+  feature_a: true
+  feature_b: false
+
+credentials:
+  # DO NOT commit credentials!
+  # Use environment variables instead
+  api_key: "${MY_EXT_API_KEY}"
+```
+
+### Config Loading
+
+In your command, load config with layered precedence:
+
+1. Extension defaults (`extension.yml` → `defaults`)
+2. Project config (`.specify/extensions/my-ext/my-ext-config.yml`)
+3. Local overrides (`.specify/extensions/my-ext/my-ext-config.local.yml` - gitignored)
+4. Environment variables (`SPECKIT_MY_EXT_*`)
+
+**Example loading script**:
+
+```bash
+#!/usr/bin/env bash
+EXT_DIR=".specify/extensions/my-ext"
+
+# Load and merge config
+config=$(yq eval '.' "$EXT_DIR/my-ext-config.yml" -o=json)
+
+# Apply env overrides
+if [ -n "${SPECKIT_MY_EXT_API_KEY:-}" ]; then
+  config=$(echo "$config" | jq ".api.api_key = \"$SPECKIT_MY_EXT_API_KEY\"")
+fi
+
+echo "$config"
+```
+
+---
+
+## Validation Rules
+
+### Extension ID
+
+- **Pattern**: `^[a-z0-9-]+$`
+- **Valid**: `my-ext`, `tool-123`, `awesome-plugin`
+- **Invalid**: `MyExt` (uppercase), `my_ext` (underscore), `my ext` (space)
+
+### Extension Version
+
+- **Format**: Semantic versioning (MAJOR.MINOR.PATCH)
+- **Valid**: `1.0.0`, `0.1.0`, `2.5.3`
+- **Invalid**: `1.0`, `v1.0.0`, `1.0.0-beta`
+
+### Command Name
+
+- **Pattern**: `^speckit\.[a-z0-9-]+\.[a-z0-9-]+$`
+- **Valid**: `speckit.my-ext.hello`, `speckit.tool.cmd`
+- **Invalid**: `my-ext.hello` (missing prefix), `speckit.hello` (no extension namespace)
+
+### Command File Path
+
+- **Must be** relative to extension root
+- **Valid**: `commands/hello.md`, `commands/subdir/cmd.md`
+- **Invalid**: `/absolute/path.md`, `../outside.md`
+
+---
+
+## Testing Extensions
+
+### Manual Testing
+
+1. **Create test extension**
+2. **Install locally**:
+
+   ```bash
+   specify extension add --dev /path/to/extension
+   ```
+
+3. **Verify installation**:
+
+   ```bash
+   specify extension list
+   ```
+
+4. **Test commands** with your AI agent
+5. **Check command registration**:
+
+   ```bash
+   ls .claude/commands/speckit.my-ext.*
+   ```
+
+6. **Remove extension**:
+
+   ```bash
+   specify extension remove my-ext
+   ```
+
+### Automated Testing
+
+Create tests for your extension:
+
+```python
+# tests/test_my_extension.py
+import pytest
+from pathlib import Path
+from specify_cli.extensions import ExtensionManifest
+
+def test_manifest_valid():
+    """Test extension manifest is valid."""
+    manifest = ExtensionManifest(Path("extension.yml"))
+    assert manifest.id == "my-ext"
+    assert len(manifest.commands) >= 1
+
+def test_command_files_exist():
+    """Test all command files exist."""
+    manifest = ExtensionManifest(Path("extension.yml"))
+    for cmd in manifest.commands:
+        cmd_file = Path(cmd["file"])
+        assert cmd_file.exists(), f"Command file not found: {cmd_file}"
+```
+
+---
+
+## Distribution
+
+### Option 1: GitHub Repository
+
+1. **Create repository**: `spec-kit-my-ext`
+2. **Add files**:
+
+   ```text
+   spec-kit-my-ext/
+   ├── extension.yml
+   ├── commands/
+   ├── scripts/
+   ├── docs/
+   ├── README.md
+   ├── LICENSE
+   └── CHANGELOG.md
+   ```
+
+3. **Create release**: Tag with version (e.g., `v1.0.0`)
+4. **Install from repo**:
+
+   ```bash
+   git clone https://github.com/you/spec-kit-my-ext
+   specify extension add --dev spec-kit-my-ext/
+   ```
+
+### Option 2: ZIP Archive (Future)
+
+Create ZIP archive and host on GitHub Releases:
+
+```bash
+zip -r spec-kit-my-ext-1.0.0.zip extension.yml commands/ scripts/ docs/
+```
+
+Users install with:
+
+```bash
+specify extension add --from https://github.com/.../spec-kit-my-ext-1.0.0.zip
+```
+
+### Option 3: Extension Catalog (Future)
+
+Submit to official catalog:
+
+1. **Fork** spec-kit repository
+2. **Add entry** to `extensions/catalog.json`
+3. **Create PR**
+4. **After merge**, users can install with:
+
+   ```bash
+   specify extension add my-ext  # No URL needed!
+   ```
+
+---
+
+## Best Practices
+
+### Naming Conventions
+
+- **Extension ID**: Use descriptive, hyphenated names (`jira-integration`, not `ji`)
+- **Commands**: Use verb-noun pattern (`create-issue`, `sync-status`)
+- **Config files**: Match extension ID (`jira-config.yml`)
+
+### Documentation
+
+- **README.md**: Overview, installation, usage
+- **CHANGELOG.md**: Version history
+- **docs/**: Detailed guides
+- **Command descriptions**: Clear, concise
+
+### Versioning
+
+- **Follow SemVer**: `MAJOR.MINOR.PATCH`
+- **MAJOR**: Breaking changes
+- **MINOR**: New features
+- **PATCH**: Bug fixes
+
+### Security
+
+- **Never commit secrets**: Use environment variables
+- **Validate input**: Sanitize user arguments
+- **Document permissions**: What files/APIs are accessed
+
+### Compatibility
+
+- **Specify version range**: Don't require exact version
+- **Test with multiple versions**: Ensure compatibility
+- **Graceful degradation**: Handle missing features
+
+---
+
+## Example Extensions
+
+### Minimal Extension
+
+Smallest possible extension:
+
+```yaml
+# extension.yml
+schema_version: "1.0"
+extension:
+  id: "minimal"
+  name: "Minimal Extension"
+  version: "1.0.0"
+  description: "Minimal example"
+requires:
+  speckit_version: ">=0.1.0"
+provides:
+  commands:
+    - name: "speckit.minimal.hello"
+      file: "commands/hello.md"
+```
+
+````markdown
+<!-- commands/hello.md -->
+---
+description: "Hello command"
+---
+
+# Hello World
+
+```bash
+echo "Hello, $ARGUMENTS!"
+```
+````
+
+### Extension with Config
+
+Extension using configuration:
+
+```yaml
+# extension.yml
+# ... metadata ...
+provides:
+  config:
+    - name: "tool-config.yml"
+      template: "tool-config.template.yml"
+      required: true
+```
+
+```yaml
+# tool-config.template.yml
+api_endpoint: "https://api.example.com"
+timeout: 30
+```
+
+````markdown
+<!-- commands/use-config.md -->
+# Use Config
+
+Load config:
+```bash
+config_file=".specify/extensions/tool/tool-config.yml"
+endpoint=$(yq eval '.api_endpoint' "$config_file")
+echo "Using endpoint: $endpoint"
+```
+````
+
+### Extension with Hooks
+
+Extension that runs automatically:
+
+```yaml
+# extension.yml
+hooks:
+  after_tasks:
+    command: "speckit.auto.analyze"
+    optional: false  # Always run
+    description: "Analyze tasks after generation"
+```
+
+---
+
+## Troubleshooting
+
+### Extension won't install
+
+**Error**: `Invalid extension ID`
+
+- **Fix**: Use lowercase, alphanumeric + hyphens only
+
+**Error**: `Extension requires spec-kit >=0.2.0`
+
+- **Fix**: Update spec-kit with `uv tool install specify-cli --force`
+
+**Error**: `Command file not found`
+
+- **Fix**: Ensure command files exist at paths specified in manifest
+
+### Commands not registered
+
+**Symptom**: Commands don't appear in AI agent
+
+**Check**:
+
+1. `.claude/commands/` directory exists
+2. Extension installed successfully
+3. Commands registered in registry:
+
+   ```bash
+   cat .specify/extensions/.registry
+   ```
+
+**Fix**: Reinstall extension to trigger registration
+
+### Config not loading
+
+**Check**:
+
+1. Config file exists: `.specify/extensions/{ext-id}/{ext-id}-config.yml`
+2. YAML syntax is valid: `yq eval '.' config.yml`
+3. Environment variables set correctly
+
+---
+
+## Getting Help
+
+- **Issues**: Report bugs at GitHub repository
+- **Discussions**: Ask questions in GitHub Discussions
+- **Examples**: See `spec-kit-jira` for full-featured example (Phase B)
+
+---
+
+## Next Steps
+
+1. **Create your extension** following this guide
+2. **Test locally** with `--dev` flag
+3. **Share with community** (GitHub, catalog)
+4. **Iterate** based on feedback
+
+Happy extending! 🚀
--- a/extensions/EXTENSION-PUBLISHING-GUIDE.md
+++ b/extensions/EXTENSION-PUBLISHING-GUIDE.md
@@ -0,0 +1,530 @@
+# Extension Publishing Guide
+
+This guide explains how to publish your extension to the Spec Kit extension catalog, making it discoverable by `specify extension search`.
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Prepare Your Extension](#prepare-your-extension)
+3. [Submit to Catalog](#submit-to-catalog)
+4. [Verification Process](#verification-process)
+5. [Release Workflow](#release-workflow)
+6. [Best Practices](#best-practices)
+
+---
+
+## Prerequisites
+
+Before publishing an extension, ensure you have:
+
+1. **Valid Extension**: A working extension with a valid `extension.yml` manifest
+2. **Git Repository**: Extension hosted on GitHub (or other public git hosting)
+3. **Documentation**: README.md with installation and usage instructions
+4. **License**: Open source license file (MIT, Apache 2.0, etc.)
+5. **Versioning**: Semantic versioning (e.g., 1.0.0)
+6. **Testing**: Extension tested on real projects
+
+---
+
+## Prepare Your Extension
+
+### 1. Extension Structure
+
+Ensure your extension follows the standard structure:
+
+```text
+your-extension/
+├── extension.yml              # Required: Extension manifest
+├── README.md                  # Required: Documentation
+├── LICENSE                    # Required: License file
+├── CHANGELOG.md               # Recommended: Version history
+├── .gitignore                 # Recommended: Git ignore rules
+│
+├── commands/                  # Extension commands
+│   ├── command1.md
+│   └── command2.md
+│
+├── config-template.yml        # Config template (if needed)
+│
+└── docs/                      # Additional documentation
+    ├── usage.md
+    └── examples/
+```
+
+### 2. extension.yml Validation
+
+Verify your manifest is valid:
+
+```yaml
+schema_version: "1.0"
+
+extension:
+  id: "your-extension"           # Unique lowercase-hyphenated ID
+  name: "Your Extension Name"     # Human-readable name
+  version: "1.0.0"                # Semantic version
+  description: "Brief description (one sentence)"
+  author: "Your Name or Organization"
+  repository: "https://github.com/your-org/spec-kit-your-extension"
+  license: "MIT"
+  homepage: "https://github.com/your-org/spec-kit-your-extension"
+
+requires:
+  speckit_version: ">=0.1.0"    # Required spec-kit version
+
+provides:
+  commands:                       # List all commands
+    - name: "speckit.your-extension.command"
+      file: "commands/command.md"
+      description: "Command description"
+
+tags:                             # 2-5 relevant tags
+  - "category"
+  - "tool-name"
+```
+
+**Validation Checklist**:
+
+- ✅ `id` is lowercase with hyphens only (no underscores, spaces, or special characters)
+- ✅ `version` follows semantic versioning (X.Y.Z)
+- ✅ `description` is concise (under 100 characters)
+- ✅ `repository` URL is valid and public
+- ✅ All command files exist in the extension directory
+- ✅ Tags are lowercase and descriptive
+
+### 3. Create GitHub Release
+
+Create a GitHub release for your extension version:
+
+```bash
+# Tag the release
+git tag v1.0.0
+git push origin v1.0.0
+
+# Create release on GitHub
+# Go to: https://github.com/your-org/spec-kit-your-extension/releases/new
+# - Tag: v1.0.0
+# - Title: v1.0.0 - Release Name
+# - Description: Changelog/release notes
+```
+
+The release archive URL will be:
+
+```text
+https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip
+```
+
+### 4. Test Installation
+
+Test that users can install from your release:
+
+```bash
+# Test dev installation
+specify extension add --dev /path/to/your-extension
+
+# Test from GitHub archive
+specify extension add --from https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip
+```
+
+---
+
+## Submit to Catalog
+
+### 1. Fork the spec-kit Repository
+
+```bash
+# Fork on GitHub
+# https://github.com/statsperform/spec-kit/fork
+
+# Clone your fork
+git clone https://github.com/YOUR-USERNAME/spec-kit.git
+cd spec-kit
+```
+
+### 2. Add Extension to Catalog
+
+Edit `extensions/catalog.json` and add your extension:
+
+```json
+{
+  "schema_version": "1.0",
+  "updated_at": "2026-01-28T15:54:00Z",
+  "catalog_url": "https://raw.githubusercontent.com/statsperform/spec-kit/main/extensions/catalog.json",
+  "extensions": {
+    "your-extension": {
+      "name": "Your Extension Name",
+      "id": "your-extension",
+      "description": "Brief description of your extension",
+      "author": "Your Name",
+      "version": "1.0.0",
+      "download_url": "https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/your-org/spec-kit-your-extension",
+      "homepage": "https://github.com/your-org/spec-kit-your-extension",
+      "documentation": "https://github.com/your-org/spec-kit-your-extension/blob/main/docs/",
+      "changelog": "https://github.com/your-org/spec-kit-your-extension/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0",
+        "tools": [
+          {
+            "name": "required-mcp-tool",
+            "version": ">=1.0.0",
+            "required": true
+          }
+        ]
+      },
+      "provides": {
+        "commands": 3,
+        "hooks": 1
+      },
+      "tags": [
+        "category",
+        "tool-name",
+        "feature"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-01-28T00:00:00Z",
+      "updated_at": "2026-01-28T00:00:00Z"
+    }
+  }
+}
+```
+
+**Important**:
+
+- Set `verified: false` (maintainers will verify)
+- Set `downloads: 0` and `stars: 0` (auto-updated later)
+- Use current timestamp for `created_at` and `updated_at`
+- Update the top-level `updated_at` to current time
+
+### 3. Submit Pull Request
+
+```bash
+# Create a branch
+git checkout -b add-your-extension
+
+# Commit your changes
+git add extensions/catalog.json
+git commit -m "Add your-extension to catalog
+
+- Extension ID: your-extension
+- Version: 1.0.0
+- Author: Your Name
+- Description: Brief description
+"
+
+# Push to your fork
+git push origin add-your-extension
+
+# Create Pull Request on GitHub
+# https://github.com/statsperform/spec-kit/compare
+```
+
+**Pull Request Template**:
+
+```markdown
+## Extension Submission
+
+**Extension Name**: Your Extension Name
+**Extension ID**: your-extension
+**Version**: 1.0.0
+**Author**: Your Name
+**Repository**: https://github.com/your-org/spec-kit-your-extension
+
+### Description
+Brief description of what your extension does.
+
+### Checklist
+- [x] Valid extension.yml manifest
+- [x] README.md with installation and usage docs
+- [x] LICENSE file included
+- [x] GitHub release created (v1.0.0)
+- [x] Extension tested on real project
+- [x] All commands working
+- [x] No security vulnerabilities
+
+### Testing
+Tested on:
+- macOS 13.0+ with spec-kit 0.1.0
+- Project: [Your test project]
+
+### Additional Notes
+Any additional context or notes for reviewers.
+```
+
+---
+
+## Verification Process
+
+### What Happens After Submission
+
+1. **Automated Checks** (if available):
+   - Manifest validation
+   - Download URL accessibility
+   - Repository existence
+   - License file presence
+
+2. **Manual Review**:
+   - Code quality review
+   - Security audit
+   - Functionality testing
+   - Documentation review
+
+3. **Verification**:
+   - If approved, `verified: true` is set
+   - Extension appears in `specify extension search --verified`
+
+### Verification Criteria
+
+To be verified, your extension must:
+
+✅ **Functionality**:
+
+- Works as described in documentation
+- All commands execute without errors
+- No breaking changes to user workflows
+
+✅ **Security**:
+
+- No known vulnerabilities
+- No malicious code
+- Safe handling of user data
+- Proper validation of inputs
+
+✅ **Code Quality**:
+
+- Clean, readable code
+- Follows extension best practices
+- Proper error handling
+- Helpful error messages
+
+✅ **Documentation**:
+
+- Clear installation instructions
+- Usage examples
+- Troubleshooting section
+- Accurate description
+
+✅ **Maintenance**:
+
+- Active repository
+- Responsive to issues
+- Regular updates
+- Semantic versioning followed
+
+### Typical Review Timeline
+
+- **Automated checks**: Immediate (if implemented)
+- **Manual review**: 3-7 business days
+- **Verification**: After successful review
+
+---
+
+## Release Workflow
+
+### Publishing New Versions
+
+When releasing a new version:
+
+1. **Update version** in `extension.yml`:
+
+   ```yaml
+   extension:
+     version: "1.1.0"  # Updated version
+   ```
+
+2. **Update CHANGELOG.md**:
+
+   ```markdown
+   ## [1.1.0] - 2026-02-15
+
+   ### Added
+   - New feature X
+
+   ### Fixed
+   - Bug fix Y
+   ```
+
+3. **Create GitHub release**:
+
+   ```bash
+   git tag v1.1.0
+   git push origin v1.1.0
+   # Create release on GitHub
+   ```
+
+4. **Update catalog**:
+
+   ```bash
+   # Fork spec-kit repo (or update existing fork)
+   cd spec-kit
+
+   # Update extensions/catalog.json
+   jq '.extensions["your-extension"].version = "1.1.0"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json
+   jq '.extensions["your-extension"].download_url = "https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.1.0.zip"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json
+   jq '.extensions["your-extension"].updated_at = "2026-02-15T00:00:00Z"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json
+   jq '.updated_at = "2026-02-15T00:00:00Z"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json
+
+   # Submit PR
+   git checkout -b update-your-extension-v1.1.0
+   git add extensions/catalog.json
+   git commit -m "Update your-extension to v1.1.0"
+   git push origin update-your-extension-v1.1.0
+   ```
+
+5. **Submit update PR** with changelog in description
+
+---
+
+## Best Practices
+
+### Extension Design
+
+1. **Single Responsibility**: Each extension should focus on one tool/integration
+2. **Clear Naming**: Use descriptive, unambiguous names
+3. **Minimal Dependencies**: Avoid unnecessary dependencies
+4. **Backward Compatibility**: Follow semantic versioning strictly
+
+### Documentation
+
+1. **README.md Structure**:
+   - Overview and features
+   - Installation instructions
+   - Configuration guide
+   - Usage examples
+   - Troubleshooting
+   - Contributing guidelines
+
+2. **Command Documentation**:
+   - Clear description
+   - Prerequisites listed
+   - Step-by-step instructions
+   - Error handling guidance
+   - Examples
+
+3. **Configuration**:
+   - Provide template file
+   - Document all options
+   - Include examples
+   - Explain defaults
+
+### Security
+
+1. **Input Validation**: Validate all user inputs
+2. **No Hardcoded Secrets**: Never include credentials
+3. **Safe Dependencies**: Only use trusted dependencies
+4. **Audit Regularly**: Check for vulnerabilities
+
+### Maintenance
+
+1. **Respond to Issues**: Address issues within 1-2 weeks
+2. **Regular Updates**: Keep dependencies updated
+3. **Changelog**: Maintain detailed changelog
+4. **Deprecation**: Give advance notice for breaking changes
+
+### Community
+
+1. **License**: Use permissive open-source license (MIT, Apache 2.0)
+2. **Contributing**: Welcome contributions
+3. **Code of Conduct**: Be respectful and inclusive
+4. **Support**: Provide ways to get help (issues, discussions, email)
+
+---
+
+## FAQ
+
+### Q: Can I publish private/proprietary extensions?
+
+A: The main catalog is for public extensions only. For private extensions:
+
+- Host your own catalog.json file
+- Users add your catalog: `specify extension add-catalog https://your-domain.com/catalog.json`
+- Not yet implemented - coming in Phase 4
+
+### Q: How long does verification take?
+
+A: Typically 3-7 business days for initial review. Updates to verified extensions are usually faster.
+
+### Q: What if my extension is rejected?
+
+A: You'll receive feedback on what needs to be fixed. Make the changes and resubmit.
+
+### Q: Can I update my extension anytime?
+
+A: Yes, submit a PR to update the catalog with your new version. Verified status may be re-evaluated for major changes.
+
+### Q: Do I need to be verified to be in the catalog?
+
+A: No, unverified extensions are still searchable. Verification just adds trust and visibility.
+
+### Q: Can extensions have paid features?
+
+A: Extensions should be free and open-source. Commercial support/services are allowed, but core functionality must be free.
+
+---
+
+## Support
+
+- **Catalog Issues**: <https://github.com/statsperform/spec-kit/issues>
+- **Extension Template**: <https://github.com/statsperform/spec-kit-extension-template> (coming soon)
+- **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md
+- **Community**: Discussions and Q&A
+
+---
+
+## Appendix: Catalog Schema
+
+### Complete Catalog Entry Schema
+
+```json
+{
+  "name": "string (required)",
+  "id": "string (required, unique)",
+  "description": "string (required, <200 chars)",
+  "author": "string (required)",
+  "version": "string (required, semver)",
+  "download_url": "string (required, valid URL)",
+  "repository": "string (required, valid URL)",
+  "homepage": "string (optional, valid URL)",
+  "documentation": "string (optional, valid URL)",
+  "changelog": "string (optional, valid URL)",
+  "license": "string (required)",
+  "requires": {
+    "speckit_version": "string (required, version specifier)",
+    "tools": [
+      {
+        "name": "string (required)",
+        "version": "string (optional, version specifier)",
+        "required": "boolean (default: false)"
+      }
+    ]
+  },
+  "provides": {
+    "commands": "integer (optional)",
+    "hooks": "integer (optional)"
+  },
+  "tags": ["array of strings (2-10 tags)"],
+  "verified": "boolean (default: false)",
+  "downloads": "integer (auto-updated)",
+  "stars": "integer (auto-updated)",
+  "created_at": "string (ISO 8601 datetime)",
+  "updated_at": "string (ISO 8601 datetime)"
+}
+```
+
+### Valid Tags
+
+Recommended tag categories:
+
+- **Integration**: jira, linear, github, gitlab, azure-devops
+- **Category**: issue-tracking, vcs, ci-cd, documentation, testing
+- **Platform**: atlassian, microsoft, google
+- **Feature**: automation, reporting, deployment, monitoring
+
+Use 2-5 tags that best describe your extension.
+
+---
+
+*Last Updated: 2026-01-28*
+*Catalog Format Version: 1.0*
--- a/extensions/EXTENSION-USER-GUIDE.md
+++ b/extensions/EXTENSION-USER-GUIDE.md
@@ -0,0 +1,885 @@
+# Extension User Guide
+
+Complete guide for using Spec Kit extensions to enhance your workflow.
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Getting Started](#getting-started)
+3. [Finding Extensions](#finding-extensions)
+4. [Installing Extensions](#installing-extensions)
+5. [Using Extensions](#using-extensions)
+6. [Managing Extensions](#managing-extensions)
+7. [Configuration](#configuration)
+8. [Troubleshooting](#troubleshooting)
+9. [Best Practices](#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
+
+```bash
+specify --version
+# Should show 0.1.0 or higher
+```
+
+### First Extension
+
+Let's install the Jira extension as an example:
+
+```bash
+# 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
+
+```bash
+specify extension search
+```
+
+Shows all available extensions in the catalog.
+
+### Search by Keyword
+
+```bash
+# Search for "jira"
+specify extension search jira
+
+# Search for "issue tracking"
+specify extension search issue
+```
+
+### Filter by Tag
+
+```bash
+# Find all issue-tracking extensions
+specify extension search --tag issue-tracking
+
+# Find all Atlassian tools
+specify extension search --tag atlassian
+```
+
+### Filter by Author
+
+```bash
+# Extensions by Stats Perform
+specify extension search --author "Stats Perform"
+```
+
+### Show Verified Only
+
+```bash
+# Only show verified extensions
+specify extension search --verified
+```
+
+### Get Extension Details
+
+```bash
+# Detailed information
+specify extension info jira
+```
+
+Shows:
+
+- Description
+- Requirements
+- Commands provided
+- Hooks available
+- Links (documentation, repository, changelog)
+- Installation status
+
+---
+
+## Installing Extensions
+
+### Install from Catalog
+
+```bash
+# 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
+
+```bash
+# 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)
+
+```bash
+# For testing or development
+specify extension add --dev /path/to/extension
+```
+
+### Installation Output
+
+```text
+✓ 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):
+
+```text
+# In Claude Code
+> /speckit.jira.specstoissues
+
+# Or use short alias (if provided)
+> /speckit.specstoissues
+```
+
+### Extension Configuration
+
+Most extensions require configuration:
+
+```bash
+# 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`
+
+```text
+# 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
+
+```bash
+specify extension list
+```
+
+Output:
+
+```text
+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
+
+```bash
+# Check for updates (all extensions)
+specify extension update
+
+# Update specific extension
+specify extension update jira
+```
+
+Output:
+
+```text
+🔄 Checking for updates...
+
+Updates available:
+
+  • jira: 1.0.0 → 1.1.0
+
+Update these extensions? [y/N]:
+```
+
+### Disable Extension Temporarily
+
+```bash
+# 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
+
+```bash
+specify extension enable jira
+
+✓ Extension 'jira' enabled
+```
+
+### Remove Extension
+
+```bash
+# 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:
+
+```text
+.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`):
+
+```yaml
+project:
+  key: "MSATS"
+
+defaults:
+  epic:
+    labels: ["spec-driven"]
+```
+
+**Local override** (`.specify/extensions/jira/jira-config.local.yml`):
+
+```yaml
+project:
+  key: "MYTEST"  # Override for local development
+```
+
+**Environment variable**:
+
+```bash
+export SPECKIT_JIRA_PROJECT_KEY="DEVTEST"
+```
+
+Final resolved config uses `DEVTEST` from environment variable.
+
+### Project-Wide Extension Settings
+
+File: `.specify/extensions.yml`
+
+```yaml
+# 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
+
+```bash
+# 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:
+
+```json
+{
+  "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)
+
+```bash
+# 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:
+
+```bash
+SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json" specify extension search
+```
+
+#### 4. Verify Configuration
+
+```bash
+# 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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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
+
+```json
+{
+  "jira": {
+    "download_url": "https://files.internal/spec-kit/jira-2.1.0.zip"
+  }
+}
+```
+
+#### Development/Testing
+
+Test new extensions before publishing:
+
+```bash
+# 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`:
+
+```bash
+# 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:
+
+   ```bash
+   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:
+
+   ```bash
+   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:
+
+   ```bash
+   uv tool upgrade specify-cli
+   ```
+
+2. Install older version of extension:
+
+   ```bash
+   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`:
+
+```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**:
+
+```markdown
+## 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:
+
+```yaml
+# .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:
+
+```bash
+# .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**:
+
+```bash
+# Weekly or before major releases
+specify extension update
+```
+
+**Pin versions for stability**:
+
+```yaml
+# .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:
+
+```markdown
+# 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*
--- a/extensions/RFC-EXTENSION-SYSTEM.md
+++ b/extensions/RFC-EXTENSION-SYSTEM.md
--- a/extensions/catalog.example.json
+++ b/extensions/catalog.example.json
@@ -0,0 +1,60 @@
+{
+  "schema_version": "1.0",
+  "updated_at": "2026-02-03T00:00:00Z",
+  "catalog_url": "https://your-org.example.com/speckit/catalog.json",
+  "extensions": {
+    "jira": {
+      "name": "Jira Integration",
+      "id": "jira",
+      "description": "Create Jira Epics, Stories, and 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",
+      "homepage": "https://github.com/your-org/spec-kit-jira",
+      "documentation": "https://github.com/your-org/spec-kit-jira/blob/main/README.md",
+      "changelog": "https://github.com/your-org/spec-kit-jira/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0",
+        "tools": [
+          {
+            "name": "atlassian",
+            "version": ">=1.0.0",
+            "required": true
+          }
+        ]
+      },
+      "provides": {
+        "commands": 3,
+        "hooks": 1
+      },
+      "tags": ["jira", "atlassian", "issue-tracking"],
+      "verified": true,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-01-28T00:00:00Z",
+      "updated_at": "2026-02-03T00:00:00Z"
+    },
+    "linear": {
+      "name": "Linear Integration",
+      "id": "linear",
+      "description": "Sync specs and tasks with Linear issues",
+      "author": "Your Organization",
+      "version": "1.0.0",
+      "download_url": "https://github.com/your-org/spec-kit-linear/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/your-org/spec-kit-linear",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 2
+      },
+      "tags": ["linear", "issue-tracking"],
+      "verified": false,
+      "created_at": "2026-01-30T00:00:00Z",
+      "updated_at": "2026-01-30T00:00:00Z"
+    }
+  }
+}
--- a/extensions/catalog.json
+++ b/extensions/catalog.json
@@ -0,0 +1,6 @@
+{
+  "schema_version": "1.0",
+  "updated_at": "2026-02-03T00:00:00Z",
+  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json",
+  "extensions": {}
+}
--- a/extensions/template/.gitignore
+++ b/extensions/template/.gitignore
@@ -0,0 +1,39 @@
+# Local configuration overrides
+*-config.local.yml
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Temporary files
+*.tmp
+.cache/
--- a/extensions/template/CHANGELOG.md
+++ b/extensions/template/CHANGELOG.md
@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this extension will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to  [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned
+
+- Feature ideas for future versions
+- Enhancements
+- Bug fixes
+
+## [1.0.0] - YYYY-MM-DD
+
+### Added
+
+- Initial release of extension
+- Command: `/speckit.my-extension.example` - Example command functionality
+- Configuration system with template
+- Documentation and examples
+
+### Features
+
+- Feature 1 description
+- Feature 2 description
+- Feature 3 description
+
+### Requirements
+
+- Spec Kit: >=0.1.0
+- External dependencies (if any)
+
+---
+
+[Unreleased]: https://github.com/your-org/spec-kit-my-extension/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/your-org/spec-kit-my-extension/releases/tag/v1.0.0
--- a/extensions/template/EXAMPLE-README.md
+++ b/extensions/template/EXAMPLE-README.md
@@ -0,0 +1,158 @@
+# EXAMPLE: Extension README
+
+This is an example of what your extension README should look like after customization.
+**Delete this file and replace README.md with content similar to this.**
+
+---
+
+# My Extension
+
+<!-- CUSTOMIZE: Replace with your extension description -->
+
+Brief description of what your extension does and why it's useful.
+
+## Features
+
+<!-- CUSTOMIZE: List key features -->
+
+- Feature 1: Description
+- Feature 2: Description
+- Feature 3: Description
+
+## Installation
+
+```bash
+# Install from catalog
+specify extension add my-extension
+
+# Or install from local development directory
+specify extension add --dev /path/to/my-extension
+```
+
+## Configuration
+
+1. Create configuration file:
+
+   ```bash
+   cp .specify/extensions/my-extension/config-template.yml \
+      .specify/extensions/my-extension/my-extension-config.yml
+   ```
+
+2. Edit configuration:
+
+   ```bash
+   vim .specify/extensions/my-extension/my-extension-config.yml
+   ```
+
+3. Set required values:
+   <!-- CUSTOMIZE: List required configuration -->
+   ```yaml
+   connection:
+     url: "https://api.example.com"
+     api_key: "your-api-key"
+
+   project:
+     id: "your-project-id"
+   ```
+
+## Usage
+
+<!-- CUSTOMIZE: Add usage examples -->
+
+### Command: example
+
+Description of what this command does.
+
+```bash
+# In Claude Code
+> /speckit.my-extension.example
+```
+
+**Prerequisites**:
+
+- Prerequisite 1
+- Prerequisite 2
+
+**Output**:
+
+- What this command produces
+- Where results are saved
+
+## Configuration Reference
+
+<!-- CUSTOMIZE: Document all configuration options -->
+
+### Connection Settings
+
+| Setting | Type | Required | Description |
+|---------|------|----------|-------------|
+| `connection.url` | string | Yes | API endpoint URL |
+| `connection.api_key` | string | Yes | API authentication key |
+
+### Project Settings
+
+| Setting | Type | Required | Description |
+|---------|------|----------|-------------|
+| `project.id` | string | Yes | Project identifier |
+| `project.workspace` | string | No | Workspace or organization |
+
+## Environment Variables
+
+Override configuration with environment variables:
+
+```bash
+# Override connection settings
+export SPECKIT_MY_EXTENSION_CONNECTION_URL="https://custom-api.com"
+export SPECKIT_MY_EXTENSION_CONNECTION_API_KEY="custom-key"
+```
+
+## Examples
+
+<!-- CUSTOMIZE: Add real-world examples -->
+
+### Example 1: Basic Workflow
+
+```bash
+# Step 1: Create specification
+> /speckit.spec
+
+# Step 2: Generate tasks
+> /speckit.tasks
+
+# Step 3: Use extension
+> /speckit.my-extension.example
+```
+
+## Troubleshooting
+
+<!-- CUSTOMIZE: Add common issues -->
+
+### Issue: Configuration not found
+
+**Solution**: Create config from template (see Configuration section)
+
+### Issue: Command not available
+
+**Solutions**:
+
+1. Check extension is installed: `specify extension list`
+2. Restart AI agent
+3. Reinstall extension
+
+## License
+
+MIT License - see LICENSE file
+
+## Support
+
+- **Issues**: <https://github.com/your-org/spec-kit-my-extension/issues>
+- **Spec Kit Docs**: <https://github.com/statsperform/spec-kit>
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+---
+
+*Extension Version: 1.0.0*
+*Spec Kit: >=0.1.0*
--- a/extensions/template/LICENSE
+++ b/extensions/template/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Your Name or Organization]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/extensions/template/README.md
+++ b/extensions/template/README.md
@@ -0,0 +1,79 @@
+# Extension Template
+
+Starter template for creating a Spec Kit extension.
+
+## Quick Start
+
+1. **Copy this template**:
+
+   ```bash
+   cp -r extensions/template my-extension
+   cd my-extension
+   ```
+
+2. **Customize `extension.yml`**:
+   - Change extension ID, name, description
+   - Update author and repository
+   - Define your commands
+
+3. **Create commands**:
+   - Add command files in `commands/` directory
+   - Use Markdown format with YAML frontmatter
+
+4. **Create config template**:
+   - Define configuration options
+   - Document all settings
+
+5. **Write documentation**:
+   - Update README.md with usage instructions
+   - Add examples
+
+6. **Test locally**:
+
+   ```bash
+   cd /path/to/spec-kit-project
+   specify extension add --dev /path/to/my-extension
+   ```
+
+7. **Publish** (optional):
+   - Create GitHub repository
+   - Create release
+   - Submit to catalog (see EXTENSION-PUBLISHING-GUIDE.md)
+
+## Files in This Template
+
+- `extension.yml` - Extension manifest (CUSTOMIZE THIS)
+- `config-template.yml` - Configuration template (CUSTOMIZE THIS)
+- `commands/example.md` - Example command (REPLACE THIS)
+- `README.md` - Extension documentation (REPLACE THIS)
+- `LICENSE` - MIT License (REVIEW THIS)
+- `CHANGELOG.md` - Version history (UPDATE THIS)
+- `.gitignore` - Git ignore rules
+
+## Customization Checklist
+
+- [ ] Update `extension.yml` with your extension details
+- [ ] Change extension ID to your extension name
+- [ ] Update author information
+- [ ] Define your commands
+- [ ] Create command files in `commands/`
+- [ ] Update config template
+- [ ] Write README with usage instructions
+- [ ] Add examples
+- [ ] Update LICENSE if needed
+- [ ] Test extension locally
+- [ ] Create git repository
+- [ ] Create first release
+
+## Need Help?
+
+- **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md
+- **API Reference**: See EXTENSION-API-REFERENCE.md
+- **Publishing Guide**: See EXTENSION-PUBLISHING-GUIDE.md
+- **User Guide**: See EXTENSION-USER-GUIDE.md
+
+## Template Version
+
+- Version: 1.0.0
+- Last Updated: 2026-01-28
+- Compatible with Spec Kit: >=0.1.0
--- a/extensions/template/commands/example.md
+++ b/extensions/template/commands/example.md
@@ -0,0 +1,210 @@
+---
+description: "Example command that demonstrates extension functionality"
+# CUSTOMIZE: List MCP tools this command uses
+tools:
+  - 'example-mcp-server/example_tool'
+---
+
+# Example Command
+
+<!-- CUSTOMIZE: Replace this entire file with your command documentation -->
+
+This is an example command that demonstrates how to create commands for Spec Kit extensions.
+
+## Purpose
+
+Describe what this command does and when to use it.
+
+## Prerequisites
+
+List requirements before using this command:
+
+1. Prerequisite 1 (e.g., "MCP server configured")
+2. Prerequisite 2 (e.g., "Configuration file exists")
+3. Prerequisite 3 (e.g., "Valid API credentials")
+
+## User Input
+
+$ARGUMENTS
+
+## Steps
+
+### Step 1: Load Configuration
+
+<!-- CUSTOMIZE: Replace with your actual steps -->
+
+Load extension configuration from the project:
+
+``bash
+config_file=".specify/extensions/my-extension/my-extension-config.yml"
+
+if [ ! -f "$config_file" ]; then
+  echo "❌ Error: Configuration not found at $config_file"
+  echo "Run 'specify extension add my-extension' to install and configure"
+  exit 1
+fi
+
+# Read configuration values
+
+setting_value=$(yq eval '.settings.key' "$config_file")
+
+# Apply environment variable overrides
+
+setting_value="${SPECKIT_MY_EXTENSION_KEY:-$setting_value}"
+
+# Validate configuration
+
+if [ -z "$setting_value" ]; then
+  echo "❌ Error: Configuration value not set"
+  echo "Edit $config_file and set 'settings.key'"
+  exit 1
+fi
+
+echo "📋 Configuration loaded: $setting_value"
+``
+
+### Step 2: Perform Main Action
+
+<!-- CUSTOMIZE: Replace with your command logic -->
+
+Describe what this step does:
+
+``markdown
+Use MCP tools to perform the main action:
+
+- Tool: example-mcp-server example_tool
+- Parameters: { "key": "$setting_value" }
+
+This calls the MCP server tool to execute the operation.
+``
+
+### Step 3: Process Results
+
+<!-- CUSTOMIZE: Add more steps as needed -->
+
+Process the results and provide output:
+
+`` bash
+echo ""
+echo "✅ Command completed successfully!"
+echo ""
+echo "Results:"
+echo "  • Item 1: Value"
+echo "  • Item 2: Value"
+echo ""
+``
+
+### Step 4: Save Output (Optional)
+
+Save results to a file if needed:
+
+``bash
+output_file=".specify/my-extension-output.json"
+
+cat > "$output_file" <<EOF
+{
+  "timestamp": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
+  "setting": "$setting_value",
+  "results": []
+}
+EOF
+
+echo "💾 Output saved to $output_file"
+``
+
+## Configuration Reference
+
+<!-- CUSTOMIZE: Document configuration options -->
+
+This command uses the following configuration from `my-extension-config.yml`:
+
+- **settings.key**: Description of what this setting does
+  - Type: string
+  - Required: Yes
+  - Example: `"example-value"`
+
+- **settings.another_key**: Description of another setting
+  - Type: boolean
+  - Required: No
+  - Default: `false`
+  - Example: `true`
+
+## Environment Variables
+
+<!-- CUSTOMIZE: Document environment variable overrides -->
+
+Configuration can be overridden with environment variables:
+
+- `SPECKIT_MY_EXTENSION_KEY` - Overrides `settings.key`
+- `SPECKIT_MY_EXTENSION_ANOTHER_KEY` - Overrides `settings.another_key`
+
+Example:
+``bash
+export SPECKIT_MY_EXTENSION_KEY="override-value"
+``
+
+## Troubleshooting
+
+<!-- CUSTOMIZE: Add common issues and solutions -->
+
+### "Configuration not found"
+
+**Solution**: Install the extension and create configuration:
+``bash
+specify extension add my-extension
+cp .specify/extensions/my-extension/config-template.yml \
+   .specify/extensions/my-extension/my-extension-config.yml
+``
+
+### "MCP tool not available"
+
+**Solution**: Ensure MCP server is configured in your AI agent settings.
+
+### "Permission denied"
+
+**Solution**: Check credentials and permissions in the external service.
+
+## Notes
+
+<!-- CUSTOMIZE: Add helpful notes and tips -->
+
+- This command requires an active connection to the external service
+- Results are cached for performance
+- Re-run the command to refresh data
+
+## Examples
+
+<!-- CUSTOMIZE: Add usage examples -->
+
+### Example 1: Basic Usage
+
+``bash
+
+# Run with default configuration
+>
+> /speckit.my-extension.example
+``
+
+### Example 2: With Environment Override
+
+``bash
+
+# Override configuration with environment variable
+
+export SPECKIT_MY_EXTENSION_KEY="custom-value"
+> /speckit.my-extension.example
+``
+
+### Example 3: After Core Command
+
+``bash
+
+# Use as part of a workflow
+>
+> /speckit.tasks
+> /speckit.my-extension.example
+``
+
+---
+
+*For more information, see the extension README or run `specify extension info my-extension`*
--- a/extensions/template/config-template.yml
+++ b/extensions/template/config-template.yml
@@ -0,0 +1,75 @@
+# Extension Configuration Template
+# Copy this to my-extension-config.yml and customize for your project
+
+# CUSTOMIZE: Add your configuration sections below
+
+# Example: Connection settings
+connection:
+  # URL to external service
+  url: ""  # REQUIRED: e.g., "https://api.example.com"
+
+  # API key or token
+  api_key: ""  # REQUIRED: Your API key
+
+# Example: Project settings
+project:
+  # Project identifier
+  id: ""  # REQUIRED: e.g., "my-project"
+
+  # Workspace or organization
+  workspace: ""  # OPTIONAL: e.g., "my-org"
+
+# Example: Feature flags
+features:
+  # Enable/disable main functionality
+  enabled: true
+
+  # Automatic synchronization
+  auto_sync: false
+
+  # Verbose logging
+  verbose: false
+
+# Example: Default values
+defaults:
+  # Labels to apply
+  labels: []  # e.g., ["automated", "spec-kit"]
+
+  # Priority level
+  priority: "medium"  # Options: "low", "medium", "high"
+
+  # Assignee
+  assignee: ""  # OPTIONAL: Default assignee
+
+# Example: Field mappings
+# Map internal names to external field IDs
+field_mappings:
+  # Example mappings
+  # internal_field: "external_field_id"
+  # status: "customfield_10001"
+
+# Example: Advanced settings
+advanced:
+  # Timeout in seconds
+  timeout: 30
+
+  # Retry attempts
+  retry_count: 3
+
+  # Cache duration in seconds
+  cache_duration: 3600
+
+# Environment Variable Overrides:
+# You can override any setting with environment variables  using this pattern:
+# SPECKIT_MY_EXTENSION_{SECTION}_{KEY}
+#
+# Examples:
+# - SPECKIT_MY_EXTENSION_CONNECTION_API_KEY: Override connection.api_key
+# - SPECKIT_MY_EXTENSION_PROJECT_ID: Override project.id
+# - SPECKIT_MY_EXTENSION_FEATURES_ENABLED: Override features.enabled
+#
+# Note: Use uppercase and replace dots with underscores
+
+# Local Overrides:
+# For local development, create my-extension-config.local.yml (gitignored)
+# to override settings without affecting the team configuration
--- a/extensions/template/extension.yml
+++ b/extensions/template/extension.yml
@@ -0,0 +1,97 @@
+schema_version: "1.0"
+
+extension:
+  # CUSTOMIZE: Change 'my-extension' to your extension ID (lowercase, hyphen-separated)
+  id: "my-extension"
+
+  # CUSTOMIZE: Human-readable name for your extension
+  name: "My Extension"
+
+  # CUSTOMIZE: Update version when releasing (semantic versioning: X.Y.Z)
+  version: "1.0.0"
+
+  # CUSTOMIZE: Brief description (under 200 characters)
+  description: "Brief description of what your extension does"
+
+  # CUSTOMIZE: Your name or organization name
+  author: "Your Name"
+
+  # CUSTOMIZE: GitHub repository URL (create before publishing)
+  repository: "https://github.com/your-org/spec-kit-my-extension"
+
+  # REVIEW: License (MIT is recommended for open source)
+  license: "MIT"
+
+  # CUSTOMIZE: Extension homepage (can be same as repository)
+  homepage: "https://github.com/your-org/spec-kit-my-extension"
+
+# Requirements for this extension
+requires:
+  # CUSTOMIZE: Minimum spec-kit version required
+  # Use >=X.Y.Z for minimum version
+  # Use >=X.Y.Z,<Y.0.0 for version range
+  speckit_version: ">=0.1.0"
+
+  # CUSTOMIZE: Add MCP tools or other dependencies
+  # Remove if no external tools required
+  tools:
+    - name: "example-mcp-server"
+      version: ">=1.0.0"
+      required: true
+
+# Commands provided by this extension
+provides:
+  commands:
+    # CUSTOMIZE: Define your commands
+    # Pattern: speckit.{extension-id}.{command-name}
+    - name: "speckit.my-extension.example"
+      file: "commands/example.md"
+      description: "Example command that demonstrates functionality"
+      # Optional: Add aliases for shorter command names
+      aliases: ["speckit.example"]
+
+    # ADD MORE COMMANDS: Copy this block for each command
+    # - name: "speckit.my-extension.another-command"
+    #   file: "commands/another-command.md"
+    #   description: "Another command"
+
+  # CUSTOMIZE: Define configuration files
+  config:
+    - name: "my-extension-config.yml"
+      template: "config-template.yml"
+      description: "Extension configuration"
+      required: true # Set to false if config is optional
+
+# CUSTOMIZE: Define hooks (optional)
+# Remove if no hooks needed
+hooks:
+  # Hook that runs after /speckit.tasks
+  after_tasks:
+    command: "speckit.my-extension.example"
+    optional: true # User will be prompted
+    prompt: "Run example command?"
+    description: "Demonstrates hook functionality"
+    condition: null # Future: conditional execution
+
+  # ADD MORE HOOKS: Copy this block for other events
+  # after_implement:
+  #   command: "speckit.my-extension.another"
+  #   optional: false  # Auto-execute without prompting
+  #   description: "Runs automatically after implementation"
+
+# CUSTOMIZE: Add relevant tags (2-5 recommended)
+# Used for discovery in catalog
+tags:
+  - "example"
+  - "template"
+  # ADD MORE: "category", "tool-name", etc.
+
+# CUSTOMIZE: Default configuration values (optional)
+# These are merged with user config
+defaults:
+  # Example default values
+  feature:
+    enabled: true
+    auto_sync: false
+
+  # ADD MORE: Any default settings for your extension
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.0.22"
+version = "0.1.1"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [
@@ -10,6 +10,8 @@ dependencies = [
    "platformdirs",
    "readchar",
    "truststore>=0.10.4",
+    "pyyaml>=6.0",
+    "packaging>=23.0",
 ]

 [project.scripts]
@@ -22,3 +24,30 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["src/specify_cli"]

+[project.optional-dependencies]
+test = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--strict-markers",
+    "--tb=short",
+]
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/tests/*", "*/__pycache__/*"]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false
+
+
--- a/scripts/bash/update-agent-context.sh
+++ b/scripts/bash/update-agent-context.sh
@@ -30,12 +30,12 @@
 #
 # 5. Multi-Agent Support
 #    - Handles agent-specific file paths and naming conventions
-#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, or Amazon Q Developer CLI
+#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, Amazon Q Developer CLI, or Antigravity
 #    - Can update single agents or all existing agent files
 #    - Creates default Claude file if no agent files exist
 #
 # Usage: ./update-agent-context.sh [agent_type]
-# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|shai|q|bob|qoder
+# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qoder
 # Leave empty to update all existing agent files

 set -e
@@ -74,6 +74,7 @@ QODER_FILE="$REPO_ROOT/QODER.md"
 AMP_FILE="$REPO_ROOT/AGENTS.md"
 SHAI_FILE="$REPO_ROOT/SHAI.md"
 Q_FILE="$REPO_ROOT/AGENTS.md"
+AGY_FILE="$REPO_ROOT/.agent/rules/specify-rules.md"
 BOB_FILE="$REPO_ROOT/AGENTS.md"

 # Template file
@@ -630,12 +631,15 @@ update_specific_agent() {
        q)
            update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
            ;;
+        agy)
+            update_agent_file "$AGY_FILE" "Antigravity"
+            ;;
        bob)
            update_agent_file "$BOB_FILE" "IBM Bob"
            ;;
        *)
            log_error "Unknown agent type '$agent_type'"
-            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|amp|shai|q|bob|qoder"
+            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|amp|shai|q|agy|bob|qoder"
            exit 1
            ;;
    esac
@@ -714,7 +718,11 @@ update_all_existing_agents() {
        update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
        found_agent=true
    fi
-    
+
+    if [[ -f "$AGY_FILE" ]]; then
+        update_agent_file "$AGY_FILE" "Antigravity"
+        found_agent=true
+    fi
    if [[ -f "$BOB_FILE" ]]; then
        update_agent_file "$BOB_FILE" "IBM Bob"
        found_agent=true
@@ -744,7 +752,7 @@ print_summary() {
    
    echo

-    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|codebuddy|shai|q|bob|qoder]"
+    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qoder]"
 }

 #==============================================================================
--- a/scripts/powershell/update-agent-context.ps1
+++ b/scripts/powershell/update-agent-context.ps1
@@ -9,7 +9,7 @@ Mirrors the behavior of scripts/bash/update-agent-context.sh:
 2. Plan Data Extraction
 3. Agent File Management (create from template or update existing)
 4. Content Generation (technology stack, recent changes, timestamp)
- 5. Multi-Agent Support (claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, amp, shai, q, bob, qoder)
+ 5. Multi-Agent Support (claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, amp, shai, q, agy, bob, qoder)

 .PARAMETER AgentType
 Optional agent key to update a single agent. If omitted, updates all existing agent files (creating a default Claude file if none exist).
@@ -25,7 +25,7 @@ Relies on common helper functions in common.ps1
 #>
 param(
    [Parameter(Position=0)]
-    [ValidateSet('claude','gemini','copilot','cursor-agent','qwen','opencode','codex','windsurf','kilocode','auggie','roo','codebuddy','amp','shai','q','bob','qoder')]
+    [ValidateSet('claude','gemini','copilot','cursor-agent','qwen','opencode','codex','windsurf','kilocode','auggie','roo','codebuddy','amp','shai','q','agy','bob','qoder')]
    [string]$AgentType
 )

@@ -59,6 +59,7 @@ $QODER_FILE    = Join-Path $REPO_ROOT 'QODER.md'
 $AMP_FILE      = Join-Path $REPO_ROOT 'AGENTS.md'
 $SHAI_FILE     = Join-Path $REPO_ROOT 'SHAI.md'
 $Q_FILE        = Join-Path $REPO_ROOT 'AGENTS.md'
+$AGY_FILE      = Join-Path $REPO_ROOT '.agent/rules/specify-rules.md'
 $BOB_FILE      = Join-Path $REPO_ROOT 'AGENTS.md'

 $TEMPLATE_FILE = Join-Path $REPO_ROOT '.specify/templates/agent-file-template.md'
@@ -387,8 +388,9 @@ function Update-SpecificAgent {
        'amp'      { Update-AgentFile -TargetFile $AMP_FILE      -AgentName 'Amp' }
        'shai'     { Update-AgentFile -TargetFile $SHAI_FILE     -AgentName 'SHAI' }
        'q'        { Update-AgentFile -TargetFile $Q_FILE        -AgentName 'Amazon Q Developer CLI' }
+        'agy'      { Update-AgentFile -TargetFile $AGY_FILE      -AgentName 'Antigravity' }
        'bob'      { Update-AgentFile -TargetFile $BOB_FILE      -AgentName 'IBM Bob' }
-        default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|bob|qoder'; return $false }
+        default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qoder'; return $false }
    }
 }

@@ -409,6 +411,7 @@ function Update-AllExistingAgents {
    if (Test-Path $QODER_FILE)    { if (-not (Update-AgentFile -TargetFile $QODER_FILE    -AgentName 'Qoder CLI')) { $ok = $false }; $found = $true }
    if (Test-Path $SHAI_FILE)     { if (-not (Update-AgentFile -TargetFile $SHAI_FILE     -AgentName 'SHAI')) { $ok = $false }; $found = $true }
    if (Test-Path $Q_FILE)        { if (-not (Update-AgentFile -TargetFile $Q_FILE        -AgentName 'Amazon Q Developer CLI')) { $ok = $false }; $found = $true }
+    if (Test-Path $AGY_FILE)      { if (-not (Update-AgentFile -TargetFile $AGY_FILE      -AgentName 'Antigravity')) { $ok = $false }; $found = $true }
    if (Test-Path $BOB_FILE)      { if (-not (Update-AgentFile -TargetFile $BOB_FILE      -AgentName 'IBM Bob')) { $ok = $false }; $found = $true }
    if (-not $found) {
        Write-Info 'No existing agent files found, creating default Claude file...'
@@ -424,7 +427,7 @@ function Print-Summary {
    if ($NEW_FRAMEWORK) { Write-Host "  - Added framework: $NEW_FRAMEWORK" }
    if ($NEW_DB -and $NEW_DB -ne 'N/A') { Write-Host "  - Added database: $NEW_DB" }
    Write-Host ''
-    Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|bob|qoder]'
+    Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qoder]'
 }

 function Main {
--- a/spec-kit.code-workspace
+++ b/spec-kit.code-workspace
@@ -0,0 +1,8 @@
+{
+	"folders": [
+		{
+			"path": "."
+		}
+	],
+	"settings": {}
+}
--- a/src/specify_cli/init.py
+++ b/src/specify_cli/init.py
--- a/src/specify_cli/extensions.py
+++ b/src/specify_cli/extensions.py
--- a/templates/commands/constitution.md
+++ b/templates/commands/constitution.md
@@ -16,11 +16,13 @@ You **MUST** consider the user input before proceeding (if not empty).

 ## Outline

-You are updating the project constitution at `/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+**Note**: If `.specify/memory/constitution.md` does not exist yet, it should have been initialized from `.specify/templates/constitution-template.md` during project setup. If it's missing, copy the template first.

 Follow this execution flow:

-1. Load the existing constitution template at `/memory/constitution.md`.
+1. Load the existing constitution at `.specify/memory/constitution.md`.
   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.

@@ -41,10 +43,10 @@ Follow this execution flow:
   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.

 4. Consistency propagation checklist (convert prior checklist into active validations):
-   - Read `/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
-   - Read `/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
-   - Read `/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
-   - Read each command file in `/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+   - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+   - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+   - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+   - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.

 5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
@@ -61,7 +63,7 @@ Follow this execution flow:
   - Dates ISO format YYYY-MM-DD.
   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).

-7. Write the completed constitution back to `/memory/constitution.md` (overwrite).
+7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).

 8. Output a final summary to the user with:
   - New version and bump rationale.
@@ -79,4 +81,4 @@ If the user supplies partial updates (e.g., only one principle revision), still

 If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.

-Do not create a new template; always operate on the existing `/memory/constitution.md` file.
+Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
--- a/templates/constitution-template.md
+++ b/templates/constitution-template.md
--- a/templates/plan-template.md
+++ b/templates/plan-template.md
@@ -3,7 +3,7 @@
 **Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
 **Input**: Feature specification from `/specs/[###-feature-name]/spec.md`

-**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.

 ## Summary

--- a/tests/init.py
+++ b/tests/init.py
@@ -0,0 +1 @@
+"""Unit tests for Spec Kit."""
--- a/tests/test_ai_skills.py
+++ b/tests/test_ai_skills.py
@@ -0,0 +1,632 @@
+"""
+Unit tests for AI agent skills installation.
+
+Tests cover:
+- Skills directory resolution for different agents (_get_skills_dir)
+- YAML frontmatter parsing and SKILL.md generation (install_ai_skills)
+- Cleanup of duplicate command files when --ai-skills is used
+- Missing templates directory handling
+- Malformed template error handling
+- CLI validation: --ai-skills requires --ai
+"""
+
+import re
+import pytest
+import tempfile
+import shutil
+import yaml
+from pathlib import Path
+from unittest.mock import patch
+
+import specify_cli
+
+from specify_cli import (
+    _get_skills_dir,
+    install_ai_skills,
+    AGENT_SKILLS_DIR_OVERRIDES,
+    DEFAULT_SKILLS_DIR,
+    SKILL_DESCRIPTIONS,
+    AGENT_CONFIG,
+    app,
+)
+
+
+# ===== Fixtures =====
+
+@pytest.fixture
+def temp_dir():
+    """Create a temporary directory for tests."""
+    tmpdir = tempfile.mkdtemp()
+    yield Path(tmpdir)
+    shutil.rmtree(tmpdir)
+
+
+@pytest.fixture
+def project_dir(temp_dir):
+    """Create a mock project directory."""
+    proj_dir = temp_dir / "test-project"
+    proj_dir.mkdir()
+    return proj_dir
+
+
+@pytest.fixture
+def templates_dir(project_dir):
+    """Create mock command templates in the project's agent commands directory.
+
+    This simulates what download_and_extract_template() does: it places
+    command .md files into project_path/<agent_folder>/commands/.
+    install_ai_skills() now reads from here instead of from the repo
+    source tree.
+    """
+    tpl_root = project_dir / ".claude" / "commands"
+    tpl_root.mkdir(parents=True, exist_ok=True)
+
+    # Template with valid YAML frontmatter
+    (tpl_root / "specify.md").write_text(
+        "---\n"
+        "description: Create or update the feature specification.\n"
+        "handoffs:\n"
+        "  - label: Build Plan\n"
+        "    agent: speckit.plan\n"
+        "scripts:\n"
+        "  sh: scripts/bash/create-new-feature.sh\n"
+        "---\n"
+        "\n"
+        "# Specify Command\n"
+        "\n"
+        "Run this to create a spec.\n",
+        encoding="utf-8",
+    )
+
+    # Template with minimal frontmatter
+    (tpl_root / "plan.md").write_text(
+        "---\n"
+        "description: Generate implementation plan.\n"
+        "---\n"
+        "\n"
+        "# Plan Command\n"
+        "\n"
+        "Plan body content.\n",
+        encoding="utf-8",
+    )
+
+    # Template with no frontmatter
+    (tpl_root / "tasks.md").write_text(
+        "# Tasks Command\n"
+        "\n"
+        "Body without frontmatter.\n",
+        encoding="utf-8",
+    )
+
+    # Template with empty YAML frontmatter (yaml.safe_load returns None)
+    (tpl_root / "empty_fm.md").write_text(
+        "---\n"
+        "---\n"
+        "\n"
+        "# Empty Frontmatter Command\n"
+        "\n"
+        "Body with empty frontmatter.\n",
+        encoding="utf-8",
+    )
+
+    return tpl_root
+
+
+@pytest.fixture
+def commands_dir_claude(project_dir):
+    """Create a populated .claude/commands directory simulating template extraction."""
+    cmd_dir = project_dir / ".claude" / "commands"
+    cmd_dir.mkdir(parents=True, exist_ok=True)
+    for name in ["speckit.specify.md", "speckit.plan.md", "speckit.tasks.md"]:
+        (cmd_dir / name).write_text(f"# {name}\nContent here\n")
+    return cmd_dir
+
+
+@pytest.fixture
+def commands_dir_gemini(project_dir):
+    """Create a populated .gemini/commands directory (TOML format)."""
+    cmd_dir = project_dir / ".gemini" / "commands"
+    cmd_dir.mkdir(parents=True)
+    for name in ["speckit.specify.toml", "speckit.plan.toml", "speckit.tasks.toml"]:
+        (cmd_dir / name).write_text(f'[command]\nname = "{name}"\n')
+    return cmd_dir
+
+
+# ===== _get_skills_dir Tests =====
+
+class TestGetSkillsDir:
+    """Test the _get_skills_dir() helper function."""
+
+    def test_claude_skills_dir(self, project_dir):
+        """Claude should use .claude/skills/."""
+        result = _get_skills_dir(project_dir, "claude")
+        assert result == project_dir / ".claude" / "skills"
+
+    def test_gemini_skills_dir(self, project_dir):
+        """Gemini should use .gemini/skills/."""
+        result = _get_skills_dir(project_dir, "gemini")
+        assert result == project_dir / ".gemini" / "skills"
+
+    def test_copilot_skills_dir(self, project_dir):
+        """Copilot should use .github/skills/."""
+        result = _get_skills_dir(project_dir, "copilot")
+        assert result == project_dir / ".github" / "skills"
+
+    def test_codex_uses_override(self, project_dir):
+        """Codex should use the AGENT_SKILLS_DIR_OVERRIDES value."""
+        result = _get_skills_dir(project_dir, "codex")
+        assert result == project_dir / ".agents" / "skills"
+
+    def test_cursor_agent_skills_dir(self, project_dir):
+        """Cursor should use .cursor/skills/."""
+        result = _get_skills_dir(project_dir, "cursor-agent")
+        assert result == project_dir / ".cursor" / "skills"
+
+    def test_unknown_agent_uses_default(self, project_dir):
+        """Unknown agents should fall back to DEFAULT_SKILLS_DIR."""
+        result = _get_skills_dir(project_dir, "nonexistent-agent")
+        assert result == project_dir / DEFAULT_SKILLS_DIR
+
+    def test_all_configured_agents_resolve(self, project_dir):
+        """Every agent in AGENT_CONFIG should resolve to a valid path."""
+        for agent_key in AGENT_CONFIG:
+            result = _get_skills_dir(project_dir, agent_key)
+            assert result is not None
+            assert str(result).startswith(str(project_dir))
+            # Should always end with "skills"
+            assert result.name == "skills"
+
+    def test_override_takes_precedence_over_config(self, project_dir):
+        """AGENT_SKILLS_DIR_OVERRIDES should take precedence over AGENT_CONFIG."""
+        for agent_key in AGENT_SKILLS_DIR_OVERRIDES:
+            result = _get_skills_dir(project_dir, agent_key)
+            expected = project_dir / AGENT_SKILLS_DIR_OVERRIDES[agent_key]
+            assert result == expected
+
+
+# ===== install_ai_skills Tests =====
+
+class TestInstallAiSkills:
+    """Test SKILL.md generation and installation logic."""
+
+    def test_skills_installed_with_correct_structure(self, project_dir, templates_dir):
+        """Verify SKILL.md files have correct agentskills.io structure."""
+        result = install_ai_skills(project_dir, "claude")
+
+        assert result is True
+
+        skills_dir = project_dir / ".claude" / "skills"
+        assert skills_dir.exists()
+
+        # Check that skill directories were created
+        skill_dirs = sorted([d.name for d in skills_dir.iterdir() if d.is_dir()])
+        assert "speckit-plan" in skill_dirs
+        assert "speckit-specify" in skill_dirs
+        assert "speckit-tasks" in skill_dirs
+        assert "speckit-empty_fm" in skill_dirs
+
+        # Verify SKILL.md content for speckit-specify
+        skill_file = skills_dir / "speckit-specify" / "SKILL.md"
+        assert skill_file.exists()
+        content = skill_file.read_text()
+
+        # Check agentskills.io frontmatter
+        assert content.startswith("---\n")
+        assert "name: speckit-specify" in content
+        assert "description:" in content
+        assert "compatibility:" in content
+        assert "metadata:" in content
+        assert "author: github-spec-kit" in content
+        assert "source: templates/commands/specify.md" in content
+
+        # Check body content is included
+        assert "# Speckit Specify Skill" in content
+        assert "Run this to create a spec." in content
+
+    def test_generated_skill_has_parseable_yaml(self, project_dir, templates_dir):
+        """Generated SKILL.md should contain valid, parseable YAML frontmatter."""
+        install_ai_skills(project_dir, "claude")
+
+        skill_file = project_dir / ".claude" / "skills" / "speckit-specify" / "SKILL.md"
+        content = skill_file.read_text()
+
+        # Extract and parse frontmatter
+        assert content.startswith("---\n")
+        parts = content.split("---", 2)
+        assert len(parts) >= 3
+        parsed = yaml.safe_load(parts[1])
+        assert isinstance(parsed, dict)
+        assert "name" in parsed
+        assert parsed["name"] == "speckit-specify"
+        assert "description" in parsed
+
+    def test_empty_yaml_frontmatter(self, project_dir, templates_dir):
+        """Templates with empty YAML frontmatter (---\\n---) should not crash."""
+        result = install_ai_skills(project_dir, "claude")
+
+        assert result is True
+
+        skill_file = project_dir / ".claude" / "skills" / "speckit-empty_fm" / "SKILL.md"
+        assert skill_file.exists()
+        content = skill_file.read_text()
+        assert "name: speckit-empty_fm" in content
+        assert "Body with empty frontmatter." in content
+
+    def test_enhanced_descriptions_used_when_available(self, project_dir, templates_dir):
+        """SKILL_DESCRIPTIONS take precedence over template frontmatter descriptions."""
+        install_ai_skills(project_dir, "claude")
+
+        skill_file = project_dir / ".claude" / "skills" / "speckit-specify" / "SKILL.md"
+        content = skill_file.read_text()
+
+        # Parse the generated YAML to compare the description value
+        # (yaml.safe_dump may wrap long strings across multiple lines)
+        parts = content.split("---", 2)
+        parsed = yaml.safe_load(parts[1])
+
+        if "specify" in SKILL_DESCRIPTIONS:
+            assert parsed["description"] == SKILL_DESCRIPTIONS["specify"]
+
+    def test_template_without_frontmatter(self, project_dir, templates_dir):
+        """Templates without YAML frontmatter should still produce valid skills."""
+        install_ai_skills(project_dir, "claude")
+
+        skill_file = project_dir / ".claude" / "skills" / "speckit-tasks" / "SKILL.md"
+        assert skill_file.exists()
+        content = skill_file.read_text()
+
+        # Should still have valid SKILL.md structure
+        assert "name: speckit-tasks" in content
+        assert "Body without frontmatter." in content
+
+    def test_missing_templates_directory(self, project_dir):
+        """Returns False when no command templates exist anywhere."""
+        # No .claude/commands/ exists, and __file__ fallback won't find anything
+        fake_init = project_dir / "nonexistent" / "src" / "specify_cli" / "__init__.py"
+        fake_init.parent.mkdir(parents=True, exist_ok=True)
+        fake_init.touch()
+
+        with patch.object(specify_cli, "__file__", str(fake_init)):
+            result = install_ai_skills(project_dir, "claude")
+
+        assert result is False
+
+        # Skills directory should not exist
+        skills_dir = project_dir / ".claude" / "skills"
+        assert not skills_dir.exists()
+
+    def test_empty_templates_directory(self, project_dir):
+        """Returns False when commands directory has no .md files."""
+        # Create empty .claude/commands/
+        empty_cmds = project_dir / ".claude" / "commands"
+        empty_cmds.mkdir(parents=True)
+
+        # Block the __file__ fallback so it can't find real templates
+        fake_init = project_dir / "nowhere" / "src" / "specify_cli" / "__init__.py"
+        fake_init.parent.mkdir(parents=True, exist_ok=True)
+        fake_init.touch()
+
+        with patch.object(specify_cli, "__file__", str(fake_init)):
+            result = install_ai_skills(project_dir, "claude")
+
+        assert result is False
+
+    def test_malformed_yaml_frontmatter(self, project_dir):
+        """Malformed YAML in a template should be handled gracefully, not crash."""
+        # Create .claude/commands/ with a broken template
+        cmds_dir = project_dir / ".claude" / "commands"
+        cmds_dir.mkdir(parents=True)
+
+        (cmds_dir / "broken.md").write_text(
+            "---\n"
+            "description: [unclosed bracket\n"
+            "  invalid: yaml: content: here\n"
+            "---\n"
+            "\n"
+            "# Broken\n",
+            encoding="utf-8",
+        )
+
+        # Should not raise — errors are caught per-file
+        result = install_ai_skills(project_dir, "claude")
+
+        # The broken template should be skipped but not crash the process
+        assert result is False
+
+    def test_additive_does_not_overwrite_other_files(self, project_dir, templates_dir):
+        """Installing skills should not remove non-speckit files in the skills dir."""
+        # Pre-create a custom skill
+        custom_dir = project_dir / ".claude" / "skills" / "my-custom-skill"
+        custom_dir.mkdir(parents=True)
+        custom_file = custom_dir / "SKILL.md"
+        custom_file.write_text("# My Custom Skill\n")
+
+        install_ai_skills(project_dir, "claude")
+
+        # Custom skill should still exist
+        assert custom_file.exists()
+        assert custom_file.read_text() == "# My Custom Skill\n"
+
+    def test_return_value(self, project_dir, templates_dir):
+        """install_ai_skills returns True when skills installed, False otherwise."""
+        assert install_ai_skills(project_dir, "claude") is True
+
+    def test_return_false_when_no_templates(self, project_dir):
+        """install_ai_skills returns False when no templates found."""
+        fake_init = project_dir / "missing" / "src" / "specify_cli" / "__init__.py"
+        fake_init.parent.mkdir(parents=True, exist_ok=True)
+        fake_init.touch()
+
+        with patch.object(specify_cli, "__file__", str(fake_init)):
+            assert install_ai_skills(project_dir, "claude") is False
+
+    def test_non_md_commands_dir_falls_back(self, project_dir):
+        """When extracted commands are .toml (e.g. gemini), fall back to repo templates."""
+        # Simulate gemini template extraction: .gemini/commands/ with .toml files only
+        cmds_dir = project_dir / ".gemini" / "commands"
+        cmds_dir.mkdir(parents=True)
+        (cmds_dir / "speckit.specify.toml").write_text('[command]\nname = "specify"\n')
+        (cmds_dir / "speckit.plan.toml").write_text('[command]\nname = "plan"\n')
+
+        # The __file__ fallback should find the real repo templates/commands/*.md
+        result = install_ai_skills(project_dir, "gemini")
+
+        assert result is True
+        skills_dir = project_dir / ".gemini" / "skills"
+        assert skills_dir.exists()
+        # Should have installed skills from the fallback .md templates
+        skill_dirs = [d.name for d in skills_dir.iterdir() if d.is_dir()]
+        assert len(skill_dirs) >= 1
+        # .toml commands should be untouched
+        assert (cmds_dir / "speckit.specify.toml").exists()
+
+    @pytest.mark.parametrize("agent_key", list(AGENT_CONFIG.keys()))
+    def test_skills_install_for_all_agents(self, temp_dir, agent_key):
+        """install_ai_skills should produce skills for every configured agent."""
+        proj = temp_dir / f"proj-{agent_key}"
+        proj.mkdir()
+
+        # Place .md templates in the agent's commands directory
+        agent_folder = AGENT_CONFIG[agent_key]["folder"]
+        cmds_dir = proj / agent_folder.rstrip("/") / "commands"
+        cmds_dir.mkdir(parents=True)
+        (cmds_dir / "specify.md").write_text(
+            "---\ndescription: Test command\n---\n\n# Test\n\nBody.\n"
+        )
+
+        result = install_ai_skills(proj, agent_key)
+
+        assert result is True
+        skills_dir = _get_skills_dir(proj, agent_key)
+        assert skills_dir.exists()
+        skill_dirs = [d.name for d in skills_dir.iterdir() if d.is_dir()]
+        assert "speckit-specify" in skill_dirs
+        assert (skills_dir / "speckit-specify" / "SKILL.md").exists()
+
+
+
+class TestCommandCoexistence:
+    """Verify install_ai_skills never touches command files.
+
+    Cleanup of freshly-extracted commands for NEW projects is handled
+    in init(), not in install_ai_skills().  These tests confirm that
+    install_ai_skills leaves existing commands intact.
+    """
+
+    def test_existing_commands_preserved_claude(self, project_dir, templates_dir, commands_dir_claude):
+        """install_ai_skills must NOT remove pre-existing .claude/commands files."""
+        # Verify commands exist before
+        assert len(list(commands_dir_claude.glob("speckit.*"))) == 3
+
+        install_ai_skills(project_dir, "claude")
+
+        # Commands must still be there — install_ai_skills never touches them
+        remaining = list(commands_dir_claude.glob("speckit.*"))
+        assert len(remaining) == 3
+
+    def test_existing_commands_preserved_gemini(self, project_dir, templates_dir, commands_dir_gemini):
+        """install_ai_skills must NOT remove pre-existing .gemini/commands files."""
+        assert len(list(commands_dir_gemini.glob("speckit.*"))) == 3
+
+        install_ai_skills(project_dir, "gemini")
+
+        remaining = list(commands_dir_gemini.glob("speckit.*"))
+        assert len(remaining) == 3
+
+    def test_commands_dir_not_removed(self, project_dir, templates_dir, commands_dir_claude):
+        """install_ai_skills must not remove the commands directory."""
+        install_ai_skills(project_dir, "claude")
+
+        assert commands_dir_claude.exists()
+
+    def test_no_commands_dir_no_error(self, project_dir, templates_dir):
+        """No error when installing skills — commands dir has templates and is preserved."""
+        result = install_ai_skills(project_dir, "claude")
+
+        # Should succeed since templates are in .claude/commands/ via fixture
+        assert result is True
+
+
+# ===== New-Project Command Skip Tests =====
+
+class TestNewProjectCommandSkip:
+    """Test that init() removes extracted commands for new projects only.
+
+    These tests run init() end-to-end via CliRunner with
+    download_and_extract_template patched to create local fixtures.
+    """
+
+    def _fake_extract(self, agent, project_path, **_kwargs):
+        """Simulate template extraction: create agent commands dir."""
+        agent_cfg = AGENT_CONFIG.get(agent, {})
+        agent_folder = agent_cfg.get("folder", "")
+        if agent_folder:
+            cmds_dir = project_path / agent_folder.rstrip("/") / "commands"
+            cmds_dir.mkdir(parents=True, exist_ok=True)
+            (cmds_dir / "speckit.specify.md").write_text("# spec")
+
+    def test_new_project_commands_removed_after_skills_succeed(self, tmp_path):
+        """For new projects, commands should be removed when skills succeed."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        target = tmp_path / "new-proj"
+
+        def fake_download(project_path, *args, **kwargs):
+            self._fake_extract("claude", project_path)
+
+        with patch("specify_cli.download_and_extract_template", side_effect=fake_download), \
+             patch("specify_cli.ensure_executable_scripts"), \
+             patch("specify_cli.ensure_constitution_from_template"), \
+             patch("specify_cli.install_ai_skills", return_value=True) as mock_skills, \
+             patch("specify_cli.is_git_repo", return_value=False), \
+             patch("specify_cli.shutil.which", return_value="/usr/bin/git"):
+            result = runner.invoke(app, ["init", str(target), "--ai", "claude", "--ai-skills", "--script", "sh", "--no-git"])
+
+        # Skills should have been called
+        mock_skills.assert_called_once()
+
+        # Commands dir should have been removed after skills succeeded
+        cmds_dir = target / ".claude" / "commands"
+        assert not cmds_dir.exists()
+
+    def test_commands_preserved_when_skills_fail(self, tmp_path):
+        """If skills fail, commands should NOT be removed (safety net)."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        target = tmp_path / "fail-proj"
+
+        def fake_download(project_path, *args, **kwargs):
+            self._fake_extract("claude", project_path)
+
+        with patch("specify_cli.download_and_extract_template", side_effect=fake_download), \
+             patch("specify_cli.ensure_executable_scripts"), \
+             patch("specify_cli.ensure_constitution_from_template"), \
+             patch("specify_cli.install_ai_skills", return_value=False), \
+             patch("specify_cli.is_git_repo", return_value=False), \
+             patch("specify_cli.shutil.which", return_value="/usr/bin/git"):
+            result = runner.invoke(app, ["init", str(target), "--ai", "claude", "--ai-skills", "--script", "sh", "--no-git"])
+
+        # Commands should still exist since skills failed
+        cmds_dir = target / ".claude" / "commands"
+        assert cmds_dir.exists()
+        assert (cmds_dir / "speckit.specify.md").exists()
+
+    def test_here_mode_commands_preserved(self, tmp_path, monkeypatch):
+        """For --here on existing repos, commands must NOT be removed."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        # Create a mock existing project with commands already present
+        target = tmp_path / "existing"
+        target.mkdir()
+        agent_folder = AGENT_CONFIG["claude"]["folder"]
+        cmds_dir = target / agent_folder.rstrip("/") / "commands"
+        cmds_dir.mkdir(parents=True)
+        (cmds_dir / "speckit.specify.md").write_text("# spec")
+
+        # --here uses CWD, so chdir into the target
+        monkeypatch.chdir(target)
+
+        def fake_download(project_path, *args, **kwargs):
+            pass  # commands already exist, no need to re-create
+
+        with patch("specify_cli.download_and_extract_template", side_effect=fake_download), \
+             patch("specify_cli.ensure_executable_scripts"), \
+             patch("specify_cli.ensure_constitution_from_template"), \
+             patch("specify_cli.install_ai_skills", return_value=True), \
+             patch("specify_cli.is_git_repo", return_value=True), \
+             patch("specify_cli.shutil.which", return_value="/usr/bin/git"):
+            result = runner.invoke(app, ["init", "--here", "--ai", "claude", "--ai-skills", "--script", "sh", "--no-git"])
+
+        # Commands must remain for --here
+        assert cmds_dir.exists()
+        assert (cmds_dir / "speckit.specify.md").exists()
+
+
+# ===== Skip-If-Exists Tests =====
+
+class TestSkipIfExists:
+    """Test that install_ai_skills does not overwrite existing SKILL.md files."""
+
+    def test_existing_skill_not_overwritten(self, project_dir, templates_dir):
+        """Pre-existing SKILL.md should not be replaced on re-run."""
+        # Pre-create a custom SKILL.md for speckit-specify
+        skill_dir = project_dir / ".claude" / "skills" / "speckit-specify"
+        skill_dir.mkdir(parents=True)
+        custom_content = "# My Custom Specify Skill\nUser-modified content\n"
+        (skill_dir / "SKILL.md").write_text(custom_content)
+
+        result = install_ai_skills(project_dir, "claude")
+
+        # The custom SKILL.md should be untouched
+        assert (skill_dir / "SKILL.md").read_text() == custom_content
+
+        # But other skills should still be installed
+        assert result is True
+        assert (project_dir / ".claude" / "skills" / "speckit-plan" / "SKILL.md").exists()
+        assert (project_dir / ".claude" / "skills" / "speckit-tasks" / "SKILL.md").exists()
+
+    def test_fresh_install_writes_all_skills(self, project_dir, templates_dir):
+        """On first install (no pre-existing skills), all should be written."""
+        result = install_ai_skills(project_dir, "claude")
+
+        assert result is True
+        skills_dir = project_dir / ".claude" / "skills"
+        skill_dirs = [d.name for d in skills_dir.iterdir() if d.is_dir()]
+        # All 4 templates should produce skills (specify, plan, tasks, empty_fm)
+        assert len(skill_dirs) == 4
+
+
+# ===== SKILL_DESCRIPTIONS Coverage Tests =====
+
+class TestSkillDescriptions:
+    """Test SKILL_DESCRIPTIONS constants."""
+
+    def test_all_known_commands_have_descriptions(self):
+        """All standard spec-kit commands should have enhanced descriptions."""
+        expected_commands = [
+            "specify", "plan", "tasks", "implement", "analyze",
+            "clarify", "constitution", "checklist", "taskstoissues",
+        ]
+        for cmd in expected_commands:
+            assert cmd in SKILL_DESCRIPTIONS, f"Missing description for '{cmd}'"
+            assert len(SKILL_DESCRIPTIONS[cmd]) > 20, f"Description for '{cmd}' is too short"
+
+
+# ===== CLI Validation Tests =====
+
+class TestCliValidation:
+    """Test --ai-skills CLI flag validation."""
+
+    def test_ai_skills_without_ai_fails(self):
+        """--ai-skills without --ai should fail with exit code 1."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", "test-proj", "--ai-skills"])
+
+        assert result.exit_code == 1
+        assert "--ai-skills requires --ai" in result.output
+
+    def test_ai_skills_without_ai_shows_usage(self):
+        """Error message should include usage hint."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", "test-proj", "--ai-skills"])
+
+        assert "Usage:" in result.output
+        assert "--ai" in result.output
+
+    def test_ai_skills_flag_appears_in_help(self):
+        """--ai-skills should appear in init --help output."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", "--help"])
+
+        plain = re.sub(r'\x1b\[[0-9;]*m', '', result.output)
+        assert "--ai-skills" in plain
+        assert "agent skills" in plain.lower()
--- a/tests/test_extensions.py
+++ b/tests/test_extensions.py
@@ -0,0 +1,989 @@
+"""
+Unit tests for the extension system.
+
+Tests cover:
+- Extension manifest validation
+- Extension registry operations
+- Extension manager installation/removal
+- Command registration
+"""
+
+import pytest
+import json
+import tempfile
+import shutil
+from pathlib import Path
+from datetime import datetime, timezone
+
+from specify_cli.extensions import (
+    ExtensionManifest,
+    ExtensionRegistry,
+    ExtensionManager,
+    CommandRegistrar,
+    ExtensionCatalog,
+    ExtensionError,
+    ValidationError,
+    CompatibilityError,
+    version_satisfies,
+)
+
+
+# ===== Fixtures =====
+
+@pytest.fixture
+def temp_dir():
+    """Create a temporary directory for tests."""
+    tmpdir = tempfile.mkdtemp()
+    yield Path(tmpdir)
+    shutil.rmtree(tmpdir)
+
+
+@pytest.fixture
+def valid_manifest_data():
+    """Valid extension manifest data."""
+    return {
+        "schema_version": "1.0",
+        "extension": {
+            "id": "test-ext",
+            "name": "Test Extension",
+            "version": "1.0.0",
+            "description": "A test extension",
+            "author": "Test Author",
+            "repository": "https://github.com/test/test-ext",
+            "license": "MIT",
+        },
+        "requires": {
+            "speckit_version": ">=0.1.0",
+            "commands": ["speckit.tasks"],
+        },
+        "provides": {
+            "commands": [
+                {
+                    "name": "speckit.test.hello",
+                    "file": "commands/hello.md",
+                    "description": "Test command",
+                }
+            ]
+        },
+        "hooks": {
+            "after_tasks": {
+                "command": "speckit.test.hello",
+                "optional": True,
+                "prompt": "Run test?",
+            }
+        },
+        "tags": ["testing", "example"],
+    }
+
+
+@pytest.fixture
+def extension_dir(temp_dir, valid_manifest_data):
+    """Create a complete extension directory structure."""
+    ext_dir = temp_dir / "test-ext"
+    ext_dir.mkdir()
+
+    # Write manifest
+    import yaml
+    manifest_path = ext_dir / "extension.yml"
+    with open(manifest_path, 'w') as f:
+        yaml.dump(valid_manifest_data, f)
+
+    # Create commands directory
+    commands_dir = ext_dir / "commands"
+    commands_dir.mkdir()
+
+    # Write command file
+    cmd_file = commands_dir / "hello.md"
+    cmd_file.write_text("""---
+description: "Test hello command"
+---
+
+# Test Hello Command
+
+$ARGUMENTS
+""")
+
+    return ext_dir
+
+
+@pytest.fixture
+def project_dir(temp_dir):
+    """Create a mock spec-kit project directory."""
+    proj_dir = temp_dir / "project"
+    proj_dir.mkdir()
+
+    # Create .specify directory
+    specify_dir = proj_dir / ".specify"
+    specify_dir.mkdir()
+
+    return proj_dir
+
+
+# ===== ExtensionManifest Tests =====
+
+class TestExtensionManifest:
+    """Test ExtensionManifest validation and parsing."""
+
+    def test_valid_manifest(self, extension_dir):
+        """Test loading a valid manifest."""
+        manifest_path = extension_dir / "extension.yml"
+        manifest = ExtensionManifest(manifest_path)
+
+        assert manifest.id == "test-ext"
+        assert manifest.name == "Test Extension"
+        assert manifest.version == "1.0.0"
+        assert manifest.description == "A test extension"
+        assert len(manifest.commands) == 1
+        assert manifest.commands[0]["name"] == "speckit.test.hello"
+
+    def test_missing_required_field(self, temp_dir):
+        """Test manifest missing required field."""
+        import yaml
+
+        manifest_path = temp_dir / "extension.yml"
+        with open(manifest_path, 'w') as f:
+            yaml.dump({"schema_version": "1.0"}, f)  # Missing 'extension'
+
+        with pytest.raises(ValidationError, match="Missing required field"):
+            ExtensionManifest(manifest_path)
+
+    def test_invalid_extension_id(self, temp_dir, valid_manifest_data):
+        """Test manifest with invalid extension ID format."""
+        import yaml
+
+        valid_manifest_data["extension"]["id"] = "Invalid_ID"  # Uppercase not allowed
+
+        manifest_path = temp_dir / "extension.yml"
+        with open(manifest_path, 'w') as f:
+            yaml.dump(valid_manifest_data, f)
+
+        with pytest.raises(ValidationError, match="Invalid extension ID"):
+            ExtensionManifest(manifest_path)
+
+    def test_invalid_version(self, temp_dir, valid_manifest_data):
+        """Test manifest with invalid semantic version."""
+        import yaml
+
+        valid_manifest_data["extension"]["version"] = "invalid"
+
+        manifest_path = temp_dir / "extension.yml"
+        with open(manifest_path, 'w') as f:
+            yaml.dump(valid_manifest_data, f)
+
+        with pytest.raises(ValidationError, match="Invalid version"):
+            ExtensionManifest(manifest_path)
+
+    def test_invalid_command_name(self, temp_dir, valid_manifest_data):
+        """Test manifest with invalid command name format."""
+        import yaml
+
+        valid_manifest_data["provides"]["commands"][0]["name"] = "invalid-name"
+
+        manifest_path = temp_dir / "extension.yml"
+        with open(manifest_path, 'w') as f:
+            yaml.dump(valid_manifest_data, f)
+
+        with pytest.raises(ValidationError, match="Invalid command name"):
+            ExtensionManifest(manifest_path)
+
+    def test_no_commands(self, temp_dir, valid_manifest_data):
+        """Test manifest with no commands provided."""
+        import yaml
+
+        valid_manifest_data["provides"]["commands"] = []
+
+        manifest_path = temp_dir / "extension.yml"
+        with open(manifest_path, 'w') as f:
+            yaml.dump(valid_manifest_data, f)
+
+        with pytest.raises(ValidationError, match="must provide at least one command"):
+            ExtensionManifest(manifest_path)
+
+    def test_manifest_hash(self, extension_dir):
+        """Test manifest hash calculation."""
+        manifest_path = extension_dir / "extension.yml"
+        manifest = ExtensionManifest(manifest_path)
+
+        hash_value = manifest.get_hash()
+        assert hash_value.startswith("sha256:")
+        assert len(hash_value) > 10
+
+
+# ===== ExtensionRegistry Tests =====
+
+class TestExtensionRegistry:
+    """Test ExtensionRegistry operations."""
+
+    def test_empty_registry(self, temp_dir):
+        """Test creating a new empty registry."""
+        extensions_dir = temp_dir / "extensions"
+        extensions_dir.mkdir()
+
+        registry = ExtensionRegistry(extensions_dir)
+
+        assert registry.data["schema_version"] == "1.0"
+        assert registry.data["extensions"] == {}
+        assert len(registry.list()) == 0
+
+    def test_add_extension(self, temp_dir):
+        """Test adding an extension to registry."""
+        extensions_dir = temp_dir / "extensions"
+        extensions_dir.mkdir()
+
+        registry = ExtensionRegistry(extensions_dir)
+
+        metadata = {
+            "version": "1.0.0",
+            "source": "local",
+            "enabled": True,
+        }
+        registry.add("test-ext", metadata)
+
+        assert registry.is_installed("test-ext")
+        ext_data = registry.get("test-ext")
+        assert ext_data["version"] == "1.0.0"
+        assert "installed_at" in ext_data
+
+    def test_remove_extension(self, temp_dir):
+        """Test removing an extension from registry."""
+        extensions_dir = temp_dir / "extensions"
+        extensions_dir.mkdir()
+
+        registry = ExtensionRegistry(extensions_dir)
+        registry.add("test-ext", {"version": "1.0.0"})
+
+        assert registry.is_installed("test-ext")
+
+        registry.remove("test-ext")
+
+        assert not registry.is_installed("test-ext")
+        assert registry.get("test-ext") is None
+
+    def test_registry_persistence(self, temp_dir):
+        """Test that registry persists to disk."""
+        extensions_dir = temp_dir / "extensions"
+        extensions_dir.mkdir()
+
+        # Create registry and add extension
+        registry1 = ExtensionRegistry(extensions_dir)
+        registry1.add("test-ext", {"version": "1.0.0"})
+
+        # Load new registry instance
+        registry2 = ExtensionRegistry(extensions_dir)
+
+        # Should still have the extension
+        assert registry2.is_installed("test-ext")
+        assert registry2.get("test-ext")["version"] == "1.0.0"
+
+
+# ===== ExtensionManager Tests =====
+
+class TestExtensionManager:
+    """Test ExtensionManager installation and removal."""
+
+    def test_check_compatibility_valid(self, extension_dir, project_dir):
+        """Test compatibility check with valid version."""
+        manager = ExtensionManager(project_dir)
+        manifest = ExtensionManifest(extension_dir / "extension.yml")
+
+        # Should not raise
+        result = manager.check_compatibility(manifest, "0.1.0")
+        assert result is True
+
+    def test_check_compatibility_invalid(self, extension_dir, project_dir):
+        """Test compatibility check with invalid version."""
+        manager = ExtensionManager(project_dir)
+        manifest = ExtensionManifest(extension_dir / "extension.yml")
+
+        # Requires >=0.1.0, but we have 0.0.1
+        with pytest.raises(CompatibilityError, match="Extension requires spec-kit"):
+            manager.check_compatibility(manifest, "0.0.1")
+
+    def test_install_from_directory(self, extension_dir, project_dir):
+        """Test installing extension from directory."""
+        manager = ExtensionManager(project_dir)
+
+        manifest = manager.install_from_directory(
+            extension_dir,
+            "0.1.0",
+            register_commands=False  # Skip command registration for now
+        )
+
+        assert manifest.id == "test-ext"
+        assert manager.registry.is_installed("test-ext")
+
+        # Check extension directory was copied
+        ext_dir = project_dir / ".specify" / "extensions" / "test-ext"
+        assert ext_dir.exists()
+        assert (ext_dir / "extension.yml").exists()
+        assert (ext_dir / "commands" / "hello.md").exists()
+
+    def test_install_duplicate(self, extension_dir, project_dir):
+        """Test installing already installed extension."""
+        manager = ExtensionManager(project_dir)
+
+        # Install once
+        manager.install_from_directory(extension_dir, "0.1.0", register_commands=False)
+
+        # Try to install again
+        with pytest.raises(ExtensionError, match="already installed"):
+            manager.install_from_directory(extension_dir, "0.1.0", register_commands=False)
+
+    def test_remove_extension(self, extension_dir, project_dir):
+        """Test removing an installed extension."""
+        manager = ExtensionManager(project_dir)
+
+        # Install extension
+        manager.install_from_directory(extension_dir, "0.1.0", register_commands=False)
+
+        ext_dir = project_dir / ".specify" / "extensions" / "test-ext"
+        assert ext_dir.exists()
+
+        # Remove extension
+        result = manager.remove("test-ext", keep_config=False)
+
+        assert result is True
+        assert not manager.registry.is_installed("test-ext")
+        assert not ext_dir.exists()
+
+    def test_remove_nonexistent(self, project_dir):
+        """Test removing non-existent extension."""
+        manager = ExtensionManager(project_dir)
+
+        result = manager.remove("nonexistent")
+        assert result is False
+
+    def test_list_installed(self, extension_dir, project_dir):
+        """Test listing installed extensions."""
+        manager = ExtensionManager(project_dir)
+
+        # Initially empty
+        assert len(manager.list_installed()) == 0
+
+        # Install extension
+        manager.install_from_directory(extension_dir, "0.1.0", register_commands=False)
+
+        # Should have one extension
+        installed = manager.list_installed()
+        assert len(installed) == 1
+        assert installed[0]["id"] == "test-ext"
+        assert installed[0]["name"] == "Test Extension"
+        assert installed[0]["version"] == "1.0.0"
+        assert installed[0]["command_count"] == 1
+        assert installed[0]["hook_count"] == 1
+
+    def test_config_backup_on_remove(self, extension_dir, project_dir):
+        """Test that config files are backed up on removal."""
+        manager = ExtensionManager(project_dir)
+
+        # Install extension
+        manager.install_from_directory(extension_dir, "0.1.0", register_commands=False)
+
+        # Create a config file
+        ext_dir = project_dir / ".specify" / "extensions" / "test-ext"
+        config_file = ext_dir / "test-ext-config.yml"
+        config_file.write_text("test: config")
+
+        # Remove extension (without keep_config)
+        manager.remove("test-ext", keep_config=False)
+
+        # Check backup was created (now in subdirectory per extension)
+        backup_dir = project_dir / ".specify" / "extensions" / ".backup" / "test-ext"
+        backup_file = backup_dir / "test-ext-config.yml"
+        assert backup_file.exists()
+        assert backup_file.read_text() == "test: config"
+
+
+# ===== CommandRegistrar Tests =====
+
+class TestCommandRegistrar:
+    """Test CommandRegistrar command registration."""
+
+    def test_parse_frontmatter_valid(self):
+        """Test parsing valid YAML frontmatter."""
+        content = """---
+description: "Test command"
+tools:
+  - tool1
+  - tool2
+---
+
+# Command body
+$ARGUMENTS
+"""
+        registrar = CommandRegistrar()
+        frontmatter, body = registrar.parse_frontmatter(content)
+
+        assert frontmatter["description"] == "Test command"
+        assert frontmatter["tools"] == ["tool1", "tool2"]
+        assert "Command body" in body
+        assert "$ARGUMENTS" in body
+
+    def test_parse_frontmatter_no_frontmatter(self):
+        """Test parsing content without frontmatter."""
+        content = "# Just a command\n$ARGUMENTS"
+
+        registrar = CommandRegistrar()
+        frontmatter, body = registrar.parse_frontmatter(content)
+
+        assert frontmatter == {}
+        assert body == content
+
+    def test_render_frontmatter(self):
+        """Test rendering frontmatter to YAML."""
+        frontmatter = {
+            "description": "Test command",
+            "tools": ["tool1", "tool2"]
+        }
+
+        registrar = CommandRegistrar()
+        output = registrar.render_frontmatter(frontmatter)
+
+        assert output.startswith("---\n")
+        assert output.endswith("---\n")
+        assert "description: Test command" in output
+
+    def test_register_commands_for_claude(self, extension_dir, project_dir):
+        """Test registering commands for Claude agent."""
+        # Create .claude directory
+        claude_dir = project_dir / ".claude" / "commands"
+        claude_dir.mkdir(parents=True)
+
+        ExtensionManager(project_dir)  # Initialize manager (side effects only)
+        manifest = ExtensionManifest(extension_dir / "extension.yml")
+
+        registrar = CommandRegistrar()
+        registered = registrar.register_commands_for_claude(
+            manifest,
+            extension_dir,
+            project_dir
+        )
+
+        assert len(registered) == 1
+        assert "speckit.test.hello" in registered
+
+        # Check command file was created
+        cmd_file = claude_dir / "speckit.test.hello.md"
+        assert cmd_file.exists()
+
+        content = cmd_file.read_text()
+        assert "description: Test hello command" in content
+        assert "<!-- Extension: test-ext -->" in content
+        assert "<!-- Config: .specify/extensions/test-ext/ -->" in content
+
+    def test_command_with_aliases(self, project_dir, temp_dir):
+        """Test registering a command with aliases."""
+        import yaml
+
+        # Create extension with command alias
+        ext_dir = temp_dir / "ext-alias"
+        ext_dir.mkdir()
+
+        manifest_data = {
+            "schema_version": "1.0",
+            "extension": {
+                "id": "ext-alias",
+                "name": "Extension with Alias",
+                "version": "1.0.0",
+                "description": "Test",
+            },
+            "requires": {
+                "speckit_version": ">=0.1.0",
+            },
+            "provides": {
+                "commands": [
+                    {
+                        "name": "speckit.alias.cmd",
+                        "file": "commands/cmd.md",
+                        "aliases": ["speckit.shortcut"],
+                    }
+                ]
+            },
+        }
+
+        with open(ext_dir / "extension.yml", 'w') as f:
+            yaml.dump(manifest_data, f)
+
+        (ext_dir / "commands").mkdir()
+        (ext_dir / "commands" / "cmd.md").write_text("---\ndescription: Test\n---\n\nTest")
+
+        claude_dir = project_dir / ".claude" / "commands"
+        claude_dir.mkdir(parents=True)
+
+        manifest = ExtensionManifest(ext_dir / "extension.yml")
+        registrar = CommandRegistrar()
+        registered = registrar.register_commands_for_claude(manifest, ext_dir, project_dir)
+
+        assert len(registered) == 2
+        assert "speckit.alias.cmd" in registered
+        assert "speckit.shortcut" in registered
+        assert (claude_dir / "speckit.alias.cmd.md").exists()
+        assert (claude_dir / "speckit.shortcut.md").exists()
+
+
+# ===== Utility Function Tests =====
+
+class TestVersionSatisfies:
+    """Test version_satisfies utility function."""
+
+    def test_version_satisfies_simple(self):
+        """Test simple version comparison."""
+        assert version_satisfies("1.0.0", ">=1.0.0")
+        assert version_satisfies("1.0.1", ">=1.0.0")
+        assert not version_satisfies("0.9.9", ">=1.0.0")
+
+    def test_version_satisfies_range(self):
+        """Test version range."""
+        assert version_satisfies("1.5.0", ">=1.0.0,<2.0.0")
+        assert not version_satisfies("2.0.0", ">=1.0.0,<2.0.0")
+        assert not version_satisfies("0.9.0", ">=1.0.0,<2.0.0")
+
+    def test_version_satisfies_complex(self):
+        """Test complex version specifier."""
+        assert version_satisfies("1.0.5", ">=1.0.0,!=1.0.3")
+        assert not version_satisfies("1.0.3", ">=1.0.0,!=1.0.3")
+
+    def test_version_satisfies_invalid(self):
+        """Test invalid version strings."""
+        assert not version_satisfies("invalid", ">=1.0.0")
+        assert not version_satisfies("1.0.0", "invalid specifier")
+
+
+# ===== Integration Tests =====
+
+class TestIntegration:
+    """Integration tests for complete workflows."""
+
+    def test_full_install_and_remove_workflow(self, extension_dir, project_dir):
+        """Test complete installation and removal workflow."""
+        # Create Claude directory
+        (project_dir / ".claude" / "commands").mkdir(parents=True)
+
+        manager = ExtensionManager(project_dir)
+
+        # Install
+        manager.install_from_directory(
+            extension_dir,
+            "0.1.0",
+            register_commands=True
+        )
+
+        # Verify installation
+        assert manager.registry.is_installed("test-ext")
+        installed = manager.list_installed()
+        assert len(installed) == 1
+        assert installed[0]["id"] == "test-ext"
+
+        # Verify command registered
+        cmd_file = project_dir / ".claude" / "commands" / "speckit.test.hello.md"
+        assert cmd_file.exists()
+
+        # Verify registry has registered commands (now a dict keyed by agent)
+        metadata = manager.registry.get("test-ext")
+        registered_commands = metadata["registered_commands"]
+        # Check that the command is registered for at least one agent
+        assert any(
+            "speckit.test.hello" in cmds
+            for cmds in registered_commands.values()
+        )
+
+        # Remove
+        result = manager.remove("test-ext")
+        assert result is True
+
+        # Verify removal
+        assert not manager.registry.is_installed("test-ext")
+        assert not cmd_file.exists()
+        assert len(manager.list_installed()) == 0
+
+    def test_multiple_extensions(self, temp_dir, project_dir):
+        """Test installing multiple extensions."""
+        import yaml
+
+        # Create two extensions
+        for i in range(1, 3):
+            ext_dir = temp_dir / f"ext{i}"
+            ext_dir.mkdir()
+
+            manifest_data = {
+                "schema_version": "1.0",
+                "extension": {
+                    "id": f"ext{i}",
+                    "name": f"Extension {i}",
+                    "version": "1.0.0",
+                    "description": f"Extension {i}",
+                },
+                "requires": {"speckit_version": ">=0.1.0"},
+                "provides": {
+                    "commands": [
+                        {
+                            "name": f"speckit.ext{i}.cmd",
+                            "file": "commands/cmd.md",
+                        }
+                    ]
+                },
+            }
+
+            with open(ext_dir / "extension.yml", 'w') as f:
+                yaml.dump(manifest_data, f)
+
+            (ext_dir / "commands").mkdir()
+            (ext_dir / "commands" / "cmd.md").write_text("---\ndescription: Test\n---\nTest")
+
+        manager = ExtensionManager(project_dir)
+
+        # Install both
+        manager.install_from_directory(temp_dir / "ext1", "0.1.0", register_commands=False)
+        manager.install_from_directory(temp_dir / "ext2", "0.1.0", register_commands=False)
+
+        # Verify both installed
+        installed = manager.list_installed()
+        assert len(installed) == 2
+        assert {ext["id"] for ext in installed} == {"ext1", "ext2"}
+
+        # Remove first
+        manager.remove("ext1")
+
+        # Verify only second remains
+        installed = manager.list_installed()
+        assert len(installed) == 1
+        assert installed[0]["id"] == "ext2"
+
+
+# ===== Extension Catalog Tests =====
+
+
+class TestExtensionCatalog:
+    """Test extension catalog functionality."""
+
+    def test_catalog_initialization(self, temp_dir):
+        """Test catalog initialization."""
+        project_dir = temp_dir / "project"
+        project_dir.mkdir()
+        (project_dir / ".specify").mkdir()
+
+        catalog = ExtensionCatalog(project_dir)
+
+        assert catalog.project_root == project_dir
+        assert catalog.cache_dir == project_dir / ".specify" / "extensions" / ".cache"
+
+    def test_cache_directory_creation(self, temp_dir):
+        """Test catalog cache directory is created when fetching."""
+        project_dir = temp_dir / "project"
+        project_dir.mkdir()
+        (project_dir / ".specify").mkdir()
+
+        catalog = ExtensionCatalog(project_dir)
+
+        # Create mock catalog data
+        catalog_data = {
+            "schema_version": "1.0",
+            "extensions": {
+                "test-ext": {
+                    "name": "Test Extension",
+                    "id": "test-ext",
+                    "version": "1.0.0",
+                    "description": "Test",
+                }
+            },
+        }
+
+        # Manually save to cache to test cache reading
+        catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+        catalog.cache_file.write_text(json.dumps(catalog_data))
+        catalog.cache_metadata_file.write_text(
+            json.dumps(
+                {
+                    "cached_at": datetime.now(timezone.utc).isoformat(),
+                    "catalog_url": "http://test.com/catalog.json",
+                }
+            )
+        )
+
+        # Should use cache
+        result = catalog.fetch_catalog()
+        assert result == catalog_data
+
+    def test_cache_expiration(self, temp_dir):
+        """Test that expired cache is not used."""
+        project_dir = temp_dir / "project"
+        project_dir.mkdir()
+        (project_dir / ".specify").mkdir()
+
+        catalog = ExtensionCatalog(project_dir)
+
+        # Create expired cache
+        catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+        catalog_data = {"schema_version": "1.0", "extensions": {}}
+        catalog.cache_file.write_text(json.dumps(catalog_data))
+
+        # Set cache time to 2 hours ago (expired)
+        expired_time = datetime.now(timezone.utc).timestamp() - 7200
+        expired_datetime = datetime.fromtimestamp(expired_time, tz=timezone.utc)
+        catalog.cache_metadata_file.write_text(
+            json.dumps(
+                {
+                    "cached_at": expired_datetime.isoformat(),
+                    "catalog_url": "http://test.com/catalog.json",
+                }
+            )
+        )
+
+        # Cache should be invalid
+        assert not catalog.is_cache_valid()
+
+    def test_search_all_extensions(self, temp_dir):
+        """Test searching all extensions without filters."""
+        project_dir = temp_dir / "project"
+        project_dir.mkdir()
+        (project_dir / ".specify").mkdir()
+
+        catalog = ExtensionCatalog(project_dir)
+
+        # Create mock catalog
+        catalog_data = {
+            "schema_version": "1.0",
+            "extensions": {
+                "jira": {
+                    "name": "Jira Integration",
+                    "id": "jira",
+                    "version": "1.0.0",
+                    "description": "Jira integration",
+                    "author": "Stats Perform",
+                    "tags": ["issue-tracking", "jira"],
+                    "verified": True,
+                },
+                "linear": {
+                    "name": "Linear Integration",
+                    "id": "linear",
+                    "version": "0.9.0",
+                    "description": "Linear integration",
+                    "author": "Community",
+                    "tags": ["issue-tracking"],
+                    "verified": False,
+                },
+            },
+        }
+
+        # Save to cache
+        catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+        catalog.cache_file.write_text(json.dumps(catalog_data))
+        catalog.cache_metadata_file.write_text(
+            json.dumps(
+                {
+                    "cached_at": datetime.now(timezone.utc).isoformat(),
+                    "catalog_url": "http://test.com",
+                }
+            )
+        )
+
+        # Search without filters
+        results = catalog.search()
+        assert len(results) == 2
+
+    def test_search_by_query(self, temp_dir):
+        """Test searching by query text."""
+        project_dir = temp_dir / "project"
+        project_dir.mkdir()
+        (project_dir / ".specify").mkdir()
+
+        catalog = ExtensionCatalog(project_dir)
+
+        # Create mock catalog
+        catalog_data = {
+            "schema_version": "1.0",
+            "extensions": {
+                "jira": {
+                    "name": "Jira Integration",
+                    "id": "jira",
+                    "version": "1.0.0",
+                    "description": "Jira issue tracking",
+                    "tags": ["jira"],
+                },
+                "linear": {
+                    "name": "Linear Integration",
+                    "id": "linear",
+                    "version": "1.0.0",
+                    "description": "Linear project management",
+                    "tags": ["linear"],
+                },
+            },
+        }
+
+        catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+        catalog.cache_file.write_text(json.dumps(catalog_data))
+        catalog.cache_metadata_file.write_text(
+            json.dumps(
+                {
+                    "cached_at": datetime.now(timezone.utc).isoformat(),
+                    "catalog_url": "http://test.com",
+                }
+            )
+        )
+
+        # Search for "jira"
+        results = catalog.search(query="jira")
+        assert len(results) == 1
+        assert results[0]["id"] == "jira"
+
+    def test_search_by_tag(self, temp_dir):
+        """Test searching by tag."""
+        project_dir = temp_dir / "project"
+        project_dir.mkdir()
+        (project_dir / ".specify").mkdir()
+
+        catalog = ExtensionCatalog(project_dir)
+
+        # Create mock catalog
+        catalog_data = {
+            "schema_version": "1.0",
+            "extensions": {
+                "jira": {
+                    "name": "Jira",
+                    "id": "jira",
+                    "version": "1.0.0",
+                    "description": "Jira",
+                    "tags": ["issue-tracking", "jira"],
+                },
+                "linear": {
+                    "name": "Linear",
+                    "id": "linear",
+                    "version": "1.0.0",
+                    "description": "Linear",
+                    "tags": ["issue-tracking", "linear"],
+                },
+                "github": {
+                    "name": "GitHub",
+                    "id": "github",
+                    "version": "1.0.0",
+                    "description": "GitHub",
+                    "tags": ["vcs", "github"],
+                },
+            },
+        }
+
+        catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+        catalog.cache_file.write_text(json.dumps(catalog_data))
+        catalog.cache_metadata_file.write_text(
+            json.dumps(
+                {
+                    "cached_at": datetime.now(timezone.utc).isoformat(),
+                    "catalog_url": "http://test.com",
+                }
+            )
+        )
+
+        # Search by tag "issue-tracking"
+        results = catalog.search(tag="issue-tracking")
+        assert len(results) == 2
+        assert {r["id"] for r in results} == {"jira", "linear"}
+
+    def test_search_verified_only(self, temp_dir):
+        """Test searching verified extensions only."""
+        project_dir = temp_dir / "project"
+        project_dir.mkdir()
+        (project_dir / ".specify").mkdir()
+
+        catalog = ExtensionCatalog(project_dir)
+
+        # Create mock catalog
+        catalog_data = {
+            "schema_version": "1.0",
+            "extensions": {
+                "jira": {
+                    "name": "Jira",
+                    "id": "jira",
+                    "version": "1.0.0",
+                    "description": "Jira",
+                    "verified": True,
+                },
+                "linear": {
+                    "name": "Linear",
+                    "id": "linear",
+                    "version": "1.0.0",
+                    "description": "Linear",
+                    "verified": False,
+                },
+            },
+        }
+
+        catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+        catalog.cache_file.write_text(json.dumps(catalog_data))
+        catalog.cache_metadata_file.write_text(
+            json.dumps(
+                {
+                    "cached_at": datetime.now(timezone.utc).isoformat(),
+                    "catalog_url": "http://test.com",
+                }
+            )
+        )
+
+        # Search verified only
+        results = catalog.search(verified_only=True)
+        assert len(results) == 1
+        assert results[0]["id"] == "jira"
+
+    def test_get_extension_info(self, temp_dir):
+        """Test getting specific extension info."""
+        project_dir = temp_dir / "project"
+        project_dir.mkdir()
+        (project_dir / ".specify").mkdir()
+
+        catalog = ExtensionCatalog(project_dir)
+
+        # Create mock catalog
+        catalog_data = {
+            "schema_version": "1.0",
+            "extensions": {
+                "jira": {
+                    "name": "Jira Integration",
+                    "id": "jira",
+                    "version": "1.0.0",
+                    "description": "Jira integration",
+                    "author": "Stats Perform",
+                },
+            },
+        }
+
+        catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+        catalog.cache_file.write_text(json.dumps(catalog_data))
+        catalog.cache_metadata_file.write_text(
+            json.dumps(
+                {
+                    "cached_at": datetime.now(timezone.utc).isoformat(),
+                    "catalog_url": "http://test.com",
+                }
+            )
+        )
+
+        # Get extension info
+        info = catalog.get_extension_info("jira")
+        assert info is not None
+        assert info["id"] == "jira"
+        assert info["name"] == "Jira Integration"
+
+        # Non-existent extension
+        info = catalog.get_extension_info("nonexistent")
+        assert info is None
+
+    def test_clear_cache(self, temp_dir):
+        """Test clearing catalog cache."""
+        project_dir = temp_dir / "project"
+        project_dir.mkdir()
+        (project_dir / ".specify").mkdir()
+
+        catalog = ExtensionCatalog(project_dir)
+
+        # Create cache
+        catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+        catalog.cache_file.write_text("{}")
+        catalog.cache_metadata_file.write_text("{}")
+
+        assert catalog.cache_file.exists()
+        assert catalog.cache_metadata_file.exists()
+
+        # Clear cache
+        catalog.clear_cache()
+
+        assert not catalog.cache_file.exists()
+        assert not catalog.cache_metadata_file.exists()
Author	SHA1	Message	Date
Manfred Riem	465acd9024	fix: include 'src/**' path in release workflow triggers (#1646 ) Co-authored-by: Manfred Riem <mnriem@users.noreply.github.com>	2026-02-20 09:46:29 -06:00
dependabot[bot]	04fc3fd1ba	chore(deps): bump github/codeql-action from 3 to 4 (#1635 ) Bumps [github/codeql-action](https://github.com/github/codeql-action) from 3 to 4. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/v3...v4) --- updated-dependencies: - dependency-name: github/codeql-action dependency-version: '4' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-02-19 16:31:23 -06:00
Manfred Riem	24d76b5d92	Add pytest and Python linting (ruff) to CI (#1637 ) * feat: add GitHub Actions workflow for testing and linting Python code * fix: resolve ruff lint errors in specify_cli - Remove extraneous f-string prefixes (F541) - Split multi-statement lines (E701, E702) - Remove unused variable assignments (F841) - Remove ruff format check from CI workflow (format-only PR to follow) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: strip ANSI codes in ai-skills help text test The Rich/Typer CLI injects ANSI escape codes into option names in --help output, causing plain string matching to fail. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>	2026-02-19 16:21:58 -06:00
Manfred Riem	0f7d04b12b	feat: add pull request template for better contribution guidelines (#1634 )	2026-02-19 15:49:34 -06:00
Manfred Riem	9402ebd00a	Feat/ai skills (#1632 ) * implement ai-skills command line switch * fix: address review comments, remove breaking change for existing projects, add tests * fix: review comments * fix: review comments * fix: review comments * fix: review comments * fix: review comments, add test cases for all the agents * fix: review comments * fix: review comments * chore: trigger CI * chore: trigger CodeQL * ci: add CodeQL workflow for code scanning * ci: add actions language to CodeQL workflow, disable default setup --------- Co-authored-by: dhilipkumars <s.dhilipkumar@gmail.com>	2026-02-19 13:24:41 -06:00
dependabot[bot]	d410d188fc	chore(deps): bump actions/stale from 9 to 10 (#1623 ) Bumps [actions/stale](https://github.com/actions/stale) from 9 to 10. - [Release notes](https://github.com/actions/stale/releases) - [Changelog](https://github.com/actions/stale/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/stale/compare/v9...v10) --- updated-dependencies: - dependency-name: actions/stale dependency-version: '10' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-02-19 07:41:50 -06:00
Manfred Riem	686c91f94e	feat: add dependabot configuration for pip and GitHub Actions updates (#1622 )	2026-02-18 17:42:41 -06:00
Manfred Riem	22036732d8	Remove Maintainers section from README.md (#1618 )	2026-02-18 16:11:16 -06:00
Laurent Thiebault	c78f8423f6	fix: typo in plan-template.md (#1446 )	2026-02-17 07:22:43 -06:00
Hanzhi Yang	76cca34293	Feat: add a new agent: Google Anti Gravity (#1220 ) * Add support for Antigravity (agy) agent * fix a few things after gemini code update * Fix missed merge conflicts * As PR states it is IDE integration setting requires_cli to 'False' --------- Co-authored-by: Manfred Riem <manfred.riem@microsoft.com>	2026-02-12 12:31:48 -06:00
Copilot	9a1e3037b0	Add stale workflow for 180-day inactive issues and PRs (#1594 ) * Initial plan * Add stale issues and PRs workflow Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com> * Add 7-day grace period before closing stale items Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com> * Update stale timing: mark at 150 days, close at 180 days Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>	2026-02-11 16:03:17 -06:00
Michal Bachorik	f14a47ea7d	Add modular extension system (#1551 ) * Add modular extension system for Spec Kit Implement a complete extension system that allows third-party developers to extend Spec Kit functionality through plugins. ## Core Features - Extension discovery and loading from local and global directories - YAML-based extension manifest (extension.yml) with metadata and capabilities - Command extensions: custom slash commands with markdown templates - Hook system: pre/post hooks for generate, task, and sync operations - Extension catalog for discovering and installing community extensions - SPECKIT_CATALOG_URL environment variable for catalog URL override ## Installation Methods - Catalog install: `specify extension add <name>` - URL install: `specify extension add <name> --from <url>` - Dev install: `specify extension add --dev <path>` ## Implementation - ExtensionManager class for lifecycle management (load, enable, disable) - Support for extension dependencies and version constraints - Configuration layering (global → project → extension) - Hook conditions for conditional execution ## Documentation - RFC with design rationale and architecture decisions - API reference for extension developers - Development guide with examples - User guide for installing and managing extensions - Publishing guide for the extension catalog ## Included - Extension template for bootstrapping new extensions - Comprehensive test suite - Example catalog.json structure Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Update Jira extension to v2.1.0 in catalog Adds 2-level mode support (Epic → Stories only). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Address PR review feedback - Fix Zip Slip vulnerability in ZIP extraction with path validation - Fix keep_config option to actually preserve config files on removal - Add URL validation for SPECKIT_CATALOG_URL (HTTPS required, localhost exception) - Add security warning when installing from custom URLs (--from flag) - Empty catalog.json so organizations can ship their own catalogs - Fix markdown linter errors (MD040: add language to code blocks) - Remove redundant import and fix unused variables in tests - Add comment explaining empty except clause for backwards compatibility Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Add comprehensive organization catalog customization docs - Explain why default catalog is empty (org control) - Document how to create and host custom catalogs - Add catalog JSON schema reference - Include use cases: private extensions, curated catalogs, air-gapped environments - Add examples for combining catalog with direct installation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Fix test assertions for extension system data structures - Update test_config_backup_on_remove to use new subdirectory structure (.backup/test-ext/file.yml instead of .backup/test-ext-file.yml) - Update test_full_install_and_remove_workflow to handle registered_commands being a dict keyed by agent name instead of a flat list Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Address Copilot review feedback - Fix localhost URL check to use parsed.hostname instead of netloc.startswith() This correctly handles URLs with ports like localhost:8080 - Fix YAML indentation error in config-template.yml (line 57) - Fix double space typo in example.md (line 172) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Add catalog.example.json as reference for organizations The main catalog.json is intentionally empty so organizations can ship their own curated catalogs. This example file shows the expected schema and structure for creating organization-specific catalogs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Address remaining Copilot security and logic review feedback - Fix Zip Slip vulnerability by using relative_to() for safe path validation - Add HTTPS validation for extension download URLs - Backup both -config.yml and -config.local.yml files on remove - Normalize boolean values to lowercase for hook condition comparisons - Show non-default catalog warning only once per instance Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Ignoring linter for extensions directory --------- Co-authored-by: iamaeroplane <michal.bachorik@gmail.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: Manfred Riem <manfred.riem@microsoft.com>	2026-02-10 14:27:20 -06:00
Manfred Riem	36d97235ad	Fixes #1586 - .specify.specify path error (#1588 )	2026-02-10 08:20:39 -06:00
jin-joung	4afbd87abb	fix: preserve constitution.md during reinitialization (#1541 ) (#1553 ) Moves constitution template from memory/ to templates/ to prevent overwrites when spec-kit is reinitialized with a different AI agent. Changes: - Move memory/constitution.md to templates/constitution-template.md - Update CLI to copy template to memory/ only on first initialization - Update constitution command to reference correct paths with .specify/ prefix - Preserve existing constitution.md when reinitializing project The CLI now checks if .specify/memory/constitution.md exists: - If it exists: preserve it (no overwrite) - If it doesn't exist: copy from .specify/templates/constitution-template.md This allows users to customize their constitution without losing changes when adding support for additional AI agents or reinitializing. Fixes #1541 Co-authored-by: jjoung1128 <jinwoong.joung@gmail.com> Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>	2026-02-09 09:01:55 -06:00
amuzip	b562438df9	fix: resolve markdownlint errors across documentation (#1571 ) - Add language specifiers to fenced code blocks (bash, text) - Fix whitespace issues around code fences - Disable MD036 (emphasis as heading) for intentional warning text - Disable MD060 (table column style) for existing table formats Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>	2026-02-09 08:48:56 -06:00
Den Delimarsky	9111699cd2	Merge pull request #1288 from github/localden/updates Small QOL updates	2025-12-04 11:58:04 -08:00