chore(deps): bump actions/setup-python from 5 to 6 (#1710)

Bumps [actions/setup-python](https://github.com/actions/setup-python) from 5 to 6.
- [Release notes](https://github.com/actions/setup-python/releases)
- [Commits](https://github.com/actions/setup-python/compare/v5...v6)

---
updated-dependencies:
- dependency-name: actions/setup-python
  dependency-version: '6'
  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>

.devcontainer/devcontainer.json

@@ -0,0 +1,77 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/python
+{
+	"name": "SpecKitDevContainer",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/python:3.13-trixie", // based on Debian "Trixie" (13)
+	"features": {
+		"ghcr.io/devcontainers/features/common-utils:2": {
+			"installZsh": true,
+			"installOhMyZsh": true,
+			"installOhMyZshConfig": true,
+			"upgradePackages": true,
+			"username": "devcontainer",
+			"userUid": "automatic",
+			"userGid": "automatic"
+		},
+		"ghcr.io/devcontainers/features/dotnet:2": {
+			"version": "lts"
+		},
+		"ghcr.io/devcontainers/features/git:1": {
+			"ppa": true,
+			"version": "latest"
+		},
+		"ghcr.io/devcontainers/features/node": {
+			"version": "lts"
+		}
+	},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+  "forwardPorts": [
+	8080 // for Spec-Kit documentation site
+  ],
+  "containerUser": "devcontainer",
+  "updateRemoteUserUID": true,
+  "postCreateCommand": "chmod +x ./.devcontainer/post-create.sh && ./.devcontainer/post-create.sh",
+  "postStartCommand": "git config --global --add safe.directory ${containerWorkspaceFolder}",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+		"mhutchie.git-graph",
+		"eamodio.gitlens",
+		"anweber.reveal-button",
+		"chrisdias.promptboost",
+		// Github Copilot
+		"GitHub.copilot",
+		"GitHub.copilot-chat",
+		// Codex
+		"openai.chatgpt",
+		// Kilo Code
+		"kilocode.Kilo-Code",
+		// Roo Code
+		"RooVeterinaryInc.roo-cline",
+		// Amazon Developer Q
+		"AmazonWebServices.amazon-q-vscode",
+		// Claude Code
+		"anthropic.claude-code"
+	],
+      "settings": {
+		"debug.javascript.autoAttachFilter": "disabled", // fix running commands in integrated terminal
+
+		// Specify settings for Github Copilot
+		"git.autofetch": true,
+		"chat.promptFilesRecommendations": {
+			"speckit.constitution": true,
+			"speckit.specify": true,
+			"speckit.plan": true,
+			"speckit.tasks": true,
+			"speckit.implement": true
+		},
+		"chat.tools.terminal.autoApprove": {
+			".specify/scripts/bash/": true,
+			".specify/scripts/powershell/": true
+		}
+      }
+    }
+  }
+}

.devcontainer/post-create.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+
+# Exit immediately on error, treat unset variables as an error, and fail if any command in a pipeline fails.
+set -euo pipefail
+
+# Function to run a command and show logs only on error
+run_command() {
+    local command_to_run="$*"
+    local output
+    local exit_code
+    
+    # Capture all output (stdout and stderr)
+    output=$(eval "$command_to_run" 2>&1) || exit_code=$?
+    exit_code=${exit_code:-0}
+    
+    if [ $exit_code -ne 0 ]; then
+        echo -e "\033[0;31m[ERROR] Command failed (Exit Code $exit_code): $command_to_run\033[0m" >&2
+        echo -e "\033[0;31m$output\033[0m" >&2
+        
+        exit $exit_code
+    fi
+}
+
+# Installing CLI-based AI Agents
+
+echo -e "\n🤖 Installing Copilot CLI..."
+run_command "npm install -g @github/copilot@latest"
+echo "✅ Done"
+
+echo -e "\n🤖 Installing Claude CLI..."
+run_command "npm install -g @anthropic-ai/claude-code@latest"
+echo "✅ Done"
+
+echo -e "\n🤖 Installing Codex CLI..."
+run_command "npm install -g @openai/codex@latest"
+echo "✅ Done"
+
+echo -e "\n🤖 Installing Gemini CLI..."
+run_command "npm install -g @google/gemini-cli@latest"
+echo "✅ Done"
+
+echo -e "\n🤖 Installing Augie CLI..."
+run_command "npm install -g @augmentcode/auggie@latest"
+echo "✅ Done"
+
+echo -e "\n🤖 Installing Qwen Code CLI..."
+run_command "npm install -g @qwen-code/qwen-code@latest"
+echo "✅ Done"
+
+echo -e "\n🤖 Installing OpenCode CLI..."
+run_command "npm install -g opencode-ai@latest"
+echo "✅ Done"
+
+echo -e "\n🤖 Installing Amazon Q CLI..."
+# 👉🏾 https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-verify-download.html
+
+run_command "curl --proto '=https' --tlsv1.2 -sSf 'https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip' -o 'q.zip'"
+run_command "curl --proto '=https' --tlsv1.2 -sSf 'https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip.sig' -o 'q.zip.sig'"
+cat > amazonq-public-key.asc << 'EOF'
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mDMEZig60RYJKwYBBAHaRw8BAQdAy/+G05U5/EOA72WlcD4WkYn5SInri8pc4Z6D
+BKNNGOm0JEFtYXpvbiBRIENMSSBUZWFtIDxxLWNsaUBhbWF6b24uY29tPoiZBBMW
+CgBBFiEEmvYEF+gnQskUPgPsUNx6jcJMVmcFAmYoOtECGwMFCQPCZwAFCwkIBwIC
+IgIGFQoJCAsCBBYCAwECHgcCF4AACgkQUNx6jcJMVmef5QD/QWWEGG/cOnbDnp68
+SJXuFkwiNwlH2rPw9ZRIQMnfAS0A/0V6ZsGB4kOylBfc7CNfzRFGtovdBBgHqA6P
+zQ/PNscGuDgEZig60RIKKwYBBAGXVQEFAQEHQC4qleONMBCq3+wJwbZSr0vbuRba
+D1xr4wUPn4Avn4AnAwEIB4h+BBgWCgAmFiEEmvYEF+gnQskUPgPsUNx6jcJMVmcF
+AmYoOtECGwwFCQPCZwAACgkQUNx6jcJMVmchMgEA6l3RveCM0YHAGQaSFMkguoAo
+vK6FgOkDawgP0NPIP2oA/jIAO4gsAntuQgMOsPunEdDeji2t+AhV02+DQIsXZpoB
+=f8yY
+-----END PGP PUBLIC KEY BLOCK-----
+EOF
+run_command "gpg --batch --import amazonq-public-key.asc"
+run_command "gpg --verify q.zip.sig q.zip"
+run_command "unzip -q q.zip"
+run_command "chmod +x ./q/install.sh"
+run_command "./q/install.sh --no-confirm"
+run_command "rm -rf ./q q.zip q.zip.sig amazonq-public-key.asc"
+echo "✅ Done"
+
+echo -e "\n🤖 Installing CodeBuddy CLI..."
+run_command "npm install -g @tencent-ai/codebuddy-code@latest"
+echo "✅ Done"
+
+# Installing UV (Python package manager)
+echo -e "\n🐍 Installing UV - Python Package Manager..."
+run_command "pipx install uv"
+echo "✅ Done"
+
+# Installing DocFx (for documentation site)
+echo -e "\n📚 Installing DocFx..."
+run_command "dotnet tool update -g docfx"
+echo "✅ Done"
+
+echo -e "\n🧹 Cleaning cache..."
+run_command "sudo apt-get autoclean"
+run_command "sudo apt-get clean"
+
+echo "✅ Setup completed. Happy coding! 🚀"

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/CODEOWNERS

@@ -1,2 +1,3 @@
 # Global code owner
-* @localden
+* @mnriem
+

.github/ISSUE_TEMPLATE/agent_request.yml

@@ -0,0 +1,141 @@
+name: Agent Request
+description: Request support for a new AI agent/assistant in Spec Kit
+title: "[Agent]: Add support for "
+labels: ["agent-request", "enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for requesting a new agent! Before submitting, please check if the agent is already supported.
+        
+        **Currently supported agents**: Claude Code, Gemini CLI, GitHub Copilot, Cursor, Qwen Code, opencode, Codex CLI, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy, Qoder CLI, Amazon Q Developer CLI, Amp, SHAI, IBM Bob, Antigravity
+
+  - type: input
+    id: agent-name
+    attributes:
+      label: Agent Name
+      description: What is the name of the AI agent/assistant?
+      placeholder: "e.g., SuperCoder AI"
+    validations:
+      required: true
+
+  - type: input
+    id: website
+    attributes:
+      label: Official Website
+      description: Link to the agent's official website or documentation
+      placeholder: "https://..."
+    validations:
+      required: true
+
+  - type: dropdown
+    id: agent-type
+    attributes:
+      label: Agent Type
+      description: How is the agent accessed?
+      options:
+        - CLI tool (command-line interface)
+        - IDE extension/plugin
+        - Both CLI and IDE
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: cli-command
+    attributes:
+      label: CLI Command (if applicable)
+      description: What command is used to invoke the agent from terminal?
+      placeholder: "e.g., supercode, ai-assistant"
+
+  - type: input
+    id: install-method
+    attributes:
+      label: Installation Method
+      description: How is the agent installed?
+      placeholder: "e.g., npm install -g supercode, pip install supercode, IDE marketplace"
+    validations:
+      required: true
+
+  - type: textarea
+    id: command-structure
+    attributes:
+      label: Command/Workflow Structure
+      description: How does the agent define custom commands or workflows?
+      placeholder: |
+        - Command file format (Markdown, YAML, TOML, etc.)
+        - Directory location (e.g., .supercode/commands/)
+        - Example command file structure
+    validations:
+      required: true
+
+  - type: textarea
+    id: argument-pattern
+    attributes:
+      label: Argument Passing Pattern
+      description: How does the agent handle arguments in commands?
+      placeholder: |
+        e.g., Uses {{args}}, $ARGUMENTS, %ARGS%, or other placeholder format
+        Example: "Run test suite with {{args}}"
+
+  - type: dropdown
+    id: popularity
+    attributes:
+      label: Popularity/Usage
+      description: How widely is this agent used?
+      options:
+        - Widely used (thousands+ of users)
+        - Growing adoption (hundreds of users)
+        - New/emerging (less than 100 users)
+        - Unknown
+    validations:
+      required: true
+
+  - type: textarea
+    id: documentation
+    attributes:
+      label: Documentation Links
+      description: Links to relevant documentation for custom commands/workflows
+      placeholder: |
+        - Command documentation: https://...
+        - API/CLI reference: https://...
+        - Examples: https://...
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: Why do you want this agent supported in Spec Kit?
+      placeholder: Explain your workflow and how this agent fits into your development process
+    validations:
+      required: true
+
+  - type: textarea
+    id: example-command
+    attributes:
+      label: Example Command File
+      description: If possible, provide an example of a command file for this agent
+      render: markdown
+      placeholder: |
+        ```toml
+        description = "Example command"
+        prompt = "Do something with {{args}}"
+        ```
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      description: Are you willing to help implement support for this agent?
+      options:
+        - label: I can help test the integration
+        - label: I can provide example command files
+        - label: I can help with documentation
+        - label: I can submit a pull request for the integration
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any other relevant information about this agent
+      placeholder: Screenshots, community links, comparison to existing agents, etc.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,118 @@
+name: Bug Report
+description: Report a bug or unexpected behavior in Specify CLI or Spec Kit
+title: "[Bug]: "
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the sections below to help us diagnose and fix the issue.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: What went wrong?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior
+      placeholder: |
+        1. Run command '...'
+        2. Execute script '...'
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+      placeholder: Describe the expected outcome
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened?
+      placeholder: Describe what happened instead
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Specify CLI Version
+      description: "Run `specify version` or `pip show spec-kit`"
+      placeholder: "e.g., 1.3.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: ai-agent
+    attributes:
+      label: AI Agent
+      description: Which AI agent are you using?
+      options:
+        - Claude Code
+        - Gemini CLI
+        - GitHub Copilot
+        - Cursor
+        - Qwen Code
+        - opencode
+        - Codex CLI
+        - Windsurf
+        - Kilo Code
+        - Auggie CLI
+        - Roo Code
+        - CodeBuddy
+        - Qoder CLI
+        - Amazon Q Developer CLI
+        - Amp
+        - SHAI
+        - IBM Bob
+        - Antigravity
+        - Not applicable
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      description: Your operating system and version
+      placeholder: "e.g., macOS 14.2, Ubuntu 22.04, Windows 11"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python Version
+      description: "Run `python --version` or `python3 --version`"
+      placeholder: "e.g., Python 3.11.5"
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error Logs
+      description: Please paste any relevant error messages or logs
+      render: shell
+      placeholder: Paste error output here
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem
+      placeholder: Screenshots, related issues, workarounds attempted, etc.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,17 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 General Discussion
+    url: https://github.com/github/spec-kit/discussions
+    about: Ask questions, share ideas, or discuss Spec-Driven Development
+  - name: 📖 Documentation
+    url: https://github.com/github/spec-kit/blob/main/README.md
+    about: Read the Spec Kit documentation and guides
+  - name: 🛠️ Extension Development Guide
+    url: https://github.com/manfredseee/spec-kit/blob/main/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
+    about: Learn how to develop and publish Spec Kit extensions
+  - name: 🤝 Contributing Guide
+    url: https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md
+    about: Learn how to contribute to Spec Kit
+  - name: 🔒 Security Issues
+    url: https://github.com/github/spec-kit/blob/main/SECURITY.md
+    about: Report security vulnerabilities privately

.github/ISSUE_TEMPLATE/extension_submission.yml

@@ -0,0 +1,280 @@
+name: Extension Submission
+description: Submit your extension to the Spec Kit catalog
+title: "[Extension]: Add "
+labels: ["extension-submission", "enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for contributing an extension! This template helps you submit your extension to the community catalog.
+        
+        **Before submitting:**
+        - Review the [Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md)
+        - Ensure your extension has a valid `extension.yml` manifest
+        - Create a GitHub release with a version tag (e.g., v1.0.0)
+        - Test installation: `specify extension add --from <your-release-url>`
+
+  - type: input
+    id: extension-id
+    attributes:
+      label: Extension ID
+      description: Unique extension identifier (lowercase with hyphens only)
+      placeholder: "e.g., jira-integration"
+    validations:
+      required: true
+
+  - type: input
+    id: extension-name
+    attributes:
+      label: Extension Name
+      description: Human-readable extension name
+      placeholder: "e.g., Jira Integration"
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Semantic version number
+      placeholder: "e.g., 1.0.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Brief description of what your extension does (under 200 characters)
+      placeholder: Integrates Jira issue tracking with Spec Kit workflows for seamless task management
+    validations:
+      required: true
+
+  - type: input
+    id: author
+    attributes:
+      label: Author
+      description: Your name or organization
+      placeholder: "e.g., John Doe or Acme Corp"
+    validations:
+      required: true
+
+  - type: input
+    id: repository
+    attributes:
+      label: Repository URL
+      description: GitHub repository URL for your extension
+      placeholder: "https://github.com/your-org/spec-kit-your-extension"
+    validations:
+      required: true
+
+  - type: input
+    id: download-url
+    attributes:
+      label: Download URL
+      description: URL to the GitHub release archive (e.g., v1.0.0.zip)
+      placeholder: "https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip"
+    validations:
+      required: true
+
+  - type: input
+    id: license
+    attributes:
+      label: License
+      description: Open source license type
+      placeholder: "e.g., MIT, Apache-2.0"
+    validations:
+      required: true
+
+  - type: input
+    id: homepage
+    attributes:
+      label: Homepage (optional)
+      description: Link to extension homepage or documentation site
+      placeholder: "https://..."
+
+  - type: input
+    id: documentation
+    attributes:
+      label: Documentation URL (optional)
+      description: Link to detailed documentation
+      placeholder: "https://github.com/your-org/spec-kit-your-extension/blob/main/docs/"
+
+  - type: input
+    id: changelog
+    attributes:
+      label: Changelog URL (optional)
+      description: Link to changelog file
+      placeholder: "https://github.com/your-org/spec-kit-your-extension/blob/main/CHANGELOG.md"
+
+  - type: input
+    id: speckit-version
+    attributes:
+      label: Required Spec Kit Version
+      description: Minimum Spec Kit version required
+      placeholder: "e.g., >=0.1.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: required-tools
+    attributes:
+      label: Required Tools (optional)
+      description: List any external tools or dependencies required
+      placeholder: |
+        - jira-cli (>=1.0.0) - required
+        - python (>=3.8) - optional
+      render: markdown
+
+  - type: input
+    id: commands-count
+    attributes:
+      label: Number of Commands
+      description: How many commands does your extension provide?
+      placeholder: "e.g., 3"
+    validations:
+      required: true
+
+  - type: input
+    id: hooks-count
+    attributes:
+      label: Number of Hooks (optional)
+      description: How many hooks does your extension provide?
+      placeholder: "e.g., 0"
+
+  - type: textarea
+    id: tags
+    attributes:
+      label: Tags
+      description: 2-5 relevant tags (lowercase, separated by commas)
+      placeholder: "issue-tracking, jira, atlassian, automation"
+    validations:
+      required: true
+
+  - type: textarea
+    id: features
+    attributes:
+      label: Key Features
+      description: List the main features and capabilities of your extension
+      placeholder: |
+        - Create Jira issues from specs
+        - Sync task status with Jira
+        - Link specs to existing issues
+        - Generate Jira reports
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: testing
+    attributes:
+      label: Testing Checklist
+      description: Confirm that your extension has been tested
+      options:
+        - label: Extension installs successfully via download URL
+          required: true
+        - label: All commands execute without errors
+          required: true
+        - label: Documentation is complete and accurate
+          required: true
+        - label: No security vulnerabilities identified
+          required: true
+        - label: Tested on at least one real project
+          required: true
+
+  - type: checkboxes
+    id: requirements
+    attributes:
+      label: Submission Requirements
+      description: Verify your extension meets all requirements
+      options:
+        - label: Valid `extension.yml` manifest included
+          required: true
+        - label: README.md with installation and usage instructions
+          required: true
+        - label: LICENSE file included
+          required: true
+        - label: GitHub release created with version tag
+          required: true
+        - label: All command files exist and are properly formatted
+          required: true
+        - label: Extension ID follows naming conventions (lowercase-with-hyphens)
+          required: true
+
+  - type: textarea
+    id: testing-details
+    attributes:
+      label: Testing Details
+      description: Describe how you tested your extension
+      placeholder: |
+        **Tested on:**
+        - macOS 14.0 with Spec Kit v0.1.0
+        - Linux Ubuntu 22.04 with Spec Kit v0.1.0
+        
+        **Test project:** [Link or description]
+        
+        **Test scenarios:**
+        1. Installed extension
+        2. Configured settings
+        3. Ran all commands
+        4. Verified outputs
+    validations:
+      required: true
+
+  - type: textarea
+    id: example-usage
+    attributes:
+      label: Example Usage
+      description: Provide a simple example of using your extension
+      render: markdown
+      placeholder: |
+        ```bash
+        # Install extension
+        specify extension add --from https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip
+        
+        # Use a command
+        /speckit.your-extension.command-name arg1 arg2
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: catalog-entry
+    attributes:
+      label: Proposed Catalog Entry
+      description: Provide the JSON entry for catalog.json (helps reviewers)
+      render: json
+      placeholder: |
+        {
+          "your-extension": {
+            "name": "Your Extension",
+            "id": "your-extension",
+            "description": "Brief description",
+            "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",
+            "license": "MIT",
+            "requires": {
+              "speckit_version": ">=0.1.0"
+            },
+            "provides": {
+              "commands": 3
+            },
+            "tags": ["category", "tool"],
+            "verified": false,
+            "downloads": 0,
+            "stars": 0,
+            "created_at": "2026-02-20T00:00:00Z",
+            "updated_at": "2026-02-20T00:00:00Z"
+          }
+        }
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any other information that would help reviewers
+      placeholder: Screenshots, demo videos, links to related projects, etc.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,104 @@
+name: Feature Request
+description: Suggest a new feature or enhancement for Specify CLI or Spec Kit
+title: "[Feature]: "
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please provide details below to help us understand and evaluate your request.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: Is your feature request related to a problem? Please describe.
+      placeholder: "I'm frustrated when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like
+      placeholder: What would you like to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Have you considered any alternative solutions or workarounds?
+      placeholder: What other approaches might work?
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which component does this feature relate to?
+      options:
+        - Specify CLI (initialization, commands)
+        - Spec templates (BDD, Testing Strategy, etc.)
+        - Agent integrations (command files, workflows)
+        - Scripts (Bash/PowerShell utilities)
+        - Documentation
+        - CI/CD workflows
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: ai-agent
+    attributes:
+      label: AI Agent (if applicable)
+      description: Does this feature relate to a specific AI agent?
+      options:
+        - All agents
+        - Claude Code
+        - Gemini CLI
+        - GitHub Copilot
+        - Cursor
+        - Qwen Code
+        - opencode
+        - Codex CLI
+        - Windsurf
+        - Kilo Code
+        - Auggie CLI
+        - Roo Code
+        - CodeBuddy
+        - Qoder CLI
+        - Amazon Q Developer CLI
+        - Amp
+        - SHAI
+        - IBM Bob
+        - Antigravity
+        - Not applicable
+
+  - type: textarea
+    id: use-cases
+    attributes:
+      label: Use Cases
+      description: Describe specific use cases where this feature would be valuable
+      placeholder: |
+        1. When working on large projects...
+        2. During spec review...
+        3. When integrating with CI/CD...
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance Criteria
+      description: How would you know this feature is complete and working?
+      placeholder: |
+        - [ ] Feature does X
+        - [ ] Documentation is updated
+        - [ ] Works with all supported agents
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Add any other context, screenshots, or examples
+      placeholder: Links to similar features, mockups, related discussions, etc.

.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"): -->
+

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

.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 }}"

.github/workflows/docs.yml

@@ -0,0 +1,68 @@
+# Build and deploy DocFX documentation to GitHub Pages
+name: Deploy Documentation to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+    paths:
+      - 'docs/**'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # Fetch all history for git info
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '8.x'
+
+      - name: Setup DocFX
+        run: dotnet tool install -g docfx
+
+      - name: Build with DocFX
+        run: |
+          cd docs
+          docfx docfx.json
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs/_site'
+
+  # Deploy job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

.github/workflows/lint.yml

@@ -0,0 +1,22 @@
+name: Lint
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Run markdownlint-cli2
+        uses: DavidAnson/markdownlint-cli2-action@v19
+        with:
+          globs: |
+            '**/*.md'
+            !extensions/**/*.md

.github/workflows/manual-release.yml

@@ -1,191 +0,0 @@
-name: Manual Release
-
-on:
-  workflow_dispatch:
-    inputs:
-      version_bump:
-        description: 'Version bump type'
-        required: true
-        default: 'patch'
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-
-jobs:
-  manual_release:
-    runs-on: ubuntu-latest
-    
-    permissions:
-      contents: write
-      
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-        
-    - name: Calculate new version
-      id: version
-      run: |
-        # Get the latest tag, or use v0.0.0 if no tags exist
-        LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
-        echo "latest_tag=$LATEST_TAG" >> $GITHUB_OUTPUT
-        
-        # Extract version number
-        VERSION=$(echo $LATEST_TAG | sed 's/v//')
-        IFS='.' read -ra VERSION_PARTS <<< "$VERSION"
-        MAJOR=${VERSION_PARTS[0]:-0}
-        MINOR=${VERSION_PARTS[1]:-0}
-        PATCH=${VERSION_PARTS[2]:-0}
-        
-        # Increment based on input
-        case "${{ github.event.inputs.version_bump }}" in
-          "major")
-            MAJOR=$((MAJOR + 1))
-            MINOR=0
-            PATCH=0
-            ;;
-          "minor")
-            MINOR=$((MINOR + 1))
-            PATCH=0
-            ;;
-          "patch")
-            PATCH=$((PATCH + 1))
-            ;;
-        esac
-        
-        NEW_VERSION="v$MAJOR.$MINOR.$PATCH"
-        echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
-        echo "New version will be: $NEW_VERSION (was $LATEST_TAG)"
-        
-    - name: Create release package
-      run: |
-        # Create base package directory structure
-        mkdir -p sdd-package-base
-        
-        # Copy common folders to base
-        echo "Packaging SDD common components..."
-        
-        if [ -d "memory" ]; then
-          cp -r memory sdd-package-base/
-          echo "✓ Copied memory folder ($(find memory -type f | wc -l) files)"
-        else
-          echo "⚠️ memory folder not found"
-        fi
-        
-        if [ -d "scripts" ]; then
-          cp -r scripts sdd-package-base/
-          echo "✓ Copied scripts folder ($(find scripts -type f | wc -l) files)"
-        else
-          echo "⚠️ scripts folder not found"
-        fi
-        
-        # Create Claude Code package
-        echo "Creating Claude Code package..."
-        mkdir -p sdd-claude-package
-        cp -r sdd-package-base/* sdd-claude-package/
-        if [ -d "agent_templates/claude" ]; then
-          cp -r agent_templates/claude sdd-claude-package/.claude
-          echo "✓ Added Claude Code commands ($(find agent_templates/claude -type f | wc -l) files)"
-        else
-          echo "⚠️ agent_templates/claude folder not found"
-        fi
-        
-        # Create Gemini CLI package
-        echo "Creating Gemini CLI package..."
-        mkdir -p sdd-gemini-package
-        cp -r sdd-package-base/* sdd-gemini-package/
-        if [ -d "agent_templates/gemini" ]; then
-          cp -r agent_templates/gemini sdd-gemini-package/.gemini
-          # Move GEMINI.md to root for easier access
-          if [ -f "sdd-gemini-package/.gemini/GEMINI.md" ]; then
-            mv sdd-gemini-package/.gemini/GEMINI.md sdd-gemini-package/GEMINI.md
-            echo "✓ Moved GEMINI.md to root of Gemini package"
-          fi
-          # Remove empty .gemini folder if it only contained GEMINI.md
-          if [ -d "sdd-gemini-package/.gemini" ] && [ -z "$(find sdd-gemini-package/.gemini -type f)" ]; then
-            rm -rf sdd-gemini-package/.gemini
-            echo "✓ Removed empty .gemini folder"
-          fi
-          echo "✓ Added Gemini CLI commands ($(find agent_templates/gemini -type f | wc -l) files)"
-        else
-          echo "⚠️ agent_templates/gemini folder not found"
-        fi
-        
-        # Create GitHub Copilot package
-        echo "Creating GitHub Copilot package..."
-        mkdir -p sdd-copilot-package
-        cp -r sdd-package-base/* sdd-copilot-package/
-        if [ -d "agent_templates/copilot" ]; then
-          mkdir -p sdd-copilot-package/.github
-          cp -r agent_templates/copilot/* sdd-copilot-package/.github/
-          echo "✓ Added Copilot instructions to .github ($(find agent_templates/copilot -type f | wc -l) files)"
-        else
-          echo "⚠️ agent_templates/copilot folder not found"
-        fi
-        
-        # Create archive files for each package
-        echo "Creating archive files..."
-        cd sdd-claude-package && zip -r ../spec-kit-template-claude-${{ steps.version.outputs.new_version }}.zip . && cd ..
-        
-        cd sdd-gemini-package && zip -r ../spec-kit-template-gemini-${{ steps.version.outputs.new_version }}.zip . && cd ..
-        
-        cd sdd-copilot-package && zip -r ../spec-kit-template-copilot-${{ steps.version.outputs.new_version }}.zip . && cd ..
-        
-        echo ""
-        echo "📦 Packages created:"
-        echo "Claude: $(ls -lh spec-kit-template-claude-*.zip | awk '{print $5}')"
-        echo "Gemini: $(ls -lh spec-kit-template-gemini-*.zip | awk '{print $5}')"
-        echo "Copilot: $(ls -lh spec-kit-template-copilot-*.zip | awk '{print $5}')"
-        echo "Copilot: $(ls -lh sdd-template-copilot-*.zip | awk '{print $5}')"
-        
-    - name: Generate detailed release notes
-      run: |
-        LAST_TAG=${{ steps.version.outputs.latest_tag }}
-        
-        # Get commit range
-        if [ "$LAST_TAG" = "v0.0.0" ]; then
-          COMMIT_RANGE="HEAD~10..HEAD"
-          COMMITS=$(git log --oneline --pretty=format:"- %s" $COMMIT_RANGE 2>/dev/null || echo "- Initial release")
-        else
-          COMMIT_RANGE="$LAST_TAG..HEAD"
-          COMMITS=$(git log --oneline --pretty=format:"- %s" $COMMIT_RANGE 2>/dev/null || echo "- No changes since last release")
-        fi
-        
-        # Count files in each directory
-        CLAUDE_COUNT=$(find agent_templates/claude -type f 2>/dev/null | wc -l || echo "0")
-        GEMINI_COUNT=$(find agent_templates/gemini -type f 2>/dev/null | wc -l || echo "0")
-        COPILOT_COUNT=$(find agent_templates/copilot -type f 2>/dev/null | wc -l || echo "0")
-        MEMORY_COUNT=$(find memory -type f 2>/dev/null | wc -l || echo "0")
-        SCRIPTS_COUNT=$(find scripts -type f 2>/dev/null | wc -l || echo "0")
-        
-        cat > release_notes.md << EOF
-        Template release ${{ steps.version.outputs.new_version }}
-        
-        Updated specification-driven development templates for GitHub Copilot, Claude Code, and Gemini CLI.
-        
-        Download the template for your preferred AI assistant:
-        - spec-kit-template-copilot-${{ steps.version.outputs.new_version }}.zip
-        - spec-kit-template-claude-${{ steps.version.outputs.new_version }}.zip
-        - spec-kit-template-gemini-${{ steps.version.outputs.new_version }}.zip  
-        
-        Changes since $LAST_TAG:
-        $COMMITS
-        EOF
-        
-    - name: Create GitHub Release
-      run: |
-        # Remove 'v' prefix from version for release title
-        VERSION_NO_V=${{ steps.version.outputs.new_version }}
-        VERSION_NO_V=${VERSION_NO_V#v}
-        
-        gh release create ${{ steps.version.outputs.new_version }} \
-          spec-kit-template-copilot-${{ steps.version.outputs.new_version }}.zip \
-          spec-kit-template-claude-${{ steps.version.outputs.new_version }}.zip \
-          spec-kit-template-gemini-${{ steps.version.outputs.new_version }}.zip \
-          --title "Spec Kit Templates - $VERSION_NO_V" \
-          --notes-file release_notes.md
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -3,220 +3,67 @@ name: Create Release
 on:
   push:
     branches: [ main ]
+    paths:
+      - 'memory/**'
+      - 'scripts/**'
+      - 'src/**'
+      - 'templates/**'
+      - '.github/workflows/**'
   workflow_dispatch:
 
 jobs:
   release:
     runs-on: ubuntu-latest
-    
     permissions:
       contents: write
       pull-requests: write
-      
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-        token: ${{ secrets.GITHUB_TOKEN }}
-        
-    - name: Get latest tag
-      id: get_tag
-      run: |
-        # Get the latest tag, or use v0.0.0 if no tags exist
-        LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
-        echo "latest_tag=$LATEST_TAG" >> $GITHUB_OUTPUT
-        
-        # Extract version number and increment
-        VERSION=$(echo $LATEST_TAG | sed 's/v//')
-        IFS='.' read -ra VERSION_PARTS <<< "$VERSION"
-        MAJOR=${VERSION_PARTS[0]:-0}
-        MINOR=${VERSION_PARTS[1]:-0}
-        PATCH=${VERSION_PARTS[2]:-0}
-        
-        # Increment patch version
-        PATCH=$((PATCH + 1))
-        NEW_VERSION="v$MAJOR.$MINOR.$PATCH"
-        
-        echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
-        echo "New version will be: $NEW_VERSION"
-        
-    - name: Check if release already exists
-      id: check_release
-      run: |
-        if gh release view ${{ steps.get_tag.outputs.new_version }} >/dev/null 2>&1; then
-          echo "exists=true" >> $GITHUB_OUTPUT
-          echo "Release ${{ steps.get_tag.outputs.new_version }} already exists, skipping..."
-        else
-          echo "exists=false" >> $GITHUB_OUTPUT
-          echo "Release ${{ steps.get_tag.outputs.new_version }} does not exist, proceeding..."
-        fi
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        
-    - name: Create release package
-      if: steps.check_release.outputs.exists == 'false'
-      run: |
-        # Create base package directory structure
-        mkdir -p sdd-package-base
-        
-        # Copy common folders to base
-        if [ -d "memory" ]; then
-          cp -r memory sdd-package-base/
-          echo "Copied memory folder"
-        fi
-        
-        if [ -d "scripts" ]; then
-          cp -r scripts sdd-package-base/
-          echo "Copied scripts folder"
-        fi
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Get latest tag
+        id: get_tag
+        run: |
+          chmod +x .github/workflows/scripts/get-next-version.sh
+          .github/workflows/scripts/get-next-version.sh
+      - name: Check if release already exists
+        id: check_release
+        run: |
+          chmod +x .github/workflows/scripts/check-release-exists.sh
+          .github/workflows/scripts/check-release-exists.sh ${{ steps.get_tag.outputs.new_version }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Create release package variants
+        if: steps.check_release.outputs.exists == 'false'
+        run: |
+          chmod +x .github/workflows/scripts/create-release-packages.sh
+          .github/workflows/scripts/create-release-packages.sh ${{ steps.get_tag.outputs.new_version }}
+      - name: Generate release notes
+        if: steps.check_release.outputs.exists == 'false'
+        id: release_notes
+        run: |
+          chmod +x .github/workflows/scripts/generate-release-notes.sh
+          .github/workflows/scripts/generate-release-notes.sh ${{ steps.get_tag.outputs.new_version }} ${{ steps.get_tag.outputs.latest_tag }}
+      - name: Create GitHub Release
+        if: steps.check_release.outputs.exists == 'false'
+        run: |
+          chmod +x .github/workflows/scripts/create-github-release.sh
+          .github/workflows/scripts/create-github-release.sh ${{ steps.get_tag.outputs.new_version }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Update version in pyproject.toml (for release artifacts only)
+        if: steps.check_release.outputs.exists == 'false'
+        run: |
+          chmod +x .github/workflows/scripts/update-version.sh
+          .github/workflows/scripts/update-version.sh ${{ steps.get_tag.outputs.new_version }}
+      - name: Commit version bump to main
+        if: steps.check_release.outputs.exists == 'false'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml
+          git diff --cached --quiet || git commit -m "chore: bump version to ${{ steps.get_tag.outputs.new_version }} [skip ci]"
+          git push
 
-        if [ -d "templates" ]; then
-          mkdir -p sdd-package-base/templates
-          # Copy templates folder but exclude the commands directory
-          find templates -type f -not -path "templates/commands/*" -exec cp --parents {} sdd-package-base/ \;
-          echo "Copied templates folder (excluding commands directory)"
-        fi
-        
-        # Generate command files for each agent from source templates
-        generate_commands() {
-          local agent=$1
-          local ext=$2
-          local arg_format=$3
-          local output_dir=$4
-          
-          mkdir -p "$output_dir"
-          
-          for template in templates/commands/*.md; do
-            if [[ -f "$template" ]]; then
-              name=$(basename "$template" .md)
-              description=$(awk '/^description:/ {gsub(/^description: *"?/, ""); gsub(/"$/, ""); print; exit}' "$template" | tr -d '\r')
-              content=$(awk '/^---$/{if(++count==2) start=1; next} start' "$template" | sed "s/{ARGS}/$arg_format/g")
-              
-              case $ext in
-                "toml")
-                  {
-                    echo "description = \"$description\""
-                    echo ""
-                    echo "prompt = \"\"\""
-                    echo "$content"
-                    echo "\"\"\""
-                  } > "$output_dir/$name.$ext"
-                  ;;
-                "md")
-                  echo "$content" > "$output_dir/$name.$ext"
-                  ;;
-                "prompt.md")
-                  {
-                    echo "# $(echo "$description" | sed 's/\. .*//')"
-                    echo ""
-                    echo "$content"
-                  } > "$output_dir/$name.$ext"
-                  ;;
-              esac
-            fi
-          done
-        }
-        
-        # Create Claude Code package
-        mkdir -p sdd-claude-package
-        cp -r sdd-package-base/* sdd-claude-package/
-        mkdir -p sdd-claude-package/.claude/commands
-        generate_commands "claude" "md" "\$ARGUMENTS" "sdd-claude-package/.claude/commands"
-        echo "Created Claude Code package"
-        
-        # Create Gemini CLI package  
-        mkdir -p sdd-gemini-package
-        cp -r sdd-package-base/* sdd-gemini-package/
-        mkdir -p sdd-gemini-package/.gemini/commands
-        generate_commands "gemini" "toml" "{{args}}" "sdd-gemini-package/.gemini/commands"
-        if [ -f "agent_templates/gemini/GEMINI.md" ]; then
-          cp agent_templates/gemini/GEMINI.md sdd-gemini-package/GEMINI.md
-        fi
-        echo "Created Gemini CLI package"
-        
-        # Create GitHub Copilot package
-        mkdir -p sdd-copilot-package
-        cp -r sdd-package-base/* sdd-copilot-package/
-        mkdir -p sdd-copilot-package/.github/prompts
-        generate_commands "copilot" "prompt.md" "\$ARGUMENTS" "sdd-copilot-package/.github/prompts"
-        echo "Created GitHub Copilot package"
-        
-        # Create archive files for each package
-        cd sdd-claude-package && zip -r ../spec-kit-template-claude-${{ steps.get_tag.outputs.new_version }}.zip . && cd ..
-        
-        cd sdd-gemini-package && zip -r ../spec-kit-template-gemini-${{ steps.get_tag.outputs.new_version }}.zip . && cd ..
-        
-        cd sdd-copilot-package && zip -r ../spec-kit-template-copilot-${{ steps.get_tag.outputs.new_version }}.zip . && cd ..
-        
-        # List contents for verification
-        echo "Claude package contents:"
-        unzip -l spec-kit-template-claude-${{ steps.get_tag.outputs.new_version }}.zip | head -10
-        echo "Gemini package contents:"
-        unzip -l spec-kit-template-gemini-${{ steps.get_tag.outputs.new_version }}.zip | head -10
-        echo "Copilot package contents:"
-        unzip -l spec-kit-template-copilot-${{ steps.get_tag.outputs.new_version }}.zip | head -10
-        
-    - name: Generate release notes
-      if: steps.check_release.outputs.exists == 'false'
-      id: release_notes
-      run: |
-        # Get commits since last tag
-        LAST_TAG=${{ steps.get_tag.outputs.latest_tag }}
-        if [ "$LAST_TAG" = "v0.0.0" ]; then
-          # Check how many commits we have and use that as the limit
-          COMMIT_COUNT=$(git rev-list --count HEAD)
-          if [ "$COMMIT_COUNT" -gt 10 ]; then
-            COMMITS=$(git log --oneline --pretty=format:"- %s" HEAD~10..HEAD)
-          else
-            COMMITS=$(git log --oneline --pretty=format:"- %s" HEAD~$COMMIT_COUNT..HEAD 2>/dev/null || git log --oneline --pretty=format:"- %s")
-          fi
-        else
-          COMMITS=$(git log --oneline --pretty=format:"- %s" $LAST_TAG..HEAD)
-        fi
-        
-        # Create release notes
-        cat > release_notes.md << EOF
-        Template release ${{ steps.get_tag.outputs.new_version }}
-        
-        Updated specification-driven development templates for GitHub Copilot, Claude Code, and Gemini CLI.
-        
-        Download the template for your preferred AI assistant:
-        - spec-kit-template-copilot-${{ steps.get_tag.outputs.new_version }}.zip
-        - spec-kit-template-claude-${{ steps.get_tag.outputs.new_version }}.zip
-        - spec-kit-template-gemini-${{ steps.get_tag.outputs.new_version }}.zip  
-        EOF
-        
-        echo "Generated release notes:"
-        cat release_notes.md
-        
-    - name: Create GitHub Release
-      if: steps.check_release.outputs.exists == 'false'
-      run: |
-        # Remove 'v' prefix from version for release title
-        VERSION_NO_V=${{ steps.get_tag.outputs.new_version }}
-        VERSION_NO_V=${VERSION_NO_V#v}
-        
-        gh release create ${{ steps.get_tag.outputs.new_version }} \
-          spec-kit-template-copilot-${{ steps.get_tag.outputs.new_version }}.zip \
-          spec-kit-template-claude-${{ steps.get_tag.outputs.new_version }}.zip \
-          spec-kit-template-gemini-${{ steps.get_tag.outputs.new_version }}.zip \
-          --title "Spec Kit Templates - $VERSION_NO_V" \
-          --notes-file release_notes.md
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        
-    - name: Update version in pyproject.toml (for release artifacts only)
-      if: steps.check_release.outputs.exists == 'false'
-      run: |
-        # Update version in pyproject.toml (remove 'v' prefix for Python versioning)
-        VERSION=${{ steps.get_tag.outputs.new_version }}
-        PYTHON_VERSION=${VERSION#v}
-        
-        if [ -f "pyproject.toml" ]; then
-          sed -i "s/version = \".*\"/version = \"$PYTHON_VERSION\"/" pyproject.toml
-          echo "Updated pyproject.toml version to $PYTHON_VERSION (for release artifacts only)"
-        fi
-        
-    # Note: No longer committing version changes back to main branch
-    # The version is only updated in the release artifacts

.github/workflows/scripts/check-release-exists.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# check-release-exists.sh
+# Check if a GitHub release already exists for the given version
+# Usage: check-release-exists.sh <version>
+
+if [[ $# -ne 1 ]]; then
+  echo "Usage: $0 <version>" >&2
+  exit 1
+fi
+
+VERSION="$1"
+
+if gh release view "$VERSION" >/dev/null 2>&1; then
+  echo "exists=true" >> $GITHUB_OUTPUT
+  echo "Release $VERSION already exists, skipping..."
+else
+  echo "exists=false" >> $GITHUB_OUTPUT
+  echo "Release $VERSION does not exist, proceeding..."
+fi

.github/workflows/scripts/create-github-release.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# create-github-release.sh
+# Create a GitHub release with all template zip files
+# Usage: create-github-release.sh <version>
+
+if [[ $# -ne 1 ]]; then
+  echo "Usage: $0 <version>" >&2
+  exit 1
+fi
+
+VERSION="$1"
+
+# Remove 'v' prefix from version for release title
+VERSION_NO_V=${VERSION#v}
+
+gh release create "$VERSION" \
+  .genreleases/spec-kit-template-copilot-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-copilot-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-claude-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-claude-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-gemini-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-gemini-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-cursor-agent-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-cursor-agent-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-opencode-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-opencode-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-qwen-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-qwen-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-windsurf-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-windsurf-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-codex-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-codex-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-kilocode-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-kilocode-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-auggie-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-auggie-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-roo-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-roo-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-codebuddy-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-codebuddy-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-qodercli-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-qodercli-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-amp-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-amp-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-shai-sh-"$VERSION".zip \
+  .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 \
+  .genreleases/spec-kit-template-generic-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-generic-ps-"$VERSION".zip \
+  --title "Spec Kit Templates - $VERSION_NO_V" \
+  --notes-file release_notes.md

.github/workflows/scripts/create-release-packages.ps1

@@ -0,0 +1,428 @@
+#!/usr/bin/env pwsh
+#requires -Version 7.0
+
+<#
+.SYNOPSIS
+    Build Spec Kit template release archives for each supported AI assistant and script type.
+
+.DESCRIPTION
+    create-release-packages.ps1 (workflow-local)
+    Build Spec Kit template release archives for each supported AI assistant and script type.
+    
+.PARAMETER Version
+    Version string with leading 'v' (e.g., v0.2.0)
+
+.PARAMETER Agents
+    Comma or space separated subset of agents to build (default: all)
+    Valid agents: claude, gemini, copilot, cursor-agent, qwen, opencode, windsurf, codex, kilocode, auggie, roo, codebuddy, amp, q, bob, qodercli, shai, agy, generic
+
+.PARAMETER Scripts
+    Comma or space separated subset of script types to build (default: both)
+    Valid scripts: sh, ps
+
+.EXAMPLE
+    .\create-release-packages.ps1 -Version v0.2.0
+
+.EXAMPLE
+    .\create-release-packages.ps1 -Version v0.2.0 -Agents claude,copilot -Scripts sh
+
+.EXAMPLE
+    .\create-release-packages.ps1 -Version v0.2.0 -Agents claude -Scripts ps
+#>
+
+param(
+    [Parameter(Mandatory=$true, Position=0)]
+    [string]$Version,
+    
+    [Parameter(Mandatory=$false)]
+    [string]$Agents = "",
+    
+    [Parameter(Mandatory=$false)]
+    [string]$Scripts = ""
+)
+
+$ErrorActionPreference = "Stop"
+
+# Validate version format
+if ($Version -notmatch '^v\d+\.\d+\.\d+$') {
+    Write-Error "Version must look like v0.0.0"
+    exit 1
+}
+
+Write-Host "Building release packages for $Version"
+
+# Create and use .genreleases directory for all build artifacts
+$GenReleasesDir = ".genreleases"
+if (Test-Path $GenReleasesDir) {
+    Remove-Item -Path $GenReleasesDir -Recurse -Force -ErrorAction SilentlyContinue
+}
+New-Item -ItemType Directory -Path $GenReleasesDir -Force | Out-Null
+
+function Rewrite-Paths {
+    param([string]$Content)
+    
+    $Content = $Content -replace '(/?)\bmemory/', '.specify/memory/'
+    $Content = $Content -replace '(/?)\bscripts/', '.specify/scripts/'
+    $Content = $Content -replace '(/?)\btemplates/', '.specify/templates/'
+    return $Content
+}
+
+function Generate-Commands {
+    param(
+        [string]$Agent,
+        [string]$Extension,
+        [string]$ArgFormat,
+        [string]$OutputDir,
+        [string]$ScriptVariant
+    )
+    
+    New-Item -ItemType Directory -Path $OutputDir -Force | Out-Null
+    
+    $templates = Get-ChildItem -Path "templates/commands/*.md" -File -ErrorAction SilentlyContinue
+    
+    foreach ($template in $templates) {
+        $name = [System.IO.Path]::GetFileNameWithoutExtension($template.Name)
+        
+        # Read file content and normalize line endings
+        $fileContent = (Get-Content -Path $template.FullName -Raw) -replace "`r`n", "`n"
+        
+        # Extract description from YAML frontmatter
+        $description = ""
+        if ($fileContent -match '(?m)^description:\s*(.+)$') {
+            $description = $matches[1]
+        }
+        
+        # Extract script command from YAML frontmatter
+        $scriptCommand = ""
+        if ($fileContent -match "(?m)^\s*${ScriptVariant}:\s*(.+)$") {
+            $scriptCommand = $matches[1]
+        }
+        
+        if ([string]::IsNullOrEmpty($scriptCommand)) {
+            Write-Warning "No script command found for $ScriptVariant in $($template.Name)"
+            $scriptCommand = "(Missing script command for $ScriptVariant)"
+        }
+        
+        # Extract agent_script command from YAML frontmatter if present
+        $agentScriptCommand = ""
+        if ($fileContent -match "(?ms)agent_scripts:.*?^\s*${ScriptVariant}:\s*(.+?)$") {
+            $agentScriptCommand = $matches[1].Trim()
+        }
+        
+        # Replace {SCRIPT} placeholder with the script command
+        $body = $fileContent -replace '\{SCRIPT\}', $scriptCommand
+        
+        # Replace {AGENT_SCRIPT} placeholder with the agent script command if found
+        if (-not [string]::IsNullOrEmpty($agentScriptCommand)) {
+            $body = $body -replace '\{AGENT_SCRIPT\}', $agentScriptCommand
+        }
+        
+        # Remove the scripts: and agent_scripts: sections from frontmatter
+        $lines = $body -split "`n"
+        $outputLines = @()
+        $inFrontmatter = $false
+        $skipScripts = $false
+        $dashCount = 0
+        
+        foreach ($line in $lines) {
+            if ($line -match '^---$') {
+                $outputLines += $line
+                $dashCount++
+                if ($dashCount -eq 1) {
+                    $inFrontmatter = $true
+                } else {
+                    $inFrontmatter = $false
+                }
+                continue
+            }
+            
+            if ($inFrontmatter) {
+                if ($line -match '^(scripts|agent_scripts):$') {
+                    $skipScripts = $true
+                    continue
+                }
+                if ($line -match '^[a-zA-Z].*:' -and $skipScripts) {
+                    $skipScripts = $false
+                }
+                if ($skipScripts -and $line -match '^\s+') {
+                    continue
+                }
+            }
+            
+            $outputLines += $line
+        }
+        
+        $body = $outputLines -join "`n"
+        
+        # Apply other substitutions
+        $body = $body -replace '\{ARGS\}', $ArgFormat
+        $body = $body -replace '__AGENT__', $Agent
+        $body = Rewrite-Paths -Content $body
+        
+        # Generate output file based on extension
+        $outputFile = Join-Path $OutputDir "speckit.$name.$Extension"
+        
+        switch ($Extension) {
+            'toml' {
+                $body = $body -replace '\\', '\\'
+                $output = "description = `"$description`"`n`nprompt = `"`"`"`n$body`n`"`"`""
+                Set-Content -Path $outputFile -Value $output -NoNewline
+            }
+            'md' {
+                Set-Content -Path $outputFile -Value $body -NoNewline
+            }
+            'agent.md' {
+                Set-Content -Path $outputFile -Value $body -NoNewline
+            }
+        }
+    }
+}
+
+function Generate-CopilotPrompts {
+    param(
+        [string]$AgentsDir,
+        [string]$PromptsDir
+    )
+    
+    New-Item -ItemType Directory -Path $PromptsDir -Force | Out-Null
+    
+    $agentFiles = Get-ChildItem -Path "$AgentsDir/speckit.*.agent.md" -File -ErrorAction SilentlyContinue
+    
+    foreach ($agentFile in $agentFiles) {
+        $basename = $agentFile.Name -replace '\.agent\.md$', ''
+        $promptFile = Join-Path $PromptsDir "$basename.prompt.md"
+        
+        $content = @"
+---
+agent: $basename
+---
+"@
+        Set-Content -Path $promptFile -Value $content
+    }
+}
+
+function Build-Variant {
+    param(
+        [string]$Agent,
+        [string]$Script
+    )
+    
+    $baseDir = Join-Path $GenReleasesDir "sdd-${Agent}-package-${Script}"
+    Write-Host "Building $Agent ($Script) package..."
+    New-Item -ItemType Directory -Path $baseDir -Force | Out-Null
+    
+    # Copy base structure but filter scripts by variant
+    $specDir = Join-Path $baseDir ".specify"
+    New-Item -ItemType Directory -Path $specDir -Force | Out-Null
+    
+    # Copy memory directory
+    if (Test-Path "memory") {
+        Copy-Item -Path "memory" -Destination $specDir -Recurse -Force
+        Write-Host "Copied memory -> .specify"
+    }
+    
+    # Only copy the relevant script variant directory
+    if (Test-Path "scripts") {
+        $scriptsDestDir = Join-Path $specDir "scripts"
+        New-Item -ItemType Directory -Path $scriptsDestDir -Force | Out-Null
+        
+        switch ($Script) {
+            'sh' {
+                if (Test-Path "scripts/bash") {
+                    Copy-Item -Path "scripts/bash" -Destination $scriptsDestDir -Recurse -Force
+                    Write-Host "Copied scripts/bash -> .specify/scripts"
+                }
+            }
+            'ps' {
+                if (Test-Path "scripts/powershell") {
+                    Copy-Item -Path "scripts/powershell" -Destination $scriptsDestDir -Recurse -Force
+                    Write-Host "Copied scripts/powershell -> .specify/scripts"
+                }
+            }
+        }
+        
+        # Copy any script files that aren't in variant-specific directories
+        Get-ChildItem -Path "scripts" -File -ErrorAction SilentlyContinue | ForEach-Object {
+            Copy-Item -Path $_.FullName -Destination $scriptsDestDir -Force
+        }
+    }
+    
+    # Copy templates (excluding commands directory and vscode-settings.json)
+    if (Test-Path "templates") {
+        $templatesDestDir = Join-Path $specDir "templates"
+        New-Item -ItemType Directory -Path $templatesDestDir -Force | Out-Null
+        
+        Get-ChildItem -Path "templates" -Recurse -File | Where-Object {
+            $_.FullName -notmatch 'templates[/\\]commands[/\\]' -and $_.Name -ne 'vscode-settings.json'
+        } | ForEach-Object {
+            $relativePath = $_.FullName.Substring((Resolve-Path "templates").Path.Length + 1)
+            $destFile = Join-Path $templatesDestDir $relativePath
+            $destFileDir = Split-Path $destFile -Parent
+            New-Item -ItemType Directory -Path $destFileDir -Force | Out-Null
+            Copy-Item -Path $_.FullName -Destination $destFile -Force
+        }
+        Write-Host "Copied templates -> .specify/templates"
+    }
+    
+    # Generate agent-specific command files
+    switch ($Agent) {
+        'claude' {
+            $cmdDir = Join-Path $baseDir ".claude/commands"
+            Generate-Commands -Agent 'claude' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'gemini' {
+            $cmdDir = Join-Path $baseDir ".gemini/commands"
+            Generate-Commands -Agent 'gemini' -Extension 'toml' -ArgFormat '{{args}}' -OutputDir $cmdDir -ScriptVariant $Script
+            if (Test-Path "agent_templates/gemini/GEMINI.md") {
+                Copy-Item -Path "agent_templates/gemini/GEMINI.md" -Destination (Join-Path $baseDir "GEMINI.md")
+            }
+        }
+        'copilot' {
+            $agentsDir = Join-Path $baseDir ".github/agents"
+            Generate-Commands -Agent 'copilot' -Extension 'agent.md' -ArgFormat '$ARGUMENTS' -OutputDir $agentsDir -ScriptVariant $Script
+            
+            # Generate companion prompt files
+            $promptsDir = Join-Path $baseDir ".github/prompts"
+            Generate-CopilotPrompts -AgentsDir $agentsDir -PromptsDir $promptsDir
+            
+            # Create VS Code workspace settings
+            $vscodeDir = Join-Path $baseDir ".vscode"
+            New-Item -ItemType Directory -Path $vscodeDir -Force | Out-Null
+            if (Test-Path "templates/vscode-settings.json") {
+                Copy-Item -Path "templates/vscode-settings.json" -Destination (Join-Path $vscodeDir "settings.json")
+            }
+        }
+        'cursor-agent' {
+            $cmdDir = Join-Path $baseDir ".cursor/commands"
+            Generate-Commands -Agent 'cursor-agent' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'qwen' {
+            $cmdDir = Join-Path $baseDir ".qwen/commands"
+            Generate-Commands -Agent 'qwen' -Extension 'toml' -ArgFormat '{{args}}' -OutputDir $cmdDir -ScriptVariant $Script
+            if (Test-Path "agent_templates/qwen/QWEN.md") {
+                Copy-Item -Path "agent_templates/qwen/QWEN.md" -Destination (Join-Path $baseDir "QWEN.md")
+            }
+        }
+        'opencode' {
+            $cmdDir = Join-Path $baseDir ".opencode/command"
+            Generate-Commands -Agent 'opencode' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'windsurf' {
+            $cmdDir = Join-Path $baseDir ".windsurf/workflows"
+            Generate-Commands -Agent 'windsurf' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'codex' {
+            $cmdDir = Join-Path $baseDir ".codex/prompts"
+            Generate-Commands -Agent 'codex' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'kilocode' {
+            $cmdDir = Join-Path $baseDir ".kilocode/workflows"
+            Generate-Commands -Agent 'kilocode' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'auggie' {
+            $cmdDir = Join-Path $baseDir ".augment/commands"
+            Generate-Commands -Agent 'auggie' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'roo' {
+            $cmdDir = Join-Path $baseDir ".roo/commands"
+            Generate-Commands -Agent 'roo' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'codebuddy' {
+            $cmdDir = Join-Path $baseDir ".codebuddy/commands"
+            Generate-Commands -Agent 'codebuddy' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'amp' {
+            $cmdDir = Join-Path $baseDir ".agents/commands"
+            Generate-Commands -Agent 'amp' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'q' {
+            $cmdDir = Join-Path $baseDir ".amazonq/prompts"
+            Generate-Commands -Agent 'q' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'bob' {
+            $cmdDir = Join-Path $baseDir ".bob/commands"
+            Generate-Commands -Agent 'bob' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'qodercli' {
+            $cmdDir = Join-Path $baseDir ".qoder/commands"
+            Generate-Commands -Agent 'qodercli' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'generic' {
+            $cmdDir = Join-Path $baseDir ".speckit/commands"
+            Generate-Commands -Agent 'generic' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+    }
+    
+    # Create zip archive
+    $zipFile = Join-Path $GenReleasesDir "spec-kit-template-${Agent}-${Script}-${Version}.zip"
+    Compress-Archive -Path "$baseDir/*" -DestinationPath $zipFile -Force
+    Write-Host "Created $zipFile"
+}
+
+# Define all agents and scripts
+$AllAgents = @('claude', 'gemini', 'copilot', 'cursor-agent', 'qwen', 'opencode', 'windsurf', 'codex', 'kilocode', 'auggie', 'roo', 'codebuddy', 'amp', 'q', 'bob', 'qodercli', 'shai', 'agy', 'generic')
+$AllScripts = @('sh', 'ps')
+
+function Normalize-List {
+    param([string]$Input)
+    
+    if ([string]::IsNullOrEmpty($Input)) {
+        return @()
+    }
+    
+    # Split by comma or space and remove duplicates while preserving order
+    $items = $Input -split '[,\s]+' | Where-Object { $_ } | Select-Object -Unique
+    return $items
+}
+
+function Validate-Subset {
+    param(
+        [string]$Type,
+        [string[]]$Allowed,
+        [string[]]$Items
+    )
+    
+    $ok = $true
+    foreach ($item in $Items) {
+        if ($item -notin $Allowed) {
+            Write-Error "Unknown $Type '$item' (allowed: $($Allowed -join ', '))"
+            $ok = $false
+        }
+    }
+    return $ok
+}
+
+# Determine agent list
+if (-not [string]::IsNullOrEmpty($Agents)) {
+    $AgentList = Normalize-List -Input $Agents
+    if (-not (Validate-Subset -Type 'agent' -Allowed $AllAgents -Items $AgentList)) {
+        exit 1
+    }
+} else {
+    $AgentList = $AllAgents
+}
+
+# Determine script list
+if (-not [string]::IsNullOrEmpty($Scripts)) {
+    $ScriptList = Normalize-List -Input $Scripts
+    if (-not (Validate-Subset -Type 'script' -Allowed $AllScripts -Items $ScriptList)) {
+        exit 1
+    }
+} else {
+    $ScriptList = $AllScripts
+}
+
+Write-Host "Agents: $($AgentList -join ', ')"
+Write-Host "Scripts: $($ScriptList -join ', ')"
+
+# Build all variants
+foreach ($agent in $AgentList) {
+    foreach ($script in $ScriptList) {
+        Build-Variant -Agent $agent -Script $script
+    }
+}
+
+Write-Host "`nArchives in ${GenReleasesDir}:"
+Get-ChildItem -Path $GenReleasesDir -Filter "spec-kit-template-*-${Version}.zip" | ForEach-Object {
+    Write-Host "  $($_.Name)"
+}

.github/workflows/scripts/create-release-packages.sh

@@ -0,0 +1,280 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# create-release-packages.sh (workflow-local)
+# Build Spec Kit template release archives for each supported AI assistant and script type.
+# Usage: .github/workflows/scripts/create-release-packages.sh <version>
+#   Version argument should include leading 'v'.
+#   Optionally set AGENTS and/or SCRIPTS env vars to limit what gets built.
+#     AGENTS  : space or comma separated subset of: claude gemini copilot cursor-agent qwen opencode windsurf codex amp shai bob generic (default: all)
+#     SCRIPTS : space or comma separated subset of: sh ps (default: both)
+#   Examples:
+#     AGENTS=claude SCRIPTS=sh $0 v0.2.0
+#     AGENTS="copilot,gemini" $0 v0.2.0
+#     SCRIPTS=ps $0 v0.2.0
+
+if [[ $# -ne 1 ]]; then
+  echo "Usage: $0 <version-with-v-prefix>" >&2
+  exit 1
+fi
+NEW_VERSION="$1"
+if [[ ! $NEW_VERSION =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+  echo "Version must look like v0.0.0" >&2
+  exit 1
+fi
+
+echo "Building release packages for $NEW_VERSION"
+
+# Create and use .genreleases directory for all build artifacts
+GENRELEASES_DIR=".genreleases"
+mkdir -p "$GENRELEASES_DIR"
+rm -rf "$GENRELEASES_DIR"/* || true
+
+rewrite_paths() {
+  sed -E \
+    -e 's@(/?)memory/@.specify/memory/@g' \
+    -e 's@(/?)scripts/@.specify/scripts/@g' \
+    -e 's@(/?)templates/@.specify/templates/@g' \
+    -e 's@\.specify\.specify/@.specify/@g'
+}
+
+generate_commands() {
+  local agent=$1 ext=$2 arg_format=$3 output_dir=$4 script_variant=$5
+  mkdir -p "$output_dir"
+  for template in templates/commands/*.md; do
+    [[ -f "$template" ]] || continue
+    local name description script_command agent_script_command body
+    name=$(basename "$template" .md)
+    
+    # Normalize line endings
+    file_content=$(tr -d '\r' < "$template")
+    
+    # Extract description and script command from YAML frontmatter
+    description=$(printf '%s\n' "$file_content" | awk '/^description:/ {sub(/^description:[[:space:]]*/, ""); print; exit}')
+    script_command=$(printf '%s\n' "$file_content" | awk -v sv="$script_variant" '/^[[:space:]]*'"$script_variant"':[[:space:]]*/ {sub(/^[[:space:]]*'"$script_variant"':[[:space:]]*/, ""); print; exit}')
+    
+    if [[ -z $script_command ]]; then
+      echo "Warning: no script command found for $script_variant in $template" >&2
+      script_command="(Missing script command for $script_variant)"
+    fi
+    
+    # Extract agent_script command from YAML frontmatter if present
+    agent_script_command=$(printf '%s\n' "$file_content" | awk '
+      /^agent_scripts:$/ { in_agent_scripts=1; next }
+      in_agent_scripts && /^[[:space:]]*'"$script_variant"':[[:space:]]*/ {
+        sub(/^[[:space:]]*'"$script_variant"':[[:space:]]*/, "")
+        print
+        exit
+      }
+      in_agent_scripts && /^[a-zA-Z]/ { in_agent_scripts=0 }
+    ')
+    
+    # Replace {SCRIPT} placeholder with the script command
+    body=$(printf '%s\n' "$file_content" | sed "s|{SCRIPT}|${script_command}|g")
+    
+    # Replace {AGENT_SCRIPT} placeholder with the agent script command if found
+    if [[ -n $agent_script_command ]]; then
+      body=$(printf '%s\n' "$body" | sed "s|{AGENT_SCRIPT}|${agent_script_command}|g")
+    fi
+    
+    # Remove the scripts: and agent_scripts: sections from frontmatter while preserving YAML structure
+    body=$(printf '%s\n' "$body" | awk '
+      /^---$/ { print; if (++dash_count == 1) in_frontmatter=1; else in_frontmatter=0; next }
+      in_frontmatter && /^scripts:$/ { skip_scripts=1; next }
+      in_frontmatter && /^agent_scripts:$/ { skip_scripts=1; next }
+      in_frontmatter && /^[a-zA-Z].*:/ && skip_scripts { skip_scripts=0 }
+      in_frontmatter && skip_scripts && /^[[:space:]]/ { next }
+      { print }
+    ')
+    
+    # Apply other substitutions
+    body=$(printf '%s\n' "$body" | sed "s/{ARGS}/$arg_format/g" | sed "s/__AGENT__/$agent/g" | rewrite_paths)
+    
+    case $ext in
+      toml)
+        body=$(printf '%s\n' "$body" | sed 's/\\/\\\\/g')
+        { echo "description = \"$description\""; echo; echo "prompt = \"\"\""; echo "$body"; echo "\"\"\""; } > "$output_dir/speckit.$name.$ext" ;;
+      md)
+        echo "$body" > "$output_dir/speckit.$name.$ext" ;;
+      agent.md)
+        echo "$body" > "$output_dir/speckit.$name.$ext" ;;
+    esac
+  done
+}
+
+generate_copilot_prompts() {
+  local agents_dir=$1 prompts_dir=$2
+  mkdir -p "$prompts_dir"
+  
+  # Generate a .prompt.md file for each .agent.md file
+  for agent_file in "$agents_dir"/speckit.*.agent.md; do
+    [[ -f "$agent_file" ]] || continue
+    
+    local basename=$(basename "$agent_file" .agent.md)
+    local prompt_file="$prompts_dir/${basename}.prompt.md"
+    
+    # Create prompt file with agent frontmatter
+    cat > "$prompt_file" <<EOF
+---
+agent: ${basename}
+---
+EOF
+  done
+}
+
+build_variant() {
+  local agent=$1 script=$2
+  local base_dir="$GENRELEASES_DIR/sdd-${agent}-package-${script}"
+  echo "Building $agent ($script) package..."
+  mkdir -p "$base_dir"
+  
+  # Copy base structure but filter scripts by variant
+  SPEC_DIR="$base_dir/.specify"
+  mkdir -p "$SPEC_DIR"
+  
+  [[ -d memory ]] && { cp -r memory "$SPEC_DIR/"; echo "Copied memory -> .specify"; }
+  
+  # Only copy the relevant script variant directory
+  if [[ -d scripts ]]; then
+    mkdir -p "$SPEC_DIR/scripts"
+    case $script in
+      sh)
+        [[ -d scripts/bash ]] && { cp -r scripts/bash "$SPEC_DIR/scripts/"; echo "Copied scripts/bash -> .specify/scripts"; }
+        # Copy any script files that aren't in variant-specific directories
+        find scripts -maxdepth 1 -type f -exec cp {} "$SPEC_DIR/scripts/" \; 2>/dev/null || true
+        ;;
+      ps)
+        [[ -d scripts/powershell ]] && { cp -r scripts/powershell "$SPEC_DIR/scripts/"; echo "Copied scripts/powershell -> .specify/scripts"; }
+        # Copy any script files that aren't in variant-specific directories
+        find scripts -maxdepth 1 -type f -exec cp {} "$SPEC_DIR/scripts/" \; 2>/dev/null || true
+        ;;
+    esac
+  fi
+  
+  [[ -d templates ]] && { mkdir -p "$SPEC_DIR/templates"; find templates -type f -not -path "templates/commands/*" -not -name "vscode-settings.json" -exec cp --parents {} "$SPEC_DIR"/ \; ; echo "Copied templates -> .specify/templates"; }
+  
+  # NOTE: We substitute {ARGS} internally. Outward tokens differ intentionally:
+  #   * Markdown/prompt (claude, copilot, cursor-agent, opencode): $ARGUMENTS
+  #   * TOML (gemini, qwen): {{args}}
+  # This keeps formats readable without extra abstraction.
+
+  case $agent in
+    claude)
+      mkdir -p "$base_dir/.claude/commands"
+      generate_commands claude md "\$ARGUMENTS" "$base_dir/.claude/commands" "$script" ;;
+    gemini)
+      mkdir -p "$base_dir/.gemini/commands"
+      generate_commands gemini toml "{{args}}" "$base_dir/.gemini/commands" "$script"
+      [[ -f agent_templates/gemini/GEMINI.md ]] && cp agent_templates/gemini/GEMINI.md "$base_dir/GEMINI.md" ;;
+    copilot)
+      mkdir -p "$base_dir/.github/agents"
+      generate_commands copilot agent.md "\$ARGUMENTS" "$base_dir/.github/agents" "$script"
+      # Generate companion prompt files
+      generate_copilot_prompts "$base_dir/.github/agents" "$base_dir/.github/prompts"
+      # Create VS Code workspace settings
+      mkdir -p "$base_dir/.vscode"
+      [[ -f templates/vscode-settings.json ]] && cp templates/vscode-settings.json "$base_dir/.vscode/settings.json"
+      ;;
+    cursor-agent)
+      mkdir -p "$base_dir/.cursor/commands"
+      generate_commands cursor-agent md "\$ARGUMENTS" "$base_dir/.cursor/commands" "$script" ;;
+    qwen)
+      mkdir -p "$base_dir/.qwen/commands"
+      generate_commands qwen toml "{{args}}" "$base_dir/.qwen/commands" "$script"
+      [[ -f agent_templates/qwen/QWEN.md ]] && cp agent_templates/qwen/QWEN.md "$base_dir/QWEN.md" ;;
+    opencode)
+      mkdir -p "$base_dir/.opencode/command"
+      generate_commands opencode md "\$ARGUMENTS" "$base_dir/.opencode/command" "$script" ;;
+    windsurf)
+      mkdir -p "$base_dir/.windsurf/workflows"
+      generate_commands windsurf md "\$ARGUMENTS" "$base_dir/.windsurf/workflows" "$script" ;;
+    codex)
+      mkdir -p "$base_dir/.codex/prompts"
+      generate_commands codex md "\$ARGUMENTS" "$base_dir/.codex/prompts" "$script" ;;
+    kilocode)
+      mkdir -p "$base_dir/.kilocode/workflows"
+      generate_commands kilocode md "\$ARGUMENTS" "$base_dir/.kilocode/workflows" "$script" ;;
+    auggie)
+      mkdir -p "$base_dir/.augment/commands"
+      generate_commands auggie md "\$ARGUMENTS" "$base_dir/.augment/commands" "$script" ;;
+    roo)
+      mkdir -p "$base_dir/.roo/commands"
+      generate_commands roo md "\$ARGUMENTS" "$base_dir/.roo/commands" "$script" ;;
+    codebuddy)
+      mkdir -p "$base_dir/.codebuddy/commands"
+      generate_commands codebuddy md "\$ARGUMENTS" "$base_dir/.codebuddy/commands" "$script" ;;
+    qodercli)
+      mkdir -p "$base_dir/.qoder/commands"
+      generate_commands qodercli md "\$ARGUMENTS" "$base_dir/.qoder/commands" "$script" ;;
+    amp)
+      mkdir -p "$base_dir/.agents/commands"
+      generate_commands amp md "\$ARGUMENTS" "$base_dir/.agents/commands" "$script" ;;
+    shai)
+      mkdir -p "$base_dir/.shai/commands"
+      generate_commands shai md "\$ARGUMENTS" "$base_dir/.shai/commands" "$script" ;;
+    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" ;;
+    generic)
+      mkdir -p "$base_dir/.speckit/commands"
+      generate_commands generic md "\$ARGUMENTS" "$base_dir/.speckit/commands" "$script" ;;
+  esac
+  ( cd "$base_dir" && zip -r "../spec-kit-template-${agent}-${script}-${NEW_VERSION}.zip" . )
+  echo "Created $GENRELEASES_DIR/spec-kit-template-${agent}-${script}-${NEW_VERSION}.zip"
+}
+
+# Determine agent list
+ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf codex kilocode auggie roo codebuddy amp shai q agy bob qodercli generic)
+ALL_SCRIPTS=(sh ps)
+
+norm_list() {
+  # convert comma+space separated -> line separated unique while preserving order of first occurrence
+  tr ',\n' '  ' | awk '{for(i=1;i<=NF;i++){if(!seen[$i]++){printf((out?"\n":"") $i);out=1}}}END{printf("\n")}'
+}
+
+validate_subset() {
+  local type=$1; shift; local -n allowed=$1; shift; local items=("$@")
+  local invalid=0
+  for it in "${items[@]}"; do
+    local found=0
+    for a in "${allowed[@]}"; do [[ $it == "$a" ]] && { found=1; break; }; done
+    if [[ $found -eq 0 ]]; then
+      echo "Error: unknown $type '$it' (allowed: ${allowed[*]})" >&2
+      invalid=1
+    fi
+  done
+  return $invalid
+}
+
+if [[ -n ${AGENTS:-} ]]; then
+  mapfile -t AGENT_LIST < <(printf '%s' "$AGENTS" | norm_list)
+  validate_subset agent ALL_AGENTS "${AGENT_LIST[@]}" || exit 1
+else
+  AGENT_LIST=("${ALL_AGENTS[@]}")
+fi
+
+if [[ -n ${SCRIPTS:-} ]]; then
+  mapfile -t SCRIPT_LIST < <(printf '%s' "$SCRIPTS" | norm_list)
+  validate_subset script ALL_SCRIPTS "${SCRIPT_LIST[@]}" || exit 1
+else
+  SCRIPT_LIST=("${ALL_SCRIPTS[@]}")
+fi
+
+echo "Agents: ${AGENT_LIST[*]}"
+echo "Scripts: ${SCRIPT_LIST[*]}"
+
+for agent in "${AGENT_LIST[@]}"; do
+  for script in "${SCRIPT_LIST[@]}"; do
+    build_variant "$agent" "$script"
+  done
+done
+
+echo "Archives in $GENRELEASES_DIR:"
+ls -1 "$GENRELEASES_DIR"/spec-kit-template-*-"${NEW_VERSION}".zip
+

.github/workflows/scripts/generate-release-notes.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# generate-release-notes.sh
+# Generate release notes from git history
+# Usage: generate-release-notes.sh <new_version> <last_tag>
+
+if [[ $# -ne 2 ]]; then
+  echo "Usage: $0 <new_version> <last_tag>" >&2
+  exit 1
+fi
+
+NEW_VERSION="$1"
+LAST_TAG="$2"
+
+# Get commits since last tag
+if [ "$LAST_TAG" = "v0.0.0" ]; then
+  # Check how many commits we have and use that as the limit
+  COMMIT_COUNT=$(git rev-list --count HEAD)
+  if [ "$COMMIT_COUNT" -gt 10 ]; then
+    COMMITS=$(git log --oneline --pretty=format:"- %s" HEAD~10..HEAD)
+  else
+    COMMITS=$(git log --oneline --pretty=format:"- %s" HEAD~$COMMIT_COUNT..HEAD 2>/dev/null || git log --oneline --pretty=format:"- %s")
+  fi
+else
+  COMMITS=$(git log --oneline --pretty=format:"- %s" $LAST_TAG..HEAD)
+fi
+
+# Create release notes
+cat > release_notes.md << EOF
+This is the latest set of releases that you can use with your agent of choice. We recommend using the Specify CLI to scaffold your projects, however you can download these independently and manage them yourself.
+
+## Changelog
+
+$COMMITS
+
+EOF
+
+echo "Generated release notes:"
+cat release_notes.md

.github/workflows/scripts/get-next-version.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# get-next-version.sh
+# Calculate the next version based on the latest git tag and output GitHub Actions variables
+# Usage: get-next-version.sh
+
+# Get the latest tag, or use v0.0.0 if no tags exist
+LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
+echo "latest_tag=$LATEST_TAG" >> $GITHUB_OUTPUT
+
+# Extract version number and increment
+VERSION=$(echo $LATEST_TAG | sed 's/v//')
+IFS='.' read -ra VERSION_PARTS <<< "$VERSION"
+MAJOR=${VERSION_PARTS[0]:-0}
+MINOR=${VERSION_PARTS[1]:-0}
+PATCH=${VERSION_PARTS[2]:-0}
+
+# Increment patch version
+PATCH=$((PATCH + 1))
+NEW_VERSION="v$MAJOR.$MINOR.$PATCH"
+
+echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+echo "New version will be: $NEW_VERSION"

.github/workflows/scripts/update-version.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# update-version.sh
+# Update version in pyproject.toml (for release artifacts only)
+# Usage: update-version.sh <version>
+
+if [[ $# -ne 1 ]]; then
+  echo "Usage: $0 <version>" >&2
+  exit 1
+fi
+
+VERSION="$1"
+
+# Remove 'v' prefix for Python versioning
+PYTHON_VERSION=${VERSION#v}
+
+if [ -f "pyproject.toml" ]; then
+  sed -i "s/version = \".*\"/version = \"$PYTHON_VERSION\"/" pyproject.toml
+  echo "Updated pyproject.toml version to $PYTHON_VERSION (for release artifacts only)"
+else
+  echo "Warning: pyproject.toml not found, skipping version update"
+fi

.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

.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@v6
+        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@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra test
+
+      - name: Run tests
+        run: uv run pytest

.gitignore

@@ -32,9 +32,21 @@ env/
 *.swp
 *.swo
 .DS_Store
+*.tmp
 
 # Project specific
 *.log
 .env
 .env.local
 *.lock
+
+# Spec Kit-specific files
+.genreleases/
+*.zip
+sdd-*/
+docs/dev
+
+# Extension system
+.specify/extensions/.cache/
+.specify/extensions/.backup/
+.specify/extensions/*/local-config.yml

.markdownlint-cli2.jsonc

@@ -0,0 +1,29 @@
+{
+  // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+  "config": {
+    "default": true,
+    "MD003": {
+      "style": "atx"
+    },
+    "MD007": {
+      "indent": 2
+    },
+    "MD013": false,
+    "MD024": {
+      "siblings_only": true
+    },
+    "MD033": false,
+    "MD041": false,
+    "MD049": {
+      "style": "asterisk"
+    },
+    "MD050": {
+      "style": "asterisk"
+    },
+    "MD036": false,
+    "MD060": false
+  },
+  "ignores": [
+    ".genreleases/"
+  ]
+}

AGENTS.md

@@ -0,0 +1,419 @@
+# AGENTS.md
+
+## About Spec Kit and Specify
+
+**GitHub Spec Kit** is a comprehensive toolkit for implementing Spec-Driven Development (SDD) - a methodology that emphasizes creating clear specifications before implementation. The toolkit includes templates, scripts, and workflows that guide development teams through a structured approach to building software.
+
+**Specify CLI** is the command-line interface that bootstraps projects with the Spec Kit framework. It sets up the necessary directory structures, templates, and AI agent integrations to support the Spec-Driven Development workflow.
+
+The toolkit supports multiple AI coding assistants, allowing teams to use their preferred tools while maintaining consistent project structure and development practices.
+
+---
+
+## General practices
+
+- Any changes to `__init__.py` for the Specify CLI require a version rev in `pyproject.toml` and addition of entries to `CHANGELOG.md`.
+
+## Adding New Agent Support
+
+This section explains how to add support for new AI agents/assistants to the Specify CLI. Use this guide as a reference when integrating new AI tools into the Spec-Driven Development workflow.
+
+### Overview
+
+Specify supports multiple AI agents by generating agent-specific command files and directory structures when initializing projects. Each agent has its own conventions for:
+
+- **Command file formats** (Markdown, TOML, etc.)
+- **Directory structures** (`.claude/commands/`, `.windsurf/workflows/`, etc.)
+- **Command invocation patterns** (slash commands, CLI tools, etc.)
+- **Argument passing conventions** (`$ARGUMENTS`, `{{args}}`, etc.)
+
+### Current Supported Agents
+
+| Agent                      | Directory              | Format   | CLI Tool        | Description                 |
+| -------------------------- | ---------------------- | -------- | --------------- | --------------------------- |
+| **Claude Code**            | `.claude/commands/`    | Markdown | `claude`        | Anthropic's Claude Code CLI |
+| **Gemini CLI**             | `.gemini/commands/`    | TOML     | `gemini`        | Google's Gemini CLI         |
+| **GitHub Copilot**         | `.github/agents/`      | Markdown | N/A (IDE-based) | GitHub Copilot in VS Code   |
+| **Cursor**                 | `.cursor/commands/`    | Markdown | `cursor-agent`  | Cursor CLI                  |
+| **Qwen Code**              | `.qwen/commands/`      | TOML     | `qwen`          | Alibaba's Qwen Code CLI     |
+| **opencode**               | `.opencode/command/`   | Markdown | `opencode`      | opencode CLI                |
+| **Codex CLI**              | `.codex/commands/`     | Markdown | `codex`         | Codex CLI                   |
+| **Windsurf**               | `.windsurf/workflows/` | Markdown | N/A (IDE-based) | Windsurf IDE workflows      |
+| **Kilo Code**              | `.kilocode/rules/`     | Markdown | N/A (IDE-based) | Kilo Code IDE               |
+| **Auggie CLI**             | `.augment/rules/`      | Markdown | `auggie`        | Auggie CLI                  |
+| **Roo Code**               | `.roo/rules/`          | Markdown | N/A (IDE-based) | Roo Code IDE                |
+| **CodeBuddy CLI**          | `.codebuddy/commands/` | Markdown | `codebuddy`     | CodeBuddy CLI               |
+| **Qoder CLI**              | `.qoder/commands/`     | Markdown | `qodercli`      | Qoder CLI                   |
+| **Amazon Q Developer CLI** | `.amazonq/prompts/`    | Markdown | `q`             | Amazon Q Developer CLI      |
+| **Amp**                    | `.agents/commands/`    | Markdown | `amp`           | Amp CLI                     |
+| **SHAI**                   | `.shai/commands/`      | Markdown | `shai`          | SHAI CLI                    |
+| **IBM Bob**                | `.bob/commands/`       | Markdown | N/A (IDE-based) | IBM Bob IDE                 |
+| **Generic**                | User-specified via `--ai-commands-dir` | Markdown | N/A | Bring your own agent        |
+
+### Step-by-Step Integration Guide
+
+Follow these steps to add a new agent (using a hypothetical new agent as an example):
+
+#### 1. Add to AGENT_CONFIG
+
+**IMPORTANT**: Use the actual CLI tool name as the key, not a shortened version.
+
+Add the new agent to the `AGENT_CONFIG` dictionary in `src/specify_cli/__init__.py`. This is the **single source of truth** for all agent metadata:
+
+```python
+AGENT_CONFIG = {
+    # ... existing agents ...
+    "new-agent-cli": {  # Use the ACTUAL CLI tool name (what users type in terminal)
+        "name": "New Agent Display Name",
+        "folder": ".newagent/",  # Directory for agent files
+        "commands_subdir": "commands",  # Subdirectory name for command files (default: "commands")
+        "install_url": "https://example.com/install",  # URL for installation docs (or None if IDE-based)
+        "requires_cli": True,  # True if CLI tool required, False for IDE-based agents
+    },
+}
+```
+
+**Key Design Principle**: The dictionary key should match the actual executable name that users install. For example:
+
+- ✅ Use `"cursor-agent"` because the CLI tool is literally called `cursor-agent`
+- ❌ Don't use `"cursor"` as a shortcut if the tool is `cursor-agent`
+
+This eliminates the need for special-case mappings throughout the codebase.
+
+**Field Explanations**:
+
+- `name`: Human-readable display name shown to users
+- `folder`: Directory where agent-specific files are stored (relative to project root)
+- `commands_subdir`: Subdirectory name within the agent folder where command/prompt files are stored (default: `"commands"`)
+  - Most agents use `"commands"` (e.g., `.claude/commands/`)
+  - Some agents use alternative names: `"agents"` (copilot), `"workflows"` (windsurf, kilocode, agy), `"prompts"` (codex, q), `"command"` (opencode - singular)
+  - This field enables `--ai-skills` to locate command templates correctly for skill generation
+- `install_url`: Installation documentation URL (set to `None` for IDE-based agents)
+- `requires_cli`: Whether the agent requires a CLI tool check during initialization
+
+#### 2. Update CLI Help Text
+
+Update the `--ai` parameter help text in the `init()` command to include the new agent:
+
+```python
+ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, new-agent-cli, or q"),
+```
+
+Also update any function docstrings, examples, and error messages that list available agents.
+
+#### 3. Update README Documentation
+
+Update the **Supported AI Agents** section in `README.md` to include the new agent:
+
+- Add the new agent to the table with appropriate support level (Full/Partial)
+- Include the agent's official website link
+- Add any relevant notes about the agent's implementation
+- Ensure the table formatting remains aligned and consistent
+
+#### 4. Update Release Package Script
+
+Modify `.github/workflows/scripts/create-release-packages.sh`:
+
+##### Add to ALL_AGENTS array
+
+```bash
+ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf q)
+```
+
+##### Add case statement for directory structure
+
+```bash
+case $agent in
+  # ... existing cases ...
+  windsurf)
+    mkdir -p "$base_dir/.windsurf/workflows"
+    generate_commands windsurf md "\$ARGUMENTS" "$base_dir/.windsurf/workflows" "$script" ;;
+esac
+```
+
+#### 4. Update GitHub Release Script
+
+Modify `.github/workflows/scripts/create-github-release.sh` to include the new agent's packages:
+
+```bash
+gh release create "$VERSION" \
+  # ... existing packages ...
+  .genreleases/spec-kit-template-windsurf-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-windsurf-ps-"$VERSION".zip \
+  # Add new agent packages here
+```
+
+#### 5. Update Agent Context Scripts
+
+##### Bash script (`scripts/bash/update-agent-context.sh`)
+
+Add file variable:
+
+```bash
+WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
+```
+
+Add to case statement:
+
+```bash
+case "$AGENT_TYPE" in
+  # ... existing cases ...
+  windsurf) update_agent_file "$WINDSURF_FILE" "Windsurf" ;;
+  "")
+    # ... existing checks ...
+    [ -f "$WINDSURF_FILE" ] && update_agent_file "$WINDSURF_FILE" "Windsurf";
+    # Update default creation condition
+    ;;
+esac
+```
+
+##### PowerShell script (`scripts/powershell/update-agent-context.ps1`)
+
+Add file variable:
+
+```powershell
+$windsurfFile = Join-Path $repoRoot '.windsurf/rules/specify-rules.md'
+```
+
+Add to switch statement:
+
+```powershell
+switch ($AgentType) {
+    # ... existing cases ...
+    'windsurf' { Update-AgentFile $windsurfFile 'Windsurf' }
+    '' {
+        foreach ($pair in @(
+            # ... existing pairs ...
+            @{file=$windsurfFile; name='Windsurf'}
+        )) {
+            if (Test-Path $pair.file) { Update-AgentFile $pair.file $pair.name }
+        }
+        # Update default creation condition
+    }
+}
+```
+
+#### 6. Update CLI Tool Checks (Optional)
+
+For agents that require CLI tools, add checks in the `check()` command and agent validation:
+
+```python
+# In check() command
+tracker.add("windsurf", "Windsurf IDE (optional)")
+windsurf_ok = check_tool_for_tracker("windsurf", "https://windsurf.com/", tracker)
+
+# In init validation (only if CLI tool required)
+elif selected_ai == "windsurf":
+    if not check_tool("windsurf", "Install from: https://windsurf.com/"):
+        console.print("[red]Error:[/red] Windsurf CLI is required for Windsurf projects")
+        agent_tool_missing = True
+```
+
+**Note**: CLI tool checks are now handled automatically based on the `requires_cli` field in AGENT_CONFIG. No additional code changes needed in the `check()` or `init()` commands - they automatically loop through AGENT_CONFIG and check tools as needed.
+
+## Important Design Decisions
+
+### Using Actual CLI Tool Names as Keys
+
+**CRITICAL**: When adding a new agent to AGENT_CONFIG, always use the **actual executable name** as the dictionary key, not a shortened or convenient version.
+
+**Why this matters:**
+
+- The `check_tool()` function uses `shutil.which(tool)` to find executables in the system PATH
+- If the key doesn't match the actual CLI tool name, you'll need special-case mappings throughout the codebase
+- This creates unnecessary complexity and maintenance burden
+
+**Example - The Cursor Lesson:**
+
+❌ **Wrong approach** (requires special-case mapping):
+
+```python
+AGENT_CONFIG = {
+    "cursor": {  # Shorthand that doesn't match the actual tool
+        "name": "Cursor",
+        # ...
+    }
+}
+
+# Then you need special cases everywhere:
+cli_tool = agent_key
+if agent_key == "cursor":
+    cli_tool = "cursor-agent"  # Map to the real tool name
+```
+
+✅ **Correct approach** (no mapping needed):
+
+```python
+AGENT_CONFIG = {
+    "cursor-agent": {  # Matches the actual executable name
+        "name": "Cursor",
+        # ...
+    }
+}
+
+# No special cases needed - just use agent_key directly!
+```
+
+**Benefits of this approach:**
+
+- Eliminates special-case logic scattered throughout the codebase
+- Makes the code more maintainable and easier to understand
+- Reduces the chance of bugs when adding new agents
+- Tool checking "just works" without additional mappings
+
+#### 7. Update Devcontainer files (Optional)
+
+For agents that have VS Code extensions or require CLI installation, update the devcontainer configuration files:
+
+##### VS Code Extension-based Agents
+
+For agents available as VS Code extensions, add them to `.devcontainer/devcontainer.json`:
+
+```json
+{
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        // ... existing extensions ...
+        // [New Agent Name]
+        "[New Agent Extension ID]"
+      ]
+    }
+  }
+}
+```
+
+##### CLI-based Agents
+
+For agents that require CLI tools, add installation commands to `.devcontainer/post-create.sh`:
+
+```bash
+#!/bin/bash
+
+# Existing installations...
+
+echo -e "\n🤖 Installing [New Agent Name] CLI..."
+# run_command "npm install -g [agent-cli-package]@latest" # Example for node-based CLI
+# or other installation instructions (must be non-interactive and compatible with Linux Debian "Trixie" or later)...
+echo "✅ Done"
+
+```
+
+**Quick Tips:**
+
+- **Extension-based agents**: Add to the `extensions` array in `devcontainer.json`
+- **CLI-based agents**: Add installation scripts to `post-create.sh`
+- **Hybrid agents**: May require both extension and CLI installation
+- **Test thoroughly**: Ensure installations work in the devcontainer environment
+
+## Agent Categories
+
+### CLI-Based Agents
+
+Require a command-line tool to be installed:
+
+- **Claude Code**: `claude` CLI
+- **Gemini CLI**: `gemini` CLI
+- **Cursor**: `cursor-agent` CLI
+- **Qwen Code**: `qwen` CLI
+- **opencode**: `opencode` CLI
+- **Amazon Q Developer CLI**: `q` CLI
+- **CodeBuddy CLI**: `codebuddy` CLI
+- **Qoder CLI**: `qodercli` CLI
+- **Amp**: `amp` CLI
+- **SHAI**: `shai` CLI
+
+### IDE-Based Agents
+
+Work within integrated development environments:
+
+- **GitHub Copilot**: Built into VS Code/compatible editors
+- **Windsurf**: Built into Windsurf IDE
+- **IBM Bob**: Built into IBM Bob IDE
+
+## Command File Formats
+
+### Markdown Format
+
+Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer, Amp, SHAI, IBM Bob
+
+**Standard format:**
+
+```markdown
+---
+description: "Command description"
+---
+
+Command content with {SCRIPT} and $ARGUMENTS placeholders.
+```
+
+**GitHub Copilot Chat Mode format:**
+
+```markdown
+---
+description: "Command description"
+mode: speckit.command-name
+---
+
+Command content with {SCRIPT} and $ARGUMENTS placeholders.
+```
+
+### TOML Format
+
+Used by: Gemini, Qwen
+
+```toml
+description = "Command description"
+
+prompt = """
+Command content with {SCRIPT} and {{args}} placeholders.
+"""
+```
+
+## Directory Conventions
+
+- **CLI agents**: Usually `.<agent-name>/commands/`
+- **IDE agents**: Follow IDE-specific patterns:
+  - Copilot: `.github/agents/`
+  - Cursor: `.cursor/commands/`
+  - Windsurf: `.windsurf/workflows/`
+
+## Argument Patterns
+
+Different agents use different argument placeholders:
+
+- **Markdown/prompt-based**: `$ARGUMENTS`
+- **TOML-based**: `{{args}}`
+- **Script placeholders**: `{SCRIPT}` (replaced with actual script path)
+- **Agent placeholders**: `__AGENT__` (replaced with agent name)
+
+## Testing New Agent Integration
+
+1. **Build test**: Run package creation script locally
+2. **CLI test**: Test `specify init --ai <agent>` command
+3. **File generation**: Verify correct directory structure and files
+4. **Command validation**: Ensure generated commands work with the agent
+5. **Context update**: Test agent context update scripts
+
+## Common Pitfalls
+
+1. **Using shorthand keys instead of actual CLI tool names**: Always use the actual executable name as the AGENT_CONFIG key (e.g., `"cursor-agent"` not `"cursor"`). This prevents the need for special-case mappings throughout the codebase.
+2. **Forgetting update scripts**: Both bash and PowerShell scripts must be updated when adding new agents.
+3. **Incorrect `requires_cli` value**: Set to `True` only for agents that actually have CLI tools to check; set to `False` for IDE-based agents.
+4. **Wrong argument format**: Use correct placeholder format for each agent type (`$ARGUMENTS` for Markdown, `{{args}}` for TOML).
+5. **Directory naming**: Follow agent-specific conventions exactly (check existing agents for patterns).
+6. **Help text inconsistency**: Update all user-facing text consistently (help strings, docstrings, README, error messages).
+
+## Future Considerations
+
+When adding new agents:
+
+- Consider the agent's native command/workflow patterns
+- Ensure compatibility with the Spec-Driven Development process
+- Document any special requirements or limitations
+- Update this guide with lessons learned
+- Verify the actual CLI tool name before adding to AGENT_CONFIG
+
+---
+
+*This documentation should be updated whenever new agents are added to maintain accuracy and completeness.*

CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+<!-- markdownlint-disable MD024 -->
+
+Recent 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.6] - 2026-02-23
+
+### Fixed
+
+- **Parameter Ordering Issues (#1641)**: Fixed CLI parameter parsing issue where option flags were incorrectly consumed as values for preceding options
+  - Added validation to detect when `--ai` or `--ai-commands-dir` incorrectly consume following flags like `--here` or `--ai-skills`
+  - Now provides clear error messages: "Invalid value for --ai: '--here'"
+  - Includes helpful hints suggesting proper usage and listing available agents
+  - Commands like `specify init --ai-skills --ai --here` now fail with actionable feedback instead of confusing "Must specify project name" errors
+  - Added comprehensive test suite (5 new tests) to prevent regressions
+
+## [0.1.5] - 2026-02-21
+
+### Fixed
+
+- **AI Skills Installation Bug (#1658)**: Fixed `--ai-skills` flag not generating skill files for GitHub Copilot and other agents with non-standard command directory structures
+  - Added `commands_subdir` field to `AGENT_CONFIG` to explicitly specify the subdirectory name for each agent
+  - Affected agents now work correctly: copilot (`.github/agents/`), opencode (`.opencode/command/`), windsurf (`.windsurf/workflows/`), codex (`.codex/prompts/`), kilocode (`.kilocode/workflows/`), q (`.amazonq/prompts/`), and agy (`.agent/workflows/`)
+  - The `install_ai_skills()` function now uses the correct path for all agents instead of assuming `commands/` for everyone
+
+## [0.1.4] - 2026-02-20
+
+### Fixed
+
+- **Qoder CLI detection**: Renamed `AGENT_CONFIG` key from `"qoder"` to `"qodercli"` to match the actual executable name, fixing `specify check` and `specify init --ai` detection failures
+
+## [0.1.3] - 2026-02-20
+
+### Added
+
+- **Generic Agent Support**: Added `--ai generic` option for unsupported AI agents ("bring your own agent")
+  - Requires `--ai-commands-dir <path>` to specify where the agent reads commands from
+  - Generates Markdown commands with `$ARGUMENTS` format (compatible with most agents)
+  - Example: `specify init my-project --ai generic --ai-commands-dir .myagent/commands/`
+  - Enables users to start with Spec Kit immediately while their agent awaits formal support
+
+## [0.0.102] - 2026-02-20
+
+- fix: include 'src/**' path in release workflow triggers (#1646)
+
+## [0.0.101] - 2026-02-19
+
+- chore(deps): bump github/codeql-action from 3 to 4 (#1635)
+
+## [0.0.100] - 2026-02-19
+
+- Add pytest and Python linting (ruff) to CI (#1637)
+- feat: add pull request template for better contribution guidelines (#1634)
+
+## [0.0.99] - 2026-02-19
+
+- Feat/ai skills (#1632)
+
+## [0.0.98] - 2026-02-19
+
+- chore(deps): bump actions/stale from 9 to 10 (#1623)
+- feat: add dependabot configuration for pip and GitHub Actions updates (#1622)
+
+## [0.0.97] - 2026-02-18
+
+- Remove Maintainers section from README.md (#1618)
+
+## [0.0.96] - 2026-02-17
+
+- fix: typo in plan-template.md (#1446)
+
+## [0.0.95] - 2026-02-12
+
+- Feat: add a new agent: Google Anti Gravity (#1220)
+
+## [0.0.94] - 2026-02-11
+
+- Add stale workflow for 180-day inactive issues and PRs (#1594)

CODE_OF_CONDUCT.md

@@ -14,21 +14,21 @@ orientation.
 Examples of behavior that contributes to creating a positive environment
 include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or
-advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
   address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Our Responsibilities
@@ -71,4 +71,4 @@ This Code of Conduct is adapted from the [Contributor Covenant][homepage], versi
 available at [http://contributor-covenant.org/version/1/4][version]
 
 [homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/4/
+[version]: http://contributor-covenant.org/version/1/4/

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-## Contributing to Spec Kit
+# Contributing to Spec Kit
 
 Hi there! We're thrilled that you'd like to contribute to Spec Kit. Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE).
 
@@ -11,10 +11,30 @@ These are one time installations required to be able to test your changes locall
 1. Install [Python 3.11+](https://www.python.org/downloads/)
 1. Install [uv](https://docs.astral.sh/uv/) for package management
 1. Install [Git](https://git-scm.com/downloads)
-1. Have an AI coding agent available: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+1. Have an [AI coding agent available](README.md#-supported-ai-agents)
+
+<details>
+<summary><b>💡 Hint if you are using <code>VSCode</code> or <code>GitHub Codespaces</code> as your IDE</b></summary>
+
+<br>
+
+Provided you have [Docker](https://docker.com) installed on your machine, you can leverage [Dev Containers](https://containers.dev) through this [VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), to easily set up your development environment, with aforementioned tools already installed and configured, thanks to the `.devcontainer/devcontainer.json` file (located at the root of the project).
+
+To do so, simply:
+
+- Checkout the repo
+- Open it with VSCode
+- Open the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) and select "Dev Containers: Open Folder in Container..."
+
+On [GitHub Codespaces](https://github.com/features/codespaces) it's even simpler, as it leverages the `.devcontainer/devcontainer.json` automatically upon opening the codespace.
+
+</details>
 
 ## Submitting a pull request
 
+> [!NOTE]
+> If your pull request introduces a large change that materially impacts the work of the CLI or the rest of the repository (e.g., you're introducing new templates, arguments, or otherwise major changes), make sure that it was **discussed and agreed upon** by the project maintainers. Pull requests with large changes that did not have a prior conversation and agreement will be closed.
+
 1. Fork and clone the repository
 1. Configure and install the dependencies: `uv sync`
 1. Make sure the CLI works on your machine: `uv run specify --help`
@@ -28,7 +48,7 @@ Here are a few things you can do that will increase the likelihood of your pull
 
 - Follow the project's coding conventions.
 - Write tests for new functionality.
-- Update documentation (`README.md,` `spec-driven.md`) if your changes affect user-facing features.
+- Update documentation (`README.md`, `spec-driven.md`) if your changes affect user-facing features.
 - Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
 - Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
 - Test your changes with the Spec-Driven Development workflow to ensure compatibility.
@@ -37,11 +57,91 @@ Here are a few things you can do that will increase the likelihood of your pull
 
 When working on spec-kit:
 
-1. Test changes with the `specify` CLI commands (`/specify`, `/plan`, `/tasks`) in your coding agent of choice
+1. Test changes with the `specify` CLI commands (`/speckit.specify`, `/speckit.plan`, `/speckit.tasks`) in your coding agent of choice
 2. Verify templates are working correctly in `templates/` directory
 3. Test script functionality in the `scripts/` directory
 4. Ensure memory files (`memory/constitution.md`) are updated if major process changes are made
 
+### Testing template and command changes locally
+
+Running `uv run specify init` pulls released packages, which won’t include your local changes.  
+To test your templates, commands, and other changes locally, follow these steps:
+
+1. **Create release packages**
+
+   Run the following command to generate the local packages:
+
+   ```bash
+   ./.github/workflows/scripts/create-release-packages.sh v1.0.0
+   ```
+
+2. **Copy the relevant package to your test project**
+
+   ```bash
+   cp -r .genreleases/sdd-copilot-package-sh/. <path-to-test-project>/
+   ```
+
+3. **Open and test the agent**
+
+   Navigate to your test project folder and open the agent to verify your implementation.
+
+## AI contributions in Spec Kit
+
+> [!IMPORTANT]
+>
+> If you are using **any kind of AI assistance** to contribute to Spec Kit,
+> it must be disclosed in the pull request or issue.
+
+We welcome and encourage the use of AI tools to help improve Spec Kit! Many valuable contributions have been enhanced with AI assistance for code generation, issue detection, and feature definition.
+
+That being said, if you are using any kind of AI assistance (e.g., agents, ChatGPT) while contributing to Spec Kit,
+**this must be disclosed in the pull request or issue**, along with the extent to which AI assistance was used (e.g., documentation comments vs. code generation).
+
+If your PR responses or comments are being generated by an AI, disclose that as well.
+
+As an exception, trivial spacing or typo fixes don't need to be disclosed, so long as the changes are limited to small parts of the code or short phrases.
+
+An example disclosure:
+
+> This PR was written primarily by GitHub Copilot.
+
+Or a more detailed disclosure:
+
+> I consulted ChatGPT to understand the codebase but the solution
+> was fully authored manually by myself.
+
+Failure to disclose this is first and foremost rude to the human operators on the other end of the pull request, but it also makes it difficult to
+determine how much scrutiny to apply to the contribution.
+
+In a perfect world, AI assistance would produce equal or higher quality work than any human. That isn't the world we live in today, and in most cases
+where human supervision or expertise is not in the loop, it's generating code that cannot be reasonably maintained or evolved.
+
+### What we're looking for
+
+When submitting AI-assisted contributions, please ensure they include:
+
+- **Clear disclosure of AI use** - You are transparent about AI use and degree to which you're using it for the contribution
+- **Human understanding and testing** - You've personally tested the changes and understand what they do
+- **Clear rationale** - You can explain why the change is needed and how it fits within Spec Kit's goals
+- **Concrete evidence** - Include test cases, scenarios, or examples that demonstrate the improvement
+- **Your own analysis** - Share your thoughts on the end-to-end developer experience
+
+### What we'll close
+
+We reserve the right to close contributions that appear to be:
+
+- Untested changes submitted without verification
+- Generic suggestions that don't address specific Spec Kit needs
+- Bulk submissions that show no human review or understanding
+
+### Guidelines for success
+
+The key is demonstrating that you understand and have validated your proposed changes. If a maintainer can easily tell that a contribution was generated entirely by AI without human input or testing, it likely needs more work before submission.
+
+Contributors who consistently submit low-effort AI-generated changes may be restricted from further contributions at the maintainers' discretion.
+
+Please be respectful to maintainers and disclose AI assistance.
+
 ## Resources
 
 - [Spec-Driven Development Methodology](./spec-driven.md)

LICENSE

@@ -19,3 +19,4 @@ 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.
+

README.md

@@ -1,29 +1,36 @@
 <div align="center">
-    <img src="./media/logo_small.webp"/>
+    <img src="./media/logo_large.webp" alt="Spec Kit Logo" width="200" height="200"/>
     <h1>🌱 Spec Kit</h1>
     <h3><em>Build high-quality software faster.</em></h3>
 </div>
 
 <p align="center">
-    <strong>An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.</strong>
+    <strong>An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of vibe coding every piece from scratch.</strong>
 </p>
 
-[![Release](https://github.com/github/spec-kit/actions/workflows/release.yml/badge.svg)](https://github.com/github/spec-kit/actions/workflows/release.yml)
+<p align="center">
+    <a href="https://github.com/github/spec-kit/actions/workflows/release.yml"><img src="https://github.com/github/spec-kit/actions/workflows/release.yml/badge.svg" alt="Release"/></a>
+    <a href="https://github.com/github/spec-kit/stargazers"><img src="https://img.shields.io/github/stars/github/spec-kit?style=social" alt="GitHub stars"/></a>
+    <a href="https://github.com/github/spec-kit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/github/spec-kit" alt="License"/></a>
+    <a href="https://github.github.io/spec-kit/"><img src="https://img.shields.io/badge/docs-GitHub_Pages-blue" alt="Documentation"/></a>
+</p>
 
 ---
 
 ## Table of Contents
 
 - [🤔 What is Spec-Driven Development?](#-what-is-spec-driven-development)
-- [⚡ Get started](#-get-started)
-- [📚 Core philosophy](#-core-philosophy)
-- [🌟 Development phases](#-development-phases)
-- [🎯 Experimental goals](#-experimental-goals)
+- [⚡ Get Started](#-get-started)
+- [📽️ Video Overview](#️-video-overview)
+- [🤖 Supported AI Agents](#-supported-ai-agents)
+- [🔧 Specify CLI Reference](#-specify-cli-reference)
+- [📚 Core Philosophy](#-core-philosophy)
+- [🌟 Development Phases](#-development-phases)
+- [🎯 Experimental Goals](#-experimental-goals)
 - [🔧 Prerequisites](#-prerequisites)
-- [📖 Learn more](#-learn-more)
-- [📋 Detailed process](#-detailed-process)
+- [📖 Learn More](#-learn-more)
+- [📋 Detailed Process](#-detailed-process)
 - [🔍 Troubleshooting](#-troubleshooting)
-- [👥 Maintainers](#-maintainers)
 - [💬 Support](#-support)
 - [🙏 Acknowledgements](#-acknowledgements)
 - [📄 License](#-license)
@@ -32,56 +39,271 @@
 
 Spec-Driven Development **flips the script** on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: **specifications become executable**, directly generating working implementations rather than just guiding them.
 
-## ⚡ Get started
+## ⚡ Get Started
 
-### 1. Install Specify
+### 1. Install Specify CLI
 
-Initialize your project depending on the coding agent you're using:
+Choose your preferred installation method:
+
+#### Option 1: Persistent Installation (Recommended)
+
+Install once and use everywhere:
+
+```bash
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
+```
+
+Then use the tool directly:
+
+```bash
+# Create new project
+specify init <PROJECT_NAME>
+
+# Or initialize in existing project
+specify init . --ai claude
+# or
+specify init --here --ai claude
+
+# Check installed tools
+specify check
+```
+
+To upgrade Specify, see the [Upgrade Guide](./docs/upgrade.md) for detailed instructions. Quick upgrade:
+
+```bash
+uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+```
+
+#### Option 2: One-time Usage
+
+Run directly without installing:
 
 ```bash
 uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
 ```
 
-### 2. Create the spec
+**Benefits of persistent installation:**
 
-Use the `/specify` command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.
+- Tool stays installed and available in PATH
+- No need to create shell aliases
+- Better tool management with `uv tool list`, `uv tool upgrade`, `uv tool uninstall`
+- Cleaner shell configuration
+
+### 2. Establish project principles
+
+Launch your AI assistant in the project directory. The `/speckit.*` commands are available in the assistant.
+
+Use the **`/speckit.constitution`** command to create your project's governing principles and development guidelines that will guide all subsequent development.
 
 ```bash
-/specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums never other nested albums. Within each album, photos are previewed in a tile-like interface.
+/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements
 ```
 
-### 3. Create a technical implementation plan
+### 3. Create the spec
 
-Use the `/plan` command to provide your tech stack and architecture choices.
+Use the **`/speckit.specify`** command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.
 
 ```bash
-/plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.
+/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.
 ```
 
-### 4. Break down and implement
+### 4. Create a technical implementation plan
 
-Use `/tasks` to create an actionable task list, then ask your agent to implement the feature.
+Use the **`/speckit.plan`** command to provide your tech stack and architecture choices.
+
+```bash
+/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.
+```
+
+### 5. Break down into tasks
+
+Use **`/speckit.tasks`** to create an actionable task list from your implementation plan.
+
+```bash
+/speckit.tasks
+```
+
+### 6. Execute implementation
+
+Use **`/speckit.implement`** to execute all tasks and build your feature according to the plan.
+
+```bash
+/speckit.implement
+```
 
 For detailed step-by-step instructions, see our [comprehensive guide](./spec-driven.md).
 
-## 📚 Core philosophy
+## 📽️ Video Overview
+
+Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)!
+
+[![Spec Kit video header](/media/spec-kit-video-header.jpg)](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)
+
+## 🤖 Supported AI Agents
+
+| Agent                                                                                | Support | Notes                                                                                                                                     |
+| ------------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| [Qoder CLI](https://qoder.com/cli)                                                   | ✅      |                                                                                                                                           |
+| [Amazon Q Developer CLI](https://aws.amazon.com/developer/learning/q-developer-cli/) | ⚠️      | Amazon Q Developer CLI [does not support](https://github.com/aws/amazon-q-developer-cli/issues/3064) custom arguments for slash commands. |
+| [Amp](https://ampcode.com/)                                                          | ✅      |                                                                                                                                           |
+| [Auggie CLI](https://docs.augmentcode.com/cli/overview)                              | ✅      |                                                                                                                                           |
+| [Claude Code](https://www.anthropic.com/claude-code)                                 | ✅      |                                                                                                                                           |
+| [CodeBuddy CLI](https://www.codebuddy.ai/cli)                                        | ✅      |                                                                                                                                           |
+| [Codex CLI](https://github.com/openai/codex)                                         | ✅      |                                                                                                                                           |
+| [Cursor](https://cursor.sh/)                                                         | ✅      |                                                                                                                                           |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli)                            | ✅      |                                                                                                                                           |
+| [GitHub Copilot](https://code.visualstudio.com/)                                     | ✅      |                                                                                                                                           |
+| [IBM Bob](https://www.ibm.com/products/bob)                                          | ✅      | IDE-based agent with slash command support                                                                                                |
+| [Jules](https://jules.google.com/)                                                   | ✅      |                                                                                                                                           |
+| [Kilo Code](https://github.com/Kilo-Org/kilocode)                                    | ✅      |                                                                                                                                           |
+| [opencode](https://opencode.ai/)                                                     | ✅      |                                                                                                                                           |
+| [Qwen Code](https://github.com/QwenLM/qwen-code)                                     | ✅      |                                                                                                                                           |
+| [Roo Code](https://roocode.com/)                                                     | ✅      |                                                                                                                                           |
+| [SHAI (OVHcloud)](https://github.com/ovh/shai)                                       | ✅      |                                                                                                                                           |
+| [Windsurf](https://windsurf.com/)                                                    | ✅      |                                                                                                                                           |
+| [Antigravity (agy)](https://agy.ai/)                                                 | ✅      |                                                                                                                                           |
+| Generic                                                                              | ✅      | Bring your own agent — use `--ai generic --ai-commands-dir <path>` for unsupported agents                                                 |
+
+## 🔧 Specify CLI Reference
+
+The `specify` command supports the following options:
+
+### Commands
+
+| Command | Description                                                                                                                                             |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init`  | Initialize a new Specify project from the latest template                                                                                               |
+| `check` | Check for installed tools (`git`, `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `qwen`, `opencode`, `codex`, `shai`, `qodercli`) |
+
+### `specify init` Arguments & 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`, `agy`, `bob`, `qodercli`, or `generic` (requires `--ai-commands-dir`) |
+| `--ai-commands-dir`    | Option   | Directory for agent command files (required with `--ai generic`, e.g. `.myagent/commands/`)                                                                                                  |
+| `--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                                                                                                                                                           |
+| `--here`               | Flag     | Initialize project in the current directory instead of creating a new one                                                                                                                    |
+| `--force`              | Flag     | Force merge/overwrite when initializing in current directory (skip confirmation)                                                                                                             |
+| `--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
+
+```bash
+# Basic project initialization
+specify init my-project
+
+# Initialize with specific AI assistant
+specify init my-project --ai claude
+
+# Initialize with Cursor support
+specify init my-project --ai cursor-agent
+
+# Initialize with Qoder support
+specify init my-project --ai qodercli
+
+# Initialize with Windsurf support
+specify init my-project --ai windsurf
+
+# Initialize with Amp support
+specify init my-project --ai amp
+
+# Initialize with SHAI support
+specify init my-project --ai shai
+
+# Initialize with IBM Bob support
+specify init my-project --ai bob
+
+# Initialize with an unsupported agent (generic / bring your own agent)
+specify init my-project --ai generic --ai-commands-dir .myagent/commands/
+
+# Initialize with PowerShell scripts (Windows/cross-platform)
+specify init my-project --ai copilot --script ps
+
+# Initialize in current directory
+specify init . --ai copilot
+# or use the --here flag
+specify init --here --ai copilot
+
+# Force merge into current (non-empty) directory without confirmation
+specify init . --force --ai copilot
+# or
+specify init --here --force --ai copilot
+
+# Skip git initialization
+specify init my-project --ai gemini --no-git
+
+# Enable debug output for troubleshooting
+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
+```
+
+### Available Slash Commands
+
+After running `specify init`, your AI coding agent will have access to these slash commands for structured development:
+
+#### Core Commands
+
+Essential commands for the Spec-Driven Development workflow:
+
+| Command                 | Description                                                              |
+| ----------------------- | ------------------------------------------------------------------------ |
+| `/speckit.constitution` | Create or update project governing principles and development guidelines |
+| `/speckit.specify`      | Define what you want to build (requirements and user stories)            |
+| `/speckit.plan`         | Create technical implementation plans with your chosen tech stack        |
+| `/speckit.tasks`        | Generate actionable task lists for implementation                        |
+| `/speckit.implement`    | Execute all tasks to build the feature according to the plan             |
+
+#### Optional Commands
+
+Additional commands for enhanced quality and validation:
+
+| Command              | Description                                                                                                                          |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `/speckit.clarify`   | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`)                                                |
+| `/speckit.analyze`   | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`)                             |
+| `/speckit.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") |
+
+### Environment Variables
+
+| Variable          | Description                                                                                                                                                                                                                                                                                            |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches.<br/>\*\*Must be set in the context of the agent you're working with prior to using `/speckit.plan` or follow-up commands. |
+
+## 📚 Core Philosophy
 
 Spec-Driven Development is a structured process that emphasizes:
 
-- **Intent-driven development** where specifications define the "_what_" before the "_how_"
+- **Intent-driven development** where specifications define the "*what*" before the "*how*"
 - **Rich specification creation** using guardrails and organizational principles
 - **Multi-step refinement** rather than one-shot code generation from prompts
 - **Heavy reliance** on advanced AI model capabilities for specification interpretation
 
-## 🌟 Development phases
+## 🌟 Development Phases
 
-| Phase | Focus | Key Activities |
-|-------|-------|----------------|
-| **0-to-1 Development** ("Greenfield") | Generate from scratch | <ul><li>Start with high-level requirements</li><li>Generate specifications</li><li>Plan implementation steps</li><li>Build production-ready applications</li></ul> |
-| **Creative Exploration** | Parallel implementations | <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul> |
-| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul> |
+| Phase                                    | Focus                    | Key Activities                                                                                                                                                     |
+| ---------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **0-to-1 Development** ("Greenfield")    | Generate from scratch    | <ul><li>Start with high-level requirements</li><li>Generate specifications</li><li>Plan implementation steps</li><li>Build production-ready applications</li></ul> |
+| **Creative Exploration**                 | Parallel implementations | <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul>                         |
+| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul>                                                                |
 
-## 🎯 Experimental goals
+## 🎯 Experimental Goals
 
 Our research and experimentation focus on:
 
@@ -105,24 +327,26 @@ Our research and experimentation focus on:
 
 - Validate the concept of parallel implementation exploration
 - Provide robust iterative feature development workflows
-- Extend processes to handle upgrades and modernization tasks  
+- Extend processes to handle upgrades and modernization tasks
 
 ## 🔧 Prerequisites
 
-- **Linux/macOS** (or WSL2 on Windows)
-- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+- **Linux/macOS/Windows**
+- [Supported](#-supported-ai-agents) AI coding agent.
 - [uv](https://docs.astral.sh/uv/) for package management
 - [Python 3.11+](https://www.python.org/downloads/)
 - [Git](https://git-scm.com/downloads)
 
-## 📖 Learn more
+If you encounter issues with an agent, please open an issue so we can refine the integration.
+
+## 📖 Learn More
 
 - **[Complete Spec-Driven Development Methodology](./spec-driven.md)** - Deep dive into the full process
-- **[Detailed Walkthrough](#detailed-process)** - Step-by-step implementation guide
+- **[Detailed Walkthrough](#-detailed-process)** - Step-by-step implementation guide
 
 ---
 
-## 📋 Detailed process
+## 📋 Detailed Process
 
 <details>
 <summary>Click to expand the detailed step-by-step walkthrough</summary>
@@ -136,7 +360,13 @@ specify init <project_name>
 Or initialize in the current directory:
 
 ```bash
+specify init .
+# or use the --here flag
 specify init --here
+# Skip confirmation when the directory already has files
+specify init . --force
+# or
+specify init --here --force
 ```
 
 ![Specify CLI bootstrapping a new project in the terminal](./media/specify_cli.gif)
@@ -147,28 +377,50 @@ You will be prompted to select the AI agent you are using. You can also proactiv
 specify init <project_name> --ai claude
 specify init <project_name> --ai gemini
 specify init <project_name> --ai copilot
+
 # Or in current directory:
+specify init . --ai claude
+specify init . --ai codex
+
+# or use --here flag
 specify init --here --ai claude
+specify init --here --ai codex
+
+# Force merge into a non-empty current directory
+specify init . --force --ai claude
+
+# or
+specify init --here --force --ai claude
 ```
 
-The CLI will check if you have Claude Code or Gemini CLI installed. If you do not, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command:
+The CLI will check if you have Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, Qoder CLI, or Amazon Q Developer CLI installed. If you do not, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command:
 
 ```bash
 specify init <project_name> --ai claude --ignore-agent-tools
 ```
 
-### **STEP 1:** Bootstrap the project
+### **STEP 1:** Establish project principles
 
 Go to the project folder and run your AI agent. In our example, we're using `claude`.
 
 ![Bootstrapping Claude Code environment](./media/bootstrap-claude-code.gif)
 
-You will know that things are configured correctly if you see the `/specify`, `/plan`, and `/tasks` commands available.
+You will know that things are configured correctly if you see the `/speckit.constitution`, `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement` commands available.
 
-The first step should be creating a new project scaffolding. Use `/specify` command and then provide the concrete requirements for the project you want to develop.
+The first step should be establishing your project's governing principles using the `/speckit.constitution` command. This helps ensure consistent decision-making throughout all subsequent development phases:
 
->[!IMPORTANT]
->Be as explicit as possible about _what_ you are trying to build and _why_. **Do not focus on the tech stack at this point**.
+```text
+/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices.
+```
+
+This step creates or updates the `.specify/memory/constitution.md` file with your project's foundational guidelines that the AI agent will reference during specification, planning, and implementation phases.
+
+### **STEP 2:** Create project specifications
+
+With your project principles established, you can now create the functional specifications. Use the `/speckit.specify` command and then provide the concrete requirements for the project you want to develop.
+
+> [!IMPORTANT]
+> Be as explicit as possible about *what* you are trying to build and *why*. **Do not focus on the tech stack at this point**.
 
 An example prompt:
 
@@ -200,29 +452,38 @@ The produced specification should contain a set of user stories and functional r
 At this stage, your project folder contents should resemble the following:
 
 ```text
-├── memory
-│	 ├── constitution.md
-│	 └── constitution_update_checklist.md
-├── scripts
-│	 ├── check-task-prerequisites.sh
-│	 ├── common.sh
-│	 ├── create-new-feature.sh
-│	 ├── get-feature-paths.sh
-│	 ├── setup-plan.sh
-│	 └── update-claude-md.sh
-├── specs
-│	 └── 001-create-taskify
-│	     └── spec.md
-└── templates
-    ├── CLAUDE-template.md
-    ├── plan-template.md
-    ├── spec-template.md
-    └── tasks-template.md
+└── .specify
+    ├── memory
+    │  └── constitution.md
+    ├── scripts
+    │  ├── check-prerequisites.sh
+    │  ├── common.sh
+    │  ├── create-new-feature.sh
+    │  ├── setup-plan.sh
+    │  └── update-claude-md.sh
+    ├── specs
+    │  └── 001-create-taskify
+    │      └── spec.md
+    └── templates
+        ├── plan-template.md
+        ├── spec-template.md
+        └── tasks-template.md
 ```
 
-### **STEP 2:** Functional specification clarification
+### **STEP 3:** Functional specification clarification (required before planning)
 
-With the baseline specification created, you can go ahead and clarify any of the requirements that were not captured properly within the first shot attempt. For example, you could use a prompt like this within the same Claude Code session:
+With the baseline specification created, you can go ahead and clarify any of the requirements that were not captured properly within the first shot attempt.
+
+You should run the structured clarification workflow **before** creating a technical plan to reduce rework downstream.
+
+Preferred order:
+
+1. Use `/speckit.clarify` (structured) – sequential, coverage-based questioning that records answers in a Clarifications section.
+2. Optionally follow up with ad-hoc free-form refinement if something still feels vague.
+
+If you intentionally want to skip clarification (e.g., spike or exploratory prototype), explicitly state that so the agent doesn't block on missing clarifications.
+
+Example free-form refinement prompt (after `/speckit.clarify` if still needed):
 
 ```text
 For each sample project or project that you create there should be a variable number of tasks between 5 and 15
@@ -238,9 +499,9 @@ Read the review and acceptance checklist, and check off each item in the checkli
 
 It's important to use the interaction with Claude Code as an opportunity to clarify and ask questions around the specification - **do not treat its first attempt as final**.
 
-### **STEP 3:** Generate a plan
+### **STEP 4:** Generate a plan
 
-You can now be specific about the tech stack and other technical requirements. You can use the `/plan` command that is built into the project template with a prompt like this:
+You can now be specific about the tech stack and other technical requirements. You can use the `/speckit.plan` command that is built into the project template with a prompt like this:
 
 ```text
 We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use
@@ -254,25 +515,23 @@ The output of this step will include a number of implementation detail documents
 .
 ├── CLAUDE.md
 ├── memory
-│	 ├── constitution.md
-│	 └── constitution_update_checklist.md
+│  └── constitution.md
 ├── scripts
-│	 ├── check-task-prerequisites.sh
-│	 ├── common.sh
-│	 ├── create-new-feature.sh
-│	 ├── get-feature-paths.sh
-│	 ├── setup-plan.sh
-│	 └── update-claude-md.sh
+│  ├── check-prerequisites.sh
+│  ├── common.sh
+│  ├── create-new-feature.sh
+│  ├── setup-plan.sh
+│  └── update-claude-md.sh
 ├── specs
-│	 └── 001-create-taskify
-│	     ├── contracts
-│	     │	 ├── api-spec.json
-│	     │	 └── signalr-spec.md
-│	     ├── data-model.md
-│	     ├── plan.md
-│	     ├── quickstart.md
-│	     ├── research.md
-│	     └── spec.md
+│  └── 001-create-taskify
+│      ├── contracts
+│      │  ├── api-spec.json
+│      │  └── signalr-spec.md
+│      ├── data-model.md
+│      ├── plan.md
+│      ├── quickstart.md
+│      ├── research.md
+│      └── spec.md
 └── templates
     ├── CLAUDE-template.md
     ├── plan-template.md
@@ -304,10 +563,10 @@ researching .NET Aspire in general and I don't think that's gonna do much for us
 That's way too untargeted research. The research needs to help you solve a specific targeted question.
 ```
 
->[!NOTE]
->Claude Code might be over-eager and add components that you did not ask for. Ask it to clarify the rationale and the source of the change.
+> [!NOTE]
+> Claude Code might be over-eager and add components that you did not ask for. Ask it to clarify the rationale and the source of the change.
 
-### **STEP 4:** Have Claude Code validate the plan
+### **STEP 5:** Have Claude Code validate the plan
 
 With the plan in place, you should have Claude Code run through it to make sure that there are no missing pieces. You can use a prompt like this:
 
@@ -323,23 +582,48 @@ This helps refine the implementation plan and helps you avoid potential blind sp
 
 You can also ask Claude Code (if you have the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli) installed) to go ahead and create a pull request from your current branch to `main` with a detailed description, to make sure that the effort is properly tracked.
 
->[!NOTE]
->Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](base/memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan.
+> [!NOTE]
+> Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](base/memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan.
 
-### STEP 5: Implementation
+### **STEP 6:** Generate task breakdown with /speckit.tasks
 
-Once ready, instruct Claude Code to implement your solution (example path included):
+With the implementation plan validated, you can now break down the plan into specific, actionable tasks that can be executed in the correct order. Use the `/speckit.tasks` command to automatically generate a detailed task breakdown from your implementation plan:
 
 ```text
-implement specs/002-create-taskify/plan.md
+/speckit.tasks
 ```
 
-Claude Code will spring into action and will start creating the implementation.
+This step creates a `tasks.md` file in your feature specification directory that contains:
 
->[!IMPORTANT]
->Claude Code will execute local CLI commands (such as `dotnet`) - make sure you have them installed on your machine.
+- **Task breakdown organized by user story** - Each user story becomes a separate implementation phase with its own set of tasks
+- **Dependency management** - Tasks are ordered to respect dependencies between components (e.g., models before services, services before endpoints)
+- **Parallel execution markers** - Tasks that can run in parallel are marked with `[P]` to optimize development workflow
+- **File path specifications** - Each task includes the exact file paths where implementation should occur
+- **Test-driven development structure** - If tests are requested, test tasks are included and ordered to be written before implementation
+- **Checkpoint validation** - Each user story phase includes checkpoints to validate independent functionality
 
-Once the implementation step is done, ask Claude Code to try to run the application and resolve any emerging build errors. If the application runs, but there are _runtime errors_ that are not directly available to Claude Code through CLI logs (e.g., errors rendered in browser logs), copy and paste the error in Claude Code and have it attempt to resolve it.
+The generated tasks.md provides a clear roadmap for the `/speckit.implement` command, ensuring systematic implementation that maintains code quality and allows for incremental delivery of user stories.
+
+### **STEP 7:** Implementation
+
+Once ready, use the `/speckit.implement` command to execute your implementation plan:
+
+```text
+/speckit.implement
+```
+
+The `/speckit.implement` command will:
+
+- Validate that all prerequisites are in place (constitution, spec, plan, and tasks)
+- Parse the task breakdown from `tasks.md`
+- Execute tasks in the correct order, respecting dependencies and parallel execution markers
+- Follow the TDD approach defined in your task plan
+- Provide progress updates and handle errors appropriately
+
+> [!IMPORTANT]
+> The AI agent will execute local CLI commands (such as `dotnet`, `npm`, etc.) - make sure you have the required tools installed on your machine.
+
+Once the implementation is complete, test the application and resolve any runtime errors that may not be visible in CLI logs (e.g., browser console errors). You can copy and paste such errors back to your AI agent for resolution.
 
 </details>
 
@@ -364,11 +648,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.

SECURITY.md

@@ -1,10 +1,10 @@
-Thanks for helping make GitHub safe for everyone.
+# Security Policy
 
-# Security
+Thanks for helping make GitHub safe for everyone.
 
 GitHub takes the security of our software products and services seriously, including all of the open source code repositories managed through our GitHub organizations, such as [GitHub](https://github.com/GitHub).
 
-Even though [open source repositories are outside of the scope of our bug bounty program](https://bounty.github.com/index.html#scope) and therefore not eligible for bounty rewards, we will ensure that your finding gets passed along to the appropriate maintainers for remediation. 
+Even though [open source repositories are outside of the scope of our bug bounty program](https://bounty.github.com/index.html#scope) and therefore not eligible for bounty rewards, we will ensure that your finding gets passed along to the appropriate maintainers for remediation.
 
 ## Reporting Security Issues
 
@@ -16,16 +16,16 @@ Instead, please send an email to opensource-security[@]github.com.
 
 Please include as much of the information listed below as you can to help us better understand and resolve the issue:
 
-  * The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting)
-  * Full paths of source file(s) related to the manifestation of the issue
-  * The location of the affected source code (tag/branch/commit or direct URL)
-  * Any special configuration required to reproduce the issue
-  * Step-by-step instructions to reproduce the issue
-  * Proof-of-concept or exploit code (if possible)
-  * Impact of the issue, including how an attacker might exploit the issue
+- The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting)
+- Full paths of source file(s) related to the manifestation of the issue
+- The location of the affected source code (tag/branch/commit or direct URL)
+- Any special configuration required to reproduce the issue
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code (if possible)
+- Impact of the issue, including how an attacker might exploit the issue
 
 This information will help us triage your report more quickly.
 
 ## Policy
 
-See [GitHub's Safe Harbor Policy](https://docs.github.com/en/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor#1-safe-harbor-terms)
+See [GitHub's Safe Harbor Policy](https://docs.github.com/en/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor#1-safe-harbor-terms)

SUPPORT.md

@@ -1,4 +1,4 @@
-# Support 
+# Support
 
 ## How to file issues and get help
 

docs/.gitignore

@@ -0,0 +1,9 @@
+# DocFX build output
+_site/
+obj/
+.docfx/
+
+# Temporary files
+*.tmp
+*.log
+

docs/README.md

@@ -0,0 +1,35 @@
+# Documentation
+
+This folder contains the documentation source files for Spec Kit, built using [DocFX](https://dotnet.github.io/docfx/).
+
+## Building Locally
+
+To build the documentation locally:
+
+1. Install DocFX:
+
+   ```bash
+   dotnet tool install -g docfx
+   ```
+
+2. Build the documentation:
+
+   ```bash
+   cd docs
+   docfx docfx.json --serve
+   ```
+
+3. Open your browser to `http://localhost:8080` to view the documentation.
+
+## Structure
+
+- `docfx.json` - DocFX configuration file
+- `index.md` - Main documentation homepage
+- `toc.yml` - Table of contents configuration
+- `installation.md` - Installation guide
+- `quickstart.md` - Quick start guide
+- `_site/` - Generated documentation output (ignored by git)
+
+## Deployment
+
+Documentation is automatically built and deployed to GitHub Pages when changes are pushed to the `main` branch. The workflow is defined in `.github/workflows/docs.yml`.

docs/docfx.json

@@ -0,0 +1,71 @@
+{
+  "build": {
+    "content": [
+      {
+        "files": [
+          "*.md",
+          "toc.yml"
+        ]
+      },
+      {
+        "files": [
+          "../README.md",
+          "../CONTRIBUTING.md",
+          "../CODE_OF_CONDUCT.md",
+          "../SECURITY.md",
+          "../SUPPORT.md"
+        ],
+        "dest": "."
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      },
+      {
+        "files": [
+          "../media/**"
+        ],
+        "dest": "media"
+      }
+    ],
+    "overwrite": [
+      {
+        "files": [
+          "apidoc/**.md"
+        ],
+        "exclude": [
+          "obj/**",
+          "_site/**"
+        ]
+      }
+    ],
+    "dest": "_site",
+    "globalMetadataFiles": [],
+    "fileMetadataFiles": [],
+    "template": [
+      "default",
+      "modern"
+    ],
+    "postProcessors": [],
+    "markdownEngineName": "markdig",
+    "noLangKeyword": false,
+    "keepFileLink": false,
+    "cleanupCacheHistory": false,
+    "disableGitFeatures": false,
+    "globalMetadata": {
+      "_appTitle": "Spec Kit Documentation",
+      "_appName": "Spec Kit",
+      "_appFooter": "Spec Kit - A specification-driven development toolkit",
+      "_enableSearch": true,
+      "_disableContribution": false,
+      "_gitContribute": {
+        "repo": "https://github.com/github/spec-kit",
+        "branch": "main"
+      }
+    }
+  }
+}
+

docs/index.md

@@ -0,0 +1,67 @@
+# Spec Kit
+
+*Build high-quality software faster.*
+
+**An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.**
+
+## What is Spec-Driven Development?
+
+Spec-Driven Development **flips the script** on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: **specifications become executable**, directly generating working implementations rather than just guiding them.
+
+## Getting Started
+
+- [Installation Guide](installation.md)
+- [Quick Start Guide](quickstart.md)
+- [Upgrade Guide](upgrade.md)
+- [Local Development](local-development.md)
+
+## Core Philosophy
+
+Spec-Driven Development is a structured process that emphasizes:
+
+- **Intent-driven development** where specifications define the "*what*" before the "*how*"
+- **Rich specification creation** using guardrails and organizational principles
+- **Multi-step refinement** rather than one-shot code generation from prompts
+- **Heavy reliance** on advanced AI model capabilities for specification interpretation
+
+## Development Phases
+
+| Phase | Focus | Key Activities |
+|-------|-------|----------------|
+| **0-to-1 Development** ("Greenfield") | Generate from scratch | <ul><li>Start with high-level requirements</li><li>Generate specifications</li><li>Plan implementation steps</li><li>Build production-ready applications</li></ul> |
+| **Creative Exploration** | Parallel implementations | <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul> |
+| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul> |
+
+## Experimental Goals
+
+Our research and experimentation focus on:
+
+### Technology Independence
+
+- Create applications using diverse technology stacks
+- Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks
+
+### Enterprise Constraints
+
+- Demonstrate mission-critical application development
+- Incorporate organizational constraints (cloud providers, tech stacks, engineering practices)
+- Support enterprise design systems and compliance requirements
+
+### User-Centric Development
+
+- Build applications for different user cohorts and preferences
+- Support various development approaches (from vibe-coding to AI-native development)
+
+### Creative & Iterative Processes
+
+- Validate the concept of parallel implementation exploration
+- Provide robust iterative feature development workflows
+- Extend processes to handle upgrades and modernization tasks
+
+## Contributing
+
+Please see our [Contributing Guide](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md) for information on how to contribute to this project.
+
+## Support
+
+For support, please check our [Support Guide](https://github.com/github/spec-kit/blob/main/SUPPORT.md) or open an issue on GitHub.

docs/installation.md

@@ -0,0 +1,92 @@
+# Installation Guide
+
+## Prerequisites
+
+- **Linux/macOS** (or Windows; PowerShell scripts now supported without WSL)
+- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [Codebuddy CLI](https://www.codebuddy.ai/cli) or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+- [uv](https://docs.astral.sh/uv/) for package management
+- [Python 3.11+](https://www.python.org/downloads/)
+- [Git](https://git-scm.com/downloads)
+
+## Installation
+
+### Initialize a New Project
+
+The easiest way to get started is to initialize a new project:
+
+```bash
+uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
+```
+
+Or initialize in the current directory:
+
+```bash
+uvx --from git+https://github.com/github/spec-kit.git specify init .
+# or use the --here flag
+uvx --from git+https://github.com/github/spec-kit.git specify init --here
+```
+
+### Specify AI Agent
+
+You can proactively specify your AI agent during initialization:
+
+```bash
+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai claude
+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai gemini
+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai copilot
+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai codebuddy
+```
+
+### Specify Script Type (Shell vs PowerShell)
+
+All automation scripts now have both Bash (`.sh`) and PowerShell (`.ps1`) variants.
+
+Auto behavior:
+
+- Windows default: `ps`
+- Other OS default: `sh`
+- Interactive mode: you'll be prompted unless you pass `--script`
+
+Force a specific script type:
+
+```bash
+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --script sh
+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --script ps
+```
+
+### Ignore Agent Tools Check
+
+If you prefer to get the templates without checking for the right tools:
+
+```bash
+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai claude --ignore-agent-tools
+```
+
+## Verification
+
+After initialization, you should see the following commands available in your AI agent:
+
+- `/speckit.specify` - Create specifications
+- `/speckit.plan` - Generate implementation plans  
+- `/speckit.tasks` - Break down into actionable tasks
+
+The `.specify/scripts` directory will contain both `.sh` and `.ps1` scripts.
+
+## Troubleshooting
+
+### Git Credential Manager on Linux
+
+If you're having issues with Git authentication on Linux, you can install Git Credential Manager:
+
+```bash
+#!/usr/bin/env bash
+set -e
+echo "Downloading Git Credential Manager v2.6.1..."
+wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
+echo "Installing Git Credential Manager..."
+sudo dpkg -i gcm-linux_amd64.2.6.1.deb
+echo "Configuring Git to use GCM..."
+git config --global credential.helper manager
+echo "Cleaning up..."
+rm gcm-linux_amd64.2.6.1.deb
+```

docs/local-development.md

@@ -0,0 +1,175 @@
+# Local Development Guide
+
+This guide shows how to iterate on the `specify` CLI locally without publishing a release or committing to `main` first.
+
+> Scripts now have both Bash (`.sh`) and PowerShell (`.ps1`) variants. The CLI auto-selects based on OS unless you pass `--script sh|ps`.
+
+## 1. Clone and Switch Branches
+
+```bash
+git clone https://github.com/github/spec-kit.git
+cd spec-kit
+# Work on a feature branch
+git checkout -b your-feature-branch
+```
+
+## 2. Run the CLI Directly (Fastest Feedback)
+
+You can execute the CLI via the module entrypoint without installing anything:
+
+```bash
+# From repo root
+python -m src.specify_cli --help
+python -m src.specify_cli init demo-project --ai claude --ignore-agent-tools --script sh
+```
+
+If you prefer invoking the script file style (uses shebang):
+
+```bash
+python src/specify_cli/__init__.py init demo-project --script ps
+```
+
+## 3. Use Editable Install (Isolated Environment)
+
+Create an isolated environment using `uv` so dependencies resolve exactly like end users get them:
+
+```bash
+# Create & activate virtual env (uv auto-manages .venv)
+uv venv
+source .venv/bin/activate  # or on Windows PowerShell: .venv\Scripts\Activate.ps1
+
+# Install project in editable mode
+uv pip install -e .
+
+# Now 'specify' entrypoint is available
+specify --help
+```
+
+Re-running after code edits requires no reinstall because of editable mode.
+
+## 4. Invoke with uvx Directly From Git (Current Branch)
+
+`uvx` can run from a local path (or a Git ref) to simulate user flows:
+
+```bash
+uvx --from . specify init demo-uvx --ai copilot --ignore-agent-tools --script sh
+```
+
+You can also point uvx at a specific branch without merging:
+
+```bash
+# Push your working branch first
+git push origin your-feature-branch
+uvx --from git+https://github.com/github/spec-kit.git@your-feature-branch specify init demo-branch-test --script ps
+```
+
+### 4a. Absolute Path uvx (Run From Anywhere)
+
+If you're in another directory, use an absolute path instead of `.`:
+
+```bash
+uvx --from /mnt/c/GitHub/spec-kit specify --help
+uvx --from /mnt/c/GitHub/spec-kit specify init demo-anywhere --ai copilot --ignore-agent-tools --script sh
+```
+
+Set an environment variable for convenience:
+
+```bash
+export SPEC_KIT_SRC=/mnt/c/GitHub/spec-kit
+uvx --from "$SPEC_KIT_SRC" specify init demo-env --ai copilot --ignore-agent-tools --script ps
+```
+
+(Optional) Define a shell function:
+
+```bash
+specify-dev() { uvx --from /mnt/c/GitHub/spec-kit specify "$@"; }
+# Then
+specify-dev --help
+```
+
+## 5. Testing Script Permission Logic
+
+After running an `init`, check that shell scripts are executable on POSIX systems:
+
+```bash
+ls -l scripts | grep .sh
+# Expect owner execute bit (e.g. -rwxr-xr-x)
+```
+
+On Windows you will instead use the `.ps1` scripts (no chmod needed).
+
+## 6. Run Lint / Basic Checks (Add Your Own)
+
+Currently no enforced lint config is bundled, but you can quickly sanity check importability:
+
+```bash
+python -c "import specify_cli; print('Import OK')"
+```
+
+## 7. Build a Wheel Locally (Optional)
+
+Validate packaging before publishing:
+
+```bash
+uv build
+ls dist/
+```
+
+Install the built artifact into a fresh throwaway environment if needed.
+
+## 8. Using a Temporary Workspace
+
+When testing `init --here` in a dirty directory, create a temp workspace:
+
+```bash
+mkdir /tmp/spec-test && cd /tmp/spec-test
+python -m src.specify_cli init --here --ai claude --ignore-agent-tools --script sh  # if repo copied here
+```
+
+Or copy only the modified CLI portion if you want a lighter sandbox.
+
+## 9. Debug Network / TLS Skips
+
+If you need to bypass TLS validation while experimenting:
+
+```bash
+specify check --skip-tls
+specify init demo --skip-tls --ai gemini --ignore-agent-tools --script ps
+```
+
+(Use only for local experimentation.)
+
+## 10. Rapid Edit Loop Summary
+
+| Action | Command |
+|--------|---------|
+| Run CLI directly | `python -m src.specify_cli --help` |
+| Editable install | `uv pip install -e .` then `specify ...` |
+| Local uvx run (repo root) | `uvx --from . specify ...` |
+| Local uvx run (abs path) | `uvx --from /mnt/c/GitHub/spec-kit specify ...` |
+| Git branch uvx | `uvx --from git+URL@branch specify ...` |
+| Build wheel | `uv build` |
+
+## 11. Cleaning Up
+
+Remove build artifacts / virtual env quickly:
+
+```bash
+rm -rf .venv dist build *.egg-info
+```
+
+## 12. Common Issues
+
+| Symptom | Fix |
+|---------|-----|
+| `ModuleNotFoundError: typer` | Run `uv pip install -e .` |
+| Scripts not executable (Linux) | Re-run init or `chmod +x scripts/*.sh` |
+| Git step skipped | You passed `--no-git` or Git not installed |
+| Wrong script type downloaded | Pass `--script sh` or `--script ps` explicitly |
+| TLS errors on corporate network | Try `--skip-tls` (not for production) |
+
+## 13. Next Steps
+
+- Update docs and run through Quick Start using your modified CLI
+- Open a PR when satisfied
+- (Optional) Tag a release once changes land in `main`

docs/quickstart.md

@@ -0,0 +1,178 @@
+# Quick Start Guide
+
+This guide will help you get started with Spec-Driven Development using Spec Kit.
+
+> [!NOTE]
+> All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`.
+
+## The 6-Step Process
+
+> [!TIP]
+> **Context Awareness**: Spec Kit commands automatically detect the active feature based on your current Git branch (e.g., `001-feature-name`). To switch between different specifications, simply switch Git branches.
+
+### Step 1: Install Specify
+
+**In your terminal**, run the `specify` CLI command to initialize your project:
+
+```bash
+# Create a new project directory
+uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
+
+# OR initialize in the current directory
+uvx --from git+https://github.com/github/spec-kit.git specify init .
+```
+
+Pick script type explicitly (optional):
+
+```bash
+uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --script ps  # Force PowerShell
+uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --script sh  # Force POSIX shell
+```
+
+### Step 2: Define Your Constitution
+
+**In your AI Agent's chat interface**, use the `/speckit.constitution` slash command to establish the core rules and principles for your project. You should provide your project's specific principles as arguments.
+
+```markdown
+/speckit.constitution This project follows a "Library-First" approach. All features must be implemented as standalone libraries first. We use TDD strictly. We prefer functional programming patterns.
+```
+
+### Step 3: Create the Spec
+
+**In the chat**, use the `/speckit.specify` slash command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.
+
+```markdown
+/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.
+```
+
+### Step 4: Refine the Spec
+
+**In the chat**, use the `/speckit.clarify` slash command to identify and resolve ambiguities in your specification. You can provide specific focus areas as arguments.
+
+```bash
+/speckit.clarify Focus on security and performance requirements.
+```
+
+### Step 5: Create a Technical Implementation Plan
+
+**In the chat**, use the `/speckit.plan` slash command to provide your tech stack and architecture choices.
+
+```markdown
+/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.
+```
+
+### Step 6: Break Down and Implement
+
+**In the chat**, use the `/speckit.tasks` slash command to create an actionable task list.
+
+```markdown
+/speckit.tasks
+```
+
+Optionally, validate the plan with `/speckit.analyze`:
+
+```markdown
+/speckit.analyze
+```
+
+Then, use the `/speckit.implement` slash command to execute the plan.
+
+```markdown
+/speckit.implement
+```
+
+> [!TIP]
+> **Phased Implementation**: For complex projects, implement in phases to avoid overwhelming the agent's context. Start with core functionality, validate it works, then add features incrementally.
+
+## Detailed Example: Building Taskify
+
+Here's a complete example of building a team productivity platform:
+
+### Step 1: Define Constitution
+
+Initialize the project's constitution to set ground rules:
+
+```markdown
+/speckit.constitution Taskify is a "Security-First" application. All user inputs must be validated. We use a microservices architecture. Code must be fully documented.
+```
+
+### Step 2: Define Requirements with `/speckit.specify`
+
+```text
+Develop Taskify, a team productivity platform. It should allow users to create projects, add team members,
+assign tasks, comment and move tasks between boards in Kanban style. In this initial phase for this feature,
+let's call it "Create Taskify," let's have multiple users but the users will be declared ahead of time, predefined.
+I want five users in two different categories, one product manager and four engineers. Let's create three
+different sample projects. Let's have the standard Kanban columns for the status of each task, such as "To Do,"
+"In Progress," "In Review," and "Done." There will be no login for this application as this is just the very
+first testing thing to ensure that our basic features are set up.
+```
+
+### Step 3: Refine the Specification
+
+Use the `/speckit.clarify` command to interactively resolve any ambiguities in your specification. You can also provide specific details you want to ensure are included.
+
+```bash
+/speckit.clarify I want to clarify the task card details. For each task in the UI for a task card, you should be able to change the current status of the task between the different columns in the Kanban work board. You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that task card, assign one of the valid users.
+```
+
+You can continue to refine the spec with more details using `/speckit.clarify`:
+
+```bash
+/speckit.clarify When you first launch Taskify, it's going to give you a list of the five users to pick from. There will be no password required. When you click on a user, you go into the main view, which displays the list of projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns. You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can delete any comments that you made, but you can't delete comments anybody else made.
+```
+
+### Step 4: Validate the Spec
+
+Validate the specification checklist using the `/speckit.checklist` command:
+
+```bash
+/speckit.checklist
+```
+
+### Step 5: Generate Technical Plan with `/speckit.plan`
+
+Be specific about your tech stack and technical requirements:
+
+```bash
+/speckit.plan We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API, tasks API, and a notifications API.
+```
+
+### Step 6: Define Tasks
+
+Generate an actionable task list using the `/speckit.tasks` command:
+
+```bash
+/speckit.tasks
+```
+
+### Step 7: Validate and Implement
+
+Have your AI agent audit the implementation plan using `/speckit.analyze`:
+
+```bash
+/speckit.analyze
+```
+
+Finally, implement the solution:
+
+```bash
+/speckit.implement
+```
+
+> [!TIP]
+> **Phased Implementation**: For large projects like Taskify, consider implementing in phases (e.g., Phase 1: Basic project/task structure, Phase 2: Kanban functionality, Phase 3: Comments and assignments). This prevents context saturation and allows for validation at each stage.
+
+## Key Principles
+
+- **Be explicit** about what you're building and why
+- **Don't focus on tech stack** during specification phase
+- **Iterate and refine** your specifications before implementation
+- **Validate** the plan before coding begins
+- **Let the AI agent handle** the implementation details
+
+## Next Steps
+
+- Read the [complete methodology](../spec-driven.md) for in-depth guidance
+- Check out [more examples](../templates) in the repository
+- Explore the [source code on GitHub](https://github.com/github/spec-kit)

docs/toc.yml

@@ -0,0 +1,19 @@
+# Home page
+- name: Home
+  href: index.md
+
+# Getting started section
+- name: Getting Started
+  items:
+    - name: Installation
+      href: installation.md
+    - name: Quick Start
+      href: quickstart.md
+    - name: Upgrade
+      href: upgrade.md
+
+# Development workflows
+- name: Development
+  items:
+    - name: Local Development
+      href: local-development.md

docs/upgrade.md

@@ -0,0 +1,444 @@
+# Upgrade Guide
+
+> You have Spec Kit installed and want to upgrade to the latest version to get new features, bug fixes, or updated slash commands. This guide covers both upgrading the CLI tool and updating your project files.
+
+---
+
+## Quick Reference
+
+| What to Upgrade | Command | When to Use |
+|----------------|---------|-------------|
+| **CLI Tool Only** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git` | Get latest CLI features without touching project files |
+| **Project Files** | `specify init --here --force --ai <your-agent>` | Update slash commands, templates, and scripts in your project |
+| **Both** | Run CLI upgrade, then project update | Recommended for major version updates |
+
+---
+
+## Part 1: Upgrade the CLI Tool
+
+The CLI tool (`specify`) is separate from your project files. Upgrade it to get the latest features and bug fixes.
+
+### If you installed with `uv tool install`
+
+```bash
+uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+```
+
+### If you use one-shot `uvx` commands
+
+No upgrade needed—`uvx` always fetches the latest version. Just run your commands as normal:
+
+```bash
+uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai copilot
+```
+
+### Verify the upgrade
+
+```bash
+specify check
+```
+
+This shows installed tools and confirms the CLI is working.
+
+---
+
+## Part 2: Updating Project Files
+
+When Spec Kit releases new features (like new slash commands or updated templates), you need to refresh your project's Spec Kit files.
+
+### What gets updated?
+
+Running `specify init --here --force` will update:
+
+- ✅ **Slash command files** (`.claude/commands/`, `.github/prompts/`, etc.)
+- ✅ **Script files** (`.specify/scripts/`)
+- ✅ **Template files** (`.specify/templates/`)
+- ✅ **Shared memory files** (`.specify/memory/`) - **⚠️ See warnings below**
+
+### What stays safe?
+
+These files are **never touched** by the upgrade—the template packages don't even contain them:
+
+- ✅ **Your specifications** (`specs/001-my-feature/spec.md`, etc.) - **CONFIRMED SAFE**
+- ✅ **Your implementation plans** (`specs/001-my-feature/plan.md`, `tasks.md`, etc.) - **CONFIRMED SAFE**
+- ✅ **Your source code** - **CONFIRMED SAFE**
+- ✅ **Your git history** - **CONFIRMED SAFE**
+
+The `specs/` directory is completely excluded from template packages and will never be modified during upgrades.
+
+### Update command
+
+Run this inside your project directory:
+
+```bash
+specify init --here --force --ai <your-agent>
+```
+
+Replace `<your-agent>` with your AI assistant. Refer to this list of [Supported AI Agents](../README.md#-supported-ai-agents)
+
+**Example:**
+
+```bash
+specify init --here --force --ai copilot
+```
+
+### Understanding the `--force` flag
+
+Without `--force`, the CLI warns you and asks for confirmation:
+
+```text
+Warning: Current directory is not empty (25 items)
+Template files will be merged with existing content and may overwrite existing files
+Proceed? [y/N]
+```
+
+With `--force`, it skips the confirmation and proceeds immediately.
+
+**Important: Your `specs/` directory is always safe.** The `--force` flag only affects template files (commands, scripts, templates, memory). Your feature specifications, plans, and tasks in `specs/` are never included in upgrade packages and cannot be overwritten.
+
+---
+
+## ⚠️ Important Warnings
+
+### 1. Constitution file will be overwritten
+
+**Known issue:** `specify init --here --force` currently overwrites `.specify/memory/constitution.md` with the default template, erasing any customizations you made.
+
+**Workaround:**
+
+```bash
+# 1. Back up your constitution before upgrading
+cp .specify/memory/constitution.md .specify/memory/constitution-backup.md
+
+# 2. Run the upgrade
+specify init --here --force --ai copilot
+
+# 3. Restore your customized constitution
+mv .specify/memory/constitution-backup.md .specify/memory/constitution.md
+```
+
+Or use git to restore it:
+
+```bash
+# After upgrade, restore from git history
+git restore .specify/memory/constitution.md
+```
+
+### 2. Custom template modifications
+
+If you customized any templates in `.specify/templates/`, the upgrade will overwrite them. Back them up first:
+
+```bash
+# Back up custom templates
+cp -r .specify/templates .specify/templates-backup
+
+# After upgrade, merge your changes back manually
+```
+
+### 3. Duplicate slash commands (IDE-based agents)
+
+Some IDE-based agents (like Kilo Code, Windsurf) may show **duplicate slash commands** after upgrading—both old and new versions appear.
+
+**Solution:** Manually delete the old command files from your agent's folder.
+
+**Example for Kilo Code:**
+
+```bash
+# Navigate to the agent's commands folder
+cd .kilocode/rules/
+
+# List files and identify duplicates
+ls -la
+
+# Delete old versions (example filenames - yours may differ)
+rm speckit.specify-old.md
+rm speckit.plan-v1.md
+```
+
+Restart your IDE to refresh the command list.
+
+---
+
+## Common Scenarios
+
+### Scenario 1: "I just want new slash commands"
+
+```bash
+# Upgrade CLI (if using persistent install)
+uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+
+# Update project files to get new commands
+specify init --here --force --ai copilot
+
+# Restore your constitution if customized
+git restore .specify/memory/constitution.md
+```
+
+### Scenario 2: "I customized templates and constitution"
+
+```bash
+# 1. Back up customizations
+cp .specify/memory/constitution.md /tmp/constitution-backup.md
+cp -r .specify/templates /tmp/templates-backup
+
+# 2. Upgrade CLI
+uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+
+# 3. Update project
+specify init --here --force --ai copilot
+
+# 4. Restore customizations
+mv /tmp/constitution-backup.md .specify/memory/constitution.md
+# Manually merge template changes if needed
+```
+
+### Scenario 3: "I see duplicate slash commands in my IDE"
+
+This happens with IDE-based agents (Kilo Code, Windsurf, Roo Code, etc.).
+
+```bash
+# Find the agent folder (example: .kilocode/rules/)
+cd .kilocode/rules/
+
+# List all files
+ls -la
+
+# Delete old command files
+rm speckit.old-command-name.md
+
+# Restart your IDE
+```
+
+### Scenario 4: "I'm working on a project without Git"
+
+If you initialized your project with `--no-git`, you can still upgrade:
+
+```bash
+# Manually back up files you customized
+cp .specify/memory/constitution.md /tmp/constitution-backup.md
+
+# Run upgrade
+specify init --here --force --ai copilot --no-git
+
+# Restore customizations
+mv /tmp/constitution-backup.md .specify/memory/constitution.md
+```
+
+The `--no-git` flag skips git initialization but doesn't affect file updates.
+
+---
+
+## Using `--no-git` Flag
+
+The `--no-git` flag tells Spec Kit to **skip git repository initialization**. This is useful when:
+
+- You manage version control differently (Mercurial, SVN, etc.)
+- Your project is part of a larger monorepo with existing git setup
+- You're experimenting and don't want version control yet
+
+**During initial setup:**
+
+```bash
+specify init my-project --ai copilot --no-git
+```
+
+**During upgrade:**
+
+```bash
+specify init --here --force --ai copilot --no-git
+```
+
+### What `--no-git` does NOT do
+
+❌ Does NOT prevent file updates
+❌ Does NOT skip slash command installation
+❌ Does NOT affect template merging
+
+It **only** skips running `git init` and creating the initial commit.
+
+### Working without Git
+
+If you use `--no-git`, you'll need to manage feature directories manually:
+
+**Set the `SPECIFY_FEATURE` environment variable** before using planning commands:
+
+```bash
+# Bash/Zsh
+export SPECIFY_FEATURE="001-my-feature"
+
+# PowerShell
+$env:SPECIFY_FEATURE = "001-my-feature"
+```
+
+This tells Spec Kit which feature directory to use when creating specs, plans, and tasks.
+
+**Why this matters:** Without git, Spec Kit can't detect your current branch name to determine the active feature. The environment variable provides that context manually.
+
+---
+
+## Troubleshooting
+
+### "Slash commands not showing up after upgrade"
+
+**Cause:** Agent didn't reload the command files.
+
+**Fix:**
+
+1. **Restart your IDE/editor** completely (not just reload window)
+2. **For CLI-based agents**, verify files exist:
+
+   ```bash
+   ls -la .claude/commands/      # Claude Code
+   ls -la .gemini/commands/       # Gemini
+   ls -la .cursor/commands/       # Cursor
+   ```
+
+3. **Check agent-specific setup:**
+   - Codex requires `CODEX_HOME` environment variable
+   - Some agents need workspace restart or cache clearing
+
+### "I lost my constitution customizations"
+
+**Fix:** Restore from git or backup:
+
+```bash
+# If you committed before upgrading
+git restore .specify/memory/constitution.md
+
+# If you backed up manually
+cp /tmp/constitution-backup.md .specify/memory/constitution.md
+```
+
+**Prevention:** Always commit or back up `constitution.md` before upgrading.
+
+### "Warning: Current directory is not empty"
+
+**Full warning message:**
+
+```text
+Warning: Current directory is not empty (25 items)
+Template files will be merged with existing content and may overwrite existing files
+Do you want to continue? [y/N]
+```
+
+**What this means:**
+
+This warning appears when you run `specify init --here` (or `specify init .`) in a directory that already has files. It's telling you:
+
+1. **The directory has existing content** - In the example, 25 files/folders
+2. **Files will be merged** - New template files will be added alongside your existing files
+3. **Some files may be overwritten** - If you already have Spec Kit files (`.claude/`, `.specify/`, etc.), they'll be replaced with the new versions
+
+**What gets overwritten:**
+
+Only Spec Kit infrastructure files:
+
+- Agent command files (`.claude/commands/`, `.github/prompts/`, etc.)
+- Scripts in `.specify/scripts/`
+- Templates in `.specify/templates/`
+- Memory files in `.specify/memory/` (including constitution)
+
+**What stays untouched:**
+
+- Your `specs/` directory (specifications, plans, tasks)
+- Your source code files
+- Your `.git/` directory and git history
+- Any other files not part of Spec Kit templates
+
+**How to respond:**
+
+- **Type `y` and press Enter** - Proceed with the merge (recommended if upgrading)
+- **Type `n` and press Enter** - Cancel the operation
+- **Use `--force` flag** - Skip this confirmation entirely:
+
+  ```bash
+  specify init --here --force --ai copilot
+  ```
+
+**When you see this warning:**
+
+- ✅ **Expected** when upgrading an existing Spec Kit project
+- ✅ **Expected** when adding Spec Kit to an existing codebase
+- ⚠️ **Unexpected** if you thought you were creating a new project in an empty directory
+
+**Prevention tip:** Before upgrading, commit or back up your `.specify/memory/constitution.md` if you customized it.
+
+### "CLI upgrade doesn't seem to work"
+
+Verify the installation:
+
+```bash
+# Check installed tools
+uv tool list
+
+# Should show specify-cli
+
+# Verify path
+which specify
+
+# Should point to the uv tool installation directory
+```
+
+If not found, reinstall:
+
+```bash
+uv tool uninstall specify-cli
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
+```
+
+### "Do I need to run specify every time I open my project?"
+
+**Short answer:** No, you only run `specify init` once per project (or when upgrading).
+
+**Explanation:**
+
+The `specify` CLI tool is used for:
+
+- **Initial setup:** `specify init` to bootstrap Spec Kit in your project
+- **Upgrades:** `specify init --here --force` to update templates and commands
+- **Diagnostics:** `specify check` to verify tool installation
+
+Once you've run `specify init`, the slash commands (like `/speckit.specify`, `/speckit.plan`, etc.) are **permanently installed** in your project's agent folder (`.claude/`, `.github/prompts/`, etc.). Your AI assistant reads these command files directly—no need to run `specify` again.
+
+**If your agent isn't recognizing slash commands:**
+
+1. **Verify command files exist:**
+
+   ```bash
+   # For GitHub Copilot
+   ls -la .github/prompts/
+
+   # For Claude
+   ls -la .claude/commands/
+   ```
+
+2. **Restart your IDE/editor completely** (not just reload window)
+
+3. **Check you're in the correct directory** where you ran `specify init`
+
+4. **For some agents**, you may need to reload the workspace or clear cache
+
+**Related issue:** If Copilot can't open local files or uses PowerShell commands unexpectedly, this is typically an IDE context issue, not related to `specify`. Try:
+
+- Restarting VS Code
+- Checking file permissions
+- Ensuring the workspace folder is properly opened
+
+---
+
+## Version Compatibility
+
+Spec Kit follows semantic versioning for major releases. The CLI and project files are designed to be compatible within the same major version.
+
+**Best practice:** Keep both CLI and project files in sync by upgrading both together during major version changes.
+
+---
+
+## Next Steps
+
+After upgrading:
+
+- **Test new slash commands:** Run `/speckit.constitution` or another command to verify everything works
+- **Review release notes:** Check [GitHub Releases](https://github.com/github/spec-kit/releases) for new features and breaking changes
+- **Update workflows:** If new commands were added, update your team's development workflows
+- **Check documentation:** Visit [github.io/spec-kit](https://github.github.io/spec-kit/) for updated guides

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*

extensions/EXTENSION-DEVELOPMENT-GUIDE.md

@@ -0,0 +1,651 @@
+# 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: Community Reference Catalog
+
+Submit to the community catalog for public discovery:
+
+1. **Fork** spec-kit repository
+2. **Add entry** to `extensions/catalog.community.json`
+3. **Update** `extensions/README.md` with your extension
+4. **Create PR** following the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md)
+5. **After merge**, your extension becomes available:
+   - Users can browse `catalog.community.json` to discover your extension
+   - Users copy the entry to their own `catalog.json`
+   - Users install with: `specify extension add my-ext` (from their catalog)
+
+See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed submission instructions.
+
+---
+
+## 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! 🚀

extensions/EXTENSION-PUBLISHING-GUIDE.md

@@ -0,0 +1,548 @@
+# 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
+
+### Understanding the Catalogs
+
+Spec Kit uses a dual-catalog system. For details about how catalogs work, see the main [Extensions README](README.md#extension-catalogs).
+
+**For extension publishing**: All community extensions should be added to `catalog.community.json`. Users browse this catalog and copy extensions they trust into their own `catalog.json`.
+
+### 1. Fork the spec-kit Repository
+
+```bash
+# Fork on GitHub
+# https://github.com/github/spec-kit/fork
+
+# Clone your fork
+git clone https://github.com/YOUR-USERNAME/spec-kit.git
+cd spec-kit
+```
+
+### 2. Add Extension to Community Catalog
+
+Edit `extensions/catalog.community.json` and add your extension:
+
+```json
+{
+  "schema_version": "1.0",
+  "updated_at": "2026-01-28T15:54:00Z",
+  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.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. Update Extensions README
+
+Add your extension to the Available Extensions table in `extensions/README.md`:
+
+```markdown
+| Your Extension Name | Brief description of what it does | [repo-name](https://github.com/your-org/spec-kit-your-extension) |
+```
+
+Insert your extension in alphabetical order in the table.
+
+### 4. Submit Pull Request
+
+```bash
+# Create a branch
+git checkout -b add-your-extension
+
+# Commit your changes
+git add extensions/catalog.community.json extensions/README.md
+git commit -m "Add your-extension to community 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/github/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
+- [x] Added to extensions/catalog.community.json
+- [x] Added to extensions/README.md Available Extensions table
+
+### 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*

extensions/EXTENSION-USER-GUIDE.md

@@ -0,0 +1,891 @@
+# 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
+
+**Note**: By default, `specify extension search` uses your organization's catalog (`catalog.json`). If the catalog is empty, you won't see any results. See [Extension Catalogs](#extension-catalogs) to learn how to populate your catalog from the community reference catalog.
+
+### Browse All Extensions
+
+```bash
+specify extension search
+```
+
+Shows all extensions in your organization's 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"
+```
+
+---
+
+## Extension Catalogs
+
+For information about how Spec Kit's dual-catalog system works (`catalog.json` vs `catalog.community.json`), see the main [Extensions README](README.md#extension-catalogs).
+
+## Organization Catalog Customization
+
+### Why Customize Your Catalog
+
+Organizations customize their `catalog.json` to:
+
+- **Control available extensions** - Curate which extensions your team can install
+- **Host private extensions** - Internal tools that shouldn't be public
+- **Customize for compliance** - Meet security/audit requirements
+- **Support air-gapped environments** - Work without internet access
+
+### Setting Up a Custom Catalog
+
+#### 1. Create Your Catalog File
+
+Create a `catalog.json` file with your extensions:
+
+```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*

extensions/README.md

@@ -0,0 +1,119 @@
+# Spec Kit Extensions
+
+Extension system for [Spec Kit](https://github.com/github/spec-kit) - add new functionality without bloating the core framework.
+
+## Extension Catalogs
+
+Spec Kit provides two catalog files with different purposes:
+
+### Your Catalog (`catalog.json`)
+
+- **Purpose**: Default upstream catalog of extensions used by the Spec Kit CLI
+- **Default State**: Empty by design in the upstream project - you or your organization populate a fork/copy with extensions you trust
+- **Location (upstream)**: `extensions/catalog.json` in the GitHub-hosted spec-kit repo
+- **CLI Default**: The `specify extension` commands use the upstream catalog URL by default, unless overridden
+- **Org Catalog**: Point `SPECKIT_CATALOG_URL` at your organization's fork or hosted catalog JSON to use it instead of the upstream default
+- **Customization**: Copy entries from the community catalog into your org catalog, or add your own extensions directly
+
+**Example override:**
+```bash
+# Override the default upstream catalog with your organization's catalog
+export SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json"
+specify extension search  # Now uses your organization's catalog instead of the upstream default
+```
+
+### Community Reference Catalog (`catalog.community.json`)
+
+- **Purpose**: Browse available community-contributed extensions
+- **Status**: Active - contains extensions submitted by the community
+- **Location**: `extensions/catalog.community.json`
+- **Usage**: Reference catalog for discovering available extensions
+- **Submission**: Open to community contributions via Pull Request
+
+**How It Works:**
+
+## Making Extensions Available
+
+You control which extensions your team can discover and install:
+
+### Option 1: Curated Catalog (Recommended for Organizations)
+
+Populate your `catalog.json` with approved extensions:
+
+1. **Discover** extensions from various sources:
+   - Browse `catalog.community.json` for community extensions
+   - Find private/internal extensions in your organization's repos
+   - Discover extensions from trusted third parties
+2. **Review** extensions and choose which ones you want to make available
+3. **Add** those extension entries to your own `catalog.json`
+4. **Team members** can now discover and install them:
+   - `specify extension search` shows your curated catalog
+   - `specify extension add <name>` installs from your catalog
+
+**Benefits**: Full control over available extensions, team consistency, organizational approval workflow
+
+**Example**: Copy an entry from `catalog.community.json` to your `catalog.json`, then your team can discover and install it by name.
+
+### Option 2: Direct URLs (For Ad-hoc Use)
+
+Skip catalog curation - team members install directly using URLs:
+
+```bash
+specify extension add --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip
+```
+
+**Benefits**: Quick for one-off testing or private extensions
+
+**Tradeoff**: Extensions installed this way won't appear in `specify extension search` for other team members unless you also add them to your `catalog.json`.
+
+## Available Community Extensions
+
+The following community-contributed extensions are available in [`catalog.community.json`](catalog.community.json):
+
+| Extension | Purpose | URL |
+|-----------|---------|-----|
+| V-Model Extension Pack | Enforces V-Model paired generation of development specs and test specs with full traceability | [spec-kit-v-model](https://github.com/leocamello/spec-kit-v-model) |
+| Cleanup Extension | Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues, and generates analysis for large issues | [spec-kit-cleanup](https://github.com/dsrednicki/spec-kit-cleanup) |
+
+## Adding Your Extension
+
+### Submission Process
+
+To add your extension to the community catalog:
+
+1. **Prepare your extension** following the [Extension Development Guide](EXTENSION-DEVELOPMENT-GUIDE.md)
+2. **Create a GitHub release** for your extension
+3. **Submit a Pull Request** that:
+   - Adds your extension to `extensions/catalog.community.json`
+   - Updates this README with your extension in the Available Extensions table
+4. **Wait for review** - maintainers will review and merge if criteria are met
+
+See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed step-by-step instructions.
+
+### Submission Checklist
+
+Before submitting, ensure:
+
+- ✅ Valid `extension.yml` manifest
+- ✅ Complete README with installation and usage instructions
+- ✅ LICENSE file included
+- ✅ GitHub release created with semantic version (e.g., v1.0.0)
+- ✅ Extension tested on a real project
+- ✅ All commands working as documented
+
+## Installing Extensions
+Once extensions are available (either in your catalog or via direct URL), install them:
+
+```bash
+# From your curated catalog (by name)
+specify extension search                  # See what's in your catalog
+specify extension add <extension-name>    # Install by name
+
+# Direct from URL (bypasses catalog)
+specify extension add --from https://github.com/<org>/<repo>/archive/refs/tags/<version>.zip
+
+# List installed extensions
+specify extension list
+```
+
+For more information, see the [Extension User Guide](EXTENSION-USER-GUIDE.md).

extensions/catalog.community.json

@@ -0,0 +1,85 @@
+{
+  "schema_version": "1.0",
+  "updated_at": "2026-02-24T00:00:00Z",
+  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
+  "extensions": {
+    "cleanup": {
+      "name": "Cleanup Extension",
+      "id": "cleanup",
+      "description": "Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues, and generates analysis for large issues.",
+      "author": "dsrednicki",
+      "version": "1.0.0",
+      "download_url": "https://github.com/dsrednicki/spec-kit-cleanup/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/dsrednicki/spec-kit-cleanup",
+      "homepage": "https://github.com/dsrednicki/spec-kit-cleanup",
+      "documentation": "https://github.com/dsrednicki/spec-kit-cleanup/blob/main/README.md",
+      "changelog": "https://github.com/dsrednicki/spec-kit-cleanup/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 1
+      },
+      "tags": ["quality", "tech-debt", "review", "cleanup", "scout-rule"],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-02-22T00:00:00Z",
+      "updated_at": "2026-02-22T00:00:00Z"
+    },
+    "retrospective": {
+      "name": "Retrospective Extension",
+      "id": "retrospective",
+      "description": "Post-implementation retrospective with spec adherence scoring, drift analysis, and human-gated spec updates.",
+      "author": "emi-dm",
+      "version": "1.0.0",
+      "download_url": "https://github.com/emi-dm/spec-kit-retrospective/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/emi-dm/spec-kit-retrospective",
+      "homepage": "https://github.com/emi-dm/spec-kit-retrospective",
+      "documentation": "https://github.com/emi-dm/spec-kit-retrospective/blob/main/README.md",
+      "changelog": "https://github.com/emi-dm/spec-kit-retrospective/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 1
+      },
+      "tags": ["retrospective", "spec-drift", "quality", "analysis", "governance"],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-02-24T00:00:00Z",
+      "updated_at": "2026-02-24T00:00:00Z"
+    }