Add support for extensions or variations

[dasiths]

Problem

Users are creating variations of Spec Kit prompts for team-specific and org-specific workflows. Managing all variations in a single repo is becoming difficult. We need a way for users to install custom prompt collections from external repositories.

Example Extensions:

• BDD (Behavior-Driven Development) workflows
• Bug diagnosis and root cause analysis
• Deep planning and architecture reviews
• Security-focused specification patterns
• Performance optimization workflows

---

Proposed Solution

Installation Command

specify install-extension https://github.com/org/speckit-extension-bdd

Installation Flow

1. Download extension from GitHub (latest release or main branch)
2. Detect which AI agent is configured (by checking for .github/prompts/, .claude/commands/, etc.)
3. Copy extension files to appropriate locations:
   • Commands → Agent-specific directory (e.g., .github/prompts/)
   • Memory files → .specify/memory/
   • Templates → .specify/templates/
4. Track installation in .specify/extensions.json

---

Agent Detection

Current State: The CLI does NOT save which agent was selected during specify init. No config file is created.

Detection Strategy: Check which agent-specific directories exist in the project:

Agent	Directory
GitHub Copilot	.github/prompts/
Claude Code	.claude/commands/
Gemini CLI	.gemini/commands/
Cursor	.cursor/commands/
Windsurf	.windsurf/workflows/

Installation Behavior:

# Auto-detect agent from project structure
specify install-extension https://github.com/org/ext

# Override with explicit agent
specify install-extension https://github.com/org/ext --agent claude

Edge Cases:

• Multiple agent directories found → Prompt user to choose or install to all
• No agent directory found → Require --agent flag

---

Extension Repository Structure

Option 1: Hybrid Structure (Recommended)

Source templates + optional pre-built agent variants:

speckit-extension-bdd/
├── extension.yaml                 # Extension manifest
├── README.md                      
├── memory/                        # Shared context files
│   └── bdd-guidelines.md  
├── templates/                     # Source templates (generic format)
│   ├── commands/                 
│   │   ├── given-when-then.md   # Generic markdown with {SCRIPT}, $ARGUMENTS
│   │   ├── scenario.md
│   │   └── feature-spec.md
│   └── acceptance-criteria.md       
└── agents/                        # Pre-built variants (optional, for speed)
    ├── claude/commands/
    │   ├── speckit.given-when-then.bdd.md
    │   └── speckit.scenario.bdd.md
    ├── gemini/commands/
    │   ├── speckit.given-when-then.bdd.toml
    │   └── speckit.scenario.bdd.toml
    └── copilot/prompts/
        ├── speckit.given-when-then.bdd.prompt.md
        └── speckit.scenario.bdd.prompt.md

Note: Files in agents/ include the extension name (e.g., .bdd.) for easy identification after installation.

Why this works:

• Write once in templates/commands/ (generic format)
• Optionally provide pre-built variants in agents/ for popular agents
• CLI tries pre-built first, falls back to converting from source templates
• Extension name in filename prevents conflicts and enables easy removal

Option 2: Flat Structure

Simpler, no pre-built variants:

speckit-extension-bdd/
├── extension.yaml
├── README.md
├── commands/
│   ├── given-when-then.md    # Generic markdown
│   └── scenario.md
├── memory/
│   └── bdd-guidelines.md
└── templates/
    └── acceptance-criteria.md

Trade-off: Simpler to create, but CLI must always convert on-the-fly.

---

Extension Manifest

File: extension.yaml

name: bdd-workflows
version: 1.0.0
description: Behavior-Driven Development workflows for Spec-Driven Development
author: your-org

# Compatibility
spec_kit_version: ">=0.9.0"
supported_agents:
  - claude
  - copilot
  - gemini
  # or "all" for all agents

# What this extension provides
provides:
  commands:
    - given-when-then
    - scenario
    - feature-spec
  memory:
    - bdd-guidelines.md
  templates:
    - acceptance-criteria.md

---

Installation Details

File Installation Strategy

Priority order:

1. Use pre-built agent variant if exists (agents/copilot/prompts/)
2. Convert from source templates (templates/commands/)
3. Copy directly from commands/ and auto-convert

File targets:

• Commands → Agent directory (e.g., .github/prompts/, .claude/commands/)
• Memory → .specify/memory/
• Templates → .specify/templates/

File Naming Convention

To track which files belong to which extension, use a naming convention:

Commands:

speckit.<command>.<extension-name>.<agent-format>

Examples:
  .github/prompts/speckit.given-when-then.bdd.prompt.md
  .claude/commands/speckit.scenario.bdd.md
  .gemini/commands/speckit.feature-spec.bdd.toml

Memory & Templates:

<filename>.<extension-name>.md

Examples:
  .specify/memory/bdd-guidelines.bdd.md
  .specify/templates/acceptance-criteria.bdd.md

Benefits:

• Easy to identify which extension a file belongs to
• Safe removal - just delete files with .<extension-name>. pattern
• Prevents naming conflicts between extensions
• Clear ownership in multi-extension projects

Installation Tracking

Create .specify/extensions.json:

{
  "installed": [
    {
      "name": "bdd-workflows",
      "version": "1.0.0",
      "source": "https://github.com/org/speckit-extension-bdd",
      "installed_at": "2025-10-16T10:30:00Z",
      "agent": "copilot",
      "files": {
        "commands": [
          ".github/prompts/speckit.given-when-then.bdd.prompt.md",
          ".github/prompts/speckit.scenario.bdd.prompt.md"
        ],
        "memory": [
          ".specify/memory/bdd-guidelines.bdd.md"
        ],
        "templates": [
          ".specify/templates/acceptance-criteria.bdd.md"
        ]
      }
    }
  ]
}

This allows:

• Easy listing of installed extensions
• Safe removal by file path
• Version tracking for updates
• Conflict detection before installation

---

Example: Installing an Extension

$ specify install-extension https://github.com/org/speckit-extension-bdd

⚠️  Installing Extension
────────────────────────
Extension: bdd-workflows v1.0.0
Source: https://github.com/org/speckit-extension-bdd

Detected agent: copilot (.github/prompts/ found)

Will install:
  • speckit.given-when-then.bdd.prompt.md
  • speckit.scenario.bdd.prompt.md
  • speckit.feature-spec.bdd.prompt.md
  • bdd-guidelines.bdd.md (memory)
  • acceptance-criteria.bdd.md (template)

Continue? [y/N] y

✓ Downloaded extension
✓ Installed 3 commands to .github/prompts/
✓ Installed 1 memory file to .specify/memory/
✓ Installed 1 template to .specify/templates/
✓ Updated .specify/extensions.json

Extension installed successfully!
Available commands: /speckit.given-when-then, /speckit.scenario, /speckit.feature-spec

---

Key Decisions for Discussion

1. Repository Structure: Option 1 (hybrid with optional pre-built) vs Option 2 (flat)?

2. Multi-agent projects: If both .github/prompts/ and .claude/commands/ exist, should we:

   • Install to both by default?
   • Prompt user to choose?
   • Require --agent flag?

3. Conflict handling: If extension file already exists, should we:

   • Prompt user (overwrite/skip/rename)?
   • Fail installation?
   • Auto-rename?

4. Version support: Support specific versions/branches initially or just latest?

   specify install-extension https://github.com/org/ext@v1.2.0
   specify install-extension https://github.com/org/ext@main

---

Next Steps

1. Gather feedback on this proposal
2. Decide on key questions above
3. Build MVP - install-extension command
4. Create starter extension repository as template for community

[dasiths]

@localden thoughts on this?

[dasiths]

I'm doing a little POC to support this more generally. https://github.com/dasiths/PromptyDumpty

[stefanwalther]

I am really wondering why this request/suggestion is not more popular. For me, to be honest, this is key to the long-term success of spec-kit. Also, having an extension system could allow testing/verification of meaningful additions, and if they are proven, it could result in extending the core of spec-kit.

One important element of an extension mechanism would also be the ability to hook into existing specs, so a kind of hook mechanism.

See also #278

[jsgoecke]

Agreed, I am finding I need this. For example, the way it branches is deep in the templates, and it ignores what is in the constitution. Really need a way to better control something like that.

[mnriem]

Delivered by our extension, preset and workflow support. See https://github.github.com/spec-kit/reference/overview.html

[dasiths]

Delivered by our extension, preset and workflow support. See https://github.github.com/spec-kit/reference/overview.html

Thank you. Glad to see it finally make it to spec-kit.