chore: bump version to 0.8.9

Rewrite docs/index.md from a philosophy essay into a landing page
organized around four pillars: Spec-driven by default, Use any coding
agent, Make it your own, and Integrate into your organization.

- Add hero section with GitHub Spec Kit branding and CTA buttons
- Add 2x2 pillar card grid with GitHub Primer color accents
- Add community stats section (96K stars, 200+ contributors, etc.)
- Add navigation cards and footer install CTA
- Move SDD philosophy content to docs/concepts/sdd.md
- Add custom DocFX template overlay with card CSS and dark mode
- Set landing layout for index.md via fileMetadata
- Update toc.yml and docfx.json for new concepts section

.github/CODEOWNERS

@@ -1,3 +1,8 @@
 # Global code owner
 * @mnriem
 
+# Community catalog files — explicit ownership for when global ownership expands
+/extensions/catalog.community.json @mnriem
+/integrations/catalog.community.json @mnriem
+/presets/catalog.community.json @mnriem
+

.github/ISSUE_TEMPLATE/preset_submission.yml

@@ -95,11 +95,18 @@ body:
     validations:
       required: true
 
+  - type: input
+    id: required-extensions
+    attributes:
+      label: Required Extensions (optional)
+      description: Comma-separated list of required extension IDs (e.g., aide)
+      placeholder: "e.g., aide, canon"
+
   - type: textarea
     id: templates-provided
     attributes:
       label: Templates Provided
-      description: List the template overrides your preset provides
+      description: List the template overrides your preset provides (enter "None" if command-only)
       placeholder: |
         - spec-template.md — adds compliance section
         - plan-template.md — includes audit checkpoints
@@ -110,10 +117,19 @@ body:
   - type: textarea
     id: commands-provided
     attributes:
-      label: Commands Provided (optional)
-      description: List any command overrides your preset provides
+      label: Commands Provided
+      description: List the command overrides your preset provides (enter "None" if template-only)
       placeholder: |
         - speckit.specify.md — customized for compliance workflows
+    validations:
+      required: true
+
+  - type: input
+    id: scripts-count
+    attributes:
+      label: Number of Scripts (optional)
+      description: How many scripts does your preset provide? (leave empty if none)
+      placeholder: "e.g., 1"
 
   - type: textarea
     id: tags

.github/workflows/catalog-assign.yml

@@ -0,0 +1,59 @@
+name: "Catalog: Auto-assign submission"
+
+on:
+  issues:
+    types: [opened, labeled]
+
+jobs:
+  assign:
+    if: >
+      (github.event.action == 'opened' && (
+        contains(github.event.issue.labels.*.name, 'extension-submission') ||
+        contains(github.event.issue.labels.*.name, 'preset-submission')
+      )) ||
+      (github.event.action == 'labeled' && (
+        github.event.label.name == 'extension-submission' ||
+        github.event.label.name == 'preset-submission'
+      ))
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - uses: actions/github-script@v9
+        with:
+          script: |
+            const issue = context.payload.issue;
+            const assigned = (issue.assignees || []).map(a => a.login);
+            const marker = '<!-- catalog-assign-bot -->';
+
+            // Assign mnriem if not already assigned
+            if (!assigned.includes('mnriem')) {
+              try {
+                await github.rest.issues.addAssignees({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.issue.number,
+                  assignees: ['mnriem'],
+                });
+              } catch (e) {
+                console.log(`Warning: could not assign mnriem: ${e.message}`);
+              }
+            }
+
+            // Post team notification if not already posted
+            const comments = await github.paginate(
+              github.rest.issues.listComments,
+              {
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+              }
+            );
+            if (!comments.some(c => c.body && c.body.includes(marker))) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: marker + '\ncc @github/spec-kit-maintainers — new catalog submission for review.',
+              });
+            }

.github/workflows/codeql.yml

@@ -19,14 +19,14 @@ jobs:
         language: [ 'actions', 'python' ]
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4
+        uses: github/codeql-action/init@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4
         with:
           languages: ${{ matrix.language }}
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v4
+        uses: github/codeql-action/analyze@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4
         with:
           category: "/language:${{ matrix.language }}"

.github/workflows/docs.yml

@@ -30,12 +30,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0 # Fetch all history for git info
 
       - name: Setup .NET
-        uses: actions/setup-dotnet@v4
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
         with:
           dotnet-version: '8.x'
 
@@ -48,10 +48,10 @@ jobs:
           docfx docfx.json
 
       - name: Setup Pages
-        uses: actions/configure-pages@v6
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v5
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
         with:
           path: 'docs/_site'
 
@@ -66,5 +66,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v5
-
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5

.github/workflows/lint.yml

@@ -12,10 +12,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
       - name: Run markdownlint-cli2
-        uses: DavidAnson/markdownlint-cli2-action@ce4853d43830c74c1753b39f3cf40f71c2031eb9 # v23
+        uses: DavidAnson/markdownlint-cli2-action@ded1f9488f68a970bc66ea5619e13e9b52e601cd # v23
         with:
           globs: |
             '**/*.md'

.github/workflows/release-trigger.yml

@@ -16,7 +16,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
           token: ${{ secrets.RELEASE_PAT }}

.github/workflows/release.yml

@@ -12,7 +12,7 @@ jobs:
       contents: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
@@ -86,4 +86,3 @@ jobs:
             --notes-file release_notes.md
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-

.github/workflows/stale.yml

@@ -14,7 +14,7 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v10
+      - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10
         with:
           # Days of inactivity before an issue or PR becomes stale
           days-before-stale: 150

.github/workflows/test.yml

@@ -13,13 +13,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install uv
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
           python-version: "3.13"
 
@@ -34,13 +34,13 @@ jobs:
         python-version: ["3.11", "3.12", "3.13"]
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install uv
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
           python-version: ${{ matrix.python-version }}
 

AGENTS.md

@@ -20,23 +20,17 @@ src/specify_cli/integrations/
 ├── base.py                # IntegrationBase, MarkdownIntegration, TomlIntegration, YamlIntegration, SkillsIntegration
 ├── manifest.py            # IntegrationManifest (file tracking)
 ├── claude/                # Example: SkillsIntegration subclass
-│   ├── __init__.py        #   ClaudeIntegration class
-│   └── scripts/           #   Thin wrapper scripts
-│       ├── update-context.sh
-│       └── update-context.ps1
+│   └── __init__.py        #   ClaudeIntegration class
 ├── gemini/                # Example: TomlIntegration subclass
-│   ├── __init__.py
-│   └── scripts/
+│   └── __init__.py
 ├── windsurf/              # Example: MarkdownIntegration subclass
-│   ├── __init__.py
-│   └── scripts/
+│   └── __init__.py
 ├── copilot/               # Example: IntegrationBase subclass (custom setup)
-│   ├── __init__.py
-│   └── scripts/
+│   └── __init__.py
 └── ...                    # One subpackage per supported agent
 ```
 
-The registry is the **single source of truth for Python integration metadata**. Supported agents, their directories, formats, and capabilities are derived from the integration classes for the Python integration layer. However, context-update behavior still requires explicit cases in the shared dispatcher scripts (`scripts/bash/update-agent-context.sh` and `scripts/powershell/update-agent-context.ps1`), which currently maintain their own supported-agent lists and agent-key→context-file mappings until they are migrated to registry-based dispatch.
+The registry is the **single source of truth for Python integration metadata**. Supported agents, their directories, formats, capabilities, and context files are derived from the integration classes for the Python integration layer.
 
 ---
 
@@ -179,63 +173,11 @@ def _register_builtins() -> None:
     # ...
 ```
 
-### 4. Add scripts
+### 4. Context file behavior
 
-Create two thin wrapper scripts in `src/specify_cli/integrations/<package_dir>/scripts/` that delegate to the shared context-update scripts. Each is ~25 lines of boilerplate.
+Set `context_file` on the integration class. The base integration setup creates or updates the managed Spec Kit section in that file, and uninstall removes the managed section when appropriate.
 
-> **Note on `<package_dir>` vs `<key>`:** `<package_dir>` is the Python-safe directory name for your integration — it matches `<key>` exactly when the key contains no hyphens (e.g., key `"gemini"` → `gemini/`), but uses underscores when it does (e.g., key `"kiro-cli"` → `kiro_cli/`). The `IntegrationBase.key` class attribute always retains the original hyphenated value (e.g., `key = "kiro-cli"`), since that is what the CLI and registry use.
-
-**`update-context.sh`:**
-
-```bash
-#!/usr/bin/env bash
-# update-context.sh — <Agent Name> integration: create/update <context_file>
-set -euo pipefail
-
-_script_dir="$(cd "$(dirname "$0")" && pwd)"
-_root="$_script_dir"
-while [ "$_root" != "/" ] && [ ! -d "$_root/.specify" ]; do _root="$(dirname "$_root")"; done
-if [ -z "${REPO_ROOT:-}" ]; then
-  if [ -d "$_root/.specify" ]; then
-    REPO_ROOT="$_root"
-  else
-    git_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
-    if [ -n "$git_root" ] && [ -d "$git_root/.specify" ]; then
-      REPO_ROOT="$git_root"
-    else
-      REPO_ROOT="$_root"
-    fi
-  fi
-fi
-
-exec "$REPO_ROOT/.specify/scripts/bash/update-agent-context.sh" <key>
-```
-
-**`update-context.ps1`:**
-
-```powershell
-# update-context.ps1 — <Agent Name> integration: create/update <context_file>
-$ErrorActionPreference = 'Stop'
-
-$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
-$repoRoot = try { git rev-parse --show-toplevel 2>$null } catch { $null }
-if (-not $repoRoot -or -not (Test-Path (Join-Path $repoRoot '.specify'))) {
-    $repoRoot = $scriptDir
-    $fsRoot = [System.IO.Path]::GetPathRoot($repoRoot)
-    while ($repoRoot -and $repoRoot -ne $fsRoot -and -not (Test-Path (Join-Path $repoRoot '.specify'))) {
-        $repoRoot = Split-Path -Parent $repoRoot
-    }
-}
-
-& "$repoRoot/.specify/scripts/powershell/update-agent-context.ps1" -AgentType <key>
-```
-
-Replace `<key>` with your integration key and `<Agent Name>` / `<context_file>` with the appropriate values.
-
-You must also add the agent to the shared context-update scripts so the shared dispatcher recognises the new key:
-
-- **`scripts/bash/update-agent-context.sh`** — add a file-path variable and a case in `update_specific_agent()`.
-- **`scripts/powershell/update-agent-context.ps1`** — add a file-path variable, add the new key to the `AgentType` parameter's `[ValidateSet(...)]`, add a switch case in `Update-SpecificAgent`, and add an entry in `Update-AllExistingAgents`.
+Only add custom setup logic when the agent needs non-standard behavior. Most integrations do not need wrapper scripts or separate context-update dispatch code.
 
 ### 5. Test it
 
@@ -422,7 +364,6 @@ Implementation: Extends `MarkdownIntegration` with custom `setup()` method that:
 3. Applies Forge-specific transformations via `_apply_forge_transformations()`
 4. Strips `handoffs` frontmatter key
 5. Injects missing `name` fields
-6. Ensures the shared `update-agent-context.*` scripts include a `forge` case that maps context updates to `AGENTS.md` and lists `forge` in their usage/help text
 
 ### Goose Integration
 
@@ -436,7 +377,7 @@ Implementation: Extends `YamlIntegration` (parallel to `TomlIntegration`):
 2. Extracts title and description from frontmatter
 3. Renders output as Goose recipe YAML (version, title, description, author, extensions, activities, prompt)
 4. Uses `yaml.safe_dump()` for header fields to ensure proper escaping
-5. Context updates map to `AGENTS.md` (shared with opencode/codex/pi/forge)
+5. Sets `context_file = "AGENTS.md"` so the base setup manages the Spec Kit context section there
 
 ## Common Pitfalls
 

CHANGELOG.md

@@ -2,6 +2,101 @@
 
 <!-- insert new changelog below this comment -->
 
+## [0.8.9] - 2026-05-12
+
+### Changed
+
+- docs: revamp landing page with four-pillar card layout (#2531)
+- feat(extensions): update governance ecosystem extensions to latest versions (#2514)
+- Add changelog extension (#2177)
+- Add install directory to docfx.json file references (#2522)
+- feat(catalog): add BrownKit (brownkit) community extension (#2510) (#2520)
+- fix(kiro-cli): replace literal $ARGUMENTS with prose fallback (#2482)
+- Preset: Add game-narrative-writing  preset to community catalog (#2454)
+- docs: clarify CLI upgrade discovery (#2519)
+- fix: make template metadata line breaks markdownlint-safe (#2505)
+- refactor(catalogs): extract integration catalog config loading (#2497)
+- test(presets): silence expected UserWarnings in self-test composition… (#2373)
+- chore: release 0.8.8, begin 0.8.9.dev0 development (#2516)
+
+## [0.8.8] - 2026-05-11
+
+### Changed
+
+- chore(deps): bump actions/checkout from 4.3.1 to 6.0.2 (#2486)
+- feat(catalog): add Spec Kit Schedule (schedule) community extension (#2473)
+- fix(integration): refresh shared infra on `integration switch` (#2375)
+- Add MDE preset to community catalog (#2513)
+- Add MDE extension to community catalog (#2512)
+- chore: update community catalog with latest extension versions (#2490)
+- chore(deps): bump actions/setup-dotnet from 4.3.1 to 5.2.0 (#2489)
+- chore(deps): bump actions/github-script from 7 to 9 (#2488)
+- chore(deps): bump DavidAnson/markdownlint-cli2-action (#2487)
+- chore(deps): bump github/codeql-action from 4.35.3 to 4.35.4 (#2485)
+- feat(catalog): add API Evolve (api-evolve) community extension (#2479)
+- feat: Config-driven opt-in authentication registry with multi-platform support (#2393)
+- chore: release 0.8.7, begin 0.8.8.dev0 development (#2480)
+
+## [0.8.7] - 2026-05-07
+
+### Changed
+
+- feat: add agent-orchestrator to community extension catalog (#2236)
+- chore: update extension versions in community catalog (#2468)
+- fix(goose): Declare args parameter in generated recipes (#2402)
+- feat: Add lingma support (#2348)
+- docs: Add uv installation guide and inline callouts (#2465)
+- Add fx-to-dotnet to community extension catalog (#2471)
+- fix: default non-interactive init to copilot integration (#2414)
+- fix(forge): use hyphen notation for command refs in Forge integration (#2462)
+- feat(catalog): add Cost Tracker (cost) community extension (#2448)
+- chore: release 0.8.6, begin 0.8.7.dev0 development (#2463)
+
+## [0.8.6] - 2026-05-06
+
+### Changed
+
+- Load constitution context in `/speckit.implement` to enforce governance during implementation (#2460)
+- feat: improve catalog submission templates and CODEOWNERS (#2401)
+- fix: validate URL scheme in build_github_request (#2449)
+- Add Architecture Guard to community catalog (#2430)
+- Add multi-model-review extension to community catalog (#2446)
+- Update Ralph Loop to v1.0.2 (#2435)
+- Pin GitHub Actions by SHA (#2441)
+- fix(workflows): require project for catalog list (#2436)
+- Add agent-parity-governance to community catalog (#2382)
+- chore: release 0.8.5, begin 0.8.6.dev0 development (#2447)
+
+## [0.8.5] - 2026-05-04
+
+### Changed
+
+- feat(presets): add Spec2Cloud preset for Azure deployment workflow (#2413)
+- update security-review and memory-md extensions to latest versions (#2445)
+- fix: honor template overrides for tasks-template (#2278) (#2292)
+- Add token-analyzer to community catalog (#2433)
+- docs: add April 2026 newsletter (#2434)
+- feat: emit init-time notice for git extension default change (#2165) (#2432)
+- Update DyanGalih(Memory Hub and Security Review) community extensions (#2429)
+- Support controlled multi-install for safe AI agent integrations (#2389)
+- chore(integrations): clean up docs and project guard (#2428)
+- chore: release 0.8.4, begin 0.8.5.dev0 development (#2431)
+
+## [0.8.4] - 2026-05-01
+
+### Changed
+
+- fix(specify): correct self-referencing step number in validation flow (#2152)
+- chore(deps): bump DavidAnson/markdownlint-cli2-action (#2425)
+- Add security-governance to community catalog (#2386)
+- Add cross-platform-governance to community catalog (#2384)
+- Add architecture-governance to community catalog (#2383)
+- Add a11y-governance to community catalog (#2381)
+- feat(extensions): add Spec2Cloud extension for Azure deployment workflow (#2412)
+- fix: migrate extension commands on integration switch (#2404)
+- feat: add Squad Bridge extension to community catalog (#2417)
+- chore: release 0.8.3, begin 0.8.4.dev0 development (#2418)
+
 ## [0.8.3] - 2026-04-29
 
 ### Changed

README.md

@@ -56,6 +56,9 @@ Choose your preferred installation method:
 
 Install once and use everywhere. Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):
 
+> [!NOTE]
+> The `uv tool install` commands below require **[uv](https://docs.astral.sh/uv/)** — a fast Python package manager. If you see `command not found: uv`, [install uv first](./docs/install/uv.md). The `pipx` alternative does not require uv.
+
 ```bash
 # Install a specific stable release (recommended — replace vX.Y.Z with the latest tag)
 uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
@@ -174,7 +177,7 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c
 ## 🧩 Community Extensions
 
 > [!NOTE]
-> Community extensions are independently created and maintained by their respective authors. GitHub and the Spec Kit maintainers may review pull requests that add entries to the community catalog for formatting, catalog structure, or policy compliance, but they do **not review, audit, endorse, or support the extension code itself**. The Community Extensions website is also a third-party resource. Review extension source code before installation and use at your own discretion.
+> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. The Community Extensions website is also a third-party resource. Review extension source code before installation and use at your own discretion.
 
 🔍 **Browse and search community extensions on the [Community Extensions website](https://speckit-community.github.io/extensions/).**
 
@@ -197,12 +200,15 @@ The following community-contributed extensions are available in [`catalog.commun
 |-----------|---------|----------|--------|-----|
 | Agent Assign | Assign specialized Claude Code agents to spec-kit tasks for targeted execution | `process` | Read+Write | [spec-kit-agent-assign](https://github.com/xymelon/spec-kit-agent-assign) |
 | AI-Driven Engineering (AIDE) | A structured 7-step workflow for building new projects from scratch with AI assistants — from vision through implementation | `process` | Read+Write | [aide](https://github.com/mnriem/spec-kit-extensions/tree/main/aide) |
+| API Evolve | Managed API contract evolution — breaking-change detection, semver enforcement, deprecation orchestration, and lifecycle gates across REST, GraphQL, and gRPC | `process` | Read+Write | [spec-kit-api-evolve](https://github.com/Quratulain-bilal/spec-kit-api-evolve) |
 | Architect Impact Previewer | Predicts architectural impact, complexity, and risks of proposed changes before implementation. | `visibility` | Read-only | [spec-kit-architect-preview](https://github.com/UmmeHabiba1312/spec-kit-architect-preview) |
+| Architecture Guard | Continuous architecture governance for AI-assisted development. Reviews specs, plans, and code for architecture drift, producing structured refactor tasks and evolution proposals. | `process` | Read+Write | [spec-kit-architecture-guard](https://github.com/DyanGalih/spec-kit-architecture-guard) |
 | Archive Extension | Archive merged features into main project memory. | `docs` | Read+Write | [spec-kit-archive](https://github.com/stn1slv/spec-kit-archive) |
 | Azure DevOps Integration | Sync user stories and tasks to Azure DevOps work items using OAuth authentication | `integration` | Read+Write | [spec-kit-azure-devops](https://github.com/pragya247/spec-kit-azure-devops) |
 | Blueprint | Stay code-literate in AI-driven development: review a complete code blueprint for every task from spec artifacts before /speckit.implement runs | `docs` | Read+Write | [spec-kit-blueprint](https://github.com/chordpli/spec-kit-blueprint) |
 | Branch Convention | Configurable branch and folder naming conventions for /specify with presets and custom patterns | `process` | Read+Write | [spec-kit-branch-convention](https://github.com/Quratulain-bilal/spec-kit-branch-convention) |
 | Brownfield Bootstrap | Bootstrap spec-kit for existing codebases — auto-discover architecture and adopt SDD incrementally | `process` | Read+Write | [spec-kit-brownfield](https://github.com/Quratulain-bilal/spec-kit-brownfield) |
+| BrownKit | Evidence-driven capability discovery, security and QA risk assessment for existing codebases | `process` | Read+Write | [BrownKit](https://github.com/MaksimShevtsov/BrownKit) |
 | Bugfix Workflow | Structured bugfix workflow — capture bugs, trace to spec artifacts, and patch specs surgically | `process` | Read+Write | [spec-kit-bugfix](https://github.com/Quratulain-bilal/spec-kit-bugfix) |
 | Canon | Adds canon-driven (baseline-driven) workflows: spec-first, code-first, spec-drift. Requires Canon Core preset installation. | `process` | Read+Write | [spec-kit-canon](https://github.com/maximiliamus/spec-kit-canon/tree/master/extension) |
 | Catalog CI | Automated validation for spec-kit community catalog entries — structure, URLs, diffs, and linting | `process` | Read-only | [spec-kit-catalog-ci](https://github.com/Quratulain-bilal/spec-kit-catalog-ci) |
@@ -211,6 +217,7 @@ The following community-contributed extensions are available in [`catalog.commun
 | 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 | `code` | Read+Write | [spec-kit-cleanup](https://github.com/dsrednicki/spec-kit-cleanup) |
 | Conduct Extension | Orchestrates spec-kit phases via sub-agent delegation to reduce context pollution. | `process` | Read+Write | [spec-kit-conduct-ext](https://github.com/twbrandon7/spec-kit-conduct-ext) |
 | Confluence Extension | Create a doc in Confluence summarizing the specifications and planning files | `integration` | Read+Write | [spec-kit-confluence](https://github.com/aaronrsun/spec-kit-confluence) |
+| Cost Tracker | Track real LLM dollar cost across SDD workflows — per-feature budgets, per-integration comparison, and finance-ready exports | `visibility` | Read+Write | [spec-kit-cost](https://github.com/Quratulain-bilal/spec-kit-cost) |
 | DocGuard — CDD Enforcement | Canonical-Driven Development enforcement. Validates, scores, and traces project documentation with automated checks, AI-driven workflows, and spec-kit hooks. Zero NPM runtime dependencies. | `docs` | Read+Write | [spec-kit-docguard](https://github.com/raccioly/docguard) |
 | Extensify | Create and validate extensions and extension catalogs | `process` | Read+Write | [extensify](https://github.com/mnriem/spec-kit-extensions/tree/main/extensify) |
 | Fix Findings | Automated analyze-fix-reanalyze loop that resolves spec findings until clean | `code` | Read+Write | [spec-kit-fix-findings](https://github.com/Quratulain-bilal/spec-kit-fix-findings) |
@@ -218,6 +225,7 @@ The following community-contributed extensions are available in [`catalog.commun
 | Fleet Orchestrator | Orchestrate a full feature lifecycle with human-in-the-loop gates across all SpecKit phases | `process` | Read+Write | [spec-kit-fleet](https://github.com/sharathsatish/spec-kit-fleet) |
 | GitHub Issues Integration 1 | Generate spec artifacts from GitHub Issues - import issues, sync updates, and maintain bidirectional traceability | `integration` | Read+Write | [spec-kit-github-issues](https://github.com/Fatima367/spec-kit-github-issues) |
 | GitHub Issues Integration 2 | Creates and syncs local specs from an existing GitHub issue | `integration` | Read+Write | [spec-kit-issue](https://github.com/aaronrsun/spec-kit-issue) |
+| Intelligent Agent Orchestrator | Cross-catalog agent discovery and intelligent prompt-to-command routing | `process` | Read+Write | [spec-kit-orchestrator](https://github.com/pragya247/spec-kit-orchestrator) |
 | Iterate | Iterate on spec documents with a two-phase define-and-apply workflow — refine specs mid-implementation and go straight back to building | `docs` | Read+Write | [spec-kit-iterate](https://github.com/imviancagrace/spec-kit-iterate) |
 | Jira Integration | Create Jira Epics, Stories, and Issues from spec-kit specifications and task breakdowns with configurable hierarchy and custom field support | `integration` | Read+Write | [spec-kit-jira](https://github.com/mbachorik/spec-kit-jira) |
 | Learning Extension | Generate educational guides from implementations and enhance clarifications with mentoring context | `docs` | Read+Write | [spec-kit-learn](https://github.com/imviancagrace/spec-kit-learn) |
@@ -229,10 +237,13 @@ The following community-contributed extensions are available in [`catalog.commun
 | MAQA Linear Integration | Linear integration for MAQA — syncs issues and sub-issues across workflow states as features progress | `integration` | Read+Write | [spec-kit-maqa-linear](https://github.com/GenieRobot/spec-kit-maqa-linear) |
 | MAQA Trello Integration | Trello board integration for MAQA — populates board from specs, moves cards, real-time checklist ticking | `integration` | Read+Write | [spec-kit-maqa-trello](https://github.com/GenieRobot/spec-kit-maqa-trello) |
 | MarkItDown Document Converter | Convert documents (PDF, Word, PowerPoint, Excel, and more) to Markdown for use as spec reference material | `docs` | Read+Write | [spec-kit-markitdown](https://github.com/BenBtg/spec-kit-markitdown) |
+| MDE | Minimal model-driven engineering workflow with setup, next, and status commands | `process` | Read+Write | [spec-kit-mde](https://github.com/AI-MDE/spec-kit-mde) |
 | Memory Loader | Loads .specify/memory/ files before lifecycle commands so LLM agents have project governance context | `docs` | Read-only | [spec-kit-memory-loader](https://github.com/KevinBrown5280/spec-kit-memory-loader) |
-| Memory MD | Repository-native durable memory for Spec Kit projects | `docs` | Read+Write | [spec-kit-memory-hub](https://github.com/DyanGalih/spec-kit-memory-hub) |
+| Memory MD | Spec Kit extension for repository-native Markdown memory that captures durable decisions, bugs, and project context | `docs` | Read+Write | [spec-kit-memory-hub](https://github.com/DyanGalih/spec-kit-memory-hub) |
 | MemoryLint | Agent memory governance tool: Automatically audits and fixes boundary conflicts between AGENTS.md and the constitution. | `process` | Read+Write | [memorylint](https://github.com/RbBtSn0w/spec-kit-extensions/tree/main/memorylint) |
 | Microsoft 365 Integration | Fetch Teams messages, meeting transcripts, and SharePoint/OneDrive files as local Markdown for spec generation | `integration` | Read+Write | [spec-kit-m365](https://github.com/BenBtg/spec-kit-m365) |
+| Multi-Model Review | Cross-model Spec Kit handoffs for spec authoring, implementation routing, and review. | `process` | Read+Write | [multi-model-review](https://github.com/formin/multi-model-review) |
+| .NET Framework to Modern .NET Migration | Orchestrate end-to-end .NET Framework to modern .NET migration across 7 phases, with SDD lifecycle integration | `process` | Read+Write | [spec-kit-fx-to-net](https://github.com/RogerBestMsft/spec-kit-FxToNet) |
 | Onboard | Contextual onboarding and progressive growth for developers new to spec-kit projects. Explains specs, maps dependencies, validates understanding, and guides the next step | `process` | Read+Write | [spec-kit-onboard](https://github.com/dmux/spec-kit-onboard) |
 | Optimize | Audit and optimize AI governance for context efficiency — token budgets, rule health, interpretability, compression, coherence, and echo detection | `process` | Read+Write | [spec-kit-optimize](https://github.com/sakitA/spec-kit-optimize) |
 | OWASP LLM Threat Model | OWASP Top 10 for LLM Applications 2025 threat analysis on agent artifacts | `code` | Read-only | [spec-kit-threatmodel](https://github.com/NaviaSamal/spec-kit-threatmodel) |
@@ -243,7 +254,7 @@ The following community-contributed extensions are available in [`catalog.commun
 | Project Health Check | Diagnose a Spec Kit project and report health issues across structure, agents, features, scripts, extensions, and git | `visibility` | Read-only | [spec-kit-doctor](https://github.com/KhawarHabibKhan/spec-kit-doctor) |
 | Project Status | Show current SDD workflow progress — active feature, artifact status, task completion, workflow phase, and extensions summary | `visibility` | Read-only | [spec-kit-status](https://github.com/KhawarHabibKhan/spec-kit-status) |
 | QA Testing Extension | Systematic QA testing with browser-driven or CLI-based validation of acceptance criteria from spec | `code` | Read-only | [spec-kit-qa](https://github.com/arunt14/spec-kit-qa) |
-| Ralph Loop | Autonomous implementation loop using AI agent CLI | `code` | Read+Write | [spec-kit-ralph](https://github.com/Rubiss/spec-kit-ralph) |
+| Ralph Loop | Autonomous implementation loop using AI agent CLI | `code` | Read+Write | [spec-kit-ralph](https://github.com/Rubiss-Projects/spec-kit-ralph) |
 | Reconcile Extension | Reconcile implementation drift by surgically updating feature artifacts. | `docs` | Read+Write | [spec-kit-reconcile](https://github.com/stn1slv/spec-kit-reconcile) |
 | Red Team | Adversarial review of specs before /speckit.plan — parallel lens agents surface risks that clarify/analyze structurally can't (prompt injection, integrity gaps, cross-spec drift, silent failures). Produces a structured findings report; no auto-edits to specs. | `docs` | Read+Write | [spec-kit-red-team](https://github.com/ashbrener/spec-kit-red-team) |
 | Repository Index | Generate index for existing repo for overview, architecture and module level. | `docs` | Read-only | [spec-kit-repoindex](https://github.com/liuyiyu/spec-kit-repoindex) |
@@ -255,20 +266,25 @@ The following community-contributed extensions are available in [`catalog.commun
 | Security Review | Full-project secure-by-design security audits plus staged, branch/PR, plan, task, follow-up, and apply reviews | `code` | Read+Write | [spec-kit-security-review](https://github.com/DyanGalih/spec-kit-security-review) |
 | SFSpeckit | Enterprise Salesforce SDLC with 18 commands for the full SDD lifecycle. | `process` | Read+Write | [spec-kit-sf](https://github.com/ysumanth06/spec-kit-sf) |
 | Ship Release Extension | Automates release pipeline: pre-flight checks, branch sync, changelog generation, CI verification, and PR creation | `process` | Read+Write | [spec-kit-ship](https://github.com/arunt14/spec-kit-ship) |
-| Spec Reference Loader | Reads the ## References section from the feature spec and loads only the listed docs into context | `docs` | Read-only | [spec-kit-spec-reference-loader](https://github.com/KevinBrown5280/spec-kit-spec-reference-loader) |
+| Spec Changelog | Auto-generate changelogs and release notes from spec git history and requirement diffs | `docs` | Read-only | [spec-kit-changelog](https://github.com/Quratulain-bilal/spec-kit-changelog) |
 | Spec Critique Extension | Dual-lens critical review of spec and plan from product strategy and engineering risk perspectives | `docs` | Read-only | [spec-kit-critique](https://github.com/arunt14/spec-kit-critique) |
 | Spec Diagram | Auto-generate Mermaid diagrams of SDD workflow state, feature progress, and task dependencies | `visibility` | Read-only | [spec-kit-diagram-](https://github.com/Quratulain-bilal/spec-kit-diagram-) |
+| Spec Kit Schedule | Optimal multi-agent task scheduling via CP-SAT — DAG precedence, hallucination-aware caps, file-conflict avoidance, stochastic durations, replanning, and interactive HTML output | `process` | Read+Write | [spec-kit-schedule](https://github.com/jfranc38/spec-kit-schedule) |
 | Spec Orchestrator | Cross-feature orchestration — track state, select tasks, and detect conflicts across parallel specs | `process` | Read-only | [spec-kit-orchestrator](https://github.com/Quratulain-bilal/spec-kit-orchestrator) |
+| Spec Reference Loader | Reads the ## References section from the feature spec and loads only the listed docs into context | `docs` | Read-only | [spec-kit-spec-reference-loader](https://github.com/KevinBrown5280/spec-kit-spec-reference-loader) |
 | Spec Refine | Update specs in-place, propagate changes to plan and tasks, and diff impact across artifacts | `process` | Read+Write | [spec-kit-refine](https://github.com/Quratulain-bilal/spec-kit-refine) |
 | Spec Scope | Effort estimation and scope tracking — estimate work, detect creep, and budget time per phase | `process` | Read-only | [spec-kit-scope-](https://github.com/Quratulain-bilal/spec-kit-scope-) |
 | Spec Sync | Detect and resolve drift between specs and implementation. AI-assisted resolution with human approval | `docs` | Read+Write | [spec-kit-sync](https://github.com/bgervin/spec-kit-sync) |
 | Spec Validate | Comprehension validation, review gating, and approval state for spec-kit artifacts — staged quizzes, peer review SLA, and a hard gate before /speckit.implement | `process` | Read+Write | [spec-kit-spec-validate](https://github.com/aeltayeb/spec-kit-spec-validate) |
+| Spec2Cloud | Spec-driven workflow tuned for shipping to Azure | `process` | Read+Write | [spec2cloud](https://github.com/Azure-Samples/Spec2Cloud) |
 | SpecTest | Auto-generate test scaffolds from spec criteria, map coverage, and find untested requirements | `code` | Read+Write | [spec-kit-spectest](https://github.com/Quratulain-bilal/spec-kit-spectest) |
+| Squad Bridge | Bootstrap and synchronize a Squad agent team from your Speckit spec and tasks | `process` | Read+Write | [spec-kit-squad](https://github.com/jwill824/spec-kit-squad) |
 | Staff Review Extension | Staff-engineer-level code review that validates implementation against spec, checks security, performance, and test coverage | `code` | Read-only | [spec-kit-staff-review](https://github.com/arunt14/spec-kit-staff-review) |
 | Status Report | Project status, feature progress, and next-action recommendations for spec-driven workflows | `visibility` | Read-only | [Open-Agent-Tools/spec-kit-status](https://github.com/Open-Agent-Tools/spec-kit-status) |
 | Superpowers Bridge | Orchestrates obra/superpowers skills within the spec-kit SDD workflow across the full lifecycle (clarification, TDD, review, verification, critique, debugging, branch completion) | `process` | Read+Write | [superpowers-bridge](https://github.com/RbBtSn0w/spec-kit-extensions/tree/main/superpowers-bridge) |
 | Superpowers Bridge (WangX0111) | Bridges spec-kit with obra/superpowers (brainstorming, TDD, subagent, code-review) into a unified, resumable workflow with graceful degradation and session progress tracking | `process` | Read+Write | [superspec](https://github.com/WangX0111/superspec) |
 | TinySpec | Lightweight single-file workflow for small tasks — skip the heavy multi-step SDD process | `process` | Read+Write | [spec-kit-tinyspec](https://github.com/Quratulain-bilal/spec-kit-tinyspec) |
+| Token Consumption Analyzer | Captures, analyzes, and compares token consumption across SDD workflows | `visibility` | Read-only | [spec-kit-token-analyzer](https://github.com/coderandhiker/spec-kit-token-analyzer) |
 | V-Model Extension Pack | Enforces V-Model paired generation of development specs and test specs with full traceability | `docs` | Read+Write | [spec-kit-v-model](https://github.com/leocamello/spec-kit-v-model) |
 | Verify Extension | Post-implementation quality gate that validates implemented code against specification artifacts | `code` | Read-only | [spec-kit-verify](https://github.com/ismaelJimenez/spec-kit-verify) |
 | Verify Tasks Extension | Detect phantom completions: tasks marked [X] in tasks.md with no real implementation | `code` | Read-only | [spec-kit-verify-tasks](https://github.com/datastone-inc/spec-kit-verify-tasks) |
@@ -479,7 +495,7 @@ specify init --here --force
 
 ![Specify CLI bootstrapping a new project in the terminal](./media/specify_cli.gif)
 
-You will be prompted to select the coding agent integration you are using. You can also proactively specify it directly in the terminal:
+In an interactive terminal, you will be prompted to select the coding agent integration you are using. In non-interactive sessions, such as CI or piped runs, `specify init` defaults to GitHub Copilot unless you pass `--integration`. You can also proactively specify the integration directly in the terminal:
 
 ```bash
 specify init <project_name> --integration copilot

docs/community/presets.md

@@ -1,22 +1,30 @@
 # Community Presets
 
 > [!NOTE]
-> Community presets are independently created and maintained by their respective authors. GitHub and the Spec Kit maintainers may review pull requests that add entries to the community catalog for formatting, catalog structure, or policy compliance, but they do **not review, audit, endorse, or support the preset code itself**. Review preset source code before installation and use at your own discretion.
+> Community presets are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the preset code itself**. Review preset source code before installation and use at your own discretion.
 
 The following community-contributed presets customize how Spec Kit behaves — overriding templates, commands, and terminology without changing any tooling. Presets are available in [`catalog.community.json`](https://github.com/github/spec-kit/blob/main/presets/catalog.community.json):
 
 | Preset | Purpose | Provides | Requires | URL |
 |--------|---------|----------|----------|-----|
+| A11Y Governance | Adds WCAG 2.2 AA accessibility checks, bilingual DE/EN delivery, CEFR-B2 readability, CLI accessibility, and inclusive-content guidance | 9 templates, 3 commands | — | [spec-kit-preset-a11y-governance](https://github.com/hindermath/spec-kit-preset-a11y-governance) |
+| Agent Parity Governance | Keeps shared AI-agent instructions aligned across project-defined agent guidance surfaces and documents intentional deviations | 6 templates, 3 commands | — | [spec-kit-preset-agent-parity-governance](https://github.com/hindermath/spec-kit-preset-agent-parity-governance) |
 | AIDE In-Place Migration | Adapts the AIDE extension workflow for in-place technology migrations (X → Y pattern) — adds migration objectives, verification gates, knowledge documents, and behavioral equivalence criteria | 2 templates, 8 commands | AIDE extension | [spec-kit-presets](https://github.com/mnriem/spec-kit-presets) |
+| Architecture Governance | Adds secure architecture governance: trust boundaries, threat modeling, STRIDE/CAPEC, S-ADRs, Zero Trust applicability, and OWASP SAMM | 11 templates, 3 commands | — | [spec-kit-preset-architecture-governance](https://github.com/hindermath/spec-kit-preset-architecture-governance) |
 | Canon Core | Adapts original Spec Kit workflow to work together with Canon extension | 2 templates, 8 commands | — | [spec-kit-canon](https://github.com/maximiliamus/spec-kit-canon) |
 | Claude AskUserQuestion | Upgrades `/speckit.clarify` and `/speckit.checklist` on Claude Code from Markdown-table prompts to the native AskUserQuestion picker, with a recommended option and reasoning on every question | 2 commands | — | [spec-kit-preset-claude-ask-questions](https://github.com/0xrafasec/spec-kit-preset-claude-ask-questions) |
+| Cross-Platform Governance | Adds Bash/PowerShell parity, dry-run/WhatIf parity, Unix man-page expectations, PowerShell comment-based help, and Verb-Noun Cmdlet discipline | 8 templates, 3 commands | — | [spec-kit-preset-cross-platform-governance](https://github.com/hindermath/spec-kit-preset-cross-platform-governance) |
 | Explicit Task Dependencies | Adds explicit `(depends on T###)` dependency declarations and an Execution Wave DAG to tasks.md for parallel scheduling | 1 template, 1 command | — | [spec-kit-preset-explicit-task-dependencies](https://github.com/Quratulain-bilal/spec-kit-preset-explicit-task-dependencies) |
 | Fiction Book Writing | It adapts the Spec-Driven Development workflow for storytelling to create books or audiobooks (with annotations) in 12 languages: features become story elements, specs become story briefs, plans become story structures, and tasks become scene-by-scene writing tasks. Supports single and multi-POV, all major plot structure frameworks, and two style modes: an author voice sample or humanized AI prose. Supports interactive elements like brainstorming, interview, roleplay and extras like statistics, cover builder and bio command. Export with templates for KDP, D2D etc. | 22 templates, 27 commands, 2 scripts | — | [speckit-preset-fiction-book-writing](https://github.com/adaumann/speckit-preset-fiction-book-writing) |
+| Game Narrative Writing | Spec-Driven Development for interactive game narrative pre-production for video games. Authors write in a portable generic format, Twine/Sugarcube (.twee) or Ink (.ink). Covers choice-IF, visual novels, and branching dialogue. Supports Tier 1 mechanic hooks (flag, counter, inventory, timer, trust, currency, npc_state, ending_condition), multi-ending design, series carry-over variable registry, and NPC-focused character architecture. | 22 templates, 36 commands, 2 scripts | — | [speckit-preset-game-narrative-writing](https://github.com/adaumann/speckit-preset-game-narrative-writing) |
 | iSAQB Architecture Governance | Adds general iSAQB/CPSA-F and arc42 architecture governance: goals, context, building blocks, runtime and deployment views, quality scenarios, ADRs, risks, and technical debt | 13 templates, 3 commands | — | [spec-kit-preset-isaqb-architecture-governance](https://github.com/hindermath/spec-kit-preset-isaqb-architecture-governance) |
 | Jira Issue Tracking | Overrides `speckit.taskstoissues` to create Jira epics, stories, and tasks instead of GitHub Issues via Atlassian MCP tools | 1 command | — | [spec-kit-preset-jira](https://github.com/luno/spec-kit-preset-jira) |
+| Model Driven Engineering | Focuses on streamlined commands, app repository support, cross-spec support, and capability-aware project memory for model-driven engineering workflows | 6 templates, 11 commands | MDE extension | [spec-kit-preset-mde](https://github.com/AI-MDE/spec-kit-preset-mde) |
 | Multi-Repo Branching | Coordinates feature branch creation across multiple git repositories (independent repos and submodules) during plan and tasks phases | 2 commands | — | [spec-kit-preset-multi-repo-branching](https://github.com/sakitA/spec-kit-preset-multi-repo-branching) |
 | Pirate Speak (Full) | Transforms all Spec Kit output into pirate speak — specs become "Voyage Manifests", plans become "Battle Plans", tasks become "Crew Assignments" | 6 templates, 9 commands | — | [spec-kit-presets](https://github.com/mnriem/spec-kit-presets) |
 | Screenwriting | Spec-Driven Development for screenwriting/scriptwriting/tutorials: feature films, television (pilot, episode, limited series), and stage plays. Adapts the Spec Kit workflow to screenplay craft — slug lines, action lines, act breaks, beat sheets, and industry-standard pitch documents. Supports three-act, Save the Cat, TV pilot, network episode, cable/streaming episode, and stage-play structural frameworks. Export to Fountain, FTX, PDF | 26 templates, 32 commands, 1 script | — | [speckit-preset-screenwriting](https://github.com/adaumann/speckit-preset-screenwriting) |
+| Security Governance | Adds secure development governance: memory-safe-language preference, secure code generation, NIST SSDF, CWE Top 25, OWASP ASVS, SBOM/VEX/SLSA, OpenSSF Scorecard, and EU CRA applicability | 12 templates, 3 commands | — | [spec-kit-preset-security-governance](https://github.com/hindermath/spec-kit-preset-security-governance) |
+| Spec2Cloud | Spec-driven workflow tuned for shipping to Azure: spec → plan → tasks → implement → deploy | 5 templates, 8 commands | — | [spec2cloud](https://github.com/Azure-Samples/Spec2Cloud) |
 | Table of Contents Navigation | Adds a navigable Table of Contents to generated spec.md, plan.md, and tasks.md documents | 3 templates, 3 commands | — | [spec-kit-preset-toc-navigation](https://github.com/Quratulain-bilal/spec-kit-preset-toc-navigation) |
 | VS Code Ask Questions | Enhances the clarify command to use `vscode/askQuestions` for batched interactive questioning. | 1 command | — | [spec-kit-presets](https://github.com/fdcastel/spec-kit-presets) |
 

docs/concepts/sdd.md

@@ -0,0 +1,46 @@
+# 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.
+
+## 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

docs/docfx.json

@@ -6,7 +6,9 @@
           "*.md",
           "toc.yml",
           "community/*.md",
-          "reference/*.md"
+          "concepts/*.md",
+          "reference/*.md",
+          "install/*.md"
         ]
       },
       {
@@ -49,7 +51,8 @@
     "fileMetadataFiles": [],
     "template": [
       "default",
-      "modern"
+      "modern",
+      "template"
     ],
     "postProcessors": [],
     "markdownEngineName": "markdig",
@@ -67,6 +70,11 @@
         "repo": "https://github.com/github/spec-kit",
         "branch": "main"
       }
+    },
+    "fileMetadata": {
+      "_layout": {
+        "index.md": "landing"
+      }
     }
   }
 }

docs/index.md

@@ -1,67 +1,152 @@
-# Spec Kit
+<div class="landing-hero">
 
-*Build high-quality software faster.*
+# GitHub Spec Kit
 
-**An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.**
+**Define what to build before building it — with any AI coding agent.**
 
-## What is Spec-Driven Development?
+Spec Kit is a toolkit for [Spec-Driven Development](concepts/sdd.md) (SDD), a methodology that puts specifications at the center of AI-assisted software development. Instead of jumping straight to code, you describe *what* to build, refine it through structured phases, and let your AI coding agent implement it.
 
-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.
+<a href="installation.md" class="btn btn-primary btn-lg">Install Spec Kit</a>&nbsp;
+<a href="quickstart.md" class="btn btn-outline-primary btn-lg">Quick Start</a>
 
-## Getting Started
+</div>
 
-- [Installation Guide](installation.md)
-- [Quick Start Guide](quickstart.md)
-- [Upgrade Guide](upgrade.md)
-- [Local Development](local-development.md)
+---
 
-## Core Philosophy
+<div class="pillar-grid">
 
-Spec-Driven Development is a structured process that emphasizes:
+<div class="pillar-card">
 
-- **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
+### Spec-driven by default
 
-## Development Phases
+The core SDD process ships ready to use: **Spec → Plan → Tasks → Implement**.
 
-| 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> |
+Define what to build before building it. Rich templates, quality checklists, and cross-artifact analysis come out of the box. Each phase produces a Markdown artifact that feeds the next — giving your AI coding agent structured context instead of ad-hoc prompts.
 
-## Experimental Goals
+<a href="quickstart.md" class="pillar-link">Walk through the workflow →</a>
 
-Our research and experimentation focus on:
+</div>
 
-### Technology Independence
+<div class="pillar-card">
 
-- 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
+### Use any coding agent
 
-### Enterprise Constraints
+<span class="pillar-stat">30 integrations</span> — Copilot, Gemini, Codex, Windsurf, Claude, Forge, Kiro, and more. Switch freely between agents with a single command. No lock-in.
 
-- Demonstrate mission-critical application development
-- Incorporate organizational constraints (cloud providers, tech stacks, engineering practices)
-- Support enterprise design systems and compliance requirements
+Run `specify init` with your agent of choice and Spec Kit sets up the right command files, context rules, and directory structures automatically. If your agent isn't listed, the `generic` integration is an escape hatch for any tool.
 
-### User-Centric Development
+<a href="reference/integrations.md" class="pillar-link">See all integrations →</a>
 
-- Build applications for different user cohorts and preferences
-- Support various development approaches (from vibe-coding to AI-native development)
+</div>
 
-### Creative & Iterative Processes
+<div class="pillar-card">
 
-- Validate the concept of parallel implementation exploration
-- Provide robust iterative feature development workflows
-- Extend processes to handle upgrades and modernization tasks
+### Make it your own
 
-## Contributing
+<span class="pillar-stat">91 community extensions</span> (50+ authors), <span class="pillar-stat">18 presets</span>, and growing — including entirely different SDD processes:
 
-Please see our [Contributing Guide](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md) for information on how to contribute to this project.
+- **AIDE** — 7-step AI-driven engineering lifecycle
+- **Canon** — baseline-driven workflows (spec-first, code-first, spec-drift)
+- **Product Forge** — product-management-oriented SDD
+- **FX→.NET** — end-to-end .NET Framework migration across 7 phases
+- **MAQA** — multi-agent orchestration with quality assurance gates
 
-## Support
+Tune the core process with presets, extend it with extensions, orchestrate it with workflows, or replace it entirely. Build and publish your own.
 
-For support, please check our [Support Guide](https://github.com/github/spec-kit/blob/main/SUPPORT.md) or open an issue on GitHub.
+<a href="community/presets.md" class="pillar-link">Browse community presets →</a>
+
+</div>
+
+<div class="pillar-card">
+
+### Integrate into your organization
+
+Works offline, behind firewalls, and on **Windows, macOS, and Linux**. Host your own extension and preset catalogs so your organization controls what gets installed.
+
+Community extensions like CI Guard and Architecture Guard add compliance gates and governance that fit the way your team already works.
+
+<a href="installation.md" class="pillar-link">Installation guide →</a>&nbsp;&nbsp;
+<a href="reference/extensions.md" class="pillar-link">Extensions reference →</a>
+
+</div>
+
+</div>
+
+---
+
+<div class="community-section">
+
+## Built by the community
+
+**200+ contributors** power the Spec Kit ecosystem — from core integrations to entirely new development processes. Anyone can create and publish an extension, preset, or workflow.
+
+<div class="stats-grid">
+  <div class="stat-item">
+    <span class="stat-number">96K+</span>
+    <span class="stat-label">GitHub stars</span>
+  </div>
+  <div class="stat-item">
+    <span class="stat-number">200+</span>
+    <span class="stat-label">Contributors</span>
+  </div>
+  <div class="stat-item">
+    <span class="stat-number">30</span>
+    <span class="stat-label">Integrations</span>
+  </div>
+  <div class="stat-item">
+    <span class="stat-number">91</span>
+    <span class="stat-label">Extensions</span>
+  </div>
+  <div class="stat-item">
+    <span class="stat-number">18</span>
+    <span class="stat-label">Presets</span>
+  </div>
+  <div class="stat-item">
+    <span class="stat-number">4</span>
+    <span class="stat-label">Friends projects</span>
+  </div>
+</div>
+
+<a href="community/presets.md">Presets</a> · <a href="community/walkthroughs.md">Walkthroughs</a> · <a href="community/friends.md">Friends</a>
+
+</div>
+
+---
+
+## Explore the docs
+
+<div class="nav-cards">
+  <a href="quickstart.md" class="nav-card">
+    <strong>Getting Started</strong>
+    <span>Install, configure, and run your first SDD workflow</span>
+  </a>
+  <a href="reference/overview.md" class="nav-card">
+    <strong>Reference</strong>
+    <span>Core commands, integrations, extensions, presets, and workflows</span>
+  </a>
+  <a href="community/presets.md" class="nav-card">
+    <strong>Community</strong>
+    <span>Presets, walkthroughs, and friend projects</span>
+  </a>
+  <a href="local-development.md" class="nav-card">
+    <strong>Development</strong>
+    <span>Contribute to Spec Kit</span>
+  </a>
+  <a href="concepts/sdd.md" class="nav-card">
+    <strong>What is SDD?</strong>
+    <span>The philosophy behind Spec-Driven Development</span>
+  </a>
+</div>
+
+---
+
+<div class="footer-cta">
+
+```bash
+uvx --from git+https://github.com/github/spec-kit.git
+specify init my-project --integration copilot
+```
+
+Ready to start? Follow the [Quick Start Guide](quickstart.md).
+
+</div>

docs/install/uv.md

@@ -0,0 +1,60 @@
+# Installing uv
+
+[uv](https://docs.astral.sh/uv/) is a fast Python package manager by [Astral](https://astral.sh/). Spec Kit uses `uv` (via `uvx` or `uv tool install`) to run the `specify` CLI without polluting your global Python environment.
+
+> [!NOTE]
+> **Already have uv?** Run `uv --version` to confirm it is installed, then head back to the [Installation Guide](../installation.md).
+
+## Installation
+
+### macOS and Linux — Standalone Installer
+
+The quickest way to install uv on macOS or Linux is the official shell script:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+After the script finishes, follow any instructions printed by the installer to add uv to your `PATH`, then open a new terminal.
+
+### Windows — Standalone Installer
+
+Run the following in **Command Prompt or PowerShell**:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+After the script finishes, open a new terminal so the `uv` binary is on your `PATH`.
+
+### macOS — Homebrew
+
+```bash
+brew install uv
+```
+
+### Windows — WinGet
+
+```powershell
+winget install --id=astral-sh.uv -e
+```
+
+### Windows — Scoop
+
+```powershell
+scoop install uv
+```
+
+## Verification
+
+Confirm that uv is installed and on your `PATH`:
+
+```bash
+uv --version
+```
+
+You should see output similar to `uv 0.x.y (...)`.
+
+## Further Reading
+
+For advanced options (self-update, proxy settings, uninstall, etc.) see the official [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).

docs/installation.md

@@ -16,6 +16,9 @@
 
 The easiest way to get started is to initialize a new project. Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):
 
+> [!NOTE]
+> The `uvx` commands below require **[uv](https://docs.astral.sh/uv/)**. If you see `command not found: uvx`, [install uv first](./install/uv.md). The `pipx` alternative does not require uv.
+
 ```bash
 # Install from a specific stable release (recommended — replace vX.Y.Z with the latest tag)
 uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>
@@ -41,6 +44,8 @@ uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here
 
 ### Specify Integration
 
+Interactive terminals prompt you to choose a coding agent integration during initialization. Non-interactive sessions, such as CI or piped runs, default to GitHub Copilot unless you pass `--integration`.
+
 You can proactively specify your coding agent integration during initialization:
 
 ```bash

docs/reference/authentication.md

@@ -0,0 +1,181 @@
+# Authentication
+
+Specify CLI uses **opt-in authentication** for HTTP requests to catalog
+sources, extension downloads, and release checks.  No credentials are
+sent unless you explicitly configure them.
+
+## Configuration
+
+Create `~/.specify/auth.json` to enable authentication:
+
+```json
+{
+  "providers": [
+    {
+      "hosts": ["github.com", "api.github.com", "raw.githubusercontent.com", "codeload.github.com"],
+      "provider": "github",
+      "auth": "bearer",
+      "token_env": "GH_TOKEN"
+    }
+  ]
+}
+```
+
+> **Security:** Restrict the file to owner-only access:
+> ```bash
+> chmod 600 ~/.specify/auth.json
+> ```
+
+Without this file, all HTTP requests are unauthenticated.
+
+## Fields
+
+Each entry in the `providers` array has the following fields:
+
+| Field | Required | Description |
+|---|---|---|
+| `hosts` | Yes | Array of hostnames this entry applies to. Supports exact hostnames, or a leading `*.` wildcard for subdomains only (for example, `*.visualstudio.com`). `*.visualstudio.com` matches `foo.visualstudio.com`, but not `visualstudio.com`. Other glob patterns such as `*github.com` or `gith?b.com` are not supported. |
+| `provider` | Yes | Built-in provider key: `github` or `azure-devops`. |
+| `auth` | Yes | Auth scheme (see below). |
+| `token` | No | Token value (inline). Use `token_env` instead when possible. |
+| `token_env` | No | Environment variable name to read the token from. |
+
+For `azure-ad` auth, additional fields are required:
+
+| Field | Required | Description |
+|---|---|---|
+| `tenant_id` | Yes | Azure AD tenant ID. |
+| `client_id` | Yes | Service principal client ID. |
+| `client_secret_env` | Yes | Environment variable containing the client secret. |
+
+Either `token` or `token_env` must be set for `bearer` and `basic-pat` schemes.
+
+## Providers and auth schemes
+
+### GitHub (`github`)
+
+| Scheme | Header | Use for |
+|---|---|---|
+| `bearer` | `Authorization: Bearer <token>` | PATs, fine-grained PATs, OAuth tokens, GitHub App tokens |
+
+**Example — PAT via environment variable:**
+
+```json
+{
+  "hosts": ["github.com", "api.github.com", "raw.githubusercontent.com", "codeload.github.com"],
+  "provider": "github",
+  "auth": "bearer",
+  "token_env": "GH_TOKEN"
+}
+```
+
+### Azure DevOps (`azure-devops`)
+
+| Scheme | Header | Use for |
+|---|---|---|
+| `basic-pat` | `Authorization: Basic base64(:<PAT>)` | Personal Access Tokens |
+| `bearer` | `Authorization: Bearer <token>` | Pre-acquired OAuth / Azure AD tokens |
+| `azure-cli` | `Authorization: Bearer <token>` | Token acquired via `az account get-access-token` |
+| `azure-ad` | `Authorization: Bearer <token>` | Token acquired via OAuth2 client credentials flow |
+
+**Example — PAT via environment variable:**
+
+```json
+{
+  "hosts": ["dev.azure.com"],
+  "provider": "azure-devops",
+  "auth": "basic-pat",
+  "token_env": "AZURE_DEVOPS_PAT"
+}
+```
+
+**Example — Azure CLI (interactive login):**
+
+```json
+{
+  "hosts": ["dev.azure.com"],
+  "provider": "azure-devops",
+  "auth": "azure-cli"
+}
+```
+
+Requires `az login` to have been run beforehand.
+
+**Example — Azure AD service principal (CI/automation):**
+
+```json
+{
+  "hosts": ["dev.azure.com"],
+  "provider": "azure-devops",
+  "auth": "azure-ad",
+  "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "client_secret_env": "AZURE_CLIENT_SECRET"
+}
+```
+
+## Multiple entries
+
+You can configure multiple entries for different hosts or organizations:
+
+```json
+{
+  "providers": [
+    {
+      "hosts": ["github.com", "api.github.com", "raw.githubusercontent.com", "codeload.github.com"],
+      "provider": "github",
+      "auth": "bearer",
+      "token_env": "GH_TOKEN"
+    },
+    {
+      "hosts": ["dev.azure.com"],
+      "provider": "azure-devops",
+      "auth": "basic-pat",
+      "token_env": "AZURE_DEVOPS_PAT"
+    }
+  ]
+}
+```
+
+## How it works
+
+1. For each outbound HTTP request, the URL hostname is matched against
+   the `hosts` patterns in `auth.json`.
+2. If a match is found, the corresponding provider resolves the token
+   and attaches the appropriate `Authorization` header.
+3. If the request receives a 401 or 403, the next matching entry is tried.
+4. After all matching entries are exhausted, an unauthenticated request
+   is attempted as a final fallback.
+5. On redirects, the `Authorization` header is stripped if the redirect
+   target leaves the entry's declared hosts — preventing credential
+   leakage to CDNs or third-party services.
+
+## Template
+
+A reference `auth.json` with GitHub pre-configured:
+
+```json
+{
+  "providers": [
+    {
+      "hosts": [
+        "github.com",
+        "api.github.com",
+        "raw.githubusercontent.com",
+        "codeload.github.com"
+      ],
+      "provider": "github",
+      "auth": "bearer",
+      "token_env": "GH_TOKEN"
+    }
+  ]
+}
+```
+
+To use it:
+
+```bash
+mkdir -p ~/.specify
+# Copy the JSON above into ~/.specify/auth.json
+chmod 600 ~/.specify/auth.json
+```

docs/reference/core.md

@@ -22,8 +22,14 @@ specify init [<project_name>]
 
 Creates a new Spec Kit project with the necessary directory structure, templates, scripts, and AI coding agent integration files.
 
+> [!NOTE]
+> The git extension is currently enabled by default during `specify init`.
+> Starting in `v0.10.0`, it will require explicit opt-in. To add it after init, run `specify extension add git`.
+
 Use `<project_name>` to create a new directory, or `--here` (or `.`) to initialize in the current directory. If the directory already has files, use `--force` to merge without confirmation.
 
+When `--integration` is omitted, interactive terminals prompt you to choose an integration. Non-interactive sessions, such as CI or piped runs, default to GitHub Copilot; pass `--integration <key>` to choose a different integration explicitly.
+
 ### Examples
 
 ```bash

docs/reference/integrations.md

@@ -23,7 +23,8 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify
 | [Junie](https://junie.jetbrains.com/)                                                | `junie`          |                                                                                                                                           |
 | [Kilo Code](https://github.com/Kilo-Org/kilocode)                                    | `kilocode`       |                                                                                                                                           |
 | [Kimi Code](https://code.kimi.com/)                                                  | `kimi`           | Skills-based integration; supports `--migrate-legacy` for dotted→hyphenated directory migration                                            |
-| [Kiro CLI](https://kiro.dev/docs/cli/)                                               | `kiro-cli`       | Alias: `--integration kiro`                                                                                                               |
+| [Kiro CLI](https://kiro.dev/docs/cli/)                                               | `kiro-cli`       | Kiro CLI does not substitute `$ARGUMENTS` in file-based prompts, so Spec Kit ships a prose fallback at render time (see [Manage prompts](https://kiro.dev/docs/cli/chat/manage-prompts/) and issue [#1926](https://github.com/github/spec-kit/issues/1926)). Alias: `--integration kiro` |
+| [Lingma](https://lingma.aliyun.com/)                                                 | `lingma`         | Skills-based integration; skills are installed automatically                                                                               |
 | [Mistral Vibe](https://github.com/mistralai/mistral-vibe)                            | `vibe`           |                                                                                                                                           |
 | [opencode](https://opencode.ai/)                                                     | `opencode`       |                                                                                                                                           |
 | [Pi Coding Agent](https://pi.dev)                                                    | `pi`             | Pi doesn't have MCP support out of the box, so `taskstoissues` won't work as intended. MCP support can be added via [extensions](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#extensions) |
@@ -43,6 +44,8 @@ specify integration list
 ```
 
 Shows all available integrations, which one is currently installed, and whether each requires a CLI tool or is IDE-based.
+When multiple integrations are installed, the list marks the default integration separately from the other installed integrations.
+The list also shows whether each built-in integration is declared multi-install safe.
 
 ## Install an Integration
 
@@ -53,12 +56,17 @@ specify integration install <key>
 | Option                   | Description                                                              |
 | ------------------------ | ------------------------------------------------------------------------ |
 | `--script sh\|ps`        | Script type: `sh` (bash/zsh) or `ps` (PowerShell)                        |
+| `--force`                | Opt in to installing alongside integrations that are not declared multi-install safe |
 | `--integration-options`  | Integration-specific options (e.g. `--integration-options="--commands-dir .myagent/cmds"`) |
 
-Installs the specified integration into the current project. Fails if another integration is already installed — use `switch` instead. If the installation fails partway through, it automatically rolls back to a clean state.
+Installs the specified integration into the current project. If another integration is already installed, the command only proceeds automatically when all involved integrations are declared multi-install safe. Otherwise, use `switch` to replace the default integration or pass `--force` to explicitly opt in to multi-install. If the installation fails partway through, it automatically rolls back to a clean state.
+
+Installing an additional integration does not change the default integration. Use `specify integration use <key>` to change the default.
 
 > **Note:** All integration management commands require a project already initialized with `specify init`. To start a new project with a specific agent, use `specify init <project> --integration <key>` instead.
 
+**Version note:** Controlled multi-install support was introduced in Spec Kit 0.8.5. If `specify integration install <key>` says another integration is already installed and only suggests `switch` or `uninstall`, check your local CLI with `specify version` and upgrade it. Running a one-shot command such as `uvx --from git+https://github.com/github/spec-kit.git specify ...` uses a temporary copy for that command only; it does not update the persistent `specify` executable on your `PATH`.
+
 ## Uninstall an Integration
 
 ```bash
@@ -84,10 +92,22 @@ specify integration switch <key>
 | Option                   | Description                                                              |
 | ------------------------ | ------------------------------------------------------------------------ |
 | `--script sh\|ps`        | Script type: `sh` (bash/zsh) or `ps` (PowerShell)                        |
-| `--force`                | Force removal of modified files during uninstall                         |
-| `--integration-options`  | Options for the target integration                                       |
+| `--force`                | Force removal of modified files during uninstall; when the target is already installed, overwrite managed shared templates while changing the default |
+| `--integration-options`  | Options for the target integration when it is not already installed      |
 
-Equivalent to running `uninstall` followed by `install` in a single step.
+If the target integration is not already installed, equivalent to running `uninstall` followed by `install` in a single step. In this mode, `--force` controls whether modified files from the removed integration are deleted. If the target integration is already installed, `switch` only changes the default integration, like `use`; in this mode, `--force` controls whether managed shared templates are overwritten while the default changes. `--integration-options` is rejected for already-installed targets because changing integration options requires reinstalling managed files; run `upgrade <key> --integration-options ...` first, then `use <key>`.
+
+## Use an Installed Integration
+
+```bash
+specify integration use <key>
+```
+
+| Option    | Description                                         |
+| --------- | --------------------------------------------------- |
+| `--force` | Overwrite managed shared templates while changing the default |
+
+Sets the default integration without uninstalling any other installed integrations. This also refreshes managed shared templates so command references match the new default integration's invocation style. Modified or untracked shared templates are preserved unless `--force` is used.
 
 ## Upgrade an Integration
 
@@ -101,7 +121,7 @@ specify integration upgrade [<key>]
 | `--script sh\|ps`        | Script type: `sh` (bash/zsh) or `ps` (PowerShell)                        |
 | `--integration-options`  | Options for the integration                                              |
 
-Reinstalls the current integration with updated templates and commands (e.g., after upgrading Spec Kit). Defaults to the currently installed integration; if a key is provided, it must match the installed one — otherwise the command fails and suggests using `switch` instead. Detects locally modified files and blocks the upgrade unless `--force` is used. Stale files from the previous install that are no longer needed are removed automatically.
+Reinstalls an installed integration with updated templates and commands (e.g., after upgrading Spec Kit). Defaults to the default integration; if a key is provided, it must be one of the installed integrations. Detects locally modified files and blocks the upgrade unless `--force` is used. Stale files from the previous install that are no longer needed are removed automatically. Shared templates stay aligned with the default integration even when upgrading a non-default integration.
 
 ## Integration-Specific Options
 
@@ -120,9 +140,39 @@ specify integration install generic --integration-options="--commands-dir .myage
 
 ## FAQ
 
-### Can I use multiple integrations at the same time?
+### Can I install multiple integrations in the same project?
 
-No. Only one AI coding agent integration can be installed per project. Use `specify integration switch <key>` to change to a different AI coding agent.
+Yes, but it is intended for team portability rather than the default workflow. Multiple integrations are allowed automatically only when the installed integration and the new integration are declared multi-install safe by Spec Kit. For other combinations, pass `--force` to acknowledge that multiple agents may see unrelated agent-specific instructions or commands.
+
+Spec Kit tracks one default integration in `.specify/integration.json` with `default_integration`, all installed integrations with `installed_integrations`, per-integration runtime settings with `integration_settings`, and a dedicated `integration_state_schema` for future state migrations. The legacy `integration` field remains as an alias for the default integration.
+
+### Which integrations are multi-install safe?
+
+An integration is multi-install safe when it uses isolated agent directories, a dedicated context file that does not collide with another safe integration, stable command invocation settings, and a separate install manifest. Shared Spec Kit templates remain aligned to the single default integration.
+
+The currently declared multi-install safe integrations are:
+
+| Key | Isolation |
+| --- | --------- |
+| `auggie` | `.augment/commands`, `.augment/rules/specify-rules.md` |
+| `claude` | `.claude/skills`, `CLAUDE.md` |
+| `codebuddy` | `.codebuddy/commands`, `CODEBUDDY.md` |
+| `codex` | `.agents/skills`, `AGENTS.md` |
+| `cursor-agent` | `.cursor/skills`, `.cursor/rules/specify-rules.mdc` |
+| `gemini` | `.gemini/commands`, `GEMINI.md` |
+| `iflow` | `.iflow/commands`, `IFLOW.md` |
+| `junie` | `.junie/commands`, `.junie/AGENTS.md` |
+| `kilocode` | `.kilocode/workflows`, `.kilocode/rules/specify-rules.md` |
+| `kimi` | `.kimi/skills`, `KIMI.md` |
+| `qodercli` | `.qoder/commands`, `QODER.md` |
+| `qwen` | `.qwen/commands`, `QWEN.md` |
+| `roo` | `.roo/commands`, `.roo/rules/specify-rules.md` |
+| `shai` | `.shai/commands`, `SHAI.md` |
+| `tabnine` | `.tabnine/agent/commands`, `TABNINE.md` |
+| `trae` | `.trae/skills`, `.trae/rules/project_rules.md` |
+| `windsurf` | `.windsurf/workflows`, `.windsurf/rules/specify-rules.md` |
+
+Integrations that share a context file or command directory with another integration, require dynamic install paths such as `--commands-dir`, or merge shared tool settings are not declared safe by default. They can still be installed alongside another integration with `--force`.
 
 ### What happens to my changes when I uninstall or switch?
 
@@ -138,4 +188,4 @@ CLI-based integrations (like Claude Code, Gemini CLI) require the tool to be ins
 
 ### When should I use `upgrade` vs `switch`?
 
-Use `upgrade` when you've upgraded Spec Kit and want to refresh the same integration's templates. Use `switch` when you want to change to a different AI coding agent.
+Use `upgrade` when you've upgraded Spec Kit and want to refresh an installed integration's managed files. Use `switch` when you want to replace the current default with another integration; if the target is already installed, `switch` behaves like `use`.

docs/template/public/main.css

@@ -0,0 +1,264 @@
+/* Spec Kit landing page — GitHub Primer colors */
+
+:root {
+  /* GitHub Primer palette */
+  --gh-blue: #0969da;
+  --gh-green: #1a7f37;
+  --gh-purple: #8250df;
+  --gh-coral: #cf222e;
+  --gh-orange: #bf8700;
+  --gh-blue-subtle: #ddf4ff;
+  --gh-green-subtle: #dafbe1;
+  --gh-purple-subtle: #fbefff;
+  --gh-coral-subtle: #ffebe9;
+}
+
+[data-bs-theme="dark"] {
+  --gh-blue: #58a6ff;
+  --gh-green: #3fb950;
+  --gh-purple: #bc8cff;
+  --gh-coral: #f85149;
+  --gh-orange: #d29922;
+  --gh-blue-subtle: #0d1d30;
+  --gh-green-subtle: #0d1d14;
+  --gh-purple-subtle: #1c0d2e;
+  --gh-coral-subtle: #2d0f0d;
+}
+
+/* Override Bootstrap primary with GitHub blue */
+body[data-layout="landing"] {
+  --bs-primary: var(--gh-blue);
+  --bs-primary-rgb: 9, 105, 218;
+  --bs-link-color: var(--gh-blue);
+  --bs-link-hover-color: var(--gh-blue);
+}
+
+[data-bs-theme="dark"] body[data-layout="landing"],
+body[data-layout="landing"][data-bs-theme="dark"] {
+  --bs-primary-rgb: 88, 166, 255;
+}
+
+/* Hero section */
+.landing-hero {
+  text-align: center;
+  padding: 3rem 0 1.5rem;
+}
+
+.landing-hero h1 {
+  font-size: 2.6rem;
+  font-weight: 800;
+  margin-bottom: 0.5rem;
+  background: linear-gradient(135deg, var(--gh-blue), var(--gh-purple));
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+.landing-hero p {
+  font-size: 1.15rem;
+  max-width: 640px;
+  margin: 0 auto 1.5rem;
+  opacity: 0.85;
+}
+
+.landing-hero .btn-primary {
+  background-color: var(--gh-blue);
+  border-color: var(--gh-blue);
+  color: #fff;
+}
+
+.landing-hero .btn-primary:hover {
+  background-color: #0860ca;
+  border-color: #0860ca;
+}
+
+.landing-hero .btn-outline-primary {
+  color: var(--gh-blue);
+  border-color: var(--gh-blue);
+}
+
+.landing-hero .btn-outline-primary:hover {
+  background-color: var(--gh-blue);
+  border-color: var(--gh-blue);
+  color: #fff;
+}
+
+/* Pillar cards grid */
+.pillar-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1.5rem;
+  margin: 2rem 0;
+}
+
+@media (max-width: 768px) {
+  .pillar-grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+.pillar-card {
+  border: 1px solid var(--bs-border-color);
+  border-radius: 0.5rem;
+  padding: 1.5rem;
+  background: var(--bs-body-bg);
+  transition: box-shadow 0.2s ease-in-out, border-color 0.2s ease-in-out;
+  border-top: 3px solid transparent;
+}
+
+/* Each pillar gets a distinct GitHub color accent */
+.pillar-card:nth-child(1) { border-top-color: var(--gh-green); }
+.pillar-card:nth-child(2) { border-top-color: var(--gh-blue); }
+.pillar-card:nth-child(3) { border-top-color: var(--gh-purple); }
+.pillar-card:nth-child(4) { border-top-color: var(--gh-coral); }
+
+.pillar-card:nth-child(1):hover { box-shadow: 0 4px 16px rgba(26, 127, 55, 0.12); }
+.pillar-card:nth-child(2):hover { box-shadow: 0 4px 16px rgba(9, 105, 218, 0.12); }
+.pillar-card:nth-child(3):hover { box-shadow: 0 4px 16px rgba(130, 80, 223, 0.12); }
+.pillar-card:nth-child(4):hover { box-shadow: 0 4px 16px rgba(207, 34, 46, 0.12); }
+
+[data-bs-theme="dark"] .pillar-card:nth-child(1):hover { box-shadow: 0 4px 16px rgba(63, 185, 80, 0.15); }
+[data-bs-theme="dark"] .pillar-card:nth-child(2):hover { box-shadow: 0 4px 16px rgba(88, 166, 255, 0.15); }
+[data-bs-theme="dark"] .pillar-card:nth-child(3):hover { box-shadow: 0 4px 16px rgba(188, 140, 255, 0.15); }
+[data-bs-theme="dark"] .pillar-card:nth-child(4):hover { box-shadow: 0 4px 16px rgba(248, 81, 73, 0.15); }
+
+.pillar-card h3 {
+  font-size: 1.2rem;
+  font-weight: 600;
+  margin-bottom: 0.75rem;
+}
+
+/* Pillar headings pick up their card's accent color */
+.pillar-card:nth-child(1) h3 { color: var(--gh-green); }
+.pillar-card:nth-child(2) h3 { color: var(--gh-blue); }
+.pillar-card:nth-child(3) h3 { color: var(--gh-purple); }
+.pillar-card:nth-child(4) h3 { color: var(--gh-coral); }
+
+.pillar-card .pillar-stat {
+  font-weight: 600;
+  color: var(--gh-blue);
+}
+
+.pillar-card:nth-child(3) .pillar-stat {
+  color: var(--gh-purple);
+}
+
+.pillar-card p:last-child {
+  margin-bottom: 0;
+}
+
+.pillar-card ul {
+  padding-left: 1.2rem;
+  margin-bottom: 0.5rem;
+}
+
+.pillar-card .pillar-link {
+  display: inline-block;
+  margin-top: 0.5rem;
+  font-size: 0.9rem;
+  font-weight: 500;
+}
+
+.pillar-card:nth-child(1) .pillar-link { color: var(--gh-blue); }
+.pillar-card:nth-child(2) .pillar-link { color: var(--gh-green); }
+.pillar-card:nth-child(3) .pillar-link { color: var(--gh-purple); }
+.pillar-card:nth-child(4) .pillar-link { color: var(--gh-coral); }
+
+/* Community stats section */
+.community-section {
+  text-align: center;
+  padding: 2rem 0;
+}
+
+.stats-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 1rem;
+  margin: 1.5rem auto;
+  max-width: 700px;
+}
+
+@media (max-width: 576px) {
+  .stats-grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+.stat-item {
+  padding: 1rem;
+}
+
+.stat-item .stat-number {
+  display: block;
+  font-size: 1.8rem;
+  font-weight: 700;
+  color: var(--gh-blue);
+  line-height: 1.2;
+}
+
+.stat-item .stat-label {
+  display: block;
+  font-size: 0.85rem;
+  opacity: 0.75;
+  margin-top: 0.25rem;
+}
+
+/* Nav cards */
+.nav-cards {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
+  margin: 1.5rem 0;
+}
+
+@media (max-width: 576px) {
+  .nav-cards {
+    grid-template-columns: 1fr;
+  }
+}
+
+.nav-card {
+  border: 1px solid var(--bs-border-color);
+  border-radius: 0.5rem;
+  padding: 1rem 1.25rem;
+  text-decoration: none;
+  color: inherit;
+  transition: box-shadow 0.2s ease-in-out, border-color 0.2s ease-in-out;
+  display: block;
+  border-left: 3px solid var(--gh-blue);
+}
+
+.nav-card:hover {
+  border-color: var(--gh-blue);
+  border-left-color: var(--gh-blue);
+  box-shadow: 0 2px 8px rgba(9, 105, 218, 0.1);
+  text-decoration: none;
+  color: inherit;
+}
+
+[data-bs-theme="dark"] .nav-card:hover {
+  box-shadow: 0 2px 8px rgba(88, 166, 255, 0.12);
+}
+
+.nav-card strong {
+  display: block;
+  margin-bottom: 0.25rem;
+  color: var(--gh-blue);
+}
+
+.nav-card span {
+  font-size: 0.9rem;
+  opacity: 0.75;
+}
+
+/* Footer CTA */
+.footer-cta {
+  text-align: center;
+  padding: 2rem 0 1rem;
+}
+
+.footer-cta code {
+  font-size: 1.05rem;
+  padding: 0.5rem 1rem;
+  border-radius: 0.375rem;
+}

docs/toc.yml

@@ -11,6 +11,8 @@
       href: quickstart.md
     - name: Upgrade
       href: upgrade.md
+    - name: Install uv
+      href: install/uv.md
 
 # Reference
 - name: Reference
@@ -28,6 +30,12 @@
     - name: Workflows
       href: reference/workflows.md
 
+# Concepts
+- name: Concepts
+  items:
+    - name: What is SDD?
+      href: concepts/sdd.md
+
 # Development workflows
 - name: Development
   items:

docs/upgrade.md

@@ -19,6 +19,12 @@
 
 The CLI tool (`specify`) is separate from your project files. Upgrade it to get the latest features and bug fixes.
 
+Before upgrading, you can check whether a newer released version is available:
+
+```bash
+specify self check
+```
+
 ### If you installed with `uv tool install`
 
 Upgrade to a specific release (check [Releases](https://github.com/github/spec-kit/releases) for the latest tag):
@@ -35,6 +41,8 @@ Specify the desired release tag:
 uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --integration copilot
 ```
 
+`uvx` runs a temporary copy of Spec Kit for that single command. It does not update a persistent `specify` installed with `uv tool install`, `pipx`, or another tool manager. If a newer feature works through `uvx` but your local `specify` still reports an older version, upgrade the persistent CLI with the command that matches your install method.
+
 ### If you installed with `pipx`
 
 Upgrade to a specific release:
@@ -49,7 +57,7 @@ pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z
 specify check
 ```
 
-This shows installed tools and confirms the CLI is working.
+This shows installed tools and confirms the CLI is working. Use `specify version` to confirm which persistent CLI version is currently on your `PATH`.
 
 ---
 

extensions/EXTENSION-DEVELOPMENT-GUIDE.md

@@ -528,11 +528,9 @@ specify extension add <extension-name> --from https://github.com/.../spec-kit-my
 
 Submit to the community catalog for public discovery:
 
-1. **Fork** spec-kit repository
-2. **Add entry** to `extensions/catalog.community.json`
-3. **Update** the Community Extensions table in `README.md` with your extension
-4. **Create PR** following the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md)
-5. **After merge**, your extension becomes available:
+1. **Create a GitHub release** for your extension
+2. **File an issue** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template
+3. **After review**, a maintainer updates the catalog and 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)

extensions/EXTENSION-PUBLISHING-GUIDE.md

@@ -7,9 +7,8 @@ This guide explains how to publish your extension to the Spec Kit extension cata
 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)
+4. [Release Workflow](#release-workflow)
+5. [Best Practices](#best-practices)
 
 ---
 
@@ -133,222 +132,46 @@ specify extension add <extension-name> --from https://github.com/your-org/spec-k
 
 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`.
+**For extension publishing**: All community extensions are listed in `extensions/catalog.community.json`. Users browse this catalog and copy extensions they trust into their own `catalog.json`.
 
-### 1. Fork the spec-kit Repository
+### How to Submit
 
-```bash
-# Fork on GitHub
-# https://github.com/github/spec-kit/fork
+To submit your extension to the community catalog, file a new issue using the **[Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml)** template. The template collects all required metadata, including:
 
-# Clone your fork
-git clone https://github.com/YOUR-USERNAME/spec-kit.git
-cd spec-kit
-```
+- Extension ID, name, and version
+- Description, author, and license
+- Repository, download URL, and documentation links
+- Required Spec Kit version and any tool dependencies
+- Number of commands and hooks
+- Tags and key features
+- Testing confirmation
 
-### 2. Add Extension to Community Catalog
+> [!IMPORTANT]
+> Do **not** open a pull request directly to edit `extensions/catalog.community.json`. All community extension submissions must go through the issue template so a maintainer can review the entry and update the catalog.
 
-Edit `extensions/catalog.community.json` and add your extension:
+### What Happens After You Submit
 
-```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"
-    }
-  }
-}
-```
+1. Your issue is automatically labeled and assigned to a maintainer for review
+2. A maintainer verifies that the catalog entry is complete and correctly formatted
+3. Once approved, the maintainer adds your extension to `extensions/catalog.community.json` and the Community Extensions table in the README
+4. Your extension becomes discoverable via `specify extension search`
 
-**Important**:
+### What Maintainers Check
 
-- 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
+- The catalog entry fields are complete and correctly formatted
+- The download URL is accessible
+- The repository exists and contains an `extension.yml` manifest
 
-### 3. Update Community Extensions Table
-
-Add your extension to the Community Extensions table in the project root `README.md`:
-
-```markdown
-| Your Extension Name | Brief description of what it does | `<category>` | <effect> | [repo-name](https://github.com/your-org/spec-kit-your-extension) |
-```
-
-**(Table) Category** — pick the one that best fits your extension:
-
-- `docs` — reads, validates, or generates spec artifacts
-- `code` — reviews, validates, or modifies source code
-- `process` — orchestrates workflow across phases
-- `integration` — syncs with external platforms
-- `visibility` — reports on project health or progress
-
-**Effect** — choose one:
-
-- Read-only — produces reports without modifying files
-- Read+Write — modifies files, creates artifacts, or updates specs
-
-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 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 Community Extensions table in README.md
-
-### 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
+> [!NOTE]
+> Maintainers do **not** review, audit, or test the extension code itself.
 
 ### Typical Review Timeline
 
-- **Automated checks**: Immediate (if implemented)
-- **Manual review**: 3-7 business days
-- **Verification**: After successful review
+- **Review**: 3-7 business days
+
+### Updating an Existing Extension
+
+To update an extension that is already in the catalog (e.g., for a new version), file a new **[Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml)** issue with the updated version, download URL, and any other changed fields. Mention in the issue that this is an update to an existing entry.
 
 ---
 
@@ -385,26 +208,7 @@ When releasing a new version:
    # 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
+4. **File an update submission** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template with the new version and download URL. Mention in the issue that this is an update to an existing entry.
 
 ---
 
@@ -473,9 +277,9 @@ A: The main catalog is for public extensions only. For private extensions:
 - 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?
+### Q: How long does review take?
 
-A: Typically 3-7 business days for initial review. Updates to verified extensions are usually faster.
+A: Typically 3-7 business days. Updates to existing extensions are usually faster.
 
 ### Q: What if my extension is rejected?
 
@@ -483,11 +287,11 @@ A: You'll receive feedback on what needs to be fixed. Make the changes and resub
 
 ### 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.
+A: Yes, file a new [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) issue with the updated version and download URL. Mention that it is an update to an existing entry.
 
 ### 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.
+A: No. All community extensions are listed in the catalog once their submission is reviewed and accepted.
 
 ### Q: Can extensions have paid features?
 
@@ -536,7 +340,7 @@ A: Extensions should be free and open-source. Commercial support/services are al
     "hooks": "integer (optional)"
   },
   "tags": ["array of strings (2-10 tags)"],
-  "verified": "boolean (default: false)",
+  "verified": "boolean (default: false, set by maintainers)",
   "downloads": "integer (auto-updated)",
   "stars": "integer (auto-updated)",
   "created_at": "string (ISO 8601 datetime)",

extensions/README.md

@@ -25,13 +25,13 @@ specify extension search  # Now uses your organization's catalog instead of the
 ### Community Reference Catalog (`catalog.community.json`)
 
 > [!NOTE]
-> Community extensions are independently created and maintained by their respective authors. GitHub and the Spec Kit maintainers may review pull requests that add entries to the community catalog for formatting, catalog structure, or policy compliance, but they do **not review, audit, endorse, or support the extension code itself**. Review extension source code before installation and use at your own discretion.
+> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. Review extension source code before installation and use at your own discretion.
 
 - **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
+- **Submission**: Open to community contributions via [issue template](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml)
 
 **How It Works:**
 
@@ -72,7 +72,7 @@ specify extension add <extension-name> --from https://github.com/org/spec-kit-ex
 ## Available Community Extensions
 
 > [!NOTE]
-> Community extensions are independently created and maintained by their respective authors. GitHub and the Spec Kit maintainers may review pull requests that add entries to the community catalog for formatting, catalog structure, or policy compliance, but they do **not review, audit, endorse, or support the extension code itself**. The Community Extensions website is also a third-party resource. Review extension source code before installation and use at your own discretion.
+> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. The Community Extensions website is also a third-party resource. Review extension source code before installation and use at your own discretion.
 
 🔍 **Browse and search community extensions on the [Community Extensions website](https://speckit-community.github.io/extensions/).**
 
@@ -89,10 +89,8 @@ 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
+3. **File an issue** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template with all required metadata
+4. **Wait for review** — a maintainer will review the submission, update the catalog, and close the issue
 
 See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed step-by-step instructions.
 

extensions/catalog.community.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-04-29T00:00:00Z",
+  "updated_at": "2026-05-12T21:40:51Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
   "extensions": {
     "aide": {
@@ -68,6 +68,75 @@
       "created_at": "2026-03-31T00:00:00Z",
       "updated_at": "2026-03-31T00:00:00Z"
     },
+    "agent-orchestrator": {
+      "name": "Intelligent Agent Orchestrator",
+      "id": "agent-orchestrator",
+      "description": "Cross-catalog agent discovery and intelligent prompt-to-command routing",
+      "author": "pragya247",
+      "version": "0.1.0",
+      "download_url": "https://github.com/pragya247/spec-kit-orchestrator/archive/refs/tags/v0.1.0.zip",
+      "repository": "https://github.com/pragya247/spec-kit-orchestrator",
+      "homepage": "https://github.com/pragya247/spec-kit-orchestrator",
+      "documentation": "https://github.com/pragya247/spec-kit-orchestrator/blob/main/README.md",
+      "changelog": "https://github.com/pragya247/spec-kit-orchestrator/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.6.1"
+      },
+      "provides": {
+        "commands": 3,
+        "hooks": 1
+      },
+      "tags": [
+        "orchestrator",
+        "routing",
+        "discovery",
+        "agent",
+        "ai"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-04T00:00:00Z",
+      "updated_at": "2026-05-04T00:00:00Z"
+    },
+    "api-evolve": {
+      "name": "API Evolve",
+      "id": "api-evolve",
+      "description": "Managed API contract evolution — breaking-change detection, semver enforcement, deprecation orchestration, and lifecycle gates across REST, GraphQL, and gRPC.",
+      "author": "Quratulain-bilal",
+      "version": "1.0.0",
+      "download_url": "https://github.com/Quratulain-bilal/spec-kit-api-evolve/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/Quratulain-bilal/spec-kit-api-evolve",
+      "homepage": "https://github.com/Quratulain-bilal/spec-kit-api-evolve",
+      "documentation": "https://github.com/Quratulain-bilal/spec-kit-api-evolve/blob/main/README.md",
+      "changelog": "https://github.com/Quratulain-bilal/spec-kit-api-evolve/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.4.0"
+      },
+      "provides": {
+        "commands": 12,
+        "hooks": 5
+      },
+      "tags": [
+        "api",
+        "contracts",
+        "versioning",
+        "openapi",
+        "graphql",
+        "grpc",
+        "deprecation",
+        "breaking-changes",
+        "semver",
+        "governance"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-07T00:00:00Z",
+      "updated_at": "2026-05-07T00:00:00Z"
+    },
     "architect-preview": {
       "name": "Architect Impact Previewer",
       "id": "architect-preview",
@@ -100,6 +169,39 @@
       "created_at": "2026-04-14T00:00:00Z",
       "updated_at": "2026-04-14T00:00:00Z"
     },
+    "architecture-guard": {
+      "name": "Architecture Guard",
+      "id": "architecture-guard",
+      "description": "Continuous architecture governance for AI-assisted development. Reviews specs, plans, and code for architecture drift, producing structured refactor tasks and evolution proposals.",
+      "author": "DyanGalih",
+      "version": "1.8.4",
+      "download_url": "https://github.com/DyanGalih/spec-kit-architecture-guard/archive/refs/tags/v1.8.4.zip",
+      "repository": "https://github.com/DyanGalih/spec-kit-architecture-guard",
+      "homepage": "https://github.com/DyanGalih/spec-kit-architecture-guard",
+      "documentation": "https://github.com/DyanGalih/spec-kit-architecture-guard/blob/main/README.md",
+      "changelog": "https://github.com/DyanGalih/spec-kit-architecture-guard/releases",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 10,
+        "hooks": 3
+      },
+      "tags": [
+        "architecture",
+        "governance",
+        "drift-detection",
+        "refactor",
+        "monolithic",
+        "microservices"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-05T07:26:00Z",
+      "updated_at": "2026-05-11T14:58:00Z"
+    },
     "archive": {
       "name": "Archive Extension",
       "id": "archive",
@@ -266,6 +368,38 @@
       "created_at": "2026-04-10T00:00:00Z",
       "updated_at": "2026-04-10T00:00:00Z"
     },
+    "brownkit": {
+      "name": "BrownKit \u2014 Brownfield Discovery for Spec-Kit",
+      "id": "brownkit",
+      "description": "Evidence-driven capability discovery, security and QA risk assessment for existing codebases.",
+      "author": "Maksim Shautsou",
+      "version": "1.0.1",
+      "download_url": "https://github.com/MaksimShevtsov/BrownKit/archive/refs/tags/v1.0.1.zip",
+      "repository": "https://github.com/MaksimShevtsov/BrownKit",
+      "homepage": "https://github.com/MaksimShevtsov/BrownKit",
+      "documentation": "https://github.com/MaksimShevtsov/BrownKit/blob/main/README.md",
+      "changelog": "https://github.com/MaksimShevtsov/BrownKit/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 10,
+        "hooks": 5
+      },
+      "tags": [
+        "brownfield",
+        "discovery",
+        "security",
+        "qa",
+        "capabilities"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-10T00:00:00Z",
+      "updated_at": "2026-05-10T00:00:00Z"
+    },
     "bugfix": {
       "name": "Bugfix Workflow",
       "id": "bugfix",
@@ -365,6 +499,38 @@
       "created_at": "2026-04-16T00:00:00Z",
       "updated_at": "2026-04-16T00:00:00Z"
     },
+    "changelog": {
+      "name": "Spec Changelog",
+      "id": "changelog",
+      "description": "Auto-generate changelogs and release notes from spec git history and requirement diffs.",
+      "author": "Quratulain-bilal",
+      "version": "1.0.0",
+      "download_url": "https://github.com/Quratulain-bilal/spec-kit-changelog/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/Quratulain-bilal/spec-kit-changelog",
+      "homepage": "https://github.com/Quratulain-bilal/spec-kit-changelog",
+      "documentation": "https://github.com/Quratulain-bilal/spec-kit-changelog/blob/main/README.md",
+      "changelog": "https://github.com/Quratulain-bilal/spec-kit-changelog/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.4.0"
+      },
+      "provides": {
+        "commands": 4,
+        "hooks": 1
+      },
+      "tags": [
+        "changelog",
+        "release-notes",
+        "documentation",
+        "git-history",
+        "notifications"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-04-11T18:00:00Z",
+      "updated_at": "2026-04-11T18:00:00Z"
+    },
     "ci-guard": {
       "name": "CI Guard",
       "id": "ci-guard",
@@ -547,6 +713,38 @@
       "created_at": "2026-03-29T00:00:00Z",
       "updated_at": "2026-03-29T00:00:00Z"
     },
+    "cost": {
+      "name": "Cost Tracker",
+      "id": "cost",
+      "description": "Track real LLM dollar cost across SDD workflows — per-feature budgets, per-integration comparison, and finance-ready exports.",
+      "author": "Quratulain-bilal",
+      "version": "1.0.0",
+      "download_url": "https://github.com/Quratulain-bilal/spec-kit-cost/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/Quratulain-bilal/spec-kit-cost",
+      "homepage": "https://github.com/Quratulain-bilal/spec-kit-cost",
+      "documentation": "https://github.com/Quratulain-bilal/spec-kit-cost/blob/main/README.md",
+      "changelog": "https://github.com/Quratulain-bilal/spec-kit-cost/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.0"
+      },
+      "provides": {
+        "commands": 5,
+        "hooks": 0
+      },
+      "tags": [
+        "cost",
+        "budget",
+        "tokens",
+        "visibility",
+        "finance"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-03T00:00:00Z",
+      "updated_at": "2026-05-05T00:00:00Z"
+    },
     "diagram": {
       "name": "Spec Diagram",
       "id": "diagram",
@@ -777,6 +975,44 @@
       "created_at": "2026-03-06T00:00:00Z",
       "updated_at": "2026-03-31T00:00:00Z"
     },
+    "fx-to-dotnet": {
+      "name": ".NET Framework to Modern .NET Migration",
+      "id": "fx-to-dotnet",
+      "description": "Orchestrate end-to-end .NET Framework to modern .NET migration across 7 phases, with SDD lifecycle integration.",
+      "author": "RogerBestMsft",
+      "version": "0.8.0",
+      "download_url": "https://github.com/RogerBestMsft/spec-kit-FxToNet/releases/download/v0.8.0/fx-to-dotnet.zip",
+      "repository": "https://github.com/RogerBestMsft/spec-kit-FxToNet",
+      "homepage": "https://github.com/RogerBestMsft/spec-kit-FxToNet",
+      "documentation": "https://github.com/RogerBestMsft/spec-kit-FxToNet/blob/main/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0",
+        "tools": [
+          {
+            "name": "Microsoft.GitHubCopilot.Modernization.Mcp",
+            "required": true
+          }
+        ]
+      },
+      "provides": {
+        "commands": 12,
+        "hooks": 5
+      },
+      "tags": [
+        "dotnet",
+        "migration",
+        "modernization",
+        "framework",
+        "aspnet",
+        "shared-artifact"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-06T00:00:00Z",
+      "updated_at": "2026-05-06T00:00:00Z"
+    },
     "github-issues": {
       "name": "GitHub Issues Integration 1",
       "id": "github-issues",
@@ -1244,6 +1480,35 @@
       "created_at": "2026-04-28T00:00:00Z",
       "updated_at": "2026-04-28T00:00:00Z"
     },
+    "mde": {
+      "name": "MDE",
+      "id": "mde",
+      "description": "A Spec Kit extension that exposes a minimal model-driven engineering workflow with setup, next, and status commands.",
+      "author": "AI-MDE",
+      "version": "0.5.1",
+      "download_url": "https://github.com/AI-MDE/spec-kit-mde/archive/refs/tags/v0.5.1.zip",
+      "repository": "https://github.com/AI-MDE/spec-kit-mde",
+      "homepage": "https://github.com/AI-MDE/spec-kit-mde",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 4,
+        "hooks": 1
+      },
+      "tags": [
+        "mde",
+        "model-driven-engineering",
+        "workflow",
+        "process"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-08T00:00:00Z",
+      "updated_at": "2026-05-08T00:00:00Z"
+    },
     "memory-loader": {
       "name": "Memory Loader",
       "id": "memory-loader",
@@ -1278,34 +1543,35 @@
     "memory-md": {
       "name": "Memory MD",
       "id": "memory-md",
-      "description": "Repository-native durable memory for Spec Kit projects",
+      "description": "Spec Kit extension for repository-native Markdown memory that captures durable decisions, bugs, and project context",
       "author": "DyanGalih",
-      "version": "0.6.2",
-      "download_url": "https://github.com/DyanGalih/spec-kit-memory-hub/archive/refs/tags/v0.6.2.zip",
+      "version": "0.8.5",
+      "download_url": "https://github.com/DyanGalih/spec-kit-memory-hub/archive/refs/tags/v0.8.5.zip",
       "repository": "https://github.com/DyanGalih/spec-kit-memory-hub",
       "homepage": "https://github.com/DyanGalih/spec-kit-memory-hub",
       "documentation": "https://github.com/DyanGalih/spec-kit-memory-hub/blob/main/README.md",
-      "changelog": "https://github.com/DyanGalih/spec-kit-memory-hub/blob/main/docs/memory-workflow-v0.6.md",
+      "changelog": "https://github.com/DyanGalih/spec-kit-memory-hub/blob/main/CHANGELOG.md",
       "license": "MIT",
       "requires": {
-        "speckit_version": ">=0.6.0"
+        "speckit_version": ">=0.2.0"
       },
       "provides": {
-        "commands": 5,
-        "hooks": 0
+        "commands": 7,
+        "hooks": 2
       },
       "tags": [
         "memory",
         "workflow",
         "docs",
         "copilot",
-        "markdown"
+        "markdown",
+        "ai-context"
       ],
       "verified": false,
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-04-23T00:00:00Z",
-      "updated_at": "2026-04-23T00:00:00Z"
+      "updated_at": "2026-05-11T14:58:00Z"
     },
     "memorylint": {
       "name": "MemoryLint",
@@ -1339,6 +1605,56 @@
       "created_at": "2026-04-09T00:00:00Z",
       "updated_at": "2026-04-16T13:10:26Z"
     },
+    "multi-model-review": {
+      "name": "Multi-Model Review",
+      "id": "multi-model-review",
+      "description": "Cross-model Spec Kit handoffs for spec authoring, implementation routing, and review.",
+      "author": "formin",
+      "version": "0.1.0",
+      "download_url": "https://github.com/formin/multi-model-review/archive/refs/tags/v0.1.0.zip",
+      "repository": "https://github.com/formin/multi-model-review",
+      "homepage": "https://github.com/formin/multi-model-review",
+      "documentation": "https://github.com/formin/multi-model-review/blob/main/README.md",
+      "changelog": "https://github.com/formin/multi-model-review/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.2.0",
+        "tools": [
+          {
+            "name": "git",
+            "required": true
+          },
+          {
+            "name": "codex",
+            "required": false
+          },
+          {
+            "name": "gemini",
+            "required": false
+          },
+          {
+            "name": "claude",
+            "required": false
+          }
+        ]
+      },
+      "provides": {
+        "commands": 4,
+        "hooks": 0
+      },
+      "tags": [
+        "review",
+        "workflow",
+        "multi-model",
+        "spec-driven-development",
+        "code"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-04T02:51:52Z",
+      "updated_at": "2026-05-04T02:51:52Z"
+    },
     "onboard": {
       "name": "Onboard",
       "id": "onboard",
@@ -1597,12 +1913,12 @@
       "id": "ralph",
       "description": "Autonomous implementation loop using AI agent CLI.",
       "author": "Rubiss",
-      "version": "1.0.1",
-      "download_url": "https://github.com/Rubiss/spec-kit-ralph/archive/refs/tags/v1.0.1.zip",
-      "repository": "https://github.com/Rubiss/spec-kit-ralph",
-      "homepage": "https://github.com/Rubiss/spec-kit-ralph",
-      "documentation": "https://github.com/Rubiss/spec-kit-ralph/blob/main/README.md",
-      "changelog": "https://github.com/Rubiss/spec-kit-ralph/blob/main/CHANGELOG.md",
+      "version": "1.0.2",
+      "download_url": "https://github.com/Rubiss-Projects/spec-kit-ralph/archive/refs/tags/v1.0.2.zip",
+      "repository": "https://github.com/Rubiss-Projects/spec-kit-ralph",
+      "homepage": "https://github.com/Rubiss-Projects/spec-kit-ralph",
+      "documentation": "https://github.com/Rubiss-Projects/spec-kit-ralph/blob/main/README.md",
+      "changelog": "https://github.com/Rubiss-Projects/spec-kit-ralph/blob/main/CHANGELOG.md",
       "license": "MIT",
       "requires": {
         "speckit_version": ">=0.1.0",
@@ -1631,7 +1947,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-03-09T00:00:00Z",
-      "updated_at": "2026-04-12T19:00:00Z"
+      "updated_at": "2026-05-04T17:02:08Z"
     },
     "reconcile": {
       "name": "Reconcile Extension",
@@ -1893,6 +2209,38 @@
       "created_at": "2026-04-20T00:00:00Z",
       "updated_at": "2026-04-20T00:00:00Z"
     },
+    "schedule": {
+      "name": "Spec Kit Schedule — CP-SAT Agent Orchestrator",
+      "id": "schedule",
+      "description": "Optimal multi-agent task scheduling via CP-SAT solver with DAG precedence, hallucination-aware caps, file-conflict avoidance, stochastic durations, replanning, and interactive HTML output",
+      "author": "Julio César Franco Ardila",
+      "version": "0.6.2",
+      "download_url": "https://github.com/jfranc38/spec-kit-schedule/archive/refs/tags/v0.6.2.zip",
+      "repository": "https://github.com/jfranc38/spec-kit-schedule",
+      "homepage": "https://github.com/jfranc38/spec-kit-schedule",
+      "documentation": "https://github.com/jfranc38/spec-kit-schedule/blob/main/README.md",
+      "changelog": "https://github.com/jfranc38/spec-kit-schedule/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.4.0"
+      },
+      "provides": {
+        "commands": 5,
+        "hooks": 1
+      },
+      "tags": [
+        "scheduling",
+        "optimization",
+        "multi-agent",
+        "cp-sat",
+        "operations-research"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-06T22:35:00Z",
+      "updated_at": "2026-05-07T17:25:00Z"
+    },
     "scope": {
       "name": "Spec Scope",
       "id": "scope",
@@ -1931,8 +2279,8 @@
       "id": "security-review",
       "description": "Full-project secure-by-design security audits plus staged, branch/PR, plan, task, follow-up, and apply reviews",
       "author": "DyanGalih",
-      "version": "1.3.0",
-      "download_url": "https://github.com/DyanGalih/spec-kit-security-review/archive/refs/tags/v1.3.0.zip",
+      "version": "1.5.0",
+      "download_url": "https://github.com/DyanGalih/spec-kit-security-review/archive/refs/tags/v1.5.0.zip",
       "repository": "https://github.com/DyanGalih/spec-kit-security-review",
       "homepage": "https://github.com/DyanGalih/spec-kit-security-review",
       "documentation": "https://github.com/DyanGalih/spec-kit-security-review/blob/main/README.md",
@@ -1942,8 +2290,8 @@
         "speckit_version": ">=0.1.0"
       },
       "provides": {
-        "commands": 6,
-        "hooks": 0
+        "commands": 9,
+        "hooks": 3
       },
       "tags": [
         "security",
@@ -1956,7 +2304,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-04-03T03:24:03Z",
-      "updated_at": "2026-04-29T00:00:00Z"
+      "updated_at": "2026-05-11T14:58:00Z"
     },
     "sf": {
       "name": "SFSpeckit — Salesforce Spec-Driven Development",
@@ -2095,6 +2443,38 @@
       "created_at": "2026-04-20T00:00:00Z",
       "updated_at": "2026-04-21T00:00:00Z"
     },
+    "spec2cloud": {
+      "name": "Spec2Cloud",
+      "id": "spec2cloud",
+      "description": "Spec-driven workflow tuned for shipping to Azure: spec → plan → tasks → implement → deploy.",
+      "author": "Azure Samples",
+      "version": "1.1.0",
+      "download_url": "https://github.com/Azure-Samples/Spec2Cloud/releases/download/spec-kit-spec2cloud-v1.1.0/extension.zip",
+      "repository": "https://github.com/Azure-Samples/Spec2Cloud",
+      "homepage": "https://aka.ms/spec2cloud",
+      "documentation": "https://github.com/Azure-Samples/Spec2Cloud/blob/main/spec-kit/README.md",
+      "changelog": "https://github.com/Azure-Samples/Spec2Cloud/blob/main/spec-kit/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.4.0"
+      },
+      "provides": {
+        "commands": 2,
+        "hooks": 0
+      },
+      "tags": [
+        "spec2cloud",
+        "azure",
+        "cloud",
+        "deploy",
+        "workflow"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-04-30T00:00:00Z",
+      "updated_at": "2026-04-30T00:00:00Z"
+    },
     "speckit-utils": {
       "name": "SDD Utilities",
       "id": "speckit-utils",
@@ -2160,6 +2540,45 @@
       "created_at": "2026-04-10T16:00:00Z",
       "updated_at": "2026-04-10T16:00:00Z"
     },
+    "squad": {
+      "name": "Squad Bridge",
+      "id": "squad",
+      "description": "Bootstrap and synchronize a Squad agent team from your Spec Kit spec and tasks.",
+      "author": "jwill824",
+      "version": "1.1.0",
+      "download_url": "https://github.com/jwill824/spec-kit-squad/archive/refs/tags/v1.1.0.zip",
+      "repository": "https://github.com/jwill824/spec-kit-squad",
+      "homepage": "https://github.com/jwill824/spec-kit-squad",
+      "documentation": "https://github.com/jwill824/spec-kit-squad/blob/main/README.md",
+      "changelog": "https://github.com/jwill824/spec-kit-squad/blob/main/docs/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0",
+        "tools": [
+          {
+            "name": "@bradygaster/squad-cli",
+            "version": ">=0.1.0",
+            "required": true
+          }
+        ]
+      },
+      "provides": {
+        "commands": 4,
+        "hooks": 2
+      },
+      "tags": [
+        "multi-agent",
+        "agents",
+        "orchestration",
+        "process",
+        "integration"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-04-29T00:00:00Z",
+      "updated_at": "2026-04-29T00:00:00Z"
+    },
     "staff-review": {
       "name": "Staff Review Extension",
       "id": "staff-review",
@@ -2424,6 +2843,37 @@
       "created_at": "2026-04-25T00:00:00Z",
       "updated_at": "2026-04-25T00:00:00Z"
     },
+    "token-analyzer": {
+      "name": "Token Consumption Analyzer",
+      "id": "token-analyzer",
+      "description": "Captures, analyzes, and compares token consumption across SDD workflows",
+      "author": "Chris Roberts | coderandhiker",
+      "version": "0.1.0",
+      "download_url": "https://github.com/coderandhiker/spec-kit-token-analyzer/archive/refs/tags/v0.1.0.zip",
+      "repository": "https://github.com/coderandhiker/spec-kit-token-analyzer",
+      "homepage": "https://github.com/coderandhiker/spec-kit-token-analyzer",
+      "documentation": "https://github.com/coderandhiker/spec-kit-token-analyzer/blob/main/README.md",
+      "changelog": "https://github.com/coderandhiker/spec-kit-token-analyzer/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.2.0"
+      },
+      "provides": {
+        "commands": 3,
+        "hooks": 4
+      },
+      "tags": [
+        "tokens",
+        "measurement",
+        "optimization",
+        "analysis"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-01T00:00:00Z",
+      "updated_at": "2026-05-01T00:00:00Z"
+    },
     "v-model": {
       "name": "V-Model Extension Pack",
       "id": "v-model",

extensions/git/commands/speckit.git.feature.md

@@ -4,7 +4,7 @@ description: "Create a feature branch with sequential or timestamp numbering"
 
 # Create Feature Branch
 
-Create and switch to a new git feature branch for the given specification. This command handles **branch creation only** — the spec directory and files are created by the core `/speckit.specify` workflow.
+Create and switch to a new git feature branch for the given specification. This command handles **branch creation only** — the spec directory and files are created by the core `__SPECKIT_COMMAND_SPECIFY__` workflow.
 
 ## User Input
 

integrations/catalog.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-04-28T00:00:00Z",
+  "updated_at": "2026-04-29T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/integrations/catalog.json",
   "integrations": {
     "claude": {
@@ -210,6 +210,15 @@
       "repository": "https://github.com/github/spec-kit",
       "tags": ["cli", "skills"]
     },
+    "lingma": {
+      "id": "lingma",
+      "name": "Lingma",
+      "version": "1.0.0",
+      "description": "Lingma IDE skills-based integration",
+      "author": "spec-kit-core",
+      "repository": "https://github.com/github/spec-kit",
+      "tags": ["ide", "skills"]
+    },
     "pi": {
       "id": "pi",
       "name": "Pi Coding Agent",

newsletters/2026-April.md

@@ -0,0 +1,147 @@
+# Spec Kit - April 2026 Newsletter
+
+This edition covers Spec Kit activity in April 2026. Seventeen releases shipped (v0.4.4 through v0.8.3), delivering a full integration plugin architecture, a workflow engine, preset composition strategies, an integration catalog, and comprehensive documentation. The community extension catalog tripled from 26 to 83 entries, community presets grew from 2 to 12, and Spec Kit appeared on the Thoughtworks Technology Radar. A summary is in the table below, followed by details.
+
+| **Spec Kit Core (Apr 2026)** | **Community & Content** | **SDD Ecosystem & Next** |
+| --- | --- | --- |
+| Seventeen releases shipped with major features: integration plugin architecture, workflow engine, preset composition, integration catalog, bundled lean preset, documentation site, and academic citation support. Three new agents added (Forgecode, Goose, Devin for Terminal). The repo grew from ~82k to **92,038 stars**. [\[github.com\]](https://github.com/github/spec-kit/releases) | Thoughtworks Technology Radar placed Spec Kit in the "Assess" ring. Community catalog grew from 26 to **83 extensions** and from 2 to **12 presets**. 12 substantive external articles published. XB Software documented a real legacy project. Fabián Silva shipped the Caramelo VS Code extension. | Matt Rickard argued for "smaller specs, harder checks." Will Torber's three-framework comparison recommended OpenSpec for most teams. The "Spec Layer" debate emerged: specs as constraint surfaces for AI agents. Spec Kit leads in breadth and portability; competitors differentiate on drift detection and orchestration depth. |
+
+***
+
+> **Important:** April's release pace outran external coverage. Most analyses published during the month (Rickard on April 1, Thoughtworks Radar on April 15, XB Software on April 17, Torber on April 23) were evaluating versions that predated the workflow engine (v0.7.0), integration catalog (v0.7.2), preset composition (v0.8.0), and catalog discovery CLI (v0.8.3). The ceremony and flexibility concerns they raised are precisely what these features address — the lean preset, pluggable workflows, composable presets, and community extensions like Conduct, MAQA, and Fleet Orchestrator already deliver alternative workflows beyond the default SDD process. We look forward to seeing how upcoming reviews account for these capabilities.
+
+## Spec Kit Project Updates
+
+### Releases Overview
+
+**v0.4.4** (April 1) delivered the first stage of the **integration plugin architecture** — base classes, a manifest system, and a registry that replaced the hard-coded agent scaffolding. It also added the Product Forge, Superpowers Bridge, MAQA suite (7 extensions), Spec Kit Onboard, and Plan Review Gate to the community catalog, fixed Claude Code CLI detection for npm-local installs, and added `--allow-existing-branch` to `create-new-feature`. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.4.4)
+
+**v0.4.5** (April 2) completed the integration migration in five stages: standard markdown integrations for 19 agents, TOML integrations (Gemini, Tabnine), skills and generic integrations, and removal of the legacy scaffold path. It also installed Claude Code as native skills, added a `--dry-run` flag for `create-new-feature`, support for 4+ digit feature branch numbers, the Fix Findings extension, and five lifecycle extensions to the community catalog. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.4.5)
+
+**v0.5.0** (April 2) was a significant packaging change: **template zip bundles were removed from releases**, with the CLI itself now handling all scaffolding. This ensured CLI and templates stay in sync. It also introduced `DEVELOPMENT.md` for contributor onboarding. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.5.0)
+
+**v0.5.1** (April 8) was a large patch release. It added the **bundled Git extension** (stages 1 and 2) with hooks on all core commands and `GIT_BRANCH_NAME` override support, **Forgecode** agent support, and the `specify integration` subcommand for post-init integration management. Argument hints were added to Claude Code commands. Numerous community extensions joined the catalog (Confluence, Canon, Spec Diagram, Branch Convention, Spec Refine, FixIt, Optimize, Security Review) along with presets (explicit-task-dependencies, toc-navigation, VS Code Ask Questions). Bug fixes included pinning typer≥0.24.0/click≥8.2.1 to fix an import crash, BSD-portable sed escaping, Trae agent fix, TOML frontmatter stripping, and preventing ambiguous TOML closing quotes. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.5.1)
+
+**v0.6.0** (April 9) rewrote **AGENTS.md for the new integration architecture**, added the SpecKit Companion to Community Friends, and brought Bugfix Workflow, Worktree Isolation, and MemoryLint to the community catalog. A new multi-repo-branching preset arrived. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.6.0)
+
+**v0.6.1** (April 10) added the **bundled lean preset** with a minimal workflow command set — a lighter-weight alternative to the full SDD ceremony. It also migrated **Cursor** from `.cursor/commands` to `.cursor/skills` and added Brownfield Bootstrap, CI Guard, SpecTest, PR Bridge, TinySpec, and Status Report to the community catalog. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.6.1)
+
+**v0.6.2** (April 13) added **Goose AI agent** support (YAML-based recipe format), the GitHub Issues Integration extension, and the What-if Analysis extension. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.6.2)
+
+**v0.7.0** (April 14) delivered the **workflow engine with catalog system**, enabling pluggable, multi-step workflow definitions. It added SFSpeckit (Salesforce SDD), the Worktrees extension, optional single-segment branch prefix for gitflow compatibility, and the claude-ask-questions and fiction-book-writing presets. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.7.0)
+
+**v0.7.1** (April 15) deprecated the `--ai` flag in favor of `--integration` on `specify init`, added Windows to the CI test matrix, fixed Claude skill chaining for hook execution, merged TESTING.md into CONTRIBUTING.md, and added the Agent Assign and Architect Preview extensions. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.7.1)
+
+**v0.7.2** (April 16) delivered the **integration catalog** for discovery, versioning, and community distribution of agent integrations. It also produced a major **documentation overhaul**: reference pages for core commands, extensions, presets, workflows, and integrations were added to `docs/reference/`, and the README CLI section was simplified. The Issues extension and Catalog CI extension joined the community catalog. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.7.2)
+
+**v0.7.3** (April 17) replaced shell-based context updates with a **marker-based upsert** mechanism, eliminating accidental context file bloat. It added a **Community Friends page** to the docs site, the Spec Scope and Blueprint extensions, and a Claude Code/Copilot CLI plugin marketplace reference in the README. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.7.3)
+
+**v0.7.4** (April 21) added **CITATION.cff and .zenodo.json** for academic citation support. It introduced Ripple (side-effect detection), Spec Validate, Version Guard, Spec Reference Loader, and Memory Loader extensions. A fix stripped UTF-8 BOM from agent context files, and the Antigravity (agy) agent layout was migrated to `.agents/` with `--skills` deprecated. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.7.4)
+
+**v0.7.5** (April 22) added `specify self check` and `self upgrade` stubs, the **preset wrap strategy** (completing the composition trifecta alongside prepend and append), the Red Team adversarial review extension, the Wireframe extension, and a **directory traversal security fix** in command write paths. Skill placeholder resolution was expanded to all SKILL.md agents. Community content (walkthroughs and presets) was moved from the README to the docs site. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.7.5)
+
+**v0.8.0** (April 23) delivered **preset composition strategies** (prepend, append, wrap) for templates, commands, and scripts — enabling presets to layer content around existing artifacts. It also added Copilot `--integration-options="--skills"` for skills-based scaffolding, `pipx` as an alternative installation method, and the Memory MD extension. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.8.0)
+
+**v0.8.1** (April 24) fixed `/speckit.plan` on custom git branches via `.specify/feature.json`, migrated the **Mistral Vibe** integration to SkillsIntegration, added the **Screenwriting** and **Jira** presets, and resolved command reference formats per integration type (dot vs. hyphen notation). [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.8.1)
+
+**v0.8.2** (April 28) introduced **GITHUB_TOKEN/GH_TOKEN authentication** for private catalog and extension downloads, deprecated the `--no-git` flag (removal gated at v0.10.0), replaced all deprecated `--ai` references with `--integration` in documentation, and added MarkItDown Document Converter, Microsoft 365 Integration, Spec Orchestrator, and the Fiction Book Writing v1.7 preset with RAG (Chroma DB) offline semantic search. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.8.2)
+
+**v0.8.3** (April 29) closed the month with **catalog discovery CLI commands** (search, info, catalog list/add/remove), support for **Devin for Terminal** as a skills-based integration, a fix for the opencode command dispatch, and the OWASP LLM Threat Model, iSAQB Architecture Governance, and Work IQ extensions. A fix was also added to the upgrade hint to prevent users from accidentally installing a PyPI squat package. [\[github.com\]](https://github.com/github/spec-kit/releases/tag/v0.8.3)
+
+### Architecture & Infrastructure Highlights
+
+The most significant architectural change in April was the **integration plugin architecture** (v0.4.4–v0.4.5), which replaced hard-coded agent scaffolding with a registry of self-describing integration classes. Each agent is now a self-contained subpackage under `src/specify_cli/integrations/<key>/` with base classes for Markdown, TOML, YAML, and Skills formats. This six-stage migration touched all 28 supported agents and laid the groundwork for the integration catalog (v0.7.2) and community-distributed integrations.
+
+The **workflow engine** (v0.7.0) introduced a catalog-based system for pluggable, multi-step workflow definitions — moving beyond the fixed seven-step SDD sequence.
+
+**Preset composition strategies** (v0.7.5/v0.8.0) completed the preset system with prepend, append, and wrap modes. Presets can now layer content around existing templates, commands, and scripts rather than only replacing them.
+
+The **marker-based context upsert** (v0.7.3) replaced fragile shell-based sed operations for updating agent context files, eliminating a class of bugs around context bloat and encoding issues.
+
+**Template zip bundles were removed** (v0.5.0), coupling the CLI and templates into a single distributable artifact.
+
+### Bug Fixes and Security
+
+The most critical fix was **blocking directory traversal in command write paths** (#2229, v0.7.5), which prevented a potential path traversal vulnerability in the CommandRegistrar. Other security-adjacent fixes included hardening against a **PyPI squat package** in upgrade hints (v0.8.3) and adding **GITHUB_TOKEN authentication** for private catalog downloads (v0.8.2).
+
+Notable bug fixes: typer/click import crash (v0.5.1), BSD-portable sed escaping (v0.5.1), UTF-8 BOM stripping from context files (v0.7.4), CRLF warning suppression in PowerShell auto-commit (v0.7.3), Claude skill chaining for hooks (v0.7.1), TOML ambiguous closing quotes (v0.5.1), and custom branch support for `/speckit.plan` (v0.8.1). [\[github.com\]](https://github.com/github/spec-kit/releases)
+
+### The Extension & Preset Ecosystem
+
+The community extension catalog **tripled** during April, growing from 26 to **83 entries**. 59 new extensions were added and 2 were removed (Cognitive Squad and Understanding, whose repositories were no longer available). Community presets grew from 2 to **12 entries**, with 10 new presets added.
+
+Notable new extensions by category:
+
+- **Project management**: GitHub Issues Integration (Fatima367, aaronrsun), Spec Orchestrator (Quratulain-bilal), Agent Assign (xuyang), Status Report (Open-Agent-Tools)
+- **Quality & security**: Red Team adversarial review (Ash Brener), Security Review (DyanGalih), Ripple side-effect detection (chordpli), Spec Validate (Ahmed Eltayeb), CI Guard (Quratulain-bilal), OWASP LLM Threat Model (NaviaSamal)
+- **Multi-agent & orchestration**: MAQA suite with 7 extensions covering multi-agent QA, Jira, Azure DevOps, GitHub Projects, Linear, and Trello integrations (GenieRobot), Product Forge (VaiYav)
+- **Spec lifecycle**: Spec Refine (Quratulain-bilal), Bugfix Workflow (Quratulain-bilal), Fix Findings (Quratulain-bilal), Brownfield Bootstrap (Quratulain-bilal), TinySpec (Quratulain-bilal)
+- **Developer experience**: Blueprint code review (chordpli), Confluence (aaronrsun), MarkItDown Document Converter (BenBtg), Microsoft 365 Integration (BenBtg), Memory MD (DyanGalih), Memory Loader (KevinBrown5280), MemoryLint (RbBtSn0w)
+- **Domain-specific**: SFSpeckit for Salesforce (Sumanth Yanamala), iSAQB Architecture Governance preset (Thorsten Hindermann), Canon baseline-driven workflows (Maxim Stupakov)
+- **Creative**: Fiction Book Writing preset v1.7 with RAG/Chroma DB support (Andreas Daumann), Screenwriting preset (Andreas Daumann)
+
+Notable contributor **Quratulain-bilal** contributed 15 extensions during the month, spanning spec lifecycle, workflow management, and CI/CD integration. **GenieRobot** contributed the 7-extension MAQA suite. **BenBtg** contributed both MarkItDown and Microsoft 365 integrations. [\[github.com\]](https://github.com/github/spec-kit/releases)
+
+### Documentation Overhaul
+
+April saw a comprehensive documentation effort. Reference pages for **core commands, extensions, presets, workflows, and integrations** were created under `docs/reference/`. Community content — **walkthroughs, presets, and a Community Friends page** — was moved from the README to `docs/community/`, reducing README length while improving discoverability. The deprecated `--ai` flag references were replaced with `--integration` across all documentation. TESTING.md was merged into CONTRIBUTING.md, and `DEVELOPMENT.md` was introduced for contributor onboarding. [\[github.com\]](https://github.com/github/spec-kit/releases)
+
+## Community & Content
+
+### Thoughtworks Technology Radar
+
+On **April 15**, the **Thoughtworks Technology Radar Volume 34** placed GitHub Spec Kit in the **"Assess" ring** under Languages & Frameworks. The blip noted that teams report value in brownfield projects, that the constitution captures project scope and architecture, but flagged potential **instruction bloat, context rot, and verbose markdown output** as concerns to watch. This is the first appearance of any SDD-specific tool on the Radar. [\[thoughtworks.com\]](https://www.thoughtworks.com/radar/languages-and-frameworks/github-spec-kit)
+
+### Developer Articles and Blog Posts
+
+April produced 12 substantive external articles (plus one excluded as AI-generated SEO spam).
+
+**Matt Rickard** published *"The Spec Layer: Why Spec-Driven Development (SDD) Works"* on April 1. His thesis: specs reduce execution freedom for AI agents, functioning as constraint surfaces. He compared Spec Kit, Kiro, OpenSpec, Tessl, Intent, and Symphony, and advocated for **"smaller specs, harder checks, less guessing."** [\[blog.matt-rickard.com\]](https://blog.matt-rickard.com/p/the-spec-layer)
+
+**Fabián Silva** published *"I Built a Visual Spec-Driven Development Extension for VS Code That Works With Any LLM"* on April 3 on DEV Community. His **Caramelo** VS Code extension adds a visual UI, approval gates, Jira integration, and multi-LLM support on top of Spec Kit's workflow, reading and writing the standard `specs/` directory. [\[dev.to\]](https://dev.to/fabian_silva_/i-built-a-visual-spec-driven-development-extension-for-vs-code-that-works-with-any-llm-36ok)
+
+**James M** published *"GitHub Spec Kit in 2026: SDD Goes Mainstream"* on April 4, calling the transition "from framework to platform" and highlighting Claude Code native skills, multi-agent support, and the massive ecosystem growth. [\[jamesm.blog\]](https://jamesm.blog/ai/github-spec-kit-2026-update/)
+
+**Peter Saktor** published a detailed tutorial on DEV Community on April 6: *"GitHub Spec-Kit: From Vibe Coding to Spec-Driven Development,"* walking through a full 7-step SDD workflow refactoring an Azure Container App with 33 tasks across 6 phases. [\[dev.to\]](https://dev.to/petersaktor/github-spec-kit-from-vibe-coding-to-spec-driven-development-1pgd)
+
+**Codexplorer** published *"Spec Kit: GitHub's Answer to 'The AI Built the Wrong Thing Again'"* on Medium (April 11), framing Spec Kit as flipping the spec-code relationship, with Go code examples covering the seven slash commands. [\[medium.com\]](https://codexplorer.medium.com/spec-kit-githubs-answer-to-the-ai-built-the-wrong-thing-again-22f122f142fb)
+
+**XB Software** published *"Spec Kit on a Real Project: Implementation Experience in Large Legacy Code"* on April 17 — a field report from applying SDD to legacy systems. A week-long task was completed in half the time. The AI surfaced hidden requirements gaps. They noted API integration weakness, that SDD is overkill for small tasks, and that an experienced reviewer is still essential. [\[xbsoftware.com\]](https://xbsoftware.com/blog/ai-in-legacy-systems-spec-driven-development/)
+
+**What IT Is** published *"Perspectives in Spec Driven Development"* on April 21, surveying the SDD landscape (Spec Kit, Kiro, Tessl) and calling Spec Kit "a good entry point." [\[theitsolutionist.com\]](https://theitsolutionist.com/2026/04/21/perspectives-in-spec-driven-development/)
+
+**Will Torber** published *"Spec Kit vs BMAD vs OpenSpec: Choosing an SDD Framework in 2026"* on DEV Community on April 23. He recommended Spec Kit for greenfield but flagged brownfield friction and the branch-per-spec limitation, ultimately **recommending OpenSpec for most teams**. [\[dev.to\]](https://dev.to/willtorber/spec-kit-vs-bmad-vs-openspec-choosing-an-sdd-framework-in-2026-d3j)
+
+**Truong Phung** published *"Spec Kit vs. Superpowers: A Comprehensive Comparison & Practical Guide to Combining Both"* on DEV Community on April 25 — an 11-section comparison proposing a hybrid workflow: "Spec Kit plans WHAT, Superpowers controls HOW," with a step-by-step playbook. [\[dev.to\]](https://dev.to/truongpx396/spec-kit-vs-superpowers-a-comprehensive-comparison-practical-guide-to-combining-both-52jj)
+
+**Markus Wondrak** published *"Re-evaluating GitHub's Spec Kit: Structured SDLC Automation"* on LinkedIn on April 26, examining Spec Kit as a structured SDLC automation approach requiring human review at phase boundaries. [\[linkedin.com\]](https://www.linkedin.com/pulse/re-evaluating-githubs-spec-kit-structured-sdlc-markus-wondrak-eewqf/)
+
+**FintechExtra** published a factual release-notes summary of v0.8.2 on April 28, highlighting authenticated catalog downloads, the UTF-8 manifest fix, and the Chroma DB semantic search in the fiction writing preset. [\[fintechextra.com\]](https://www.fintechextra.com/news/github-spec-kit-v082-expands-catalog-support-and-tightens-cli-behavior-331)
+
+### Community Friends and Tools
+
+The **SpecKit Companion** VS Code extension was added to the Community Friends section (v0.6.0). A community-maintained plugin for **Claude Code and GitHub Copilot CLI** that installs Spec Kit skills via the plugin marketplace was referenced in the README (v0.7.3). Fabián Silva's **Caramelo** VS Code extension demonstrated a visual UI approach to SDD. [\[github.com\]](https://github.com/github/spec-kit)
+
+## SDD Ecosystem & Industry Trends
+
+### The "Spec Layer" Debate
+
+Matt Rickard's "The Spec Layer" essay established a new framing for SDD: specifications as **constraint surfaces** that reduce execution freedom for AI agents. His comparison of six SDD tools argued for smaller, more focused specs with harder verification checks — a departure from comprehensive specification documents. This framing resonated across the community, with the Thoughtworks Radar entry and multiple comparison articles echoing the tension between spec depth and practical overhead.
+
+### Competitive Landscape
+
+**Will Torber's** three-framework comparison (Spec Kit, BMAD, OpenSpec) recommended **OpenSpec for most teams**, citing lower ceremony and better brownfield support. **Truong Phung** proposed combining Spec Kit with **Superpowers** (Jesse Vincent) for a "plan WHAT + control HOW" hybrid. These comparisons reflected a maturing market where practitioners combine tools rather than picking one.
+
+The **Thoughtworks Radar** placement validated SDD as a category worth tracking but flagged instruction bloat and context rot as open concerns — the same issues the Augment Code comparison raised in March. XB Software's field report confirmed these in practice: SDD adds value for complex legacy work but creates unnecessary overhead for small tasks.
+
+Spec Kit continued to lead in **GitHub popularity** (92k stars) and **agent breadth** (29 integrations). The market continued to differentiate along several axes: Spec Kit on portability and ecosystem breadth, Intent on living specs and drift detection, BMAD-METHOD on multi-agent orchestration, and OpenSpec on simplicity. [\[dev.to\]](https://dev.to/willtorber/spec-kit-vs-bmad-vs-openspec-choosing-an-sdd-framework-in-2026-d3j) [\[thoughtworks.com\]](https://www.thoughtworks.com/radar/languages-and-frameworks/github-spec-kit)
+
+## Roadmap
+
+Areas under discussion or in progress for future development:
+
+- **Spec lifecycle management** — context rot and spec drift remained the most cited concern across articles (Thoughtworks Radar, XB Software, Will Torber). The marker-based upsert (v0.7.3) addressed context file drift; spec-level drift detection remains an open area. The Reconcile and Archive extensions are community steps toward this. [\[thoughtworks.com\]](https://www.thoughtworks.com/radar/languages-and-frameworks/github-spec-kit)
+- **Workflow customization** — the workflow engine (v0.7.0) and preset composition strategies (v0.8.0) provide the foundation. Community presets for fiction writing, screenwriting, Jira tracking, and architecture governance demonstrate the breadth of possible workflows beyond standard SDD. [\[github.com\]](https://github.com/github/spec-kit/releases)
+- **Catalog discovery and distribution** — the integration catalog (v0.7.2) and catalog discovery CLI (v0.8.3) bring `specify` closer to a package-manager experience for extensions, presets, and integrations. Private catalog authentication (v0.8.2) supports enterprise distribution. [\[github.com\]](https://github.com/github/spec-kit/releases)
+- **Experience simplification** — the bundled lean preset (v0.6.1), `specify self check` (v0.7.5), and the deprecation of `--ai` in favor of `--integration` (v0.7.1) reflect ongoing work to reduce ceremony and improve the onboarding experience. Multiple external articles (Torber, XB Software) noted SDD overhead as a barrier. [\[dev.to\]](https://dev.to/willtorber/spec-kit-vs-bmad-vs-openspec-choosing-an-sdd-framework-in-2026-d3j)
+- **Cross-platform and enterprise** — Windows CI (v0.7.1), GITHUB_TOKEN authentication (v0.8.2), Salesforce-specific extensions, and the iSAQB architecture governance preset indicate growing enterprise adoption. [\[github.com\]](https://github.com/github/spec-kit)

presets/README.md

@@ -98,7 +98,7 @@ Multiple composing presets chain recursively. For example, a security preset wit
 Presets are discovered through catalogs. By default, Spec Kit uses the official and community catalogs:
 
 > [!NOTE]
-> Community presets are independently created and maintained by their respective authors. GitHub and the Spec Kit maintainers may review pull requests that add entries to the community catalog for formatting, catalog structure, or policy compliance, but they do **not review, audit, endorse, or support the preset code itself**. Review preset source code before installation and use at your own discretion.
+> Community presets are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the preset code itself**. Review preset source code before installation and use at your own discretion.
 
 ```bash
 # List active catalogs

presets/catalog.community.json

@@ -1,8 +1,64 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-04-27T00:00:00Z",
+  "updated_at": "2026-05-05T10:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json",
   "presets": {
+    "a11y-governance": {
+      "name": "A11Y Governance",
+      "id": "a11y-governance",
+      "version": "0.2.0",
+      "description": "Adds accessibility, bilingual DE/EN delivery, CEFR-B2 readability, and inclusive-content governance to Spec Kit.",
+      "author": "Thorsten Hindermann",
+      "repository": "https://github.com/hindermath/spec-kit-preset-a11y-governance",
+      "download_url": "https://github.com/hindermath/spec-kit-preset-a11y-governance/archive/refs/tags/v0.2.0.zip",
+      "homepage": "https://github.com/hindermath/spec-kit-preset-a11y-governance",
+      "documentation": "https://github.com/hindermath/spec-kit-preset-a11y-governance/blob/main/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.0"
+      },
+      "provides": {
+        "templates": 9,
+        "commands": 3
+      },
+      "tags": [
+        "a11y",
+        "accessibility",
+        "bilingual",
+        "wcag",
+        "inclusion"
+      ],
+      "created_at": "2026-04-27T00:00:00Z",
+      "updated_at": "2026-04-27T00:00:00Z"
+    },
+    "agent-parity-governance": {
+      "name": "Agent Parity Governance",
+      "id": "agent-parity-governance",
+      "version": "0.1.0",
+      "description": "Keeps shared AI-agent guidance aligned across a project-defined set of agent instruction surfaces.",
+      "author": "Thorsten Hindermann",
+      "repository": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance",
+      "download_url": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance/archive/refs/tags/v0.1.0.zip",
+      "homepage": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance",
+      "documentation": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance/blob/main/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.0"
+      },
+      "provides": {
+        "templates": 6,
+        "commands": 3
+      },
+      "tags": [
+        "agents",
+        "governance",
+        "parity",
+        "agent-guidance",
+        "multi-agent"
+      ],
+      "created_at": "2026-04-27T00:00:00Z",
+      "updated_at": "2026-04-27T00:00:00Z"
+    },
     "aide-in-place": {
       "name": "AIDE In-Place Migration",
       "id": "aide-in-place",
@@ -16,7 +72,9 @@
       "license": "MIT",
       "requires": {
         "speckit_version": ">=0.2.0",
-        "extensions": ["aide"]
+        "extensions": [
+          "aide"
+        ]
       },
       "provides": {
         "templates": 2,
@@ -29,6 +87,34 @@
         "aide"
       ]
     },
+    "architecture-governance": {
+      "name": "Architecture Governance",
+      "id": "architecture-governance",
+      "version": "0.2.0",
+      "description": "Adds secure architecture governance, threat modeling, STRIDE/CAPEC, Zero Trust, S-ADRs, and OWASP SAMM to Spec Kit.",
+      "author": "Thorsten Hindermann",
+      "repository": "https://github.com/hindermath/spec-kit-preset-architecture-governance",
+      "download_url": "https://github.com/hindermath/spec-kit-preset-architecture-governance/archive/refs/tags/v0.2.0.zip",
+      "homepage": "https://github.com/hindermath/spec-kit-preset-architecture-governance",
+      "documentation": "https://github.com/hindermath/spec-kit-preset-architecture-governance/blob/main/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.0"
+      },
+      "provides": {
+        "templates": 11,
+        "commands": 3
+      },
+      "tags": [
+        "architecture",
+        "governance",
+        "threat-modeling",
+        "stride",
+        "zero-trust"
+      ],
+      "created_at": "2026-04-27T00:00:00Z",
+      "updated_at": "2026-04-27T00:00:00Z"
+    },
     "canon-core": {
       "name": "Canon Core",
       "id": "canon-core",
@@ -80,6 +166,34 @@
       "created_at": "2026-04-13T00:00:00Z",
       "updated_at": "2026-04-13T00:00:00Z"
     },
+    "cross-platform-governance": {
+      "name": "Cross-Platform Governance",
+      "id": "cross-platform-governance",
+      "version": "0.1.0",
+      "description": "Adds Bash and PowerShell parity, dry-run/WhatIf parity, man-page expectations, and Verb-Noun Cmdlet discipline.",
+      "author": "Thorsten Hindermann",
+      "repository": "https://github.com/hindermath/spec-kit-preset-cross-platform-governance",
+      "download_url": "https://github.com/hindermath/spec-kit-preset-cross-platform-governance/archive/refs/tags/v0.1.0.zip",
+      "homepage": "https://github.com/hindermath/spec-kit-preset-cross-platform-governance",
+      "documentation": "https://github.com/hindermath/spec-kit-preset-cross-platform-governance/blob/main/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.0"
+      },
+      "provides": {
+        "templates": 8,
+        "commands": 3
+      },
+      "tags": [
+        "cross-platform",
+        "bash",
+        "powershell",
+        "man-page",
+        "cmdlet"
+      ],
+      "created_at": "2026-04-27T00:00:00Z",
+      "updated_at": "2026-04-27T00:00:00Z"
+    },
     "explicit-task-dependencies": {
       "name": "Explicit Task Dependencies",
       "id": "explicit-task-dependencies",
@@ -142,6 +256,43 @@
       "created_at": "2026-04-09T08:00:00Z",
       "updated_at": "2026-04-27T08:00:00Z"
     },
+    "game-narrative-writing": {
+      "name": "Game Narrative Writing",
+      "id": "game-narrative-writing",
+      "version": "1.0.0",
+      "description": "Spec-Driven Development for interactive game-narrative pre-production in video games. Authors write in a portable generic format, Twine/Sugarcube (.twee) or Ink (.ink). Covers choice-IF, visual novels, and branching dialogue. Supports Tier 1 mechanic hooks (flag, counter, inventory, timer, trust, currency, npc_state, ending_condition), multi-ending design, series carry-over variable registry, and NPC-focused character architecture.",
+      "author": "Andreas Daumann",
+      "repository": "https://github.com/adaumann/speckit-preset-game-narrative-writing",
+      "download_url": "https://github.com/adaumann/speckit-preset-game-narrative-writing/archive/refs/tags/v1.0.0.zip",
+      "homepage": "https://github.com/adaumann/speckit-preset-game-narrative-writing",
+      "documentation": "https://github.com/adaumann/speckit-preset-game-narrative-writing/blob/main/game-narrative-writing/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.5.0"
+      },
+      "provides": {
+        "templates": 22,
+        "commands": 36,
+        "scripts": 2
+      },
+      "tags": [
+        "game-writing",
+        "interactive-fiction",
+        "twine",
+        "ink",
+        "renpy",
+        "point-and-click",
+        "branching-narrative",
+        "choice-if",
+        "visual-novel",
+        "mechanic-hooks",
+        "game-narrative",
+        "export",
+        "series"
+      ],
+      "created_at": "2026-05-05T08:00:00Z",
+      "updated_at": "2026-05-05T08:00:00Z"
+    },
     "isaqb-architecture-governance": {
       "name": "iSAQB Architecture Governance",
       "id": "isaqb-architecture-governance",
@@ -197,6 +348,37 @@
       "created_at": "2026-04-15T00:00:00Z",
       "updated_at": "2026-04-15T00:00:00Z"
     },
+    "mde": {
+      "name": "Model Driven Engineering",
+      "id": "mde",
+      "version": "0.5.1",
+      "description": "Focuses on streamlined commands, app repository support, cross-spec support, and capability-aware project memory for model-driven engineering workflows.",
+      "author": "Ralph Hanna",
+      "repository": "https://github.com/AI-MDE/spec-kit-preset-mde",
+      "download_url": "https://github.com/AI-MDE/spec-kit-preset-mde/archive/refs/tags/v0.5.1.zip",
+      "homepage": "https://github.com/AI-MDE/spec-kit-preset-mde",
+      "documentation": "https://github.com/AI-MDE/spec-kit-preset-mde/blob/main/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0",
+        "extensions": [
+          "mde"
+        ]
+      },
+      "provides": {
+        "templates": 6,
+        "commands": 11
+      },
+      "tags": [
+        "model-driven-engineering",
+        "software-lifecycle",
+        "business-analysis",
+        "business-application",
+        "multi-layered-architecture"
+      ],
+      "created_at": "2026-05-08T00:00:00Z",
+      "updated_at": "2026-05-08T00:00:00Z"
+    },
     "multi-repo-branching": {
       "name": "Multi-Repo Branching",
       "id": "multi-repo-branching",
@@ -287,6 +469,61 @@
       "created_at": "2026-04-23T08:00:00Z",
       "updated_at": "2026-04-23T08:00:00Z"
     },
+    "security-governance": {
+      "name": "Security Governance",
+      "id": "security-governance",
+      "version": "0.2.0",
+      "description": "Adds secure development governance, MSL preference, ASVS verification, supply-chain transparency, and EU CRA awareness.",
+      "author": "Thorsten Hindermann",
+      "repository": "https://github.com/hindermath/spec-kit-preset-security-governance",
+      "download_url": "https://github.com/hindermath/spec-kit-preset-security-governance/archive/refs/tags/v0.2.0.zip",
+      "homepage": "https://github.com/hindermath/spec-kit-preset-security-governance",
+      "documentation": "https://github.com/hindermath/spec-kit-preset-security-governance/blob/main/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.0"
+      },
+      "provides": {
+        "templates": 12,
+        "commands": 3
+      },
+      "tags": [
+        "security",
+        "governance",
+        "msl",
+        "asvs",
+        "supply-chain"
+      ],
+      "created_at": "2026-04-27T00:00:00Z",
+      "updated_at": "2026-04-27T00:00:00Z"
+    },
+    "spec2cloud": {
+      "name": "Spec2Cloud",
+      "id": "spec2cloud",
+      "version": "1.1.0",
+      "description": "Spec-driven workflow tuned for shipping to Azure: spec → plan → tasks → implement → deploy.",
+      "author": "Azure Samples",
+      "repository": "https://github.com/Azure-Samples/Spec2Cloud",
+      "download_url": "https://github.com/Azure-Samples/Spec2Cloud/releases/download/spec-kit-spec2cloud-v1.1.0/preset.zip",
+      "homepage": "https://aka.ms/spec2cloud",
+      "documentation": "https://github.com/Azure-Samples/Spec2Cloud/blob/main/spec-kit/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "templates": 5,
+        "commands": 8
+      },
+      "tags": [
+        "azure",
+        "spec2cloud",
+        "workflow",
+        "deployment"
+      ],
+      "created_at": "2026-04-30T00:00:00Z",
+      "updated_at": "2026-04-30T00:00:00Z"
+    }, 
     "toc-navigation": {
       "name": "Table of Contents Navigation",
       "id": "toc-navigation",

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.8.3"
+version = "0.8.9"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [

scripts/bash/setup-tasks.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json) JSON_MODE=true ;;
+        --help|-h)
+            echo "Usage: $0 [--json]"
+            echo "  --json    Output results in JSON format"
+            echo "  --help    Show this help message"
+            exit 0
+            ;;
+        *) echo "ERROR: Unknown option '$arg'" >&2; exit 1 ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths
+_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+eval "$_paths_output"
+unset _paths_output
+
+# Validate branch
+# If feature.json pins an existing feature directory, branch naming is not required.
+if ! feature_json_matches_feature_dir "$REPO_ROOT" "$FEATURE_DIR"; then
+    check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+fi
+
+if [[ ! -f "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.plan first to create the implementation plan." >&2
+    exit 1
+fi
+
+if [[ ! -f "$FEATURE_SPEC" ]]; then
+    echo "ERROR: spec.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.specify first to create the feature structure." >&2
+    exit 1
+fi
+
+# Build available docs list
+docs=()
+[[ -f "$RESEARCH" ]] && docs+=("research.md")
+[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
+if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+    docs+=("contracts/")
+fi
+[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
+
+# Resolve tasks template through override stack
+TASKS_TEMPLATE=$(resolve_template "tasks-template" "$REPO_ROOT") || true
+if [[ -z "$TASKS_TEMPLATE" ]] || [[ ! -f "$TASKS_TEMPLATE" ]]; then
+    echo "ERROR: Could not resolve required tasks-template from the template override stack for $REPO_ROOT" >&2
+    echo "Template 'tasks-template' was not found in any supported location (overrides, presets, extensions, or shared core). Add an override at .specify/templates/overrides/tasks-template.md, or run 'specify init' / reinstall shared infra to restore the core .specify/templates/tasks-template.md template." >&2
+    exit 1
+fi
+
+# Output results
+if $JSON_MODE; then
+    if has_jq; then
+        if [[ ${#docs[@]} -eq 0 ]]; then
+            json_docs="[]"
+        else
+            json_docs=$(printf '%s\n' "${docs[@]}" | jq -R . | jq -s .)
+        fi
+        jq -cn \
+            --arg feature_dir "$FEATURE_DIR" \
+            --argjson docs "$json_docs" \
+            --arg tasks_template "${TASKS_TEMPLATE:-}" \
+            '{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs,TASKS_TEMPLATE:$tasks_template}'
+    else
+        if [[ ${#docs[@]} -eq 0 ]]; then
+            json_docs="[]"
+        else
+            json_docs=$(for d in "${docs[@]}"; do printf '"%s",' "$(json_escape "$d")"; done)
+            json_docs="[${json_docs%,}]"
+        fi
+        printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s,"TASKS_TEMPLATE":"%s"}\n' \
+            "$(json_escape "$FEATURE_DIR")" "$json_docs" "$(json_escape "${TASKS_TEMPLATE:-}")"
+    fi
+else
+    echo "FEATURE_DIR: $FEATURE_DIR"
+    echo "TASKS_TEMPLATE: ${TASKS_TEMPLATE:-not found}"
+    echo "AVAILABLE_DOCS:"
+    check_file "$RESEARCH" "research.md"
+    check_file "$DATA_MODEL" "data-model.md"
+    check_dir "$CONTRACTS_DIR" "contracts/"
+    check_file "$QUICKSTART" "quickstart.md"
+fi

scripts/powershell/setup-tasks.ps1

@@ -0,0 +1,74 @@
+#!/usr/bin/env pwsh
+
+[CmdletBinding()]
+param(
+    [switch]$Json,
+    [switch]$Help
+)
+
+$ErrorActionPreference = 'Stop'
+
+if ($Help) {
+    Write-Output "Usage: setup-tasks.ps1 [-Json] [-Help]"
+    exit 0
+}
+
+# Source common functions
+. "$PSScriptRoot/common.ps1"
+
+# Get feature paths and validate branch
+$paths = Get-FeaturePathsEnv
+
+# If feature.json pins an existing feature directory, branch naming is not required.
+if (-not (Test-FeatureJsonMatchesFeatureDir -RepoRoot $paths.REPO_ROOT -ActiveFeatureDir $paths.FEATURE_DIR)) {
+    if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit $paths.HAS_GIT)) {
+        exit 1
+    }
+}
+
+if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) {
+    [Console]::Error.WriteLine("ERROR: plan.md not found in $($paths.FEATURE_DIR)")
+    [Console]::Error.WriteLine("Run /speckit.plan first to create the implementation plan.")
+    exit 1
+}
+
+if (-not (Test-Path $paths.FEATURE_SPEC -PathType Leaf)) {
+    [Console]::Error.WriteLine("ERROR: spec.md not found in $($paths.FEATURE_DIR)")
+    [Console]::Error.WriteLine("Run /speckit.specify first to create the feature structure.")
+    exit 1
+}
+
+# Build available docs list
+$docs = @()
+if (Test-Path $paths.RESEARCH) { $docs += 'research.md' }
+if (Test-Path $paths.DATA_MODEL) { $docs += 'data-model.md' }
+if ((Test-Path $paths.CONTRACTS_DIR) -and (Get-ChildItem -Path $paths.CONTRACTS_DIR -ErrorAction SilentlyContinue | Select-Object -First 1)) {
+    $docs += 'contracts/'
+}
+if (Test-Path $paths.QUICKSTART) { $docs += 'quickstart.md' }
+
+# Resolve tasks template through override stack
+$tasksTemplate = Resolve-Template -TemplateName 'tasks-template' -RepoRoot $paths.REPO_ROOT
+if (-not $tasksTemplate -or -not (Test-Path -LiteralPath $tasksTemplate -PathType Leaf)) {
+    $expectedCoreTemplate = Join-Path $paths.REPO_ROOT '.specify/templates/tasks-template.md'
+    [Console]::Error.WriteLine("ERROR: Tasks template not found for repository root: $($paths.REPO_ROOT)`nTemplate resolution order: overrides -> presets -> extensions -> core.`nExpected shared/core template location: $expectedCoreTemplate`nTo continue, verify whether 'tasks-template.md' is available in '.specify/templates/overrides/', preset templates, extension templates, or restore the shared/core templates (for example by re-running 'specify init') so that '.specify/templates/tasks-template.md' exists.")
+    exit 1
+}
+$tasksTemplate = (Resolve-Path -LiteralPath $tasksTemplate).Path
+
+# Output results
+if ($Json) {
+    [PSCustomObject]@{
+        FEATURE_DIR    = $paths.FEATURE_DIR
+        AVAILABLE_DOCS = $docs
+        TASKS_TEMPLATE = $tasksTemplate
+    } | ConvertTo-Json -Compress
+} else {
+    Write-Output "FEATURE_DIR: $($paths.FEATURE_DIR)"
+    Write-Output "TASKS_TEMPLATE: $(if ($tasksTemplate) { $tasksTemplate } else { 'not found' })"
+    Write-Output "AVAILABLE_DOCS:"
+    Test-FileExists -Path $paths.RESEARCH -Description 'research.md' | Out-Null
+    Test-FileExists -Path $paths.DATA_MODEL -Description 'data-model.md' | Out-Null
+    Test-DirHasFiles -Path $paths.CONTRACTS_DIR -Description 'contracts/' | Out-Null
+    Test-FileExists -Path $paths.QUICKSTART -Description 'quickstart.md' | Out-Null
+}

src/specify_cli/_github_http.py

@@ -8,8 +8,8 @@ third-party hosts on redirects.
 
 import os
 import urllib.request
-from urllib.parse import urlparse
 from typing import Dict
+from urllib.parse import urlparse
 
 # GitHub-owned hostnames that should receive the Authorization header.
 # Includes codeload.github.com because GitHub archive URL downloads
@@ -30,12 +30,25 @@ def build_github_request(url: str) -> urllib.request.Request:
     ``Authorization: Bearer <value>`` header when the target hostname is one
     of the known GitHub-owned domains. Non-GitHub URLs are returned as plain
     requests so credentials are never leaked to third-party hosts.
+
+    Raises:
+        ValueError: If ``url`` is empty or whitespace-only.
+        ValueError: If ``url`` does not use the ``http`` or ``https`` scheme.
+        ValueError: If ``url`` does not include a hostname.
     """
     headers: Dict[str, str] = {}
+    url = url.strip()
+    if not url:
+        raise ValueError("url must not be empty")
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"}:
+        raise ValueError(f"url must start with http:// or https://, got: {url!r}")
+    if not parsed.hostname:
+        raise ValueError(f"url must include a hostname, got: {url!r}")
     github_token = (os.environ.get("GITHUB_TOKEN") or "").strip()
     gh_token = (os.environ.get("GH_TOKEN") or "").strip()
     token = github_token or gh_token or None
-    hostname = (urlparse(url).hostname or "").lower()
+    hostname = parsed.hostname.lower()
     if token and hostname in GITHUB_HOSTS:
         headers["Authorization"] = f"Bearer {token}"
     return urllib.request.Request(url, headers=headers)

src/specify_cli/agents.py

@@ -7,12 +7,12 @@ command files into agent-specific directories in the correct format.
 """
 
 import os
-from pathlib import Path
-from typing import Dict, List, Any, Optional
-
 import platform
 import re
 from copy import deepcopy
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
 import yaml
 
 
@@ -25,7 +25,16 @@ def _build_agent_configs() -> dict[str, Any]:
         if key == "generic":
             continue
         if integration.registrar_config:
-            configs[key] = dict(integration.registrar_config)
+            config = dict(integration.registrar_config)
+            # Propagate invoke_separator from the integration class when the
+            # registrar_config dict doesn't already declare it explicitly.
+            # SkillsIntegration subclasses (claude, codex, …) set
+            # invoke_separator="-" as a class attribute but omit it from
+            # registrar_config, so without this they would fall back to "."
+            # when register_commands() resolves __SPECKIT_COMMAND_*__ tokens.
+            if "invoke_separator" not in config:
+                config["invoke_separator"] = integration.invoke_separator
+            configs[key] = config
     return configs
 
 
@@ -419,9 +428,7 @@ class CommandRegistrar:
         normalized = Path(os.path.normpath(candidate))
         base_normalized = Path(os.path.normpath(base))
         if not normalized.is_relative_to(base_normalized):
-            raise ValueError(
-                f"Output path {candidate!r} escapes directory {base!r}"
-            )
+            raise ValueError(f"Output path {candidate!r} escapes directory {base!r}")
 
     def register_commands(
         self,
@@ -471,7 +478,10 @@ class CommandRegistrar:
 
             if frontmatter.get("strategy") == "wrap":
                 from .presets import _substitute_core_template
-                body, core_frontmatter = _substitute_core_template(body, cmd_name, project_root, self)
+
+                body, core_frontmatter = _substitute_core_template(
+                    body, cmd_name, project_root, self
+                )
                 frontmatter = dict(frontmatter)
                 for key in ("scripts", "agent_scripts"):
                     if key not in frontmatter and key in core_frontmatter:
@@ -492,6 +502,16 @@ class CommandRegistrar:
                 body, "$ARGUMENTS", agent_config["args"]
             )
 
+            # Resolve __SPECKIT_COMMAND_*__ tokens using the agent's invoke separator.
+            # The separator is sourced from agent_config (populated by _build_agent_configs,
+            # which propagates each integration's invoke_separator class attribute).
+            # Deferred import of IntegrationBase avoids a circular import at module load
+            # (base.py itself imports CommandRegistrar lazily).
+            from specify_cli.integrations.base import IntegrationBase  # noqa: PLC0415
+
+            _sep = agent_config.get("invoke_separator", ".")
+            body = IntegrationBase.resolve_command_refs(body, _sep)
+
             output_name = self._compute_output_name(agent_name, cmd_name, agent_config)
 
             if agent_config["extension"] == "/SKILL.md":
@@ -505,12 +525,22 @@ class CommandRegistrar:
                     project_root,
                 )
             elif agent_config["format"] == "markdown":
-                body = self.resolve_skill_placeholders(agent_name, frontmatter, body, project_root)
-                body = self._convert_argument_placeholder(body, "$ARGUMENTS", agent_config["args"])
-                output = self.render_markdown_command(frontmatter, body, source_id, context_note)
+                body = self.resolve_skill_placeholders(
+                    agent_name, frontmatter, body, project_root
+                )
+                body = self._convert_argument_placeholder(
+                    body, "$ARGUMENTS", agent_config["args"]
+                )
+                output = self.render_markdown_command(
+                    frontmatter, body, source_id, context_note
+                )
             elif agent_config["format"] == "toml":
-                body = self.resolve_skill_placeholders(agent_name, frontmatter, body, project_root)
-                body = self._convert_argument_placeholder(body, "$ARGUMENTS", agent_config["args"])
+                body = self.resolve_skill_placeholders(
+                    agent_name, frontmatter, body, project_root
+                )
+                body = self._convert_argument_placeholder(
+                    body, "$ARGUMENTS", agent_config["args"]
+                )
                 output = self.render_toml_command(frontmatter, body, source_id)
             elif agent_config["format"] == "yaml":
                 output = self.render_yaml_command(
@@ -685,8 +715,11 @@ class CommandRegistrar:
             if agent_dir.exists():
                 try:
                     registered = self.register_commands(
-                        agent_name, commands, source_id,
-                        source_dir, project_root,
+                        agent_name,
+                        commands,
+                        source_id,
+                        source_dir,
+                        project_root,
                         context_note=context_note,
                     )
                     if registered:

src/specify_cli/authentication/__init__.py

@@ -0,0 +1,50 @@
+"""Authentication provider registry for multi-platform support.
+
+Credentials are **opt-in only**.  No authentication headers are sent unless
+the user creates ``~/.specify/auth.json`` mapping hosts to providers.
+Provider classes define *how* to authenticate (Bearer, Basic-PAT, etc.)
+while the config file defines *where* and *with what credentials*.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base import AuthProvider
+
+# Maps provider key → AuthProvider class instance.
+AUTH_REGISTRY: dict[str, AuthProvider] = {}
+
+
+def _register(provider: AuthProvider) -> None:
+    """Register a provider instance in the global registry.
+
+    Raises ``ValueError`` for falsy keys and ``KeyError`` for duplicates.
+    """
+    key = provider.key
+    if not key:
+        raise ValueError("Cannot register provider with an empty key.")
+    if key in AUTH_REGISTRY:
+        raise KeyError(f"Provider with key {key!r} is already registered.")
+    AUTH_REGISTRY[key] = provider
+
+
+def get_provider(key: str) -> AuthProvider | None:
+    """Return the provider for *key*, or ``None`` if not registered."""
+    return AUTH_REGISTRY.get(key)
+
+
+# -- Register built-in providers -----------------------------------------
+
+
+def _register_builtins() -> None:
+    """Register all built-in authentication providers (alphabetical)."""
+    from .azure_devops import AzureDevOpsAuth
+    from .github import GitHubAuth
+
+    _register(AzureDevOpsAuth())
+    _register(GitHubAuth())
+
+
+_register_builtins()

src/specify_cli/authentication/azure_devops.py

@@ -0,0 +1,117 @@
+"""Azure DevOps authentication provider."""
+
+from __future__ import annotations
+
+import base64
+import json as _json
+import os
+import subprocess
+from typing import TYPE_CHECKING
+
+from .base import AuthProvider
+
+if TYPE_CHECKING:
+    from .config import AuthConfigEntry
+
+# Azure DevOps resource ID for OAuth / Azure AD token acquisition.
+_ADO_RESOURCE_ID = "499b84ac-1321-427f-aa17-267ca6975798"
+
+
+class AzureDevOpsAuth(AuthProvider):
+    """Azure DevOps authentication provider.
+
+    Supports four auth schemes:
+
+    * ``basic-pat`` — PAT with empty username, Base64-encoded as ``:<PAT>``
+    * ``bearer`` — pre-acquired OAuth / Azure AD token
+    * ``azure-cli`` — acquires a token via ``az account get-access-token``
+    * ``azure-ad`` — acquires a token via OAuth2 client credentials flow
+    """
+
+    key = "azure-devops"
+    supported_auth_schemes = ("basic-pat", "bearer", "azure-cli", "azure-ad")
+
+    def auth_headers(self, token: str, auth_scheme: str) -> dict[str, str]:
+        """Build the ``Authorization`` header for the given scheme."""
+        if auth_scheme == "basic-pat":
+            encoded = base64.b64encode(f":{token}".encode("ascii")).decode("ascii")
+            return {"Authorization": f"Basic {encoded}"}
+        if auth_scheme in ("bearer", "azure-cli", "azure-ad"):
+            return {"Authorization": f"Bearer {token}"}
+        raise ValueError(
+            f"AzureDevOpsAuth does not support auth scheme {auth_scheme!r}"
+        )
+
+    def resolve_token(self, entry: AuthConfigEntry) -> str | None:
+        """Resolve token, with special handling for azure-cli and azure-ad."""
+        if entry.auth == "azure-cli":
+            return self._acquire_via_az_cli()
+        if entry.auth == "azure-ad":
+            return self._acquire_via_client_credentials(entry)
+        return super().resolve_token(entry)
+
+    # -- Token acquisition ------------------------------------------------
+
+    @staticmethod
+    def _acquire_via_az_cli() -> str | None:
+        """Run ``az account get-access-token`` and return the access token."""
+        try:
+            result = subprocess.run(  # noqa: S603, S607
+                [
+                    "az",
+                    "account",
+                    "get-access-token",
+                    "--resource",
+                    _ADO_RESOURCE_ID,
+                    "--output",
+                    "json",
+                ],
+                capture_output=True,
+                text=True,
+                timeout=30,
+                check=False,
+            )
+            if result.returncode != 0:
+                return None
+            payload = _json.loads(result.stdout)
+            token = payload.get("accessToken", "").strip()
+            return token or None
+        except (OSError, subprocess.TimeoutExpired, _json.JSONDecodeError, KeyError):
+            return None
+
+    @staticmethod
+    def _acquire_via_client_credentials(entry: AuthConfigEntry) -> str | None:
+        """Acquire a token via OAuth2 client credentials flow."""
+        import urllib.error
+        import urllib.request
+
+        if not entry.tenant_id or not entry.client_id or not entry.client_secret_env:
+            return None
+        client_secret = os.environ.get(entry.client_secret_env, "").strip()
+        if not client_secret:
+            return None
+
+        url = (
+            f"https://login.microsoftonline.com/{entry.tenant_id}"
+            "/oauth2/v2.0/token"
+        )
+        from urllib.parse import urlencode
+        body = urlencode({
+            "grant_type": "client_credentials",
+            "client_id": entry.client_id,
+            "client_secret": client_secret,
+            "scope": f"{_ADO_RESOURCE_ID}/.default",
+        }).encode("utf-8")
+
+        req = urllib.request.Request(
+            url,
+            data=body,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:  # noqa: S310
+                payload = _json.loads(resp.read().decode("utf-8"))
+                token = payload.get("access_token", "").strip()
+                return token or None
+        except (urllib.error.URLError, OSError, _json.JSONDecodeError, KeyError):
+            return None

src/specify_cli/authentication/base.py

@@ -0,0 +1,57 @@
+"""Abstract base class for authentication providers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .config import AuthConfigEntry
+
+
+class AuthProvider(ABC):
+    """Abstract base class every authentication provider must implement.
+
+    Subclasses must set:
+
+    * ``key`` — unique provider identifier (e.g. ``"github"``, ``"azure-devops"``)
+    * ``supported_auth_schemes`` — tuple of auth scheme strings this provider handles
+
+    And implement:
+
+    * ``auth_headers(token, auth_scheme)`` — build headers from a resolved token
+    * ``resolve_token(entry)`` — obtain the token for a config entry
+    """
+
+    key: str = ""
+    """Unique provider identifier."""
+
+    supported_auth_schemes: tuple[str, ...] = ()
+    """Auth schemes this provider supports (e.g. ``("bearer",)``)."""
+
+    @abstractmethod
+    def auth_headers(self, token: str, auth_scheme: str) -> dict[str, str]:
+        """Build authentication headers for *token* using *auth_scheme*.
+
+        Must return a dict with at least an ``Authorization`` key.
+        """
+
+    def resolve_token(self, entry: AuthConfigEntry) -> str | None:
+        """Resolve the token for *entry*.
+
+        Default implementation reads from ``entry.token`` directly
+        or from the environment variable named by ``entry.token_env``.
+        Override for schemes that acquire tokens dynamically
+        (e.g. ``azure-cli``, ``azure-ad``).
+        """
+        import os
+
+        if entry.token:
+            return entry.token.strip() or None
+        if entry.token_env:
+            val = os.environ.get(entry.token_env)
+            if val is not None:
+                val = val.strip()
+                if val:
+                    return val
+        return None

src/specify_cli/authentication/config.py

@@ -0,0 +1,209 @@
+"""Authentication configuration loader.
+
+Reads ``~/.specify/auth.json`` to determine which hosts receive credentials
+and which provider/auth-scheme to use.  No credentials are sent without
+an explicit opt-in via this file.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from pathlib import Path
+from urllib.parse import urlparse
+
+
+@dataclass(frozen=True)
+class AuthConfigEntry:
+    """A single provider entry from ``auth.json``."""
+
+    hosts: tuple[str, ...]
+    provider: str
+    auth: str
+    token: str | None = None
+    token_env: str | None = None
+    # Azure AD service-principal fields
+    tenant_id: str | None = None
+    client_id: str | None = None
+    client_secret_env: str | None = None
+
+
+def _default_config_path() -> Path:
+    """Return ``~/.specify/auth.json``."""
+    return Path.home() / ".specify" / "auth.json"
+
+
+def _is_valid_host_pattern(pattern: str) -> bool:
+    """Return True for safe host patterns: exact hostnames or ``*.suffix`` only.
+
+    Rejects patterns like ``*github.com`` (which would match
+    ``github.com.evil.com``) or multi-wildcard forms.  Only these two
+    forms are accepted:
+
+    * ``example.com``           — exact hostname
+    * ``*.example.com``         — leading ``*.`` wildcard; matches subdomains
+      such as ``myorg.example.com`` but not ``example.com`` itself
+    """
+    if "*" not in pattern:
+        return True  # exact hostname — already validated as non-empty
+    # Only *.suffix is allowed; no other wildcard positions
+    return pattern.startswith("*.") and "*" not in pattern[2:]
+
+
+def load_auth_config(
+    path: Path | None = None,
+) -> list[AuthConfigEntry]:
+    """Load and validate ``auth.json``, returning configured entries.
+
+    Returns an empty list when the file does not exist — this means
+    all HTTP requests will be unauthenticated (opt-in model).
+
+    Raises ``ValueError`` on schema violations.  Callers that want
+    misconfigurations to fail fast can allow this exception to
+    propagate; higher-level HTTP helpers may instead catch it,
+    warn, and continue with unauthenticated requests.
+    """
+    config_path = path or _default_config_path()
+
+    if not config_path.is_file():
+        return []
+
+    # Warn (but don't fail) if the file is world-readable (POSIX only).
+    if os.name != "nt":
+        try:
+            mode = config_path.stat().st_mode
+            if mode & (stat.S_IRGRP | stat.S_IROTH):
+                import warnings
+
+                warnings.warn(
+                    f"{config_path} is readable by group/others. "
+                    "Consider restricting with: chmod 600 "
+                    f"{config_path}",
+                    UserWarning,
+                    stacklevel=2,
+                )
+        except OSError:
+            pass  # stat failed — skip permission check
+
+    raw = json.loads(config_path.read_text(encoding="utf-8"))
+
+    if not isinstance(raw, dict):
+        raise ValueError(f"auth.json must be a JSON object, got {type(raw).__name__}")
+
+    providers_raw = raw.get("providers")
+    if not isinstance(providers_raw, list):
+        raise ValueError("auth.json must contain a 'providers' array")
+
+    entries: list[AuthConfigEntry] = []
+    for i, entry_raw in enumerate(providers_raw):
+        if not isinstance(entry_raw, dict):
+            raise ValueError(f"providers[{i}]: must be a JSON object")
+
+        hosts = entry_raw.get("hosts")
+        if not isinstance(hosts, list) or not hosts:
+            raise ValueError(f"providers[{i}]: 'hosts' must be a non-empty array")
+        if not all(isinstance(h, str) and h.strip() for h in hosts):
+            raise ValueError(f"providers[{i}]: each host must be a non-empty string")
+        # Normalize hosts: strip whitespace and lowercase
+        hosts = [h.strip().lower() for h in hosts]
+        # Reject dangerous wildcard forms (e.g. *github.com matches github.com.evil.com)
+        for h in hosts:
+            if not _is_valid_host_pattern(h):
+                raise ValueError(
+                    f"providers[{i}]: invalid host pattern {h!r}. "
+                    "Only exact hostnames or '*.suffix' forms are allowed "
+                    "(e.g. 'github.com' or '*.visualstudio.com')."
+                )
+
+        provider = entry_raw.get("provider", "")
+        if not isinstance(provider, str) or not provider:
+            raise ValueError(f"providers[{i}]: 'provider' must be a non-empty string")
+
+        auth = entry_raw.get("auth", "")
+        if not isinstance(auth, str) or not auth:
+            raise ValueError(f"providers[{i}]: 'auth' must be a non-empty string")
+
+        token = entry_raw.get("token")
+        token_env = entry_raw.get("token_env")
+
+        # Validate token/token_env types
+        if token is not None and (not isinstance(token, str) or not token.strip()):
+            raise ValueError(f"providers[{i}]: 'token' must be a non-empty string")
+        if token_env is not None and (not isinstance(token_env, str) or not token_env.strip()):
+            raise ValueError(f"providers[{i}]: 'token_env' must be a non-empty string")
+
+        # Validate provider+scheme compatibility
+        from . import get_provider as _get_provider
+        _prov = _get_provider(provider)
+        if _prov is None:
+            from . import AUTH_REGISTRY
+            raise ValueError(
+                f"providers[{i}]: unknown provider {provider!r}; "
+                f"registered: {sorted(AUTH_REGISTRY.keys())}"
+            )
+        if auth not in _prov.supported_auth_schemes:
+            raise ValueError(
+                f"providers[{i}]: provider {provider!r} does not support "
+                f"auth scheme {auth!r}; supported: {list(_prov.supported_auth_schemes)}"
+            )
+
+        # Validate token source based on auth scheme
+        if auth in ("bearer", "basic-pat"):
+            if not token and not token_env:
+                raise ValueError(
+                    f"providers[{i}]: auth={auth!r} requires 'token' or 'token_env'"
+                )
+        elif auth == "azure-ad":
+            tenant_id = entry_raw.get("tenant_id")
+            client_id = entry_raw.get("client_id")
+            client_secret_env = entry_raw.get("client_secret_env")
+            if not all([tenant_id, client_id, client_secret_env]):
+                raise ValueError(
+                    f"providers[{i}]: auth='azure-ad' requires "
+                    "'tenant_id', 'client_id', and 'client_secret_env'"
+                )
+            for field_name, field_val in [
+                ("tenant_id", tenant_id),
+                ("client_id", client_id),
+                ("client_secret_env", client_secret_env),
+            ]:
+                if not isinstance(field_val, str) or not field_val.strip():
+                    raise ValueError(
+                        f"providers[{i}]: '{field_name}' must be a non-empty string"
+                    )
+        # azure-cli needs no extra fields
+
+        entries.append(
+            AuthConfigEntry(
+                hosts=tuple(hosts),
+                provider=provider,
+                auth=auth,
+                token=token,
+                token_env=token_env,
+                tenant_id=entry_raw.get("tenant_id"),
+                client_id=entry_raw.get("client_id"),
+                client_secret_env=entry_raw.get("client_secret_env"),
+            )
+        )
+
+    return entries
+
+
+def find_entries_for_url(
+    url: str, entries: list[AuthConfigEntry]
+) -> list[AuthConfigEntry]:
+    """Return entries whose ``hosts`` match the hostname of *url*."""
+    hostname = (urlparse(url).hostname or "").lower()
+    if not hostname:
+        return []
+    return [
+        e
+        for e in entries
+        if any(
+            pattern == hostname or fnmatch(hostname, pattern)
+            for pattern in e.hosts
+        )
+    ]

src/specify_cli/authentication/github.py

@@ -0,0 +1,24 @@
+"""GitHub authentication provider."""
+
+from __future__ import annotations
+
+from .base import AuthProvider
+
+
+class GitHubAuth(AuthProvider):
+    """GitHub authentication provider.
+
+    Supports the ``bearer`` auth scheme, used for PATs, fine-grained PATs,
+    OAuth tokens, and GitHub App installation tokens.
+    """
+
+    key = "github"
+    supported_auth_schemes = ("bearer",)
+
+    def auth_headers(self, token: str, auth_scheme: str) -> dict[str, str]:
+        """Return ``Authorization: Bearer <token>``."""
+        if auth_scheme != "bearer":
+            raise ValueError(
+                f"GitHubAuth does not support auth scheme {auth_scheme!r}"
+            )
+        return {"Authorization": f"Bearer {token}"}

src/specify_cli/authentication/http.py

@@ -0,0 +1,149 @@
+"""Authenticated HTTP helpers driven by ``~/.specify/auth.json``.
+
+No credentials are sent unless the user has created ``auth.json``.
+For each outbound URL the helper matches the hostname against
+configured entries, resolves the token via the appropriate provider
+class, and attaches auth headers.  Redirect safety is enforced:
+the ``Authorization`` header is stripped when a redirect leaves the
+entry's declared hosts.  On 401/403 the next matching entry is tried,
+then unauthenticated.
+"""
+
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from fnmatch import fnmatch
+from urllib.parse import urlparse
+
+from . import get_provider
+from .config import AuthConfigEntry, _default_config_path, find_entries_for_url, load_auth_config
+
+
+_config_override: list[AuthConfigEntry] | None = None
+_config_cache: list[AuthConfigEntry] | None = None  # None = not yet loaded
+
+
+def _load_config() -> list[AuthConfigEntry]:
+    """Load auth config, using override if set (for testing).
+
+    The result is cached per-process so ``auth.json`` is read at most once,
+    and any warning about a malformed file fires only once.
+    """
+    global _config_cache
+    if _config_override is not None:
+        return _config_override
+    if _config_cache is not None:
+        return _config_cache
+    try:
+        _config_cache = load_auth_config()
+    except (ValueError, OSError) as exc:
+        import warnings
+        config_path = _default_config_path()
+        warnings.warn(
+            f"Failed to load {config_path}: {exc}. "
+            "All requests will be unauthenticated.",
+            UserWarning,
+            stacklevel=2,
+        )
+        _config_cache = []
+    return _config_cache
+
+
+def _hostname_in_hosts(hostname: str, hosts: tuple[str, ...]) -> bool:
+    """Return True if *hostname* matches any pattern in *hosts*."""
+    hostname = hostname.lower()
+    return any(p == hostname or fnmatch(hostname, p) for p in hosts)
+
+
+class _StripAuthOnRedirect(urllib.request.HTTPRedirectHandler):
+    """Drop ``Authorization`` when a redirect leaves the entry's declared hosts."""
+
+    def __init__(self, hosts: tuple[str, ...]) -> None:
+        super().__init__()
+        self._hosts = hosts
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        original_auth = (
+            req.get_header("Authorization")
+            or req.unredirected_hdrs.get("Authorization")
+        )
+        new_req = super().redirect_request(req, fp, code, msg, headers, newurl)
+        if new_req is not None:
+            hostname = (urlparse(newurl).hostname or "").lower()
+            if _hostname_in_hosts(hostname, self._hosts):
+                if original_auth:
+                    new_req.add_unredirected_header("Authorization", original_auth)
+            else:
+                new_req.headers.pop("Authorization", None)
+                new_req.unredirected_hdrs.pop("Authorization", None)
+        return new_req
+
+
+def build_request(url: str, extra_headers: dict[str, str] | None = None) -> urllib.request.Request:
+    """Build a :class:`~urllib.request.Request`, attaching auth when config matches.
+
+    Uses the first matching entry from ``auth.json`` whose token resolves.
+    Returns a plain request when no entry matches or the file doesn't exist.
+    """
+    headers: dict[str, str] = {}
+    if extra_headers:
+        # Strip Authorization from extra_headers to prevent bypass
+        headers.update({k: v for k, v in extra_headers.items() if k.lower() != "authorization"})
+    # Auth headers applied last — cannot be overridden by extra_headers
+    entries = find_entries_for_url(url, _load_config())
+    for entry in entries:
+        provider = get_provider(entry.provider)
+        if provider is None:
+            continue
+        token = provider.resolve_token(entry)
+        if token:
+            headers.update(provider.auth_headers(token, entry.auth))
+            break
+    return urllib.request.Request(url, headers=headers)
+
+
+def open_url(url: str, timeout: int = 10, extra_headers: dict[str, str] | None = None):
+    """Open *url* with config-driven auth, redirect stripping, and fallthrough.
+
+    1. Find ``auth.json`` entries whose hosts match the URL.
+    2. For each entry, resolve the token and try the request.
+    3. On 401/403 move to the next matching entry.
+    4. After all entries exhausted (or none matched), try unauthenticated.
+    5. Non-auth errors (404, 500, network) raise immediately.
+
+    *extra_headers* (e.g. ``Accept``) are merged into every attempt.
+    """
+    entries = find_entries_for_url(url, _load_config())
+
+    def _make_req(auth_headers: dict[str, str]) -> urllib.request.Request:
+        merged = {}
+        if extra_headers:
+            # Strip Authorization from extra_headers to prevent bypass
+            merged.update({k: v for k, v in extra_headers.items() if k.lower() != "authorization"})
+        # Auth headers applied last — cannot be overridden by extra_headers
+        merged.update(auth_headers)
+        return urllib.request.Request(url, headers=merged)
+
+    # Try each matching entry
+    for entry in entries:
+        provider = get_provider(entry.provider)
+        if provider is None:
+            continue
+        token = provider.resolve_token(entry)
+        if not token:
+            continue
+
+        req = _make_req(provider.auth_headers(token, entry.auth))
+        opener = urllib.request.build_opener(_StripAuthOnRedirect(entry.hosts))
+        try:
+            return opener.open(req, timeout=timeout)
+        except urllib.error.HTTPError as exc:
+            if exc.code in (401, 403):
+                exc.close()
+                continue  # try next entry
+            raise
+
+    # No entry worked (or none matched) — unauthenticated fallback
+    req = _make_req({})
+    return urllib.request.urlopen(req, timeout=timeout)  # noqa: S310

src/specify_cli/catalogs.py

@@ -0,0 +1,180 @@
+"""Shared catalog stack config primitives.
+
+Catalog-backed features use the same local config shape and URL validation
+rules. This module keeps those narrow primitives in one place while individual
+catalog types keep their active source resolution, fetch, cache, and
+domain-specific validation behavior.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar
+
+import yaml
+
+
+@dataclass
+class CatalogEntry:
+    """Represents a single catalog source in a catalog stack."""
+
+    url: str
+    name: str
+    priority: int
+    install_allowed: bool
+    description: str = ""
+
+
+class CatalogStackBase:
+    """Base class for ordered catalog-source resolution.
+
+    Subclasses provide catalog-specific metadata and exception classes. Fetching
+    and schema validation stay in each concrete catalog because those formats
+    differ across integrations, extensions, presets, and workflows.
+    """
+
+    ENTRY_CLASS: ClassVar[type[CatalogEntry]] = CatalogEntry
+    ERROR_TYPE: ClassVar[type[Exception]] = ValueError
+    VALIDATION_ERROR_TYPE: ClassVar[type[Exception]] = ValueError
+
+    CONFIG_FILENAME: ClassVar[str]
+
+    @classmethod
+    def _error(cls, message: str) -> Exception:
+        return cls.ERROR_TYPE(message)
+
+    @classmethod
+    def _validation_error(cls, message: str) -> Exception:
+        return cls.VALIDATION_ERROR_TYPE(message)
+
+    @classmethod
+    def _entry(
+        cls,
+        *,
+        url: str,
+        name: str,
+        priority: int,
+        install_allowed: bool,
+        description: str = "",
+    ) -> CatalogEntry:
+        return cls.ENTRY_CLASS(
+            url=url,
+            name=name,
+            priority=priority,
+            install_allowed=install_allowed,
+            description=description,
+        )
+
+    @classmethod
+    def _validate_catalog_url(cls, url: str) -> None:
+        """Validate that a catalog URL uses HTTPS, except localhost HTTP."""
+        from urllib.parse import urlparse
+
+        parsed = urlparse(url)
+        is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
+        if parsed.scheme != "https" and not (parsed.scheme == "http" and is_localhost):
+            raise cls._error(
+                f"Catalog URL must use HTTPS (got {parsed.scheme}://). "
+                "HTTP is only allowed for localhost."
+            )
+        if not parsed.netloc:
+            raise cls._error("Catalog URL must be a valid URL with a host.")
+
+    def _load_catalog_config(self, config_path: Path) -> list[CatalogEntry] | None:
+        """Load catalog stack configuration from a YAML file.
+
+        Returns ``None`` when the file does not exist. Existing files fail
+        closed when they are malformed, empty, or contain no usable URLs.
+        """
+        if not config_path.exists():
+            return None
+        try:
+            data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+        except (yaml.YAMLError, OSError, UnicodeError) as exc:
+            raise self._validation_error(
+                f"Failed to read catalog config {config_path}: {exc}"
+            ) from exc
+        if data is None:
+            data = {}
+        if not isinstance(data, dict):
+            raise self._validation_error(
+                f"Invalid catalog config {config_path}: expected a YAML mapping at the root"
+            )
+
+        catalogs_data = data.get("catalogs", [])
+        if not isinstance(catalogs_data, list):
+            raise self._validation_error(
+                f"Invalid catalog config {config_path}: 'catalogs' must be a list, "
+                f"got {type(catalogs_data).__name__}"
+            )
+        if not catalogs_data:
+            raise self._validation_error(
+                f"Catalog config {config_path} exists but contains no 'catalogs' entries. "
+                f"Remove the file to use built-in defaults, or add valid catalog entries."
+            )
+
+        entries: list[CatalogEntry] = []
+        skipped: list[int] = []
+        for idx, item in enumerate(catalogs_data):
+            if not isinstance(item, dict):
+                raise self._validation_error(
+                    f"Invalid catalog config {config_path}: catalog entry at index {idx}: "
+                    f"expected a mapping, got {type(item).__name__}"
+                )
+            url = str(item.get("url", "")).strip()
+            if not url:
+                skipped.append(idx)
+                continue
+            try:
+                self._validate_catalog_url(url)
+            except self.ERROR_TYPE as exc:
+                raise self._validation_error(
+                    f"Invalid catalog URL in {config_path} at index {idx}: {exc}"
+                ) from exc
+
+            raw_priority = item.get("priority", idx + 1)
+            if isinstance(raw_priority, bool):
+                raise self._validation_error(
+                    f"Invalid catalog config {config_path}: "
+                    f"Invalid priority for catalog '{item.get('name', idx + 1)}': "
+                    f"expected integer, got {raw_priority!r}"
+                )
+            try:
+                priority = int(raw_priority)
+            except (TypeError, ValueError):
+                raise self._validation_error(
+                    f"Invalid catalog config {config_path}: "
+                    f"Invalid priority for catalog '{item.get('name', idx + 1)}': "
+                    f"expected integer, got {raw_priority!r}"
+                )
+
+            raw_install = item.get("install_allowed", False)
+            if isinstance(raw_install, str):
+                install_allowed = raw_install.strip().lower() in ("true", "yes", "1")
+            else:
+                install_allowed = bool(raw_install)
+
+            raw_name = item.get("name")
+            name = str(raw_name).strip() if raw_name is not None else ""
+            if not name:
+                name = f"catalog-{len(entries) + 1}"
+
+            entries.append(
+                self._entry(
+                    url=url,
+                    name=name,
+                    priority=priority,
+                    install_allowed=install_allowed,
+                    description=str(item.get("description", "")),
+                )
+            )
+
+        entries.sort(key=lambda e: e.priority)
+        if not entries:
+            raise self._validation_error(
+                f"Catalog config {config_path} contains {len(catalogs_data)} "
+                f"entries but none have valid URLs (entries at indices {skipped} "
+                f"were skipped). Each catalog entry must have a 'url' field."
+            )
+        return entries

src/specify_cli/extensions.py

@@ -962,29 +962,40 @@ class ExtensionManager:
 
         return written
 
-    def _unregister_extension_skills(self, skill_names: List[str], extension_id: str) -> None:
+    def _unregister_extension_skills(
+        self,
+        skill_names: List[str],
+        extension_id: str,
+        skills_dir: Optional[Path] = None,
+    ) -> None:
         """Remove SKILL.md directories for extension skills.
 
         Called during extension removal to clean up skill files that
         were created by ``_register_extension_skills()``.
 
-        If ``_get_skills_dir()`` returns ``None`` (e.g. the user removed
-        init-options.json or toggled ai_skills after installation), we
-        fall back to scanning all known agent skills directories so that
-        orphaned skill directories are still cleaned up.  In that case
-        each candidate directory is verified against the SKILL.md
-        ``metadata.source`` field before removal to avoid accidentally
-        deleting user-created skills with the same name.
+        If *skills_dir* is not provided and ``_get_skills_dir()`` returns
+        ``None`` (e.g. the user removed init-options.json or toggled
+        ai_skills after installation), we fall back to scanning all known
+        agent skills directories so that orphaned skill directories are
+        still cleaned up.  In that case each candidate directory is
+        verified against the SKILL.md ``metadata.source`` field before
+        removal to avoid accidentally deleting user-created skills with
+        the same name.
 
         Args:
             skill_names: List of skill names to remove.
             extension_id: Extension ID used to verify ownership during
                 fallback candidate scanning.
+            skills_dir: Optional explicit skills directory to use instead
+                of resolving via ``_get_skills_dir()``.  Useful when the
+                caller needs to target a specific agent's skills directory
+                regardless of the currently-active agent in init-options.
         """
         if not skill_names:
             return
 
-        skills_dir = self._get_skills_dir()
+        if skills_dir is None:
+            skills_dir = self._get_skills_dir()
 
         if skills_dir:
             # Fast path: we know the exact skills directory
@@ -1332,6 +1343,156 @@ class ExtensionManager:
 
         return True
 
+    @staticmethod
+    def _valid_name_list(value: Any) -> List[str]:
+        """Return string entries from a registry list, ignoring corrupt values."""
+        if not isinstance(value, list):
+            return []
+        return [item for item in value if isinstance(item, str)]
+
+    def unregister_agent_artifacts(self, agent_name: str) -> None:
+        """Remove extension files registered for a specific agent.
+
+        Extension command files are tracked per agent in ``registered_commands``.
+        Extension skills are scoped to the provided *agent_name*; they are removed
+        from that agent's skills directory (resolved via its integration config)
+        and the registry field is cleared.
+
+        Skips cleanup when *agent_name* is not a supported agent to avoid
+        losing registry entries while leaving orphaned files on disk.
+        """
+        if not agent_name:
+            return
+
+        registrar = CommandRegistrar()
+        if agent_name not in registrar.AGENT_CONFIGS:
+            return
+
+        # Resolve the skills directory for the specific agent so cleanup is
+        # agent-scoped and does not depend on the currently-active agent in
+        # init-options.  Use the same helper that extension install uses.
+        from . import _get_skills_dir as resolve_skills_dir
+
+        agent_skills_dir = resolve_skills_dir(self.project_root, agent_name)
+
+        for ext_id, metadata in self.registry.list().items():
+            updates: Dict[str, Any] = {}
+
+            registered_commands = metadata.get("registered_commands", {})
+            if isinstance(registered_commands, dict) and agent_name in registered_commands:
+                command_names = self._valid_name_list(registered_commands.get(agent_name))
+                if command_names:
+                    registrar.unregister_commands({agent_name: command_names}, self.project_root)
+
+                new_registered = copy.deepcopy(registered_commands)
+                new_registered.pop(agent_name, None)
+                updates["registered_commands"] = new_registered
+
+            registered_skills = self._valid_name_list(metadata.get("registered_skills", []))
+            if registered_skills:
+                # Only pass the resolved skills_dir when it actually exists.
+                # Otherwise let _unregister_extension_skills fall back to
+                # scanning all known agent skills directories, which is useful
+                # for cleaning up stale entries created by earlier installs.
+                skills_dir = agent_skills_dir if agent_skills_dir.is_dir() else None
+                self._unregister_extension_skills(
+                    registered_skills, ext_id, skills_dir=skills_dir
+                )
+
+                # Only reconcile registry state when cleanup was scoped to a
+                # specific existing directory. When skills_dir is None,
+                # _unregister_extension_skills falls back to scanning multiple
+                # candidate directories, so agent_skills_dir cannot be used to
+                # infer what was removed.  When skills_dir is set,
+                # _unregister_extension_skills may intentionally skip deletion
+                # when ownership cannot be verified (e.g., corrupted/missing
+                # SKILL.md or mismatching metadata.source).  Only drop registry
+                # entries for skill directories that were actually removed so
+                # future cleanup attempts can still find skipped ones.
+                if skills_dir is not None:
+                    remaining_skills = [
+                        skill_name
+                        for skill_name in registered_skills
+                        if (skills_dir / skill_name).is_dir()
+                    ]
+                    if remaining_skills != registered_skills:
+                        updates["registered_skills"] = remaining_skills
+
+            if updates:
+                self.registry.update(ext_id, updates)
+
+    def register_enabled_extensions_for_agent(self, agent_name: str) -> None:
+        """Register installed, enabled extensions for ``agent_name``.
+
+        This is intended to be called after switching integrations. Command
+        registration is scoped to the explicit ``agent_name`` argument, but some
+        behavior still depends on the current init-options state (for example,
+        skills-mode handling uses the active ``ai`` / ``ai_skills`` settings).
+
+        Callers should therefore pass the agent that has just been made active
+        in init-options; in normal use, ``agent_name`` is expected to match the
+        current ``ai`` value. This mirrors extension install behavior while
+        avoiding stale default-mode command directories when that active agent
+        is running in skills mode (notably Copilot ``--skills``).
+        """
+        if not agent_name:
+            return
+
+        from . import load_init_options
+
+        registrar = CommandRegistrar()
+        agent_config = registrar.AGENT_CONFIGS.get(agent_name)
+        init_options = load_init_options(self.project_root)
+        if not isinstance(init_options, dict):
+            init_options = {}
+
+        active_agent = init_options.get("ai")
+        skills_mode_active = (
+            active_agent == agent_name
+            and bool(init_options.get("ai_skills"))
+            and bool(agent_config)
+            and agent_config.get("extension") != "/SKILL.md"
+        )
+
+        for ext_id, metadata in self.registry.list().items():
+            if not metadata.get("enabled", True):
+                continue
+
+            manifest = self.get_extension(ext_id)
+            if manifest is None:
+                continue
+
+            ext_dir = self.extensions_dir / ext_id
+            updates: Dict[str, Any] = {}
+
+            if agent_config and not skills_mode_active:
+                registered = registrar.register_commands_for_agent(
+                    agent_name, manifest, ext_dir, self.project_root
+                )
+                registered_commands = metadata.get("registered_commands", {})
+                if not isinstance(registered_commands, dict):
+                    registered_commands = {}
+                new_registered = copy.deepcopy(registered_commands)
+                if registered:
+                    new_registered[agent_name] = registered
+                else:
+                    # Registration returned empty list (e.g., corrupted
+                    # manifest pointing at missing command files).  Clear
+                    # stale entry so later cleanup doesn't try to remove
+                    # files that were never written.
+                    new_registered.pop(agent_name, None)
+                if new_registered != registered_commands:
+                    updates["registered_commands"] = new_registered
+
+            registered_skills = self._register_extension_skills(manifest, ext_dir)
+            if registered_skills:
+                existing_skills = self._valid_name_list(metadata.get("registered_skills", []))
+                merged_skills = list(dict.fromkeys(existing_skills + registered_skills))
+                updates["registered_skills"] = merged_skills
+
+            if updates:
+                self.registry.update(ext_id, updates)
+
     def list_installed(self) -> List[Dict[str, Any]]:
         """List all installed extensions with metadata.
 
@@ -1546,20 +1707,20 @@ class ExtensionCatalog:
             raise ValidationError("Catalog URL must be a valid URL with a host.")
 
     def _make_request(self, url: str):
-        """Build a urllib Request, adding a GitHub auth header when available.
+        """Build a urllib Request, adding auth headers when a provider matches.
 
-        Delegates to :func:`specify_cli._github_http.build_github_request`.
+        Delegates to :func:`specify_cli.authentication.http.build_request`.
         """
-        from specify_cli._github_http import build_github_request
-        return build_github_request(url)
+        from specify_cli.authentication.http import build_request
+        return build_request(url)
 
     def _open_url(self, url: str, timeout: int = 10):
-        """Open a URL with GitHub auth, stripping the header on cross-host redirects.
+        """Open a URL with provider-based auth, trying each configured provider.
 
-        Delegates to :func:`specify_cli._github_http.open_github_url`.
+        Delegates to :func:`specify_cli.authentication.http.open_url`.
         """
-        from specify_cli._github_http import open_github_url
-        return open_github_url(url, timeout)
+        from specify_cli.authentication.http import open_url
+        return open_url(url, timeout)
 
     def _load_catalog_config(self, config_path: Path) -> Optional[List[CatalogEntry]]:
         """Load catalog stack configuration from a YAML file.

src/specify_cli/integration_runtime.py

@@ -0,0 +1,90 @@
+"""Runtime helpers for integration commands."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from .integration_state import integration_setting, integration_settings
+
+
+ParseOptions = Callable[[Any, str], dict[str, Any] | None]
+
+
+def resolve_integration_options(
+    integration: Any,
+    state: dict[str, Any],
+    key: str,
+    raw_options: str | None,
+    *,
+    parse_options: ParseOptions,
+) -> tuple[str | None, dict[str, Any] | None]:
+    """Resolve raw and parsed options for an integration operation."""
+    if raw_options is not None:
+        return raw_options, parse_options(integration, raw_options)
+
+    setting = integration_setting(state, key)
+    stored_raw = setting.get("raw_options")
+    if not isinstance(stored_raw, str):
+        stored_raw = None
+
+    stored_parsed = setting.get("parsed_options")
+    if isinstance(stored_parsed, dict):
+        return stored_raw, stored_parsed or None
+
+    if stored_raw:
+        return stored_raw, parse_options(integration, stored_raw)
+
+    return None, None
+
+
+def with_integration_setting(
+    state: dict[str, Any],
+    key: str,
+    integration: Any,
+    *,
+    script_type: str | None = None,
+    raw_options: str | None = None,
+    parsed_options: dict[str, Any] | None = None,
+) -> dict[str, dict[str, Any]]:
+    """Return integration settings with *key* updated."""
+    settings = integration_settings(state)
+    current = dict(settings.get(key, {}))
+
+    if script_type:
+        current["script"] = script_type
+    if raw_options is not None:
+        current["raw_options"] = raw_options
+    elif "raw_options" in current and not current.get("raw_options"):
+        current.pop("raw_options", None)
+
+    if parsed_options is not None:
+        current["parsed_options"] = parsed_options
+    elif raw_options is not None:
+        current.pop("parsed_options", None)
+
+    current["invoke_separator"] = integration.effective_invoke_separator(parsed_options)
+    settings[key] = current
+    return settings
+
+
+def invoke_separator_for_integration(
+    integration: Any,
+    state: dict[str, Any],
+    key: str,
+    parsed_options: dict[str, Any] | None = None,
+) -> str:
+    """Resolve the invocation separator for stored/default integration state."""
+    if parsed_options is not None:
+        return integration.effective_invoke_separator(parsed_options)
+
+    setting = integration_setting(state, key)
+    stored_separator = setting.get("invoke_separator")
+    if isinstance(stored_separator, str) and stored_separator:
+        return stored_separator
+
+    stored_parsed = setting.get("parsed_options")
+    if isinstance(stored_parsed, dict):
+        return integration.effective_invoke_separator(stored_parsed)
+
+    return integration.effective_invoke_separator(None)

src/specify_cli/integration_state.py

@@ -0,0 +1,161 @@
+"""State helpers for installed AI agent integrations."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+INTEGRATION_JSON = ".specify/integration.json"
+INTEGRATION_STATE_SCHEMA = 1
+
+
+def clean_integration_key(key: Any) -> str | None:
+    """Return a stripped integration key, or None for empty/non-string values."""
+    if not isinstance(key, str) or not key.strip():
+        return None
+    return key.strip()
+
+
+def dedupe_integration_keys(keys: list[Any]) -> list[str]:
+    """Return a de-duplicated list of non-empty integration keys."""
+    seen: set[str] = set()
+    deduped: list[str] = []
+    for key in keys:
+        clean = clean_integration_key(key)
+        if clean is None:
+            continue
+        if clean in seen:
+            continue
+        seen.add(clean)
+        deduped.append(clean)
+    return deduped
+
+
+def normalize_integration_settings(settings: Any) -> dict[str, dict[str, Any]]:
+    """Return JSON-safe per-integration runtime settings."""
+    if not isinstance(settings, dict):
+        return {}
+
+    normalized: dict[str, dict[str, Any]] = {}
+    for key, value in settings.items():
+        if not isinstance(key, str) or not key.strip() or not isinstance(value, dict):
+            continue
+
+        clean: dict[str, Any] = {}
+        script = value.get("script")
+        if isinstance(script, str) and script.strip():
+            clean["script"] = script.strip()
+
+        raw_options = value.get("raw_options")
+        if isinstance(raw_options, str):
+            clean["raw_options"] = raw_options
+
+        parsed_options = value.get("parsed_options")
+        if isinstance(parsed_options, dict):
+            clean["parsed_options"] = parsed_options
+
+        invoke_separator = value.get("invoke_separator")
+        if isinstance(invoke_separator, str) and invoke_separator.strip():
+            clean["invoke_separator"] = invoke_separator.strip()
+
+        if clean:
+            normalized[key.strip()] = clean
+
+    return normalized
+
+
+def _normalized_integration_state_schema(value: Any) -> int:
+    if isinstance(value, int) and not isinstance(value, bool) and value > INTEGRATION_STATE_SCHEMA:
+        return value
+    return INTEGRATION_STATE_SCHEMA
+
+
+def normalize_integration_state(data: dict[str, Any]) -> dict[str, Any]:
+    """Normalize legacy and multi-install integration metadata."""
+    legacy_key = clean_integration_key(data.get("integration"))
+    default_key = clean_integration_key(data.get("default_integration")) or legacy_key
+
+    installed = data.get("installed_integrations")
+    installed_keys = dedupe_integration_keys(installed if isinstance(installed, list) else [])
+    if not default_key and installed_keys:
+        default_key = installed_keys[0]
+    if default_key and default_key not in installed_keys:
+        installed_keys.insert(0, default_key)
+
+    settings = normalize_integration_settings(data.get("integration_settings"))
+
+    normalized = dict(data)
+    normalized["integration_state_schema"] = _normalized_integration_state_schema(
+        data.get("integration_state_schema")
+    )
+    if default_key:
+        normalized["integration"] = default_key
+        normalized["default_integration"] = default_key
+    else:
+        normalized.pop("integration", None)
+        normalized.pop("default_integration", None)
+    normalized["installed_integrations"] = installed_keys
+    normalized["integration_settings"] = {
+        key: settings[key] for key in installed_keys if key in settings
+    }
+    return normalized
+
+
+def default_integration_key(state: dict[str, Any]) -> str | None:
+    """Return the default integration key from normalized state."""
+    key = state.get("default_integration") or state.get("integration")
+    return clean_integration_key(key)
+
+
+def installed_integration_keys(state: dict[str, Any]) -> list[str]:
+    """Return installed integration keys from normalized state."""
+    return dedupe_integration_keys(state.get("installed_integrations", []))
+
+
+def integration_settings(state: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """Return normalized per-integration settings from state."""
+    return normalize_integration_settings(state.get("integration_settings"))
+
+
+def integration_setting(state: dict[str, Any], key: str) -> dict[str, Any]:
+    """Return stored runtime settings for *key*."""
+    return dict(integration_settings(state).get(key, {}))
+
+
+def write_integration_json(
+    project_root: Path,
+    *,
+    version: str,
+    integration_key: str | None,
+    installed_integrations: list[str] | None = None,
+    settings: dict[str, dict[str, Any]] | None = None,
+) -> None:
+    """Write ``.specify/integration.json`` with legacy-compatible state."""
+    dest = project_root / INTEGRATION_JSON
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    integration_key = clean_integration_key(integration_key)
+    installed = dedupe_integration_keys(installed_integrations or [])
+    if integration_key and integration_key not in installed:
+        installed.insert(0, integration_key)
+    if not integration_key and installed:
+        integration_key = installed[0]
+
+    normalized_settings = normalize_integration_settings(settings or {})
+    normalized_settings = {
+        key: normalized_settings[key] for key in installed if key in normalized_settings
+    }
+
+    data: dict[str, Any] = {
+        "version": version,
+        "integration_state_schema": INTEGRATION_STATE_SCHEMA,
+        "installed_integrations": installed,
+        "integration_settings": normalized_settings,
+    }
+    if integration_key:
+        data["integration"] = integration_key
+        data["default_integration"] = integration_key
+
+    dest.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")

src/specify_cli/integrations/__init__.py

@@ -66,6 +66,7 @@ def _register_builtins() -> None:
     from .kilocode import KilocodeIntegration
     from .kimi import KimiIntegration
     from .kiro_cli import KiroCliIntegration
+    from .lingma import LingmaIntegration
     from .opencode import OpencodeIntegration
     from .pi import PiIntegration
     from .qodercli import QodercliIntegration
@@ -97,6 +98,7 @@ def _register_builtins() -> None:
     _register(KilocodeIntegration())
     _register(KimiIntegration())
     _register(KiroCliIntegration())
+    _register(LingmaIntegration())
     _register(OpencodeIntegration())
     _register(PiIntegration())
     _register(QodercliIntegration())

src/specify_cli/integrations/auggie/__init__.py

@@ -19,3 +19,4 @@ class AuggieIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = ".augment/rules/specify-rules.md"
+    multi_install_safe = True

src/specify_cli/integrations/base.py

@@ -20,6 +20,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+import yaml
+
 if TYPE_CHECKING:
     from .manifest import IntegrationManifest
 
@@ -87,6 +89,14 @@ class IntegrationBase(ABC):
     invoke_separator: str = "."
     """Separator used in slash-command invocations (``"."`` → ``/speckit.plan``)."""
 
+    multi_install_safe: bool = False
+    """Whether this integration is declared safe to install alongside others.
+
+    Safe integrations must use a static, unique agent root, command directory,
+    and context file. Registry tests enforce those invariants for every
+    integration that sets this flag.
+    """
+
     # -- Markers for managed context section ------------------------------
 
     CONTEXT_MARKER_START = "<!-- SPECKIT START -->"
@@ -598,6 +608,7 @@ class IntegrationBase(ABC):
         # For .mdc files, treat Speckit-generated frontmatter-only content as empty
         if ctx_path.suffix == ".mdc":
             import re
+
             # Delete the file if only YAML frontmatter remains (no body content)
             frontmatter_only = re.match(
                 r"^---\n.*?\n---\s*$", normalized, re.DOTALL
@@ -945,7 +956,6 @@ class TomlIntegration(IntegrationBase):
         and ``>``) keep their YAML semantics instead of being treated as
         raw text.
         """
-        import yaml
 
         frontmatter_text, _ = TomlIntegration._split_frontmatter(content)
         if not frontmatter_text:
@@ -1132,7 +1142,6 @@ class YamlIntegration(IntegrationBase):
     @staticmethod
     def _extract_frontmatter(content: str) -> dict[str, Any]:
         """Extract frontmatter as a dict from YAML frontmatter block."""
-        import yaml
 
         if not content.startswith("---"):
             return {}
@@ -1193,24 +1202,38 @@ class YamlIntegration(IntegrationBase):
             text = text[len("speckit.") :]
         return text.replace(".", " ").replace("-", " ").replace("_", " ").title()
 
-    @staticmethod
-    def _render_yaml(title: str, description: str, body: str, source_id: str) -> str:
+
+    @classmethod
+    def _build_yaml_header(cls, title: str, description: str) -> dict[str, Any]:
+        """Build the base YAML header."""
+        header = {
+            "version": "1.0.0",
+            "title": title,
+            "description": description,
+            "author": {"contact": "spec-kit"},
+            "parameters": [
+                {
+                    "key": "args",
+                    "input_type": "string",
+                    "requirement": "optional",
+                    "default": "",
+                    "description": "User input passed to the command.",
+                }
+            ],
+            "extensions": [{"type": "builtin", "name": "developer"}],
+            "activities": ["Spec-Driven Development"],
+        }
+        return header
+
+    @classmethod
+    def _render_yaml(cls, title: str, description: str, body: str, source_id: str) -> str:
         """Render a YAML recipe file from title, description, and body.
 
         Produces a Goose-compatible recipe with a literal block scalar
         for the prompt content.  Uses ``yaml.safe_dump()`` for the
         header fields to ensure proper escaping.
         """
-        import yaml
-
-        header = {
-            "version": "1.0.0",
-            "title": title,
-            "description": description,
-            "author": {"contact": "spec-kit"},
-            "extensions": [{"type": "builtin", "name": "developer"}],
-            "activities": ["Spec-Driven Development"],
-        }
+        header = cls._build_yaml_header(title, description)
 
         header_yaml = yaml.safe_dump(
             header,
@@ -1219,12 +1242,20 @@ class YamlIntegration(IntegrationBase):
             default_flow_style=False,
         ).strip()
 
-        # Indent each line for YAML block scalar
+        # Indent the body for YAML block scalar
         indented = "\n".join(f"  {line}" for line in body.split("\n"))
 
-        lines = [header_yaml, "prompt: |", indented, "", f"# Source: {source_id}"]
+        lines = [
+            header_yaml,
+            "prompt: |",
+            indented,
+            "",
+            f"# Source: {source_id}",
+        ]
+
         return "\n".join(lines) + "\n"
 
+
     def setup(
         self,
         project_root: Path,
@@ -1383,7 +1414,6 @@ class SkillsIntegration(IntegrationBase):
         template.  Each SKILL.md has normalised frontmatter containing
         ``name``, ``description``, ``compatibility``, and ``metadata``.
         """
-        import yaml
 
         templates = self.list_command_templates()
         if not templates:

src/specify_cli/integrations/catalog.py

@@ -21,6 +21,8 @@ from typing import Any, Dict, List, Optional, Tuple
 import yaml
 from packaging import version as pkg_version
 
+from ..catalogs import CatalogEntry, CatalogStackBase
+
 
 # ---------------------------------------------------------------------------
 # Errors
@@ -43,21 +45,15 @@ class IntegrationDescriptorError(Exception):
 # ---------------------------------------------------------------------------
 
 @dataclass
-class IntegrationCatalogEntry:
+class IntegrationCatalogEntry(CatalogEntry):
     """Represents a single catalog source in the catalog stack."""
 
-    url: str
-    name: str
-    priority: int
-    install_allowed: bool
-    description: str = ""
-
 
 # ---------------------------------------------------------------------------
 # IntegrationCatalog
 # ---------------------------------------------------------------------------
 
-class IntegrationCatalog:
+class IntegrationCatalog(CatalogStackBase):
     """Manages integration catalog fetching, caching, and searching."""
 
     DEFAULT_CATALOG_URL = (
@@ -67,136 +63,15 @@ class IntegrationCatalog:
         "https://raw.githubusercontent.com/github/spec-kit/main/integrations/catalog.community.json"
     )
     CACHE_DURATION = 3600  # 1 hour
+    CONFIG_FILENAME = "integration-catalogs.yml"
+    ENTRY_CLASS = IntegrationCatalogEntry
+    ERROR_TYPE = IntegrationCatalogError
+    VALIDATION_ERROR_TYPE = IntegrationValidationError
 
     def __init__(self, project_root: Path) -> None:
         self.project_root = project_root
         self.cache_dir = project_root / ".specify" / "integrations" / ".cache"
 
-    # -- URL validation ---------------------------------------------------
-
-    @staticmethod
-    def _validate_catalog_url(url: str) -> None:
-        from urllib.parse import urlparse
-
-        parsed = urlparse(url)
-        is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
-        if parsed.scheme != "https" and not (parsed.scheme == "http" and is_localhost):
-            raise IntegrationCatalogError(
-                f"Catalog URL must use HTTPS (got {parsed.scheme}://). "
-                "HTTP is only allowed for localhost."
-            )
-        if not parsed.netloc:
-            raise IntegrationCatalogError(
-                "Catalog URL must be a valid URL with a host."
-            )
-
-    # -- Catalog stack ----------------------------------------------------
-
-    def _load_catalog_config(
-        self, config_path: Path
-    ) -> Optional[List[IntegrationCatalogEntry]]:
-        """Load catalog stack from a YAML file.
-
-        Returns None when the file does not exist.
-
-        Raises:
-            IntegrationValidationError: on any local-config / YAML problem
-                (parse failures, wrong shape, missing/invalid fields,
-                invalid catalog URLs, etc.). This is a subclass of
-                :class:`IntegrationCatalogError`, so any caller that already
-                catches ``IntegrationCatalogError`` keeps working — but
-                callers that want to distinguish *local config* problems
-                from *remote/network* problems can match the subclass.
-        """
-        if not config_path.exists():
-            return None
-        try:
-            data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
-        except (yaml.YAMLError, OSError, UnicodeError) as exc:
-            raise IntegrationValidationError(
-                f"Failed to read catalog config {config_path}: {exc}"
-            ) from exc
-        if data is None:
-            data = {}
-        if not isinstance(data, dict):
-            raise IntegrationValidationError(
-                f"Invalid catalog config {config_path}: expected a YAML mapping at the root"
-            )
-        catalogs_data = data.get("catalogs", [])
-        if not isinstance(catalogs_data, list):
-            raise IntegrationValidationError(
-                f"Invalid catalog config {config_path}: 'catalogs' must be a list, "
-                f"got {type(catalogs_data).__name__}"
-            )
-        if not catalogs_data:
-            raise IntegrationValidationError(
-                f"Catalog config {config_path} exists but contains no 'catalogs' entries. "
-                f"Remove the file to use built-in defaults, or add valid catalog entries."
-            )
-        entries: List[IntegrationCatalogEntry] = []
-        skipped: List[int] = []
-        for idx, item in enumerate(catalogs_data):
-            if not isinstance(item, dict):
-                raise IntegrationValidationError(
-                    f"Invalid catalog config {config_path}: catalog entry at index {idx}: "
-                    f"expected a mapping, got {type(item).__name__}"
-                )
-            url = str(item.get("url", "")).strip()
-            if not url:
-                skipped.append(idx)
-                continue
-            try:
-                self._validate_catalog_url(url)
-            except IntegrationCatalogError as exc:
-                # ``_validate_catalog_url`` raises the base class for direct
-                # callers (e.g. ``add_catalog`` validating user input); when
-                # the bad URL came from a local config file, surface it as a
-                # validation error so CLI handlers can route it accordingly.
-                raise IntegrationValidationError(
-                    f"Invalid catalog URL in {config_path} at index {idx}: {exc}"
-                ) from exc
-            raw_priority = item.get("priority", idx + 1)
-            if isinstance(raw_priority, bool):
-                raise IntegrationValidationError(
-                    f"Invalid catalog config {config_path}: "
-                    f"Invalid priority for catalog '{item.get('name', idx + 1)}': "
-                    f"expected integer, got {raw_priority!r}"
-                )
-            try:
-                priority = int(raw_priority)
-            except (TypeError, ValueError):
-                raise IntegrationValidationError(
-                    f"Invalid catalog config {config_path}: "
-                    f"Invalid priority for catalog '{item.get('name', idx + 1)}': "
-                    f"expected integer, got {raw_priority!r}"
-                )
-            raw_install = item.get("install_allowed", False)
-            if isinstance(raw_install, str):
-                install_allowed = raw_install.strip().lower() in ("true", "yes", "1")
-            else:
-                install_allowed = bool(raw_install)
-            raw_name = item.get("name")
-            name = str(raw_name).strip() if raw_name is not None else ""
-            if not name:
-                name = f"catalog-{len(entries) + 1}"
-            entries.append(
-                IntegrationCatalogEntry(
-                    url=url,
-                    name=name,
-                    priority=priority,
-                    install_allowed=install_allowed,
-                    description=str(item.get("description", "")),
-                )
-            )
-        entries.sort(key=lambda e: e.priority)
-        if not entries:
-            raise IntegrationValidationError(
-                f"Catalog config {config_path} contains {len(catalogs_data)} "
-                f"entries but none have valid URLs (entries at indices {skipped} "
-                f"were skipped). Each catalog entry must have a 'url' field."
-            )
-        return entries
-
     def get_active_catalogs(self) -> List[IntegrationCatalogEntry]:
         """Return the ordered list of active integration catalogs.
 
@@ -265,7 +140,6 @@ class IntegrationCatalog:
     ) -> Dict[str, Any]:
         """Fetch one catalog, with per-URL caching."""
         import urllib.error
-        import urllib.request
 
         url_hash = hashlib.sha256(entry.url.encode()).hexdigest()[:16]
         cache_file = self.cache_dir / f"catalog-{url_hash}.json"
@@ -289,7 +163,9 @@ class IntegrationCatalog:
                     pass  # Cache cleanup is best-effort; ignore deletion failures.
 
         try:
-            with urllib.request.urlopen(entry.url, timeout=10) as resp:
+            from specify_cli.authentication.http import open_url
+
+            with open_url(entry.url, timeout=10) as resp:
                 # Validate final URL after redirects
                 final_url = resp.geturl()
                 if final_url != entry.url:
@@ -443,8 +319,6 @@ class IntegrationCatalog:
 
     # -- Catalog-source management ----------------------------------------
 
-    CONFIG_FILENAME = "integration-catalogs.yml"
-
     def get_catalog_configs(self) -> List[Dict[str, Any]]:
         """Return the active catalog stack as a list of dicts.
 

src/specify_cli/integrations/claude/__init__.py

@@ -53,6 +53,7 @@ class ClaudeIntegration(SkillsIntegration):
         "extension": "/SKILL.md",
     }
     context_file = "CLAUDE.md"
+    multi_install_safe = True
 
     @staticmethod
     def inject_argument_hint(content: str, hint: str) -> str:

src/specify_cli/integrations/codebuddy/__init__.py

@@ -19,3 +19,4 @@ class CodebuddyIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = "CODEBUDDY.md"
+    multi_install_safe = True

src/specify_cli/integrations/codex/__init__.py

@@ -27,6 +27,7 @@ class CodexIntegration(SkillsIntegration):
         "extension": "/SKILL.md",
     }
     context_file = "AGENTS.md"
+    multi_install_safe = True
 
     def build_exec_args(
         self,

src/specify_cli/integrations/cursor_agent/__init__.py

@@ -26,6 +26,7 @@ class CursorAgentIntegration(SkillsIntegration):
     }
 
     context_file = ".cursor/rules/specify-rules.mdc"
+    multi_install_safe = True
 
     @classmethod
     def options(cls) -> list[IntegrationOption]:

src/specify_cli/integrations/forge/__init__.py

@@ -87,8 +87,10 @@ class ForgeIntegration(MarkdownIntegration):
         "strip_frontmatter_keys": ["handoffs"],
         "inject_name": True,
         "format_name": format_forge_command_name,  # Custom name formatter
+        "invoke_separator": "-",
     }
     context_file = "AGENTS.md"
+    invoke_separator = "-"
 
     def setup(
         self,
@@ -133,6 +135,7 @@ class ForgeIntegration(MarkdownIntegration):
             processed = self.process_template(
                 raw, self.key, script_type, arg_placeholder,
                 context_file=self.context_file or "",
+                invoke_separator=self.invoke_separator,
             )
 
             # FORGE-SPECIFIC: Ensure any remaining $ARGUMENTS placeholders are

src/specify_cli/integrations/gemini/__init__.py

@@ -19,3 +19,4 @@ class GeminiIntegration(TomlIntegration):
         "extension": ".toml",
     }
     context_file = "GEMINI.md"
+    multi_install_safe = True

src/specify_cli/integrations/iflow/__init__.py

@@ -19,3 +19,4 @@ class IflowIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = "IFLOW.md"
+    multi_install_safe = True

src/specify_cli/integrations/junie/__init__.py

@@ -19,3 +19,4 @@ class JunieIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = ".junie/AGENTS.md"
+    multi_install_safe = True

src/specify_cli/integrations/kilocode/__init__.py

@@ -19,3 +19,4 @@ class KilocodeIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = ".kilocode/rules/specify-rules.md"
+    multi_install_safe = True

src/specify_cli/integrations/kimi/__init__.py

@@ -36,6 +36,7 @@ class KimiIntegration(SkillsIntegration):
         "extension": "/SKILL.md",
     }
     context_file = "KIMI.md"
+    multi_install_safe = True
 
     @classmethod
     def options(cls) -> list[IntegrationOption]:

src/specify_cli/integrations/kiro_cli/__init__.py

@@ -3,6 +3,14 @@
 from ..base import MarkdownIntegration
 
 
+# Kiro CLI file-based prompts do NOT support any argument-substitution syntax,
+# so a raw "$ARGUMENTS" token would reach the model verbatim and break the
+# prompt (issue #1926, kirodotdev/Kiro#4141). Use a prose fallback so the
+# rendered prompt instructs the model to take its argument from the user's
+# next message.
+_KIRO_ARG_FALLBACK = "(the user will provide the argument in this conversation)"
+
+
 class KiroCliIntegration(MarkdownIntegration):
     key = "kiro-cli"
     config = {
@@ -15,7 +23,7 @@ class KiroCliIntegration(MarkdownIntegration):
     registrar_config = {
         "dir": ".kiro/prompts",
         "format": "markdown",
-        "args": "$ARGUMENTS",
+        "args": _KIRO_ARG_FALLBACK,
         "extension": ".md",
     }
     context_file = "AGENTS.md"

src/specify_cli/integrations/lingma/__init__.py

@@ -0,0 +1,41 @@
+"""Lingma IDE integration. — skills-based agent.
+
+Lingma IDE uses ``.lingma/skills/speckit-<name>/SKILL.md`` layout.
+In Specify CLI, the Lingma integration is skills-only, and ``--skills``
+defaults to ``True``.
+"""
+
+from __future__ import annotations
+
+from ..base import IntegrationOption, SkillsIntegration
+
+
+class LingmaIntegration(SkillsIntegration):
+    """Integration for Lingma IDE."""
+
+    key = "lingma"
+    config = {
+        "name": "Lingma",
+        "folder": ".lingma/",
+        "commands_subdir": "skills",
+        "install_url": None,
+        "requires_cli": False,
+    }
+    registrar_config = {
+        "dir": ".lingma/skills",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": "/SKILL.md",
+    }
+    context_file = ".lingma/rules/specify-rules.md"
+
+    @classmethod
+    def options(cls) -> list[IntegrationOption]:
+        return [
+            IntegrationOption(
+                "--skills",
+                is_flag=True,
+                default=True,
+                help="Install as agent skills",
+            ),
+        ]

src/specify_cli/integrations/manifest.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import hashlib
 import json
 import os
+import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
@@ -47,6 +48,59 @@ def _validate_rel_path(rel: Path, root: Path) -> Path:
     return resolved
 
 
+def _manifest_path_label(root: Path, path: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def _ensure_safe_manifest_directory(root: Path, directory: Path) -> None:
+    """Create a manifest directory without following symlinked parents."""
+    root_resolved = root.resolve()
+    try:
+        rel = directory.relative_to(root)
+    except ValueError:
+        label = _manifest_path_label(root, directory)
+        raise ValueError(f"Integration manifest directory escapes project root: {label}") from None
+
+    current = root
+    for part in rel.parts:
+        current = current / part
+        label = _manifest_path_label(root, current)
+        if current.is_symlink():
+            raise ValueError(f"Refusing to use symlinked integration manifest directory: {label}")
+        if current.exists():
+            if not current.is_dir():
+                raise ValueError(f"Integration manifest directory path is not a directory: {label}")
+            try:
+                current.resolve().relative_to(root_resolved)
+            except (OSError, ValueError):
+                raise ValueError(f"Integration manifest directory escapes project root: {label}") from None
+            continue
+        current.mkdir()
+        try:
+            current.resolve().relative_to(root_resolved)
+        except (OSError, ValueError):
+            raise ValueError(f"Integration manifest directory escapes project root: {label}") from None
+
+
+def _ensure_safe_manifest_destination(root: Path, path: Path) -> None:
+    """Refuse manifest writes that would escape the project or follow symlinks."""
+    root_resolved = root.resolve()
+    _ensure_safe_manifest_directory(root, path.parent)
+    label = _manifest_path_label(root, path)
+    if path.is_symlink():
+        raise ValueError(f"Refusing to overwrite symlinked integration manifest path: {label}")
+    if path.exists():
+        if not path.is_file():
+            raise ValueError(f"Integration manifest path is not a file: {label}")
+        try:
+            path.resolve().relative_to(root_resolved)
+        except (OSError, ValueError):
+            raise ValueError(f"Integration manifest path escapes project root: {label}") from None
+
+
 class IntegrationManifest:
     """Tracks files installed by a single integration.
 
@@ -217,8 +271,19 @@ class IntegrationManifest:
             "files": self._files,
         }
         path = self.manifest_path
-        path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+        content = json.dumps(data, indent=2) + "\n"
+        _ensure_safe_manifest_destination(self.project_root, path)
+        fd, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+        temp_path = Path(temp_name)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(content)
+            temp_path.chmod(0o644)
+            _ensure_safe_manifest_destination(self.project_root, path)
+            os.replace(temp_path, path)
+        finally:
+            if temp_path.exists():
+                temp_path.unlink()
         return path
 
     @classmethod

src/specify_cli/integrations/qodercli/__init__.py

@@ -19,3 +19,4 @@ class QodercliIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = "QODER.md"
+    multi_install_safe = True

src/specify_cli/integrations/qwen/__init__.py

@@ -19,3 +19,4 @@ class QwenIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = "QWEN.md"
+    multi_install_safe = True

src/specify_cli/integrations/roo/__init__.py

@@ -19,3 +19,4 @@ class RooIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = ".roo/rules/specify-rules.md"
+    multi_install_safe = True

src/specify_cli/integrations/shai/__init__.py

@@ -19,3 +19,4 @@ class ShaiIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = "SHAI.md"
+    multi_install_safe = True

src/specify_cli/integrations/tabnine/__init__.py

@@ -19,3 +19,4 @@ class TabnineIntegration(TomlIntegration):
         "extension": ".toml",
     }
     context_file = "TABNINE.md"
+    multi_install_safe = True

src/specify_cli/integrations/trae/__init__.py

@@ -27,6 +27,7 @@ class TraeIntegration(SkillsIntegration):
         "extension": "/SKILL.md",
     }
     context_file = ".trae/rules/project_rules.md"
+    multi_install_safe = True
 
     @classmethod
     def options(cls) -> list[IntegrationOption]:

src/specify_cli/integrations/windsurf/__init__.py

@@ -19,3 +19,4 @@ class WindsurfIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = ".windsurf/rules/specify-rules.md"
+    multi_install_safe = True

src/specify_cli/presets.py

@@ -1845,20 +1845,20 @@ class PresetCatalog:
             )
 
     def _make_request(self, url: str):
-        """Build a urllib Request, adding a GitHub auth header when available.
+        """Build a urllib Request, adding auth headers when a provider matches.
 
-        Delegates to :func:`specify_cli._github_http.build_github_request`.
+        Delegates to :func:`specify_cli.authentication.http.build_request`.
         """
-        from specify_cli._github_http import build_github_request
-        return build_github_request(url)
+        from specify_cli.authentication.http import build_request
+        return build_request(url)
 
     def _open_url(self, url: str, timeout: int = 10):
-        """Open a URL with GitHub auth, stripping the header on cross-host redirects.
+        """Open a URL with provider-based auth, trying each configured provider.
 
-        Delegates to :func:`specify_cli._github_http.open_github_url`.
+        Delegates to :func:`specify_cli.authentication.http.open_url`.
         """
-        from specify_cli._github_http import open_github_url
-        return open_github_url(url, timeout)
+        from specify_cli.authentication.http import open_url
+        return open_url(url, timeout)
 
     def _load_catalog_config(self, config_path: Path) -> Optional[List[PresetCatalogEntry]]:
         """Load catalog stack configuration from a YAML file.

src/specify_cli/shared_infra.py

@@ -0,0 +1,441 @@
+"""Shared Spec Kit infrastructure installation helpers."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from .integrations.base import IntegrationBase
+from .integrations.manifest import IntegrationManifest
+
+
+class SymlinkedSharedPathError(ValueError):
+    """Raised when a shared infrastructure path or ancestor is a symlink.
+
+    Distinct from other unsafe-path errors so callers can preserve symlinked
+    destinations as customizations while still letting genuine safety errors
+    (e.g. path escape, not-a-directory) propagate and abort the operation.
+    """
+
+
+def load_speckit_manifest(
+    project_path: Path,
+    *,
+    version: str,
+    console: Any | None = None,
+) -> IntegrationManifest:
+    """Load the shared infrastructure manifest, preserving existing entries."""
+    manifest_path = project_path / ".specify" / "integrations" / "speckit.manifest.json"
+    if manifest_path.exists():
+        try:
+            manifest = IntegrationManifest.load("speckit", project_path)
+            manifest.version = version
+            return manifest
+        except (ValueError, FileNotFoundError, OSError, UnicodeDecodeError) as exc:
+            if console is not None:
+                console.print(
+                    f"[yellow]Warning:[/yellow] Could not read shared infrastructure "
+                    f"manifest at {manifest_path}: {exc}"
+                )
+                console.print(
+                    "A new shared manifest will be created; previously tracked "
+                    "shared files may be treated as untracked."
+                )
+    return IntegrationManifest("speckit", project_path, version=version)
+
+
+def shared_templates_source(
+    *,
+    core_pack: Path | None,
+    repo_root: Path,
+) -> Path:
+    """Return the bundled/source shared templates directory."""
+    if core_pack and (core_pack / "templates").is_dir():
+        return core_pack / "templates"
+    return repo_root / "templates"
+
+
+def shared_scripts_source(
+    *,
+    core_pack: Path | None,
+    repo_root: Path,
+) -> Path:
+    """Return the bundled/source shared scripts directory."""
+    if core_pack and (core_pack / "scripts").is_dir():
+        return core_pack / "scripts"
+    return repo_root / "scripts"
+
+
+def _shared_destination_label(project_path: Path, dest: Path) -> str:
+    try:
+        return dest.relative_to(project_path).as_posix()
+    except ValueError:
+        return str(dest)
+
+
+def _shared_relative_path(project_path: Path, dest: Path) -> Path:
+    try:
+        rel = dest.relative_to(project_path)
+    except ValueError:
+        label = _shared_destination_label(project_path, dest)
+        raise ValueError(f"Shared infrastructure path escapes project root: {label}") from None
+
+    if rel.is_absolute() or ".." in rel.parts:
+        label = _shared_destination_label(project_path, dest)
+        raise ValueError(f"Shared infrastructure path escapes project root: {label}")
+    return rel
+
+
+def _ensure_safe_shared_directory(project_path: Path, directory: Path, *, create: bool = True) -> None:
+    """Create a shared infra directory without following symlinked parents."""
+    root = project_path.resolve()
+    rel = _shared_relative_path(project_path, directory)
+    current = project_path
+
+    for part in rel.parts:
+        current = current / part
+        label = _shared_destination_label(project_path, current)
+        if current.is_symlink():
+            raise SymlinkedSharedPathError(f"Refusing to use symlinked shared infrastructure directory: {label}")
+        if current.exists():
+            if not current.is_dir():
+                raise ValueError(f"Shared infrastructure directory path is not a directory: {label}")
+            try:
+                current.resolve().relative_to(root)
+            except (OSError, ValueError):
+                raise ValueError(f"Shared infrastructure directory escapes project root: {label}") from None
+            continue
+        if not create:
+            raise ValueError(f"Shared infrastructure directory does not exist: {label}")
+        current.mkdir()
+        if current.is_symlink():
+            raise SymlinkedSharedPathError(f"Refusing to use symlinked shared infrastructure directory: {label}")
+        try:
+            current.resolve().relative_to(root)
+        except (OSError, ValueError):
+            raise ValueError(f"Shared infrastructure directory escapes project root: {label}") from None
+
+
+def _validate_safe_shared_directory(project_path: Path, directory: Path) -> None:
+    """Validate existing directory parents while allowing missing directories."""
+    root = project_path.resolve()
+    rel = _shared_relative_path(project_path, directory)
+    current = project_path
+
+    for part in rel.parts:
+        current = current / part
+        label = _shared_destination_label(project_path, current)
+        if current.is_symlink():
+            raise SymlinkedSharedPathError(f"Refusing to use symlinked shared infrastructure directory: {label}")
+        if not current.exists():
+            continue
+        if not current.is_dir():
+            raise ValueError(f"Shared infrastructure directory path is not a directory: {label}")
+        try:
+            current.resolve().relative_to(root)
+        except (OSError, ValueError):
+            raise ValueError(f"Shared infrastructure directory escapes project root: {label}") from None
+
+
+def _ensure_safe_shared_destination(
+    project_path: Path,
+    dest: Path,
+    *,
+    parent_must_exist: bool = True,
+) -> None:
+    """Refuse shared infra writes that would escape or follow symlinks."""
+    root = project_path.resolve()
+    _shared_relative_path(project_path, dest)
+    if parent_must_exist:
+        _ensure_safe_shared_directory(project_path, dest.parent, create=False)
+    else:
+        _validate_safe_shared_directory(project_path, dest.parent)
+    label = _shared_destination_label(project_path, dest)
+    if dest.is_symlink():
+        raise SymlinkedSharedPathError(f"Refusing to overwrite symlinked shared infrastructure path: {label}")
+
+    if dest.exists():
+        try:
+            dest.resolve().relative_to(root)
+        except (OSError, ValueError):
+            raise ValueError(f"Shared infrastructure destination escapes project root: {label}") from None
+
+
+def _write_shared_text(project_path: Path, dest: Path, content: str) -> None:
+    _write_shared_bytes(project_path, dest, content.encode("utf-8"))
+
+
+def _write_shared_bytes(
+    project_path: Path,
+    dest: Path,
+    content: bytes,
+    *,
+    mode: int = 0o644,
+) -> None:
+    _ensure_safe_shared_destination(project_path, dest)
+    fd, temp_name = tempfile.mkstemp(prefix=f".{dest.name}.", dir=dest.parent)
+    temp_path = Path(temp_name)
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(content)
+        temp_path.chmod(mode)
+        _ensure_safe_shared_destination(project_path, dest)
+        os.replace(temp_path, dest)
+    finally:
+        if temp_path.exists():
+            temp_path.unlink()
+
+
+def refresh_shared_templates(
+    project_path: Path,
+    *,
+    version: str,
+    core_pack: Path | None,
+    repo_root: Path,
+    console: Any,
+    invoke_separator: str,
+    force: bool = False,
+) -> None:
+    """Refresh default-sensitive shared templates without touching scripts."""
+    templates_src = shared_templates_source(core_pack=core_pack, repo_root=repo_root)
+    if not templates_src.is_dir():
+        return
+
+    manifest = load_speckit_manifest(project_path, version=version, console=console)
+    tracked_files = manifest.files
+    modified = set(manifest.check_modified())
+    skipped_files: list[str] = []
+    planned_updates: list[tuple[Path, str, str]] = []
+
+    dest_templates = project_path / ".specify" / "templates"
+    _ensure_safe_shared_directory(project_path, dest_templates)
+    for src in templates_src.iterdir():
+        if not src.is_file() or src.name == "vscode-settings.json" or src.name.startswith("."):
+            continue
+
+        dst = dest_templates / src.name
+        _ensure_safe_shared_destination(project_path, dst)
+        rel = dst.relative_to(project_path).as_posix()
+        if dst.exists() and not force:
+            if rel not in tracked_files or rel in modified:
+                skipped_files.append(rel)
+                continue
+
+        content = src.read_text(encoding="utf-8")
+        content = IntegrationBase.resolve_command_refs(content, invoke_separator)
+        planned_updates.append((dst, rel, content))
+
+    for dst, rel, content in planned_updates:
+        _write_shared_text(project_path, dst, content)
+        manifest.record_existing(rel)
+
+    manifest.save()
+
+    if skipped_files:
+        console.print(
+            f"[yellow]⚠[/yellow]  {len(skipped_files)} modified or untracked shared template file(s) were not updated:"
+        )
+        for rel in skipped_files:
+            console.print(f"    {rel}")
+
+
+def install_shared_infra(
+    project_path: Path,
+    script_type: str,
+    *,
+    version: str,
+    core_pack: Path | None,
+    repo_root: Path,
+    console: Any,
+    force: bool = False,
+    invoke_separator: str = ".",
+    refresh_managed: bool = False,
+    refresh_hint: str | None = None,
+) -> bool:
+    """Install shared scripts and templates into *project_path*.
+
+    When ``refresh_managed`` is True, files whose on-disk hash still matches
+    the previously recorded manifest hash are overwritten with the bundled
+    version. Files whose hash diverges are treated as user customizations and
+    preserved with a warning. ``force=True`` overwrites every regular file
+    (symlinks and symlinked-parent destinations are always preserved with a
+    warning — the safe-destination check refuses to follow them so writes
+    cannot escape the project root). ``refresh_hint`` is shown after the
+    customization warning to tell the user which flag would overwrite their
+    customizations.
+    """
+    from .integrations.manifest import _sha256
+
+    manifest = load_speckit_manifest(project_path, version=version, console=console)
+    prior_hashes = dict(manifest.files)
+
+    def _is_managed(rel: str, dst: Path) -> bool:
+        expected = prior_hashes.get(rel)
+        if not expected or not dst.is_file() or dst.is_symlink():
+            return False
+        try:
+            return _sha256(dst) == expected
+        except OSError:
+            return False
+
+    skipped_files: list[str] = []
+    preserved_user_files: list[str] = []
+    symlinked_files: list[str] = []
+    planned_copies: list[tuple[Path, str, bytes, int]] = []
+    planned_templates: list[tuple[Path, str, str]] = []
+
+    def _decide_overwrite(rel: str, dst: Path) -> tuple[bool, str | None]:
+        """Return (write, bucket) where bucket is 'skip', 'preserved', or None."""
+        if not dst.exists():
+            return True, None
+        if force:
+            return True, None
+        if refresh_managed:
+            if _is_managed(rel, dst):
+                return True, None
+            if rel in prior_hashes:
+                return False, "preserved"
+            return False, "skip"
+        return False, "skip"
+
+    def _safe_dest_or_bucket(dst: Path, rel: str, *, parent_must_exist: bool = True) -> bool:
+        """Run the safe-destination check and bucket symlinked paths.
+
+        Returns True when the destination is safe to consider (write or skip).
+        Returns False (and records *rel* under ``symlinked_files``) when the
+        destination or any of its ancestors is a symlink — those paths can't
+        be written to safely, but they shouldn't abort the whole switch
+        either. They're surfaced as a separate "symlinked" warning bucket.
+
+        Other unsafe-path errors (e.g. path escape, parent-not-a-directory)
+        are NOT caught here: they re-raise so the operation aborts, since
+        treating them as "symlinked" would mask security-relevant failures.
+        """
+        try:
+            _ensure_safe_shared_destination(project_path, dst, parent_must_exist=parent_must_exist)
+        except SymlinkedSharedPathError:
+            symlinked_files.append(rel)
+            return False
+        return True
+
+    def _ensure_or_bucket_dir(directory: Path) -> bool:
+        """Create *directory* unless an ancestor is symlinked.
+
+        Returns True when the directory is safe to use. Returns False (and
+        records the path under ``symlinked_files``) when a symlink ancestor
+        forces us to skip the whole subtree. Other unsafe-path errors
+        (escape, not-a-directory) re-raise so the operation aborts.
+        """
+        try:
+            _ensure_safe_shared_directory(project_path, directory)
+        except SymlinkedSharedPathError:
+            symlinked_files.append(directory.relative_to(project_path).as_posix())
+            return False
+        return True
+
+    scripts_src = shared_scripts_source(core_pack=core_pack, repo_root=repo_root)
+    if scripts_src.is_dir():
+        dest_scripts = project_path / ".specify" / "scripts"
+        if _ensure_or_bucket_dir(dest_scripts):
+            variant_dir = "bash" if script_type == "sh" else "powershell"
+            variant_src = scripts_src / variant_dir
+            if variant_src.is_dir():
+                dest_variant = dest_scripts / variant_dir
+                if _ensure_or_bucket_dir(dest_variant):
+                    for src_path in variant_src.rglob("*"):
+                        if not src_path.is_file():
+                            continue
+
+                        rel_path = src_path.relative_to(variant_src)
+                        dst_path = dest_variant / rel_path
+                        rel = dst_path.relative_to(project_path).as_posix()
+                        if not _safe_dest_or_bucket(dst_path, rel, parent_must_exist=False):
+                            continue
+                        write, bucket = _decide_overwrite(rel, dst_path)
+                        if not write:
+                            if bucket == "preserved":
+                                preserved_user_files.append(rel)
+                            else:
+                                skipped_files.append(rel)
+                            continue
+
+                        if not _ensure_or_bucket_dir(dst_path.parent):
+                            continue
+                        planned_copies.append((dst_path, rel, src_path.read_bytes(), src_path.stat().st_mode & 0o777))
+
+    templates_src = shared_templates_source(core_pack=core_pack, repo_root=repo_root)
+    if templates_src.is_dir():
+        dest_templates = project_path / ".specify" / "templates"
+        if _ensure_or_bucket_dir(dest_templates):
+            for src in templates_src.iterdir():
+                if not src.is_file() or src.name == "vscode-settings.json" or src.name.startswith("."):
+                    continue
+
+                dst = dest_templates / src.name
+                rel = dst.relative_to(project_path).as_posix()
+                if not _safe_dest_or_bucket(dst, rel):
+                    continue
+                write, bucket = _decide_overwrite(rel, dst)
+                if not write:
+                    if bucket == "preserved":
+                        preserved_user_files.append(rel)
+                    else:
+                        skipped_files.append(rel)
+                    continue
+
+                content = src.read_text(encoding="utf-8")
+                content = IntegrationBase.resolve_command_refs(content, invoke_separator)
+                planned_templates.append((dst, rel, content))
+
+    for dst_path, rel, content, mode in planned_copies:
+        if not _ensure_or_bucket_dir(dst_path.parent):
+            continue
+        _write_shared_bytes(project_path, dst_path, content, mode=mode)
+        manifest.record_existing(rel)
+
+    for dst, rel, content in planned_templates:
+        _write_shared_text(project_path, dst, content)
+        manifest.record_existing(rel)
+
+    if skipped_files:
+        console.print(
+            f"[yellow]⚠[/yellow]  {len(skipped_files)} shared infrastructure file(s) already exist and were not updated:"
+        )
+        for path in skipped_files:
+            console.print(f"    {path}")
+        if refresh_managed and refresh_hint:
+            console.print(refresh_hint)
+        else:
+            console.print(
+                "To refresh shared infrastructure, run "
+                "[cyan]specify init --here --force[/cyan] or "
+                "[cyan]specify integration upgrade --force[/cyan]."
+            )
+
+    if symlinked_files:
+        console.print(
+            f"[yellow]⚠[/yellow]  Skipped {len(symlinked_files)} symlinked shared "
+            "infrastructure path(s) — symlinks are never overwritten because they "
+            "may resolve outside the project root:"
+        )
+        for path in symlinked_files:
+            console.print(f"    {path}")
+        console.print(
+            "To restore the bundled version, remove or replace the symlink manually, "
+            "then re-run the command."
+        )
+
+    if preserved_user_files:
+        console.print(
+            f"[yellow]⚠[/yellow]  Preserved {len(preserved_user_files)} customized shared "
+            "infrastructure file(s) (hash differs from previous install):"
+        )
+        for path in preserved_user_files:
+            console.print(f"    {path}")
+        if refresh_hint:
+            console.print(refresh_hint)
+
+    manifest.save()
+    return True

src/specify_cli/workflows/catalog.py

@@ -322,7 +322,7 @@ class WorkflowCatalog:
 
         # Fetch from URL — validate scheme before opening and after redirects
         from urllib.parse import urlparse
-        from urllib.request import urlopen
+        from specify_cli.authentication.http import open_url as _open_url
 
         def _validate_catalog_url(url: str) -> None:
             parsed = urlparse(url)
@@ -337,7 +337,7 @@ class WorkflowCatalog:
         _validate_catalog_url(entry.url)
 
         try:
-            with urlopen(entry.url, timeout=30) as resp:  # noqa: S310
+            with _open_url(entry.url, timeout=30) as resp:
                 _validate_catalog_url(resp.geturl())
                 data = json.loads(resp.read().decode("utf-8"))
         except Exception as exc:

templates/commands/implement.md

@@ -88,6 +88,7 @@ You **MUST** consider the user input before proceeding (if not empty).
    - **IF EXISTS**: Read data-model.md for entities and relationships
    - **IF EXISTS**: Read contracts/ for API specifications and test requirements
    - **IF EXISTS**: Read research.md for technical decisions and constraints
+   - **IF EXISTS**: Read /memory/constitution.md for governance constraints
    - **IF EXISTS**: Read quickstart.md for integration scenarios
 
 4. **Project Setup Verification**:

templates/commands/specify.md

@@ -183,7 +183,7 @@ Given that feature description, do this:
 
    c. **Handle Validation Results**:
 
-      - **If all items pass**: Mark checklist complete and proceed to step 7
+      - **If all items pass**: Mark checklist complete and proceed to step 8
 
       - **If items fail (excluding [NEEDS CLARIFICATION])**:
         1. List the failing items and specific issues

templates/commands/tasks.md

@@ -10,8 +10,8 @@ handoffs:
     prompt: Start the implementation in phases
     send: true
 scripts:
-  sh: scripts/bash/check-prerequisites.sh --json
-  ps: scripts/powershell/check-prerequisites.ps1 -Json
+  sh: scripts/bash/setup-tasks.sh --json
+  ps: scripts/powershell/setup-tasks.ps1 -Json
 ---
 
 ## User Input
@@ -58,7 +58,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Outline
 
-1. **Setup**: Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+1. **Setup**: Run `{SCRIPT}` from repo root and parse FEATURE_DIR, TASKS_TEMPLATE, and AVAILABLE_DOCS list. `FEATURE_DIR` and `TASKS_TEMPLATE` must be absolute paths when provided. `AVAILABLE_DOCS` is a list of document names/relative paths available under `FEATURE_DIR` (for example `research.md` or `contracts/`). For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
 
 2. **Load design documents**: Read from FEATURE_DIR:
    - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
@@ -76,7 +76,7 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Create parallel execution examples per user story
    - Validate task completeness (each user story has all needed tasks, independently testable)
 
-4. **Generate tasks.md**: Use `templates/tasks-template.md` as structure, fill with:
+4. **Generate tasks.md**: Read the tasks template from TASKS_TEMPLATE (from the JSON output above) and use it as structure. If TASKS_TEMPLATE is empty, fall back to `.specify/templates/tasks-template.md`. Fill with:
    - Correct feature name from plan.md
    - Phase 1: Setup tasks (project initialization)
    - Phase 2: Foundational tasks (blocking prerequisites for all user stories)

templates/plan-template.md

@@ -1,6 +1,7 @@
 # Implementation Plan: [FEATURE]
 
 **Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+
 **Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
 
 **Note**: This template is filled in by the `__SPECKIT_COMMAND_PLAN__` command. See `.specify/templates/plan-template.md` for the execution workflow.
@@ -17,14 +18,22 @@
   the iteration process.
 -->
 
-**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
-**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
-**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
-**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
+
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
+
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
+
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
+
 **Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
-**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION]  
-**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
-**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+
+**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION]
+
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
+
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
+
 **Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
 
 ## Constitution Check

templates/spec-template.md

@@ -1,8 +1,11 @@
 # Feature Specification: [FEATURE NAME]
 
-**Feature Branch**: `[###-feature-name]`  
-**Created**: [DATE]  
-**Status**: Draft  
+**Feature Branch**: `[###-feature-name]`
+
+**Created**: [DATE]
+
+**Status**: Draft
+
 **Input**: User description: "$ARGUMENTS"
 
 ## User Scenarios & Testing *(mandatory)*
@@ -11,7 +14,7 @@
   IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
   Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
   you should still have a viable MVP (Minimum Viable Product) that delivers value.
-  
+
   Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
   Think of each story as a standalone slice of functionality that can be:
   - Developed independently
@@ -85,7 +88,7 @@
 ### Functional Requirements
 
 - **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
-- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
 - **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
 - **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
 - **FR-005**: System MUST [behavior, e.g., "log all security events"]

templates/tasks-template.md

@@ -6,6 +6,7 @@ description: "Task list template for feature implementation"
 # Tasks: [FEATURE NAME]
 
 **Input**: Design documents from `/specs/[###-feature-name]/`
+
 **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
 
 **Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
@@ -25,21 +26,21 @@ description: "Task list template for feature implementation"
 - **Mobile**: `api/src/`, `ios/src/` or `android/src/`
 - Paths shown below assume single project - adjust based on plan.md structure
 
-<!-- 
+<!--
   ============================================================================
   IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
-  
+
   The __SPECKIT_COMMAND_TASKS__ command MUST replace these with actual tasks based on:
   - User stories from spec.md (with their priorities P1, P2, P3...)
   - Feature requirements from plan.md
   - Entities from data-model.md
   - Endpoints from contracts/
-  
+
   Tasks MUST be organized by user story so each story can be:
   - Implemented independently
   - Tested independently
   - Delivered as an MVP increment
-  
+
   DO NOT keep these sample tasks in the generated tasks.md file.
   ============================================================================
 -->

tests/auth_helpers.py

@@ -0,0 +1,21 @@
+"""Shared test helpers for authentication config injection."""
+
+from __future__ import annotations
+
+from specify_cli.authentication.config import AuthConfigEntry
+
+
+def make_github_auth_entry(token_env: str = "GH_TOKEN") -> AuthConfigEntry:
+    """Build a GitHub ``AuthConfigEntry`` for testing."""
+    return AuthConfigEntry(
+        hosts=("github.com", "api.github.com", "raw.githubusercontent.com", "codeload.github.com"),
+        provider="github",
+        auth="bearer",
+        token_env=token_env,
+    )
+
+
+def inject_github_config(monkeypatch, token_env: str = "GH_TOKEN") -> None:
+    """Inject a GitHub auth.json config entry into the auth HTTP module."""
+    from specify_cli.authentication import http as _auth_http
+    monkeypatch.setattr(_auth_http, "_config_override", [make_github_auth_entry(token_env)])

tests/conftest.py

@@ -66,3 +66,18 @@ requires_bash = pytest.mark.skipif(
 def strip_ansi(text: str) -> str:
     """Remove ANSI escape codes from Rich-formatted CLI output."""
     return _ANSI_ESCAPE_RE.sub("", text)
+
+
+# ---------------------------------------------------------------------------
+# Auth config isolation — prevents tests from reading ~/.specify/auth.json
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(autouse=True)
+def _isolate_auth_config(monkeypatch):
+    """Ensure no test reads the real ~/.specify/auth.json."""
+    from specify_cli.authentication import http as _auth_http
+    monkeypatch.setattr(_auth_http, "_config_override", [])
+    # Also clear the per-process cache so tests that unset _config_override
+    # won't see a previously cached real-file result.
+    monkeypatch.setattr(_auth_http, "_config_cache", None)

tests/integrations/test_cli.py

@@ -1,13 +1,21 @@
 """Tests for --integration flag on specify init (CLI-level)."""
 
+import io
 import json
 import os
 
+import pytest
 import yaml
+from rich.console import Console
 
 from tests.conftest import strip_ansi
 
 
+class _NoopConsole:
+    def print(self, *args, **kwargs):
+        pass
+
+
 def _normalize_cli_output(output: str) -> str:
     output = strip_ansi(output)
     output = " ".join(output.split())
@@ -73,6 +81,29 @@ class TestInitIntegrationFlag:
         shared_manifest = project / ".specify" / "integrations" / "speckit.manifest.json"
         assert shared_manifest.exists()
 
+    def test_noninteractive_init_defaults_to_copilot(self, tmp_path, monkeypatch):
+        from typer.testing import CliRunner
+        from specify_cli import app
+        import specify_cli
+
+        def fail_select(*_args, **_kwargs):
+            raise AssertionError("non-interactive init should not open the integration picker")
+
+        monkeypatch.setattr(specify_cli, "select_with_arrows", fail_select)
+
+        runner = CliRunner()
+        project = tmp_path / "noninteractive"
+        result = runner.invoke(app, [
+            "init", str(project), "--script", "sh", "--no-git", "--ignore-agent-tools",
+        ], catch_exceptions=False)
+
+        assert result.exit_code == 0, result.output
+        assert f"defaulting to '{specify_cli.DEFAULT_INIT_INTEGRATION}'" in result.output
+        assert (project / ".github" / "agents" / "speckit.plan.agent.md").exists()
+
+        data = json.loads((project / ".specify" / "integration.json").read_text(encoding="utf-8"))
+        assert data["integration"] == specify_cli.DEFAULT_INIT_INTEGRATION
+
     def test_ai_copilot_auto_promotes(self, tmp_path):
         from typer.testing import CliRunner
         from specify_cli import app
@@ -254,6 +285,314 @@ class TestInitIntegrationFlag:
         normalized = " ".join(captured.out.split())
         assert "specify integration upgrade --force" in normalized
 
+    def test_shared_infra_warns_when_manifest_cannot_be_loaded(self, tmp_path, capsys):
+        """Invalid shared manifests warn before falling back to a new manifest."""
+        from specify_cli import _install_shared_infra
+
+        project = tmp_path / "bad-shared-manifest-test"
+        project.mkdir()
+        integrations_dir = project / ".specify" / "integrations"
+        integrations_dir.mkdir(parents=True)
+        manifest_path = integrations_dir / "speckit.manifest.json"
+        manifest_path.write_text("{not json", encoding="utf-8")
+
+        _install_shared_infra(project, "sh")
+
+        captured = capsys.readouterr()
+        assert "Could not read shared infrastructure manifest" in captured.out
+        assert "A new shared manifest will be created" in captured.out
+
+    def test_shared_infra_warns_when_manifest_cannot_be_decoded(self, tmp_path, capsys):
+        """Non-UTF-8 shared manifests warn before falling back to a new manifest."""
+        from specify_cli import _install_shared_infra
+
+        project = tmp_path / "bad-shared-manifest-encoding-test"
+        project.mkdir()
+        integrations_dir = project / ".specify" / "integrations"
+        integrations_dir.mkdir(parents=True)
+        manifest_path = integrations_dir / "speckit.manifest.json"
+        manifest_path.write_bytes(b"\xff\xfe\x00")
+
+        _install_shared_infra(project, "sh")
+
+        captured = capsys.readouterr()
+        assert "Could not read shared infrastructure manifest" in captured.out
+        assert "A new shared manifest will be created" in captured.out
+
+    @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+    def test_shared_infra_buckets_symlinked_script_destination(self, tmp_path, capsys):
+        """Symlinked script destinations are bucketed with a warning; the symlink target is preserved."""
+        from specify_cli import _install_shared_infra
+
+        project = tmp_path / "symlink-script-test"
+        project.mkdir()
+        (project / ".specify").mkdir()
+
+        outside = tmp_path / "outside-script.sh"
+        outside.write_text("# outside\n", encoding="utf-8")
+        scripts_dir = project / ".specify" / "scripts" / "bash"
+        scripts_dir.mkdir(parents=True)
+        os.symlink(outside, scripts_dir / "common.sh")
+
+        _install_shared_infra(project, "sh", force=True)
+
+        captured = capsys.readouterr()
+        assert "symlinked shared infrastructure" in captured.out
+        assert outside.read_text(encoding="utf-8") == "# outside\n"
+
+    @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+    def test_shared_infra_buckets_symlinked_template_destination(self, tmp_path, capsys):
+        """Symlinked template destinations are bucketed with a warning; the symlink target is preserved."""
+        from specify_cli import _install_shared_infra
+
+        project = tmp_path / "symlink-template-test"
+        project.mkdir()
+        (project / ".specify").mkdir()
+
+        outside = tmp_path / "outside-template.md"
+        outside.write_text("# outside\n", encoding="utf-8")
+        templates_dir = project / ".specify" / "templates"
+        templates_dir.mkdir(parents=True)
+        os.symlink(outside, templates_dir / "plan-template.md")
+
+        _install_shared_infra(project, "sh", force=True)
+
+        captured = capsys.readouterr()
+        assert "symlinked shared infrastructure" in captured.out
+        assert outside.read_text(encoding="utf-8") == "# outside\n"
+
+    @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+    def test_shared_template_refresh_refuses_symlinked_destination(self, tmp_path):
+        """Template-only refreshes must not follow destination symlinks."""
+        from specify_cli import _refresh_shared_templates
+
+        project = tmp_path / "symlink-refresh-test"
+        project.mkdir()
+        (project / ".specify").mkdir()
+
+        outside = tmp_path / "outside-refresh.md"
+        outside.write_text("# outside\n", encoding="utf-8")
+        templates_dir = project / ".specify" / "templates"
+        templates_dir.mkdir(parents=True)
+        os.symlink(outside, templates_dir / "plan-template.md")
+
+        with pytest.raises(ValueError, match="Refusing to overwrite symlinked"):
+            _refresh_shared_templates(project, invoke_separator=".", force=True)
+
+        assert outside.read_text(encoding="utf-8") == "# outside\n"
+
+    @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+    def test_shared_infra_refuses_symlinked_specify_directory_before_mkdir(self, tmp_path):
+        """Shared infra installs must not follow a symlinked .specify directory."""
+        from specify_cli import _install_shared_infra
+
+        project = tmp_path / "symlink-dir-test"
+        project.mkdir()
+        outside = tmp_path / "outside-specify"
+        outside.mkdir()
+        os.symlink(outside, project / ".specify")
+
+        with pytest.raises(ValueError, match="symlinked"):
+            _install_shared_infra(project, "sh", force=True)
+        # Nothing should have been written under the symlinked .specify target.
+        assert list(outside.iterdir()) == []
+
+        assert not (outside / "scripts").exists()
+        assert not (outside / "templates").exists()
+
+    @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+    def test_shared_infra_refuses_symlinked_shared_manifest(self, tmp_path):
+        """Shared infra manifest saves must not follow destination symlinks."""
+        from specify_cli.shared_infra import install_shared_infra
+
+        project = tmp_path / "symlink-shared-manifest-test"
+        project.mkdir()
+        integrations_dir = project / ".specify" / "integrations"
+        integrations_dir.mkdir(parents=True)
+
+        outside = tmp_path / "outside-manifest.json"
+        outside.write_text("# outside\n", encoding="utf-8")
+        os.symlink(outside, integrations_dir / "speckit.manifest.json")
+
+        core_pack = tmp_path / "core-pack"
+        templates_src = core_pack / "templates"
+        templates_src.mkdir(parents=True)
+        (templates_src / "plan-template.md").write_text("# plan\n", encoding="utf-8")
+
+        with pytest.raises(ValueError, match="symlinked integration manifest"):
+            install_shared_infra(
+                project,
+                "sh",
+                version="test",
+                core_pack=core_pack,
+                repo_root=tmp_path / "unused",
+                console=_NoopConsole(),
+                force=True,
+            )
+
+        assert outside.read_text(encoding="utf-8") == "# outside\n"
+
+    @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+    def test_shared_template_refresh_preflights_before_writing(self, tmp_path):
+        """Template refresh validates all destinations before writing any file."""
+        from specify_cli.shared_infra import refresh_shared_templates
+
+        project = tmp_path / "preflight-refresh-test"
+        project.mkdir()
+        templates_dir = project / ".specify" / "templates"
+        templates_dir.mkdir(parents=True)
+
+        core_pack = tmp_path / "core-pack"
+        templates_src = core_pack / "templates"
+        templates_src.mkdir(parents=True)
+        (templates_src / "a-template.md").write_text("# new a\n", encoding="utf-8")
+        (templates_src / "z-template.md").write_text("# new z\n", encoding="utf-8")
+
+        existing = templates_dir / "a-template.md"
+        existing.write_text("# old a\n", encoding="utf-8")
+        outside = tmp_path / "outside-z.md"
+        outside.write_text("# outside\n", encoding="utf-8")
+        os.symlink(outside, templates_dir / "z-template.md")
+
+        with pytest.raises(ValueError, match="Refusing to overwrite symlinked"):
+            refresh_shared_templates(
+                project,
+                version="test",
+                core_pack=core_pack,
+                repo_root=tmp_path / "unused",
+                console=_NoopConsole(),
+                invoke_separator=".",
+                force=True,
+            )
+
+        assert existing.read_text(encoding="utf-8") == "# old a\n"
+        assert outside.read_text(encoding="utf-8") == "# outside\n"
+
+    @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+    def test_shared_infra_install_buckets_unsafe_destinations_and_continues(self, tmp_path):
+        """Symlinked destinations are bucketed with a warning; safe destinations in the same install still complete."""
+        from specify_cli.shared_infra import install_shared_infra
+
+        project = tmp_path / "preflight-install-test"
+        project.mkdir()
+        scripts_dir = project / ".specify" / "scripts" / "bash"
+        scripts_dir.mkdir(parents=True)
+
+        core_pack = tmp_path / "core-pack"
+        scripts_src = core_pack / "scripts" / "bash"
+        scripts_src.mkdir(parents=True)
+        (scripts_src / "a.sh").write_text("# new a\n", encoding="utf-8")
+        (scripts_src / "z.sh").write_text("# new z\n", encoding="utf-8")
+
+        existing = scripts_dir / "a.sh"
+        existing.write_text("# old a\n", encoding="utf-8")
+        outside = tmp_path / "outside-z.sh"
+        outside.write_text("# outside\n", encoding="utf-8")
+        os.symlink(outside, scripts_dir / "z.sh")
+
+        install_shared_infra(
+            project,
+            "sh",
+            version="test",
+            core_pack=core_pack,
+            repo_root=tmp_path / "unused",
+            console=_NoopConsole(),
+            force=True,
+        )
+
+        # Symlinked z.sh is preserved (bucketed); regular a.sh is overwritten.
+        assert outside.read_text(encoding="utf-8") == "# outside\n"
+        assert existing.read_text(encoding="utf-8") == "# new a\n"
+
+    def test_shared_infra_install_supports_nested_script_sources(self, tmp_path):
+        """Nested script source files create safe destination parents at write time."""
+        from specify_cli.shared_infra import install_shared_infra
+
+        project = tmp_path / "nested-script-install-test"
+        project.mkdir()
+
+        core_pack = tmp_path / "core-pack"
+        nested_src = core_pack / "scripts" / "bash" / "nested"
+        nested_src.mkdir(parents=True)
+        (nested_src / "deep.sh").write_text("# nested\n", encoding="utf-8")
+
+        install_shared_infra(
+            project,
+            "sh",
+            version="test",
+            core_pack=core_pack,
+            repo_root=tmp_path / "unused",
+            console=_NoopConsole(),
+            force=True,
+        )
+
+        nested_dest = project / ".specify" / "scripts" / "bash" / "nested" / "deep.sh"
+        assert nested_dest.read_text(encoding="utf-8") == "# nested\n"
+
+    def test_shared_infra_skip_warning_uses_posix_paths(self, tmp_path):
+        """Skipped shared infra paths are reported consistently across platforms."""
+        from specify_cli.shared_infra import install_shared_infra
+
+        project = tmp_path / "posix-skip-warning-test"
+        project.mkdir()
+        nested_dest = project / ".specify" / "scripts" / "bash" / "nested"
+        nested_dest.mkdir(parents=True)
+        (nested_dest / "deep.sh").write_text("# existing script\n", encoding="utf-8")
+
+        templates_dest = project / ".specify" / "templates"
+        templates_dest.mkdir(parents=True)
+        (templates_dest / "plan-template.md").write_text("# existing template\n", encoding="utf-8")
+
+        core_pack = tmp_path / "core-pack"
+        nested_src = core_pack / "scripts" / "bash" / "nested"
+        nested_src.mkdir(parents=True)
+        (nested_src / "deep.sh").write_text("# bundled script\n", encoding="utf-8")
+
+        templates_src = core_pack / "templates"
+        templates_src.mkdir(parents=True)
+        (templates_src / "plan-template.md").write_text("# bundled template\n", encoding="utf-8")
+
+        buffer = io.StringIO()
+        install_shared_infra(
+            project,
+            "sh",
+            version="test",
+            core_pack=core_pack,
+            repo_root=tmp_path / "unused",
+            console=Console(file=buffer, force_terminal=False, width=120),
+            force=False,
+        )
+
+        output = buffer.getvalue()
+        assert ".specify/scripts/bash/nested/deep.sh" in output
+        assert ".specify/templates/plan-template.md" in output
+
+    @pytest.mark.skipif(os.name == "nt", reason="POSIX mode bits are not stable on Windows")
+    def test_shared_template_writes_are_not_world_writable(self, tmp_path):
+        """Shared template writes use a safe default mode instead of chmod 666."""
+        from specify_cli.shared_infra import install_shared_infra
+
+        project = tmp_path / "template-mode-test"
+        project.mkdir()
+
+        core_pack = tmp_path / "core-pack"
+        templates_src = core_pack / "templates"
+        templates_src.mkdir(parents=True)
+        (templates_src / "plan-template.md").write_text("# plan\n", encoding="utf-8")
+
+        install_shared_infra(
+            project,
+            "sh",
+            version="test",
+            core_pack=core_pack,
+            repo_root=tmp_path / "unused",
+            console=_NoopConsole(),
+            force=True,
+        )
+
+        written = project / ".specify" / "templates" / "plan-template.md"
+        assert written.stat().st_mode & 0o777 == 0o644
+
     def test_shared_infra_no_warning_when_forced(self, tmp_path, capsys):
         """No skip warning when force=True (all files overwritten)."""
         from specify_cli import _install_shared_infra
@@ -473,6 +812,32 @@ class TestGitExtensionAutoInstall:
         assert "will be removed" in normalized_output
         assert "git extension will no longer be enabled by default" in normalized_output
 
+    def test_default_git_auto_enable_emits_notice(self, tmp_path):
+        """Default git auto-enable emits notice about the v0.10.0 opt-in change."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        project = tmp_path / "git-default-notice"
+        project.mkdir()
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            runner = CliRunner()
+            result = runner.invoke(app, [
+                "init", "--here", "--ai", "claude", "--script", "sh",
+                "--ignore-agent-tools",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+
+        normalized_output = _normalize_cli_output(result.output)
+        assert result.exit_code == 0, result.output
+        # Check for key message components (notice may have box-drawing chars)
+        assert "git extension is currently enabled by default" in normalized_output
+        assert "v0.10.0" in normalized_output
+        assert "explicit opt-in" in normalized_output
+        assert "specify extension add git" in normalized_output
+
     def test_git_extension_commands_registered(self, tmp_path):
         """Git extension commands are registered with the agent during init."""
         from typer.testing import CliRunner
@@ -706,6 +1071,119 @@ class TestIntegrationCatalogDiscoveryCLI:
         assert result.exit_code == 1
         assert "Not a spec-kit project" in result.output
 
+    def test_primary_integration_commands_require_specify_project(self, tmp_path):
+        project = tmp_path / "bare"
+        project.mkdir()
+        commands = [
+            ["integration", "list"],
+            ["integration", "install", "codex"],
+            ["integration", "use", "codex"],
+            ["integration", "uninstall"],
+            ["integration", "switch", "codex"],
+            ["integration", "upgrade"],
+        ]
+
+        for command in commands:
+            result = self._invoke(command, project)
+            failure_context = (
+                f"command={command!r}, exit_code={result.exit_code}, output={result.output!r}"
+            )
+            assert result.exit_code == 1, failure_context
+            assert "Not a spec-kit project" in result.output, failure_context
+
+    def test_integration_commands_require_specify_directory(self, tmp_path):
+        project = tmp_path / "bad"
+        project.mkdir()
+        (project / ".specify").write_text("not a directory")
+
+        commands = [
+            ["integration", "list"],
+            ["integration", "use", "codex"],
+        ]
+
+        for command in commands:
+            result = self._invoke(command, project)
+            assert result.exit_code == 1, result.output
+            assert "Not a spec-kit project" in result.output
+
+    def test_project_scoped_commands_require_specify_directory(self, tmp_path):
+        project = tmp_path / "bad-feature-commands"
+        project.mkdir()
+        (project / ".specify").write_text("not a directory")
+
+        commands = [
+            ["preset", "list"],
+            ["preset", "add", "demo"],
+            ["preset", "remove", "demo"],
+            ["preset", "search"],
+            ["preset", "resolve", "spec-template"],
+            ["preset", "info", "demo"],
+            ["preset", "set-priority", "demo", "5"],
+            ["preset", "enable", "demo"],
+            ["preset", "disable", "demo"],
+            ["preset", "catalog", "list"],
+            ["preset", "catalog", "add", "https://example.com/catalog.yml", "--name", "demo"],
+            ["preset", "catalog", "remove", "demo"],
+            ["extension", "list"],
+            ["extension", "add", "demo"],
+            ["extension", "remove", "demo"],
+            ["extension", "search"],
+            ["extension", "info", "demo"],
+            ["extension", "update", "demo"],
+            ["extension", "enable", "demo"],
+            ["extension", "disable", "demo"],
+            ["extension", "set-priority", "demo", "5"],
+            ["extension", "catalog", "list"],
+            ["extension", "catalog", "add", "https://example.com/catalog.yml", "--name", "demo"],
+            ["extension", "catalog", "remove", "demo"],
+            ["workflow", "run", "demo"],
+            ["workflow", "resume", "demo"],
+            ["workflow", "status"],
+            ["workflow", "list"],
+            ["workflow", "add", "demo"],
+            ["workflow", "remove", "demo"],
+            ["workflow", "search"],
+            ["workflow", "info", "demo"],
+            ["workflow", "catalog", "list"],
+            ["workflow", "catalog", "add", "https://example.com/catalog.yml"],
+            ["workflow", "catalog", "remove", "0"],
+        ]
+
+        for command in commands:
+            result = self._invoke(command, project)
+            failure_context = (
+                f"command={command!r}, exit_code={result.exit_code}, output={result.output!r}"
+            )
+            assert result.exit_code == 1, failure_context
+            assert "Not a spec-kit project" in result.output, failure_context
+
+    def test_catalog_config_output_uses_posix_paths(self, tmp_path):
+        project = self._make_project(tmp_path)
+
+        preset_add = self._invoke([
+            "preset", "catalog", "add",
+            "https://example.com/preset-catalog.yml",
+            "--name", "demo-presets",
+        ], project)
+        assert preset_add.exit_code == 0, preset_add.output
+        assert "Config saved to .specify/preset-catalogs.yml" in preset_add.output
+
+        preset_list = self._invoke(["preset", "catalog", "list"], project)
+        assert preset_list.exit_code == 0, preset_list.output
+        assert "Config: .specify/preset-catalogs.yml" in preset_list.output
+
+        extension_add = self._invoke([
+            "extension", "catalog", "add",
+            "https://example.com/extension-catalog.yml",
+            "--name", "demo-extensions",
+        ], project)
+        assert extension_add.exit_code == 0, extension_add.output
+        assert "Config saved to .specify/extension-catalogs.yml" in extension_add.output
+
+        extension_list = self._invoke(["extension", "catalog", "list"], project)
+        assert extension_list.exit_code == 0, extension_list.output
+        assert "Config: .specify/extension-catalogs.yml" in extension_list.output
+
     # -- search ------------------------------------------------------------
 
     def test_search_lists_all(self, tmp_path, monkeypatch):

tests/integrations/test_integration_base_markdown.py

@@ -274,11 +274,11 @@ class MarkdownIntegrationTests:
 
         if script_variant == "sh":
             for name in ["check-prerequisites.sh", "common.sh", "create-new-feature.sh",
-                         "setup-plan.sh"]:
+                         "setup-plan.sh", "setup-tasks.sh"]:
                 files.append(f".specify/scripts/bash/{name}")
         else:
             for name in ["check-prerequisites.ps1", "common.ps1", "create-new-feature.ps1",
-                         "setup-plan.ps1"]:
+                         "setup-plan.ps1", "setup-tasks.ps1"]:
                 files.append(f".specify/scripts/powershell/{name}")
 
         for name in ["checklist-template.md",

tests/integrations/test_integration_base_skills.py

@@ -387,6 +387,7 @@ class SkillsIntegrationTests:
                 ".specify/scripts/bash/common.sh",
                 ".specify/scripts/bash/create-new-feature.sh",
                 ".specify/scripts/bash/setup-plan.sh",
+                ".specify/scripts/bash/setup-tasks.sh",
             ]
         else:
             files += [
@@ -394,6 +395,7 @@ class SkillsIntegrationTests:
                 ".specify/scripts/powershell/common.ps1",
                 ".specify/scripts/powershell/create-new-feature.ps1",
                 ".specify/scripts/powershell/setup-plan.ps1",
+                ".specify/scripts/powershell/setup-tasks.ps1",
             ]
         # Templates
         files += [

tests/integrations/test_integration_base_toml.py

@@ -516,6 +516,7 @@ class TomlIntegrationTests:
                 "common.sh",
                 "create-new-feature.sh",
                 "setup-plan.sh",
+                "setup-tasks.sh",
             ]:
                 files.append(f".specify/scripts/bash/{name}")
         else:
@@ -524,6 +525,7 @@ class TomlIntegrationTests:
                 "common.ps1",
                 "create-new-feature.ps1",
                 "setup-plan.ps1",
+                "setup-tasks.ps1",
             ]:
                 files.append(f".specify/scripts/powershell/{name}")
 

tests/integrations/test_integration_base_yaml.py

@@ -395,6 +395,7 @@ class YamlIntegrationTests:
                 "common.sh",
                 "create-new-feature.sh",
                 "setup-plan.sh",
+                "setup-tasks.sh",
             ]:
                 files.append(f".specify/scripts/bash/{name}")
         else:
@@ -403,6 +404,7 @@ class YamlIntegrationTests:
                 "common.ps1",
                 "create-new-feature.ps1",
                 "setup-plan.ps1",
+                "setup-tasks.ps1",
             ]:
                 files.append(f".specify/scripts/powershell/{name}")
 

tests/integrations/test_integration_catalog.py

@@ -166,12 +166,12 @@ class TestCatalogFetch:
     """Tests that use a local HTTP server stub via monkeypatch."""
 
     def _patch_urlopen(self, monkeypatch, catalog_data):
-        """Patch urllib.request.urlopen to return *catalog_data*."""
+        """Patch authentication.http.urllib.request.urlopen to return *catalog_data*."""
 
         class FakeResponse:
             def __init__(self, data, url=""):
                 self._data = json.dumps(data).encode()
-                self._url = url
+                self._url = url if isinstance(url, str) else url.full_url
 
             def read(self):
                 return self._data
@@ -185,11 +185,12 @@ class TestCatalogFetch:
             def __exit__(self, *a):
                 pass
 
-        def fake_urlopen(url, timeout=10):
+        def fake_urlopen(req, timeout=10):
+            url = req if isinstance(req, str) else req.full_url
             return FakeResponse(catalog_data, url)
 
-        import urllib.request
-        monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
+        import specify_cli.authentication.http as _auth_http
+        monkeypatch.setattr(_auth_http.urllib.request, "urlopen", fake_urlopen)
 
     def test_fetch_and_search_all(self, tmp_path, monkeypatch):
         monkeypatch.setenv("HOME", str(tmp_path))
@@ -486,12 +487,12 @@ class TestIntegrationListCatalog:
             },
         }
 
-        import urllib.request
+        import specify_cli.authentication.http as _auth_http
 
         class FakeResponse:
             def __init__(self, data, url=""):
                 self._data = json.dumps(data).encode()
-                self._url = url
+                self._url = url if isinstance(url, str) else url.full_url
             def read(self):
                 return self._data
             def geturl(self):
@@ -501,7 +502,8 @@ class TestIntegrationListCatalog:
             def __exit__(self, *a):
                 pass
 
-        monkeypatch.setattr(urllib.request, "urlopen", lambda url, timeout=10: FakeResponse(catalog, url))
+        monkeypatch.setattr(_auth_http.urllib.request, "urlopen",
+                            lambda req, timeout=10: FakeResponse(catalog, req if isinstance(req, str) else req.full_url))
 
         old = os.getcwd()
         try:
@@ -670,7 +672,7 @@ class TestIntegrationUpgrade:
         finally:
             os.chdir(old)
         assert result.exit_code != 0
-        assert "not the currently installed integration" in result.output
+        assert "not installed" in result.output
 
     def test_upgrade_no_manifest(self, tmp_path):
         """Upgrade with missing manifest suggests fresh install."""

tests/integrations/test_integration_claude.py

@@ -196,7 +196,10 @@ class TestClaudeIntegration:
         try:
             os.chdir(project)
             runner = CliRunner()
-            with patch("specify_cli.select_with_arrows", return_value="claude"):
+            with (
+                patch("specify_cli._stdin_is_interactive", return_value=True),
+                patch("specify_cli.select_with_arrows", return_value="claude"),
+            ):
                 result = runner.invoke(
                     app,
                     [

tests/integrations/test_integration_copilot.py

@@ -206,6 +206,7 @@ class TestCopilotIntegration:
             ".specify/scripts/bash/common.sh",
             ".specify/scripts/bash/create-new-feature.sh",
             ".specify/scripts/bash/setup-plan.sh",
+            ".specify/scripts/bash/setup-tasks.sh",
             ".specify/templates/checklist-template.md",
             ".specify/templates/constitution-template.md",
             ".specify/templates/plan-template.md",
@@ -265,6 +266,7 @@ class TestCopilotIntegration:
             ".specify/scripts/powershell/common.ps1",
             ".specify/scripts/powershell/create-new-feature.ps1",
             ".specify/scripts/powershell/setup-plan.ps1",
+            ".specify/scripts/powershell/setup-tasks.ps1",
             ".specify/templates/checklist-template.md",
             ".specify/templates/constitution-template.md",
             ".specify/templates/plan-template.md",
@@ -614,6 +616,7 @@ class TestCopilotSkillsMode:
             ".specify/scripts/bash/common.sh",
             ".specify/scripts/bash/create-new-feature.sh",
             ".specify/scripts/bash/setup-plan.sh",
+            ".specify/scripts/bash/setup-tasks.sh",
             # Templates
             ".specify/templates/checklist-template.md",
             ".specify/templates/constitution-template.md",

tests/integrations/test_integration_forge.py

@@ -141,6 +141,7 @@ class TestForgeIntegration:
         assert actual_commands == expected_commands
 
     def test_templates_are_processed(self, tmp_path):
+        import re
         from specify_cli.integrations.forge import ForgeIntegration
         forge = ForgeIntegration()
         m = IntegrationManifest("forge", tmp_path)
@@ -157,6 +158,11 @@ class TestForgeIntegration:
             assert "$ARGUMENTS" not in content, f"{cmd_file.name} has unprocessed $ARGUMENTS"
             # Frontmatter sections should be stripped
             assert "\nscripts:\n" not in content
+            # Check Forge-specific: command references use hyphen notation, not dot notation
+            assert not re.search(r"/speckit\.[a-z]", content), (
+                f"{cmd_file.name} contains dot-notation command reference (/speckit.<cmd>); "
+                "Forge requires hyphen notation (/speckit-<cmd>) for ZSH compatibility"
+            )
 
     def test_plan_references_correct_context_file(self, tmp_path):
         """The generated plan command must reference forge's context file."""
@@ -224,6 +230,33 @@ class TestForgeIntegration:
                 "checklist should contain {{parameters}} in User Input section"
             )
 
+    def test_command_refs_use_hyphen_notation(self, tmp_path):
+        """Verify all generated Forge command files use /speckit-foo, not /speckit.foo."""
+        import re
+        from specify_cli.integrations.forge import ForgeIntegration
+        forge = ForgeIntegration()
+        m = IntegrationManifest("forge", tmp_path)
+        forge.setup(tmp_path, m)
+        commands_dir = tmp_path / ".forge" / "commands"
+
+        files_with_refs = []
+        files_with_dot_refs = []
+        for cmd_file in commands_dir.glob("speckit.*.md"):
+            content = cmd_file.read_text(encoding="utf-8")
+            if re.search(r"/speckit-[a-z]", content):
+                files_with_refs.append(cmd_file.name)
+            if re.search(r"/speckit\.[a-z]", content):
+                files_with_dot_refs.append(cmd_file.name)
+
+        assert files_with_dot_refs == [], (
+            f"Files contain dot-notation command references: {files_with_dot_refs}. "
+            "Forge requires hyphen notation (/speckit-<cmd>) for ZSH compatibility."
+        )
+        assert len(files_with_refs) > 0, (
+            "Expected at least one generated Forge command to contain /speckit-<cmd> reference, "
+            "but none were found. Check that __SPECKIT_COMMAND_*__ tokens are being resolved."
+        )
+
     def test_name_field_uses_hyphenated_format(self, tmp_path):
         """Verify that injected name fields use hyphenated format (speckit-plan, not speckit.plan)."""
         from specify_cli.integrations.forge import ForgeIntegration
@@ -401,3 +434,48 @@ class TestForgeCommandRegistrar:
         assert "name:" not in content, (
             "Windsurf should not inject name field - format_name callback should be Forge-only"
         )
+
+    def test_git_extension_command_uses_hyphen_notation(self, tmp_path):
+        """Verify the git extension's feature command uses /speckit-specify (not /speckit.specify) for Forge."""
+        from pathlib import Path
+        from specify_cli.agents import CommandRegistrar
+
+        # Locate the real git extension command source file
+        repo_root = Path(__file__).resolve().parent.parent.parent
+        ext_dir = repo_root / "extensions" / "git"
+        cmd_source = ext_dir / "commands" / "speckit.git.feature.md"
+        assert cmd_source.exists(), (
+            f"Git extension command source not found at {cmd_source}. "
+            "Ensure extensions/git/commands/speckit.git.feature.md exists."
+        )
+
+        registrar = CommandRegistrar()
+        commands = [
+            {
+                "name": "speckit.git.feature",
+                "file": "commands/speckit.git.feature.md",
+            }
+        ]
+
+        registered = registrar.register_commands(
+            "forge",
+            commands,
+            "git",
+            ext_dir,
+            tmp_path,
+        )
+
+        assert "speckit.git.feature" in registered
+
+        forge_cmd = tmp_path / ".forge" / "commands" / "speckit.git.feature.md"
+        assert forge_cmd.exists(), "Expected Forge command file was not created"
+
+        content = forge_cmd.read_text(encoding="utf-8")
+        assert "/speckit-specify" in content, (
+            "Expected '/speckit-specify' (hyphen) in generated Forge git.feature command body, "
+            "but it was not found. Check that __SPECKIT_COMMAND_SPECIFY__ is resolved correctly."
+        )
+        assert "/speckit.specify" not in content, (
+            "Found '/speckit.specify' (dot notation) in generated Forge git.feature command body. "
+            "Forge requires hyphen notation for ZSH compatibility."
+        )

tests/integrations/test_integration_generic.py

@@ -185,6 +185,16 @@ class TestGenericIntegration:
         )
         assert "__CONTEXT_FILE__" not in content
 
+    def test_implement_loads_constitution_context(self, tmp_path):
+        """The generated implement command should load constitution governance context."""
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        implement_file = tmp_path / ".custom" / "cmds" / "speckit.implement.md"
+        assert implement_file.exists()
+        content = implement_file.read_text(encoding="utf-8")
+        assert ".specify/memory/constitution.md" in content
+
     # -- CLI --------------------------------------------------------------
 
     def test_cli_generic_without_commands_dir_fails(self, tmp_path):
@@ -264,6 +274,7 @@ class TestGenericIntegration:
             ".specify/scripts/bash/common.sh",
             ".specify/scripts/bash/create-new-feature.sh",
             ".specify/scripts/bash/setup-plan.sh",
+            ".specify/scripts/bash/setup-tasks.sh",
             ".specify/templates/checklist-template.md",
             ".specify/templates/constitution-template.md",
             ".specify/templates/plan-template.md",
@@ -319,6 +330,7 @@ class TestGenericIntegration:
             ".specify/scripts/powershell/common.ps1",
             ".specify/scripts/powershell/create-new-feature.ps1",
             ".specify/scripts/powershell/setup-plan.ps1",
+            ".specify/scripts/powershell/setup-tasks.ps1",
             ".specify/templates/checklist-template.md",
             ".specify/templates/constitution-template.md",
             ".specify/templates/plan-template.md",

tests/integrations/test_integration_goose.py

@@ -1,5 +1,9 @@
 """Tests for GooseIntegration."""
 
+import yaml
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+
 from .test_integration_base_yaml import YamlIntegrationTests
 
 
@@ -9,3 +13,27 @@ class TestGooseIntegration(YamlIntegrationTests):
     COMMANDS_SUBDIR = "recipes"
     REGISTRAR_DIR = ".goose/recipes"
     CONTEXT_FILE = "AGENTS.md"
+
+    def test_setup_declares_args_parameter_for_args_prompt(self, tmp_path):
+        # “If a generated Goose recipe uses {{args}} in its prompt, it
+        # must declare a corresponding args parameter.”
+
+        integration = get_integration("goose")
+        assert integration is not None
+
+        manifest = IntegrationManifest("goose", tmp_path)
+        created = integration.setup(tmp_path, manifest, script_type="sh")
+
+        recipe_files = [path for path in created if path.suffix == ".yaml"]
+        assert recipe_files
+
+        for recipe_file in recipe_files:
+            data = yaml.safe_load(recipe_file.read_text(encoding="utf-8"))
+
+            if "{{args}}" not in data["prompt"]:
+                continue
+
+            assert any(
+                param.get("key") == "args"
+                for param in data.get("parameters", [])
+            ), f"{recipe_file} uses {{{{args}}}} but does not declare args"

tests/integrations/test_integration_kiro_cli.py

@@ -1,10 +1,41 @@
 """Tests for KiroCliIntegration."""
 
 import os
+import re
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.kiro_cli import _KIRO_ARG_FALLBACK
+from specify_cli.integrations.manifest import IntegrationManifest
 
 from .test_integration_base_markdown import MarkdownIntegrationTests
 
 
+# Regex shapes that indicate a value is a placeholder token, not prose.
+# Covers Bash ($VAR, ${VAR}, ${VAR:-default}), Mustache/Handlebars/Jinja
+# ({{var}}, {{{var}}}), Liquid/Jinja control ({% ... %}), Python str.format /
+# .NET ({var}, {0}), angle-bracket (<var>), and Windows-style (%VAR%).
+# Anchored to the FULL STRING so legitimate prose mentioning a placeholder
+# (e.g. "the {{magic}} of placeholders") is not flagged. The Liquid pattern
+# is anchored to the START so multi-tag templates fire while mid-sentence
+# {%-quotation does not.
+_PLACEHOLDER_TOKEN_PATTERNS = (
+    re.compile(r"^\$\w+$"),                                  # $ARGUMENTS, $args
+    re.compile(r"^\$\{\w+(?:[:\-+?][^}]*)?\}$"),             # ${ARGS}, ${ARGS:-default}
+    re.compile(r"^\{\{\{?\s*\w+(\s*[|.][^}]*)?\s*\}?\}\}$"), # {{var}} {{{var}}} {{x|y}}
+    re.compile(r"^\{%"),                                     # {% if x %}{{ x }}{% endif %}
+    re.compile(r"^<\w+>$"),                                  # <args>
+    re.compile(r"^%\w+%$"),                                  # %USERNAME%
+    re.compile(r"^\{(?:\d+|[a-zA-Z_]\w*)(?:[.\[][^}]*)?(?:![rsa])?(?::[^}]*)?\}$"),  # {0}, {var}, {0:>5}
+)
+
+
+def _looks_like_placeholder_token(value: str) -> bool:
+    """Return True if *value* matches a known placeholder-token shape."""
+    if not value:
+        return False
+    return any(p.search(value) for p in _PLACEHOLDER_TOKEN_PATTERNS)
+
+
 class TestKiroCliIntegration(MarkdownIntegrationTests):
     KEY = "kiro-cli"
     FOLDER = ".kiro/"
@@ -12,6 +43,85 @@ class TestKiroCliIntegration(MarkdownIntegrationTests):
     REGISTRAR_DIR = ".kiro/prompts"
     CONTEXT_FILE = "AGENTS.md"
 
+    def test_registrar_config(self):
+        """Override base assertion: kiro-cli uses a prose fallback for args
+        because Kiro CLI file-based prompts do not natively substitute
+        ``$ARGUMENTS`` (see issue #1926 / kirodotdev/Kiro#4141). The
+        regression-guard load is carried by the two layer tests below
+        (exact-fallback + placeholder-shape rejection)."""
+        i = get_integration(self.KEY)
+        assert i.registrar_config["dir"] == self.REGISTRAR_DIR
+        assert i.registrar_config["format"] == "markdown"
+        assert i.registrar_config["extension"] == ".md"
+
+    def test_registrar_config_args_is_exact_prose_fallback(self):
+        """Layer 1 — pin the exact fallback so wording drift requires a
+        deliberate paired commit (production constant + test update)."""
+        i = get_integration(self.KEY)
+        assert i.registrar_config["args"] == _KIRO_ARG_FALLBACK, (
+            f"args drifted from the pinned fallback constant. "
+            f"Got: {i.registrar_config['args']!r}; expected: {_KIRO_ARG_FALLBACK!r}. "
+            f"If the wording change is intentional, update _KIRO_ARG_FALLBACK and "
+            f"this test together."
+        )
+
+    def test_registrar_config_args_does_not_look_like_a_placeholder_token(self):
+        """Layer 2 — independent regression guard: even if someone bypasses
+        layer-1 by changing both constant and test, the value still must not
+        look like ANY placeholder token shape ($X, ${X}, {{X}}, <X>, %X%, {0},
+        {% %}). Catches the class of regression Copilot called out: a swap
+        from $ARGUMENTS to $INPUT or {{userMessage}} would fail this test
+        even if it accidentally passed layer 1."""
+        i = get_integration(self.KEY)
+        args = i.registrar_config["args"]
+        assert not _looks_like_placeholder_token(args), (
+            f"registrar_config['args'] = {args!r} matches a known placeholder-"
+            f"token shape — Kiro CLI does not substitute placeholders so this "
+            f"would reach the model verbatim and break the prompt (issue #1926). "
+            f"Use a prose fallback instead."
+        )
+
+    def test_rendered_prompts_do_not_contain_raw_arguments(self, tmp_path):
+        """Rendered Kiro prompt files must NOT contain the raw ``$ARGUMENTS``
+        token — Kiro CLI does not substitute it, so the literal would reach
+        the model and break the prompt (issue #1926)."""
+        integration = get_integration(self.KEY)
+        manifest = IntegrationManifest(self.KEY, tmp_path)
+        integration.setup(tmp_path, manifest, script_type="sh")
+
+        prompts_dir = tmp_path / self.REGISTRAR_DIR
+        rendered = list(prompts_dir.glob("*.md"))
+        assert rendered, "expected at least one rendered prompt file"
+
+        offenders = [
+            p.name for p in rendered if "$ARGUMENTS" in p.read_text(encoding="utf-8")
+        ]
+        assert offenders == [], (
+            f"these rendered prompts still contain the raw $ARGUMENTS token: {offenders}"
+        )
+
+    def test_rendered_prompts_contain_kiro_arg_placeholder(self, tmp_path):
+        """The chosen kiro-cli args fallback string must end up in at least
+        one rendered prompt (proves substitution actually fired, not just
+        that $ARGUMENTS was removed). Imports the fallback constant directly
+        instead of reading the field back so the test stays independent of
+        the integration's own config — even if the registrar_config['args']
+        regresses, this test still verifies the FALLBACK STRING is in the
+        rendered output."""
+        integration = get_integration(self.KEY)
+        manifest = IntegrationManifest(self.KEY, tmp_path)
+        integration.setup(tmp_path, manifest, script_type="sh")
+
+        expected = _KIRO_ARG_FALLBACK
+        prompts_dir = tmp_path / self.REGISTRAR_DIR
+        contents = "\n".join(
+            p.read_text(encoding="utf-8") for p in prompts_dir.glob("*.md")
+        )
+        assert expected in contents, (
+            f"none of the rendered prompts contain the configured args fallback "
+            f"({expected!r})"
+        )
+
 
 class TestKiroAlias:
     """--ai kiro alias normalizes to kiro-cli and auto-promotes."""

tests/integrations/test_integration_lingma.py

@@ -0,0 +1,11 @@
+"""Tests for LingmaIntegration."""
+
+from .test_integration_base_skills import SkillsIntegrationTests
+
+
+class TestLingmaIntegration(SkillsIntegrationTests):
+    KEY = "lingma"
+    FOLDER = ".lingma/"
+    COMMANDS_SUBDIR = "skills"
+    REGISTRAR_DIR = ".lingma/skills"
+    CONTEXT_FILE = ".lingma/rules/specify-rules.md"

tests/integrations/test_integration_state.py

@@ -0,0 +1,86 @@
+"""Tests for integration state normalization helpers."""
+
+import json
+
+from specify_cli.integration_state import (
+    INTEGRATION_JSON,
+    default_integration_key,
+    integration_setting,
+    normalize_integration_state,
+    write_integration_json,
+)
+
+
+def test_normalize_integration_state_strips_default_key_without_duplicates():
+    state = normalize_integration_state(
+        {
+            "default_integration": " claude ",
+            "integration": " claude ",
+            "installed_integrations": ["claude"],
+        }
+    )
+
+    assert state["integration"] == "claude"
+    assert state["default_integration"] == "claude"
+    assert state["installed_integrations"] == ["claude"]
+
+
+def test_normalize_integration_state_strips_legacy_key_fallback():
+    state = normalize_integration_state(
+        {
+            "integration": " codex ",
+            "installed_integrations": [],
+        }
+    )
+
+    assert state["integration"] == "codex"
+    assert state["default_integration"] == "codex"
+    assert state["installed_integrations"] == ["codex"]
+
+
+def test_normalize_integration_state_preserves_newer_schema():
+    state = normalize_integration_state(
+        {
+            "integration_state_schema": 99,
+            "integration": "claude",
+            "installed_integrations": ["claude"],
+            "future_field": {"keep": True},
+        }
+    )
+
+    assert state["integration_state_schema"] == 99
+    assert state["future_field"] == {"keep": True}
+
+
+def test_default_integration_key_strips_raw_state_values():
+    assert default_integration_key({"default_integration": " claude "}) == "claude"
+    assert default_integration_key({"integration": " codex "}) == "codex"
+
+
+def test_integration_settings_strip_invoke_separator():
+    setting = integration_setting(
+        {
+            "integration_settings": {
+                "claude": {
+                    "invoke_separator": " - ",
+                }
+            }
+        },
+        "claude",
+    )
+
+    assert setting["invoke_separator"] == "-"
+
+
+def test_write_integration_json_strips_integration_key(tmp_path):
+    write_integration_json(
+        tmp_path,
+        version="1.2.3",
+        integration_key=" claude ",
+        installed_integrations=["claude"],
+    )
+
+    state = json.loads((tmp_path / INTEGRATION_JSON).read_text(encoding="utf-8"))
+    assert state["integration"] == "claude"
+    assert state["default_integration"] == "claude"
+    assert state["installed_integrations"] == ["claude"]