Potential fix for pull request finding 'Empty except'

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

.editorconfig

@@ -0,0 +1,28 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.{json,jsonc}]
+indent_size = 2
+
+[*.md]
+indent_size = 2
+trim_trailing_whitespace = false
+
+[*.{sh,bash}]
+indent_size = 4
+
+[*.{ps1,psm1,psd1}]
+indent_size = 4
+
+[Makefile]
+indent_style = tab

.gitattributes

@@ -1 +1,3 @@
 * text=auto eol=lf
+
+.github/workflows/*.lock.yml linguist-generated=true merge=ours -whitespace

.github/aw/actions-lock.json

@@ -0,0 +1,14 @@
+{
+  "entries": {
+    "actions/github-script@v9.0.0": {
+      "repo": "actions/github-script",
+      "version": "v9.0.0",
+      "sha": "3a2844b7e9c422d3c10d287c895573f7108da1b3"
+    },
+    "github/gh-aw-actions/setup@v0.74.8": {
+      "repo": "github/gh-aw-actions/setup",
+      "version": "v0.74.8",
+      "sha": "efa55847f72aadb03490d955263ff911bf758700"
+    }
+  }
+}

.github/dependabot.yml

@@ -1,11 +1,12 @@
-version: 2
 updates:
-  - package-ecosystem: "pip"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "weekly"
+- directory: /
+  package-ecosystem: pip
+  schedule:
+    interval: weekly
+- directory: /
+  ignore:
+  - dependency-name: "github/gh-aw-actions/**" # Managed by gh aw compile. Version-locked to the gh-aw compiler; do not bump.
+  package-ecosystem: github-actions
+  schedule:
+    interval: weekly
+version: 2

.github/skills/add-community-extension/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: add-community-extension
+description: 'Add a community extension to the Spec Kit catalog from a GitHub issue submission. USE FOR: processing extension submission issues, validating catalog entries, updating catalog.community.json and docs/community/extensions.md, creating PRs. DO NOT USE FOR: creating new extensions from scratch, or first-party extension work.'
+argument-hint: 'GitHub issue URL or number for the extension submission'
+---
+
+# Add Community Extension
+
+Process an extension submission issue and add or update it in the community catalog.
+
+## When to Use
+
+- A new `[Extension]` submission issue is filed
+- An existing extension submits an update issue (new version, changed metadata)
+- You need to add or update a community extension in `extensions/catalog.community.json` and `docs/community/extensions.md`
+
+## Procedure
+
+### 1. Fetch the submission issue
+
+Read the GitHub issue to extract all metadata:
+- Extension ID, name, version, description, author
+- Repository URL, download URL, homepage, documentation, changelog
+- License, required spec-kit version, optional tool dependencies
+- Number of commands and hooks
+- Tags
+
+### 2. Validate against publishing rules
+
+Check **all** of the following (per `extensions/EXTENSION-PUBLISHING-GUIDE.md`):
+
+| Check | How |
+|-------|-----|
+| Repository exists and is public | Fetch the repository URL |
+| `extension.yml` manifest present | Confirm in repo file listing |
+| README.md present | Confirm in repo file listing |
+| LICENSE file present | Confirm in repo file listing |
+| GitHub release exists matching version | Check releases on the repo page |
+| Download URL is accessible | Verify it follows `archive/refs/tags/vX.Y.Z.zip` pattern and release exists |
+| Extension ID is lowercase-with-hyphens only | Regex: `^[a-z][a-z0-9-]*$` |
+| Version follows semver | Format: `X.Y.Z` |
+| Submission checklists are all checked | Confirm in issue body |
+
+### 3. Determine if this is an add or update
+
+Search `extensions/catalog.community.json` for the extension ID.
+
+- **Not found** → this is a **new addition**. Proceed to step 4.
+- **Found** → this is an **update**. Proceed to step 4 but replace the existing entry in-place instead of inserting.
+
+### 4. Add or update `extensions/catalog.community.json`
+
+**New extension:** Insert the entry in **alphabetical order** by extension ID.
+
+**Update:** Replace the existing entry in-place. Update only the fields that changed (typically `version`, `download_url`, `description`, `provides`, `requires`, `tags`, `updated_at`). Preserve `created_at` and `downloads`/`stars` from the existing entry.
+
+Use the existing entries as the format template. Required fields:
+
+```json
+{
+  "<id>": {
+    "name": "<name>",
+    "id": "<id>",
+    "description": "<description>",
+    "author": "<author>",
+    "version": "<version>",
+    "download_url": "<download_url>",
+    "repository": "<repository>",
+    "homepage": "<homepage>",
+    "documentation": "<documentation>",
+    "changelog": "<changelog>",
+    "license": "<license>",
+    "requires": {
+      "speckit_version": "<speckit_version>"
+    },
+    "provides": {
+      "commands": <N>,
+      "hooks": <N>
+    },
+    "tags": ["<tag1>", "<tag2>"],
+    "verified": false,
+    "downloads": 0,
+    "stars": 0,
+    "created_at": "<today>T00:00:00Z",
+    "updated_at": "<today>T00:00:00Z"
+  }
+}
+```
+
+If the extension has optional tool dependencies, add a `"tools"` array inside `"requires"`:
+
+```json
+"tools": [{ "name": "<tool>", "required": false }]
+```
+
+Also update the top-level `"updated_at"` timestamp in the catalog.
+
+After editing, **validate the JSON** by running:
+
+```bash
+python3 -c "import json; json.load(open('extensions/catalog.community.json')); print('Valid JSON')"
+```
+
+### 5. Add or update `docs/community/extensions.md` community extensions table
+
+**New extension:** Insert a new row into the `# Community Extensions` table in **alphabetical order** by extension name.
+
+**Update:** Find the existing row and update the description or other changed fields in-place.
+
+Determine the category and effect from the extension's behavior:
+
+```
+| <Name> | <Description> | `<category>` | <Effect> | [<repo-name>](<repository-url>) |
+```
+
+**Category** — one of: `docs`, `code`, `process`, `integration`, `visibility`
+**Effect** — `Read-only` (produces reports only) or `Read+Write` (modifies project files)
+
+### 6. Commit, push, and open PR
+
+Use `add-` for new extensions, `update-` for updates:
+
+```bash
+# New extension
+git checkout -b add-<extension-id>-extension
+
+# Update
+git checkout -b update-<extension-id>-extension
+```
+
+```bash
+git add extensions/catalog.community.json docs/community/extensions.md
+
+# New extension
+git commit -m "Add <Name> extension to community catalog
+
+Add <id> extension submitted by @<issue-author> to:
+- extensions/catalog.community.json (alphabetical order)
+- docs/community/extensions.md community extensions table
+
+Closes #<issue-number>"
+
+# Update
+git commit -m "Update <Name> extension to v<version>
+
+Update <id> extension submitted by @<issue-author>:
+- extensions/catalog.community.json (version, download_url, etc.)
+- docs/community/extensions.md community extensions table
+
+Closes #<issue-number>"
+
+git push origin <branch-name>
+```
+
+Then create a PR to `upstream` (`github/spec-kit`) with:
+- **Title:** `Add <Name> extension to community catalog` (or `Update <Name> extension to v<version>`)
+- **Body:** Include validation summary, `Closes #<issue-number>`, and `cc @<issue-author>`
+- **Head:** `<fork-owner>:<branch-name>`
+- **Base:** `main`
+
+## Common Pitfalls
+
+- **Alphabetical order matters** — entries must be sorted by ID in the JSON and by name in the docs table.
+- **Don't forget the catalog `updated_at`** — the top-level timestamp in `catalog.community.json` must be refreshed.
+- **Validate JSON after editing** — a trailing comma or missing brace will break the catalog.
+- **Use `Closes` not `Fixes`** — `Closes #N` is the correct keyword for submission issues.
+- **Match the proposed entry but verify** — the issue may include a proposed JSON block, but always validate field values against the actual repository state.
+- **Preserve `created_at` on updates** — keep the original `created_at` value; only change `updated_at`.
+- **Preserve `downloads` and `stars` on updates** — these reflect usage metrics and must not be reset.

.github/workflows/add-community-extension.md

@@ -0,0 +1,285 @@
+---
+description: "Process community extension submission issues — validate, add to catalog, and open a PR for maintainer review"
+emoji: "🧩"
+
+on:
+  issues:
+    types: [labeled]
+  skip-bots: [github-actions, copilot, dependabot]
+
+tools:
+  edit:
+  bash: ["echo", "cat", "head", "tail", "grep", "wc", "sort", "python3", "jq", "date"]
+  github:
+    toolsets: [issues, repos]
+  web-fetch:
+
+permissions:
+  contents: read
+  issues: read
+
+checkout:
+  fetch-depth: 0
+
+safe-outputs:
+  noop:
+    report-as-issue: false
+  create-pull-request:
+    title-prefix: "[extension] "
+    labels: [extension-submission, automated]
+    draft: true
+    max: 1
+    protected-files:
+      policy: blocked
+      exclude:
+        - README.md
+        - CHANGELOG.md
+  add-comment:
+    max: 2
+  add-labels:
+    allowed: [extension-submission, validation-passed, validation-failed, needs-info]
+    max: 3
+---
+
+# Add Community Extension from Issue Submission
+
+You are a catalog maintenance agent for the Spec Kit project. Your job is to
+process community extension submission issues and create pull requests that add
+or update entries in the community extension catalog.
+
+## Triggering Conditions
+
+This workflow only triggers when the `extension-submission` label is added to an
+issue. Before processing, verify that the issue title starts with `[Extension]:`.
+If it does not, stop without commenting.
+
+## Step 1 — Read and Parse the Issue
+
+Read issue #${{ github.event.issue.number }}.
+
+Extract the following fields from the structured issue body (GitHub issue form
+fields):
+
+| Field | Issue Form ID | Required |
+|-------|--------------|----------|
+| Extension ID | `extension-id` | Yes |
+| Extension Name | `extension-name` | Yes |
+| Version | `version` | Yes |
+| Description | `description` | Yes |
+| Author | `author` | Yes |
+| Repository URL | `repository` | Yes |
+| Download URL | `download-url` | Yes |
+| License | `license` | Yes |
+| Homepage | `homepage` | No |
+| Documentation URL | `documentation` | No |
+| Changelog URL | `changelog` | No |
+| Required Spec Kit Version | `speckit-version` | Yes |
+| Required Tools | `required-tools` | No |
+| Number of Commands | `commands-count` | Yes |
+| Number of Hooks | `hooks-count` | No (default 0) |
+| Tags | `tags` | Yes |
+| Proposed Catalog Entry | `catalog-entry` | Yes |
+
+The issue body uses GitHub's issue form format. Each field appears under a
+heading matching the field label (e.g., `### Extension ID` followed by the
+value). Parse accordingly.
+
+## Step 2 — Validate the Submission
+
+Run **all** of the following validation checks. Collect all results before
+deciding pass/fail:
+
+### 2a. Extension ID format
+- Must match regex: `^[a-z][a-z0-9-]*$`
+- Must be lowercase with hyphens only
+
+### 2b. Version format
+- Must follow semver: `X.Y.Z` (digits only, no `v` prefix)
+
+### 2c. Repository validation
+- Fetch the repository URL — confirm it exists and is publicly accessible
+- Confirm the repository contains an `extension.yml` file
+- Confirm the repository contains a `README.md` file
+- Confirm the repository contains a `LICENSE` file
+
+### 2d. Release and download URL validation
+- The download URL should follow the pattern
+  `https://github.com/<owner>/<repo>/archive/refs/tags/v<version>.zip`
+  or
+  `https://github.com/<owner>/<repo>/releases/download/<tag>/<asset>.zip`
+- Verify a GitHub release exists matching the submitted version
+
+### 2e. Submission checklists
+- Confirm that all required checkboxes in the Testing Checklist and Submission
+  Requirements sections are checked (`[x]`)
+
+### Validation outcome
+
+If **any** validation fails:
+1. Add a comment on the issue listing each failed check with a clear explanation
+   of what's wrong and how to fix it
+2. Add the `validation-failed` label
+3. **Stop — do not proceed further**
+
+If all validations pass:
+1. Add the `validation-passed` label
+2. Continue to Step 3
+
+## Step 3 — Determine Add vs Update
+
+Search `extensions/catalog.community.json` for the extension ID.
+
+- **Not found** → this is a **new addition**
+- **Found** → this is an **update** — replace the existing entry in-place;
+  preserve `created_at`, `downloads`, and `stars` from the existing entry
+
+## Step 4 — Update `extensions/catalog.community.json`
+
+Edit `extensions/catalog.community.json` to add or update the extension entry.
+
+### For a new extension
+
+Insert the entry in **alphabetical order by extension ID** within the
+`"extensions"` object. Use this structure:
+
+```json
+{
+  "<id>": {
+    "name": "<name>",
+    "id": "<id>",
+    "description": "<description>",
+    "author": "<author>",
+    "version": "<version>",
+    "download_url": "<download_url>",
+    "repository": "<repository>",
+    "homepage": "<homepage or repository>",
+    "documentation": "<documentation or repository README>",
+    "changelog": "<changelog or empty string>",
+    "license": "<license>",
+    "requires": {
+      "speckit_version": "<speckit_version>"
+    },
+    "provides": {
+      "commands": <N>,
+      "hooks": <N>
+    },
+    "tags": ["<tag1>", "<tag2>"],
+    "verified": false,
+    "downloads": 0,
+    "stars": 0,
+    "created_at": "<today>T00:00:00Z",
+    "updated_at": "<today>T00:00:00Z"
+  }
+}
+```
+
+If the extension has optional tool dependencies, add a `"tools"` array inside
+`"requires"`:
+
+```json
+"tools": [{ "name": "<tool>", "required": false }]
+```
+
+### For an update
+
+Replace only the changed fields (typically `version`, `download_url`,
+`description`, `provides`, `requires`, `tags`, `updated_at`). **Preserve**
+`created_at`, `downloads`, and `stars` from the existing entry.
+
+### After editing
+
+Update the **top-level `"updated_at"` timestamp** in the catalog to today's date
+in ISO 8601 format.
+
+Validate the JSON by running:
+
+```bash
+python3 -c "import json; json.load(open('extensions/catalog.community.json')); print('Valid JSON')"
+```
+
+If validation fails, fix the JSON and re-validate before continuing.
+
+## Step 5 — Update `docs/community/extensions.md`
+
+Edit `docs/community/extensions.md` to add or update a row in the Community
+Extensions table.
+
+### For a new extension
+
+Insert a new row in **alphabetical order by extension name**:
+
+```
+| <Name> | <Description> | `<category>` | <Effect> | [<repo-name>](<repository-url>) |
+```
+
+Determine the category from the extension's behavior:
+- `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
+
+Determine the effect:
+- `Read-only` — produces reports only
+- `Read+Write` — modifies project files
+
+### For an update
+
+Find the existing row and update any changed fields in-place.
+
+## Step 6 — Create Pull Request
+
+Create a pull request with the changes. Use this branch naming convention:
+
+- **New extension:** `add-<extension-id>-extension`
+- **Update:** `update-<extension-id>-extension`
+
+### Commit message
+
+For a new extension:
+```
+Add <Name> extension to community catalog
+
+Add <id> extension submitted by @<issue-author> to:
+- extensions/catalog.community.json (alphabetical order)
+- docs/community/extensions.md community extensions table
+
+Closes #<issue-number>
+```
+
+For an update:
+```
+Update <Name> extension to v<version>
+
+Update <id> extension submitted by @<issue-author>:
+- extensions/catalog.community.json (version, download_url, etc.)
+- docs/community/extensions.md community extensions table
+
+Closes #<issue-number>
+```
+
+### PR description
+
+Include:
+- A summary of what changed
+- Validation results (all checks passed)
+- `Closes #${{ github.event.issue.number }}`
+- `cc @<issue-author>` — mention the submitter
+
+## Important Rules
+
+- **Alphabetical order matters** — entries must be sorted by ID in the JSON and
+  by name in the docs table
+- **Always validate JSON** after editing — a trailing comma or missing brace
+  will break the catalog
+- **Use `Closes` not `Fixes`** — `Closes #N` is the correct keyword for
+  submission issues
+- **Match the proposed entry but verify** — the issue may include a proposed
+  JSON block, but always validate field values against the actual repository
+  state rather than blindly trusting the submitter's JSON
+- **Preserve `created_at` on updates** — keep the original value; only update
+  `updated_at`
+- **Preserve `downloads` and `stars` on updates** — these reflect usage metrics
+  and must not be reset
+- **Do not modify any other files** — only `extensions/catalog.community.json`
+  and `docs/community/extensions.md`

.github/workflows/add-community-preset.md

@@ -0,0 +1,279 @@
+---
+description: "Process community preset submission issues — validate, add to catalog, and open a PR for maintainer review"
+emoji: "🎨"
+
+on:
+  issues:
+    types: [labeled]
+  skip-bots: [github-actions, copilot, dependabot]
+
+tools:
+  edit:
+  bash: ["echo", "cat", "head", "tail", "grep", "wc", "sort", "python3", "jq", "date"]
+  github:
+    toolsets: [issues, repos]
+  web-fetch:
+
+permissions:
+  contents: read
+  issues: read
+
+checkout:
+  fetch-depth: 0
+
+safe-outputs:
+  noop:
+    report-as-issue: false
+  create-pull-request:
+    title-prefix: "[preset] "
+    labels: [preset-submission, automated]
+    draft: true
+    max: 1
+    protected-files:
+      policy: blocked
+      exclude:
+        - README.md
+        - CHANGELOG.md
+  add-comment:
+    max: 2
+  add-labels:
+    allowed: [preset-submission, validation-passed, validation-failed, needs-info]
+    max: 3
+---
+
+# Add Community Preset from Issue Submission
+
+You are a catalog maintenance agent for the Spec Kit project. Your job is to
+process community preset submission issues and create pull requests that add
+or update entries in the community preset catalog.
+
+## Triggering Conditions
+
+This workflow only triggers when the `preset-submission` label is added to an
+issue. Before processing, verify that the issue title starts with `[Preset]:`.
+If it does not, stop without commenting.
+
+## Step 1 — Read and Parse the Issue
+
+Read issue #${{ github.event.issue.number }}.
+
+Extract the following fields from the structured issue body (GitHub issue form
+fields):
+
+| Field | Issue Form ID | Required |
+|-------|--------------|----------|
+| Preset ID | `preset-id` | Yes |
+| Preset Name | `preset-name` | Yes |
+| Version | `version` | Yes |
+| Description | `description` | Yes |
+| Author | `author` | Yes |
+| Repository URL | `repository` | Yes |
+| Download URL | `download-url` | Yes |
+| License | `license` | Yes |
+| Required Spec Kit Version | `speckit-version` | Yes |
+| Required Extensions | `required-extensions` | No |
+| Templates Provided | `templates-provided` | Yes |
+| Commands Provided | `commands-provided` | Yes |
+| Number of Scripts | `scripts-count` | No (default 0) |
+| Tags | `tags` | Yes |
+
+The issue body uses GitHub's issue form format. Each field appears under a
+heading matching the field label (e.g., `### Preset ID` followed by the
+value). Parse accordingly.
+
+## Step 2 — Validate the Submission
+
+Run **all** of the following validation checks. Collect all results before
+deciding pass/fail:
+
+### 2a. Preset ID format
+- Must match regex: `^[a-z][a-z0-9-]*$`
+- Must be lowercase with hyphens only
+
+### 2b. Version format
+- Must follow semver: `X.Y.Z` (digits only, no `v` prefix)
+
+### 2c. Repository validation
+- Fetch the repository URL — confirm it exists and is publicly accessible
+- Confirm the repository contains a `preset.yml` file
+- Confirm the repository contains a `README.md` file
+- Confirm the repository contains a `LICENSE` file
+
+### 2d. Release and download URL validation
+- The download URL should follow the pattern
+  `https://github.com/<owner>/<repo>/archive/refs/tags/v<version>.zip`
+  or
+  `https://github.com/<owner>/<repo>/releases/download/<tag>/<asset>.zip`
+- Verify a GitHub release exists matching the submitted version
+
+### 2e. Submission checklists
+- Confirm that all required checkboxes in the Testing Checklist and Submission
+  Requirements sections are checked (`[x]`)
+
+### Validation outcome
+
+If **any** validation fails:
+1. Add a comment on the issue listing each failed check with a clear explanation
+   of what's wrong and how to fix it
+2. Add the `validation-failed` label
+3. **Stop — do not proceed further**
+
+If all validations pass:
+1. Add the `validation-passed` label
+2. Continue to Step 3
+
+## Step 3 — Determine Add vs Update
+
+Search `presets/catalog.community.json` for the preset ID.
+
+- **Not found** → this is a **new addition**
+- **Found** → this is an **update** — replace the existing entry in-place;
+  preserve `created_at` from the existing entry
+
+## Step 4 — Update `presets/catalog.community.json`
+
+Edit `presets/catalog.community.json` to add or update the preset entry.
+
+### For a new preset
+
+Insert the entry in **alphabetical order by preset ID** within the
+`"presets"` object. Use this structure:
+
+```json
+{
+  "<id>": {
+    "name": "<name>",
+    "id": "<id>",
+    "version": "<version>",
+    "description": "<description>",
+    "author": "<author>",
+    "repository": "<repository>",
+    "download_url": "<download_url>",
+    "homepage": "<homepage or repository>",
+    "documentation": "<documentation or repository README>",
+    "license": "<license>",
+    "requires": {
+      "speckit_version": "<speckit_version>"
+    },
+    "provides": {
+      "templates": <N>,
+      "commands": <N>
+    },
+    "tags": ["<tag1>", "<tag2>"],
+    "created_at": "<today>T00:00:00Z",
+    "updated_at": "<today>T00:00:00Z"
+  }
+}
+```
+
+If the preset has required extensions, add an `"extensions"` array inside
+`"requires"`:
+
+```json
+"requires": {
+  "speckit_version": "<speckit_version>",
+  "extensions": ["<extension-id>"]
+}
+```
+
+If the preset provides scripts, add `"scripts": <N>` inside `"provides"`.
+
+### For an update
+
+Replace only the changed fields (typically `version`, `download_url`,
+`description`, `provides`, `requires`, `tags`, `updated_at`). **Preserve**
+`created_at` from the existing entry.
+
+### Counting templates and commands
+
+Parse the "Templates Provided" and "Commands Provided" issue fields:
+- Count the number of list items (lines starting with `-`)
+- If the field says "None", the count is 0
+
+### After editing
+
+Update the **top-level `"updated_at"` timestamp** in the catalog to today's date
+in ISO 8601 format.
+
+Validate the JSON by running:
+
+```bash
+python3 -c "import json; json.load(open('presets/catalog.community.json')); print('Valid JSON')"
+```
+
+If validation fails, fix the JSON and re-validate before continuing.
+
+## Step 5 — Update `docs/community/presets.md`
+
+Edit `docs/community/presets.md` to add or update a row in the Community
+Presets table.
+
+### For a new preset
+
+Insert a new row in **alphabetical order by preset name**:
+
+```
+| <Name> | <Description> | <N> templates, <N> commands | <Requires> | [<repo-name>](<repository-url>) |
+```
+
+For the Requires column:
+- Use `—` if no extensions are required
+- List required extension names if any (e.g., `AIDE extension`)
+
+If the preset provides scripts, include them: `<N> templates, <N> commands, <N> scripts`
+
+### For an update
+
+Find the existing row and update any changed fields in-place.
+
+## Step 6 — Create Pull Request
+
+Create a pull request with the changes. Use this branch naming convention:
+
+- **New preset:** `add-<preset-id>-preset`
+- **Update:** `update-<preset-id>-preset`
+
+### Commit message
+
+For a new preset:
+```
+Add <Name> preset to community catalog
+
+Add <id> preset submitted by @<issue-author> to:
+- presets/catalog.community.json (alphabetical order)
+- docs/community/presets.md community presets table
+
+Closes #<issue-number>
+```
+
+For an update:
+```
+Update <Name> preset to v<version>
+
+Update <id> preset submitted by @<issue-author>:
+- presets/catalog.community.json (version, download_url, etc.)
+- docs/community/presets.md community presets table
+
+Closes #<issue-number>
+```
+
+### PR description
+
+Include:
+- A summary of what changed
+- Validation results (all checks passed)
+- `Closes #${{ github.event.issue.number }}`
+- `cc @<issue-author>` — mention the submitter
+
+## Important Rules
+
+- **Alphabetical order matters** — entries must be sorted by ID in the JSON and
+  by name in the docs table
+- **Always validate JSON** after editing — a trailing comma or missing brace
+  will break the catalog
+- **Use `Closes` not `Fixes`** — `Closes #N` is the correct keyword for
+  submission issues
+- **Preserve `created_at` on updates** — keep the original value; only update
+  `updated_at`
+- **Do not modify any other files** — only `presets/catalog.community.json`
+  and `docs/community/presets.md`

.github/workflows/codeql.yml

@@ -22,11 +22,11 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4
+        uses: github/codeql-action/init@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4
         with:
           languages: ${{ matrix.language }}
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4
+        uses: github/codeql-action/analyze@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4
         with:
           category: "/language:${{ matrix.language }}"

.github/workflows/docs.yml

@@ -35,7 +35,7 @@ jobs:
           fetch-depth: 0 # Fetch all history for git info
 
       - name: Setup .NET
-        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
+        uses: actions/setup-dotnet@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5.3.0
         with:
           dotnet-version: '8.x'
 

.github/workflows/lint.yml

@@ -13,6 +13,28 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 1
+
+      - name: Run git diff --check
+        shell: bash
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          PUSH_BEFORE_SHA: ${{ github.event.before }}
+          GITHUB_SHA: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            git fetch --no-tags --depth=1 origin "+${PR_BASE_SHA}:refs/checks/pr-base"
+            git diff --check refs/checks/pr-base HEAD
+          elif [ "$PUSH_BEFORE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            git diff-tree --check --no-commit-id --root -r "$GITHUB_SHA"
+          else
+            git fetch --no-tags --depth=1 origin "+${PUSH_BEFORE_SHA}:refs/checks/push-before"
+            git diff --check refs/checks/push-before HEAD
+          fi
 
       - name: Run markdownlint-cli2
         uses: DavidAnson/markdownlint-cli2-action@ded1f9488f68a970bc66ea5619e13e9b52e601cd # v23

.github/workflows/stale.yml

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

AGENTS.md

@@ -147,12 +147,12 @@ class CodexIntegration(SkillsIntegration):
 
 | Field | Location | Purpose |
 |---|---|---|
-| `key` | Class attribute | Unique identifier; for CLI-based integrations (`requires_cli: True`), must match the CLI executable name |
+| `key` | Class attribute | Unique identifier; for most CLI-based integrations this matches the executable name, but see `cli_executable` below for exceptions |
 | `config` | Class attribute (dict) | Agent metadata: `name`, `folder`, `commands_subdir`, `install_url`, `requires_cli` |
 | `registrar_config` | Class attribute (dict) | Command output config: `dir`, `format`, `args` placeholder, file `extension` |
 | `context_file` | Class attribute (str or None) | Path to agent context/instructions file (e.g., `"CLAUDE.md"`, `".github/copilot-instructions.md"`) |
 
-**Key design rule:** For CLI-based integrations (`requires_cli: True`), `key` must be the actual executable name (e.g., `"cursor-agent"` not `"cursor"`). This ensures `shutil.which(key)` works for CLI-tool checks without special-case mappings. IDE-based integrations (`requires_cli: False`) should use their canonical identifier (e.g., `"windsurf"`, `"copilot"`).
+**Key design rule:** For CLI-based integrations (`requires_cli: True`), `key` should generally match the CLI executable name so that the default `is_cli_available()` check works without any override. When the executable name differs from the key (e.g., RovoDev's key is `"rovodev"` but the binary is `"acli"`), override the `cli_executable` property or `is_cli_available()` method — see [§6 Optional overrides](#6-optional-overrides) below. IDE-based integrations (`requires_cli: False`) should use their canonical identifier (e.g., `"windsurf"`, `"copilot"`).
 
 ### 3. Register it
 
@@ -177,7 +177,24 @@ def _register_builtins() -> None:
 
 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.
 
-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.
+The managed section is owned by the bundled `agent-context` extension (`extensions/agent-context/`). All configuration flows through the extension's own config file at `.specify/extensions/agent-context/agent-context-config.yml`:
+
+```yaml
+# Path to the coding agent context file managed by this extension
+context_file: CLAUDE.md
+
+# Delimiters for the managed Spec Kit section
+context_markers:
+  start: "<!-- SPECKIT START -->"
+  end: "<!-- SPECKIT END -->"
+```
+
+- `context_file` is written automatically from the integration's class attribute when `specify init` or `specify integration use` is run.
+- `context_markers.{start,end}` defaults to `IntegrationBase.CONTEXT_MARKER_START` / `CONTEXT_MARKER_END`. Users who want custom markers edit `agent-context-config.yml` directly — both the Python layer (`upsert_context_section()` / `remove_context_section()`) and the bundled scripts (`extensions/agent-context/scripts/bash/update-agent-context.sh` and `.ps1`) read from this single source of truth.
+
+Users can opt out entirely with `specify extension disable agent-context`; while disabled, Spec Kit skips context-file creation, updates, and removal (the gates are inside `upsert_context_section()` and `remove_context_section()`).
+
+Only add custom setup logic when the agent needs non-standard behavior. Integrations no longer require per-agent thin wrapper scripts or shared context-update dispatcher scripts — the `agent-context` extension is fully generic.
 
 ### 5. Test it
 
@@ -205,11 +222,37 @@ The base classes handle most work automatically. Override only when the agent de
 
 | Override | When to use | Example |
 |---|---|---|
+| `cli_executable` | Binary name differs from `key` | RovoDev: key `"rovodev"`, binary `"acli"` → override returns `"acli"` |
+| `is_cli_available()` | Multiple binary names or non-PATH installs | Claude checks `~/.claude/local/`; Kiro accepts both `kiro-cli` and `kiro` |
 | `command_filename(template_name)` | Custom file naming or extension | Copilot → `speckit.{name}.agent.md` |
 | `options()` | Integration-specific CLI flags via `--integration-options` | Codex → `--skills` flag, Copilot → `--skills` flag |
 | `setup()` | Custom install logic (companion files, settings merge) | Copilot → `.agent.md` + `.prompt.md` + `.vscode/settings.json` (default) or `speckit-<name>/SKILL.md` (skills mode) |
 | `teardown()` | Custom uninstall logic | Rarely needed; base handles manifest-tracked files |
 
+**`cli_executable` property** — Return the binary name to look up on `PATH` for tool-availability checks. The default implementation returns `self.key`. Override when the executable name differs from the integration key:
+
+```python
+@property
+def cli_executable(self) -> str:
+    return "acli"  # e.g. RovoDev: key="rovodev", binary="acli"
+```
+
+**`is_cli_available()` method** — Return `True` if the integration's CLI tool is installed. The default implementation calls `shutil.which(self.cli_executable)`. Override for more complex detection:
+
+```python
+def is_cli_available(self) -> bool:
+    # Multiple binary names (Kiro):
+    return shutil.which("kiro-cli") is not None or shutil.which("kiro") is not None
+
+    # Non-PATH install locations (Claude):
+    import specify_cli._utils as _utils_mod
+    if _utils_mod.CLAUDE_LOCAL_PATH.is_file() or _utils_mod.CLAUDE_NPM_LOCAL_PATH.is_file():
+        return True
+    return shutil.which(self.cli_executable) is not None
+```
+
+`is_cli_available()` is used by `check_tool()` in `_utils.py` and by both `CommandStep` and `PromptStep` workflow steps to gate CLI dispatch. No hardcoded special cases should be added to those callers — encode detection logic in the integration class instead.
+
 **Example — Copilot (fully custom `setup`):**
 
 Copilot extends `IntegrationBase` directly because it creates `.agent.md` commands, companion `.prompt.md` files, and merges `.vscode/settings.json`. It also supports a `--skills` mode that scaffolds `speckit-<name>/SKILL.md` under `.github/skills/` using composition with an internal `_CopilotSkillsHelper`. See `src/specify_cli/integrations/copilot/__init__.py` for the full implementation.
@@ -379,10 +422,48 @@ Implementation: Extends `YamlIntegration` (parallel to `TomlIntegration`):
 4. Uses `yaml.safe_dump()` for header fields to ensure proper escaping
 5. Sets `context_file = "AGENTS.md"` so the base setup manages the Spec Kit context section there
 
+## Branch Naming Convention
+
+Branches follow one of two patterns depending on whether an issue exists:
+
+```
+<type>/<number>-<short-slug>   # when an issue is created first
+<type>/<short-slug>            # when no issue exists (PR-only changes)
+```
+
+When an issue exists, include its number immediately after the prefix — this is what makes branches traceable. For small or self-contained changes that go straight to a PR without a tracking issue, omit the number.
+
+| Prefix | When to use | Example |
+|---|---|---|
+| `feat/` | New features | `feat/2342-workflow-cli-alignment` |
+| `fix/` | Bug fixes | `fix/2653-paths-only-validation` |
+| `docs/` | Documentation changes | `docs/2677-branch-naming-convention`, `docs/update-landing-stats` |
+| `community/` | Community catalog additions | `community/2492-add-mde-extension` |
+| `chore/` | Maintenance, tooling, CI | `chore/2366-editorconfig` |
+
+**Rules:**
+
+1. Include the issue number when one exists — this is what makes branches traceable
+2. Use kebab-case for the slug
+3. Keep the slug short — enough to identify the work without looking up the issue
+
+---
+
+## Responding to PR Review Comments
+
+- If you are an agent working on behalf of a human, **disclose your identity in your PR comment** — name the agent (and model, if applicable) and the human you are acting for (e.g., "Posted on behalf of @user by GitHub Copilot (model: &lt;name-if-known&gt;)").
+- Post **one** top-level summary comment per review round listing what changed and the commit SHA. Do not reply on every individual comment.
+- Reply inline only when context is needed (disagreement, deferral, non-obvious fix). Keep it to a sentence or two.
+- **Never click "Resolve conversation"** — that belongs to the reviewer or PR author.
+- No emoji, no celebratory framing, no checklist mirroring the reviewer's items, no restating what the reviewer wrote.
+- Re-request review once per round (when all feedback is addressed), not after every intermediate push.
+
+---
+
 ## Common Pitfalls
 
-1. **Using shorthand keys for CLI-based integrations**: For CLI-based integrations (`requires_cli: True`), the `key` must match the executable name (e.g., `"cursor-agent"` not `"cursor"`). `shutil.which(key)` is used for CLI tool checks — mismatches require special-case mappings. IDE-based integrations (`requires_cli: False`) are not subject to this constraint.
-2. **Forgetting update scripts**: Both bash and PowerShell thin wrappers and the shared context-update scripts must be updated.
+1. **Using shorthand keys for CLI-based integrations**: For CLI-based integrations (`requires_cli: True`), `key` should generally match the executable name. When it cannot (e.g., the binary name differs), override `cli_executable` or `is_cli_available()` on the integration class. Do **not** add special-case mappings to `check_tool()`, `CommandStep`, or `PromptStep`.
+2. **Forgetting context configuration**: The bundled `agent-context` extension reads from `.specify/extensions/agent-context/agent-context-config.yml`. New integrations only need to set `context_file` on the class — markers and dispatcher scripts are managed centrally.
 3. **Incorrect `requires_cli` value**: Set to `True` only for agents that have a CLI tool; set to `False` for IDE-based agents.
 4. **Wrong argument format**: Use `$ARGUMENTS` for Markdown agents, `{{args}}` for TOML agents.
 5. **Skipping registration**: The import and `_register()` call in `_register_builtins()` must both be added.

CHANGELOG.md

@@ -2,6 +2,241 @@
 
 <!-- insert new changelog below this comment -->
 
+## [0.9.4] - 2026-06-04
+
+### Changed
+
+- feat(workflows): add JSON output for workflow run resume and status (#2814)
+- Update workflow-preset community catalog to v1.3.2 (#2841)
+- fix: recover active skills registration for extensions (#2803)
+- fix(cursor-agent): enable headless CLI dispatch end-to-end (-p --trust --approve-mcps --force + Windows .cmd shim resolution) (#2631)
+- Update Superpowers Implementation Bridge extension to v1.0.2 (#2852)
+- docs(agents): add PR review response guidance to AGENTS.md (#2850)
+- Allow `specify workflow run` to execute YAML files without a project (#2825)
+- feat(extensions): add --force flag to extension add for overwrite reinstall (#2530)
+- chore: release 0.9.3, begin 0.9.4.dev0 development (#2836)
+
+## [0.9.3] - 2026-06-03
+
+### Changed
+
+- fix: render script command hints with active agent separator (#2649)
+- chore(tests): fix ruff lint violations in tests/ (#2827)
+- fix(workflows): validate run_id in RunState.load before touching the … (#2813)
+- feat(cli): implement specify self upgrade (#2475)
+- feat(workflows): allow resume to accept updated workflow inputs (#2815)
+- catalog: rename "superpowers-bridge" to "superspec" (v1.0.1) (#2772)
+- fix(cli): force UTF-8 stdout/stderr on Windows to prevent UnicodeEncodeError (#2817)
+- fix(plan): clarify quickstart validation guide scope (#2805)
+- chore: release 0.9.2, begin 0.9.3.dev0 development (#2823)
+
+## [0.9.2] - 2026-06-02
+
+### Changed
+
+- Update agent parity governance preset catalog entry (#2777)
+- fix: resolve GitHub release asset API URL for private repo extension downloads (#2792)
+- fix: remove unsupported mode: frontmatter from Copilot skills mode (fixes #2799) (#2819)
+- refactor(integrations): co-locate integration commands in integrations/ domain dir (PR-5/8) (#2720)
+- Update Product Forge extension to v1.6.0 (#2820)
+- feat(workflows): add continue_on_error step field for non-halting failures (#2663)
+- chore: add .editorconfig for consistent code formatting (#2366)
+- fix(shared-infra): record skipped files in speckit.manifest.json (#2483)
+- chore: release 0.9.1, begin 0.9.2.dev0 development (#2818)
+
+## [0.9.1] - 2026-06-02
+
+### Changed
+
+- fix(cli): pin UTF-8 encoding on init-options and .extensionignore I/O (#2686)
+- docs: list Hermes in supported integrations table (#2768)
+- fix(copilot): resolve active spec template (#2765)
+- fix: add missing agent-context extension entries to Cline _expected_files (#2797)
+- Add spec-kit-linear extension to community catalog (#2795)
+- feat: add native Cline integration (#2508)
+- Update workflow-preset community catalog entry (#2756)
+- chore: release 0.9.0, begin 0.9.1.dev0 development (#2794)
+- Add RAG Azure Builder extension to community catalog (#2793)
+
+## [0.9.0] - 2026-06-01
+
+### Changed
+
+- chore: recompile workflow lock files (#2774)
+- Add Multi-Sites Spec Kit extension to community catalog (#2791)
+- Update Product Spec Extension to v0.8.3 (#2790)
+- Publish May 2026 Newsletter (#2787)
+- fix: move URL install confirmation prompt before spinner (#2783) (#2784)
+- Update Reqnroll BDD extension to v1.1.0 (#2775)
+- Extract agent context updates into bundled agent-context extension (#2546)
+- chore(deps): bump actions/setup-dotnet from 5.2.0 to 5.3.0 (#2755)
+- chore: release 0.8.18, begin 0.8.19.dev0 development (#2766)
+
+## [0.8.18] - 2026-05-29
+
+### Changed
+
+- Add support for SPECKIT_WORKFLOW_RUN_ID override (#2742)
+- feat: support SPECKIT_INTEGRATION_<KEY>_EXECUTABLE env var (#2743)
+- chore(deps): bump github/gh-aw-actions from 0.74.8 to 0.77.0 (#2754)
+- chore(deps): bump github/codeql-action from 4.35.5 to 4.36.0 (#2753)
+- fix: disable no-op issue reporting for catalog submission workflows (#2748)
+- Add confirmation prompt for URL-based extension installs (#2745)
+- fix: restrict community submission workflows to labeled event only (#2741)
+- feat(integrations): support SPECIFY_<KEY>_EXTRA_ARGS env var for agent subprocess flags (#2596)
+- chore: release 0.8.17, begin 0.8.18.dev0 development (#2737)
+
+## [0.8.17] - 2026-05-28
+
+### Changed
+
+- docs: consolidate Community sections in README (#2736)
+- Fix shared script command hints for integration separators (#2627)
+- docs: update security-governance preset to v0.4.0 (#2703)
+- feat(agy): enhance Google Antigravity CLI integration (#2689)
+- Fix --dev extension agent symlinks (#2554)
+- Share skills hook note post-processing (#2679)
+- feat: add Hermes Agent integration (with review fixes) (#2651)
+- Update Superpowers Implementation Bridge to v0.7.0 (#2732)
+- chore: release 0.8.16, begin 0.8.17.dev0 development (#2729)
+
+## [0.8.16] - 2026-05-27
+
+### Changed
+
+- docs: update landing page stats and branch naming convention (#2727)
+- feat(workflows): expose {{ context.run_id }} template variable (#2664)
+- fix: resolve __SPECKIT_COMMAND_*__ refs in preset skill rendering (#2717) (#2718)
+- Add Workflow Preset to community catalog (#2725)
+- fix: paths-only skips branch validation, setup-plan preserves existing plan (#2672)
+- docs: fix broken pipx homepage URLs to point to pipx.pypa.io (#2670)
+- Update Architecture Guard extension to v1.8.9 (#2723)
+- Re-validate spec quality checklist after clarify updates spec (#2715)
+- chore: release 0.8.15, begin 0.8.16.dev0 development (#2722)
+
+## [0.8.15] - 2026-05-27
+
+### Changed
+
+- Update Fiction Book Writing preset to v1.8.1 (#2714)
+- chore: update memorylint and superb to 1.4.0 (#2690)
+- fix: promote post-execution hook dispatch to H2 with directive language (#2713)
+- Add Token Budget extension to community catalog (#2712)
+- fix: create skills directory on demand during extension/preset install (#2711)
+- fix: PS 5.1 compat — replace non-ASCII chars in shipped PowerShell scripts (#2709)
+- docs: update security-governance preset to v0.3.0 (#2676)
+- Update README.md (#2675)
+- chore: release 0.8.14, begin 0.8.15.dev0 development (#2706)
+
+## [0.8.14] - 2026-05-26
+
+### Changed
+
+- Add util for windows sub-process (#2598)
+- refactor: create commands/ package and move init handler (PR-4/8) (#2615)
+- Add Product Spec Extension to community catalog (#2705)
+- fix init-options speckit version refresh (#2647)
+- chore(deps): bump github/gh-aw-actions from 0.74.8 to 0.74.9 (#2658)
+- docs: add branch naming convention to AGENTS.md and CONTRIBUTING.md (#2678)
+- chore(deps): bump actions/stale from 10.2.0 to 10.3.0 (#2657)
+- chore(deps): bump github/codeql-action from 4.35.4 to 4.35.5 (#2656)
+- chore: release 0.8.13, begin 0.8.14.dev0 development (#2669)
+
+## [0.8.13] - 2026-05-21
+
+### Changed
+
+- fix: while/do-while loop condition reads stale iteration-0 step output (#2662)
+- docs: fix directory hierarchy in README examples (#2639)
+- fix(catalogs): reject boolean priority in extension and preset catalog readers (#2589)
+- Update Agent Governance extension to v1.2.0 (#2659)
+- Add agentic workflows for community catalog submissions (#2655)
+- feat: add self-check tip to check output (#2574)
+- fix(cli): clarify exception diagnostics (#2602)
+- ci: add diff whitespace check (#2572)
+- chore: release 0.8.12, begin 0.8.13.dev0 development (#2648)
+
+## [0.8.12] - 2026-05-20
+
+### Changed
+
+- fix(codex): inject dot-to-hyphen hook command note in Codex skills (#2503)
+- Update Squad Bridge extension to v1.3.0 (#2645)
+- Update Superpowers Implementation Bridge extension to v0.5.0 (#2644)
+- Add Team Assign extension to community catalog (#2642)
+- refactor: migrate extension catalog stack parsing to shared base (#2576)
+- Update Architecture Workflow extension to v1.1.0 (#2588)
+-  fix(workflow): support integration: auto to follow project's initialized AI (#2421)
+- Add Superpowers Implementation Bridge extension to community catalog (#2586)
+- Add Interactive HTML Preview extension to community catalog (#2585)
+- chore: release 0.8.11, begin 0.8.12.dev0 development (#2584)
+- Update Agent Governance extension to v1.1.0 (#2583)
+
+## [0.8.11] - 2026-05-15
+
+### Changed
+
+- refactor: extract _version.py from __init__.py (PR-3/8) (#2550)
+- Add Time Machine extension to community catalog (#2580)
+- fix(powershell): ensure UTF-8 templates are written without BOM (#2280)
+- docs: document high-assurance spec workflow (#2518)
+- docs: fix script name in directory tree examples (#2555)
+- Fix preset skill description precedence (#2538)
+- fix(integration): clarify multi-install guidance (#2549)
+- feat: add version feature reporting (#2548)
+- Add Architecture Workflow extension to community catalog (#2565)
+- chore: release 0.8.10, begin 0.8.11.dev0 development (#2562)
+
+## [0.8.10] - 2026-05-14
+
+### Changed
+
+- docs: streamline install section and add community overview (#2561)
+- Move community extensions table from README to docs site (#2560)
+- Add Agent Governance extension to community catalog (#2559)
+- Add Reqnroll BDD extension to community catalog (#2545)
+- fix(cli): harden extension registration and discovery workflows (#2499)
+- refactor: extract _assets.py and _utils.py from __init__.py (PR-2/8) (#2543)
+- fix(opencode): use commands/ directory (plural) to match OpenCode docs (#2453)
+- refactor: extract _console.py from __init__.py (PR-1/8) (#2474)
+- Fix constitution reference in README (#2491)
+- chore: release 0.8.9, begin 0.8.10.dev0 development (#2532)
+
+## [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

CONTRIBUTING.md

@@ -38,7 +38,7 @@ On [GitHub Codespaces](https://github.com/features/codespaces) it's even simpler
 1. Fork and clone the repository
 1. Configure and install the dependencies: `uv sync --extra test`
 1. Make sure the CLI works on your machine: `uv run specify --help`
-1. Create a new branch: `git checkout -b my-branch-name`
+1. Create a new branch: `git checkout -b <type>/<number>-<short-slug>` (see [Branch naming](#branch-naming) below)
 1. Make your change, add tests, and make sure everything still works
 1. Test the CLI functionality with a sample project if relevant
 1. Push to your fork and submit a pull request
@@ -55,6 +55,20 @@ Here are a few things you can do that will increase the likelihood of your pull
 - Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
 - Test your changes with the Spec-Driven Development workflow to ensure compatibility.
 
+### Branch naming
+
+We recommend naming branches as `<type>/<number>-<short-slug>`, where `<number>` is the issue or PR number (whichever comes first) and `<type>` is one of:
+
+| Prefix | When to use | Example |
+|---|---|---|
+| `feat/` | New features | `feat/2342-workflow-cli-alignment` |
+| `fix/` | Bug fixes | `fix/2653-paths-only-validation` |
+| `docs/` | Documentation changes | `docs/2677-branch-naming-convention` |
+| `community/` | Community catalog additions | `community/2492-add-mde-extension` |
+| `chore/` | Maintenance, tooling, CI | `chore/2366-editorconfig` |
+
+Including the issue or PR number makes branches traceable — especially useful since the project uses squash merges and `git branch --merged` won't detect merged branches. If you start with a PR (no issue), use the PR number once it's assigned.
+
 ## Development workflow
 
 When working on spec-kit:

README.md

@@ -22,10 +22,7 @@
 - [🤔 What is Spec-Driven Development?](#-what-is-spec-driven-development)
 - [⚡ Get Started](#-get-started)
 - [📽️ Video Overview](#️-video-overview)
-- [🧩 Community Extensions](#-community-extensions)
-- [🎨 Community Presets](#-community-presets)
-- [🚶 Community Walkthroughs](#-community-walkthroughs)
-- [🛠️ Community Friends](#️-community-friends)
+- [🌍 Community](#-community)
 - [🤖 Supported AI Coding Agent Integrations](#-supported-ai-coding-agent-integrations)
 - [🔧 Specify CLI Reference](#-specify-cli-reference)
 - [🧩 Making Spec Kit Your Own: Extensions & Presets](#-making-spec-kit-your-own-extensions--presets)
@@ -35,7 +32,6 @@
 - [🔧 Prerequisites](#-prerequisites)
 - [📖 Learn More](#-learn-more)
 - [📋 Detailed Process](#-detailed-process)
-- [🔍 Troubleshooting](#-troubleshooting)
 - [💬 Support](#-support)
 - [🙏 Acknowledgements](#-acknowledgements)
 - [📄 License](#-license)
@@ -48,83 +44,40 @@ Spec-Driven Development **flips the script** on traditional software development
 
 ### 1. Install Specify CLI
 
-Choose your preferred installation method:
-
-> **Important:** The only official, maintained packages for Spec Kit are published from this GitHub repository. Any packages with the same name on PyPI are **not** affiliated with this project and are not maintained by the Spec Kit maintainers. Always install directly from GitHub as shown below.
-
-#### Option 1: Persistent Installation (Recommended)
-
-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.
+Requires **[uv](https://docs.astral.sh/uv/)** ([install uv](./docs/install/uv.md)). Replace `vX.Y.Z` with the latest tag from [Releases](https://github.com/github/spec-kit/releases):
 
 ```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
-
-# Or install latest from main (may include unreleased changes)
-uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
-
-# Alternative: using pipx (also works)
-pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z
-pipx install git+https://github.com/github/spec-kit.git
 ```
 
-Then verify the correct version is installed:
+See the [Installation Guide](./docs/installation.md) for alternative methods, verification, upgrade, and troubleshooting.
+
+### 2. Initialize a project
 
 ```bash
-specify version
+specify init my-project --integration copilot
+cd my-project
 ```
 
-And use the tool directly:
+To check for updates or upgrade the installed CLI, use the self-management commands. See the [Upgrade Guide](./docs/upgrade.md) for detailed scenarios and customization options.
 
 ```bash
-# Create new project
-specify init <PROJECT_NAME>
+# Check whether a newer release is available (read-only — does not modify anything)
+specify self check
 
-# Or initialize in existing project
-specify init . --integration copilot
-# or
-specify init --here --integration copilot
+# Preview what would run, without actually upgrading
+specify self upgrade --dry-run
 
-# Check installed tools
-specify check
+# Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install)
+specify self upgrade
+
+# Or pin a specific release tag (replace vX.Y.Z[suffix] with your desired release tag)
+specify self upgrade --tag vX.Y.Z[suffix]
 ```
 
-To upgrade Specify, see the [Upgrade Guide](./docs/upgrade.md) for detailed instructions. Quick upgrade:
+Bare `specify self upgrade` executes immediately, matching the no-prompt behavior of commands like `pip install -U` and `npm update`. For `uv tool` installs, it runs `uv tool install specify-cli --force --from <git ref>` under the hood so pinned release tags work, including dev, alpha/beta/rc, or build metadata suffixes. `uvx` (ephemeral) runs and source checkouts are detected and produce path-specific guidance instead of running an installer. Set `SPECIFY_UPGRADE_TIMEOUT_SECS` to cap how long the installer subprocess may run (default: no timeout — interrupt with `Ctrl+C` if needed).
 
-```bash
-uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z
-# pipx users: pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z
-```
-
-#### Option 2: One-time Usage
-
-Run directly without installing:
-
-```bash
-# Create new project (pinned to a stable release — 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>
-
-# Or initialize in existing project
-uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init . --integration copilot
-# or
-uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --integration copilot
-```
-
-**Benefits of persistent installation:**
-
-- Tool stays installed and available in PATH
-- No need to create shell aliases
-- Better tool management with `uv tool list`, `uv tool upgrade`, `uv tool uninstall`
-- Cleaner shell configuration
-
-#### Option 3: Enterprise / Air-Gapped Installation
-
-If your environment blocks access to PyPI or GitHub, see the [Enterprise / Air-Gapped Installation](./docs/installation.md#enterprise--air-gapped-installation) guide for step-by-step instructions on using `pip download` to create portable, OS-specific wheel bundles on a connected machine.
-
-### 2. Establish project principles
+### 3. Establish project principles
 
 Launch your coding agent in the project directory. Most agents expose spec-kit as `/speckit.*` slash commands; Codex CLI in skills mode uses `$speckit-*` instead.
 
@@ -134,7 +87,7 @@ Use the **`/speckit.constitution`** command to create your project's governing p
 /speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements
 ```
 
-### 3. Create the spec
+### 4. Create the spec
 
 Use the **`/speckit.specify`** command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.
 
@@ -142,7 +95,7 @@ Use the **`/speckit.specify`** command to describe what you want to build. Focus
 /speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.
 ```
 
-### 4. Create a technical implementation plan
+### 5. Create a technical implementation plan
 
 Use the **`/speckit.plan`** command to provide your tech stack and architecture choices.
 
@@ -150,7 +103,7 @@ Use the **`/speckit.plan`** command to provide your tech stack and architecture
 /speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.
 ```
 
-### 5. Break down into tasks
+### 6. Break down into tasks
 
 Use **`/speckit.tasks`** to create an actionable task list from your implementation plan.
 
@@ -158,7 +111,7 @@ Use **`/speckit.tasks`** to create an actionable task list from your implementat
 /speckit.tasks
 ```
 
-### 6. Execute implementation
+### 7. Execute implementation
 
 Use **`/speckit.implement`** to execute all tasks and build your feature according to the plan.
 
@@ -174,143 +127,19 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c
 
 [![Spec Kit video header](/media/spec-kit-video-header.jpg)](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)
 
-## 🧩 Community Extensions
+## 🌍 Community
+
+Explore community-contributed resources on the [Spec Kit docs site](https://github.github.io/spec-kit/):
+
+- [Extensions](https://github.github.io/spec-kit/community/extensions.html) — commands, hooks, and capabilities
+- [Presets](https://github.github.io/spec-kit/community/presets.html) — template and terminology overrides
+- [Walkthroughs](https://github.github.io/spec-kit/community/walkthroughs.html) — end-to-end SDD scenarios
+- [Friends](https://github.github.io/spec-kit/community/friends.html) — projects that extend or build on Spec Kit
 
 > [!NOTE]
-> 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.
+> Community contributions are independently created and maintained by their respective authors. Review 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/).**
-
-The following community-contributed extensions are available in [`catalog.community.json`](extensions/catalog.community.json):
-
-**Categories:**
-
-- `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:**
-
-- `Read-only` — produces reports without modifying files
-- `Read+Write` — modifies files, creates artifacts, or updates specs
-
-| Extension | Purpose | Category | Effect | URL |
-|-----------|---------|----------|--------|-----|
-| 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) |
-| 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) |
-| CI Guard | Spec compliance gates for CI/CD — verify specs exist, check drift, and block merges on gaps | `process` | Read-only | [spec-kit-ci-guard](https://github.com/Quratulain-bilal/spec-kit-ci-guard) |
-| Checkpoint Extension | Commit the changes made during the middle of the implementation, so you don't end up with just one very large commit at the end | `code` | Read+Write | [spec-kit-checkpoint](https://github.com/aaronrsun/spec-kit-checkpoint) |
-| 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) |
-| FixIt Extension | Spec-aware bug fixing — maps bugs to spec artifacts, proposes a plan, applies minimal changes | `code` | Read+Write | [spec-kit-fixit](https://github.com/speckit-community/spec-kit-fixit) |
-| 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) |
-| MAQA — Multi-Agent & Quality Assurance | Coordinator → feature → QA agent workflow with parallel worktree-based implementation. Language-agnostic. Auto-detects installed board plugins. Optional CI gate. | `process` | Read+Write | [spec-kit-maqa-ext](https://github.com/GenieRobot/spec-kit-maqa-ext) |
-| MAQA Azure DevOps Integration | Azure DevOps Boards integration for MAQA — syncs User Stories and Task children as features progress | `integration` | Read+Write | [spec-kit-maqa-azure-devops](https://github.com/GenieRobot/spec-kit-maqa-azure-devops) |
-| MAQA CI/CD Gate | Auto-detects GitHub Actions, CircleCI, GitLab CI, and Bitbucket Pipelines. Blocks QA handoff until pipeline is green. | `process` | Read+Write | [spec-kit-maqa-ci](https://github.com/GenieRobot/spec-kit-maqa-ci) |
-| MAQA GitHub Projects Integration | GitHub Projects v2 integration for MAQA — syncs draft issues and Status columns as features progress | `integration` | Read+Write | [spec-kit-maqa-github-projects](https://github.com/GenieRobot/spec-kit-maqa-github-projects) |
-| MAQA Jira Integration | Jira integration for MAQA — syncs Stories and Subtasks as features progress through the board | `integration` | Read+Write | [spec-kit-maqa-jira](https://github.com/GenieRobot/spec-kit-maqa-jira) |
-| 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 | 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) |
-| Plan Review Gate | Require spec.md and plan.md to be merged via MR/PR before allowing task generation | `process` | Read-only | [spec-kit-plan-review-gate](https://github.com/luno/spec-kit-plan-review-gate) |
-| PR Bridge | Auto-generate pull request descriptions, checklists, and summaries from spec artifacts | `process` | Read-only | [spec-kit-pr-bridge-](https://github.com/Quratulain-bilal/spec-kit-pr-bridge-) |
-| Presetify | Create and validate presets and preset catalogs | `process` | Read+Write | [presetify](https://github.com/mnriem/spec-kit-extensions/tree/main/presetify) |
-| Product Forge | Full product lifecycle from research to release — portfolio, lite mode, monorepo, optional V-Model | `process` | Read+Write | [speckit-product-forge](https://github.com/VaiYav/speckit-product-forge) |
-| 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-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) |
-| Retro Extension | Sprint retrospective analysis with metrics, spec accuracy assessment, and improvement suggestions | `process` | Read+Write | [spec-kit-retro](https://github.com/arunt14/spec-kit-retro) |
-| Retrospective Extension | Post-implementation retrospective with spec adherence scoring, drift analysis, and human-gated spec updates | `docs` | Read+Write | [spec-kit-retrospective](https://github.com/emi-dm/spec-kit-retrospective) |
-| Review Extension | Post-implementation comprehensive code review with specialized agents for code quality, comments, tests, error handling, type design, and simplification | `code` | Read-only | [spec-kit-review](https://github.com/ismaelJimenez/spec-kit-review) |
-| Ripple | Detect side effects that tests can't catch after implementation — delta-anchored analysis across 9 domain-agnostic categories | `code` | Read+Write | [spec-kit-ripple](https://github.com/chordpli/spec-kit-ripple) |
-| SDD Utilities | Resume interrupted workflows, validate project health, and verify spec-to-task traceability | `process` | Read+Write | [speckit-utils](https://github.com/mvanhorn/speckit-utils) |
-| 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 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 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) |
-| Version Guard | Verify tech stack versions against live npm registries before planning and implementation | `process` | Read-only | [spec-kit-version-guard](https://github.com/KevinBrown5280/spec-kit-version-guard) |
-| What-if Analysis | Preview the downstream impact (complexity, effort, tasks, risks) of requirement changes before committing to them | `visibility` | Read-only | [spec-kit-whatif](https://github.com/DevAbdullah90/spec-kit-whatif) |
-| Wireframe Visual Feedback Loop | SVG wireframe generation, review, and sign-off for spec-driven development. Approved wireframes become spec constraints honored by /speckit.plan, /speckit.tasks, and /speckit.implement | `visibility` | Read+Write | [spec-kit-extension-wireframe](https://github.com/TortoiseWolfe/spec-kit-extension-wireframe) |
-| Work IQ | Integrate Microsoft 365 organizational knowledge into spec-driven development workflows | `integration` | Read-only | [spec-kit-workiq](https://github.com/sakitA/spec-kit-workiq) |
-| Worktree Isolation | Spawn isolated git worktrees for parallel feature development without checkout switching | `process` | Read+Write | [spec-kit-worktree](https://github.com/Quratulain-bilal/spec-kit-worktree) |
-| Worktrees | Default-on worktree isolation for parallel agents — sibling or nested layout | `process` | Read+Write | [spec-kit-worktree-parallel](https://github.com/dango85/spec-kit-worktree-parallel) |
-
-To submit your own extension, see the [Extension Publishing Guide](extensions/EXTENSION-PUBLISHING-GUIDE.md).
-
-## 🎨 Community Presets
-
-Community-contributed presets customize how Spec Kit behaves — overriding templates, commands, and terminology without changing any tooling. See the full list on the [Community Presets](https://github.github.io/spec-kit/community/presets.html) page.
-
-> [!NOTE]
-> Community presets are third-party contributions and are not maintained by the Spec Kit team. Review them carefully before use, and see the docs page above for the full disclaimer.
-
-To submit your own preset, see the [Presets Publishing Guide](presets/PUBLISHING.md).
-
-## 🚶 Community Walkthroughs
-
-See Spec-Driven Development in action across different scenarios with community-contributed walkthroughs; find the full list on the [Community Walkthroughs](https://github.github.io/spec-kit/community/walkthroughs.html) page.
-
-## 🛠️ Community Friends
-
-Community projects that extend, visualize, or build on Spec Kit. See the full list on the [Community Friends](https://github.github.io/spec-kit/community/friends.html) page.
+Want to contribute? See the [Extension Publishing Guide](extensions/EXTENSION-PUBLISHING-GUIDE.md) or the [Presets Publishing Guide](presets/PUBLISHING.md).
 
 ## 🤖 Supported AI Coding Agent Integrations
 
@@ -322,7 +151,7 @@ Run `specify integration list` to see all available integrations in your install
 
 After running `specify init`, your AI coding agent will have access to these slash commands for structured development. For integrations that support skills mode, passing `--integration <agent> --integration-options="--skills"` installs agent skills instead of slash-command prompt files.
 
-#### Core Commands
+### Core Commands
 
 Essential commands for the Spec-Driven Development workflow:
 
@@ -335,7 +164,7 @@ Essential commands for the Spec-Driven Development workflow:
 | `/speckit.taskstoissues` | `speckit-taskstoissues`| Convert generated task lists into GitHub issues for tracking and execution |
 | `/speckit.implement`     | `speckit-implement`    | Execute all tasks to build the feature according to the plan               |
 
-#### Optional Commands
+### Optional Commands
 
 Additional commands for enhanced quality and validation:
 
@@ -380,7 +209,7 @@ specify extension add <extension-name>
 
 For example, extensions could add Jira integration, post-implementation code review, V-Model test traceability, or project health diagnostics.
 
-See the [Extensions reference](https://github.github.io/spec-kit/reference/extensions.html) for the full command guide. Browse the [community extensions](#-community-extensions) above for what's available.
+See the [Extensions reference](https://github.github.io/spec-kit/reference/extensions.html) for the full command guide. Browse the [community extensions](https://github.github.io/spec-kit/community/extensions.html) for what's available.
 
 ### Presets — Customize Existing Workflows
 
@@ -455,7 +284,7 @@ Our research and experimentation focus on:
 
 - **Linux/macOS/Windows**
 - [Supported](#-supported-ai-coding-agent-integrations) AI coding agent.
-- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pypa.github.io/pipx/) for persistent installation
+- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pipx.pypa.io/) for persistent installation
 - [Python 3.11+](https://www.python.org/downloads/)
 - [Git](https://git-scm.com/downloads)
 
@@ -574,22 +403,24 @@ The produced specification should contain a set of user stories and functional r
 At this stage, your project folder contents should resemble the following:
 
 ```text
-└── .specify
-    ├── memory
-    │  └── constitution.md
-    ├── scripts
-    │  ├── check-prerequisites.sh
-    │  ├── common.sh
-    │  ├── create-new-feature.sh
-    │  ├── setup-plan.sh
-    │  └── update-claude-md.sh
-    ├── specs
-    │  └── 001-create-taskify
-    │      └── spec.md
-    └── templates
-        ├── plan-template.md
-        ├── spec-template.md
-        └── tasks-template.md
+.
+├── .specify
+│   ├── memory
+│   │   └── constitution.md
+│   ├── scripts
+│   │   └── bash
+│   │       ├── check-prerequisites.sh
+│   │       ├── common.sh
+│   │       ├── create-new-feature.sh
+│   │       ├── setup-plan.sh
+│   │       └── setup-tasks.sh
+│   └── templates
+│       ├── plan-template.md
+│       ├── spec-template.md
+│       └── tasks-template.md
+└── specs
+    └── 001-create-taskify
+        └── spec.md
 ```
 
 ### **STEP 3:** Functional specification clarification (required before planning)
@@ -636,29 +467,31 @@ The output of this step will include a number of implementation detail documents
 ```text
 .
 ├── CLAUDE.md
-├── memory
-│  └── constitution.md
-├── scripts
-│  ├── check-prerequisites.sh
-│  ├── common.sh
-│  ├── create-new-feature.sh
-│  ├── setup-plan.sh
-│  └── update-claude-md.sh
-├── specs
-│  └── 001-create-taskify
-│      ├── contracts
-│      │  ├── api-spec.json
-│      │  └── signalr-spec.md
-│      ├── data-model.md
-│      ├── plan.md
-│      ├── quickstart.md
-│      ├── research.md
-│      └── spec.md
-└── templates
-    ├── CLAUDE-template.md
-    ├── plan-template.md
-    ├── spec-template.md
-    └── tasks-template.md
+├── .specify
+│   ├── memory
+│   │   └── constitution.md
+│   ├── scripts
+│   │   └── bash
+│   │       ├── check-prerequisites.sh
+│   │       ├── common.sh
+│   │       ├── create-new-feature.sh
+│   │       ├── setup-plan.sh
+│   │       └── setup-tasks.sh
+│   └── templates
+│       ├── CLAUDE-template.md
+│       ├── plan-template.md
+│       ├── spec-template.md
+│       └── tasks-template.md
+└── specs
+    └── 001-create-taskify
+        ├── contracts
+        │   ├── api-spec.json
+        │   └── signalr-spec.md
+        ├── data-model.md
+        ├── plan.md
+        ├── quickstart.md
+        ├── research.md
+        └── spec.md
 ```
 
 Check the `research.md` document to ensure that the right tech stack is used, based on your instructions. You can ask Claude Code to refine it if any of the components stand out, or even have it check the locally-installed version of the platform/framework you want to use (e.g., .NET).
@@ -705,7 +538,7 @@ This helps refine the implementation plan and helps you avoid potential blind sp
 You can also ask Claude Code (if you have the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli) installed) to go ahead and create a pull request from your current branch to `main` with a detailed description, to make sure that the effort is properly tracked.
 
 > [!NOTE]
-> Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](base/memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan.
+> Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the constitution in `.specify/memory/constitution.md` as the foundational piece that it must adhere to when establishing the plan.
 
 ### **STEP 6:** Generate task breakdown with /speckit.tasks
 
@@ -751,25 +584,6 @@ Once the implementation is complete, test the application and resolve any runtim
 
 ---
 
-## 🔍 Troubleshooting
-
-### Git Credential Manager on Linux
-
-If you're having issues with Git authentication on Linux, you can install Git Credential Manager:
-
-```bash
-#!/usr/bin/env bash
-set -e
-echo "Downloading Git Credential Manager v2.6.1..."
-wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
-echo "Installing Git Credential Manager..."
-sudo dpkg -i gcm-linux_amd64.2.6.1.deb
-echo "Configuring Git to use GCM..."
-git config --global credential.helper manager
-echo "Cleaning up..."
-rm gcm-linux_amd64.2.6.1.deb
-```
-
 ## 💬 Support
 
 For support, please open a [GitHub issue](https://github.com/github/spec-kit/issues/new). We welcome bug reports, feature requests, and questions about using Spec-Driven Development.

docs/community/extensions.md

@@ -0,0 +1,134 @@
+# Community Extensions
+
+> [!NOTE]
+> 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/).**
+
+The following community-contributed extensions are available in [`catalog.community.json`](https://github.com/github/spec-kit/blob/main/extensions/catalog.community.json):
+
+**Categories:**
+
+- `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:**
+
+- `Read-only` — produces reports without modifying files
+- `Read+Write` — modifies files, creates artifacts, or updates specs
+
+| Extension | Purpose | Category | Effect | URL |
+|-----------|---------|----------|--------|-----|
+| 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) |
+| Agent Governance | Generate agent-platform repository governance files from Spec Kit metadata | `process` | Read+Write | [spec-kit-agent-governance](https://github.com/bigsmartben/spec-kit-agent-governance) |
+| 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 | Framework-agnostic architecture review extension for validating implementation against governance and architecture constitutions, detecting architectural drift, and generating non-blocking refactor tasks | `process` | Read+Write | [spec-kit-architecture-guard](https://github.com/DyanGalih/spec-kit-architecture-guard) |
+| Architecture Workflow | Generate or reverse project-level 4+1 architecture view artifacts and synthesis | `docs` | Read+Write | [spec-kit-arch](https://github.com/bigsmartben/spec-kit-arch) |
+| 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) |
+| CI Guard | Spec compliance gates for CI/CD — verify specs exist, check drift, and block merges on gaps | `process` | Read-only | [spec-kit-ci-guard](https://github.com/Quratulain-bilal/spec-kit-ci-guard) |
+| Checkpoint Extension | Commit the changes made during the middle of the implementation, so you don't end up with just one very large commit at the end | `code` | Read+Write | [spec-kit-checkpoint](https://github.com/aaronrsun/spec-kit-checkpoint) |
+| 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) |
+| FixIt Extension | Spec-aware bug fixing — maps bugs to spec artifacts, proposes a plan, applies minimal changes | `code` | Read+Write | [spec-kit-fixit](https://github.com/speckit-community/spec-kit-fixit) |
+| 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) |
+| Interactive HTML Preview | Generate self-contained interactive HTML prototypes from Spec Kit artifacts | `docs` | Read+Write | [spec-kit-preview](https://github.com/bigsmartben/spec-kit-preview) |
+| 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) |
+| Linear Integration | Mirror spec-kit feature directories into Linear (filesystem → Linear, reconcile-based, unidirectional). | `integration` | Read+Write | [spec-kit-linear](https://github.com/ashbrener/spec-kit-linear) |
+| MAQA — Multi-Agent & Quality Assurance | Coordinator → feature → QA agent workflow with parallel worktree-based implementation. Language-agnostic. Auto-detects installed board plugins. Optional CI gate. | `process` | Read+Write | [spec-kit-maqa-ext](https://github.com/GenieRobot/spec-kit-maqa-ext) |
+| MAQA Azure DevOps Integration | Azure DevOps Boards integration for MAQA — syncs User Stories and Task children as features progress | `integration` | Read+Write | [spec-kit-maqa-azure-devops](https://github.com/GenieRobot/spec-kit-maqa-azure-devops) |
+| MAQA CI/CD Gate | Auto-detects GitHub Actions, CircleCI, GitLab CI, and Bitbucket Pipelines. Blocks QA handoff until pipeline is green. | `process` | Read+Write | [spec-kit-maqa-ci](https://github.com/GenieRobot/spec-kit-maqa-ci) |
+| MAQA GitHub Projects Integration | GitHub Projects v2 integration for MAQA — syncs draft issues and Status columns as features progress | `integration` | Read+Write | [spec-kit-maqa-github-projects](https://github.com/GenieRobot/spec-kit-maqa-github-projects) |
+| MAQA Jira Integration | Jira integration for MAQA — syncs Stories and Subtasks as features progress through the board | `integration` | Read+Write | [spec-kit-maqa-jira](https://github.com/GenieRobot/spec-kit-maqa-jira) |
+| 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 | 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) |
+| Multi-Sites Spec Kit | Multi-site aware specify command with per-site spec folders, auto-increment, and Drupal support | `process` | Read+Write | [spec-kit-multi-sites](https://github.com/teeyo/spec-kit-multi-sites) |
+| .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) |
+| Plan Review Gate | Require spec.md and plan.md to be merged via MR/PR before allowing task generation | `process` | Read-only | [spec-kit-plan-review-gate](https://github.com/luno/spec-kit-plan-review-gate) |
+| PR Bridge | Auto-generate pull request descriptions, checklists, and summaries from spec artifacts | `process` | Read-only | [spec-kit-pr-bridge-](https://github.com/Quratulain-bilal/spec-kit-pr-bridge-) |
+| Presetify | Create and validate presets and preset catalogs | `process` | Read+Write | [presetify](https://github.com/mnriem/spec-kit-extensions/tree/main/presetify) |
+| Product Forge | Full product lifecycle from research to release — express/lite/standard/v-model tracks, living spec + traceability, structured journeys → E2E, monorepo, and selectable doc-structure strategies | `process` | Read+Write | [speckit-product-forge](https://github.com/VaiYav/speckit-product-forge) |
+| Product Spec Extension | Generates PRFAQ, Lean PRD, stakeholder summaries, and technical designs from engineering specs | `docs` | Read+Write | [spec-kit-product](https://github.com/d0whc3r/spec-kit-product) |
+| 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) |
+| RAG Azure Builder | Spec Kit extension for onboarding and operating an Azure RAG stack with guided workflows. | `process` | Read+Write | [spec-kit-extension-rag-azure-builder](https://github.com/Sertxito/spec-kit-extension-rag-azure-builder) |
+| 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) |
+| Reqnroll BDD | Adds Reqnroll BDD planning, Gherkin generation, traceability, safe task injection, handoff, and verification to Spec Kit | `process` | Read+Write | [spec-kit-reqnroll-bdd](https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd) |
+| Retro Extension | Sprint retrospective analysis with metrics, spec accuracy assessment, and improvement suggestions | `process` | Read+Write | [spec-kit-retro](https://github.com/arunt14/spec-kit-retro) |
+| Retrospective Extension | Post-implementation retrospective with spec adherence scoring, drift analysis, and human-gated spec updates | `docs` | Read+Write | [spec-kit-retrospective](https://github.com/emi-dm/spec-kit-retrospective) |
+| Review Extension | Post-implementation comprehensive code review with specialized agents for code quality, comments, tests, error handling, type design, and simplification | `code` | Read-only | [spec-kit-review](https://github.com/ismaelJimenez/spec-kit-review) |
+| Ripple | Detect side effects that tests can't catch after implementation — delta-anchored analysis across 9 domain-agnostic categories | `code` | Read+Write | [spec-kit-ripple](https://github.com/chordpli/spec-kit-ripple) |
+| SDD Utilities | Resume interrupted workflows, validate project health, and verify spec-to-task traceability | `process` | Read+Write | [speckit-utils](https://github.com/mvanhorn/speckit-utils) |
+| 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 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 Implementation Bridge | Thin orchestrator between Spec Kit (design) and Superpowers (implementation). Cross-agent. | `process` | Read+Write | [speckit-superpowers-bridge](https://github.com/lihan3238/speckit-superpowers-bridge) |
+| Superspec | 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) |
+| Team Assign | Assign tasks.md items to human engineers, split into subtasks, and generate a per-engineer workboard | `process` | Read+Write | [spec-kit-team-assign](https://github.com/tarunkumarbhati/spec-kit-team-assign) |
+| Time Machine | Retroactively apply the full SDD workflow to existing codebases — analyse, spec, and ship feature-by-feature | `process` | Read+Write | [spec-kit-time-machine](https://github.com/teeyo/spec-kit-time-machine) |
+| 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 Budget | Reduces LLM token consumption in Spec Kit workflows: compact artifacts in-place, scope per-phase reading, suppress prose padding, and report token usage | `process` | Read+Write | [spec-kit-token-budget](https://github.com/tinesoft/spec-kit-token-budget) |
+| 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) |
+| Version Guard | Verify tech stack versions against live npm registries before planning and implementation | `process` | Read-only | [spec-kit-version-guard](https://github.com/KevinBrown5280/spec-kit-version-guard) |
+| What-if Analysis | Preview the downstream impact (complexity, effort, tasks, risks) of requirement changes before committing to them | `visibility` | Read-only | [spec-kit-whatif](https://github.com/DevAbdullah90/spec-kit-whatif) |
+| Wireframe Visual Feedback Loop | SVG wireframe generation, review, and sign-off for spec-driven development. Approved wireframes become spec constraints honored by /speckit.plan, /speckit.tasks, and /speckit.implement | `visibility` | Read+Write | [spec-kit-extension-wireframe](https://github.com/TortoiseWolfe/spec-kit-extension-wireframe) |
+| Work IQ | Integrate Microsoft 365 organizational knowledge into spec-driven development workflows | `integration` | Read-only | [spec-kit-workiq](https://github.com/sakitA/spec-kit-workiq) |
+| Worktree Isolation | Spawn isolated git worktrees for parallel feature development without checkout switching | `process` | Read+Write | [spec-kit-worktree](https://github.com/Quratulain-bilal/spec-kit-worktree) |
+| Worktrees | Default-on worktree isolation for parallel agents — sibling or nested layout | `process` | Read+Write | [spec-kit-worktree-parallel](https://github.com/dango85/spec-kit-worktree-parallel) |
+
+To submit your own extension, see the [Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md).

docs/community/overview.md

@@ -0,0 +1,27 @@
+# Community
+
+The Spec Kit community builds extensions, presets, walkthroughs, and companion projects that expand what you can do with Spec-Driven Development. All community contributions are independently created and maintained by their respective authors.
+
+## Extensions
+
+Extensions add new capabilities to Spec Kit — domain-specific commands, external tool integrations, quality gates, and more. Over 90 community extensions are available from 50+ authors, covering everything from accessibility governance to multi-agent orchestration.
+
+[Browse community extensions →](extensions.md)
+
+## Presets
+
+Presets customize how Spec Kit behaves — overriding templates, commands, and terminology without changing any tooling. Community presets range from language localizations to entirely different development methodologies.
+
+[Browse community presets →](presets.md)
+
+## Walkthroughs
+
+Step-by-step guides that show Spec-Driven Development in action across different scenarios, languages, and frameworks.
+
+[Browse community walkthroughs →](walkthroughs.md)
+
+## Friends
+
+Community projects that extend, visualize, or build on Spec Kit — including VS Code extensions, Claude Code plugins, and more.
+
+[Browse friend projects →](friends.md)

docs/community/presets.md

@@ -8,23 +8,25 @@ The following community-contributed presets customize how Spec Kit behaves — o
 | 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) |
+| Agent Parity Governance | Keeps shared AI-agent instructions aligned and adds agent-neutral Spec Kit model-routing guidance across project-defined agent guidance surfaces | 9 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) |
+| 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 principles. Supports interactive elements like brainstorming, interview, roleplay and extras like statistics, cover builder and bio command. Export with templates for KDP, D2D etc. | 25 templates, 33 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) |
+| Security Governance | Adds secure development governance: memory-safe-language preference, language-specific secure-coding profiles, NIST SSDF, CWE Top 25, OWASP ASVS, SBOM/AI-SBOM, VEX/SLSA, OpenSSF Scorecard, G7/BSI AI-SBOM target evidence, 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) |
+| Workflow Preset | Behavior-first specification, design artifacts, and agent-native handoff orchestration — adds requirement-phase behavior drafts, formal BDD/UIF/behavior contracts, optional design artifacts, and scoped implementation handoffs with Core Agent, Vertical Planner Agent, and Worker Agent modes | 22 templates, 8 commands | — | [spec-kit-workflow-preset](https://github.com/bigsmartben/spec-kit-workflow-preset) |
 
 To build and publish your own preset, see the [Presets Publishing Guide](https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md).

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,154 @@
-# 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">105 community extensions</span> (60+ authors), <span class="pillar-stat">22 presets</span>, and growing. Tune the core process with presets, extend it with extensions, orchestrate it with workflows, or replace it entirely. Build and publish your own.
 
-Please see our [Contributing Guide](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md) for information on how to contribute to this project.
+Including entirely different SDD processes:
 
-## Support
+- **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
 
-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">106K+</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">105</span>
+    <span class="stat-label">Extensions</span>
+  </div>
+  <div class="stat-item">
+    <span class="stat-number">22</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/overview.md" class="nav-card">
+    <strong>Community</strong>
+    <span>Extensions, 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>
+
+<p class="text-end small text-body-secondary">Last updated: May 27, 2026</p>

docs/install/air-gapped.md

@@ -0,0 +1,59 @@
+# Enterprise / Air-Gapped Installation
+
+If your environment blocks access to PyPI or GitHub, you can create a portable wheel bundle on a connected machine and transfer it to the air-gapped target.
+
+## Step 1: Build the wheel on a connected machine
+
+> **Important:** `pip download` resolves platform-specific wheels (e.g., PyYAML includes native extensions). You must run this step on a machine with the **same OS and Python version** as the air-gapped target. If you need to support multiple platforms, repeat this step on each target OS (Linux, macOS, Windows) and Python version.
+
+```bash
+# Clone the repository
+git clone https://github.com/github/spec-kit.git
+cd spec-kit
+
+# Build the wheel
+pip install build
+python -m build --wheel --outdir dist/
+
+# Download the wheel and all its runtime dependencies
+pip download -d dist/ dist/specify_cli-*.whl
+```
+
+## Step 2: Transfer the `dist/` directory
+
+Copy the entire `dist/` directory (which contains the `specify-cli` wheel and all dependency wheels) to the target machine via USB, network share, or other approved transfer method.
+
+## Step 3: Install on the air-gapped machine
+
+```bash
+pip install --no-index --find-links=./dist specify-cli
+```
+
+## Step 4: Initialize a project
+
+No network access is required — bundled assets are used by default:
+
+```bash
+specify init my-project --integration copilot
+```
+
+> **Note:** Python 3.11+ is required.
+
+> **Windows note:** Offline scaffolding requires PowerShell 7+ (`pwsh`), not Windows PowerShell 5.x (`powershell.exe`). Install from https://aka.ms/powershell.
+
+## Git Credential Manager on Linux
+
+If you're having issues with Git authentication on Linux, you can install Git Credential Manager:
+
+```bash
+#!/usr/bin/env bash
+set -e
+echo "Downloading Git Credential Manager v2.6.1..."
+wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
+echo "Installing Git Credential Manager..."
+sudo dpkg -i gcm-linux_amd64.2.6.1.deb
+echo "Configuring Git to use GCM..."
+git config --global credential.helper manager
+echo "Cleaning up..."
+rm gcm-linux_amd64.2.6.1.deb
+```

docs/install/one-time.md

@@ -0,0 +1,32 @@
+# One-time Usage (uvx)
+
+If you want to try Spec Kit without installing it permanently, use `uvx` to run it directly. This downloads the tool into a temporary environment that is discarded after the command finishes.
+
+> [!NOTE]
+> The commands below require **[uv](https://docs.astral.sh/uv/)**. If you see `command not found: uvx`, [install uv first](uv.md).
+
+## Run Specify CLI
+
+```bash
+# Create a new project (latest from main)
+uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
+
+# Or target a specific release (replace vX.Y.Z with a tag from Releases)
+uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>
+
+# Initialize in the current directory
+uvx --from git+https://github.com/github/spec-kit.git specify init . --integration copilot
+
+# Or use the --here flag
+uvx --from git+https://github.com/github/spec-kit.git specify init --here --integration copilot
+```
+
+## When to use persistent installation instead
+
+If you plan to use Spec Kit regularly, a persistent installation is recommended:
+
+- Tool stays installed and available in PATH
+- No re-download on every invocation
+- Better tool management with `uv tool list`, `uv tool upgrade`, `uv tool uninstall`
+
+See the main [Installation Guide](../installation.md) for persistent installation instructions.

docs/install/pipx.md

@@ -0,0 +1,37 @@
+# Installing with pipx
+
+[pipx](https://pipx.pypa.io/) is a tool for installing Python CLI applications in isolated environments. It does not require [uv](https://docs.astral.sh/uv/).
+
+## Install Specify CLI
+
+Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):
+
+```bash
+# Install a specific stable release (recommended — replace vX.Y.Z with the latest tag)
+pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z
+
+# Or install latest from main (may include unreleased changes)
+pipx install git+https://github.com/github/spec-kit.git
+```
+
+## Verify
+
+```bash
+specify version
+```
+
+## Upgrade
+
+```bash
+pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z
+```
+
+## Uninstall
+
+```bash
+pipx uninstall specify-cli
+```
+
+## Next steps
+
+Head to the [Quick Start](../quickstart.md) to initialize your first project.

docs/installation.md

@@ -4,44 +4,41 @@
 
 - **Linux/macOS** (or Windows; PowerShell scripts now supported without WSL)
 - AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [Codebuddy CLI](https://www.codebuddy.ai/cli), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [Pi Coding Agent](https://pi.dev)
-- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pypa.github.io/pipx/) for persistent installation
+- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pipx.pypa.io/) for persistent installation
 - [Python 3.11+](https://www.python.org/downloads/)
 - [Git](https://git-scm.com/downloads)
 
 ## Installation
 
-> **Important:** The only official, maintained packages for Spec Kit come from the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository. Any packages with the same name available on PyPI (e.g. `specify-cli` on pypi.org) are **not** affiliated with this project and are not maintained by the Spec Kit maintainers. For normal installs, use the GitHub-based commands shown below. For offline or air-gapped environments, locally built wheels created from this repository are also valid.
+> [!IMPORTANT]
+> The only official, maintained packages for Spec Kit come from the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository. Any packages with the same name available on PyPI (e.g. `specify-cli` on pypi.org) are **not** affiliated with this project and are not maintained by the Spec Kit maintainers. For normal installs, use the GitHub-based commands shown below. For offline or air-gapped environments, locally built wheels created from this repository are also valid.
 
-### Initialize a New Project
+### Persistent Installation (Recommended)
 
-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):
+Install once and use everywhere. Replace `vX.Y.Z` with a tag from [Releases](https://github.com/github/spec-kit/releases):
 
 > [!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.
+> The command below requires **[uv](https://docs.astral.sh/uv/)**. If you see `command not found: uv`, [install uv first](./install/uv.md).
 
 ```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>
-
-# Or install latest from main (may include unreleased changes)
-uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
 ```
 
-> [!NOTE]
-> For a persistent installation, `pipx` works equally well:
-> ```bash
-> pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z
-> ```
-> The project uses a standard `hatchling` build backend and has no uv-specific dependencies.
-
-Or initialize in the current directory:
+Then initialize a project:
 
 ```bash
-uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init .
-# or use the --here flag
-uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here
+specify init <PROJECT_NAME> --integration copilot
 ```
 
+### One-time Usage
+
+Run directly without installing — see the [One-time usage (uvx)](install/one-time.md) guide.
+
+### Alternative Package Managers
+
+- **pipx** — see the [pipx installation guide](install/pipx.md)
+- **Enterprise / Air-Gapped** — see the [air-gapped installation guide](install/air-gapped.md)
+
 ### 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`.
@@ -49,11 +46,11 @@ Interactive terminals prompt you to choose a coding agent integration during ini
 You can proactively specify your coding agent integration during initialization:
 
 ```bash
-uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --integration claude
-uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --integration gemini
-uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --integration copilot
-uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --integration codebuddy
-uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --integration pi
+specify init <project_name> --integration claude
+specify init <project_name> --integration gemini
+specify init <project_name> --integration copilot
+specify init <project_name> --integration codebuddy
+specify init <project_name> --integration pi
 ```
 
 ### Specify Script Type (Shell vs PowerShell)
@@ -69,8 +66,8 @@ Auto behavior:
 Force a specific script type:
 
 ```bash
-uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --script sh
-uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --script ps
+specify init <project_name> --script sh
+specify init <project_name> --script ps
 ```
 
 ### Ignore Agent Tools Check
@@ -78,7 +75,7 @@ uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <proje
 If you prefer to get the templates without checking for the right tools:
 
 ```bash
-uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --integration claude --ignore-agent-tools
+specify init <project_name> --integration claude --ignore-agent-tools
 ```
 
 ## Verification
@@ -91,73 +88,25 @@ specify version
 
 This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name.
 
+**Stay current:** Run `specify self check` periodically to learn whether a newer release is available — it is read-only and never modifies your installation. When you are ready to upgrade, follow the [Upgrade Guide](./upgrade.md).
+
 After initialization, you should see the following commands available in your coding agent:
 
 - `/speckit.specify` - Create specifications
 - `/speckit.plan` - Generate implementation plans  
 - `/speckit.tasks` - Break down into actionable tasks
 
-The `.specify/scripts` directory will contain both `.sh` and `.ps1` scripts.
+Scripts are installed into a variant subdirectory matching the chosen script type:
+
+- `.specify/scripts/bash/` — contains `.sh` scripts (default on Linux/macOS)
+- `.specify/scripts/powershell/` — contains `.ps1` scripts (default on Windows)
 
 ## Troubleshooting
 
 ### Enterprise / Air-Gapped Installation
 
-If your environment blocks access to PyPI (you see 403 errors when running `uv tool install` or `pip install`), you can create a portable wheel bundle on a connected machine and transfer it to the air-gapped target.
-
-**Step 1: Build the wheel on a connected machine (same OS and Python version as the target)**
-
-```bash
-# Clone the repository
-git clone https://github.com/github/spec-kit.git
-cd spec-kit
-
-# Build the wheel
-pip install build
-python -m build --wheel --outdir dist/
-
-# Download the wheel and all its runtime dependencies
-pip download -d dist/ dist/specify_cli-*.whl
-```
-
-> **Important:** `pip download` resolves platform-specific wheels (e.g., PyYAML includes native extensions). You must run this step on a machine with the **same OS and Python version** as the air-gapped target. If you need to support multiple platforms, repeat this step on each target OS (Linux, macOS, Windows) and Python version.
-
-**Step 2: Transfer the `dist/` directory to the air-gapped machine**
-
-Copy the entire `dist/` directory (which contains the `specify-cli` wheel and all dependency wheels) to the target machine via USB, network share, or other approved transfer method.
-
-**Step 3: Install on the air-gapped machine**
-
-```bash
-pip install --no-index --find-links=./dist specify-cli
-```
-
-**Step 4: Initialize a project (no network required)**
-
-```bash
-# Initialize a project — no GitHub access needed
-specify init my-project --integration claude
-```
-
-Bundled assets are used by default — no network access is required.
-
-> **Note:** Python 3.11+ is required.
-
-> **Windows note:** Offline scaffolding requires PowerShell 7+ (`pwsh`), not Windows PowerShell 5.x (`powershell.exe`). Install from https://aka.ms/powershell.
+If your environment blocks access to PyPI or GitHub, see the [Enterprise / Air-Gapped Installation](install/air-gapped.md) guide for step-by-step instructions on creating portable wheel bundles.
 
 ### Git Credential Manager on Linux
 
-If you're having issues with Git authentication on Linux, you can install Git Credential Manager:
-
-```bash
-#!/usr/bin/env bash
-set -e
-echo "Downloading Git Credential Manager v2.6.1..."
-wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
-echo "Installing Git Credential Manager..."
-sudo dpkg -i gcm-linux_amd64.2.6.1.deb
-echo "Configuring Git to use GCM..."
-git config --global credential.helper manager
-echo "Cleaning up..."
-rm gcm-linux_amd64.2.6.1.deb
-```
+If you're having issues with Git authentication on Linux, see the [Air-Gapped Installation guide](install/air-gapped.md#git-credential-manager-on-linux) for Git Credential Manager setup instructions.

docs/quickstart.md

@@ -5,11 +5,19 @@ This guide will help you get started with Spec-Driven Development using Spec Kit
 > [!NOTE]
 > All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`.
 
-## The 6-Step Process
+## Recommended Workflow
 
 > [!TIP]
 > **Context Awareness**: Spec Kit commands automatically detect the active feature based on your current Git branch (e.g., `001-feature-name`). To switch between different specifications, simply switch Git branches.
 
+After installing Spec Kit and defining your project constitution, quick experiments can use the lean feature path: `/speckit.specify` -> `/speckit.plan` -> `/speckit.tasks` -> `/speckit.implement`. For production features or any work with meaningful ambiguity, treat `/speckit.clarify`, `/speckit.checklist`, and `/speckit.analyze` as regular quality gates:
+
+```text
+/speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.checklist -> /speckit.plan -> /speckit.tasks -> /speckit.analyze -> /speckit.implement
+```
+
+Use `/speckit.clarify` to reduce requirement ambiguity before planning, `/speckit.checklist` to validate requirements quality before planning, and `/speckit.analyze` to check spec/plan/task consistency before implementation starts. You can repeat `/speckit.analyze` after implementation as an extra review, but keep the first analysis before `/speckit.implement` so gaps are caught while the plan and tasks can still be adjusted.
+
 ### Step 1: Install Specify
 
 **In your terminal**, run the `specify` CLI command to initialize your project:
@@ -24,10 +32,13 @@ uvx --from git+https://github.com/github/spec-kit.git specify init .
 
 > [!NOTE]
 > You can also install the CLI persistently with `pipx`:
+>
 > ```bash
 > pipx install git+https://github.com/github/spec-kit.git
 > ```
+>
 > After installing with `pipx`, run `specify` directly instead of `uvx --from ... specify`, for example:
+>
 > ```bash
 > specify init <PROJECT_NAME>
 > specify init .
@@ -56,7 +67,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 /speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.
 ```
 
-### Step 4: Refine the Spec
+### Step 4: Refine and Validate the Spec
 
 **In the chat**, use the `/speckit.clarify` slash command to identify and resolve ambiguities in your specification. You can provide specific focus areas as arguments.
 
@@ -64,6 +75,12 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 /speckit.clarify Focus on security and performance requirements.
 ```
 
+Then validate the requirements with `/speckit.checklist` before creating the technical plan:
+
+```bash
+/speckit.checklist
+```
+
 ### Step 5: Create a Technical Implementation Plan
 
 **In the chat**, use the `/speckit.plan` slash command to provide your tech stack and architecture choices.
@@ -72,7 +89,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 /speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.
 ```
 
-### Step 6: Break Down and Implement
+### Step 6: Break Down, Analyze, and Implement
 
 **In the chat**, use the `/speckit.tasks` slash command to create an actionable task list.
 
@@ -80,13 +97,13 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 /speckit.tasks
 ```
 
-Optionally, validate the plan with `/speckit.analyze`:
+Validate cross-artifact consistency with `/speckit.analyze` before implementation:
 
 ```markdown
 /speckit.analyze
 ```
 
-Then, use the `/speckit.implement` slash command to execute the plan.
+Use the `/speckit.implement` slash command to execute the plan.
 
 ```markdown
 /speckit.implement
@@ -159,7 +176,7 @@ Generate an actionable task list using the `/speckit.tasks` command:
 
 ### Step 7: Validate and Implement
 
-Have your coding agent audit the implementation plan using `/speckit.analyze`:
+Have your coding agent audit the spec, plan, and tasks with `/speckit.analyze` before implementation:
 
 ```bash
 /speckit.analyze
@@ -179,7 +196,7 @@ Finally, implement the solution:
 - **Be explicit** about what you're building and why
 - **Don't focus on tech stack** during specification phase
 - **Iterate and refine** your specifications before implementation
-- **Validate** the plan before coding begins
+- **Validate** requirements and plans before coding begins
 - **Let the coding agent handle** the implementation details
 
 ## Next Steps

docs/reference/core.md

@@ -69,6 +69,8 @@ specify check
 
 Checks that required tools are available on your system: `git` and any CLI-based AI coding agents. IDE-based agents are skipped since they don't require a CLI tool.
 
+This command stays offline. If a command behaves like an older Spec Kit version or an expected CLI feature is missing, run `specify self check` to check whether your local CLI is behind the latest release.
+
 ## Version Information
 
 ```bash
@@ -77,6 +79,16 @@ specify version
 
 Displays the Spec Kit CLI version, Python version, platform, and architecture.
 
+To inspect local CLI capabilities without checking the network:
+
+```bash
+specify version --features
+specify version --features --json
+```
+
+The JSON form is intended for scripts and coding agents that need to choose a
+workflow based on the installed CLI's supported features.
+
 A quick version check is also available via:
 
 ```bash

docs/reference/integrations.md

@@ -10,6 +10,7 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify
 | [Antigravity (agy)](https://antigravity.google/)                                     | `agy`            | Skills-based integration; skills are installed automatically                                                                               |
 | [Auggie CLI](https://docs.augmentcode.com/cli/overview)                              | `auggie`         |                                                                                                                                           |
 | [Claude Code](https://www.anthropic.com/claude-code)                                 | `claude`         | Skills-based integration; installs skills in `.claude/skills`                                                                              |
+| [Cline](https://github.com/cline/cline)                                              | `cline`          | IDE-based agent                                                                                                                           |
 | [CodeBuddy CLI](https://www.codebuddy.ai/cli)                                        | `codebuddy`      |                                                                                                                                           |
 | [Codex CLI](https://github.com/openai/codex)                                         | `codex`          | Skills-based integration; installs skills into `.agents/skills` and invokes them as `$speckit-<command>` |
 | [Cursor](https://cursor.sh/)                                                         | `cursor-agent`   |                                                                                                                                           |
@@ -18,12 +19,13 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli)                            | `gemini`         |                                                                                                                                           |
 | [GitHub Copilot](https://code.visualstudio.com/)                                     | `copilot`        |                                                                                                                                           |
 | [Goose](https://block.github.io/goose/)                                              | `goose`          | Uses YAML recipe format in `.goose/recipes/`                                                                                              |
+| [Hermes](https://github.com/NousResearch/hermes-agent)                               | `hermes`         | Skills-based integration; installs skills globally into `~/.hermes/skills/`                                                                |
 | [IBM Bob](https://www.ibm.com/products/bob)                                          | `bob`            | IDE-based agent                                                                                                                           |
 | [iFlow CLI](https://docs.iflow.cn/en/cli/quickstart)                                 | `iflow`          |                                                                                                                                           |
 | [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`       |                                                                                                                                           |
@@ -31,6 +33,7 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify
 | [Qoder CLI](https://qoder.com/cli)                                                   | `qodercli`       |                                                                                                                                           |
 | [Qwen Code](https://github.com/QwenLM/qwen-code)                                     | `qwen`           |                                                                                                                                           |
 | [Roo Code](https://roocode.com/)                                                     | `roo`            |                                                                                                                                           |
+| [RovoDev](https://www.atlassian.com/software/rovo-dev)                               | `rovodev`        | Generates `.rovodev/skills/`, prompt wrappers, and `prompts.yml`; runtime dispatch uses `acli rovodev`                                   |
 | [SHAI (OVHcloud)](https://github.com/ovh/shai)                                       | `shai`           |                                                                                                                                           |
 | [Tabnine CLI](https://docs.tabnine.com/main/getting-started/tabnine-cli)             | `tabnine`        |                                                                                                                                           |
 | [Trae](https://www.trae.ai/)                                                         | `trae`           | Skills-based integration; skills are installed automatically                                                                               |
@@ -65,6 +68,8 @@ Installing an additional integration does not change the default integration. Us
 
 > **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

docs/reference/workflows.md

@@ -11,6 +11,7 @@ specify workflow run <source>
 | Option              | Description                                              |
 | ------------------- | -------------------------------------------------------- |
 | `-i` / `--input`    | Pass input values as `key=value` (repeatable)            |
+| `--json`            | Emit the run outcome as a single JSON object             |
 
 Runs a workflow from a catalog ID, URL, or local file path. Inputs declared by the workflow can be provided via `--input` or will be prompted interactively.
 
@@ -20,7 +21,25 @@ Example:
 specify workflow run speckit -i spec="Build a kanban board with drag-and-drop task management" -i scope=full
 ```
 
-> **Note:** All workflow commands require a project already initialized with `specify init`.
+With `--json`, a single machine-readable object is printed instead of formatted text (the default output is unchanged when the flag is omitted):
+
+```bash
+specify workflow run my-pipeline.yml --json
+```
+
+```json
+{
+  "run_id": "662bf791",
+  "workflow_id": "build-and-review",
+  "status": "paused",
+  "current_step_id": "review",
+  "current_step_index": 0
+}
+```
+
+`workflow_id` is the `workflow.id` declared inside the YAML, not the file name. The object is printed exactly as shown — pretty-printed with two-space indentation, on plain stdout with no Rich markup — so it always parses. While the workflow runs under `--json`, any progress a step would print (for example a gate prompt, or output from a prompt step's CLI subprocess) is redirected to stderr, so stdout carries only the JSON object. Read the object from stdout; leave stderr attached to the terminal or capture it separately.
+
+> **Note:** Most workflow commands require a project already initialized with `specify init`. The exception is `specify workflow run <local-file.{yml,yaml}>`, which can run outside a project; in that case, run state is stored under the current directory's `.specify/workflows/runs/<run_id>/`.
 
 ## Resume a Workflow
 
@@ -28,14 +47,29 @@ specify workflow run speckit -i spec="Build a kanban board with drag-and-drop ta
 specify workflow resume <run_id>
 ```
 
+| Option              | Description                                              |
+| ------------------- | -------------------------------------------------------- |
+| `-i` / `--input`    | Updated input values as `key=value` (repeatable)         |
+| `--json`            | Emit the resume outcome as a single JSON object          |
+
 Resumes a paused or failed workflow run from the exact step where it stopped. Useful after responding to a gate step or fixing an issue that caused a failure.
 
+Supplied `--input` values are merged over the run's stored inputs and re-validated against the workflow's input types, then the blocked step is re-run with the updated values. This lets a run continue with information that only became available after it paused, or with a corrected value after a failure:
+
+```bash
+specify workflow resume <run_id> --input cmd="exit 0"
+```
+
 ## Workflow Status
 
 ```bash
 specify workflow status [<run_id>]
 ```
 
+| Option              | Description                                              |
+| ------------------- | -------------------------------------------------------- |
+| `--json`            | Emit run status (or the runs list) as a JSON object      |
+
 Shows the status of a specific run, or lists all runs if no ID is given. Run states: `created`, `running`, `completed`, `paused`, `failed`, `aborted`.
 
 ## List Installed Workflows

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

@@ -13,6 +13,12 @@
       href: upgrade.md
     - name: Install uv
       href: install/uv.md
+    - name: Install with pipx
+      href: install/pipx.md
+    - name: One-time Usage (uvx)
+      href: install/one-time.md
+    - name: Enterprise / Air-Gapped
+      href: install/air-gapped.md
 
 # Reference
 - name: Reference
@@ -30,6 +36,12 @@
     - name: Workflows
       href: reference/workflows.md
 
+# Concepts
+- name: Concepts
+  items:
+    - name: What is SDD?
+      href: concepts/sdd.md
+
 # Development workflows
 - name: Development
   items:
@@ -38,7 +50,12 @@
 
 # Community
 - name: Community
+  href: community/overview.md
   items:
+    - name: Overview
+      href: community/overview.md
+    - name: Extensions
+      href: community/extensions.md
     - name: Presets
       href: community/presets.md
     - name: Walkthroughs

docs/upgrade.md

@@ -8,8 +8,10 @@
 
 | What to Upgrade | Command | When to Use |
 |----------------|---------|-------------|
-| **CLI Tool Only** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z` | Get latest CLI features without touching project files |
-| **CLI Tool Only (pipx)** | `pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z` | Reinstall/upgrade a pipx-installed CLI to a specific release |
+| **CLI Tool (recommended)** | `specify self upgrade` | Latest stable release, in place. Auto-detects whether you installed via `uv tool` or `pipx`. |
+| **CLI Tool — pin a version** | `specify self upgrade --tag vX.Y.Z[suffix]` | Upgrade to a specific release tag instead of the latest stable. Suffixes are limited to dev, alpha/beta/rc, and/or build metadata forms. |
+| **CLI Tool — manual fallback** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z` | When `specify self upgrade` isn't available (older installs) or when you want explicit control. |
+| **CLI Tool — manual fallback (pipx)** | `pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z` | Same as above, for pipx installs. |
 | **Project Files** | `specify init --here --force --integration <your-agent>` | Update slash commands, templates, and scripts in your project |
 | **Both** | Run CLI upgrade, then project update | Recommended for major version updates |
 
@@ -19,6 +21,32 @@
 
 The CLI tool (`specify`) is separate from your project files. Upgrade it to get the latest features and bug fixes.
 
+### Recommended: `specify self upgrade`
+
+The CLI ships with two self-management commands that handle the common case automatically:
+
+```bash
+# Check whether a newer release is available (read-only — does not modify anything)
+specify self check
+
+# Preview what would run, without actually upgrading
+specify self upgrade --dry-run
+
+# Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install)
+specify self upgrade
+
+# Or pin a specific release tag (replace vX.Y.Z[suffix] with the tag you want)
+specify self upgrade --tag vX.Y.Z[suffix]
+```
+
+Bare `specify self upgrade` executes immediately, matching the no-prompt behavior of commands like `pip install -U` and `npm update`. The CLI classifies your runtime into one of: `uv tool`, `pipx`, `uvx (ephemeral)`, source checkout, or unsupported. Only `uv tool` and `pipx` are upgraded automatically; for `uv tool` installs, it runs `uv tool install specify-cli --force --from <git ref>` under the hood so pinned release tags work. The other paths print path-specific guidance and exit 0 without touching anything.
+
+Pinned tags must start with `vMAJOR.MINOR.PATCH`. Optional suffixes are limited to dev, alpha/beta/rc, and/or build metadata forms such as `v1.0.0-rc1`, `v0.8.0.dev0`, `v0.8.0+build.42`, or the combination `v1.0.0-rc1+build.42`; branch names, hash refs, `latest`, and bare versions without `v` are rejected.
+
+Set `SPECIFY_UPGRADE_TIMEOUT_SECS` to cap how long the installer subprocess may run (default: no timeout — interrupt with `Ctrl+C` if needed). If that internal timeout fires, `specify self upgrade` exits 124 and reports that it timed out while waiting for the installer subprocess, including the configured timeout and manual retry command. A real installer exit code 124 is propagated with `Upgrade failed. Installer exit code: 124.`, so scripts should treat exit 124 as ambiguous and inspect the message when they need to distinguish the two cases.
+
+If your installed CLI is older than the release that introduced `specify self upgrade`, use the manual equivalents below. These commands are also useful when you want explicit control over the installer command.
+
 ### 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 +63,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:
@@ -46,10 +76,14 @@ pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z
 ### Verify the upgrade
 
 ```bash
+# Confirms the CLI is working and shows installed tools
 specify check
+
+# Confirms the installed version against the latest GitHub release
+specify self check
 ```
 
-This shows installed tools and confirms the CLI is working.
+`specify check` shows the surrounding tool environment; `specify self check` is read-only and tells you whether you're now on the latest release (`Up to date: X.Y.Z`) or if a newer one became available between releases.
 
 ---
 
@@ -178,8 +212,8 @@ Restart your IDE to refresh the command list.
 ### Scenario 1: "I just want new slash commands"
 
 ```bash
-# Upgrade CLI (if using persistent install)
-uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+# Upgrade CLI (auto-detects uv tool vs pipx install)
+specify self upgrade
 
 # Update project files to get new commands
 specify init --here --force --integration copilot
@@ -196,7 +230,7 @@ cp .specify/memory/constitution.md /tmp/constitution-backup.md
 cp -r .specify/templates /tmp/templates-backup
 
 # 2. Upgrade CLI
-uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+specify self upgrade
 
 # 3. Update project
 specify init --here --force --integration copilot
@@ -380,7 +414,19 @@ Only Spec Kit infrastructure files:
 
 ### "CLI upgrade doesn't seem to work"
 
-Verify the installation:
+If a command behaves like an older Spec Kit version, first ask the CLI itself:
+
+```bash
+# Read-only — prints "Up to date: X.Y.Z" or "Update available: X.Y.Z → vY.Z.W"
+specify self check
+
+# Preview the install method, current version, and target tag the upgrade would use
+specify self upgrade --dry-run
+```
+
+`specify check` is an offline environment scan; `specify self check` is the CLI version lookup.
+
+If `self check` shows the wrong version, verify the installation:
 
 ```bash
 # Check installed tools

extensions/README.md

@@ -76,7 +76,7 @@ specify extension add <extension-name> --from https://github.com/org/spec-kit-ex
 
 🔍 **Browse and search community extensions on the [Community Extensions website](https://speckit-community.github.io/extensions/).**
 
-See the [Community Extensions](../README.md#-community-extensions) section in the main README for the full list of available community-contributed extensions.
+See the [Community Extensions](https://github.github.io/spec-kit/community/extensions.html) page for the full list of available community-contributed extensions.
 
 For the raw catalog data, see [`catalog.community.json`](catalog.community.json).
 

extensions/agent-context/README.md

@@ -0,0 +1,57 @@
+# Coding Agent Context Extension
+
+This bundled extension manages the **coding agent context/instruction file** (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`, `GEMINI.md`, …) for the active integration.
+
+It owns the lifecycle of the managed section delimited by the configurable start/end markers (defaults: `<!-- SPECKIT START -->` / `<!-- SPECKIT END -->`).
+
+## Why an extension?
+
+Not every Spec Kit user wants Spec Kit to write into the coding agent's context file. Extracting this behavior into a dedicated extension lets users:
+
+- **Opt out** entirely with `specify extension disable agent-context` — Spec Kit will then never create or modify the agent context file.
+- **Customize the markers** by editing `.specify/extensions/agent-context/agent-context-config.yml` — both the Python layer and the bundled scripts honor the same `context_markers` value.
+- **Refresh on demand** with `/speckit.agent-context.update`, or automatically through the hooks declared in `extension.yml` (`after_specify`, `after_plan`).
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `speckit.agent-context.update` | Refresh the managed section in the agent context file with the current plan path. |
+
+## Configuration
+
+All configuration flows through the extension's own config file at
+`.specify/extensions/agent-context/agent-context-config.yml`:
+
+```yaml
+# Path to the coding agent context file managed by this extension
+context_file: CLAUDE.md
+
+# Delimiters for the managed Spec Kit section
+context_markers:
+  start: "<!-- SPECKIT START -->"
+  end: "<!-- SPECKIT END -->"
+```
+
+- `context_file` — the project-relative path to the coding agent context file, written by `specify init` and `specify integration install`.
+- `context_markers.start` / `.end` — the delimiters around the managed section. Edit these to use custom markers.
+
+## Requirements
+
+The bundled update scripts require **Python 3** with **PyYAML** for YAML/upsert processing (PowerShell can also use `ConvertFrom-Yaml` when available).
+
+PyYAML ships with the `specify` CLI and is normally available via the same `python3` interpreter. If a hook reports *"PyYAML is required … not available in the current Python environment"*, it means the system `python3` differs from the one used to install Spec Kit. To resolve, run:
+
+```bash
+pip install pyyaml
+# or target the specific interpreter Spec Kit uses:
+/path/to/speckit-python -m pip install pyyaml
+```
+
+## Disable
+
+```bash
+specify extension disable agent-context
+```
+
+When disabled, Spec Kit skips context file creation, updates, and removal (the gates are inside `upsert_context_section()` and `remove_context_section()`).

extensions/agent-context/agent-context-config.yml

@@ -0,0 +1,15 @@
+# Coding Agent Context Extension Configuration
+# These values are populated automatically by `specify init` and
+# `specify integration use` / `specify integration install`.
+
+# Path (relative to the project root) to the coding agent context file
+# managed by this extension (e.g. CLAUDE.md, AGENTS.md,
+# .github/copilot-instructions.md). Set automatically from the active
+# integration and regenerated during `specify init` or integration switches.
+context_file: ""
+
+# Delimiters for the managed Spec Kit section.
+# Edit these to use custom markers.
+context_markers:
+  start: "<!-- SPECKIT START -->"
+  end: "<!-- SPECKIT END -->"

extensions/agent-context/commands/speckit.agent-context.update.md

@@ -0,0 +1,26 @@
+---
+description: "Refresh the managed Spec Kit section in the coding agent context file"
+---
+
+# Update Coding Agent Context
+
+Refresh the managed Spec Kit section inside the active coding agent's context/instruction file (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`).
+
+## Behavior
+
+The script reads the agent-context extension config at
+`.specify/extensions/agent-context/agent-context-config.yml` to discover:
+
+- `context_file` — the path of the coding agent context file to manage.
+- `context_markers.start` / `.end` — the delimiters surrounding the managed section. Defaults to `<!-- SPECKIT START -->` and `<!-- SPECKIT END -->` when the field is missing.
+
+It then creates, replaces, or appends the managed block so that the section points at the most recent plan path when one can be discovered (`specs/<feature>/plan.md`).
+
+If `context_file` is empty or the file cannot be located, the command reports nothing to do and exits successfully.
+
+## Execution
+
+- **Bash**: `.specify/extensions/agent-context/scripts/bash/update-agent-context.sh [plan_path]`
+- **PowerShell**: `.specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1 [plan_path]`
+
+When `plan_path` is omitted, the script auto-detects the most recently modified `specs/*/plan.md`.

extensions/agent-context/extension.yml

@@ -0,0 +1,34 @@
+schema_version: "1.0"
+
+extension:
+  id: agent-context
+  name: "Coding Agent Context"
+  version: "1.0.0"
+  description: "Manages coding agent context/instruction files (e.g., CLAUDE.md, copilot-instructions.md) with project-specific plan references and configurable markers"
+  author: spec-kit-core
+  repository: https://github.com/github/spec-kit
+  license: MIT
+
+requires:
+  speckit_version: ">=0.2.0"
+
+provides:
+  commands:
+    - name: speckit.agent-context.update
+      file: commands/speckit.agent-context.update.md
+      description: "Refresh the managed Spec Kit section in the coding agent context file"
+
+hooks:
+  after_specify:
+    command: speckit.agent-context.update
+    optional: true
+    description: "Refresh agent context after specification"
+  after_plan:
+    command: speckit.agent-context.update
+    optional: true
+    description: "Refresh agent context after planning"
+
+tags:
+  - "agent"
+  - "context"
+  - "core"

extensions/agent-context/scripts/bash/update-agent-context.sh

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+# update-agent-context.sh
+#
+# Refresh the managed Spec Kit section in the coding agent's context file
+# (e.g. CLAUDE.md, .github/copilot-instructions.md, AGENTS.md).
+#
+# Reads `context_file` and `context_markers.{start,end}` from the
+# agent-context extension config:
+#   .specify/extensions/agent-context/agent-context-config.yml
+#
+# Usage: update-agent-context.sh [plan_path]
+#
+# When `plan_path` is omitted, the script picks the most recently modified
+# `specs/*/plan.md` if any exist, otherwise emits the section without a
+# concrete plan path.
+
+set -euo pipefail
+
+PROJECT_ROOT="$(pwd)"
+EXT_CONFIG="$PROJECT_ROOT/.specify/extensions/agent-context/agent-context-config.yml"
+DEFAULT_START="<!-- SPECKIT START -->"
+DEFAULT_END="<!-- SPECKIT END -->"
+
+if [[ ! -f "$EXT_CONFIG" ]]; then
+  echo "agent-context: $EXT_CONFIG not found; nothing to do." >&2
+  exit 0
+fi
+
+# Locate a suitable Python interpreter (python3, then python).
+_python=""
+if command -v python3 >/dev/null 2>&1; then
+  _python="python3"
+elif command -v python >/dev/null 2>&1 && python --version 2>&1 | grep -q "^Python 3"; then
+  _python="python"
+fi
+
+if [[ -z "$_python" ]]; then
+  echo "agent-context: Python 3 not found on PATH; skipping update." >&2
+  exit 0
+fi
+
+# Parse extension config once; emit three newline-separated fields:
+# context_file, context_markers.start, context_markers.end
+if ! _raw_opts="$("$_python" - "$EXT_CONFIG" <<'PY'
+import sys
+try:
+    import yaml
+except ImportError:
+    print(
+        "agent-context: PyYAML is required to parse extension config but is not available "
+        "in the current Python environment.\n"
+        "  To resolve: pip install pyyaml (or install it into the environment used by python3).\n"
+        "  Context file will not be updated until PyYAML is importable.",
+        file=sys.stderr,
+    )
+    sys.exit(2)
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = yaml.safe_load(fh)
+except Exception as exc:
+    print(
+        f"agent-context: unable to parse {sys.argv[1]} ({exc}); cannot update context.",
+        file=sys.stderr,
+    )
+    sys.exit(2)
+if not isinstance(data, dict):
+    data = {}
+def get_str(obj, *keys):
+    node = obj
+    for k in keys:
+        if isinstance(node, dict) and k in node:
+            node = node[k]
+        else:
+            return ""
+    return node if isinstance(node, str) else ""
+print(get_str(data, "context_file"))
+print(get_str(data, "context_markers", "start"))
+print(get_str(data, "context_markers", "end"))
+PY
+)"; then
+  echo "agent-context: skipping update (see above for details)." >&2
+  exit 0
+fi
+
+_opts_lines=()
+while IFS= read -r _line || [[ -n "$_line" ]]; do
+  _opts_lines+=("$_line")
+done < <(printf '%s\n' "$_raw_opts")
+if (( ${#_opts_lines[@]} < 3 )); then
+  echo "agent-context: malformed config parser output; expected 3 lines (context_file, marker_start, marker_end), got ${#_opts_lines[@]}; skipping update." >&2
+  exit 0
+fi
+CONTEXT_FILE="${_opts_lines[0]}"
+MARKER_START="${_opts_lines[1]}"
+MARKER_END="${_opts_lines[2]}"
+
+if [[ -z "$CONTEXT_FILE" ]]; then
+  echo "agent-context: context_file not set in extension config; nothing to do." >&2
+  exit 0
+fi
+
+# Reject absolute paths, backslash separators, and '..' path segments in context_file
+if [[ "$CONTEXT_FILE" == /* ]] || [[ "$CONTEXT_FILE" =~ ^[A-Za-z]: ]]; then
+  echo "agent-context: context_file must be a project-relative path; got '$CONTEXT_FILE'." >&2
+  exit 1
+fi
+if [[ "$CONTEXT_FILE" == *\\* ]]; then
+  echo "agent-context: context_file must not contain backslash separators; got '$CONTEXT_FILE'." >&2
+  exit 1
+fi
+IFS='/' read -ra _cf_parts <<< "$CONTEXT_FILE"
+for _seg in "${_cf_parts[@]}"; do
+  if [[ "$_seg" == ".." ]]; then
+    echo "agent-context: context_file must not contain '..' path segments; got '$CONTEXT_FILE'." >&2
+    exit 1
+  fi
+done
+unset _cf_parts _seg
+
+[[ -z "$MARKER_START" ]] && MARKER_START="$DEFAULT_START"
+[[ -z "$MARKER_END"   ]] && MARKER_END="$DEFAULT_END"
+
+PLAN_PATH="${1:-}"
+if [[ -z "$PLAN_PATH" ]]; then
+  # Pick the most recently modified plan.md one level deep (specs/<feature>/plan.md).
+  # Use find + sort by modification time to avoid ls/head fragility with
+  # spaces in paths or SIGPIPE from pipefail.
+  _plan_abs="$("$_python" - "$PROJECT_ROOT" <<'PY'
+import sys, os
+from pathlib import Path
+specs = Path(sys.argv[1]) / "specs"
+plans = sorted(
+    specs.glob("*/plan.md"),
+    key=lambda p: p.stat().st_mtime,
+    reverse=True,
+)
+print(plans[0] if plans else "")
+PY
+)"
+  if [[ -n "$_plan_abs" ]]; then
+    PLAN_PATH="${_plan_abs#"$PROJECT_ROOT/"}"
+  fi
+fi
+
+CTX_PATH="$PROJECT_ROOT/$CONTEXT_FILE"
+mkdir -p "$(dirname "$CTX_PATH")"
+
+# Build the managed section
+TMP_SECTION="$(mktemp)"
+trap 'rm -f "$TMP_SECTION"' EXIT
+{
+  echo "$MARKER_START"
+  echo "For additional context about technologies to be used, project structure,"
+  echo "shell commands, and other important information, read the current plan"
+  if [[ -n "$PLAN_PATH" ]]; then
+    echo "at $PLAN_PATH"
+  fi
+  echo "$MARKER_END"
+} > "$TMP_SECTION"
+
+"$_python" - "$CTX_PATH" "$MARKER_START" "$MARKER_END" "$TMP_SECTION" <<'PY'
+import sys, os
+ctx_path, start, end, section_path = sys.argv[1:5]
+with open(section_path, "r", encoding="utf-8") as fh:
+    section = fh.read().rstrip("\n") + "\n"
+
+if os.path.exists(ctx_path):
+    with open(ctx_path, "r", encoding="utf-8-sig") as fh:
+        content = fh.read()
+    s = content.find(start)
+    e = content.find(end, s if s != -1 else 0)
+    if s != -1 and e != -1 and e > s:
+        end_of_marker = e + len(end)
+        if end_of_marker < len(content) and content[end_of_marker] == "\r":
+            end_of_marker += 1
+        if end_of_marker < len(content) and content[end_of_marker] == "\n":
+            end_of_marker += 1
+        new_content = content[:s] + section + content[end_of_marker:]
+    elif s != -1:
+        new_content = content[:s] + section
+    elif e != -1:
+        end_of_marker = e + len(end)
+        if end_of_marker < len(content) and content[end_of_marker] == "\r":
+            end_of_marker += 1
+        if end_of_marker < len(content) and content[end_of_marker] == "\n":
+            end_of_marker += 1
+        new_content = section + content[end_of_marker:]
+    else:
+        if content and not content.endswith("\n"):
+            content += "\n"
+        new_content = (content + "\n" + section) if content else section
+else:
+    new_content = section
+
+new_content = new_content.replace("\r\n", "\n").replace("\r", "\n")
+with open(ctx_path, "wb") as fh:
+    fh.write(new_content.encode("utf-8"))
+PY
+
+echo "agent-context: updated $CONTEXT_FILE"

extensions/agent-context/scripts/powershell/update-agent-context.ps1

@@ -0,0 +1,237 @@
+#!/usr/bin/env pwsh
+# update-agent-context.ps1
+#
+# Refresh the managed Spec Kit section in the coding agent's context file
+# (e.g. CLAUDE.md, .github/copilot-instructions.md, AGENTS.md).
+#
+# Reads `context_file` and `context_markers.{start,end}` from the
+# agent-context extension config:
+#   .specify/extensions/agent-context/agent-context-config.yml
+#
+# Usage: update-agent-context.ps1 [plan_path]
+
+[CmdletBinding()]
+param(
+    [Parameter(Position = 0)]
+    [string]$PlanPath
+)
+
+function Get-ConfigValue {
+    param(
+        [AllowNull()][object]$Object,
+        [Parameter(Mandatory = $true)][string]$Key
+    )
+
+    if ($null -eq $Object) {
+        return $null
+    }
+    if ($Object -is [System.Collections.IDictionary]) {
+        return $Object[$Key]
+    }
+    $prop = $Object.PSObject.Properties[$Key]
+    if ($prop) {
+        return $prop.Value
+    }
+    return $null
+}
+
+function Test-ConfigObject {
+    param(
+        [AllowNull()][object]$Object
+    )
+
+    if ($null -eq $Object) {
+        return $false
+    }
+    if ($Object -is [System.Collections.IDictionary]) {
+        return $true
+    }
+    if ($Object -is [System.Management.Automation.PSCustomObject]) {
+        return $true
+    }
+    return $false
+}
+
+$ErrorActionPreference = 'Stop'
+$DefaultStart = '<!-- SPECKIT START -->'
+$DefaultEnd   = '<!-- SPECKIT END -->'
+$ProjectRoot  = (Get-Location).Path
+$ExtConfig    = Join-Path $ProjectRoot '.specify/extensions/agent-context/agent-context-config.yml'
+
+if (-not (Test-Path -LiteralPath $ExtConfig)) {
+    Write-Warning "agent-context: $ExtConfig not found; nothing to do."
+    exit 0
+}
+
+$Options = $null
+if (Get-Command ConvertFrom-Yaml -ErrorAction SilentlyContinue) {
+    try {
+        $Options = Get-Content -LiteralPath $ExtConfig -Raw | ConvertFrom-Yaml -ErrorAction Stop
+    } catch {
+        # fall through to Python fallback
+    }
+}
+
+if ($null -eq $Options) {
+    # ConvertFrom-Yaml unavailable or failed; fall back to Python+PyYAML.
+    $pythonCmd = $null
+    foreach ($candidate in @('python3', 'python')) {
+        if (Get-Command $candidate -ErrorAction SilentlyContinue) {
+            # Verify it is Python 3
+            $verOut = & $candidate --version 2>&1
+            if ($verOut -match 'Python 3') {
+                $pythonCmd = $candidate
+                break
+            }
+        }
+    }
+
+    if ($pythonCmd) {
+        try {
+            $jsonOut = & $pythonCmd -c @'
+import json
+import sys
+try:
+    import yaml
+except ImportError:
+    print(
+        "agent-context: PyYAML is required to parse extension config; cannot update context.",
+        file=sys.stderr,
+    )
+    sys.exit(2)
+
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = yaml.safe_load(fh)
+except Exception as exc:
+    print(
+        f"agent-context: unable to parse {sys.argv[1]} ({exc}); cannot update context.",
+        file=sys.stderr,
+    )
+    sys.exit(2)
+
+if not isinstance(data, dict):
+    data = {}
+
+print(json.dumps(data))
+'@ $ExtConfig
+            if ($LASTEXITCODE -eq 0 -and $jsonOut) {
+                $Options = $jsonOut | ConvertFrom-Json -ErrorAction Stop
+            }
+        } catch {
+            $Options = $null
+        }
+    }
+
+    if (-not $Options) {
+        Write-Warning "agent-context: unable to parse $ExtConfig; skipping update."
+        exit 0
+    }
+}
+
+if (-not (Test-ConfigObject -Object $Options)) {
+    Write-Warning "agent-context: $ExtConfig must contain a YAML mapping; skipping update."
+    exit 0
+}
+
+$ContextFile = Get-ConfigValue -Object $Options -Key 'context_file'
+if (-not $ContextFile) {
+    Write-Warning 'agent-context: context_file not set in extension config; nothing to do.'
+    exit 0
+}
+
+# Reject absolute paths and '..' path segments in context_file
+if ([System.IO.Path]::IsPathRooted($ContextFile)) {
+    Write-Warning "agent-context: context_file must be a project-relative path; got '$ContextFile'."
+    exit 1
+}
+$cfSegments = $ContextFile -split '[/\\]'
+if ($cfSegments -contains '..') {
+    Write-Warning "agent-context: context_file must not contain '..' path segments; got '$ContextFile'."
+    exit 1
+}
+
+$MarkerStart = $DefaultStart
+$MarkerEnd   = $DefaultEnd
+$cm = Get-ConfigValue -Object $Options -Key 'context_markers'
+if ($cm) {
+    $cmStart = Get-ConfigValue -Object $cm -Key 'start'
+    if ($cmStart -is [string] -and $cmStart) {
+        $MarkerStart = $cmStart
+    }
+    $cmEnd = Get-ConfigValue -Object $cm -Key 'end'
+    if ($cmEnd -is [string] -and $cmEnd) {
+        $MarkerEnd = $cmEnd
+    }
+}
+
+if (-not $PlanPath) {
+    # Discover plan.md exactly one level deep (specs/<feature>/plan.md),
+    # matching the bash glob specs/*/plan.md. Wrap in try/catch so access errors under
+    # $ErrorActionPreference = 'Stop' don't abort the script.
+    try {
+        $specsDir = Join-Path $ProjectRoot 'specs'
+        $candidate = Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |
+            ForEach-Object { Get-Item -LiteralPath (Join-Path $_.FullName 'plan.md') -ErrorAction SilentlyContinue } |
+            Where-Object { $_ } |
+            Sort-Object LastWriteTime -Descending |
+            Select-Object -First 1
+        if ($candidate) {
+            $PlanPath = [System.IO.Path]::GetRelativePath($ProjectRoot, $candidate.FullName).Replace('\','/')
+        }
+    } catch {
+        # Non-fatal: continue without a plan path.
+    }
+}
+
+$CtxPath = Join-Path $ProjectRoot $ContextFile
+$CtxDir  = Split-Path -Parent $CtxPath
+if ($CtxDir -and -not (Test-Path -LiteralPath $CtxDir)) {
+    New-Item -ItemType Directory -Path $CtxDir -Force | Out-Null
+}
+
+$lines = @($MarkerStart,
+           'For additional context about technologies to be used, project structure,',
+           'shell commands, and other important information, read the current plan')
+if ($PlanPath) {
+    $lines += "at $PlanPath"
+}
+$lines += $MarkerEnd
+$Section = ($lines -join "`n") + "`n"
+
+if (Test-Path -LiteralPath $CtxPath) {
+    $rawBytes = [System.IO.File]::ReadAllBytes($CtxPath)
+    # Strip UTF-8 BOM if present
+    if ($rawBytes.Length -ge 3 -and $rawBytes[0] -eq 0xEF -and $rawBytes[1] -eq 0xBB -and $rawBytes[2] -eq 0xBF) {
+        $content = [System.Text.Encoding]::UTF8.GetString($rawBytes, 3, $rawBytes.Length - 3)
+    } else {
+        $content = [System.Text.Encoding]::UTF8.GetString($rawBytes)
+    }
+
+    $s = $content.IndexOf($MarkerStart)
+    $e = if ($s -ge 0) { $content.IndexOf($MarkerEnd, $s) } else { $content.IndexOf($MarkerEnd) }
+
+    if ($s -ge 0 -and $e -ge 0 -and $e -gt $s) {
+        $endOfMarker = $e + $MarkerEnd.Length
+        if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`r") { $endOfMarker++ }
+        if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`n") { $endOfMarker++ }
+        $newContent = $content.Substring(0, $s) + $Section + $content.Substring($endOfMarker)
+    } elseif ($s -ge 0) {
+        $newContent = $content.Substring(0, $s) + $Section
+    } elseif ($e -ge 0) {
+        $endOfMarker = $e + $MarkerEnd.Length
+        if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`r") { $endOfMarker++ }
+        if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`n") { $endOfMarker++ }
+        $newContent = $Section + $content.Substring($endOfMarker)
+    } else {
+        if ($content -and -not $content.EndsWith("`n")) { $content += "`n" }
+        if ($content) { $newContent = $content + "`n" + $Section } else { $newContent = $Section }
+    }
+} else {
+    $newContent = $Section
+}
+
+$newContent = $newContent.Replace("`r`n", "`n").Replace("`r", "`n")
+[System.IO.File]::WriteAllText($CtxPath, $newContent, (New-Object System.Text.UTF8Encoding($false)))
+
+Write-Host "agent-context: updated $ContextFile"

extensions/catalog.community.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-05-07T20:05:00Z",
+  "updated_at": "2026-06-04T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
   "extensions": {
     "aide": {
@@ -68,6 +68,43 @@
       "created_at": "2026-03-31T00:00:00Z",
       "updated_at": "2026-03-31T00:00:00Z"
     },
+    "agent-governance": {
+      "name": "Agent Governance",
+      "id": "agent-governance",
+      "description": "Generate agent-platform repository governance files from Spec Kit metadata.",
+      "author": "bigben",
+      "version": "1.2.0",
+      "download_url": "https://github.com/bigsmartben/spec-kit-agent-governance/archive/refs/tags/v1.2.0.zip",
+      "repository": "https://github.com/bigsmartben/spec-kit-agent-governance",
+      "homepage": "https://github.com/bigsmartben/spec-kit-agent-governance",
+      "documentation": "https://github.com/bigsmartben/spec-kit-agent-governance/blob/main/README.md",
+      "changelog": "https://github.com/bigsmartben/spec-kit-agent-governance/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.0",
+        "tools": [
+          {
+            "name": "uv",
+            "required": true
+          }
+        ]
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 3
+      },
+      "tags": [
+        "governance",
+        "agents",
+        "memory",
+        "context"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-14T00:00:00Z",
+      "updated_at": "2026-05-21T00:00:00Z"
+    },
     "agent-orchestrator": {
       "name": "Intelligent Agent Orchestrator",
       "id": "agent-orchestrator",
@@ -137,6 +174,37 @@
       "created_at": "2026-05-07T00:00:00Z",
       "updated_at": "2026-05-07T00:00:00Z"
     },
+    "arch": {
+      "name": "Architecture Workflow",
+      "id": "arch",
+      "description": "Generate or reverse project-level 4+1 architecture view artifacts and synthesis",
+      "author": "bigsmartben",
+      "version": "1.1.0",
+      "download_url": "https://github.com/bigsmartben/spec-kit-arch/archive/refs/tags/v1.1.0.zip",
+      "repository": "https://github.com/bigsmartben/spec-kit-arch",
+      "homepage": "https://github.com/bigsmartben/spec-kit-arch",
+      "documentation": "https://github.com/bigsmartben/spec-kit-arch/blob/main/README.md",
+      "changelog": "https://github.com/bigsmartben/spec-kit-arch/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.10.dev0"
+      },
+      "provides": {
+        "commands": 2,
+        "hooks": 0
+      },
+      "tags": [
+        "architecture",
+        "4plus1",
+        "workflow",
+        "design"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-14T00:00:00Z",
+      "updated_at": "2026-05-15T00:00:00Z"
+    },
     "architect-preview": {
       "name": "Architect Impact Previewer",
       "id": "architect-preview",
@@ -172,10 +240,10 @@
     "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.",
+      "description": "Framework-agnostic architecture review extension for validating implementation against governance and architecture constitutions, detecting architectural drift, and generating non-blocking refactor tasks.",
       "author": "DyanGalih",
-      "version": "1.8.0",
-      "download_url": "https://github.com/DyanGalih/spec-kit-architecture-guard/archive/refs/tags/v1.8.0.zip",
+      "version": "1.8.9",
+      "download_url": "https://github.com/DyanGalih/spec-kit-architecture-guard/archive/refs/tags/v1.8.9.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",
@@ -185,22 +253,23 @@
         "speckit_version": ">=0.1.0"
       },
       "provides": {
-        "commands": 6,
-        "hooks": 0
+        "commands": 10,
+        "hooks": 3
       },
       "tags": [
         "architecture",
-        "governance",
-        "drift-detection",
+        "spec-kit",
+        "review",
         "refactor",
-        "monolithic",
-        "microservices"
+        "workflow",
+        "governance",
+        "guardrails"
       ],
       "verified": false,
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-05-05T07:26:00Z",
-      "updated_at": "2026-05-07T15:37:14Z"
+      "updated_at": "2026-05-27T00:00:00Z"
     },
     "archive": {
       "name": "Archive Extension",
@@ -368,6 +437,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",
@@ -467,6 +568,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",
@@ -1113,6 +1246,39 @@
       "created_at": "2026-03-17T00:00:00Z",
       "updated_at": "2026-03-17T00:00:00Z"
     },
+    "linear": {
+      "name": "Linear Integration",
+      "id": "linear",
+      "description": "Mirror spec-kit feature directories into Linear (filesystem → Linear, reconcile-based, unidirectional).",
+      "author": "Ash Brener",
+      "version": "0.2.0",
+      "download_url": "https://github.com/ashbrener/spec-kit-linear/archive/refs/tags/v0.2.0.zip",
+      "repository": "https://github.com/ashbrener/spec-kit-linear",
+      "homepage": "https://github.com/ashbrener/spec-kit-linear",
+      "documentation": "https://github.com/ashbrener/spec-kit-linear/blob/main/README.md",
+      "changelog": "https://github.com/ashbrener/spec-kit-linear/releases",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 5,
+        "hooks": 6
+      },
+      "tags": [
+        "issue-tracking",
+        "linear",
+        "tasks-sync",
+        "lifecycle-mirror",
+        "memory",
+        "cross-repo"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-06-01T00:00:00Z",
+      "updated_at": "2026-06-01T00:00:00Z"
+    },
     "m365": {
       "name": "Microsoft 365 Integration",
       "id": "m365",
@@ -1481,8 +1647,8 @@
       "id": "memory-md",
       "description": "Spec Kit extension for repository-native Markdown memory that captures durable decisions, bugs, and project context",
       "author": "DyanGalih",
-      "version": "0.8.0",
-      "download_url": "https://github.com/DyanGalih/spec-kit-memory-hub/archive/refs/tags/v0.8.0.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",
@@ -1492,8 +1658,8 @@
         "speckit_version": ">=0.2.0"
       },
       "provides": {
-        "commands": 6,
-        "hooks": 0
+        "commands": 7,
+        "hooks": 2
       },
       "tags": [
         "memory",
@@ -1507,15 +1673,15 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-04-23T00:00:00Z",
-      "updated_at": "2026-05-07T15:37:14Z"
+      "updated_at": "2026-05-11T14:58:00Z"
     },
     "memorylint": {
       "name": "MemoryLint",
       "id": "memorylint",
       "description": "Agent memory governance tool: Automatically audits and fixes boundary conflicts between AGENTS.md and the constitution.",
       "author": "RbBtSn0w",
-      "version": "1.3.0",
-      "download_url": "https://github.com/RbBtSn0w/spec-kit-extensions/releases/download/memorylint-v1.3.0/memorylint.zip",
+      "version": "1.4.0",
+      "download_url": "https://github.com/RbBtSn0w/spec-kit-extensions/releases/download/memorylint-v1.4.0/memorylint.zip",
       "repository": "https://github.com/RbBtSn0w/spec-kit-extensions",
       "homepage": "https://github.com/RbBtSn0w/spec-kit-extensions/tree/main/memorylint",
       "documentation": "https://github.com/RbBtSn0w/spec-kit-extensions/blob/main/memorylint/README.md",
@@ -1525,8 +1691,8 @@
         "speckit_version": ">=0.5.1"
       },
       "provides": {
-        "commands": 1,
-        "hooks": 1
+        "commands": 2,
+        "hooks": 3
       },
       "tags": [
         "memory",
@@ -1539,7 +1705,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-04-09T00:00:00Z",
-      "updated_at": "2026-04-16T13:10:26Z"
+      "updated_at": "2026-05-24T01:06:49Z"
     },
     "multi-model-review": {
       "name": "Multi-Model Review",
@@ -1591,6 +1757,37 @@
       "created_at": "2026-05-04T02:51:52Z",
       "updated_at": "2026-05-04T02:51:52Z"
     },
+    "multi-sites": {
+      "name": "Multi-Sites Spec Kit",
+      "id": "multi-sites",
+      "description": "Multi-site aware specify command with per-site spec folders, auto-increment, and Drupal support",
+      "author": "teeyo",
+      "version": "1.0.0",
+      "download_url": "https://github.com/teeyo/spec-kit-multi-sites/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/teeyo/spec-kit-multi-sites",
+      "homepage": "https://github.com/teeyo/spec-kit-multi-sites",
+      "documentation": "https://github.com/teeyo/spec-kit-multi-sites/blob/main/README.md",
+      "changelog": "https://github.com/teeyo/spec-kit-multi-sites/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 0
+      },
+      "tags": [
+        "multi-site",
+        "drupal",
+        "workflow",
+        "process"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-06-01T00:00:00Z",
+      "updated_at": "2026-06-01T00:00:00Z"
+    },
     "onboard": {
       "name": "Onboard",
       "id": "onboard",
@@ -1782,13 +1979,86 @@
       "created_at": "2026-03-18T00:00:00Z",
       "updated_at": "2026-03-18T00:00:00Z"
     },
+    "preview": {
+      "name": "Interactive HTML Preview",
+      "id": "preview",
+      "description": "Generate self-contained interactive HTML prototypes from Spec Kit artifacts",
+      "author": "bigsmartben",
+      "version": "1.0.0",
+      "download_url": "https://github.com/bigsmartben/spec-kit-preview/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/bigsmartben/spec-kit-preview",
+      "homepage": "https://github.com/bigsmartben/spec-kit-preview",
+      "documentation": "https://github.com/bigsmartben/spec-kit-preview/blob/main/README.md",
+      "changelog": "https://github.com/bigsmartben/spec-kit-preview/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.10.dev0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 0
+      },
+      "tags": [
+        "preview",
+        "prototype",
+        "html",
+        "ux"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-15T00:00:00Z",
+      "updated_at": "2026-05-15T00:00:00Z"
+    },
+    "product": {
+      "name": "Product Spec Extension",
+      "id": "product",
+      "description": "Generates PRFAQ, Lean PRD, stakeholder summaries, and technical designs from engineering specs.",
+      "author": "d0whc3r",
+      "version": "0.8.3",
+      "download_url": "https://github.com/d0whc3r/spec-kit-product/releases/download/v0.8.3/product-0.8.3.zip",
+      "repository": "https://github.com/d0whc3r/spec-kit-product",
+      "homepage": "https://d0whc3r.github.io/spec-kit-product/",
+      "documentation": "https://github.com/d0whc3r/spec-kit-product/wiki",
+      "changelog": "https://github.com/d0whc3r/spec-kit-product/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.2.0"
+      },
+      "provides": {
+        "commands": 4,
+        "hooks": 3
+      },
+      "tags": [
+        "design",
+        "documentation",
+        "jtbd",
+        "lean-prd",
+        "planning",
+        "prd",
+        "prfaq",
+        "product",
+        "product-management",
+        "requirements",
+        "spec",
+        "spec-kit",
+        "spec-kit-extension",
+        "stakeholder",
+        "technical-design"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-26T00:00:00Z",
+      "updated_at": "2026-06-01T00:00:00Z"
+    },
     "product-forge": {
       "name": "Product Forge",
       "id": "product-forge",
-      "description": "Full product lifecycle from research to release — portfolio, lite mode, monorepo, optional V-Model",
+      "description": "Full product lifecycle from research to release — express/lite/standard/v-model tracks, living spec + traceability, structured journeys → E2E, monorepo, and selectable doc-structure strategies",
       "author": "VaiYav",
-      "version": "1.5.1",
-      "download_url": "https://github.com/VaiYav/speckit-product-forge/archive/refs/tags/v1.5.1.zip",
+      "version": "1.6.0",
+      "download_url": "https://github.com/VaiYav/speckit-product-forge/archive/refs/tags/v1.6.0.zip",
       "repository": "https://github.com/VaiYav/speckit-product-forge",
       "homepage": "https://github.com/VaiYav/speckit-product-forge",
       "documentation": "https://github.com/VaiYav/speckit-product-forge/blob/main/README.md",
@@ -1798,7 +2068,7 @@
         "speckit_version": ">=0.1.0"
       },
       "provides": {
-        "commands": 29,
+        "commands": 31,
         "hooks": 0
       },
       "tags": [
@@ -1812,7 +2082,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-03-28T00:00:00Z",
-      "updated_at": "2026-04-24T15:52:00Z"
+      "updated_at": "2026-06-02T00:00:00Z"
     },
     "qa": {
       "name": "QA Testing Extension",
@@ -1844,6 +2114,38 @@
       "created_at": "2026-04-01T00:00:00Z",
       "updated_at": "2026-04-01T00:00:00Z"
     },
+    "rag-azure-builder": {
+      "name": "RAG Azure Builder",
+      "id": "rag-azure-builder",
+      "description": "Spec Kit extension for onboarding and operating an Azure RAG stack with guided workflows.",
+      "author": "Sertxito",
+      "version": "1.2.0",
+      "download_url": "https://github.com/Sertxito/spec-kit-extension-rag-azure-builder/archive/refs/tags/v1.2.0.zip",
+      "repository": "https://github.com/Sertxito/spec-kit-extension-rag-azure-builder",
+      "homepage": "https://github.com/Sertxito/spec-kit-extension-rag-azure-builder",
+      "documentation": "https://github.com/Sertxito/spec-kit-extension-rag-azure-builder#readme",
+      "changelog": "https://github.com/Sertxito/spec-kit-extension-rag-azure-builder/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.0"
+      },
+      "provides": {
+        "commands": 5,
+        "hooks": 0
+      },
+      "tags": [
+        "azure",
+        "rag",
+        "search",
+        "onboarding",
+        "cost-optimization"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-06-01T00:00:00Z",
+      "updated_at": "2026-06-01T00:00:00Z"
+    },
     "ralph": {
       "name": "Ralph Loop",
       "id": "ralph",
@@ -2017,6 +2319,44 @@
       "created_at": "2026-03-23T13:30:00Z",
       "updated_at": "2026-03-23T13:30:00Z"
     },
+    "reqnroll-bdd": {
+      "name": "Reqnroll BDD",
+      "id": "reqnroll-bdd",
+      "description": "Adds Reqnroll BDD planning, Gherkin generation, traceability, safe task injection, handoff, and verification to Spec Kit.",
+      "author": "LoogaCY Studio",
+      "version": "1.1.0",
+      "download_url": "https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd/archive/refs/tags/v1.1.0.zip",
+      "repository": "https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd",
+      "homepage": "https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd",
+      "documentation": "https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd#readme",
+      "changelog": "https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.0",
+        "tools": [
+          {
+            "name": "dotnet",
+            "required": false
+          }
+        ]
+      },
+      "provides": {
+        "commands": 4,
+        "hooks": 1
+      },
+      "tags": [
+        "bdd",
+        "reqnroll",
+        "dotnet",
+        "gherkin",
+        "acceptance-testing"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-13T00:00:00Z",
+      "updated_at": "2026-05-30T00:00:00Z"
+    },
     "retro": {
       "name": "Retro Extension",
       "id": "retro",
@@ -2215,8 +2555,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.4.5",
-      "download_url": "https://github.com/DyanGalih/spec-kit-security-review/archive/refs/tags/v1.4.5.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",
@@ -2226,8 +2566,8 @@
         "speckit_version": ">=0.1.0"
       },
       "provides": {
-        "commands": 7,
-        "hooks": 0
+        "commands": 9,
+        "hooks": 3
       },
       "tags": [
         "security",
@@ -2240,7 +2580,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-04-03T03:24:03Z",
-      "updated_at": "2026-05-06T22:28:55Z"
+      "updated_at": "2026-05-11T14:58:00Z"
     },
     "sf": {
       "name": "SFSpeckit — Salesforce Spec-Driven Development",
@@ -2411,6 +2751,55 @@
       "created_at": "2026-04-30T00:00:00Z",
       "updated_at": "2026-04-30T00:00:00Z"
     },
+    "speckit-superpowers-bridge": {
+      "name": "Superpowers Implementation Bridge",
+      "id": "speckit-superpowers-bridge",
+      "description": "Thin orchestrator between Spec Kit (design) and Superpowers (implementation). Cross-agent.",
+      "author": "lihan3238",
+      "version": "1.0.2",
+      "download_url": "https://github.com/lihan3238/speckit-superpowers-bridge/releases/download/v1.0.2/speckit-superpowers-bridge-v1.0.2.zip",
+      "repository": "https://github.com/lihan3238/speckit-superpowers-bridge",
+      "homepage": "https://github.com/lihan3238/speckit-superpowers-bridge",
+      "documentation": "https://github.com/lihan3238/speckit-superpowers-bridge#readme",
+      "changelog": "https://github.com/lihan3238/speckit-superpowers-bridge/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.10",
+        "tools": [
+          {
+            "name": "powershell",
+            "version": ">=5.1",
+            "required": false
+          },
+          {
+            "name": "bash",
+            "version": ">=4.0",
+            "required": false
+          },
+          {
+            "name": "jq",
+            "version": ">=1.6",
+            "required": false
+          }
+        ]
+      },
+      "provides": {
+        "commands": 3,
+        "hooks": 5
+      },
+      "tags": [
+        "bridge",
+        "superpowers",
+        "cross-agent",
+        "tdd",
+        "workflow"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-15T00:00:00Z",
+      "updated_at": "2026-06-04T00:00:00Z"
+    },
     "speckit-utils": {
       "name": "SDD Utilities",
       "id": "speckit-utils",
@@ -2479,21 +2868,21 @@
     "squad": {
       "name": "Squad Bridge",
       "id": "squad",
-      "description": "Bootstrap and synchronize a Squad agent team from your Spec Kit spec and tasks.",
+      "description": "Bootstrap and synchronize a Squad agent team from your Speckit 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",
+      "version": "1.3.0",
+      "download_url": "https://github.com/jwill824/spec-kit-squad/archive/refs/tags/v1.3.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",
+        "speckit_version": ">=0.8.11",
         "tools": [
           {
             "name": "@bradygaster/squad-cli",
-            "version": ">=0.1.0",
+            "version": ">=0.9.4",
             "required": true
           }
         ]
@@ -2513,7 +2902,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-04-29T00:00:00Z",
-      "updated_at": "2026-04-29T00:00:00Z"
+      "updated_at": "2026-05-20T00:00:00Z"
     },
     "staff-review": {
       "name": "Staff Review Extension",
@@ -2612,8 +3001,8 @@
       "id": "superb",
       "description": "Orchestrates obra/superpowers skills within the spec-kit SDD workflow. Thin bridge commands delegate to superpowers' authoritative SKILL.md files at runtime (with graceful fallback), while bridge-original commands provide spec-kit-native value. Eight commands cover the full lifecycle: intent clarification, TDD enforcement, task review, verification, critique, systematic debugging, branch completion, and review response. Hook-bound commands fire automatically; standalone commands are invoked when needed.",
       "author": "rbbtsn0w",
-      "version": "1.3.0",
-      "download_url": "https://github.com/RbBtSn0w/spec-kit-extensions/releases/download/superpowers-bridge-v1.3.0/superpowers-bridge.zip",
+      "version": "1.4.0",
+      "download_url": "https://github.com/RbBtSn0w/spec-kit-extensions/releases/download/superpowers-bridge-v1.4.0/superpowers-bridge.zip",
       "repository": "https://github.com/RbBtSn0w/spec-kit-extensions",
       "homepage": "https://github.com/RbBtSn0w/spec-kit-extensions",
       "documentation": "https://github.com/RbBtSn0w/spec-kit-extensions/blob/main/superpowers-bridge/README.md",
@@ -2631,7 +3020,7 @@
       },
       "provides": {
         "commands": 8,
-        "hooks": 4
+        "hooks": 3
       },
       "tags": [
         "methodology",
@@ -2648,15 +3037,15 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-03-30T00:00:00Z",
-      "updated_at": "2026-04-16T14:08:23Z"
+      "updated_at": "2026-05-24T01:07:34Z"
     },
-    "superpowers-bridge": {
-      "name": "Superpowers Bridge",
-      "id": "superpowers-bridge",
+    "superspec": {
+      "name": "Superspec",
+      "id": "superspec",
       "description": "Bridges spec-kit workflows with obra/superpowers capabilities for brainstorming, TDD, code review, and resumable execution.",
       "author": "WangX0111",
-      "version": "1.0.0",
-      "download_url": "https://github.com/WangX0111/superspec/archive/refs/tags/v1.0.0.zip",
+      "version": "1.0.1",
+      "download_url": "https://github.com/WangX0111/superspec/archive/refs/tags/v1.0.1.zip",
       "repository": "https://github.com/WangX0111/superspec",
       "homepage": "https://github.com/WangX0111/superspec",
       "documentation": "https://github.com/WangX0111/superspec/blob/main/README.md",
@@ -2681,7 +3070,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-04-22T00:00:00Z",
-      "updated_at": "2026-04-22T00:00:00Z"
+      "updated_at": "2026-05-30T00:00:00Z"
     },
     "sync": {
       "name": "Spec Sync",
@@ -2715,6 +3104,74 @@
       "created_at": "2026-03-02T00:00:00Z",
       "updated_at": "2026-03-02T00:00:00Z"
     },
+    "team-assign": {
+      "name": "Team Assign",
+      "id": "team-assign",
+      "description": "Assign tasks.md items to human engineers, split into subtasks, and generate a per-engineer workboard",
+      "author": "tarunkumarbhati",
+      "version": "1.0.0",
+      "download_url": "https://github.com/tarunkumarbhati/spec-kit-team-assign/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/tarunkumarbhati/spec-kit-team-assign",
+      "homepage": "https://github.com/tarunkumarbhati/spec-kit-team-assign",
+      "documentation": "https://github.com/tarunkumarbhati/spec-kit-team-assign/blob/main/README.md",
+      "changelog": "https://github.com/tarunkumarbhati/spec-kit-team-assign/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 3
+      },
+      "tags": [
+        "team",
+        "assignment",
+        "process",
+        "planning",
+        "subtasks"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-20T00:00:00Z",
+      "updated_at": "2026-05-20T00:00:00Z"
+    },
+    "time-machine": {
+      "name": "Time Machine",
+      "id": "time-machine",
+      "description": "Retroactively apply the full SDD workflow to existing codebases — analyse, spec, and ship feature-by-feature",
+      "author": "te3yo",
+      "version": "1.1.0",
+      "download_url": "https://github.com/teeyo/spec-kit-time-machine/archive/refs/tags/v1.1.0.zip",
+      "repository": "https://github.com/teeyo/spec-kit-time-machine",
+      "homepage": "https://github.com/teeyo/spec-kit-time-machine",
+      "documentation": "https://github.com/teeyo/spec-kit-time-machine",
+      "changelog": "https://github.com/teeyo/spec-kit-time-machine/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0",
+        "tools": [
+          {
+            "name": "git",
+            "required": true
+          }
+        ]
+      },
+      "provides": {
+        "commands": 3,
+        "hooks": 1
+      },
+      "tags": [
+        "brownfield",
+        "automation",
+        "workflow",
+        "process"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-15T00:00:00Z",
+      "updated_at": "2026-05-15T00:00:00Z"
+    },
     "tinyspec": {
       "name": "TinySpec",
       "id": "tinyspec",
@@ -2810,6 +3267,48 @@
       "created_at": "2026-05-01T00:00:00Z",
       "updated_at": "2026-05-01T00:00:00Z"
     },
+    "token-budget": {
+      "name": "Token Budget",
+      "id": "token-budget",
+      "description": "Reduces LLM token consumption in Spec Kit workflows: compact artifacts in-place, scope per-phase reading, suppress prose padding, and report token usage.",
+      "author": "Tine Kondo",
+      "version": "1.0.1",
+      "download_url": "https://github.com/tinesoft/spec-kit-token-budget/archive/refs/tags/v1.0.1.zip",
+      "repository": "https://github.com/tinesoft/spec-kit-token-budget",
+      "homepage": "https://github.com/tinesoft/spec-kit-token-budget",
+      "documentation": "https://github.com/tinesoft/spec-kit-token-budget/blob/main/README.md",
+      "changelog": "https://github.com/tinesoft/spec-kit-token-budget/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0",
+        "tools": [
+          {
+            "name": "python3",
+            "required": false
+          },
+          {
+            "name": "rtk",
+            "required": false
+          }
+        ]
+      },
+      "provides": {
+        "commands": 4,
+        "hooks": 6
+      },
+      "tags": [
+        "tokens",
+        "budget",
+        "context",
+        "efficiency",
+        "cost-optimization"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-26T00:00:00Z",
+      "updated_at": "2026-05-26T00:00:00Z"
+    },
     "v-model": {
       "name": "V-Model Extension Pack",
       "id": "v-model",
@@ -3108,4 +3607,4 @@
       "updated_at": "2026-04-13T00:00:00Z"
     }
   }
-}
+}

extensions/catalog.json

@@ -3,6 +3,20 @@
   "updated_at": "2026-04-10T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json",
   "extensions": {
+    "agent-context": {
+      "name": "Coding Agent Context",
+      "id": "agent-context",
+      "version": "1.0.0",
+      "description": "Manages coding agent context/instruction files (e.g., CLAUDE.md, copilot-instructions.md) with project-specific plan references and configurable markers",
+      "author": "spec-kit-core",
+      "repository": "https://github.com/github/spec-kit",
+      "bundled": true,
+      "tags": [
+        "agent",
+        "context",
+        "core"
+      ]
+    },
     "git": {
       "name": "Git Branching Workflow",
       "id": "git",

extensions/git/commands/speckit.git.initialize.md

@@ -35,7 +35,7 @@ Replace the script to add project-specific Git initialization steps:
 ## Output
 
 On success:
-- `✓ Git repository initialized`
+- `[OK] Git repository initialized`
 
 ## Graceful Degradation
 

extensions/git/scripts/powershell/auto-commit.ps1

@@ -115,7 +115,7 @@ if (Test-Path $configFile) {
         }
     }
 } else {
-    # No config file — auto-commit disabled by default
+    # No config file -- auto-commit disabled by default
     exit 0
 }
 

extensions/git/scripts/powershell/git-common.ps1

@@ -1,6 +1,6 @@
 #!/usr/bin/env pwsh
 # Git-specific common functions for the git extension.
-# Extracted from scripts/powershell/common.ps1 — contains only git-specific
+# Extracted from scripts/powershell/common.ps1 -- contains only git-specific
 # branch validation and detection logic.
 
 function Test-HasGit {

extensions/git/scripts/powershell/initialize-repo.ps1

@@ -1,7 +1,7 @@
 #!/usr/bin/env pwsh
 # Git extension: initialize-repo.ps1
 # Initialize a Git repository with an initial commit.
-# Customizable — replace this script to add .gitignore templates,
+# Customizable -- replace this script to add .gitignore templates,
 # default branch config, git-flow, LFS, signing, etc.
 $ErrorActionPreference = 'Stop'
 
@@ -66,4 +66,4 @@ try {
     exit 1
 }
 
-Write-Host "✓ Git repository initialized"
+Write-Host "[OK] Git repository initialized"

integrations/catalog.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-04-29T00:00:00Z",
+  "updated_at": "2026-06-02T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/integrations/catalog.json",
   "integrations": {
     "claude": {
@@ -12,6 +12,15 @@
       "repository": "https://github.com/github/spec-kit",
       "tags": ["cli", "anthropic"]
     },
+    "cline": {
+      "id": "cline",
+      "name": "Cline",
+      "version": "1.0.0",
+      "description": "Cline IDE integration",
+      "author": "spec-kit-core",
+      "repository": "https://github.com/github/spec-kit",
+      "tags": ["ide"]
+    },
     "copilot": {
       "id": "copilot",
       "name": "GitHub Copilot",
@@ -165,6 +174,15 @@
       "repository": "https://github.com/github/spec-kit",
       "tags": ["ide"]
     },
+    "rovodev": {
+      "id": "rovodev",
+      "name": "RovoDev ACLI",
+      "version": "1.0.0",
+      "description": "Atlassian RovoDev integration",
+      "author": "spec-kit-core",
+      "repository": "https://github.com/github/spec-kit",
+      "tags": ["cli", "atlassian"]
+    },
     "bob": {
       "id": "bob",
       "name": "IBM Bob",
@@ -272,6 +290,15 @@
       "author": "spec-kit-core",
       "repository": "https://github.com/github/spec-kit",
       "tags": ["cli"]
+    },
+    "hermes": {
+      "id": "hermes",
+      "name": "Hermes Agent",
+      "version": "1.0.0",
+      "description": "Hermes Agent skills-based integration by Nous Research",
+      "author": "spec-kit-core",
+      "repository": "https://github.com/github/spec-kit",
+      "tags": ["cli", "skills"]
     }
   }
 }

newsletters/2026-May.md

@@ -0,0 +1,138 @@
+# Spec Kit - May 2026 Newsletter
+
+This edition covers Spec Kit activity in May 2026 — a month defined by three milestone 100s: **100,000+ stars**, **100+ community extensions**, and recognition as a **top-100 GitHub project**. Fourteen releases shipped (v0.8.4 through v0.8.17), delivering multi-agent install support, constitution governance enforcement, and continued architecture cleanup. The Open Source Friday livestream, a wave of multilingual coverage, and analyst recognition from The Futurum Group marked the project's transition from fast-moving experiment to established ecosystem. A summary is in the table below, followed by details.
+
+| **Spec Kit Core (May 2026)** | **Community & Content** | **SDD Ecosystem & Next** |
+| --- | --- | --- |
+| Fourteen releases shipped with key features: multi-install for concurrent agent integrations, constitution governance in implement, authentication provider registry, Hermes and Lingma agents, and a `__init__.py` decomposition series. The repo grew from ~92k to **106,951 stars**, crossing **100K** on May 21. [\[github.com\]](https://github.com/github/spec-kit/releases) | The community extension catalog crossed **100 entries** (now 105). Open Source Friday livestream drove a press wave: Visual Studio Magazine, DevOps.com, MarkTechPost, HackerNoon, and 25+ more articles — now tracked across multiple languages following an expanded discovery methodology. **217 contributors** now listed. | MarkTechPost called Spec Kit "the most community-adopted open-source option" for SDD. The Futurum Group's Mitch Ashley framed specs as "the unit of governance across agents and contributors." Truong Phung published a 61-min production playbook referencing Spec Kit. Competitors grew but differentiate on orchestration; Spec Kit leads in portability and community. |
+
+***
+
+> **A Month of 100s.** May 2026 was defined by three milestones that all share the same number. The community extension catalog crossed **100 entries** during the week of May 21, making Spec Kit a genuine platform with more capabilities in its ecosystem than in its core. The repository crossed **100,000 GitHub stars** on the same week. And with 107K stars at month's end, Spec Kit now ranks among the **top 100 most-starred projects on all of GitHub**. None of this would have happened without the community — the contributors, extension authors, preset builders, article writers, and practitioners who turned a spec-driven development experiment into an ecosystem. Thank you.
+
+## Spec Kit Project Updates
+
+### Releases Overview
+
+**v0.8.4–v0.8.7** (May 1–7) opened the month with four patch releases delivering the most-requested feature of the year: **multi-install support for concurrent AI agent integrations** (#2389), enabling multiple agents in a single project. This closed five long-standing issues dating back 228 days. The releases also added **constitution governance in `/speckit.implement`** (#2460), ensuring the implement phase now loads `constitution.md` to enforce governance during code generation. An **authentication provider registry** (#2393) added config-driven multi-platform auth. The **Lingma agent** joined the integration roster. Security hardening included pinning all remaining GitHub Actions to immutable SHAs (#2441) and URL scheme validation to prevent SSRF-style bugs (#2449). Seven new community extensions and six new governance-themed presets landed. [\[github.com\]](https://github.com/github/spec-kit/releases)
+
+**v0.8.8–v0.8.10** (May 8–14) shipped three releases focused on stability. **Version feature reporting** (#2548) improved upgrade visibility. Bug fixes addressed the Kiro CLI `$ARGUMENTS` placeholder (#1926, open 52 days), markdownlint-safe template metadata (#1343, open 147 days), and preset skill description precedence. The `__init__.py` decomposition series began with PRs 1–2/8, extracting `_console.py`, `_assets.py`, and `_utils.py`. Seven new extensions joined (Architecture Workflow, Agent Governance, BrownKit, Schedule, Reqnroll BDD, MDE, Changelog) along with two new presets (MDE, game-narrative-writing). The docs site received a major overhaul: the landing page was revamped with a four-pillar card layout, the install section was streamlined, and the community extensions table moved to the docs site. [\[github.com\]](https://github.com/github/spec-kit/releases)
+
+**v0.8.11–v0.8.13** (May 15–21) delivered three releases as the repo **crossed 100K stars**. **Agentic catalog submissions** (#2655) added AI-assisted workflows for community catalog contributions. A **high-assurance spec workflow** was documented (#2518). The while/do-while loop stale output bug (#2592) was caught and fixed same-day. **Integration auto mode** (#2421) now follows the project's initialized AI instead of hardcoding Copilot. The PowerShell UTF-8 BOM issue (#2280) was resolved. Four new extensions joined (Team Assign, Interactive HTML Preview, Time Machine, Superpowers Implementation Bridge), bringing the catalog to **103 entries** — crossing the 100 mark. [\[github.com\]](https://github.com/github/spec-kit/releases)
+
+**v0.8.14–v0.8.17** (May 22–28) closed the month with four releases. The **Hermes Agent** joined as a new integration target (#2651). Workflows gained a **`{{ context.run_id }}` template variable** (#2664). A new `SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS` environment variable (#2596) lets users pass extra flags to agent subprocesses. **Extension installs from URLs now prompt for confirmation** (#2745), a security improvement for URL-based installs. The spec quality checklist is now **re-validated after clarify updates the spec** (#2715). Token Budget, Product Spec, and Workflow Preset extensions joined the catalog, bringing it to **105 entries**. [\[github.com\]](https://github.com/github/spec-kit/releases)
+
+### Architecture & Refactoring
+
+The most significant internal effort in May was the **`__init__.py` decomposition series**, progressing through PRs 1–4 of 8. This systematic extraction moved `_console.py`, `_assets.py`, `_utils.py`, `_version.py`, and the `commands/` package out of the monolithic init module, improving maintainability and contributor onboarding. The **ExtensionCatalog was migrated to the shared catalog stack base** (#2437), reducing duplicated catalog handling across extension, preset, and integration catalogs. [\[github.com\]](https://github.com/github/spec-kit/releases)
+
+### Bug Fixes and Security
+
+Fourteen releases produced a strong cadence of fixes. Long-standing issues resolved include the Kiro CLI `$ARGUMENTS` placeholder (52 days), markdownlint template metadata line breaks (147 days), and the `--ai` flag for adding agent commands (136 days). The PowerShell UTF-8 BOM issue was fixed, preset skill rendering now correctly resolves `__SPECKIT_COMMAND_*__` refs (#2717), and a Windows gate-step crash was addressed (#2635).
+
+Security improvements included **URL-based extension install confirmation** (#2745), **pinning GitHub Actions to immutable SHAs** (#2441), **URL scheme validation** (#2449), and restricting community submission workflows to labeled events only (#2741). [\[github.com\]](https://github.com/github/spec-kit/releases)
+
+### The Extension & Preset Ecosystem
+
+The community extension catalog grew from 92 to **105 entries** during May, crossing the **100 mark** on May 21. Thirteen new extensions were added over the month. Community presets grew from 18 to **21 entries**, with three new presets added.
+
+Notable new extensions by category:
+
+- **Architecture & governance**: Architecture Workflow (bigsmartben), Agent Governance (bigben), Architecture Guard (DyanGalih), BrownKit (Maksim Shautsou)
+- **Cost & token management**: Cost Tracker (Quratulain-bilal), Token Analyzer (Chris Roberts), Token Budget (Tine Kondo)
+- **Agent orchestration**: Agent Orchestrator (pragya247), Multi-Model Review (formin)
+- **Project management**: Team Assign (tarunkumarbhati), Changelog (Quratulain-bilal)
+- **Cloud & enterprise**: Spec2Cloud for Azure (Azure Samples), .NET Framework to Modern .NET Migration (RogerBestMsft)
+- **API & lifecycle**: API Evolve (Quratulain-bilal), Product Spec (spec-kit-product contributors)
+- **Quality**: Schedule with CP-SAT solver (Julio César Franco Ardila), Reqnroll BDD (LoogaCY Studio), MDE (AI-MDE)
+- **Spec exploration**: Interactive HTML Preview (bigsmartben), Time Machine (te3yo)
+- **Cross-tool bridges**: Superpowers Implementation Bridge (lihan3238)
+
+New governance-themed presets dominated: a11y-governance, architecture-governance, security-governance, cross-platform-governance, agent-parity-governance, and Spec2Cloud preset. Creative presets included game-narrative-writing and MDE.
+
+The extension ecosystem also showed maturation through active maintenance. **Architecture Guard** progressed through four releases (v1.6.7 → v1.8.9), adding documentation quality improvements and governance features. **Memory MD** shipped multiple updates (v0.6.9 → v0.8.0), adding a `speckit.memory-md.log-finding` command. **Security Review** reached v1.4.5 with a new `speckit.security-review.log-finding` command. **Superpowers Implementation Bridge** evolved rapidly (v0.5.0 → v0.7.0). **Squad Bridge** updated to v1.3.0, **Fiction Book Writing** to v1.8.1, **Security Governance** to v0.4.0, and **MemoryLint** to v1.4.0. [\[github.com\]](https://github.github.io/spec-kit/community/extensions.html)
+
+### Documentation & Docs Site
+
+The docs site received its most significant update since launch. The **landing page was revamped** with a four-pillar card layout (#2531). The **install section was streamlined** (#2561). The **community extensions table** was moved from the README to the docs site (#2560), reducing README length while improving discoverability. **Community sections in the README** were consolidated (#2736). The **uv installation guide** was added with inline callouts (#2465). Landing page stats and branch naming conventions were updated (#2727). [\[github.com\]](https://github.com/github/spec-kit/releases)
+
+## Community & Content
+
+### The Open Source Friday Livestream
+
+On **May 8**, the **GitHub Open Source Friday livestream** featured Spec Kit, hosted by Andrea Griffiths with lead maintainer Manfred Riem. The livestream demonstrated a full SDD workflow building a time-zone-aware command-line utility with GitHub Copilot in VS Code. Riem described AI agents as "a very capable intern and a very quick intern but it's still an intern nonetheless." He emphasized that "the spec is always the source of truth" and highlighted the community ecosystem, noting the project was "nearing the 100 mark" for extensions. The livestream drove significant press attention in the following days. [\[youtube.com\]](https://www.youtube.com/watch?v=2IArMAhkJcE)
+
+### Press and Industry Coverage
+
+May produced the broadest press coverage to date, with publications from the mainstream developer media covering Spec Kit for the first time.
+
+**Visual Studio Magazine** (David Ramel, May 12) published *"GitHub Spec Kit Takes Off as Antidote to Piecemeal 'Vibe Coding'"*, reporting on the Open Source Friday livestream and the growing ecosystem. The article noted Spec Kit's story is "no longer just that GitHub open sourced a spec-driven development toolkit last fall" but that "the toolkit is becoming a fast-moving ecosystem for teams trying to make AI-assisted development more structured, repeatable and traceable." [\[visualstudiomagazine.com\]](https://visualstudiomagazine.com/articles/2026/05/12/github-spec-kit-takes-off-as-antidote-to-piecemeal-vibe-coding.aspx)
+
+**DevOps.com** (Tom Smith, May 11) published *"GitHub's Spec Kit Puts the Spec Back in Software Development"*, featuring analyst commentary from The Futurum Group (see The Analyst View below). [\[devops.com\]](https://devops.com/githubs-spec-kit-puts-the-spec-back-in-software-development/)
+
+**MarkTechPost** (Asif Razzaq, May 8) published two articles: a comprehensive step-by-step tutorial calling Spec Kit an open-source toolkit with "90k+ stars" and "one of the faster-growing developer tooling repositories," and a 9-tool SDD comparison calling Spec Kit **"the most community-adopted open-source option"** and "the default starting point for teams new to SDD." [\[marktechpost.com\]](https://www.marktechpost.com/2026/05/08/meet-github-spec-kit-an-open-source-toolkit-for-spec-driven-development-with-ai-coding-agents/)
+
+**HackerNoon** (Andrey Kucherenko, May 6) published *"The Spec-First Development Showdown"*, a hands-on comparison of Spec Kit, OpenSpec, BMAD, and Gangsta Agents. [\[hackernoon.com\]](https://hackernoon.com/the-spec-first-development-showdown-spec-kit-openspec-bmad-and-gangsta-agents-compared)
+
+### Developer Articles and Blog Posts
+
+May produced a wave of independent coverage — well beyond any previous month. Starting this month, article discovery was expanded beyond English-centric search engines to include language-appropriate engines for 25+ languages, so the broader coverage partly reflects wider discovery rather than a sudden spike.
+
+Notable non-English coverage:
+
+- **Japanese**: テックオーシャン published a detailed experience report on *"Claude Code × Spec Kit"* on note.com, praising task decomposition accuracy while noting spec sync requires manual workarounds. [\[note.com\]](https://note.com/techocean_corp/n/nd2bd63106c16)
+- **Portuguese**: Jady Sobjak de Mello Godoi published *"GitHub Spec Kit: Revolucionando o Desenvolvimento com SDD"* on DEV Community. [\[dev.to\]](https://dev.to/jadysmgodoi/github-speckit-revolucionando-o-desenvolvimento-com-sdd-l66)
+- **Italian**: Cosmonet published a comprehensive guide, *"GitHub Spec Kit: la guida completa allo Spec-Driven Development."* [\[cosmonet.info\]](https://www.cosmonet.info/github-spec-kit-guida-spec-driven-development/)
+- **French**: InnoSpira covered Spec Kit's rapid growth past 100K stars. [\[innospira.fr\]](https://www.innospira.fr/index.php/2026/05/12/github-spec-kit-place-au-developpement-pilote-par-la-spec/)
+- **Spanish**: Q2B Studio published an overview for Spanish-speaking developers. [\[q2bstudio.com\]](https://www.q2bstudio.com/nuestro-blog/1727819/github-spec-kit-desarrollo-especificaciones-ia)
+
+Notable English-language articles:
+
+- **Truong Phung** (DEV Community, May 29) published a comprehensive production playbook for AI-assisted development, referencing Spec Kit (see The Production Playbook Pattern below). [\[dev.to\]](https://dev.to/truongpx396/building-production-grade-fullstack-products-with-ai-coding-agents-a-practical-playbook-2idd)
+- **Mehul Gupta** (Medium, May 17) called Spec Kit "an operating system for AI-assisted software engineering." [\[medium.com\]](https://medium.com/data-science-in-your-pocket/what-is-github-spec-kit-bye-bye-vibe-coding-37efbaa32880)
+- **Kento IKEDA** (DEV Community / AWS Builders, May 2) examined the emerging three-layer pattern for AI agent instructions (AGENTS.md, SKILL.md, DESIGN.md), referencing Spec Kit's approach. [\[dev.to\]](https://dev.to/aws-builders/agentsmd-skillmd-designmd-how-ai-instructions-split-into-three-layers-d0g)
+- **PyShine** (May 13) published a detailed guide covering the 6-step workflow, 30+ integrations, and 60+ extensions. [\[pyshine.com\]](https://pyshine.com/GitHub-Spec-Kit-Spec-Driven-Development/)
+- **DeployHQ** (Alex M, May 13) examined the "deployment gap" — Spec Kit ends at code, Workspaces ends at PR — and showed how to wire DeployHQ into the post-merge step. [\[deployhq.com\]](https://www.deployhq.com/blog/spec-kit-copilot-workspaces-deployment)
+- **spec-coding.dev** (May 11) examined five practical SDD patterns shared by OpenSpec, Superpowers, and Spec Kit. [\[spec-coding.dev\]](https://spec-coding.dev/blog/spec-driven-development-tools-openspec-spec-kit-superpowers)
+- **kiadev.net** (Ignaty Kashnitsky, May 9) published two articles: a detailed technical protocol and a 9-tool comparison recommending Spec Kit as a "portable, community-driven starting point." [\[kiadev.net\]](https://www.kiadev.net/news/2026-05-09-github-spec-kit-sdd-toolkit)
+
+Coverage also appeared on WinBuzzer, Let's Data Science, Openflows, AI in Plain English (Medium), Artiverse, KnightLi Blog (multilingual EN/CN/JP/ES), and fundesk.io.
+
+### Community Growth by the Numbers
+
+| Metric | Start of May | End of May | Change |
+| --- | --- | --- | --- |
+| GitHub stars | 92,038 | 106,951 | +14,913 (+16%) |
+| Forks | ~8,000 | 9,464 | +~1,500 |
+| Contributors | — | 217 | — |
+| Releases (total) | 135 | 152 | +17 (incl. 3 late-April) |
+| Community extensions | 92 | 105 | +13 |
+| Community presets | 18 | 21 | +3 |
+| Discussions (open) | ~400 | 422 | +~22 |
+
+## SDD Ecosystem & Industry Trends
+
+### The Analyst View
+
+The Futurum Group's **Mitch Ashley** provided the most significant analyst framing of SDD to date on DevOps.com: "GitHub's Spec Kit signals AI-assisted coding is shifting from prompts to durable, versioned specifications. Vendors are competing to own the artifact that governs intent across Copilot, Claude Code, and Gemini CLI." He warned that "verification at each checkpoint cannot be deferred to the agent producing it" — echoing the project's own emphasis on human oversight at phase boundaries. [\[devops.com\]](https://devops.com/githubs-spec-kit-puts-the-spec-back-in-software-development/)
+
+### The Production Playbook Pattern
+
+**Truong Phung's** 61-minute production playbook represented a new level of depth in community content. Rather than reviewing Spec Kit as a tool, Phung treated SDD as a given and built a comprehensive guide around the **Spec → Plan → Code → Verify loop**, with Spec Kit and Superpowers as the reference implementations. His seven opening truths — "the bottleneck moved from typing to thinking," "context engineering > prompt engineering," and "the PR is the unit of work, not the ticket" — capture the emerging practitioner consensus around structured AI development. [\[dev.to\]](https://dev.to/truongpx396/building-production-grade-fullstack-products-with-ai-coding-agents-a-practical-playbook-2idd)
+
+### Competitive Landscape
+
+The **MarkTechPost comparison** of nine SDD tools called Spec Kit "the most community-adopted open-source option," while positioning competitors along distinct axes: **Kiro** (integrated IDE with EARS-based specs and agent hooks), **BMAD-METHOD** (~48K stars, 12+ specialized agents), **GSD** (~64K stars, lean meta-prompting), **Augment Code** (context engine for 400K+ files, not a spec authoring tool), **OpenSpec** (~52K stars, change accountability and audit trails), and **Tessl** (spec registry with 10K+ library specs). [\[marktechpost.com\]](https://www.marktechpost.com/2026/05/08/9-best-ai-tools-for-spec-driven-development-in-2026-kiro-bmad-gsd-and-more-compare/)
+
+With 107K stars at month's end, Spec Kit is the **only spec-driven development tool in the top 100 most-starred repositories on GitHub** — none of the competitors above are close to the 100K threshold. The broader top-100 list includes AI-adjacent projects like agentic skills frameworks (obra/superpowers at 212K, anthropics/skills at 143K), agent harness tools, and LLM inference engines, but Spec Kit is the only one built around a spec-first development workflow. [\[github.com\]](https://github.com/search?q=stars%3A%3E100000&type=repositories&s=stars&o=desc)
+
+## Roadmap
+
+Areas under discussion or in progress for future development:
+
+- **CLI architecture cleanup** — the `__init__.py` decomposition (4/8 complete) continues toward a modular command structure. This internal cleanup improves contributor onboarding and test isolation. [\[github.com\]](https://github.com/github/spec-kit/releases)
+- **Spec lifecycle management** — spec drift and context rot remain the most cited concern across articles (DevOps.com, DeployHQ, テックオーシャン). The clarify re-validation (#2715) and reconcile extensions are incremental steps; a more comprehensive solution is expected. [\[devops.com\]](https://devops.com/githubs-spec-kit-puts-the-spec-back-in-software-development/)
+- **Multi-agent workflows** — multi-install support (#2389) was the most-requested feature. The next frontier is orchestrating multiple agents across phases, a pattern the community's MAQA, Fleet, and Conduct extensions already explore. [\[github.com\]](https://github.com/github/spec-kit/releases)
+- **Catalog maturity** — catalog discovery CLI (v0.8.3), agentic submissions (v0.8.13), and GITHUB_TOKEN auth (v0.8.2) are building toward a package-manager experience. As the catalog grows past 100 entries, curation and quality signals become critical. [\[github.com\]](https://github.com/github/spec-kit/releases)
+- **Experience simplification** — the deployment gap (DeployHQ), ceremony overhead for small tasks (テックオーシャン, spec-coding.dev), and verbose output (Thoughtworks Radar) continue as open concerns. The lean preset, TinySpec extension, and workflow engine provide answers; discoverability of these options remains an opportunity. [\[deployhq.com\]](https://www.deployhq.com/blog/spec-kit-copilot-workspaces-deployment)
+- **Toward a stable release** — fourteen releases in one month reflects pre-1.0 momentum. The git extension default-off notice (#2432, gated at v0.10.0) and the `--no-git` deprecation (removal at v0.10.0) signal a path toward API stabilization. [\[github.com\]](https://github.com/github/spec-kit/releases)

presets/catalog.community.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-05-05T10:00:00Z",
+  "updated_at": "2026-06-03T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json",
   "presets": {
     "a11y-governance": {
@@ -34,11 +34,11 @@
     "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.",
+      "version": "0.2.0",
+      "description": "Keeps shared AI-agent guidance aligned and adds agent-neutral Spec Kit model-routing guidance across declared 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",
+      "download_url": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance/archive/refs/tags/v0.2.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",
@@ -46,18 +46,20 @@
         "speckit_version": ">=0.8.0"
       },
       "provides": {
-        "templates": 6,
+        "templates": 9,
         "commands": 3
       },
       "tags": [
         "agents",
         "governance",
         "parity",
+        "agent-md",
         "agent-guidance",
+        "model-routing",
         "multi-agent"
       ],
       "created_at": "2026-04-27T00:00:00Z",
-      "updated_at": "2026-04-27T00:00:00Z"
+      "updated_at": "2026-05-31T00:00:00Z"
     },
     "aide-in-place": {
       "name": "AIDE In-Place Migration",
@@ -222,11 +224,11 @@
     "fiction-book-writing": {
       "name": "Fiction Book Writing",
       "id": "fiction-book-writing",
-      "version": "1.7.0",
-      "description": "Spec-Driven Development for novel and long-form fiction. 27 AI commands from idea to submission: story bible governance, 9 POV modes, all major plot structure frameworks, scene-by-scene drafting with quality gates, audiobook pipeline (SSML/ElevenLabs), cover design, sensitivity review, pacing and prose statistics, and pandoc-based export to DOCX/EPUB/LaTeX. Two style modes: author voice sample extraction or humanized-AI prose with 5 craft profiles. 12 languages supported. Support for offline semantic search.",
+      "version": "1.8.1",
+      "description": "Spec-Driven Development for novel and long-form fiction. 33 AI commands from idea to submission: story bible governance, 9 POV modes, all major plot structure frameworks, scene-by-scene drafting with quality gates, audiobook pipeline (SSML/ElevenLabs), cover design, sensitivity review, pacing and prose statistics, and pandoc-based export to DOCX/EPUB/LaTeX. Two style modes: author voice sample extraction or humanized-AI prose with 5 craft profiles. 12 languages supported. Support for offline semantic search.",
       "author": "Andreas Daumann",
       "repository": "https://github.com/adaumann/speckit-preset-fiction-book-writing",
-      "download_url": "https://github.com/adaumann/speckit-preset-fiction-book-writing/archive/refs/tags/v1.7.0.zip",
+      "download_url": "https://github.com/adaumann/speckit-preset-fiction-book-writing/archive/refs/tags/v1.8.1.zip",
       "homepage": "https://github.com/adaumann/speckit-preset-fiction-book-writing",
       "documentation": "https://github.com/adaumann/speckit-preset-fiction-book-writing/blob/main/fiction-book-writing/README.md",
       "license": "MIT",
@@ -234,8 +236,8 @@
         "speckit_version": ">=0.5.0"
       },
       "provides": {
-        "templates": 22,
-        "commands": 27,
+        "templates": 25,
+        "commands": 33,
         "scripts": 2
       },
       "tags": [
@@ -254,7 +256,44 @@
         "language-support"
       ],
       "created_at": "2026-04-09T08:00:00Z",
-      "updated_at": "2026-04-27T08:00:00Z"
+      "updated_at": "2026-05-24T08: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",
@@ -435,11 +474,11 @@
     "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.",
+      "version": "0.4.0",
+      "description": "Adds memory-safe-language preference, language-specific secure coding profiles, ASVS verification, SBOM/AI-SBOM supply-chain transparency, and EU Cyber Resilience Act 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",
+      "download_url": "https://github.com/hindermath/spec-kit-preset-security-governance/archive/refs/tags/v0.4.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",
@@ -454,11 +493,28 @@
         "security",
         "governance",
         "msl",
+        "ssdf",
         "asvs",
-        "supply-chain"
+        "supply-chain",
+        "sbom",
+        "ai-sbom",
+        "vex",
+        "slsa",
+        "cwe-top-25",
+        "secure-coding",
+        "rust",
+        "go",
+        "swift",
+        "java",
+        "kotlin",
+        "python",
+        "typescript",
+        "g7",
+        "bsi",
+        "cra"
       ],
       "created_at": "2026-04-27T00:00:00Z",
-      "updated_at": "2026-04-27T00:00:00Z"
+      "updated_at": "2026-05-26T00:00:00Z"
     },
     "spec2cloud": {
       "name": "Spec2Cloud",
@@ -486,7 +542,7 @@
       ],
       "created_at": "2026-04-30T00:00:00Z",
       "updated_at": "2026-04-30T00:00:00Z"
-    }, 
+    },
     "toc-navigation": {
       "name": "Table of Contents Navigation",
       "id": "toc-navigation",
@@ -535,6 +591,34 @@
         "clarify",
         "interactive"
       ]
+    },
+    "workflow-preset": {
+      "name": "Workflow Preset",
+      "id": "workflow-preset",
+      "version": "1.3.2",
+      "description": "Behavior-first specification, design artifacts, and agent-native handoff orchestration.",
+      "author": "bigsmartben",
+      "repository": "https://github.com/bigsmartben/spec-kit-workflow-preset",
+      "download_url": "https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v1.3.2/spec-kit-workflow-preset-v1.3.2.zip",
+      "homepage": "https://github.com/bigsmartben/spec-kit-workflow-preset",
+      "documentation": "https://github.com/bigsmartben/spec-kit-workflow-preset/blob/main/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.10.dev0"
+      },
+      "provides": {
+        "templates": 22,
+        "commands": 8
+      },
+      "tags": [
+        "behavior",
+        "bdd",
+        "planning",
+        "implementation",
+        "handoff"
+      ],
+      "created_at": "2026-05-27T00:00:00Z",
+      "updated_at": "2026-06-03T00:00:00Z"
     }
   }
 }

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.8.8.dev0"
+version = "0.9.5.dev0"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [
@@ -40,6 +40,7 @@ packages = ["src/specify_cli"]
 "scripts/powershell" = "specify_cli/core_pack/scripts/powershell"
 # Bundled extensions (installable via `specify extension add <name>`)
 "extensions/git" = "specify_cli/core_pack/extensions/git"
+"extensions/agent-context" = "specify_cli/core_pack/extensions/agent-context"
 # Bundled workflows (auto-installed during `specify init`)
 "workflows/speckit" = "specify_cli/core_pack/workflows/speckit"
 # Bundled presets (installable via `specify preset add <name>` or `specify init --preset <name>`)

scripts/bash/check-prerequisites.sh

@@ -78,13 +78,12 @@ done
 SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/common.sh"
 
-# Get feature paths and validate branch
+# Get feature paths
 _paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
 eval "$_paths_output"
 unset _paths_output
-check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
 
-# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+# If paths-only mode, output paths and exit (no validation)
 if $PATHS_ONLY; then
     if $JSON_MODE; then
         # Minimal JSON paths payload (no validation performed)
@@ -112,23 +111,26 @@ if $PATHS_ONLY; then
     exit 0
 fi
 
+# Validate branch name
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
 # Validate required directories and files
 if [[ ! -d "$FEATURE_DIR" ]]; then
     echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
-    echo "Run /speckit.specify first to create the feature structure." >&2
+    echo "Run $(format_speckit_command specify "$REPO_ROOT") first to create the feature structure." >&2
     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
+    echo "Run $(format_speckit_command plan "$REPO_ROOT") first to create the implementation plan." >&2
     exit 1
 fi
 
 # Check for tasks.md if required
 if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
     echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
-    echo "Run /speckit.tasks first to create the task list." >&2
+    echo "Run $(format_speckit_command tasks "$REPO_ROOT") first to create the task list." >&2
     exit 1
 fi
 

scripts/bash/common.sh

@@ -186,7 +186,7 @@ read_feature_json_feature_directory() {
 }
 
 # Returns 0 when .specify/feature.json lists feature_directory that exists as a directory
-# and matches the resolved active FEATURE_DIR (so /speckit.plan can skip git branch pattern checks).
+# and matches the resolved active FEATURE_DIR (so __SPECKIT_COMMAND_PLAN__ can skip git branch pattern checks).
 # Delegates parsing to read_feature_json_feature_directory, which is safe under `set -e`.
 feature_json_matches_feature_dir() {
     local repo_root="$1"
@@ -262,7 +262,7 @@ get_feature_paths() {
 
     # Resolve feature directory.  Priority:
     #   1. SPECIFY_FEATURE_DIRECTORY env var (explicit override)
-    #   2. .specify/feature.json "feature_directory" key (persisted by /speckit.specify)
+    #   2. .specify/feature.json "feature_directory" key (persisted by __SPECKIT_COMMAND_SPECIFY__)
     #   3. Branch-name-based prefix lookup (legacy fallback)
     local feature_dir
     if [[ -n "${SPECIFY_FEATURE_DIRECTORY:-}" ]]; then
@@ -307,6 +307,83 @@ has_jq() {
     command -v jq >/dev/null 2>&1
 }
 
+get_invoke_separator() {
+    local repo_root="${1:-$(get_repo_root)}"
+    if [[ "${_SPECIFY_INVOKE_SEPARATOR_CACHE_REPO_ROOT:-}" == "$repo_root" && -n "${_SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE:-}" ]]; then
+        printf '%s\n' "$_SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE"
+        return 0
+    fi
+
+    local integration_json="$repo_root/.specify/integration.json"
+    local separator="."
+    local parsed_with_jq=0
+
+    if [[ -f "$integration_json" ]]; then
+        if command -v jq >/dev/null 2>&1; then
+            local jq_separator
+            if jq_separator=$(jq -r '(.default_integration // .integration // "") as $k | if $k == "" then "." else (.integration_settings[$k].invoke_separator // ".") end' "$integration_json" 2>/dev/null); then
+                parsed_with_jq=1
+                case "$jq_separator" in
+                    "."|"-") separator="$jq_separator" ;;
+                esac
+            fi
+        fi
+
+        if [[ "$parsed_with_jq" -eq 0 ]] && command -v python3 >/dev/null 2>&1; then
+            if separator=$(python3 - "$integration_json" <<'PY' 2>/dev/null
+import json
+import sys
+
+try:
+    with open(sys.argv[1], encoding="utf-8") as fh:
+        state = json.load(fh)
+    key = state.get("default_integration") or state.get("integration") or ""
+    settings = state.get("integration_settings")
+    separator = "."
+    if isinstance(key, str) and isinstance(settings, dict):
+        entry = settings.get(key)
+        if isinstance(entry, dict) and entry.get("invoke_separator") in {".", "-"}:
+            separator = entry["invoke_separator"]
+    print(separator)
+except Exception:
+    print(".")
+PY
+); then
+                case "$separator" in
+                    "."|"-") ;;
+                    *) separator="." ;;
+                esac
+            else
+                separator="."
+            fi
+        fi
+    fi
+
+    _SPECIFY_INVOKE_SEPARATOR_CACHE_REPO_ROOT="$repo_root"
+    _SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE="$separator"
+    printf '%s\n' "$separator"
+}
+
+format_speckit_command() {
+    local command_name="$1"
+    local repo_root="${2:-$(get_repo_root)}"
+    local separator
+    if [[ "${_SPECIFY_INVOKE_SEPARATOR_CACHE_REPO_ROOT:-}" == "$repo_root" && -n "${_SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE:-}" ]]; then
+        separator="$_SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE"
+    else
+        separator=$(get_invoke_separator "$repo_root")
+        _SPECIFY_INVOKE_SEPARATOR_CACHE_REPO_ROOT="$repo_root"
+        _SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE="$separator"
+    fi
+
+    command_name="${command_name#/}"
+    command_name="${command_name#speckit.}"
+    command_name="${command_name#speckit-}"
+    command_name="${command_name//./$separator}"
+
+    printf '/speckit%s%s\n' "$separator" "$command_name"
+}
+
 # Escape a string for safe embedding in a JSON value (fallback when jq is unavailable).
 # Handles backslash, double-quote, and JSON-required control character escapes (RFC 8259).
 json_escape() {
@@ -642,4 +719,3 @@ except Exception:
     printf '%s' "$content"
     return 0
 }
-

scripts/bash/setup-plan.sh

@@ -40,15 +40,31 @@ fi
 # Ensure the feature directory exists
 mkdir -p "$FEATURE_DIR"
 
-# Copy plan template if it exists
-TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT") || true
-if [[ -n "$TEMPLATE" ]] && [[ -f "$TEMPLATE" ]]; then
-    cp "$TEMPLATE" "$IMPL_PLAN"
-    echo "Copied plan template to $IMPL_PLAN"
+# Copy plan template if plan doesn't already exist
+if [[ -f "$IMPL_PLAN" ]]; then
+    if $JSON_MODE; then
+        echo "Plan already exists at $IMPL_PLAN, skipping template copy" >&2
+    else
+        echo "Plan already exists at $IMPL_PLAN, skipping template copy"
+    fi
 else
-    echo "Warning: Plan template not found"
-    # Create a basic plan file if template doesn't exist
-    touch "$IMPL_PLAN"
+    TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT") || true
+    if [[ -n "$TEMPLATE" ]] && [[ -f "$TEMPLATE" ]]; then
+        cp "$TEMPLATE" "$IMPL_PLAN"
+        if $JSON_MODE; then
+            echo "Copied plan template to $IMPL_PLAN" >&2
+        else
+            echo "Copied plan template to $IMPL_PLAN"
+        fi
+    else
+        if $JSON_MODE; then
+            echo "Warning: Plan template not found" >&2
+        else
+            echo "Warning: Plan template not found"
+        fi
+        # Create a basic plan file if template doesn't exist
+        touch "$IMPL_PLAN"
+    fi
 fi
 
 # Output results

scripts/bash/setup-tasks.sh

@@ -35,13 +35,13 @@ 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
+    echo "Run $(format_speckit_command plan "$REPO_ROOT") 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
+    echo "Run $(format_speckit_command specify "$REPO_ROOT") first to create the feature structure." >&2
     exit 1
 fi
 

scripts/powershell/check-prerequisites.ps1

@@ -56,14 +56,10 @@ EXAMPLES:
 # Source common functions
 . "$PSScriptRoot/common.ps1"
 
-# Get feature paths and validate branch
+# Get feature paths
 $paths = Get-FeaturePathsEnv
 
-if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GIT)) { 
-    exit 1 
-}
-
-# If paths-only mode, output paths and exit (support combined -Json -PathsOnly)
+# If paths-only mode, output paths and exit (no validation)
 if ($PathsOnly) {
     if ($Json) {
         [PSCustomObject]@{
@@ -85,23 +81,31 @@ if ($PathsOnly) {
     exit 0
 }
 
+# Validate branch name
+if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GIT)) {
+    exit 1
+}
+
 # Validate required directories and files
 if (-not (Test-Path $paths.FEATURE_DIR -PathType Container)) {
     Write-Output "ERROR: Feature directory not found: $($paths.FEATURE_DIR)"
-    Write-Output "Run /speckit.specify first to create the feature structure."
+    $specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
+    Write-Output "Run $specifyCommand first to create the feature structure."
     exit 1
 }
 
 if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) {
     Write-Output "ERROR: plan.md not found in $($paths.FEATURE_DIR)"
-    Write-Output "Run /speckit.plan first to create the implementation plan."
+    $planCommand = Format-SpecKitCommand -CommandName 'plan' -RepoRoot $paths.REPO_ROOT
+    Write-Output "Run $planCommand first to create the implementation plan."
     exit 1
 }
 
 # Check for tasks.md if required
 if ($RequireTasks -and -not (Test-Path $paths.TASKS -PathType Leaf)) {
     Write-Output "ERROR: tasks.md not found in $($paths.FEATURE_DIR)"
-    Write-Output "Run /speckit.tasks first to create the task list."
+    $tasksCommand = Format-SpecKitCommand -CommandName 'tasks' -RepoRoot $paths.REPO_ROOT
+    Write-Output "Run $tasksCommand first to create the task list."
     exit 1
 }
 

scripts/powershell/common.ps1

@@ -165,7 +165,7 @@ function Test-FeatureBranch {
 }
 
 # True when .specify/feature.json pins an existing feature directory that matches the
-# active FEATURE_DIR from Get-FeaturePathsEnv (so /speckit.plan can skip git branch pattern checks).
+# active FEATURE_DIR from Get-FeaturePathsEnv (so __SPECKIT_COMMAND_PLAN__ can skip git branch pattern checks).
 function Test-FeatureJsonMatchesFeatureDir {
     param(
         [Parameter(Mandatory = $true)][string]$RepoRoot,
@@ -288,7 +288,7 @@ function Get-FeaturePathsEnv {
 
     # Resolve feature directory.  Priority:
     #   1. SPECIFY_FEATURE_DIRECTORY env var (explicit override)
-    #   2. .specify/feature.json "feature_directory" key (persisted by /speckit.specify)
+    #   2. .specify/feature.json "feature_directory" key (persisted by __SPECKIT_COMMAND_SPECIFY__)
     #   3. Branch-name-based prefix lookup (same as scripts/bash/common.sh)
     $featureJson = Join-Path $repoRoot '.specify/feature.json'
     if ($env:SPECIFY_FEATURE_DIRECTORY) {
@@ -336,10 +336,10 @@ function Get-FeaturePathsEnv {
 function Test-FileExists {
     param([string]$Path, [string]$Description)
     if (Test-Path -Path $Path -PathType Leaf) {
-        Write-Output "  ✓ $Description"
+        Write-Output "  [OK] $Description"
         return $true
     } else {
-        Write-Output "  ✗ $Description"
+        Write-Output "  [FAIL] $Description"
         return $false
     }
 }
@@ -347,14 +347,66 @@ function Test-FileExists {
 function Test-DirHasFiles {
     param([string]$Path, [string]$Description)
     if ((Test-Path -Path $Path -PathType Container) -and (Get-ChildItem -Path $Path -ErrorAction SilentlyContinue | Where-Object { -not $_.PSIsContainer } | Select-Object -First 1)) {
-        Write-Output "  ✓ $Description"
+        Write-Output "  [OK] $Description"
         return $true
     } else {
-        Write-Output "  ✗ $Description"
+        Write-Output "  [FAIL] $Description"
         return $false
     }
 }
 
+function Get-InvokeSeparator {
+    param([string]$RepoRoot = (Get-RepoRoot))
+
+    if ($null -eq $script:SpecKitInvokeSeparatorCache) {
+        $script:SpecKitInvokeSeparatorCache = @{}
+    }
+    if ($script:SpecKitInvokeSeparatorCache.ContainsKey($RepoRoot)) {
+        return $script:SpecKitInvokeSeparatorCache[$RepoRoot]
+    }
+
+    $separator = '.'
+    $integrationJson = Join-Path $RepoRoot '.specify/integration.json'
+    if (Test-Path -LiteralPath $integrationJson -PathType Leaf) {
+        try {
+            $state = Get-Content -LiteralPath $integrationJson -Raw | ConvertFrom-Json
+            $key = if ($state.default_integration) { [string]$state.default_integration } elseif ($state.integration) { [string]$state.integration } else { '' }
+            if ($key -and $state.integration_settings) {
+                $settingProperty = $state.integration_settings.PSObject.Properties[$key]
+                if ($settingProperty) {
+                    $setting = $settingProperty.Value
+                    if ($setting -and ($setting.invoke_separator -eq '.' -or $setting.invoke_separator -eq '-')) {
+                        $separator = [string]$setting.invoke_separator
+                    }
+                }
+            }
+        } catch {
+            $separator = '.'
+        }
+    }
+
+    $script:SpecKitInvokeSeparatorCache[$RepoRoot] = $separator
+    return $separator
+}
+
+function Format-SpecKitCommand {
+    param(
+        [Parameter(Mandatory = $true)][string]$CommandName,
+        [string]$RepoRoot = (Get-RepoRoot)
+    )
+
+    $separator = Get-InvokeSeparator -RepoRoot $RepoRoot
+    $name = $CommandName.TrimStart('/')
+    if ($name.StartsWith('speckit.')) {
+        $name = $name.Substring(8)
+    } elseif ($name.StartsWith('speckit-')) {
+        $name = $name.Substring(8)
+    }
+    $name = $name -replace '\.', $separator
+
+    return "/speckit$separator$name"
+}
+
 # Find a usable Python 3 executable (python3, python, or py -3).
 # Returns the command/arguments as an array, or $null if none found.
 function Get-Python3Command {
@@ -591,7 +643,7 @@ except Exception:
 
     if ($layerPaths.Count -eq 0) { return $null }
 
-    # If the top (highest-priority) layer is replace, it wins entirely —
+    # If the top (highest-priority) layer is replace, it wins entirely --
     # lower layers are irrelevant regardless of their strategies.
     if ($layerStrategies[0] -eq 'replace') {
         return (Get-Content $layerPaths[0] -Raw)
@@ -640,4 +692,4 @@ except Exception:
     }
 
     return $content
-}
+}

scripts/powershell/create-new-feature.ps1

@@ -312,7 +312,7 @@ if (-not $DryRun) {
                 if ($AllowExistingBranch) {
                     # If we're already on the branch, continue without another checkout.
                     if ($currentBranch -eq $branchName) {
-                        # Already on the target branch — nothing to do
+                        # Already on the target branch -- nothing to do
                     } else {
                         # Otherwise switch to the existing branch instead of failing.
                         $switchBranchError = git checkout -q $branchName 2>&1 | Out-String
@@ -350,7 +350,10 @@ if (-not $DryRun) {
     if (-not (Test-Path -PathType Leaf $specFile)) {
         $template = Resolve-Template -TemplateName 'spec-template' -RepoRoot $repoRoot
         if ($template -and (Test-Path $template)) {
-            Copy-Item $template $specFile -Force
+            # Read the template content and write it to the spec file with UTF-8 encoding without BOM
+            $content = [System.IO.File]::ReadAllText($template)
+            $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+            [System.IO.File]::WriteAllText($specFile, $content, $utf8NoBom)
         } else {
             New-Item -ItemType File -Path $specFile -Force | Out-Null
         }

scripts/powershell/setup-plan.ps1

@@ -33,15 +33,25 @@ if (-not (Test-FeatureJsonMatchesFeatureDir -RepoRoot $paths.REPO_ROOT -ActiveFe
 # Ensure the feature directory exists
 New-Item -ItemType Directory -Path $paths.FEATURE_DIR -Force | Out-Null
 
-# Copy plan template if it exists, otherwise note it or create empty file
-$template = Resolve-Template -TemplateName 'plan-template' -RepoRoot $paths.REPO_ROOT
-if ($template -and (Test-Path $template)) { 
-    Copy-Item $template $paths.IMPL_PLAN -Force
-    Write-Output "Copied plan template to $($paths.IMPL_PLAN)"
+# Copy plan template if plan doesn't already exist
+if (Test-Path $paths.IMPL_PLAN -PathType Leaf) {
+    if ($Json) {
+        [Console]::Error.WriteLine("Plan already exists at $($paths.IMPL_PLAN), skipping template copy")
+    } else {
+        Write-Output "Plan already exists at $($paths.IMPL_PLAN), skipping template copy"
+    }
 } else {
-    Write-Warning "Plan template not found"
-    # Create a basic plan file if template doesn't exist
-    New-Item -ItemType File -Path $paths.IMPL_PLAN -Force | Out-Null
+    $template = Resolve-Template -TemplateName 'plan-template' -RepoRoot $paths.REPO_ROOT
+    if ($template -and (Test-Path $template)) {
+        # Read the template content and write it to the implementation plan file with UTF-8 encoding without BOM
+        $content = [System.IO.File]::ReadAllText($template)
+        $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+        [System.IO.File]::WriteAllText($paths.IMPL_PLAN, $content, $utf8NoBom)
+    } else {
+        Write-Warning "Plan template not found"
+        # Create a basic plan file if template doesn't exist
+        New-Item -ItemType File -Path $paths.IMPL_PLAN -Force | Out-Null
+    }
 }
 
 # Output results

scripts/powershell/setup-tasks.ps1

@@ -28,13 +28,15 @@ if (-not (Test-FeatureJsonMatchesFeatureDir -RepoRoot $paths.REPO_ROOT -ActiveFe
 
 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.")
+    $planCommand = Format-SpecKitCommand -CommandName 'plan' -RepoRoot $paths.REPO_ROOT
+    [Console]::Error.WriteLine("Run $planCommand 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.")
+    $specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
+    [Console]::Error.WriteLine("Run $specifyCommand first to create the feature structure.")
     exit 1
 }
 

src/specify_cli/_agent_config.py

@@ -0,0 +1,45 @@
+"""Agent configuration constants derived from the integration registry."""
+from __future__ import annotations
+
+from typing import Any
+
+
+def _build_agent_config() -> dict[str, dict[str, Any]]:
+    from .integrations import INTEGRATION_REGISTRY
+    config: dict[str, dict[str, Any]] = {}
+    for key, integration in INTEGRATION_REGISTRY.items():
+        if integration.config:
+            config[key] = dict(integration.config)
+    return config
+
+
+AGENT_CONFIG: dict[str, dict[str, Any]] = _build_agent_config()
+
+DEFAULT_INIT_INTEGRATION = "copilot"
+
+AI_ASSISTANT_ALIASES: dict[str, str] = {
+    "kiro": "kiro-cli",
+}
+
+
+def _build_ai_assistant_help() -> str:
+    non_generic_agents = sorted(agent for agent in AGENT_CONFIG if agent != "generic")
+    base_help = (
+        f"AI assistant to use: {', '.join(non_generic_agents)}, "
+        "or generic (requires --ai-commands-dir)."
+    )
+    if not AI_ASSISTANT_ALIASES:
+        return base_help
+    alias_phrases = []
+    for alias, target in sorted(AI_ASSISTANT_ALIASES.items()):
+        alias_phrases.append(f"'{alias}' as an alias for '{target}'")
+    if len(alias_phrases) == 1:
+        aliases_text = alias_phrases[0]
+    else:
+        aliases_text = ", ".join(alias_phrases[:-1]) + " and " + alias_phrases[-1]
+    return base_help + " Use " + aliases_text + "."
+
+
+AI_ASSISTANT_HELP: str = _build_ai_assistant_help()
+
+SCRIPT_TYPE_CHOICES: dict[str, str] = {"sh": "POSIX Shell (bash/zsh)", "ps": "PowerShell"}

src/specify_cli/_assets.py

@@ -0,0 +1,121 @@
+"""Bundle path resolution and version lookup for specify_cli.
+
+Stdlib-only; zero internal imports so it sits at the base of the dependency
+graph without risk of circular imports.
+"""
+from __future__ import annotations
+
+import importlib.metadata
+import re
+from pathlib import Path
+
+
+def _locate_core_pack() -> Path | None:
+    """Return the filesystem path to the bundled core_pack directory, or None.
+
+    Only present in wheel installs: hatchling's force-include copies
+    templates/, scripts/ etc. into specify_cli/core_pack/ at build time.
+
+    Source-checkout and editable installs do NOT have this directory.
+    Callers that need to work in both environments must check the repo-root
+    trees (templates/, scripts/) as a fallback when this returns None.
+    """
+    # Wheel install: core_pack is a sibling directory of this file
+    candidate = Path(__file__).parent / "core_pack"
+    if candidate.is_dir():
+        return candidate
+    return None
+
+
+def _repo_root() -> Path:
+    """Return the source checkout root used for editable installs."""
+    return Path(__file__).parent.parent.parent
+
+
+def _locate_bundled_extension(extension_id: str) -> Path | None:
+    """Return the path to a bundled extension, or None.
+
+    Checks the wheel's core_pack first, then falls back to the
+    source-checkout ``extensions/<id>/`` directory.
+    """
+    if not re.match(r'^[a-z0-9-]+$', extension_id):
+        return None
+
+    core = _locate_core_pack()
+    if core is not None:
+        candidate = core / "extensions" / extension_id
+        if (candidate / "extension.yml").is_file():
+            return candidate
+
+    # Source-checkout / editable install: look relative to repo root
+    candidate = _repo_root() / "extensions" / extension_id
+    if (candidate / "extension.yml").is_file():
+        return candidate
+
+    return None
+
+
+def _locate_bundled_workflow(workflow_id: str) -> Path | None:
+    """Return the path to a bundled workflow directory, or None.
+
+    Checks the wheel's core_pack first, then falls back to the
+    source-checkout ``workflows/<id>/`` directory.
+    """
+    if not re.match(r'^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$', workflow_id):
+        return None
+
+    core = _locate_core_pack()
+    if core is not None:
+        candidate = core / "workflows" / workflow_id
+        if (candidate / "workflow.yml").is_file():
+            return candidate
+
+    # Source-checkout / editable install: look relative to repo root
+    candidate = _repo_root() / "workflows" / workflow_id
+    if (candidate / "workflow.yml").is_file():
+        return candidate
+
+    return None
+
+
+def _locate_bundled_preset(preset_id: str) -> Path | None:
+    """Return the path to a bundled preset, or None.
+
+    Checks the wheel's core_pack first, then falls back to the
+    source-checkout ``presets/<id>/`` directory.
+    """
+    if not re.match(r'^[a-z0-9-]+$', preset_id):
+        return None
+
+    core = _locate_core_pack()
+    if core is not None:
+        candidate = core / "presets" / preset_id
+        if (candidate / "preset.yml").is_file():
+            return candidate
+
+    # Source-checkout / editable install: look relative to repo root
+    candidate = _repo_root() / "presets" / preset_id
+    if (candidate / "preset.yml").is_file():
+        return candidate
+
+    return None
+
+
+def get_speckit_version() -> str:
+    """Get current spec-kit version."""
+    try:
+        return importlib.metadata.version("specify-cli")
+    except Exception:
+        # Fallback: try reading from pyproject.toml
+        try:
+            import tomllib
+            pyproject_path = _repo_root() / "pyproject.toml"
+            if pyproject_path.exists():
+                with open(pyproject_path, "rb") as f:
+                    data = tomllib.load(f)
+                    return data.get("project", {}).get("version", "unknown")
+        except Exception:
+            # Intentionally ignore any errors while reading/parsing pyproject.toml.
+            # If this lookup fails for any reason, we fall back to returning "unknown" below.
+            pass
+    return "unknown"

src/specify_cli/_console.py

@@ -0,0 +1,245 @@
+"""Base Rich/Typer console layer for the specify CLI.
+
+This module is the single source of Rich ``Console`` instances and Typer UI
+helpers used throughout ``specify_cli``.  Nothing in this file should import
+from other ``specify_cli`` sub-modules; all dependencies must flow *into* this
+layer, not out of it, to avoid circular imports.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import readchar
+import typer
+from rich.align import Align
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich.tree import Tree
+from typer.core import TyperGroup
+
+BANNER = """
+███████╗██████╗ ███████╗ ██████╗██╗███████╗██╗   ██╗
+██╔════╝██╔══██╗██╔════╝██╔════╝██║██╔════╝╚██╗ ██╔╝
+███████╗██████╔╝█████╗  ██║     ██║█████╗   ╚████╔╝
+╚════██║██╔═══╝ ██╔══╝  ██║     ██║██╔══╝    ╚██╔╝
+███████║██║     ███████╗╚██████╗██║██║        ██║
+╚══════╝╚═╝     ╚══════╝ ╚═════╝╚═╝╚═╝        ╚═╝
+"""
+
+TAGLINE = "GitHub Spec Kit - Spec-Driven Development Toolkit"
+
+console = Console(highlight=False)
+
+class StepTracker:
+    """Track and render hierarchical steps without emojis, similar to Claude Code tree output.
+    Supports live auto-refresh via an attached refresh callback.
+    """
+    def __init__(self, title: str):
+        self.title = title
+        self.steps = []  # list of dicts: {key, label, status, detail}
+        self.status_order = {"pending": 0, "running": 1, "done": 2, "error": 3, "skipped": 4}
+        self._refresh_cb: Callable[[], None] | None = None
+
+    def attach_refresh(self, cb: Callable[[], None]) -> None:
+        self._refresh_cb = cb
+
+    def add(self, key: str, label: str):
+        if key not in [s["key"] for s in self.steps]:
+            self.steps.append({"key": key, "label": label, "status": "pending", "detail": ""})
+            self._maybe_refresh()
+
+    def start(self, key: str, detail: str = ""):
+        self._update(key, status="running", detail=detail)
+
+    def complete(self, key: str, detail: str = ""):
+        self._update(key, status="done", detail=detail)
+
+    def error(self, key: str, detail: str = ""):
+        self._update(key, status="error", detail=detail)
+
+    def skip(self, key: str, detail: str = ""):
+        self._update(key, status="skipped", detail=detail)
+
+    def _update(self, key: str, status: str, detail: str):
+        for s in self.steps:
+            if s["key"] == key:
+                s["status"] = status
+                if detail:
+                    s["detail"] = detail
+                self._maybe_refresh()
+                return
+
+        self.steps.append({"key": key, "label": key, "status": status, "detail": detail})
+        self._maybe_refresh()
+
+    def _maybe_refresh(self):
+        if self._refresh_cb:
+            try:
+                self._refresh_cb()
+            except Exception:
+                pass
+
+    def render(self):
+        tree = Tree(f"[cyan]{self.title}[/cyan]", guide_style="grey50")
+        for step in self.steps:
+            label = step["label"]
+            detail_text = step["detail"].strip() if step["detail"] else ""
+
+            status = step["status"]
+            if status == "done":
+                symbol = "[green]●[/green]"
+            elif status == "pending":
+                symbol = "[green dim]○[/green dim]"
+            elif status == "running":
+                symbol = "[cyan]○[/cyan]"
+            elif status == "error":
+                symbol = "[red]●[/red]"
+            elif status == "skipped":
+                symbol = "[yellow]○[/yellow]"
+            else:
+                symbol = " "
+
+            if status == "pending":
+                # Entire line light gray (pending)
+                if detail_text:
+                    line = f"{symbol} [bright_black]{label} ({detail_text})[/bright_black]"
+                else:
+                    line = f"{symbol} [bright_black]{label}[/bright_black]"
+            else:
+                # Label white, detail (if any) light gray in parentheses
+                if detail_text:
+                    line = f"{symbol} [white]{label}[/white] [bright_black]({detail_text})[/bright_black]"
+                else:
+                    line = f"{symbol} [white]{label}[/white]"
+
+            tree.add(line)
+        return tree
+
+
+def get_key():
+    """Get a single keypress in a cross-platform way using readchar."""
+    key = readchar.readkey()
+
+    if key == readchar.key.UP or key == readchar.key.CTRL_P:
+        return 'up'
+    if key == readchar.key.DOWN or key == readchar.key.CTRL_N:
+        return 'down'
+
+    if key == readchar.key.ENTER:
+        return 'enter'
+
+    if key == readchar.key.ESC:
+        return 'escape'
+
+    if key == readchar.key.CTRL_C:
+        raise KeyboardInterrupt
+
+    return key
+
+def select_with_arrows(
+    options: dict[str, str],
+    prompt_text: str = "Select an option",
+    default_key: str | None = None,
+) -> str:
+    """
+    Interactive selection using arrow keys with Rich Live display.
+
+    Args:
+        options: Dict with keys as option keys and values as descriptions
+        prompt_text: Text to show above the options
+        default_key: Default option key to start with
+
+    Returns:
+        Selected option key
+    """
+    if not options:
+        raise ValueError("select_with_arrows() requires at least one option.")
+
+    option_keys = list(options.keys())
+    if default_key and default_key in option_keys:
+        selected_index = option_keys.index(default_key)
+    else:
+        selected_index = 0
+
+    selected_key = None
+
+    def create_selection_panel():
+        """Create the selection panel with current selection highlighted."""
+        table = Table.grid(padding=(0, 2))
+        table.add_column(style="cyan", justify="left", width=3)
+        table.add_column(style="white", justify="left")
+
+        for i, key in enumerate(option_keys):
+            if i == selected_index:
+                table.add_row("▶", f"[cyan]{key}[/cyan] [dim]({options[key]})[/dim]")
+            else:
+                table.add_row(" ", f"[cyan]{key}[/cyan] [dim]({options[key]})[/dim]")
+
+        table.add_row("", "")
+        table.add_row("", "[dim]Use ↑/↓ to navigate, Enter to select, Esc to cancel[/dim]")
+
+        return Panel(
+            table,
+            title=f"[bold]{prompt_text}[/bold]",
+            border_style="cyan",
+            padding=(1, 2)
+        )
+
+    console.print()
+
+    def run_selection_loop():
+        nonlocal selected_key, selected_index
+        with Live(create_selection_panel(), console=console, transient=True, auto_refresh=False) as live:
+            while True:
+                try:
+                    key = get_key()
+                    if key == 'up':
+                        selected_index = (selected_index - 1) % len(option_keys)
+                    elif key == 'down':
+                        selected_index = (selected_index + 1) % len(option_keys)
+                    elif key == 'enter':
+                        selected_key = option_keys[selected_index]
+                        break
+                    elif key == 'escape':
+                        console.print("\n[yellow]Selection cancelled[/yellow]")
+                        raise typer.Exit(code=1)
+
+                    live.update(create_selection_panel(), refresh=True)
+
+                except KeyboardInterrupt:
+                    console.print("\n[yellow]Selection cancelled[/yellow]")
+                    raise typer.Exit(code=1)
+
+    run_selection_loop()
+
+    if selected_key is None:
+        console.print("\n[red]Selection failed.[/red]")
+        raise typer.Exit(code=1)
+
+    return selected_key
+
+class BannerGroup(TyperGroup):
+    """Custom group that shows banner before help."""
+
+    def format_help(self, ctx, formatter):
+        # Show banner before help
+        show_banner()
+        super().format_help(ctx, formatter)
+
+
+def show_banner():
+    """Display the ASCII art banner."""
+    banner_lines = BANNER.strip().split('\n')
+    colors = ["bright_blue", "blue", "cyan", "bright_cyan", "white", "bright_white"]
+
+    styled_banner = Text()
+    for i, line in enumerate(banner_lines):
+        color = colors[i % len(colors)]
+        styled_banner.append(line + "\n", style=color)
+
+    console.print(Align.center(styled_banner))
+    console.print(Align.center(Text(TAGLINE, style="italic bright_yellow")))
+    console.print()

src/specify_cli/_init_options.py

@@ -0,0 +1,36 @@
+"""Helpers for interpreting persisted init options."""
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+
+INIT_OPTIONS_FILE = ".specify/init-options.json"
+
+
+def save_init_options(project_path: Path, options: dict[str, Any]) -> None:
+    """Persist the CLI options used during ``specify init``."""
+    dest = project_path / INIT_OPTIONS_FILE
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(
+        json.dumps(options, indent=2, sort_keys=True, ensure_ascii=False),
+        encoding="utf-8",
+    )
+
+
+def load_init_options(project_path: Path) -> dict[str, Any]:
+    """Load persisted init options, returning an empty dict when unavailable."""
+    path = project_path / INIT_OPTIONS_FILE
+    if not path.exists():
+        return {}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError, UnicodeError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def is_ai_skills_enabled(opts: Mapping[str, Any] | None) -> bool:
+    """Return True only when init options explicitly enable AI skills."""
+    return isinstance(opts, Mapping) and opts.get("ai_skills") is True

src/specify_cli/_utils.py

@@ -0,0 +1,294 @@
+"""System utilities: subprocess, tool detection, file operations."""
+from __future__ import annotations
+
+import json
+import json5
+import os
+import shutil
+import stat
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+from ._console import console
+
+CLAUDE_LOCAL_PATH = Path.home() / ".claude" / "local" / "claude"
+CLAUDE_NPM_LOCAL_PATH = Path.home() / ".claude" / "local" / "node_modules" / ".bin" / "claude"
+
+
+def run_command(cmd: list[str], check_return: bool = True, capture: bool = False, shell: bool = False) -> str | None:
+    """Run a shell command and optionally capture output."""
+    try:
+        if capture:
+            result = subprocess.run(cmd, check=check_return, capture_output=True, text=True, shell=shell)
+            return result.stdout.strip()
+        else:
+            subprocess.run(cmd, check=check_return, shell=shell)
+            return None
+    except subprocess.CalledProcessError as e:
+        if check_return:
+            console.print(f"[red]Error running command:[/red] {' '.join(cmd)}")
+            console.print(f"[red]Exit code:[/red] {e.returncode}")
+            if hasattr(e, 'stderr') and e.stderr:
+                console.print(f"[red]Error output:[/red] {e.stderr}")
+            raise
+        return None
+
+
+def check_tool(tool: str, tracker=None) -> bool:
+    """Check if a tool is installed. Optionally update tracker.
+
+    For tools that correspond to a registered integration the check is
+    delegated to ``IntegrationBase.is_cli_available()`` so that each
+    integration can encode its own detection logic (e.g. multiple
+    binary names, non-PATH install locations).  Unknown tools fall back
+    to a plain ``shutil.which`` look-up.
+
+    Args:
+        tool: Name of the tool to check (typically an integration key)
+        tracker: StepTracker | None to update with results
+
+    Returns:
+        True if tool is found, False otherwise
+    """
+    found: bool
+
+    # Delegate to the integration's is_cli_available() when the tool
+    # key matches a registered integration.  This removes the need for
+    # hard-coded special cases here (e.g. Claude local paths, kiro dual
+    # binaries, rovodev/acli mismatch).  See issue #2597.
+    try:
+        from specify_cli.integrations import get_integration
+
+        impl = get_integration(tool)
+        if impl is not None:
+            found = impl.is_cli_available()
+            if tracker:
+                if found:
+                    tracker.complete(tool, "available")
+                else:
+                    tracker.error(tool, "not found")
+            return found
+    except ImportError as exc:
+        # Integrations module is unavailable in this environment; fall back
+        # to PATH-based detection below for non-integration tools.
+        _ = exc
+
+    # Fallback for non-integration tools (e.g. "git").
+    found = shutil.which(tool) is not None
+
+    if tracker:
+        if found:
+            tracker.complete(tool, "available")
+        else:
+            tracker.error(tool, "not found")
+
+    return found
+
+
+def is_git_repo(path: Path | None = None) -> bool:
+    """Check if the specified path is inside a git repository."""
+    if path is None:
+        path = Path.cwd()
+
+    if not path.is_dir():
+        return False
+
+    try:
+        subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            check=True,
+            capture_output=True,
+            cwd=path,
+        )
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+def init_git_repo(project_path: Path, quiet: bool = False) -> tuple[bool, str | None]:
+    """Initialize a git repository in the specified path."""
+    try:
+        original_cwd = Path.cwd()
+        os.chdir(project_path)
+        if not quiet:
+            console.print("[cyan]Initializing git repository...[/cyan]")
+        subprocess.run(["git", "init"], check=True, capture_output=True, text=True)
+        subprocess.run(["git", "add", "."], check=True, capture_output=True, text=True)
+        subprocess.run(["git", "commit", "-m", "Initial commit from Specify template"], check=True, capture_output=True, text=True)
+        if not quiet:
+            console.print("[green]✓[/green] Git repository initialized")
+        return True, None
+    except subprocess.CalledProcessError as e:
+        error_msg = f"Command: {' '.join(e.cmd)}\nExit code: {e.returncode}"
+        if e.stderr:
+            error_msg += f"\nError: {e.stderr.strip()}"
+        elif e.stdout:
+            error_msg += f"\nOutput: {e.stdout.strip()}"
+        if not quiet:
+            console.print(f"[red]Error initializing git repository:[/red] {e}")
+        return False, error_msg
+    finally:
+        os.chdir(original_cwd)
+
+
+def handle_vscode_settings(sub_item, dest_file, rel_path, verbose=False, tracker=None) -> None:
+    """Handle merging or copying of .vscode/settings.json files.
+
+    Note: when merge produces changes, rewritten output is normalized JSON and
+    existing JSONC comments/trailing commas are not preserved.
+    """
+    def log(message, color="green"):
+        if verbose and not tracker:
+            console.print(f"[{color}]{message}[/] {rel_path}")
+
+    def atomic_write_json(target_file: Path, payload: dict[str, Any]) -> None:
+        """Atomically write JSON while preserving existing mode bits when possible."""
+        temp_path: Path | None = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode='w',
+                encoding='utf-8',
+                dir=target_file.parent,
+                prefix=f"{target_file.name}.",
+                suffix=".tmp",
+                delete=False,
+            ) as f:
+                temp_path = Path(f.name)
+                json.dump(payload, f, indent=4)
+                f.write('\n')
+
+            if target_file.exists():
+                try:
+                    existing_stat = target_file.stat()
+                    os.chmod(temp_path, stat.S_IMODE(existing_stat.st_mode))
+                    if hasattr(os, "chown"):
+                        try:
+                            os.chown(temp_path, existing_stat.st_uid, existing_stat.st_gid)
+                        except PermissionError:
+                            # Best-effort owner/group preservation without requiring elevated privileges.
+                            pass
+                except OSError:
+                    # Best-effort metadata preservation; data safety is prioritized.
+                    pass
+
+            os.replace(temp_path, target_file)
+        except Exception:
+            if temp_path and temp_path.exists():
+                temp_path.unlink()
+            raise
+
+    try:
+        with open(sub_item, 'r', encoding='utf-8') as f:
+            # json5 natively supports comments and trailing commas (JSONC)
+            new_settings = json5.load(f)
+
+        if dest_file.exists():
+            merged = merge_json_files(dest_file, new_settings, verbose=verbose and not tracker)
+            if merged is not None:
+                atomic_write_json(dest_file, merged)
+                log("Merged:", "green")
+                log("Note: comments/trailing commas are normalized when rewritten", "yellow")
+            else:
+                log("Skipped merge (preserved existing settings)", "yellow")
+        else:
+            shutil.copy2(sub_item, dest_file)
+            log("Copied (no existing settings.json):", "blue")
+
+    except Exception as e:
+        log(f"Warning: Could not merge settings: {e}", "yellow")
+        if not dest_file.exists():
+            shutil.copy2(sub_item, dest_file)
+
+
+def merge_json_files(existing_path: Path, new_content: Any, verbose: bool = False) -> dict[str, Any] | None:
+    """Merge new JSON content into existing JSON file.
+
+    Performs a polite deep merge where:
+    - New keys are added
+    - Existing keys are preserved (not overwritten) unless both values are dictionaries
+    - Nested dictionaries are merged recursively only when both sides are dictionaries
+    - Lists and other values are preserved from base if they exist
+
+    Args:
+        existing_path: Path to existing JSON file
+        new_content: New JSON content to merge in
+        verbose: Whether to print merge details
+
+    Returns:
+        Merged JSON content as dict, or None if the existing file should be left untouched.
+    """
+    # Load existing content first to have a safe fallback
+    existing_content = None
+    exists = existing_path.exists()
+
+    if exists:
+        try:
+            with open(existing_path, 'r', encoding='utf-8') as f:
+                # Handle comments (JSONC) natively with json5
+                # Note: json5 handles BOM automatically
+                existing_content = json5.load(f)
+        except FileNotFoundError:
+            # Handle race condition where file is deleted after exists() check
+            exists = False
+        except Exception as e:
+            if verbose:
+                console.print(f"[yellow]Warning: Could not read or parse existing JSON in {existing_path.name} ({e}).[/yellow]")
+            # Skip merge to preserve existing file if unparseable or inaccessible (e.g. PermissionError)
+            return None
+
+    # Validate template content
+    if not isinstance(new_content, dict):
+        if verbose:
+            console.print(f"[yellow]Warning: Template content for {existing_path.name} is not a dictionary. Preserving existing settings.[/yellow]")
+        return None
+
+    if not exists:
+        return new_content
+
+    # If existing content parsed but is not a dict, skip merge to avoid data loss
+    if not isinstance(existing_content, dict):
+        if verbose:
+            console.print(f"[yellow]Warning: Existing JSON in {existing_path.name} is not an object. Skipping merge to avoid data loss.[/yellow]")
+        return None
+
+    def deep_merge_polite(base: dict[str, Any], update: dict[str, Any]) -> dict[str, Any]:
+        """Recursively merge update dict into base dict, preserving base values."""
+        result = base.copy()
+        for key, value in update.items():
+            if key not in result:
+                # Add new key
+                result[key] = value
+            elif isinstance(result[key], dict) and isinstance(value, dict):
+                # Recursively merge nested dictionaries
+                result[key] = deep_merge_polite(result[key], value)
+            else:
+                # Key already exists and values are not both dicts; preserve existing value.
+                # This ensures user settings aren't overwritten by template defaults.
+                pass
+        return result
+
+    merged = deep_merge_polite(existing_content, new_content)
+
+    # Detect if anything actually changed. If not, return None so the caller
+    # can skip rewriting the file (preserving user's comments/formatting).
+    if merged == existing_content:
+        return None
+
+    if verbose:
+        console.print(f"[cyan]Merged JSON file:[/cyan] {existing_path.name}")
+
+    return merged
+
+
+def _display_project_path(project_root: Path, path: str | Path) -> str:
+    """Return a stable POSIX-style display path for paths under a project."""
+    path_obj = Path(path)
+    try:
+        rel_path = path_obj.relative_to(project_root) if path_obj.is_absolute() else path_obj
+    except ValueError:
+        try:
+            rel_path = path_obj.resolve().relative_to(project_root.resolve())
+        except (OSError, ValueError):
+            return path_obj.as_posix()
+    return rel_path.as_posix()

src/specify_cli/agents.py

@@ -15,6 +15,8 @@ from typing import Any, Dict, List, Optional
 
 import yaml
 
+from ._init_options import is_ai_skills_enabled, load_init_options
+
 
 def _build_agent_configs() -> dict[str, Any]:
     """Derive CommandRegistrar.AGENT_CONFIGS from INTEGRATION_REGISTRY."""
@@ -67,6 +69,33 @@ class CommandRegistrar:
             except ImportError:
                 pass  # Circular import during module init; retry on next access
 
+    @staticmethod
+    def _hyphenate_frontmatter_refs(val: Any) -> Any:
+        """Recursively find any dotted references starting with speckit. and hyphenate them."""
+        if isinstance(val, dict):
+            return {
+                k: CommandRegistrar._hyphenate_frontmatter_refs(v)
+                for k, v in val.items()
+            }
+        elif isinstance(val, list):
+            return [CommandRegistrar._hyphenate_frontmatter_refs(x) for x in val]
+        elif isinstance(val, str):
+            return re.sub(
+                r"\bspeckit\.[A-Za-z0-9-_]+(?:\.[A-Za-z0-9-_]+)*\b",
+                lambda m: m.group(0).replace(".", "-"),
+                val,
+            )
+        return val
+
+    @staticmethod
+    def _hyphenate_body_refs(body: str) -> str:
+        """Hyphenate dotted speckit references in command body text."""
+        return re.sub(
+            r"\bspeckit\.[A-Za-z0-9-_]+(?:\.[A-Za-z0-9-_]+)*\b",
+            lambda m: m.group(0).replace(".", "-"),
+            body,
+        )
+
     @staticmethod
     def parse_frontmatter(content: str) -> tuple[dict, str]:
         """Parse YAML frontmatter from Markdown content.
@@ -332,11 +361,6 @@ class CommandRegistrar:
         agent_name: str, frontmatter: dict, body: str, project_root: Path
     ) -> str:
         """Resolve script placeholders for skills-backed agents."""
-        try:
-            from . import load_init_options
-        except ImportError:
-            return body
-
         if not isinstance(frontmatter, dict):
             frontmatter = {}
 
@@ -374,8 +398,15 @@ class CommandRegistrar:
 
         body = body.replace("{ARGS}", "$ARGUMENTS").replace("__AGENT__", agent_name)
 
-        # Resolve __CONTEXT_FILE__ from init-options
-        context_file = init_opts.get("context_file") or ""
+        # Resolve __CONTEXT_FILE__ from the agent-context extension config.
+        # Fall back to init-options.json for projects that haven't migrated.
+        # Local import: _load_agent_context_config lives in __init__.py which
+        # imports agents.py, so a top-level import would be circular.
+        from . import _load_agent_context_config
+        ac_cfg = _load_agent_context_config(project_root)
+        context_file = ac_cfg.get("context_file") or ""
+        if not context_file:
+            context_file = init_opts.get("context_file") or ""
         body = body.replace("__CONTEXT_FILE__", context_file)
 
         return CommandRegistrar.rewrite_project_relative_paths(body)
@@ -401,6 +432,9 @@ class CommandRegistrar:
     ) -> str:
         """Compute the on-disk command or skill name for an agent."""
         if agent_config["extension"] != "/SKILL.md":
+            format_name = agent_config.get("format_name")
+            if format_name:
+                return format_name(cmd_name)
             return cmd_name
 
         short_name = cmd_name
@@ -430,6 +464,36 @@ class CommandRegistrar:
         if not normalized.is_relative_to(base_normalized):
             raise ValueError(f"Output path {candidate!r} escapes directory {base!r}")
 
+    @staticmethod
+    def _is_safe_command_name(name: str) -> bool:
+        """Reject names that could escape the commands directory via path traversal."""
+        if os.path.sep in name or "/" in name or "\\" in name:
+            return False
+        return os.path.normpath(name) == name
+
+    @staticmethod
+    def _same_lexical_path(left: Path, right: Path) -> bool:
+        """Compare paths after lexical normalization without resolving symlinks."""
+        return os.path.normcase(os.path.normpath(os.fspath(left))) == os.path.normcase(
+            os.path.normpath(os.fspath(right))
+        )
+
+    @staticmethod
+    def _active_skills_agent(project_root: Path) -> Optional[str]:
+        """Return the initialized skills-backed agent, if skills mode is active."""
+        opts = load_init_options(project_root)
+        if not isinstance(opts, dict):
+            return None
+
+        agent = opts.get("ai")
+        if not isinstance(agent, str) or not agent:
+            return None
+        # Kimi is a native skills integration; when ai_skills is not boolean
+        # True, Kimi still uses its existing SKILL.md layout.
+        if not is_ai_skills_enabled(opts) and agent != "kimi":
+            return None
+        return agent
+
     def register_commands(
         self,
         agent_name: str,
@@ -438,6 +502,8 @@ class CommandRegistrar:
         source_dir: Path,
         project_root: Path,
         context_note: str = None,
+        _resolved_dir: Path = None,
+        link_outputs: bool = False,
     ) -> List[str]:
         """Register commands for a specific agent.
 
@@ -448,6 +514,13 @@ class CommandRegistrar:
             source_dir: Directory containing command source files
             project_root: Path to project root
             context_note: Custom context comment for markdown output
+            _resolved_dir: Pre-resolved command directory (internal use
+                only — avoids a second ``_resolve_agent_dir`` call and
+                duplicate deprecation warnings when invoked from
+                ``register_commands_for_all_agents``).
+            link_outputs: If True, write rendered output to a source-local
+                dev cache and symlink the agent command file to it. Falls back
+                to a normal file write when symlinks are unavailable.
 
         Returns:
             List of registered command names
@@ -460,13 +533,17 @@ class CommandRegistrar:
             raise ValueError(f"Unsupported agent: {agent_name}")
 
         agent_config = self.AGENT_CONFIGS[agent_name]
-        commands_dir = project_root / agent_config["dir"]
+        commands_dir = _resolved_dir or self._resolve_agent_dir(
+            agent_name, agent_config, project_root,
+        )
         commands_dir.mkdir(parents=True, exist_ok=True)
 
         registered = []
+        is_cline_ext = agent_name == "cline" and source_id != "core"
 
         for cmd_info in commands:
             cmd_name = cmd_info["name"]
+            aliases = cmd_info.get("aliases", [])
             cmd_file = cmd_info["file"]
 
             source_file = source_dir / cmd_file
@@ -498,6 +575,10 @@ class CommandRegistrar:
                 format_name = agent_config.get("format_name")
                 frontmatter["name"] = format_name(cmd_name) if format_name else cmd_name
 
+            if is_cline_ext:
+                frontmatter = self._hyphenate_frontmatter_refs(frontmatter)
+                body = self._hyphenate_body_refs(body)
+
             body = self._convert_argument_placeholder(
                 body, "$ARGUMENTS", agent_config["args"]
             )
@@ -552,14 +633,22 @@ class CommandRegistrar:
             dest_file = commands_dir / f"{output_name}{agent_config['extension']}"
             self._ensure_inside(dest_file, commands_dir)
             dest_file.parent.mkdir(parents=True, exist_ok=True)
-            dest_file.write_text(output, encoding="utf-8")
+            self._write_registered_output(
+                dest_file,
+                output,
+                source_dir,
+                agent_name,
+                output_name,
+                agent_config["extension"],
+                link_outputs,
+            )
 
             if agent_name == "copilot":
                 self.write_copilot_prompt(project_root, cmd_name)
 
             registered.append(cmd_name)
 
-            for alias in cmd_info.get("aliases", []):
+            for alias in aliases:
                 alias_output_name = self._compute_output_name(
                     agent_name, alias, agent_config
                 )
@@ -618,13 +707,56 @@ class CommandRegistrar:
                 )
                 self._ensure_inside(alias_file, commands_dir)
                 alias_file.parent.mkdir(parents=True, exist_ok=True)
-                alias_file.write_text(alias_output, encoding="utf-8")
+                self._write_registered_output(
+                    alias_file,
+                    alias_output,
+                    source_dir,
+                    agent_name,
+                    alias_output_name,
+                    agent_config["extension"],
+                    link_outputs,
+                )
                 if agent_name == "copilot":
                     self.write_copilot_prompt(project_root, alias)
                 registered.append(alias)
 
         return registered
 
+    @staticmethod
+    def _write_registered_output(
+        dest_file: Path,
+        content: str,
+        source_dir: Path,
+        agent_name: str,
+        output_name: str,
+        extension: str,
+        link_outputs: bool,
+    ) -> None:
+        """Write a rendered agent artifact, optionally as a dev-mode symlink."""
+        if not link_outputs:
+            dest_file.write_text(content, encoding="utf-8")
+            return
+
+        rel_output = Path(f"{output_name}{extension}")
+        cache_root = source_dir / ".specify-dev" / "agent-commands" / agent_name
+        cache_file = cache_root / rel_output
+        CommandRegistrar._ensure_inside(cache_file, cache_root)
+
+        try:
+            cache_file.parent.mkdir(parents=True, exist_ok=True)
+            cache_file.write_text(content, encoding="utf-8")
+            if dest_file.exists() or dest_file.is_symlink():
+                dest_file.unlink()
+            target = os.path.relpath(cache_file, dest_file.parent)
+            os.symlink(target, dest_file)
+        except (OSError, ValueError):
+            # Windows often requires Developer Mode or admin privileges for
+            # symlinks, and relpath can fail across drives. Keep dev installs
+            # functional by falling back to a copy.
+            if dest_file.is_symlink():
+                dest_file.unlink()
+            dest_file.write_text(content, encoding="utf-8")
+
     @staticmethod
     def write_copilot_prompt(project_root: Path, cmd_name: str) -> None:
         """Generate a companion .prompt.md file for a Copilot agent command.
@@ -639,6 +771,53 @@ class CommandRegistrar:
         CommandRegistrar._ensure_inside(prompt_file, prompts_dir)
         prompt_file.write_text(f"---\nagent: {cmd_name}\n---\n", encoding="utf-8")
 
+    @staticmethod
+    def _resolve_agent_dir(
+        agent_name: str,
+        agent_config: dict[str, Any],
+        project_root: Path,
+    ) -> Path:
+        """Return the agent command directory, falling back to legacy_dir.
+
+        Supports project-relative paths (e.g. ``.claude/skills/``),
+        home-relative paths (e.g. ``~/.hermes/skills``), and absolute
+        paths — the ``agent_config["dir"]`` value is resolved verbatim
+        when absolute or starting with ``~/``, or joined with
+        ``project_root`` when relative.
+
+        When the canonical directory does not exist but a ``legacy_dir``
+        is configured and present on disk, returns the legacy path and
+        emits a deprecation warning advising the user to upgrade.
+
+        Integrations that do not declare ``legacy_dir`` get the canonical
+        path unconditionally — no fallback, no warning.
+        """
+        dir_str = agent_config["dir"]
+        if dir_str.startswith("~"):
+            # Use Path.home() + remainder instead of expanduser() so tests
+            # that monkeypatch Path.home() can properly isolate the home dir.
+            # expanduser() uses OS env/user lookup and ignores monkeypatches.
+            agent_dir = Path.home() / dir_str[1:].lstrip("/")
+        else:
+            p = Path(dir_str)
+            agent_dir = p if p.is_absolute() else project_root / p
+        if not agent_dir.exists():
+            legacy = agent_config.get("legacy_dir")
+            if legacy:
+                legacy_dir = project_root / legacy
+                if legacy_dir.exists():
+                    import warnings
+
+                    warnings.warn(
+                        f"Found legacy '{legacy}' directory for "
+                        f"{agent_name}. Run 'specify integration "
+                        f"upgrade {agent_name}' to migrate to "
+                        f"'{agent_config['dir']}'.",
+                        stacklevel=3,
+                    )
+                    return legacy_dir
+        return agent_dir
+
     def register_commands_for_all_agents(
         self,
         commands: List[Dict[str, Any]],
@@ -646,6 +825,8 @@ class CommandRegistrar:
         source_dir: Path,
         project_root: Path,
         context_note: str = None,
+        link_outputs: bool = False,
+        create_missing_active_skills_dir: bool = False,
     ) -> Dict[str, List[str]]:
         """Register commands for all detected agents in the project.
 
@@ -655,6 +836,13 @@ class CommandRegistrar:
             source_dir: Directory containing command source files
             project_root: Path to project root
             context_note: Custom context comment for markdown output
+            link_outputs: If True, create dev-mode symlinks for rendered
+                command files when supported by the OS.
+            create_missing_active_skills_dir: If True, attempt missing-dir
+                recovery only for the active initialized skills-backed agent.
+                Recovery requires active skills mode (or Kimi's existing native
+                skills directory) and is skipped when safe resolution or
+                creation fails.
 
         Returns:
             Dictionary mapping agent names to list of registered commands
@@ -662,10 +850,73 @@ class CommandRegistrar:
         results = {}
 
         self._ensure_configs()
+        active_skills_agent = (
+            self._active_skills_agent(project_root)
+            if create_missing_active_skills_dir else None
+        )
+        active_created_skills_dir: Optional[Path] = None
         for agent_name, agent_config in self.AGENT_CONFIGS.items():
-            agent_dir = project_root / agent_config["dir"]
+            active_skills_output = (
+                agent_name == active_skills_agent
+                and agent_config.get("extension") == "/SKILL.md"
+            )
+            recovered_active_skills_dir: Optional[Path] = None
+            # Check detect_dir first (project-local marker) if configured,
+            # falling back to the resolved dir for output.  This prevents
+            # global dirs (e.g. ~/.hermes/skills) from causing false
+            # detection in every project.
+            detect_dir_str = agent_config.get("detect_dir")
+            if detect_dir_str:
+                detect_path = project_root / detect_dir_str
+                if not detect_path.is_dir():
+                    if not active_skills_output:
+                        continue
+                    try:
+                        from . import resolve_active_skills_dir
 
-            if agent_dir.exists():
+                        recovered_active_skills_dir = (
+                            resolve_active_skills_dir(project_root)
+                        )
+                    except (ValueError, OSError):
+                        continue
+                    if recovered_active_skills_dir is None or not detect_path.is_dir():
+                        continue
+                    active_created_skills_dir = recovered_active_skills_dir
+            agent_dir = self._resolve_agent_dir(
+                agent_name, agent_config, project_root,
+            )
+
+            agent_dir_existed = agent_dir.is_dir()
+            register_missing_active_skills_agent = (
+                not agent_dir_existed
+                and active_skills_output
+            )
+            if register_missing_active_skills_agent:
+                if recovered_active_skills_dir is None:
+                    try:
+                        from . import resolve_active_skills_dir
+
+                        recovered_active_skills_dir = (
+                            resolve_active_skills_dir(project_root)
+                        )
+                    except (ValueError, OSError):
+                        continue
+                    if recovered_active_skills_dir is None:
+                        continue
+                active_created_skills_dir = recovered_active_skills_dir
+            # Shared skill dirs such as .agents/skills should not make
+            # later integrations look detected when the active agent just
+            # recreated the directory during this registration pass.
+            created_by_active_agent = (
+                active_created_skills_dir is not None
+                and self._same_lexical_path(agent_dir, active_created_skills_dir)
+                and agent_name != active_skills_agent
+            )
+            should_register = (
+                agent_dir_existed and not created_by_active_agent
+            ) or register_missing_active_skills_agent
+
+            if should_register:
                 try:
                     registered = self.register_commands(
                         agent_name,
@@ -674,11 +925,21 @@ class CommandRegistrar:
                         source_dir,
                         project_root,
                         context_note=context_note,
+                        _resolved_dir=agent_dir,
+                        link_outputs=link_outputs,
                     )
                     if registered:
                         results[agent_name] = registered
+                    if register_missing_active_skills_agent:
+                        active_created_skills_dir = (
+                            recovered_active_skills_dir or agent_dir
+                        )
                 except ValueError:
                     continue
+                except OSError:
+                    if register_missing_active_skills_agent:
+                        continue
+                    raise
 
         return results
 
@@ -689,6 +950,7 @@ class CommandRegistrar:
         source_dir: Path,
         project_root: Path,
         context_note: Optional[str] = None,
+        link_outputs: bool = False,
     ) -> Dict[str, List[str]]:
         """Register commands for all non-skill agents in the project.
 
@@ -702,6 +964,8 @@ class CommandRegistrar:
             source_dir: Directory containing command source files
             project_root: Path to project root
             context_note: Custom context comment for markdown output
+            link_outputs: If True, create dev-mode symlinks for rendered
+                command files when supported by the OS.
 
         Returns:
             Dictionary mapping agent names to list of registered commands
@@ -711,8 +975,15 @@ class CommandRegistrar:
         for agent_name, agent_config in self.AGENT_CONFIGS.items():
             if agent_config.get("extension") == "/SKILL.md":
                 continue
-            agent_dir = project_root / agent_config["dir"]
-            if agent_dir.exists():
+            detect_dir_str = agent_config.get("detect_dir")
+            if detect_dir_str:
+                detect_path = project_root / detect_dir_str
+                if not detect_path.is_dir():
+                    continue
+            agent_dir = self._resolve_agent_dir(
+                agent_name, agent_config, project_root,
+            )
+            if agent_dir.is_dir():
                 try:
                     registered = self.register_commands(
                         agent_name,
@@ -721,6 +992,8 @@ class CommandRegistrar:
                         source_dir,
                         project_root,
                         context_note=context_note,
+                        _resolved_dir=agent_dir,
+                        link_outputs=link_outputs,
                     )
                     if registered:
                         results[agent_name] = registered
@@ -733,6 +1006,11 @@ class CommandRegistrar:
     ) -> None:
         """Remove previously registered command files from agent directories.
 
+        When a ``legacy_dir`` is configured, files are removed from
+        *both* the canonical and the legacy directory so that orphaned
+        commands left behind after an ``integration upgrade`` are
+        cleaned up as well.
+
         Args:
             registered_commands: Dict mapping agent names to command name lists
             project_root: Path to project root
@@ -743,24 +1021,49 @@ class CommandRegistrar:
                 continue
 
             agent_config = self.AGENT_CONFIGS[agent_name]
-            commands_dir = project_root / agent_config["dir"]
+            commands_dir = self._resolve_agent_dir(
+                agent_name, agent_config, project_root,
+            )
+
+            # Collect all directories to clean: canonical (or resolved
+            # legacy) plus the legacy dir if it exists separately.
+            dirs_to_clean = [commands_dir]
+            legacy = agent_config.get("legacy_dir")
+            if legacy:
+                legacy_dir = project_root / legacy
+                if legacy_dir.exists() and legacy_dir != commands_dir:
+                    dirs_to_clean.append(legacy_dir)
 
             for cmd_name in cmd_names:
                 output_name = self._compute_output_name(
                     agent_name, cmd_name, agent_config
                 )
-                cmd_file = commands_dir / f"{output_name}{agent_config['extension']}"
-                if cmd_file.exists():
-                    cmd_file.unlink()
-                    # For SKILL.md agents each command lives in its own subdirectory
-                    # (e.g. .agents/skills/speckit-ext-cmd/SKILL.md). Remove the
-                    # parent dir when it becomes empty to avoid orphaned directories.
-                    parent = cmd_file.parent
-                    if parent != commands_dir and parent.exists():
+
+                names_to_clean = [output_name]
+                if output_name != cmd_name and self._is_safe_command_name(cmd_name):
+                    names_to_clean.append(cmd_name)
+
+                for target_dir in dirs_to_clean:
+                    for name in names_to_clean:
+                        cmd_file = (
+                            target_dir / f"{name}{agent_config['extension']}"
+                        )
                         try:
-                            parent.rmdir()  # no-op if dir still has other files
-                        except OSError:
-                            pass
+                            self._ensure_inside(cmd_file, target_dir)
+                        except ValueError:
+                            continue
+                        if cmd_file.exists() or cmd_file.is_symlink():
+                            cmd_file.unlink()
+                            # For SKILL.md agents each command lives in its own
+                            # subdirectory (e.g. .agents/skills/speckit-ext-cmd/
+                            # SKILL.md).  Remove the parent dir when it becomes
+                            # empty to avoid orphaned directories.
+                            parent = cmd_file.parent
+                            if parent != target_dir and parent.exists():
+                                try:
+                                    parent.rmdir()
+                                except OSError:
+                                    pass
 
                 if agent_name == "copilot":
                     prompt_file = (

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/commands/__init__.py

@@ -0,0 +1,7 @@
+"""CLI command groups extracted from the main application.
+
+Implemented command modules expose a ``register(app)`` function. Placeholder
+modules are import-only anchors for command groups that still live in the main
+application module.
+"""
+from __future__ import annotations

src/specify_cli/commands/init.py

@@ -0,0 +1,786 @@
+"""specify init command."""
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.live import Live
+from rich.panel import Panel
+
+from .._agent_config import (
+    AGENT_CONFIG,
+    AI_ASSISTANT_ALIASES,
+    AI_ASSISTANT_HELP,
+    DEFAULT_INIT_INTEGRATION,
+    SCRIPT_TYPE_CHOICES,
+)
+from .._assets import (
+    _locate_bundled_extension,
+    _locate_bundled_preset,
+    _locate_bundled_workflow,
+    get_speckit_version,
+)
+from .._console import StepTracker, console, select_with_arrows, show_banner
+from .._utils import check_tool, init_git_repo, is_git_repo
+
+def _build_integration_equivalent(
+    integration_key: str,
+    ai_commands_dir: str | None = None,
+) -> str:
+    parts = [f"--integration {integration_key}"]
+    if integration_key == "generic" and ai_commands_dir:
+        parts.append(
+            f'--integration-options="--commands-dir {shlex.quote(ai_commands_dir)}"'
+        )
+    return " ".join(parts)
+
+
+def _build_ai_deprecation_warning(
+    integration_key: str,
+    ai_commands_dir: str | None = None,
+) -> str:
+    replacement = _build_integration_equivalent(
+        integration_key,
+        ai_commands_dir=ai_commands_dir,
+    )
+    return (
+        "[bold]--ai[/bold] is deprecated and will no longer be available in version 0.10.0 or later.\n\n"
+        f"Use [bold]{replacement}[/bold] instead."
+    )
+
+
+def _stdin_is_interactive() -> bool:
+    return sys.stdin.isatty()
+
+
+def ensure_constitution_from_template(
+    project_path: Path, tracker: StepTracker | None = None
+) -> None:
+    """Copy constitution template to memory if it doesn't exist."""
+    memory_constitution = project_path / ".specify" / "memory" / "constitution.md"
+    template_constitution = project_path / ".specify" / "templates" / "constitution-template.md"
+
+    if memory_constitution.exists():
+        if tracker:
+            tracker.add("constitution", "Constitution setup")
+            tracker.skip("constitution", "existing file preserved")
+        return
+
+    if not template_constitution.exists():
+        if tracker:
+            tracker.add("constitution", "Constitution setup")
+            tracker.error("constitution", "template not found")
+        return
+
+    try:
+        memory_constitution.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(template_constitution, memory_constitution)
+        if tracker:
+            tracker.add("constitution", "Constitution setup")
+            tracker.complete("constitution", "copied from template")
+        else:
+            console.print("[cyan]Initialized constitution from template[/cyan]")
+    except Exception as e:
+        if tracker:
+            tracker.add("constitution", "Constitution setup")
+            tracker.error("constitution", str(e))
+        else:
+            console.print(f"[yellow]Warning: Could not initialize constitution: {e}[/yellow]")
+
+
+def register(app: typer.Typer) -> None:
+    @app.command()
+    def init(
+        project_name: str = typer.Argument(None, help="Name for your new project directory (optional if using --here, or use '.' for current directory)"),
+        ai_assistant: str = typer.Option(None, "--ai", help=AI_ASSISTANT_HELP),
+        ai_commands_dir: str = typer.Option(None, "--ai-commands-dir", help="Directory for agent command files (required with --ai generic, e.g. .myagent/commands/)"),
+        script_type: str = typer.Option(None, "--script", help="Script type to use: sh or ps"),
+        ignore_agent_tools: bool = typer.Option(False, "--ignore-agent-tools", help="Skip checks for coding agent tools like Claude Code"),
+        no_git: bool = typer.Option(False, "--no-git", help="Skip git repository initialization"),
+        here: bool = typer.Option(False, "--here", help="Initialize project in the current directory instead of creating a new one"),
+        force: bool = typer.Option(False, "--force", help="Force merge/overwrite when using --here (skip confirmation)"),
+        skip_tls: bool = typer.Option(False, "--skip-tls", help="Deprecated (no-op). Previously: skip SSL/TLS verification.", hidden=True),
+        debug: bool = typer.Option(False, "--debug", help="Deprecated. Previously: show verbose diagnostic output; currently only prints additional diagnostic details on failure.", hidden=True),
+        github_token: str = typer.Option(None, "--github-token", help="Deprecated (no-op). Previously: GitHub token for API requests.", hidden=True),
+        ai_skills: bool = typer.Option(False, "--ai-skills", help="Install Prompt.MD templates as agent skills (requires --ai)"),
+        offline: bool = typer.Option(False, "--offline", help="Deprecated (no-op). All scaffolding now uses bundled assets.", hidden=True),
+        preset: str = typer.Option(None, "--preset", help="Install a preset during initialization (by preset ID)"),
+        branch_numbering: str = typer.Option(None, "--branch-numbering", help="Branch numbering strategy: 'sequential' (001, 002, …, 1000, … — expands past 999 automatically) or 'timestamp' (YYYYMMDD-HHMMSS)"),
+        integration: str = typer.Option(None, "--integration", help="Use the new integration system (e.g. --integration copilot). Mutually exclusive with --ai."),
+        integration_options: str = typer.Option(None, "--integration-options", help='Options for the integration (e.g. --integration-options="--commands-dir .myagent/cmds")'),
+    ):
+        """
+        Initialize a new Specify project.
+
+        Project files are scaffolded from assets bundled inside the specify-cli
+        package, so initialization does not need network access and templates
+        match the installed CLI version.
+
+        This command will:
+        1. Check that required tools are installed (git is optional)
+        2. Let you choose your coding agent integration, or default to Copilot
+           in non-interactive sessions
+        3. Install bundled Spec Kit templates, scripts, workflow, and shared
+           project infrastructure
+        4. Initialize a fresh git repository (if not --no-git and no existing repo)
+        5. Set up coding agent integration commands and optional presets
+
+        Examples:
+            specify init my-project
+            specify init my-project --integration claude
+            specify init my-project --integration copilot --no-git
+            specify init --ignore-agent-tools my-project
+            specify init . --integration claude         # Initialize in current directory
+            specify init .                     # Initialize in current directory (interactive integration selection)
+            specify init --here --integration claude    # Alternative syntax for current directory
+            specify init --here --integration codex --integration-options="--skills"
+            specify init --here --integration codebuddy
+            specify init --here --integration vibe      # Initialize with Mistral Vibe support
+            specify init --here
+            specify init --here --force  # Skip confirmation when current directory not empty
+            specify init my-project --integration claude   # Claude installs skills by default
+            specify init --here --integration gemini
+            specify init my-project --integration generic --integration-options="--commands-dir .myagent/commands/"  # Bring your own agent; requires --commands-dir
+            specify init my-project --integration claude --preset healthcare-compliance  # With preset
+        """
+        # Lazy imports to avoid circular dependency — __init__.py imports this module
+        from .. import (
+            _install_shared_infra_or_exit,
+            _print_cli_warning,
+            _update_agent_context_config_file,
+            ensure_executable_scripts,
+            save_init_options,
+        )
+        from ..integrations._commands import (
+            _parse_integration_options,
+            _write_integration_json,
+        )
+        from ..integration_runtime import with_integration_setting as _with_integration_setting
+
+        show_banner()
+        ai_deprecation_warning: str | None = None
+
+        if ai_assistant and ai_assistant.startswith("--"):
+            console.print(f"[red]Error:[/red] Invalid value for --ai: '{ai_assistant}'")
+            console.print("[yellow]Hint:[/yellow] Did you forget to provide a value for --ai?")
+            console.print("[yellow]Example:[/yellow] specify init --integration claude --here")
+            console.print(f"[yellow]Available agents:[/yellow] {', '.join(AGENT_CONFIG.keys())}")
+            raise typer.Exit(1)
+
+        if ai_commands_dir and ai_commands_dir.startswith("--"):
+            console.print(f"[red]Error:[/red] Invalid value for --ai-commands-dir: '{ai_commands_dir}'")
+            console.print("[yellow]Hint:[/yellow] Did you forget to provide a value for --ai-commands-dir?")
+            console.print("[yellow]Example:[/yellow] specify init --integration generic --integration-options=\"--commands-dir .myagent/commands/\"")
+            raise typer.Exit(1)
+
+        if ai_assistant:
+            ai_assistant = AI_ASSISTANT_ALIASES.get(ai_assistant, ai_assistant)
+
+        if integration and ai_assistant:
+            console.print("[red]Error:[/red] --integration and --ai are mutually exclusive")
+            raise typer.Exit(1)
+
+        from ..integrations import INTEGRATION_REGISTRY, get_integration
+        if integration:
+            resolved_integration = get_integration(integration)
+            if not resolved_integration:
+                console.print(f"[red]Error:[/red] Unknown integration: '{integration}'")
+                available = ", ".join(sorted(INTEGRATION_REGISTRY))
+                console.print(f"[yellow]Available integrations:[/yellow] {available}")
+                raise typer.Exit(1)
+            ai_assistant = integration
+        elif ai_assistant:
+            resolved_integration = get_integration(ai_assistant)
+            if not resolved_integration:
+                console.print(f"[red]Error:[/red] Unknown agent '{ai_assistant}'. Choose from: {', '.join(sorted(INTEGRATION_REGISTRY))}")
+                raise typer.Exit(1)
+            ai_deprecation_warning = _build_ai_deprecation_warning(
+                resolved_integration.key,
+                ai_commands_dir=ai_commands_dir,
+            )
+
+        if ai_assistant or integration:
+            if ai_skills:
+                from ..integrations.base import SkillsIntegration as _SkillsCheck
+                if isinstance(resolved_integration, _SkillsCheck):
+                    console.print(
+                        "[dim]Note: --ai-skills is not needed; "
+                        "skills are the default for this integration.[/dim]"
+                    )
+                else:
+                    console.print(
+                        "[dim]Note: --ai-skills has no effect with "
+                        f"{resolved_integration.key}; this integration uses commands, not skills.[/dim]"
+                    )
+            if ai_commands_dir and resolved_integration.key != "generic":
+                console.print(
+                    "[dim]Note: --ai-commands-dir is deprecated; "
+                    'use [bold]--integration generic --integration-options="--commands-dir <dir>"[/bold] instead.[/dim]'
+                )
+
+        if no_git:
+            console.print(
+                "[yellow]⚠️  --no-git is deprecated and will be removed in v0.10.0.[/yellow]\n"
+                "[yellow]The git extension will no longer be enabled by default "
+                "— use the [bold]specify extension[/bold] commands to install or enable the git extension if needed.[/yellow]"
+            )
+
+        if project_name == ".":
+            here = True
+            project_name = None
+
+        if here and project_name:
+            console.print("[red]Error:[/red] Cannot specify both project name and --here flag")
+            raise typer.Exit(1)
+
+        if not here and not project_name:
+            console.print("[red]Error:[/red] Must specify either a project name, use '.' for current directory, or use --here flag")
+            raise typer.Exit(1)
+
+        if ai_skills and not ai_assistant:
+            console.print("[red]Error:[/red] --ai-skills requires --ai to be specified")
+            console.print("[yellow]Usage:[/yellow] specify init <project> --ai <agent> --ai-skills")
+            raise typer.Exit(1)
+
+        BRANCH_NUMBERING_CHOICES = {"sequential", "timestamp"}
+        if branch_numbering and branch_numbering not in BRANCH_NUMBERING_CHOICES:
+            console.print(f"[red]Error:[/red] Invalid --branch-numbering value '{branch_numbering}'. Choose from: {', '.join(sorted(BRANCH_NUMBERING_CHOICES))}")
+            raise typer.Exit(1)
+
+        dir_existed_before = False
+        if here:
+            project_name = Path.cwd().name
+            project_path = Path.cwd()
+            dir_existed_before = True
+
+            existing_items = list(project_path.iterdir())
+            if existing_items:
+                console.print(f"[yellow]Warning:[/yellow] Current directory is not empty ({len(existing_items)} items)")
+                console.print("[yellow]Template files will be merged with existing content and may overwrite existing files[/yellow]")
+                if force:
+                    console.print("[cyan]--force supplied: skipping confirmation and proceeding with merge[/cyan]")
+                else:
+                    response = typer.confirm("Do you want to continue?")
+                    if not response:
+                        console.print("[yellow]Operation cancelled[/yellow]")
+                        raise typer.Exit(0)
+        else:
+            project_path = Path(project_name).resolve()
+            dir_existed_before = project_path.exists()
+            if project_path.exists():
+                if not project_path.is_dir():
+                    console.print(f"[red]Error:[/red] '{project_name}' exists but is not a directory.")
+                    raise typer.Exit(1)
+                existing_items = list(project_path.iterdir())
+                if force:
+                    if existing_items:
+                        console.print(f"[yellow]Warning:[/yellow] Directory '{project_name}' is not empty ({len(existing_items)} items)")
+                        console.print("[yellow]Template files will be merged with existing content and may overwrite existing files[/yellow]")
+                    console.print(f"[cyan]--force supplied: merging into existing directory '[cyan]{project_name}[/cyan]'[/cyan]")
+                else:
+                    error_panel = Panel(
+                        f"Directory already exists: '[cyan]{project_name}[/cyan]'\n"
+                        "Please choose a different project name or remove the existing directory.\n"
+                        "Use [bold]--force[/bold] to merge into the existing directory.",
+                        title="[red]Directory Conflict[/red]",
+                        border_style="red",
+                        padding=(1, 2)
+                    )
+                    console.print()
+                    console.print(error_panel)
+                    raise typer.Exit(1)
+
+        if ai_assistant:
+            if ai_assistant not in AGENT_CONFIG:
+                console.print(f"[red]Error:[/red] Invalid AI assistant '{ai_assistant}'. Choose from: {', '.join(AGENT_CONFIG.keys())}")
+                raise typer.Exit(1)
+            selected_ai = ai_assistant
+        elif not _stdin_is_interactive():
+            console.print(
+                f"[dim]Non-interactive session detected: defaulting to '{DEFAULT_INIT_INTEGRATION}'. "
+                "Use --integration to choose a different agent.[/dim]"
+            )
+            selected_ai = DEFAULT_INIT_INTEGRATION
+        else:
+            ai_choices = {key: config["name"] for key, config in AGENT_CONFIG.items()}
+            selected_ai = select_with_arrows(
+                ai_choices,
+                "Choose your coding agent integration:",
+                DEFAULT_INIT_INTEGRATION,
+            )
+
+        if not ai_assistant:
+            resolved_integration = get_integration(selected_ai)
+            if not resolved_integration:
+                console.print(f"[red]Error:[/red] Unknown agent '{selected_ai}'")
+                raise typer.Exit(1)
+
+        if selected_ai == "generic" and not integration_options:
+            if not ai_commands_dir:
+                console.print("[red]Error:[/red] --ai-commands-dir is required when using --ai generic or --integration generic")
+                console.print('[dim]Example: specify init my-project --integration generic --integration-options="--commands-dir .myagent/commands/"[/dim]')
+                raise typer.Exit(1)
+
+        current_dir = Path.cwd()
+
+        setup_lines = [
+            "[cyan]Specify Project Setup[/cyan]",
+            "",
+            f"{'Project':<15} [green]{project_path.name}[/green]",
+            f"{'Working Path':<15} [dim]{current_dir}[/dim]",
+        ]
+
+        if not here:
+            setup_lines.append(f"{'Target Path':<15} [dim]{project_path}[/dim]")
+
+        console.print(Panel("\n".join(setup_lines), border_style="cyan", padding=(1, 2)))
+
+        should_init_git = False
+        if not no_git:
+            should_init_git = check_tool("git")
+            if not should_init_git:
+                console.print("[yellow]Git not found - will skip repository initialization[/yellow]")
+
+        if not ignore_agent_tools:
+            agent_config = AGENT_CONFIG.get(selected_ai)
+            if agent_config and agent_config["requires_cli"]:
+                install_url = agent_config["install_url"]
+                if not check_tool(selected_ai):
+                    error_panel = Panel(
+                        f"[cyan]{selected_ai}[/cyan] not found\n"
+                        f"Install from: [cyan]{install_url}[/cyan]\n"
+                        f"{agent_config['name']} is required to continue with this project type.\n\n"
+                        "Tip: Use [cyan]--ignore-agent-tools[/cyan] to skip this check",
+                        title="[red]Agent Detection Error[/red]",
+                        border_style="red",
+                        padding=(1, 2)
+                    )
+                    console.print()
+                    console.print(error_panel)
+                    raise typer.Exit(1)
+
+        if script_type:
+            if script_type not in SCRIPT_TYPE_CHOICES:
+                console.print(f"[red]Error:[/red] Invalid script type '{script_type}'. Choose from: {', '.join(SCRIPT_TYPE_CHOICES.keys())}")
+                raise typer.Exit(1)
+            selected_script = script_type
+        else:
+            default_script = "ps" if os.name == "nt" else "sh"
+
+            if _stdin_is_interactive():
+                selected_script = select_with_arrows(SCRIPT_TYPE_CHOICES, "Choose script type (or press Enter)", default_script)
+            else:
+                selected_script = default_script
+
+        console.print(f"[cyan]Selected coding agent integration:[/cyan] {selected_ai}")
+        console.print(f"[cyan]Selected script type:[/cyan] {selected_script}")
+
+        tracker = StepTracker("Initialize Specify Project")
+
+        tracker.add("precheck", "Check required tools")
+        tracker.complete("precheck", "ok")
+        tracker.add("ai-select", "Select coding agent integration")
+        tracker.complete("ai-select", f"{selected_ai}")
+        tracker.add("script-select", "Select script type")
+        tracker.complete("script-select", selected_script)
+
+        tracker.add("integration", "Install integration")
+        tracker.add("shared-infra", "Install shared infrastructure")
+
+        for key, label in [
+            ("chmod", "Ensure scripts executable"),
+            ("constitution", "Constitution setup"),
+            ("git", "Install git extension"),
+            ("workflow", "Install bundled workflow"),
+            ("agent-context", "Install agent-context extension"),
+            ("final", "Finalize"),
+        ]:
+            tracker.add(key, label)
+
+        git_default_notice = False
+
+        with Live(tracker.render(), console=console, refresh_per_second=8, transient=True) as live:
+            tracker.attach_refresh(lambda: live.update(tracker.render()))
+            try:
+                from ..integrations.manifest import IntegrationManifest
+                tracker.start("integration")
+                manifest = IntegrationManifest(
+                    resolved_integration.key, project_path, version=get_speckit_version()
+                )
+
+                integration_parsed_options: dict[str, Any] = {}
+                if ai_commands_dir:
+                    integration_parsed_options["commands_dir"] = ai_commands_dir
+                if ai_skills:
+                    integration_parsed_options["skills"] = True
+                if integration_options:
+                    extra = _parse_integration_options(resolved_integration, integration_options)
+                    if extra:
+                        integration_parsed_options.update(extra)
+
+                resolved_integration.setup(
+                    project_path, manifest,
+                    parsed_options=integration_parsed_options or None,
+                    script_type=selected_script,
+                    raw_options=integration_options,
+                )
+                manifest.save()
+
+                integration_settings = _with_integration_setting(
+                    {},
+                    resolved_integration.key,
+                    resolved_integration,
+                    script_type=selected_script,
+                    raw_options=integration_options,
+                    parsed_options=integration_parsed_options or None,
+                )
+                _write_integration_json(
+                    project_path,
+                    resolved_integration.key,
+                    [resolved_integration.key],
+                    integration_settings,
+                )
+
+                tracker.complete("integration", resolved_integration.config.get("name", resolved_integration.key))
+
+                tracker.start("shared-infra")
+                _install_shared_infra_or_exit(
+                    project_path,
+                    selected_script,
+                    tracker=tracker,
+                    force=force,
+                    invoke_separator=resolved_integration.effective_invoke_separator(integration_parsed_options),
+                )
+                tracker.complete("shared-infra", f"scripts ({selected_script}) + templates")
+
+                ensure_constitution_from_template(project_path, tracker=tracker)
+
+                if not no_git:
+                    tracker.start("git")
+                    git_messages = []
+                    git_has_error = False
+                    if is_git_repo(project_path):
+                        git_messages.append("existing repo detected")
+                    elif should_init_git:
+                        success, error_msg = init_git_repo(project_path, quiet=True)
+                        if success:
+                            git_messages.append("initialized")
+                        else:
+                            git_has_error = True
+                            if error_msg:
+                                sanitized = error_msg.replace('\n', ' ').strip()
+                                git_messages.append(f"init failed: {sanitized[:120]}")
+                            else:
+                                git_messages.append("init failed")
+                    else:
+                        git_messages.append("git not available")
+                    try:
+                        from ..extensions import ExtensionManager
+                        bundled_path = _locate_bundled_extension("git")
+                        if bundled_path:
+                            manager = ExtensionManager(project_path)
+                            if manager.registry.is_installed("git"):
+                                git_messages.append("extension already installed")
+                            else:
+                                manager.install_from_directory(
+                                    bundled_path, get_speckit_version()
+                                )
+                                git_default_notice = True
+                                git_messages.append("extension installed")
+                        else:
+                            git_has_error = True
+                            git_messages.append("bundled extension not found")
+                    except Exception as ext_err:
+                        git_has_error = True
+                        sanitized_ext = str(ext_err).replace('\n', ' ').strip()
+                        git_messages.append(
+                            f"extension install failed: {sanitized_ext[:120]}"
+                        )
+                    summary = "; ".join(git_messages)
+                    if git_has_error:
+                        tracker.error("git", summary)
+                    else:
+                        tracker.complete("git", summary)
+                else:
+                    tracker.skip("git", "--no-git flag")
+
+                try:
+                    bundled_wf = _locate_bundled_workflow("speckit")
+                    if bundled_wf:
+                        from ..workflows.catalog import WorkflowRegistry
+                        from ..workflows.engine import WorkflowDefinition
+                        wf_registry = WorkflowRegistry(project_path)
+                        if wf_registry.is_installed("speckit"):
+                            tracker.complete("workflow", "already installed")
+                        else:
+                            import shutil as _shutil
+                            dest_wf = project_path / ".specify" / "workflows" / "speckit"
+                            dest_wf.mkdir(parents=True, exist_ok=True)
+                            _shutil.copy2(
+                                bundled_wf / "workflow.yml",
+                                dest_wf / "workflow.yml",
+                            )
+                            definition = WorkflowDefinition.from_yaml(dest_wf / "workflow.yml")
+                            wf_registry.add("speckit", {
+                                "name": definition.name,
+                                "version": definition.version,
+                                "description": definition.description,
+                                "source": "bundled",
+                            })
+                            tracker.complete("workflow", "speckit installed")
+                    else:
+                        tracker.skip("workflow", "bundled workflow not found")
+                except Exception as wf_err:
+                    sanitized_wf = str(wf_err).replace('\n', ' ').strip()
+                    tracker.error("workflow", f"install failed: {sanitized_wf[:120]}")
+
+                init_opts = {
+                    "ai": selected_ai,
+                    "integration": resolved_integration.key,
+                    "branch_numbering": branch_numbering or "sequential",
+                    "here": here,
+                    "script": selected_script,
+                    "speckit_version": get_speckit_version(),
+                }
+                from ..integrations.base import SkillsIntegration as _SkillsPersist
+                if isinstance(resolved_integration, _SkillsPersist) or getattr(resolved_integration, "_skills_mode", False):
+                    init_opts["ai_skills"] = True
+                save_init_options(project_path, init_opts)
+
+                # --- agent-context extension (bundled, auto-installed) ---
+                # Installed after init-options.json is written so that skill
+                # registration can read ai_skills + integration key.
+                try:
+                    from ..extensions import ExtensionManager as _ExtMgr
+                    bundled_ac = _locate_bundled_extension("agent-context")
+                    if bundled_ac:
+                        ac_mgr = _ExtMgr(project_path)
+                        if ac_mgr.registry.is_installed("agent-context"):
+                            tracker.complete("agent-context", "already installed")
+                        else:
+                            ac_mgr.install_from_directory(
+                                bundled_ac, get_speckit_version()
+                            )
+                            tracker.complete("agent-context", "extension installed")
+                    else:
+                        from ..extensions import REINSTALL_COMMAND as _ac_reinstall
+                        tracker.error(
+                            "agent-context",
+                            f"bundled extension not found — installation may be "
+                            f"incomplete. Run: {_ac_reinstall}",
+                        )
+                except Exception as ac_err:
+                    sanitized_ac = str(ac_err).replace('\n', ' ').strip()
+                    tracker.error(
+                        "agent-context",
+                        f"extension install failed: {sanitized_ac[:120]}",
+                    )
+
+                # Write context_file to the agent-context extension config
+                # AFTER the extension install (which copies the template config
+                # with an empty context_file).
+                if resolved_integration.context_file:
+                    _update_agent_context_config_file(
+                        project_path,
+                        resolved_integration.context_file,
+                        preserve_markers=True,
+                    )
+
+                ensure_executable_scripts(project_path, tracker=tracker)
+
+                if preset:
+                    try:
+                        from ..presets import PresetManager, PresetCatalog, PresetError
+                        preset_manager = PresetManager(project_path)
+                        speckit_ver = get_speckit_version()
+
+                        local_path = Path(preset).resolve()
+                        if local_path.is_dir() and (local_path / "preset.yml").exists():
+                            preset_manager.install_from_directory(local_path, speckit_ver)
+                        else:
+                            bundled_path = _locate_bundled_preset(preset)
+                            if bundled_path:
+                                preset_manager.install_from_directory(bundled_path, speckit_ver)
+                            else:
+                                preset_catalog = PresetCatalog(project_path)
+                                pack_info = preset_catalog.get_pack_info(preset)
+                                if not pack_info:
+                                    console.print(f"[yellow]Warning:[/yellow] Preset '{preset}' not found in catalog. Skipping.")
+                                elif pack_info.get("bundled") and not pack_info.get("download_url"):
+                                    from ..extensions import REINSTALL_COMMAND
+                                    console.print(
+                                        f"[yellow]Warning:[/yellow] Preset '{preset}' is bundled with spec-kit "
+                                        f"but could not be found in the installed package."
+                                    )
+                                    console.print(
+                                        "This usually means the spec-kit installation is incomplete or corrupted."
+                                    )
+                                    console.print(f"Try reinstalling: {REINSTALL_COMMAND}")
+                                else:
+                                    zip_path = None
+                                    try:
+                                        zip_path = preset_catalog.download_pack(preset)
+                                        preset_manager.install_from_zip(zip_path, speckit_ver)
+                                    except PresetError as preset_err:
+                                        _print_cli_warning(
+                                            "install",
+                                            "preset",
+                                            preset,
+                                            preset_err,
+                                            continuing="Continuing without the optional preset.",
+                                        )
+                                    finally:
+                                        if zip_path is not None:
+                                            try:
+                                                zip_path.unlink(missing_ok=True)
+                                            except OSError:
+                                                pass
+                    except Exception as preset_err:
+                        _print_cli_warning(
+                            "install",
+                            "preset",
+                            preset,
+                            preset_err,
+                            continuing="Continuing without the optional preset.",
+                        )
+
+                tracker.complete("final", "project ready")
+            except (typer.Exit, SystemExit):
+                raise
+            except Exception as e:
+                tracker.error("final", str(e))
+                console.print(Panel(f"Initialization failed: {e}", title="Failure", border_style="red"))
+                if debug:
+                    _env_pairs = [
+                        ("Python", sys.version.split()[0]),
+                        ("Platform", sys.platform),
+                        ("CWD", str(Path.cwd())),
+                    ]
+                    _label_width = max(len(k) for k, _ in _env_pairs)
+                    env_lines = [f"{k.ljust(_label_width)} → [bright_black]{v}[/bright_black]" for k, v in _env_pairs]
+                    console.print(Panel("\n".join(env_lines), title="Debug Environment", border_style="magenta"))
+                if not here and project_path.exists() and not dir_existed_before:
+                    shutil.rmtree(project_path)
+                raise typer.Exit(1)
+            finally:
+                pass
+
+        console.print(tracker.render())
+        console.print("\n[bold green]Project ready.[/bold green]")
+
+        agent_config = AGENT_CONFIG.get(selected_ai)
+        if agent_config:
+            agent_folder = ai_commands_dir if selected_ai == "generic" else agent_config["folder"]
+            if agent_folder:
+                security_notice = Panel(
+                    f"Some agents may store credentials, auth tokens, or other identifying and private artifacts in the agent folder within your project.\n"
+                    f"Consider adding [cyan]{agent_folder}[/cyan] (or parts of it) to [cyan].gitignore[/cyan] to prevent accidental credential leakage.",
+                    title="[yellow]Agent Folder Security[/yellow]",
+                    border_style="yellow",
+                    padding=(1, 2)
+                )
+                console.print()
+                console.print(security_notice)
+
+        if ai_deprecation_warning:
+            deprecation_notice = Panel(
+                ai_deprecation_warning,
+                title="[bold red]Deprecation Warning[/bold red]",
+                border_style="red",
+                padding=(1, 2),
+            )
+            console.print()
+            console.print(deprecation_notice)
+
+        if git_default_notice:
+            default_change_notice = Panel(
+                "The git extension is currently enabled by default during [bold]specify init[/bold].\n"
+                "Starting in [bold]v0.10.0[/bold], this will require explicit opt-in.\n"
+                "Use [bold]specify extension add git[/bold] after init when needed.",
+                title="[yellow]Notice: Git Default Changing[/yellow]",
+                border_style="yellow",
+                padding=(1, 2),
+            )
+            console.print()
+            console.print(default_change_notice)
+
+        steps_lines = []
+        if not here:
+            steps_lines.append(f"1. Go to the project folder: [cyan]cd {project_name}[/cyan]")
+            step_num = 2
+        else:
+            steps_lines.append("1. You're already in the project directory!")
+            step_num = 2
+
+        from ..integrations.base import SkillsIntegration as _SkillsInt
+        _is_skills_integration = isinstance(resolved_integration, _SkillsInt) or getattr(resolved_integration, "_skills_mode", False)
+
+        codex_skill_mode = selected_ai == "codex" and (ai_skills or _is_skills_integration)
+        claude_skill_mode = selected_ai == "claude" and (ai_skills or _is_skills_integration)
+        kimi_skill_mode = selected_ai == "kimi"
+        agy_skill_mode = selected_ai == "agy" and _is_skills_integration
+        trae_skill_mode = selected_ai == "trae"
+        cursor_agent_skill_mode = selected_ai == "cursor-agent" and (ai_skills or _is_skills_integration)
+        copilot_skill_mode = selected_ai == "copilot" and _is_skills_integration
+        devin_skill_mode = selected_ai == "devin"
+        cline_skill_mode = selected_ai == "cline"
+        native_skill_mode = codex_skill_mode or claude_skill_mode or kimi_skill_mode or agy_skill_mode or trae_skill_mode or cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode
+
+        if codex_skill_mode and not ai_skills:
+            steps_lines.append(f"{step_num}. Start Codex in this project directory; spec-kit skills were installed to [cyan].agents/skills[/cyan]")
+            step_num += 1
+        if claude_skill_mode and not ai_skills:
+            steps_lines.append(f"{step_num}. Start Claude in this project directory; spec-kit skills were installed to [cyan].claude/skills[/cyan]")
+            step_num += 1
+        if cursor_agent_skill_mode and not ai_skills:
+            steps_lines.append(f"{step_num}. Start Cursor Agent in this project directory; spec-kit skills were installed to [cyan].cursor/skills[/cyan]")
+            step_num += 1
+        if devin_skill_mode:
+            steps_lines.append(f"{step_num}. Start Devin in this project directory; spec-kit skills were installed to [cyan].devin/skills[/cyan]")
+            step_num += 1
+        usage_label = "skills" if native_skill_mode else "slash commands"
+
+        def _display_cmd(name: str) -> str:
+            if codex_skill_mode or agy_skill_mode or trae_skill_mode:
+                return f"$speckit-{name}"
+            if claude_skill_mode:
+                return f"/speckit-{name}"
+            if kimi_skill_mode:
+                return f"/skill:speckit-{name}"
+            if cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode or cline_skill_mode:
+                return f"/speckit-{name}"
+            return f"/speckit.{name}"
+
+        steps_lines.append(f"{step_num}. Start using {usage_label} with your coding agent:")
+
+        steps_lines.append(f"   {step_num}.1 [cyan]{_display_cmd('constitution')}[/] - Establish project principles")
+        steps_lines.append(f"   {step_num}.2 [cyan]{_display_cmd('specify')}[/] - Create baseline specification")
+        steps_lines.append(f"   {step_num}.3 [cyan]{_display_cmd('plan')}[/] - Create implementation plan")
+        steps_lines.append(f"   {step_num}.4 [cyan]{_display_cmd('tasks')}[/] - Generate actionable tasks")
+        steps_lines.append(f"   {step_num}.5 [cyan]{_display_cmd('implement')}[/] - Execute implementation")
+
+        steps_panel = Panel("\n".join(steps_lines), title="Next Steps", border_style="cyan", padding=(1, 2))
+        console.print()
+        console.print(steps_panel)
+
+        enhancement_intro = (
+            "Optional skills that you can use for your specs [bright_black](improve quality & confidence)[/bright_black]"
+            if native_skill_mode
+            else "Optional commands that you can use for your specs [bright_black](improve quality & confidence)[/bright_black]"
+        )
+        enhancement_lines = [
+            enhancement_intro,
+            "",
+            f"○ [cyan]{_display_cmd('clarify')}[/] [bright_black](optional)[/bright_black] - Ask structured questions to de-risk ambiguous areas before planning (run before [cyan]{_display_cmd('plan')}[/] if used)",
+            f"○ [cyan]{_display_cmd('analyze')}[/] [bright_black](optional)[/bright_black] - Cross-artifact consistency & alignment report (after [cyan]{_display_cmd('tasks')}[/], before [cyan]{_display_cmd('implement')}[/])",
+            f"○ [cyan]{_display_cmd('checklist')}[/] [bright_black](optional)[/bright_black] - Generate quality checklists to validate requirements completeness, clarity, and consistency (after [cyan]{_display_cmd('plan')}[/])"
+        ]
+        enhancements_title = "Enhancement Skills" if native_skill_mode else "Enhancement Commands"
+        enhancements_panel = Panel("\n".join(enhancement_lines), title=enhancements_title, border_style="cyan", padding=(1, 2))
+        console.print()
+        console.print(enhancements_panel)

src/specify_cli/extensions.py

@@ -25,13 +25,16 @@ import yaml
 from packaging import version as pkg_version
 from packaging.specifiers import SpecifierSet, InvalidSpecifier
 
+from .catalogs import CatalogEntry as BaseCatalogEntry, CatalogStackBase
+from ._init_options import is_ai_skills_enabled
+
 _FALLBACK_CORE_COMMAND_NAMES = frozenset({
     "analyze",
-    "checklist",
     "clarify",
     "constitution",
     "implement",
     "plan",
+    "checklist",
     "specify",
     "tasks",
     "taskstoissues",
@@ -107,13 +110,8 @@ def normalize_priority(value: Any, default: int = 10) -> int:
 
 
 @dataclass
-class CatalogEntry:
+class CatalogEntry(BaseCatalogEntry):
     """Represents a single catalog entry in the catalog stack."""
-    url: str
-    name: str
-    priority: int
-    install_allowed: bool
-    description: str = ""
 
 
 class ExtensionManifest:
@@ -764,7 +762,28 @@ class ExtensionManager:
         if not ignore_file.exists():
             return None
 
-        lines: List[str] = ignore_file.read_text().splitlines()
+        # Pin UTF-8 explicitly: ``Path.read_text`` defaults to the system
+        # locale codec on Windows (cp1252 / gb2312 / cp932), which silently
+        # corrupts multibyte patterns when the file is shared across
+        # machines with different locales. The next line already
+        # normalises backslashes "so Windows-authored files work" — the
+        # codebase already expects Windows authors to write this file.
+        #
+        # A file that is not valid UTF-8 is a user-authoring mistake, so
+        # surface it as ``ValidationError`` with a pointer to the offending
+        # byte — the same pattern ``ExtensionManifest._load_yaml`` uses
+        # for ``extension.yml`` (see ``UnicodeDecodeError`` handler in
+        # this module). Without the wrap, the raw ``UnicodeDecodeError``
+        # would abort installation with a Python traceback instead of a
+        # clear message naming the file.
+        try:
+            raw = ignore_file.read_text(encoding="utf-8")
+        except UnicodeDecodeError as e:
+            raise ValidationError(
+                f".extensionignore is not valid UTF-8: {ignore_file} "
+                f"({e.reason} at byte {e.start})"
+            )
+        lines: List[str] = raw.splitlines()
 
         # Normalise backslashes in patterns so Windows-authored files work
         normalised: List[str] = []
@@ -804,42 +823,67 @@ class ExtensionManager:
     def _get_skills_dir(self) -> Optional[Path]:
         """Return the active skills directory for extension skill registration.
 
-        Reads ``.specify/init-options.json`` to determine whether skills
-        are enabled and which agent was selected, then delegates to
-        the module-level ``_get_skills_dir()`` helper for the concrete path.
+        Delegates to :func:`resolve_active_skills_dir` which reads
+        init-options, applies the Kimi native-skills fallback, and
+        safely creates the directory when ``ai_skills`` is enabled.
 
-        Kimi is treated as a native-skills agent: if ``ai == "kimi"`` and
-        ``.kimi/skills`` exists, extension installs should still propagate
-        command skills even when ``ai_skills`` is false.
-
-        Returns:
-            The skills directory ``Path``, or ``None`` if skills were not
-            enabled and no native-skills fallback applies.
+        Returns ``None`` (instead of raising) when the directory cannot
+        be created due to symlink, containment, or permission issues so
+        that callers can fall back gracefully.
         """
-        from . import load_init_options, _get_skills_dir as resolve_skills_dir
+        from . import (
+            _print_cli_warning,
+            load_init_options,
+            resolve_active_skills_dir,
+        )
+
+        def _ensure_usable(skills_dir: Path) -> Optional[Path]:
+            try:
+                skills_dir.mkdir(parents=True, exist_ok=True)
+                if not skills_dir.is_dir():
+                    raise NotADirectoryError(f"{skills_dir} is not a directory")
+            except (OSError, ValueError) as exc:
+                _print_cli_warning(
+                    "resolve", "skills directory", str(skills_dir), exc,
+                    continuing="Continuing without skill registration.",
+                )
+                return None
+            return skills_dir
+
+        try:
+            skills_dir = resolve_active_skills_dir(self.project_root)
+        except (ValueError, OSError) as exc:
+            _print_cli_warning(
+                "resolve", "skills directory", None, exc,
+                continuing="Continuing without skill registration.",
+            )
+            return None
+        if skills_dir is None:
+            return None
 
         opts = load_init_options(self.project_root)
         if not isinstance(opts, dict):
-            opts = {}
+            return _ensure_usable(skills_dir)
+        selected_ai = opts.get("ai")
+        if not isinstance(selected_ai, str) or not selected_ai:
+            return _ensure_usable(skills_dir)
 
-        agent = opts.get("ai")
-        if not isinstance(agent, str) or not agent:
-            return None
+        from .agents import CommandRegistrar
 
-        ai_skills_enabled = bool(opts.get("ai_skills"))
-        if not ai_skills_enabled and agent != "kimi":
-            return None
-
-        skills_dir = resolve_skills_dir(self.project_root, agent)
-        if not skills_dir.is_dir():
-            return None
-
-        return skills_dir
+        registrar = CommandRegistrar()
+        agent_config = registrar.AGENT_CONFIGS.get(selected_ai)
+        if agent_config and agent_config.get("extension") == "/SKILL.md":
+            agent_skills_dir = registrar._resolve_agent_dir(
+                selected_ai, agent_config, self.project_root
+            )
+            return _ensure_usable(agent_skills_dir)
+        return _ensure_usable(skills_dir)
 
     def _register_extension_skills(
         self,
         manifest: ExtensionManifest,
         extension_dir: Path,
+        link_outputs: bool = False,
     ) -> List[str]:
         """Generate SKILL.md files for extension commands as agent skills.
 
@@ -851,6 +895,8 @@ class ExtensionManager:
         Args:
             manifest: Extension manifest.
             extension_dir: Installed extension directory.
+            link_outputs: If True, create dev-mode symlinks for rendered
+                skill files when supported by the OS.
 
         Returns:
             List of skill names that were created (for registry storage).
@@ -903,9 +949,18 @@ class ExtensionManager:
             # Check if skill already exists before creating the directory
             skill_subdir = skills_dir / skill_name
             skill_file = skill_subdir / "SKILL.md"
-            if skill_file.exists():
-                # Do not overwrite user-customized skills
-                continue
+            cache_root = extension_dir / ".specify-dev" / "extension-skills"
+            cache_file = cache_root / skill_name / "SKILL.md"
+            CommandRegistrar._ensure_inside(cache_file, cache_root)
+            if skill_file.exists() or skill_file.is_symlink():
+                # Do not overwrite user-customized skills, but allow dev-mode
+                # symlinks that point back to this extension's generated cache
+                # to be refreshed on a subsequent dev install.
+                if not (
+                    link_outputs
+                    and self._is_expected_dev_symlink(skill_file, cache_file)
+                ):
+                    continue
 
             # Create skill directory; track whether we created it so we can clean
             # up safely if reading the source file subsequently fails.
@@ -957,11 +1012,35 @@ class ExtensionManager:
                     skill_content
                 )
 
-            skill_file.write_text(skill_content, encoding="utf-8")
+            if link_outputs:
+                try:
+                    cache_file.parent.mkdir(parents=True, exist_ok=True)
+                    cache_file.write_text(skill_content, encoding="utf-8")
+                    if skill_file.exists() or skill_file.is_symlink():
+                        skill_file.unlink()
+                    target = os.path.relpath(cache_file, skill_file.parent)
+                    os.symlink(target, skill_file)
+                except (OSError, ValueError):
+                    if skill_file.is_symlink():
+                        skill_file.unlink()
+                    skill_file.write_text(skill_content, encoding="utf-8")
+            else:
+                skill_file.write_text(skill_content, encoding="utf-8")
             written.append(skill_name)
 
         return written
 
+    @staticmethod
+    def _is_expected_dev_symlink(skill_file: Path, cache_file: Path) -> bool:
+        """Return True when an existing skill file links to its dev cache."""
+        if not skill_file.is_symlink():
+            return False
+
+        try:
+            return skill_file.resolve(strict=False) == cache_file.resolve(strict=False)
+        except OSError:
+            return False
+
     def _unregister_extension_skills(
         self,
         skill_names: List[str],
@@ -1132,6 +1211,8 @@ class ExtensionManager:
         speckit_version: str,
         register_commands: bool = True,
         priority: int = 10,
+        link_commands: bool = False,
+        force: bool = False,
     ) -> ExtensionManifest:
         """Install extension from a local directory.
 
@@ -1140,6 +1221,10 @@ class ExtensionManager:
             speckit_version: Current spec-kit version
             register_commands: If True, register commands with AI agents
             priority: Resolution priority (lower = higher precedence, default 10)
+            link_commands: If True, register rendered agent artifacts as
+                symlinks to a dev cache when supported by the OS.
+            force: If True and extension is already installed, remove it first
+                   before proceeding with installation
 
         Returns:
             Installed extension manifest
@@ -1161,14 +1246,34 @@ class ExtensionManager:
 
         # Check if already installed
         if self.registry.is_installed(manifest.id):
-            raise ExtensionError(
-                f"Extension '{manifest.id}' is already installed. "
-                f"Use 'specify extension remove {manifest.id}' first."
-            )
+            if not force:
+                raise ExtensionError(
+                    f"Extension '{manifest.id}' is already installed. "
+                    f"Use 'specify extension remove {manifest.id}' first, "
+                    f"or retry with --force to overwrite."
+                )
 
         # Reject manifests that would shadow core commands or installed extensions.
         self._validate_install_conflicts(manifest)
 
+        # Remove existing installation AFTER all validations pass so that a
+        # validation failure doesn't leave the user with a half-uninstalled
+        # extension (configs stranded in .backup/).
+        did_remove = False
+        if force and self.registry.is_installed(manifest.id):
+            # Clear any stale backup from a previous remove so that only the
+            # backup produced by the current remove() call is restored later.
+            backup_config_dir = self.extensions_dir / ".backup" / manifest.id
+            # Check is_symlink first: is_dir() follows symlinks so a
+            # symlink-to-directory would pass, but rmtree() raises on them.
+            if backup_config_dir.is_symlink():
+                backup_config_dir.unlink()
+            elif backup_config_dir.is_dir():
+                shutil.rmtree(backup_config_dir)
+            elif backup_config_dir.exists():
+                backup_config_dir.unlink()
+            did_remove = self.remove(manifest.id)
+
         # Install extension
         dest_dir = self.extensions_dir / manifest.id
         if dest_dir.exists():
@@ -1183,17 +1288,43 @@ class ExtensionManager:
             registrar = CommandRegistrar()
             # Register for all detected agents
             registered_commands = registrar.register_commands_for_all_agents(
-                manifest, dest_dir, self.project_root
+                manifest,
+                dest_dir,
+                self.project_root,
+                link_outputs=link_commands,
+                create_missing_active_skills_dir=True,
             )
 
         # Auto-register extension commands as agent skills when --ai-skills
         # was used during project initialisation (feature parity).
-        registered_skills = self._register_extension_skills(manifest, dest_dir)
+        registered_skills = self._register_extension_skills(
+            manifest, dest_dir, link_outputs=link_commands
+        )
 
-        # Register hooks
+        # Register hooks and update installed list in extensions.yml
         hook_executor = HookExecutor(self.project_root)
         hook_executor.register_hooks(manifest)
 
+        # Restore config files from backup when --force triggered a removal.
+        # Only restore *.yml config files to match what remove() backs up,
+        # so unexpected artifacts in .backup/ are not resurrected.
+        if did_remove:
+            backup_config_dir = self.extensions_dir / ".backup" / manifest.id
+            # is_symlink first: is_dir() follows symlinks, but rmtree()
+            # raises on them — and we shouldn't follow symlinks to restore.
+            if backup_config_dir.is_symlink():
+                backup_config_dir.unlink()
+            elif backup_config_dir.is_dir():
+                for cfg_file in backup_config_dir.iterdir():
+                    if cfg_file.is_file() and not cfg_file.is_symlink() and (
+                        cfg_file.name.endswith("-config.yml") or
+                        cfg_file.name.endswith("-config.local.yml")
+                    ):
+                        shutil.copy2(cfg_file, dest_dir / cfg_file.name)
+                shutil.rmtree(backup_config_dir)
+            elif backup_config_dir.exists():
+                backup_config_dir.unlink()
+
         # Update registry
         self.registry.add(manifest.id, {
             "version": manifest.version,
@@ -1212,6 +1343,7 @@ class ExtensionManager:
         zip_path: Path,
         speckit_version: str,
         priority: int = 10,
+        force: bool = False,
     ) -> ExtensionManifest:
         """Install extension from ZIP file.
 
@@ -1219,6 +1351,8 @@ class ExtensionManager:
             zip_path: Path to extension ZIP file
             speckit_version: Current spec-kit version
             priority: Resolution priority (lower = higher precedence, default 10)
+            force: If True and extension is already installed, remove it first
+                   before proceeding with installation
 
         Returns:
             Installed extension manifest
@@ -1265,7 +1399,9 @@ class ExtensionManager:
                 raise ValidationError("No extension.yml found in ZIP file")
 
             # Install from extracted directory
-            return self.install_from_directory(extension_dir, speckit_version, priority=priority)
+            return self.install_from_directory(
+                extension_dir, speckit_version, priority=priority, force=force
+            )
 
     def remove(self, extension_id: str, keep_config: bool = False) -> bool:
         """Remove an installed extension.
@@ -1447,9 +1583,10 @@ class ExtensionManager:
             init_options = {}
 
         active_agent = init_options.get("ai")
+        ai_skills_enabled = is_ai_skills_enabled(init_options)
         skills_mode_active = (
             active_agent == agent_name
-            and bool(init_options.get("ai_skills"))
+            and ai_skills_enabled
             and bool(agent_config)
             and agent_config.get("extension") != "/SKILL.md"
         )
@@ -1624,7 +1761,8 @@ class CommandRegistrar:
         agent_name: str,
         manifest: ExtensionManifest,
         extension_dir: Path,
-        project_root: Path
+        project_root: Path,
+        link_outputs: bool = False,
     ) -> List[str]:
         """Register extension commands for a specific agent."""
         if agent_name not in self.AGENT_CONFIGS:
@@ -1632,20 +1770,25 @@ class CommandRegistrar:
         context_note = f"\n<!-- Extension: {manifest.id} -->\n<!-- Config: .specify/extensions/{manifest.id}/ -->\n"
         return self._registrar.register_commands(
             agent_name, manifest.commands, manifest.id, extension_dir, project_root,
-            context_note=context_note
+            context_note=context_note,
+            link_outputs=link_outputs,
         )
 
     def register_commands_for_all_agents(
         self,
         manifest: ExtensionManifest,
         extension_dir: Path,
-        project_root: Path
+        project_root: Path,
+        link_outputs: bool = False,
+        create_missing_active_skills_dir: bool = False,
     ) -> Dict[str, List[str]]:
         """Register extension commands for all detected agents."""
         context_note = f"\n<!-- Extension: {manifest.id} -->\n<!-- Config: .specify/extensions/{manifest.id}/ -->\n"
         return self._registrar.register_commands_for_all_agents(
             manifest.commands, manifest.id, extension_dir, project_root,
-            context_note=context_note
+            context_note=context_note,
+            link_outputs=link_outputs,
+            create_missing_active_skills_dir=create_missing_active_skills_dir,
         )
 
     def unregister_commands(
@@ -1660,18 +1803,25 @@ class CommandRegistrar:
         self,
         manifest: ExtensionManifest,
         extension_dir: Path,
-        project_root: Path
+        project_root: Path,
+        link_outputs: bool = False,
     ) -> List[str]:
         """Register extension commands for Claude Code agent."""
-        return self.register_commands_for_agent("claude", manifest, extension_dir, project_root)
+        return self.register_commands_for_agent(
+            "claude", manifest, extension_dir, project_root, link_outputs=link_outputs
+        )
 
 
-class ExtensionCatalog:
+class ExtensionCatalog(CatalogStackBase):
     """Manages extension catalog fetching, caching, and searching."""
 
     DEFAULT_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json"
     COMMUNITY_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json"
     CACHE_DURATION = 3600  # 1 hour in seconds
+    CONFIG_FILENAME = "extension-catalogs.yml"
+    ENTRY_CLASS = CatalogEntry
+    ERROR_TYPE = ValidationError
+    VALIDATION_ERROR_TYPE = ValidationError
 
     def __init__(self, project_root: Path):
         """Initialize extension catalog manager.
@@ -1685,27 +1835,6 @@ class ExtensionCatalog:
         self.cache_file = self.cache_dir / "catalog.json"
         self.cache_metadata_file = self.cache_dir / "catalog-metadata.json"
 
-    def _validate_catalog_url(self, url: str) -> None:
-        """Validate that a catalog URL uses HTTPS (localhost HTTP allowed).
-
-        Args:
-            url: URL to validate
-
-        Raises:
-            ValidationError: If URL is invalid or uses non-HTTPS scheme
-        """
-        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 ValidationError(
-                f"Catalog URL must use HTTPS (got {parsed.scheme}://). "
-                "HTTP is only allowed for localhost."
-            )
-        if not parsed.netloc:
-            raise ValidationError("Catalog URL must be a valid URL with a host.")
-
     def _make_request(self, url: str):
         """Build a urllib Request, adding auth headers when a provider matches.
 
@@ -1714,88 +1843,59 @@ class ExtensionCatalog:
         from specify_cli.authentication.http import build_request
         return build_request(url)
 
-    def _open_url(self, url: str, timeout: int = 10):
+    def _open_url(
+        self,
+        url: str,
+        timeout: int = 10,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ):
         """Open a URL with provider-based auth, trying each configured provider.
 
         Delegates to :func:`specify_cli.authentication.http.open_url`.
         """
         from specify_cli.authentication.http import open_url
-        return open_url(url, timeout)
+        return open_url(url, timeout, extra_headers=extra_headers)
 
-    def _load_catalog_config(self, config_path: Path) -> Optional[List[CatalogEntry]]:
-        """Load catalog stack configuration from a YAML file.
+    def _resolve_github_release_asset_api_url(
+        self,
+        download_url: str,
+        timeout: int = 60,
+    ) -> Optional[str]:
+        """Resolve a GitHub release asset URL to its API asset URL."""
+        import urllib.error
+        from urllib.parse import unquote, urlparse
 
-        Args:
-            config_path: Path to extension-catalogs.yml
+        parsed = urlparse(download_url)
+        parts = [unquote(part) for part in parsed.path.strip("/").split("/")]
+        if (
+            parsed.hostname == "api.github.com"
+            and len(parts) >= 6
+            and parts[:1] == ["repos"]
+            and parts[3:5] == ["releases", "assets"]
+        ):
+            return download_url
 
-        Returns:
-            Ordered list of CatalogEntry objects, or None if file doesn't exist.
-
-        Raises:
-            ValidationError: If any catalog entry has an invalid URL,
-                the file cannot be parsed, a priority value is invalid,
-                or the file exists but contains no valid catalog entries
-                (fail-closed for security).
-        """
-        if not config_path.exists():
+        if parsed.hostname != "github.com":
             return None
+
+        if len(parts) < 6 or parts[2:4] != ["releases", "download"]:
+            return None
+
+        owner, repo, tag = parts[0], parts[1], parts[4]
+        asset_name = "/".join(parts[5:])
+        release_url = f"https://api.github.com/repos/{owner}/{repo}/releases/tags/{tag}"
+
         try:
-            data = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
-        except (yaml.YAMLError, OSError, UnicodeError) as e:
-            raise ValidationError(
-                f"Failed to read catalog config {config_path}: {e}"
-            )
-        catalogs_data = data.get("catalogs", [])
-        if not catalogs_data:
-            # File exists but has no catalogs key or empty list - fail closed
-            raise ValidationError(
-                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."
-            )
-        if not isinstance(catalogs_data, list):
-            raise ValidationError(
-                f"Invalid catalog config: 'catalogs' must be a list, got {type(catalogs_data).__name__}"
-            )
-        entries: List[CatalogEntry] = []
-        skipped_entries: List[int] = []
-        for idx, item in enumerate(catalogs_data):
-            if not isinstance(item, dict):
-                raise ValidationError(
-                    f"Invalid catalog entry at index {idx}: expected a mapping, got {type(item).__name__}"
-                )
-            url = str(item.get("url", "")).strip()
-            if not url:
-                skipped_entries.append(idx)
-                continue
-            self._validate_catalog_url(url)
-            try:
-                priority = int(item.get("priority", idx + 1))
-            except (TypeError, ValueError):
-                raise ValidationError(
-                    f"Invalid priority for catalog '{item.get('name', idx + 1)}': "
-                    f"expected integer, got {item.get('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)
-            entries.append(CatalogEntry(
-                url=url,
-                name=str(item.get("name", f"catalog-{idx + 1}")),
-                priority=priority,
-                install_allowed=install_allowed,
-                description=str(item.get("description", "")),
-            ))
-        entries.sort(key=lambda e: e.priority)
-        if not entries:
-            # All entries were invalid (missing URLs) - fail closed for security
-            raise ValidationError(
-                f"Catalog config {config_path} contains {len(catalogs_data)} entries but none have valid URLs "
-                f"(entries at indices {skipped_entries} were skipped). "
-                f"Each catalog entry must have a 'url' field."
-            )
-        return entries
+            with self._open_url(release_url, timeout=timeout) as response:
+                release_data = json.loads(response.read())
+        except (urllib.error.URLError, json.JSONDecodeError):
+            return None
+
+        for asset in release_data.get("assets", []):
+            if asset.get("name") == asset_name and asset.get("url"):
+                return str(asset["url"])
+
+        return None
 
     def get_active_catalogs(self) -> List[CatalogEntry]:
         """Get the ordered list of active catalogs.
@@ -1826,24 +1926,44 @@ class ExtensionCatalog:
                         file=sys.stderr,
                     )
                     self._non_default_catalog_warning_shown = True
-            return [CatalogEntry(url=catalog_url, name="custom", priority=1, install_allowed=True, description="Custom catalog via SPECKIT_CATALOG_URL")]
+            return [
+                self._entry(
+                    url=catalog_url,
+                    name="custom",
+                    priority=1,
+                    install_allowed=True,
+                    description="Custom catalog via SPECKIT_CATALOG_URL",
+                )
+            ]
 
         # 2. Project-level config overrides all defaults
-        project_config_path = self.project_root / ".specify" / "extension-catalogs.yml"
+        project_config_path = self.project_root / ".specify" / self.CONFIG_FILENAME
         catalogs = self._load_catalog_config(project_config_path)
         if catalogs is not None:
             return catalogs
 
         # 3. User-level config
-        user_config_path = Path.home() / ".specify" / "extension-catalogs.yml"
+        user_config_path = Path.home() / ".specify" / self.CONFIG_FILENAME
         catalogs = self._load_catalog_config(user_config_path)
         if catalogs is not None:
             return catalogs
 
         # 4. Built-in default stack
         return [
-            CatalogEntry(url=self.DEFAULT_CATALOG_URL, name="default", priority=1, install_allowed=True, description="Built-in catalog of installable extensions"),
-            CatalogEntry(url=self.COMMUNITY_CATALOG_URL, name="community", priority=2, install_allowed=False, description="Community-contributed extensions (discovery only)"),
+            self._entry(
+                url=self.DEFAULT_CATALOG_URL,
+                name="default",
+                priority=1,
+                install_allowed=True,
+                description="Built-in catalog of installable extensions",
+            ),
+            self._entry(
+                url=self.COMMUNITY_CATALOG_URL,
+                name="community",
+                priority=2,
+                install_allowed=False,
+                description="Community-contributed extensions (discovery only)",
+            ),
         ]
 
     def get_catalog_url(self) -> str:
@@ -2175,9 +2295,15 @@ class ExtensionCatalog:
         zip_filename = f"{extension_id}-{version}.zip"
         zip_path = target_dir / zip_filename
 
+        extra_headers = None
+        resolved_download_url = self._resolve_github_release_asset_api_url(download_url)
+        if resolved_download_url:
+            download_url = resolved_download_url
+            extra_headers = {"Accept": "application/octet-stream"}
+
         # Download the ZIP file
         try:
-            with self._open_url(download_url, timeout=60) as response:
+            with self._open_url(download_url, timeout=60, extra_headers=extra_headers) as response:
                 zip_data = response.read()
 
             zip_path.write_bytes(zip_data)
@@ -2450,10 +2576,12 @@ class HookExecutor:
 
         init_options = self._load_init_options()
         selected_ai = init_options.get("ai")
-        codex_skill_mode = selected_ai == "codex" and bool(init_options.get("ai_skills"))
-        claude_skill_mode = selected_ai == "claude" and bool(init_options.get("ai_skills"))
+        ai_skills_enabled = is_ai_skills_enabled(init_options)
+        codex_skill_mode = selected_ai == "codex" and ai_skills_enabled
+        claude_skill_mode = selected_ai == "claude" and ai_skills_enabled
         kimi_skill_mode = selected_ai == "kimi"
-        cursor_skill_mode = selected_ai == "cursor-agent" and bool(init_options.get("ai_skills"))
+        cursor_skill_mode = selected_ai == "cursor-agent" and ai_skills_enabled
+        cline_mode = selected_ai == "cline"
 
         skill_name = self._skill_name_from_command(command_id)
         if codex_skill_mode and skill_name:
@@ -2464,6 +2592,10 @@ class HookExecutor:
             return f"/skill:{skill_name}"
         if cursor_skill_mode and skill_name:
             return f"/{skill_name}"
+        if cline_mode:
+            from .integrations.cline import format_cline_command_name
+
+            return f"/{format_cline_command_name(command_id)}"
 
         return f"/{command_id}"
 
@@ -2481,7 +2613,32 @@ class HookExecutor:
             }
 
         try:
-            return yaml.safe_load(self.config_file.read_text(encoding="utf-8")) or {}
+            result = yaml.safe_load(self.config_file.read_text(encoding="utf-8"))
+            # Coerce non-dict root (including None for an empty file) to the
+            # fully-normalized default so callers always get guaranteed fields.
+            if not isinstance(result, dict):
+                return {
+                    "installed": [],
+                    "settings": {"auto_execute_hooks": True},
+                    "hooks": {},
+                }
+            # Normalize nested fields so read-only callers like get_hooks_for_event()
+            # never see non-dict hooks or non-list installed (Feedback)
+            if not isinstance(result.get("hooks"), dict):
+                result["hooks"] = {}
+            if not isinstance(result.get("installed"), list):
+                result["installed"] = []
+            if not isinstance(result.get("settings"), dict):
+                result["settings"] = {"auto_execute_hooks": True}
+            # Sanitize hook event values: coerce non-list values to [] and filter
+            # non-dict items so get_hooks_for_event() can safely call .get() (Feedback)
+            for event_key in list(result["hooks"]):
+                event_val = result["hooks"][event_key]
+                if not isinstance(event_val, list):
+                    result["hooks"][event_key] = []
+                else:
+                    result["hooks"][event_key] = [h for h in event_val if isinstance(h, dict)]
+            return result
         except (yaml.YAMLError, OSError, UnicodeError):
             return {
                 "installed": [],
@@ -2501,25 +2658,141 @@ class HookExecutor:
             encoding="utf-8",
         )
 
+    def register_extension(self, extension_id: str):
+        """Add extension to the installed list in project config.
+
+        Args:
+            extension_id: ID of extension to register
+        """
+        config = self.get_project_config()
+
+        # Ensure config is a dict (defensive)
+        if not isinstance(config, dict):
+            config = {}
+
+        raw_installed = config.get("installed")
+        sanitized = self._sanitize_installed_list(raw_installed, add_id=extension_id)
+
+        if sanitized != raw_installed:
+            config["installed"] = sanitized
+            self.save_project_config(config)
+
+    def unregister_extension(self, extension_id: str):
+        """Remove extension from the installed list in project config.
+
+        Args:
+            extension_id: ID of extension to unregister
+        """
+        config = self.get_project_config()
+
+        if not isinstance(config, dict):
+            config = {}
+
+        raw_installed = config.get("installed")
+        sanitized = self._sanitize_installed_list(raw_installed, remove_id=extension_id)
+
+        # Always persist if sanitized state differs from raw config (ensures normalization)
+        if sanitized != raw_installed:
+            config["installed"] = sanitized
+            self.save_project_config(config)
+
+    @staticmethod
+    def _sanitize_installed_list(
+        raw: object,
+        *,
+        add_id: str = "",
+        remove_id: str = "",
+    ) -> list:
+        """Normalize, deduplicate, and optionally add/remove an extension id.
+
+        Shared by register_extension() and unregister_extension() to prevent
+        the two paths from drifting.
+
+        Args:
+            raw: The raw value from config["installed"] (may be non-list).
+            add_id: If non-empty, ensure this id is present (plain-string fallback).
+            remove_id: If non-empty, remove this id from the list.
+
+        Returns:
+            A sanitized, deduplicated, alphabetically-sorted list.
+        """
+        _VALID_ID = re.compile(r'^[a-z0-9-]+$')
+
+        installed = raw if isinstance(raw, list) else []
+
+        # Keep only entries whose resolved id is a non-empty string matching
+        # the extension-id format (^[a-z0-9-]+$), same rule ExtensionManifest enforces.
+        def _valid_entry(x: object) -> bool:
+            if isinstance(x, str):
+                return bool(_VALID_ID.match(x.strip()))
+            if isinstance(x, dict):
+                eid = x.get("id")
+                return isinstance(eid, str) and bool(_VALID_ID.match(eid.strip()))
+            return False
+
+        valid = [x for x in installed if _valid_entry(x)]
+
+        # Deduplicate by id: prefer dict (richer metadata) over plain string
+        seen: dict = {}  # id -> entry (dict preferred over str)
+        for x in valid:
+            eid = x.strip() if isinstance(x, str) else x.get("id", "").strip()
+            if eid not in seen or isinstance(x, dict):
+                seen[eid] = x
+
+        # Validate add_id against the same regex before inserting
+        if add_id and _VALID_ID.match(add_id.strip()) and add_id not in seen:
+            seen[add_id] = add_id
+
+        if remove_id:
+            seen.pop(remove_id, None)
+
+        def _sort_key(x: object) -> str:
+            return x if isinstance(x, str) else x.get("id", "")  # type: ignore[return-value]
+
+        return sorted(seen.values(), key=_sort_key)
+
     def register_hooks(self, manifest: ExtensionManifest):
         """Register extension hooks in project config.
 
         Args:
             manifest: Extension manifest with hooks to register
         """
+        # Always ensure the extension is in the installed list
+        self.register_extension(manifest.id)
+
         if not hasattr(manifest, "hooks") or not manifest.hooks:
             return
 
         config = self.get_project_config()
 
-        # Ensure hooks dict exists
-        if "hooks" not in config:
+        # Ensure config is a dict (defensive)
+        changed = False
+        if not isinstance(config, dict):
+            config = {}
+            changed = True
+
+        # Ensure hooks dict exists and is a mapping
+        if "hooks" not in config or not isinstance(config["hooks"], dict):
             config["hooks"] = {}
+            changed = True
+        else:
+            # Sanitize existing hook lists to prevent crashes in downstream code (Feedback)
+            for h_name in list(config["hooks"].keys()):
+                h_list = config["hooks"][h_name]
+                if not isinstance(h_list, list):
+                    config["hooks"][h_name] = []
+                    changed = True
+                else:
+                    sanitized_h_list = [h for h in h_list if isinstance(h, dict)]
+                    if len(sanitized_h_list) != len(h_list):
+                        config["hooks"][h_name] = sanitized_h_list
+                        changed = True
 
         # Register each hook
         for hook_name, hook_config in manifest.hooks.items():
-            if hook_name not in config["hooks"]:
+            if hook_name not in config["hooks"] or not isinstance(config["hooks"][hook_name], list):
                 config["hooks"][hook_name] = []
+                changed = True
 
             # Add hook entry
             hook_entry = {
@@ -2534,22 +2807,22 @@ class HookExecutor:
                 "condition": hook_config.get("condition"),
             }
 
-            # Check if already registered
-            existing = [
-                h
-                for h in config["hooks"][hook_name]
-                if h.get("extension") == manifest.id
+            # Deduplicate: remove all existing entries for this extension on this
+            # hook event, then append the single canonical entry. This prevents
+            # multiple hooks firing when hand-edited or older versions leave
+            # duplicate entries behind. (Feedback from review)
+            original_list = config["hooks"][hook_name]
+            deduped = [
+                h for h in original_list
+                if not (isinstance(h, dict) and h.get("extension") == manifest.id)
             ]
+            deduped.append(hook_entry)
+            if deduped != original_list:
+                config["hooks"][hook_name] = deduped
+                changed = True
 
-            if not existing:
-                config["hooks"][hook_name].append(hook_entry)
-            else:
-                # Update existing
-                for i, h in enumerate(config["hooks"][hook_name]):
-                    if h.get("extension") == manifest.id:
-                        config["hooks"][hook_name][i] = hook_entry
-
-        self.save_project_config(config)
+        if changed:
+            self.save_project_config(config)
 
     def unregister_hooks(self, extension_id: str):
         """Remove extension hooks from project config.
@@ -2557,17 +2830,30 @@ class HookExecutor:
         Args:
             extension_id: ID of extension to unregister
         """
+        # Always remove from installed list (Feedback from review)
+        self.unregister_extension(extension_id)
+
         config = self.get_project_config()
 
-        if "hooks" not in config:
+        if not isinstance(config, dict):
+            config = {}
+            # We don't save yet, as there are no hooks to unregister,
+            # but unregister_extension above might have already saved a normalized config.
+            return
+
+        if "hooks" not in config or not isinstance(config["hooks"], dict):
             return
 
         # Remove hooks for this extension
-        for hook_name in config["hooks"]:
+        for hook_name in list(config["hooks"].keys()):
+            hook_list = config["hooks"][hook_name]
+            if not isinstance(hook_list, list):
+                config["hooks"][hook_name] = []
+                continue
             config["hooks"][hook_name] = [
                 h
-                for h in config["hooks"][hook_name]
-                if h.get("extension") != extension_id
+                for h in hook_list
+                if isinstance(h, dict) and h.get("extension") != extension_id
             ]
 
         # Clean up empty hook arrays

src/specify_cli/integration_state.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
@@ -11,6 +12,67 @@ INTEGRATION_JSON = ".specify/integration.json"
 INTEGRATION_STATE_SCHEMA = 1
 
 
+@dataclass(frozen=True)
+class IntegrationReadError:
+    """Structured failure from :func:`try_read_integration_json`.
+
+    Callers map ``kind`` to whatever surface they need (loud CLI error,
+    silent fallback, etc.) without re-implementing the parse/validation logic.
+    """
+
+    kind: str  # "decode", "os", "not_object", "schema_too_new"
+    detail: str = ""
+    schema: int | None = None
+
+
+def try_read_integration_json(
+    project_root: Path,
+) -> tuple[dict[str, Any] | None, IntegrationReadError | None]:
+    """Parse ``.specify/integration.json`` without raising.
+
+    Returns ``(normalized_state, None)`` on success, ``(None, None)`` when the
+    file does not exist, or ``(None, error)`` for any parse / validation
+    failure. This is the single low-level reader; both the CLI's loud
+    ``_read_integration_json`` and the workflow engine's silent
+    ``_load_project_integration`` consume it so the schema guard and parse
+    logic cannot drift between them.
+    """
+    path = project_root / INTEGRATION_JSON
+    # Avoid Path.exists() / Path.is_file() as a pre-check: both return False
+    # on some OSErrors (e.g. permission errors during stat), which would
+    # silently treat an unreadable-but-present file as missing. Attempt the
+    # read directly and distinguish FileNotFoundError (genuinely absent) from
+    # other OSErrors (which become loud errors via the IntegrationReadError
+    # path).
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None, None
+    except IsADirectoryError as exc:
+        return None, IntegrationReadError(
+            kind="os",
+            detail=f"{path} exists but is not a regular file: {exc}",
+        )
+    except UnicodeDecodeError as exc:
+        return None, IntegrationReadError(kind="decode", detail=str(exc))
+    except OSError as exc:
+        return None, IntegrationReadError(kind="os", detail=str(exc))
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        return None, IntegrationReadError(kind="decode", detail=str(exc))
+    if not isinstance(data, dict):
+        return None, IntegrationReadError(kind="not_object", detail=type(data).__name__)
+    schema = data.get("integration_state_schema")
+    if (
+        isinstance(schema, int)
+        and not isinstance(schema, bool)
+        and schema > INTEGRATION_STATE_SCHEMA
+    ):
+        return None, IntegrationReadError(kind="schema_too_new", schema=schema)
+    return normalize_integration_state(data), None
+
+
 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():

src/specify_cli/integrations/__init__.py

@@ -52,6 +52,7 @@ def _register_builtins() -> None:
     from .auggie import AuggieIntegration
     from .bob import BobIntegration
     from .claude import ClaudeIntegration
+    from .cline import ClineIntegration
     from .codebuddy import CodebuddyIntegration
     from .codex import CodexIntegration
     from .copilot import CopilotIntegration
@@ -61,6 +62,7 @@ def _register_builtins() -> None:
     from .gemini import GeminiIntegration
     from .generic import GenericIntegration
     from .goose import GooseIntegration
+    from .hermes import HermesIntegration
     from .iflow import IflowIntegration
     from .junie import JunieIntegration
     from .kilocode import KilocodeIntegration
@@ -72,6 +74,7 @@ def _register_builtins() -> None:
     from .qodercli import QodercliIntegration
     from .qwen import QwenIntegration
     from .roo import RooIntegration
+    from .rovodev import RovodevIntegration
     from .shai import ShaiIntegration
     from .tabnine import TabnineIntegration
     from .trae import TraeIntegration
@@ -84,6 +87,7 @@ def _register_builtins() -> None:
     _register(AuggieIntegration())
     _register(BobIntegration())
     _register(ClaudeIntegration())
+    _register(ClineIntegration())
     _register(CodebuddyIntegration())
     _register(CodexIntegration())
     _register(CopilotIntegration())
@@ -93,6 +97,7 @@ def _register_builtins() -> None:
     _register(GeminiIntegration())
     _register(GenericIntegration())
     _register(GooseIntegration())
+    _register(HermesIntegration())
     _register(IflowIntegration())
     _register(JunieIntegration())
     _register(KilocodeIntegration())
@@ -104,6 +109,7 @@ def _register_builtins() -> None:
     _register(QodercliIntegration())
     _register(QwenIntegration())
     _register(RooIntegration())
+    _register(RovodevIntegration())
     _register(ShaiIntegration())
     _register(TabnineIntegration())
     _register(TraeIntegration())

src/specify_cli/integrations/_commands.py

@@ -0,0 +1,34 @@
+"""specify integration * commands — app objects and register() entry point."""
+from __future__ import annotations
+
+import typer
+
+from .._assets import get_speckit_version  # noqa: F401 — re-exported for monkeypatching in tests
+
+# Re-export helpers used by commands/init.py and tests
+from ._helpers import (  # noqa: F401
+    _cli_error_detail,
+    _cli_phase_label,
+    _parse_integration_options,
+    _write_integration_json,
+)
+
+integration_app = typer.Typer(
+    name="integration",
+    help="Manage coding agent integrations",
+    add_completion=False,
+)
+
+integration_catalog_app = typer.Typer(
+    name="catalog",
+    help="Manage integration catalog sources",
+    add_completion=False,
+)
+integration_app.add_typer(integration_catalog_app, name="catalog")
+
+
+def register(app: typer.Typer) -> None:
+    from . import _install_commands  # noqa: F401 — registers handlers via decorators
+    from . import _migrate_commands  # noqa: F401
+    from . import _query_commands    # noqa: F401
+    app.add_typer(integration_app, name="integration")

src/specify_cli/integrations/_helpers.py

@@ -0,0 +1,402 @@
+"""specify integration helpers — internal utilities shared across command modules."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from .._agent_config import SCRIPT_TYPE_CHOICES
+from .._console import console
+from ..integration_runtime import (
+    invoke_separator_for_integration as _invoke_separator_for_integration,
+    resolve_integration_options as _resolve_integration_options_impl,
+    with_integration_setting as _with_integration_setting,
+)
+from ..integration_state import (
+    INTEGRATION_JSON,
+    INTEGRATION_STATE_SCHEMA,
+    integration_setting as _integration_setting,
+    try_read_integration_json as _try_read_integration_json,
+    write_integration_json as _write_integration_json_file,
+)
+
+
+def _get_speckit_version() -> str:
+    """Return the current Spec Kit version.
+
+    Resolved lazily through ``_commands.get_speckit_version`` so that tests
+    that monkeypatch ``specify_cli.integrations._commands.get_speckit_version``
+    still affect helpers called from the command handlers.
+    """
+    from . import _commands  # noqa: PLC0415 — intentional late import to avoid circular + enable patching
+    return _commands.get_speckit_version()
+
+
+# ---------------------------------------------------------------------------
+# JSON read / write helpers
+# ---------------------------------------------------------------------------
+
+def _read_integration_json(project_root: Path) -> dict[str, Any]:
+    """Load ``.specify/integration.json``. Returns normalized state when present.
+
+    Delegates the parse / schema-guard logic to the shared
+    :func:`_try_read_integration_json` helper so the CLI and workflow engine
+    cannot drift on validation rules. Each error variant is translated into
+    the existing loud-fail UX (console message + ``typer.Exit(1)``).
+    """
+    path = project_root / INTEGRATION_JSON
+    state, error = _try_read_integration_json(project_root)
+    if error is None:
+        return state or {}
+    if error.kind == "decode":
+        console.print(f"[red]Error:[/red] {path} contains invalid JSON or is not valid UTF-8.")
+        console.print(f"Please fix or delete {INTEGRATION_JSON} and retry.")
+        console.print(f"[dim]Details:[/dim] {error.detail}")
+    elif error.kind == "os":
+        console.print(f"[red]Error:[/red] Could not read {path}.")
+        console.print(f"Please fix file permissions or delete {INTEGRATION_JSON} and retry.")
+        console.print(f"[dim]Details:[/dim] {error.detail}")
+    elif error.kind == "not_object":
+        console.print(
+            f"[red]Error:[/red] {path} must contain a JSON object, got {error.detail}."
+        )
+        console.print(f"Please fix or delete {INTEGRATION_JSON} and retry.")
+    elif error.kind == "schema_too_new":
+        console.print(
+            f"[red]Error:[/red] {path} uses integration state schema {error.schema}, "
+            f"but this CLI only supports schema {INTEGRATION_STATE_SCHEMA}."
+        )
+        console.print("Please upgrade Spec Kit before modifying integrations.")
+    raise typer.Exit(1)
+
+
+def _write_integration_json(
+    project_root: Path,
+    integration_key: str | None,
+    installed_integrations: list[str] | None = None,
+    integration_settings: dict[str, dict[str, Any]] | None = None,
+) -> None:
+    """Write ``.specify/integration.json`` with legacy-compatible state."""
+    _write_integration_json_file(
+        project_root,
+        version=_get_speckit_version(),
+        integration_key=integration_key,
+        installed_integrations=installed_integrations,
+        settings=integration_settings,
+    )
+
+
+# ---------------------------------------------------------------------------
+# init-options.json helpers
+# ---------------------------------------------------------------------------
+
+def _refresh_init_options_speckit_version(project_root: Path) -> None:
+    """Refresh only the Spec Kit version recorded in init-options.json."""
+    from .. import load_init_options, save_init_options
+    opts = load_init_options(project_root)
+    if not isinstance(opts, dict) or not opts:
+        return
+    opts["speckit_version"] = _get_speckit_version()
+    save_init_options(project_root, opts)
+
+
+def _clear_init_options_for_integration(project_root: Path, integration_key: str) -> None:
+    """Clear active integration keys from init-options.json when they match.
+
+    Also clears ``context_file`` from the agent-context extension config so
+    no stale path is left behind when the integration is uninstalled.
+    """
+    from .. import (
+        _AGENT_CTX_EXT_CONFIG,
+        _update_agent_context_config_file,
+        load_init_options,
+        save_init_options,
+    )
+    opts = load_init_options(project_root)
+    has_legacy_context_keys = ("context_file" in opts) or ("context_markers" in opts)
+    # Remove legacy fields that older versions may have written.
+    opts.pop("context_file", None)
+    opts.pop("context_markers", None)
+
+    if opts.get("integration") == integration_key or opts.get("ai") == integration_key:
+        opts.pop("integration", None)
+        opts.pop("ai", None)
+        opts.pop("ai_skills", None)
+        save_init_options(project_root, opts)
+        # Clear context_file in the extension config if it already exists.
+        # Avoid creating the config (and parent dirs) in projects where the
+        # agent-context extension was never installed.
+        ext_cfg_path = project_root / _AGENT_CTX_EXT_CONFIG
+        if ext_cfg_path.exists():
+            _update_agent_context_config_file(
+                project_root, "", preserve_markers=True
+            )
+    elif has_legacy_context_keys:
+        save_init_options(project_root, opts)
+
+
+def _remove_integration_json(project_root: Path) -> None:
+    """Remove ``.specify/integration.json`` if it exists."""
+    path = project_root / INTEGRATION_JSON
+    if path.exists():
+        path.unlink()
+
+
+# ---------------------------------------------------------------------------
+# Error sentinels
+# ---------------------------------------------------------------------------
+
+_MANIFEST_READ_ERRORS = (ValueError, FileNotFoundError, OSError, UnicodeDecodeError)
+
+
+class _SharedTemplateRefreshError(RuntimeError):
+    """Raised when default integration metadata should not be persisted."""
+
+
+# ---------------------------------------------------------------------------
+# Script type resolution
+# ---------------------------------------------------------------------------
+
+def _normalize_script_type(script_type: str, source: str) -> str:
+    """Normalize and validate a script type from CLI/config sources."""
+    normalized = script_type.strip().lower()
+    if normalized in SCRIPT_TYPE_CHOICES:
+        return normalized
+    console.print(
+        f"[red]Error:[/red] Invalid script type {script_type!r} from {source}. "
+        f"Expected one of: {', '.join(sorted(SCRIPT_TYPE_CHOICES.keys()))}."
+    )
+    raise typer.Exit(1)
+
+
+def _resolve_script_type(project_root: Path, script_type: str | None) -> str:
+    """Resolve the script type from the CLI flag or init-options.json."""
+    from .. import load_init_options
+    if script_type:
+        return _normalize_script_type(script_type, "--script")
+    opts = load_init_options(project_root)
+    saved = opts.get("script")
+    if isinstance(saved, str) and saved.strip():
+        return _normalize_script_type(saved, ".specify/init-options.json")
+    return "ps" if os.name == "nt" else "sh"
+
+
+def _resolve_integration_script_type(
+    project_root: Path,
+    state: dict[str, Any],
+    key: str,
+    script_type: str | None = None,
+) -> str:
+    """Resolve script type for an integration, preferring stored settings."""
+    if script_type:
+        return _normalize_script_type(script_type, "--script")
+
+    stored = _integration_setting(state, key).get("script")
+    if isinstance(stored, str) and stored.strip():
+        return _normalize_script_type(stored, f"{INTEGRATION_JSON} integration_settings.{key}.script")
+
+    return _resolve_script_type(project_root, None)
+
+
+# ---------------------------------------------------------------------------
+# Integration options
+# ---------------------------------------------------------------------------
+
+def _parse_integration_options(integration: Any, raw_options: str) -> dict[str, Any] | None:
+    """Parse --integration-options string into a dict matching the integration's declared options.
+
+    Returns ``None`` when no options are provided.
+    """
+    import shlex
+    parsed: dict[str, Any] = {}
+    tokens = shlex.split(raw_options)
+    declared_options = list(integration.options())
+    declared = {opt.name.lstrip("-"): opt for opt in declared_options}
+    allowed = ", ".join(sorted(opt.name for opt in declared_options))
+    i = 0
+    while i < len(tokens):
+        token = tokens[i]
+        if not token.startswith("-"):
+            console.print(f"[red]Error:[/red] Unexpected integration option value '{token}'.")
+            if allowed:
+                console.print(f"Allowed options: {allowed}")
+            raise typer.Exit(1)
+        name = token.lstrip("-")
+        value: str | None = None
+        # Handle --name=value syntax
+        if "=" in name:
+            name, value = name.split("=", 1)
+        opt = declared.get(name)
+        if not opt:
+            console.print(f"[red]Error:[/red] Unknown integration option '{token}'.")
+            if allowed:
+                console.print(f"Allowed options: {allowed}")
+            raise typer.Exit(1)
+        key = name.replace("-", "_")
+        if opt.is_flag:
+            if value is not None:
+                console.print(f"[red]Error:[/red] Option '{opt.name}' is a flag and does not accept a value.")
+                raise typer.Exit(1)
+            parsed[key] = True
+            i += 1
+        elif value is not None:
+            parsed[key] = value
+            i += 1
+        elif i + 1 < len(tokens) and not tokens[i + 1].startswith("-"):
+            parsed[key] = tokens[i + 1]
+            i += 2
+        else:
+            console.print(f"[red]Error:[/red] Option '{opt.name}' requires a value.")
+            raise typer.Exit(1)
+    return parsed or None
+
+
+def _resolve_integration_options(
+    integration: Any,
+    state: dict[str, Any],
+    key: str,
+    raw_options: str | None,
+) -> tuple[str | None, dict[str, Any] | None]:
+    """Resolve raw and parsed options for an integration operation."""
+    return _resolve_integration_options_impl(
+        integration,
+        state,
+        key,
+        raw_options,
+        parse_options=_parse_integration_options,
+    )
+
+
+def _update_init_options_for_integration(
+    project_root: Path,
+    integration: Any,
+    script_type: str | None = None,
+) -> None:
+    """Update init-options.json and the agent-context extension config to
+    reflect *integration* as the active one.
+
+    ``context_file`` and ``context_markers`` are stored in the agent-context
+    extension config (``.specify/extensions/agent-context/agent-context-config.yml``),
+    not in ``init-options.json``.  Existing user-customised markers are
+    always preserved when the config already exists; invalid marker values
+    are silently ignored at runtime by ``_resolve_context_markers()`` which
+    falls back to the class-level defaults.
+    """
+    from .. import (
+        _AGENT_CTX_EXT_CONFIG,
+        _update_agent_context_config_file,
+        load_init_options,
+        save_init_options,
+    )
+    from .base import SkillsIntegration
+    opts = load_init_options(project_root)
+    opts["integration"] = integration.key
+    opts["ai"] = integration.key
+    # Remove legacy fields if they were written by an older version.
+    opts.pop("context_file", None)
+    opts.pop("context_markers", None)
+    opts["speckit_version"] = _get_speckit_version()
+    if script_type:
+        opts["script"] = script_type
+    if isinstance(integration, SkillsIntegration) or getattr(integration, "_skills_mode", False):
+        opts["ai_skills"] = True
+    else:
+        opts.pop("ai_skills", None)
+
+    # Update the agent-context extension config BEFORE init-options.json
+    # so a failure here doesn't leave init-options partially updated.
+    ext_cfg_path = project_root / _AGENT_CTX_EXT_CONFIG
+    if ext_cfg_path.exists():
+        _update_agent_context_config_file(
+            project_root,
+            integration.context_file,
+            preserve_markers=True,
+        )
+    elif integration.context_file:
+        # Extension config doesn't exist yet (extension not installed).
+        # Write defaults so scripts have something to read.
+        _update_agent_context_config_file(
+            project_root,
+            integration.context_file,
+            preserve_markers=False,
+        )
+
+    save_init_options(project_root, opts)
+
+
+# ---------------------------------------------------------------------------
+# Default integration persistence
+# ---------------------------------------------------------------------------
+
+def _set_default_integration(
+    project_root: Path,
+    state: dict[str, Any],
+    key: str,
+    integration: Any,
+    installed_keys: list[str],
+    *,
+    script_type: str | None = None,
+    raw_options: str | None = None,
+    parsed_options: dict[str, Any] | None = None,
+    refresh_templates: bool = True,
+    refresh_templates_force: bool = False,
+    refresh_hint: str | None = None,
+) -> None:
+    """Persist *key* as default and align active runtime metadata."""
+    from .. import _install_shared_infra
+    resolved_script = _resolve_integration_script_type(project_root, state, key, script_type)
+    settings = _with_integration_setting(
+        state,
+        key,
+        integration,
+        script_type=resolved_script,
+        raw_options=raw_options,
+        parsed_options=parsed_options,
+    )
+
+    if refresh_templates:
+        try:
+            _install_shared_infra(
+                project_root,
+                resolved_script,
+                invoke_separator=_invoke_separator_for_integration(
+                    integration, {"integration_settings": settings}, key, parsed_options
+                ),
+                force=refresh_templates_force,
+                refresh_managed=True,
+                refresh_hint=refresh_hint,
+            )
+        except (ValueError, OSError) as exc:
+            raise _SharedTemplateRefreshError(
+                f"Failed to refresh shared infrastructure for '{key}': {exc}"
+            ) from exc
+
+    _write_integration_json(project_root, key, installed_keys, settings)
+    _update_init_options_for_integration(project_root, integration, script_type=resolved_script)
+
+
+def _set_default_integration_or_exit(*args: Any, **kwargs: Any) -> None:
+    try:
+        _set_default_integration(*args, **kwargs)
+    except _SharedTemplateRefreshError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# CLI formatting helpers (re-exported from _commands.py)
+# ---------------------------------------------------------------------------
+
+def _cli_error_detail(exc: BaseException) -> str:
+    """Return a compact one-line exception detail for CLI output."""
+    return str(exc).replace("\n", " ").strip() or exc.__class__.__name__
+
+
+def _cli_phase_label(phase: str, target_kind: str, target: str | None = None) -> str:
+    """Format a stable operation label for user-visible diagnostics."""
+    label = f"{phase} {target_kind}".strip()
+    if target:
+        label = f"{label} '{target}'"
+    return label

src/specify_cli/integrations/_install_commands.py

@@ -0,0 +1,309 @@
+"""specify integration install / uninstall command handlers."""
+from __future__ import annotations
+
+import os
+
+import typer
+
+from .._console import console
+from .._utils import _display_project_path
+from ..integration_runtime import (
+    invoke_separator_for_integration as _invoke_separator_for_integration,
+    with_integration_setting as _with_integration_setting,
+)
+from ..integration_state import (
+    dedupe_integration_keys as _dedupe_integration_keys,
+    default_integration_key as _default_integration_key,
+    installed_integration_keys as _installed_integration_keys,
+    integration_settings as _integration_settings,
+)
+from ._commands import integration_app
+from ._helpers import (
+    _MANIFEST_READ_ERRORS,
+    _clear_init_options_for_integration,
+    _cli_error_detail,
+    _cli_phase_label,
+    _get_speckit_version,
+    _read_integration_json,
+    _refresh_init_options_speckit_version,
+    _remove_integration_json,
+    _resolve_integration_options,
+    _resolve_script_type,
+    _set_default_integration_or_exit,
+    _update_init_options_for_integration,
+    _write_integration_json,
+)
+
+
+@integration_app.command("install")
+def integration_install(
+    key: str = typer.Argument(help="Integration key to install (e.g. claude, copilot)"),
+    script: str | None = typer.Option(None, "--script", help="Script type: sh or ps (default: from init-options.json or platform default)"),
+    force: bool = typer.Option(False, "--force", help="Allow multi-install when integrations are not declared safe"),
+    integration_options: str | None = typer.Option(None, "--integration-options", help='Options for the integration (e.g. --integration-options="--commands-dir .myagent/cmds")'),
+):
+    """Install an integration into an existing project."""
+    from . import INTEGRATION_REGISTRY, get_integration
+    from .manifest import IntegrationManifest
+    from .. import _require_specify_project, _install_shared_infra_or_exit
+
+    project_root = _require_specify_project()
+    integration = get_integration(key)
+    if integration is None:
+        console.print(f"[red]Error:[/red] Unknown integration '{key}'")
+        available = ", ".join(sorted(INTEGRATION_REGISTRY.keys()))
+        console.print(f"Available integrations: {available}")
+        raise typer.Exit(1)
+
+    current = _read_integration_json(project_root)
+    default_key = _default_integration_key(current)
+    installed_keys = _installed_integration_keys(current)
+
+    if key in installed_keys:
+        console.print(f"[yellow]Integration '{key}' is already installed.[/yellow]")
+        if default_key == key:
+            console.print("It is already the default integration.")
+        else:
+            console.print(
+                f"To make it the default integration, run "
+                f"[cyan]specify integration use {key}[/cyan]."
+            )
+        console.print(
+            f"To refresh its managed files or options, run "
+            f"[cyan]specify integration upgrade {key}[/cyan]."
+        )
+        console.print("No files were changed.")
+        raise typer.Exit(0)
+
+    if installed_keys and not force:
+        unsafe_keys = []
+        for installed_key in installed_keys:
+            installed_integration = get_integration(installed_key)
+            if not installed_integration or not getattr(installed_integration, "multi_install_safe", False):
+                unsafe_keys.append(installed_key)
+        if unsafe_keys or not getattr(integration, "multi_install_safe", False):
+            console.print(
+                f"[red]Error:[/red] Installed integrations: {', '.join(installed_keys)}."
+            )
+            if default_key:
+                console.print(f"Default integration: [cyan]{default_key}[/cyan].")
+            console.print(
+                "Installing multiple integrations is only automatic when all involved "
+                "integrations are declared multi-install safe."
+            )
+            console.print(
+                f"To replace the default integration, run "
+                f"[cyan]specify integration switch {key}[/cyan]."
+            )
+            console.print(
+                f"To install '{key}' alongside the existing integrations anyway, "
+                "retry the same install command with [cyan]--force[/cyan]."
+            )
+            raise typer.Exit(1)
+
+    selected_script = _resolve_script_type(project_root, script)
+
+    # Build parsed options from --integration-options so the integration
+    # can determine its effective invoke separator before shared infra
+    # is installed.
+    raw_options, parsed_options = _resolve_integration_options(
+        integration, current, key, integration_options
+    )
+
+    # Ensure shared infrastructure is present (safe to run unconditionally;
+    # _install_shared_infra merges missing files without overwriting).
+    infra_integration = integration
+    infra_key = key
+    infra_parsed = parsed_options
+    if default_key:
+        default_integration = get_integration(default_key)
+        if default_integration is not None:
+            infra_integration = default_integration
+            infra_key = default_key
+            _, infra_parsed = _resolve_integration_options(
+                default_integration, current, default_key, None
+            )
+    _install_shared_infra_or_exit(
+        project_root,
+        selected_script,
+        invoke_separator=_invoke_separator_for_integration(
+            infra_integration, current, infra_key, infra_parsed
+        ),
+    )
+    if os.name != "nt":
+        from .. import ensure_executable_scripts
+        ensure_executable_scripts(project_root)
+
+    manifest = IntegrationManifest(
+        integration.key, project_root, version=_get_speckit_version()
+    )
+
+    try:
+        integration.setup(
+            project_root, manifest,
+            parsed_options=parsed_options,
+            script_type=selected_script,
+            raw_options=raw_options,
+        )
+        manifest.save()
+        new_installed = _dedupe_integration_keys([*installed_keys, integration.key])
+        new_default = default_key or integration.key
+        settings = _with_integration_setting(
+            current,
+            integration.key,
+            integration,
+            script_type=selected_script,
+            raw_options=raw_options,
+            parsed_options=parsed_options,
+        )
+        _write_integration_json(project_root, new_default, new_installed, settings)
+        if new_default == integration.key:
+            _update_init_options_for_integration(project_root, integration, script_type=selected_script)
+        else:
+            _refresh_init_options_speckit_version(project_root)
+
+    except Exception as exc:
+        # Attempt rollback of any files written by setup
+        try:
+            integration.teardown(project_root, manifest, force=True)
+        except Exception as rollback_err:
+            # Suppress so the original setup error remains the primary failure
+            from .. import _print_cli_warning
+            _print_cli_warning(
+                "rollback",
+                "integration",
+                key,
+                rollback_err,
+                continuing="The original install failure is still the primary error.",
+            )
+        if installed_keys:
+            _write_integration_json(
+                project_root, default_key, installed_keys, _integration_settings(current)
+            )
+        else:
+            _remove_integration_json(project_root)
+        console.print(
+            f"[red]Error:[/red] Failed to {_cli_phase_label('install', 'integration', key)}: "
+            f"{_cli_error_detail(exc)}"
+        )
+        raise typer.Exit(1)
+
+    name = (integration.config or {}).get("name", key)
+    console.print(f"\n[green]✓[/green] Integration '{name}' installed successfully")
+    if default_key:
+        console.print(f"[dim]Default integration remains:[/dim] [cyan]{default_key}[/cyan]")
+
+
+@integration_app.command("uninstall")
+def integration_uninstall(
+    key: str = typer.Argument(None, help="Integration key to uninstall (default: current integration)"),
+    force: bool = typer.Option(False, "--force", help="Remove files even if modified"),
+):
+    """Uninstall an integration, safely preserving modified files."""
+    from . import get_integration
+    from .manifest import IntegrationManifest
+    from .. import _require_specify_project
+
+    project_root = _require_specify_project()
+    current = _read_integration_json(project_root)
+    default_key = _default_integration_key(current)
+    installed_keys = _installed_integration_keys(current)
+
+    if key is None:
+        if not default_key:
+            console.print("[yellow]No integration is currently installed.[/yellow]")
+            raise typer.Exit(0)
+        key = default_key
+
+    if key not in installed_keys:
+        console.print(f"[red]Error:[/red] Integration '{key}' is not installed.")
+        raise typer.Exit(1)
+
+    integration = get_integration(key)
+
+    manifest_path = project_root / ".specify" / "integrations" / f"{key}.manifest.json"
+    if not manifest_path.exists():
+        console.print(f"[yellow]No manifest found for integration '{key}'. Nothing to uninstall.[/yellow]")
+        remaining = [installed for installed in installed_keys if installed != key]
+        new_default = default_key if default_key != key else (remaining[0] if remaining else None)
+        if remaining:
+            if default_key == key and new_default and (new_integration := get_integration(new_default)):
+                raw_options, parsed_options = _resolve_integration_options(
+                    new_integration, current, new_default, None
+                )
+                _set_default_integration_or_exit(
+                    project_root,
+                    current,
+                    new_default,
+                    new_integration,
+                    remaining,
+                    raw_options=raw_options,
+                    parsed_options=parsed_options,
+                )
+            else:
+                _write_integration_json(
+                    project_root, new_default, remaining, _integration_settings(current)
+                )
+        else:
+            _remove_integration_json(project_root)
+        if default_key == key:
+            _clear_init_options_for_integration(project_root, key)
+        raise typer.Exit(0)
+
+    try:
+        manifest = IntegrationManifest.load(key, project_root)
+    except _MANIFEST_READ_ERRORS as exc:
+        console.print(f"[red]Error:[/red] Integration manifest for '{key}' is unreadable.")
+        console.print(f"Manifest: {manifest_path}")
+        console.print(
+            f"To recover, delete the unreadable manifest, run "
+            f"[cyan]specify integration uninstall {key}[/cyan] to clear stale metadata, "
+            f"then run [cyan]specify integration install {key}[/cyan] to regenerate."
+        )
+        console.print(f"[dim]Details:[/dim] {exc}")
+        raise typer.Exit(1)
+
+    if not integration:
+        console.print(
+            f"[yellow]Warning:[/yellow] Integration '{key}' not found "
+            "in registry. Falling back to manifest-based cleanup."
+        )
+        removed, skipped = manifest.uninstall(project_root, force=force)
+    else:
+        removed, skipped = integration.teardown(project_root, manifest, force=force)
+
+    remaining = [installed for installed in installed_keys if installed != key]
+    new_default = default_key if default_key != key else (remaining[0] if remaining else None)
+    if remaining:
+        if default_key == key and new_default and (new_integration := get_integration(new_default)):
+            raw_options, parsed_options = _resolve_integration_options(
+                new_integration, current, new_default, None
+            )
+            _set_default_integration_or_exit(
+                project_root,
+                current,
+                new_default,
+                new_integration,
+                remaining,
+                raw_options=raw_options,
+                parsed_options=parsed_options,
+            )
+        else:
+            _write_integration_json(
+                project_root, new_default, remaining, _integration_settings(current)
+            )
+    else:
+        _remove_integration_json(project_root)
+
+    if default_key == key:
+        _clear_init_options_for_integration(project_root, key)
+
+    name = (integration.config or {}).get("name", key) if integration else key
+    console.print(f"\n[green]✓[/green] Integration '{name}' uninstalled")
+    if removed:
+        console.print(f"  Removed {len(removed)} file(s)")
+    if skipped:
+        console.print(f"\n[yellow]⚠[/yellow]  {len(skipped)} modified file(s) were preserved:")
+        for path in skipped:
+            rel = _display_project_path(project_root, path)
+            console.print(f"    {rel}")

src/specify_cli/integrations/_migrate_commands.py

@@ -0,0 +1,490 @@
+"""specify integration switch / upgrade command handlers."""
+from __future__ import annotations
+
+import os
+
+import typer
+
+from .._console import console
+from ..integration_runtime import (
+    invoke_separator_for_integration as _invoke_separator_for_integration,
+    with_integration_setting as _with_integration_setting,
+)
+from ..integration_state import (
+    dedupe_integration_keys as _dedupe_integration_keys,
+    default_integration_key as _default_integration_key,
+    installed_integration_keys as _installed_integration_keys,
+    integration_settings as _integration_settings,
+)
+from ._commands import integration_app
+from ._helpers import (
+    _MANIFEST_READ_ERRORS,
+    _SharedTemplateRefreshError,
+    _clear_init_options_for_integration,
+    _cli_error_detail,
+    _cli_phase_label,
+    _get_speckit_version,
+    _read_integration_json,
+    _refresh_init_options_speckit_version,
+    _remove_integration_json,
+    _resolve_integration_options,
+    _resolve_integration_script_type,
+    _resolve_script_type,
+    _set_default_integration,
+    _set_default_integration_or_exit,
+    _update_init_options_for_integration,
+    _write_integration_json,
+)
+
+
+@integration_app.command("switch")
+def integration_switch(
+    target: str = typer.Argument(help="Integration key to switch to"),
+    script: str | None = typer.Option(None, "--script", help="Script type: sh or ps (default: from init-options.json or platform default)"),
+    force: bool = typer.Option(False, "--force", help="Force removal of modified files during uninstall of the previous integration"),
+    refresh_shared_infra: bool = typer.Option(False, "--refresh-shared-infra", help="Also overwrite shared infrastructure files even if you customized them (otherwise customizations are preserved)"),
+    integration_options: str | None = typer.Option(None, "--integration-options", help='Options for the target integration'),
+):
+    """Switch from the current integration to a different one."""
+    from . import INTEGRATION_REGISTRY, get_integration
+    from .manifest import IntegrationManifest
+    from .. import _print_cli_warning, _require_specify_project, _install_shared_infra_or_exit
+
+    project_root = _require_specify_project()
+    target_integration = get_integration(target)
+    if target_integration is None:
+        console.print(f"[red]Error:[/red] Unknown integration '{target}'")
+        available = ", ".join(sorted(INTEGRATION_REGISTRY.keys()))
+        console.print(f"Available integrations: {available}")
+        raise typer.Exit(1)
+
+    current = _read_integration_json(project_root)
+    installed_keys = _installed_integration_keys(current)
+    installed_key = _default_integration_key(current)
+
+    if installed_key == target:
+        if integration_options is not None:
+            console.print(
+                "[red]Error:[/red] --integration-options cannot be used when switching "
+                "to an already installed integration."
+            )
+            console.print(
+                f"Run [cyan]specify integration upgrade {target} --integration-options ...[/cyan] "
+                "to update managed files/options."
+            )
+            raise typer.Exit(1)
+        if force:
+            raw_options, parsed_options = _resolve_integration_options(
+                target_integration, current, target, None
+            )
+            _set_default_integration_or_exit(
+                project_root,
+                current,
+                target,
+                target_integration,
+                installed_keys,
+                raw_options=raw_options,
+                parsed_options=parsed_options,
+                refresh_templates_force=True,
+            )
+            console.print(
+                f"\n[green]✓[/green] Default integration remains [bold]{target}[/bold]; "
+                "shared infrastructure refreshed."
+            )
+            raise typer.Exit(0)
+        console.print(f"[yellow]Integration '{target}' is already the default integration. Nothing to switch.[/yellow]")
+        raise typer.Exit(0)
+
+    if target in installed_keys:
+        if integration_options is not None:
+            console.print(
+                "[red]Error:[/red] --integration-options cannot be used when switching "
+                "to an already installed integration."
+            )
+            console.print(
+                f"Run [cyan]specify integration upgrade {target} --integration-options ...[/cyan] "
+                f"to update managed files/options, then [cyan]specify integration use {target}[/cyan]."
+            )
+            raise typer.Exit(1)
+        raw_options, parsed_options = _resolve_integration_options(
+            target_integration, current, target, None
+        )
+        _set_default_integration_or_exit(
+            project_root,
+            current,
+            target,
+            target_integration,
+            installed_keys,
+            raw_options=raw_options,
+            parsed_options=parsed_options,
+            refresh_templates_force=force,
+        )
+        console.print(f"\n[green]✓[/green] Default integration set to [bold]{target}[/bold].")
+        raise typer.Exit(0)
+
+    selected_script = _resolve_script_type(project_root, script)
+
+    # Phase 1: Uninstall current integration (if any)
+    if installed_key:
+        current_integration = get_integration(installed_key)
+        manifest_path = project_root / ".specify" / "integrations" / f"{installed_key}.manifest.json"
+
+        if current_integration and manifest_path.exists():
+            console.print(f"Uninstalling current integration: [cyan]{installed_key}[/cyan]")
+            try:
+                old_manifest = IntegrationManifest.load(installed_key, project_root)
+            except _MANIFEST_READ_ERRORS as exc:
+                console.print(f"[red]Error:[/red] Could not read integration manifest for '{installed_key}': {manifest_path}")
+                console.print(f"[dim]{exc}[/dim]")
+                console.print(
+                    f"To recover, delete the unreadable manifest at {manifest_path}, "
+                    f"run [cyan]specify integration uninstall {installed_key}[/cyan], then retry."
+                )
+                raise typer.Exit(1)
+            removed, skipped = current_integration.teardown(
+                project_root, old_manifest, force=force,
+            )
+            if removed:
+                console.print(f"  Removed {len(removed)} file(s)")
+            if skipped:
+                console.print(f"  [yellow]⚠[/yellow]  {len(skipped)} modified file(s) preserved")
+        elif not current_integration and manifest_path.exists():
+            # Integration removed from registry but manifest exists — use manifest-only uninstall
+            console.print(f"Uninstalling unknown integration '{installed_key}' via manifest")
+            try:
+                old_manifest = IntegrationManifest.load(installed_key, project_root)
+                removed, skipped = old_manifest.uninstall(project_root, force=force)
+                if removed:
+                    console.print(f"  Removed {len(removed)} file(s)")
+                if skipped:
+                    console.print(f"  [yellow]⚠[/yellow]  {len(skipped)} modified file(s) preserved")
+            except _MANIFEST_READ_ERRORS as exc:
+                console.print(f"[yellow]Warning:[/yellow] Could not read manifest for '{installed_key}': {exc}")
+        else:
+            console.print(f"[red]Error:[/red] Integration '{installed_key}' is installed but has no manifest.")
+            console.print(
+                f"Run [cyan]specify integration uninstall {installed_key}[/cyan] to clear metadata, "
+                f"then retry [cyan]specify integration switch {target}[/cyan]."
+            )
+            raise typer.Exit(1)
+
+        # Unregister extension commands for the old agent so they don't
+        # remain as orphans in the old agent's directory.
+        try:
+            from ..extensions import ExtensionManager
+
+            ext_mgr = ExtensionManager(project_root)
+            ext_mgr.unregister_agent_artifacts(installed_key)
+        except Exception as ext_err:
+            _print_cli_warning(
+                "clean up extension artifacts for",
+                "integration",
+                installed_key,
+                ext_err,
+                continuing="Continuing with integration switch; old extension artifacts may need manual cleanup.",
+            )
+
+        # Clear metadata so a failed Phase 2 doesn't leave stale references
+        installed_keys = [installed for installed in installed_keys if installed != installed_key]
+        _clear_init_options_for_integration(project_root, installed_key)
+        if installed_keys:
+            fallback_key = installed_keys[0]
+            fallback_integration = get_integration(fallback_key)
+            if fallback_integration is not None:
+                raw_options, parsed_options = _resolve_integration_options(
+                    fallback_integration, current, fallback_key, None
+                )
+                _set_default_integration_or_exit(
+                    project_root,
+                    current,
+                    fallback_key,
+                    fallback_integration,
+                    installed_keys,
+                    raw_options=raw_options,
+                    parsed_options=parsed_options,
+                )
+            else:
+                _write_integration_json(
+                    project_root, fallback_key, installed_keys, _integration_settings(current)
+                )
+        else:
+            _remove_integration_json(project_root)
+        current = _read_integration_json(project_root)
+
+    # Build parsed options from --integration-options so the integration
+    # can determine its effective invoke separator before shared infra
+    # is installed.
+    raw_options, parsed_options = _resolve_integration_options(
+        target_integration, current, target, integration_options
+    )
+
+    # Refresh shared infrastructure to the current CLI version. Switching
+    # integrations is exactly when stale vendored shared scripts (e.g.
+    # update-agent-context.sh that pre-dates the target integration's
+    # supported-agent list) would silently break the new integration.
+    #
+    # Use refresh_managed=True so only files that match their previously
+    # recorded hash are overwritten — user customizations are detected via
+    # hash divergence and preserved with a warning. Pass
+    # --refresh-shared-infra to overwrite customizations as well. See #2293.
+    _install_shared_infra_or_exit(
+        project_root,
+        selected_script,
+        force=refresh_shared_infra,
+        refresh_managed=True,
+        invoke_separator=_invoke_separator_for_integration(
+            target_integration, current, target, parsed_options
+        ),
+        refresh_hint=(
+            "To overwrite customizations, re-run with "
+            "[cyan]specify integration switch ... --refresh-shared-infra[/cyan]."
+        ),
+    )
+    if os.name != "nt":
+        from .. import ensure_executable_scripts
+        ensure_executable_scripts(project_root)
+
+    # Phase 2: Install target integration
+    console.print(f"Installing integration: [cyan]{target}[/cyan]")
+    manifest = IntegrationManifest(
+        target_integration.key, project_root, version=_get_speckit_version()
+    )
+
+    try:
+        target_integration.setup(
+            project_root, manifest,
+            parsed_options=parsed_options,
+            script_type=selected_script,
+            raw_options=raw_options,
+        )
+        manifest.save()
+        _set_default_integration(
+            project_root,
+            current,
+            target_integration.key,
+            target_integration,
+            _dedupe_integration_keys([*installed_keys, target_integration.key]),
+            script_type=selected_script,
+            raw_options=raw_options,
+            parsed_options=parsed_options,
+        )
+
+        # Re-register extension commands for the new agent so that
+        # previously-installed extensions are available in the new integration.
+        try:
+            from ..extensions import ExtensionManager
+
+            ext_mgr = ExtensionManager(project_root)
+            ext_mgr.register_enabled_extensions_for_agent(target)
+        except Exception as ext_err:
+            _print_cli_warning(
+                "register extension artifacts for",
+                "integration",
+                target,
+                ext_err,
+                continuing="The integration switch succeeded, but installed extensions may need re-registration.",
+            )
+
+    except Exception as exc:
+        # Attempt rollback of any files written by setup
+        try:
+            target_integration.teardown(project_root, manifest, force=True)
+        except Exception as rollback_err:
+            # Suppress so the original setup error remains the primary failure
+            _print_cli_warning(
+                "rollback",
+                "integration",
+                target,
+                rollback_err,
+                continuing="The original switch failure is still the primary error.",
+            )
+        if installed_keys:
+            fallback_key = installed_keys[0]
+            fallback_integration = get_integration(fallback_key)
+            if fallback_integration is not None:
+                raw_options, parsed_options = _resolve_integration_options(
+                    fallback_integration, current, fallback_key, None
+                )
+                try:
+                    _set_default_integration(
+                        project_root,
+                        current,
+                        fallback_key,
+                        fallback_integration,
+                        installed_keys,
+                        raw_options=raw_options,
+                        parsed_options=parsed_options,
+                    )
+                except _SharedTemplateRefreshError as restore_err:
+                    console.print(
+                        f"[yellow]Warning:[/yellow] Failed to restore default "
+                        f"integration '{fallback_key}': {restore_err}"
+                    )
+            else:
+                _write_integration_json(
+                    project_root, fallback_key, installed_keys, _integration_settings(current)
+                )
+        else:
+            _remove_integration_json(project_root)
+        console.print(
+            f"[red]Error:[/red] Failed to {_cli_phase_label('install', 'integration', target)} "
+            f"during switch: {_cli_error_detail(exc)}"
+        )
+        raise typer.Exit(1)
+
+    name = (target_integration.config or {}).get("name", target)
+    console.print(f"\n[green]✓[/green] Switched to integration '{name}'")
+
+
+@integration_app.command("upgrade")
+def integration_upgrade(
+    key: str | None = typer.Argument(None, help="Integration key to upgrade (default: current integration)"),
+    force: bool = typer.Option(False, "--force", help="Force upgrade even if files are modified"),
+    script: str | None = typer.Option(None, "--script", help="Script type: sh or ps (default: from init-options.json or platform default)"),
+    integration_options: str | None = typer.Option(None, "--integration-options", help="Options for the integration"),
+):
+    """Upgrade an integration by reinstalling with diff-aware file handling.
+
+    Compares manifest hashes to detect locally modified files and
+    blocks the upgrade unless --force is used.
+    """
+    from . import get_integration
+    from .manifest import IntegrationManifest
+    from .. import _require_specify_project, _install_shared_infra_or_exit, _install_shared_infra
+
+    project_root = _require_specify_project()
+    current = _read_integration_json(project_root)
+    installed_key = _default_integration_key(current)
+    installed_keys = _installed_integration_keys(current)
+
+    if key is None:
+        if not installed_key:
+            console.print("[yellow]No integration is currently installed.[/yellow]")
+            raise typer.Exit(0)
+        key = installed_key
+
+    if key not in installed_keys:
+        console.print(f"[red]Error:[/red] Integration '{key}' is not installed.")
+        raise typer.Exit(1)
+
+    integration = get_integration(key)
+    if integration is None:
+        console.print(f"[red]Error:[/red] Unknown integration '{key}'")
+        raise typer.Exit(1)
+
+    manifest_path = project_root / ".specify" / "integrations" / f"{key}.manifest.json"
+    if not manifest_path.exists():
+        console.print(f"[yellow]No manifest found for integration '{key}'. Nothing to upgrade.[/yellow]")
+        console.print(f"Run [cyan]specify integration install {key}[/cyan] to perform a fresh install.")
+        raise typer.Exit(0)
+
+    try:
+        old_manifest = IntegrationManifest.load(key, project_root)
+    except _MANIFEST_READ_ERRORS as exc:
+        console.print(f"[red]Error:[/red] Integration manifest for '{key}' is unreadable: {exc}")
+        raise typer.Exit(1)
+
+    # Detect modified files via manifest hashes
+    modified = old_manifest.check_modified()
+    if modified and not force:
+        console.print(f"[yellow]⚠[/yellow]  {len(modified)} file(s) have been modified since installation:")
+        for rel in modified:
+            console.print(f"    {rel}")
+        console.print("\nUse [cyan]--force[/cyan] to overwrite modified files, or resolve manually.")
+        raise typer.Exit(1)
+
+    selected_script = _resolve_integration_script_type(project_root, current, key, script)
+
+    # Build parsed options from --integration-options so the integration
+    # can determine its effective invoke separator before shared infra
+    # is installed.
+    raw_options, parsed_options = _resolve_integration_options(
+        integration, current, key, integration_options
+    )
+
+    # Ensure shared infrastructure is up to date; --force overwrites existing files.
+    infra_integration = integration
+    infra_key = key
+    infra_parsed = parsed_options
+    if installed_key and installed_key != key:
+        default_integration = get_integration(installed_key)
+        if default_integration is not None:
+            infra_integration = default_integration
+            infra_key = installed_key
+            _, infra_parsed = _resolve_integration_options(
+                default_integration, current, installed_key, None
+            )
+    _install_shared_infra_or_exit(
+        project_root,
+        selected_script,
+        force=force,
+        invoke_separator=_invoke_separator_for_integration(
+            infra_integration, current, infra_key, infra_parsed
+        ),
+    )
+    if os.name != "nt":
+        from .. import ensure_executable_scripts
+        ensure_executable_scripts(project_root)
+
+    # Phase 1: Install new files (overwrites existing; old-only files remain)
+    console.print(f"Upgrading integration: [cyan]{key}[/cyan]")
+    new_manifest = IntegrationManifest(key, project_root, version=_get_speckit_version())
+
+    try:
+        integration.setup(
+            project_root,
+            new_manifest,
+            parsed_options=parsed_options,
+            script_type=selected_script,
+            raw_options=raw_options,
+        )
+        settings = _with_integration_setting(
+            current,
+            key,
+            integration,
+            script_type=selected_script,
+            raw_options=raw_options,
+            parsed_options=parsed_options,
+        )
+        if installed_key == key:
+            try:
+                _install_shared_infra(
+                    project_root,
+                    selected_script,
+                    invoke_separator=_invoke_separator_for_integration(
+                        integration, {"integration_settings": settings}, key, parsed_options
+                    ),
+                    force=force,
+                    refresh_managed=True,
+                )
+            except (ValueError, OSError) as exc:
+                raise _SharedTemplateRefreshError(
+                    f"Failed to refresh shared infrastructure for '{key}': {exc}"
+                ) from exc
+        new_manifest.save()
+        _write_integration_json(project_root, installed_key, installed_keys, settings)
+        if installed_key == key:
+            _update_init_options_for_integration(project_root, integration, script_type=selected_script)
+        else:
+            _refresh_init_options_speckit_version(project_root)
+    except Exception as exc:
+        # Don't teardown — setup overwrites in-place, so teardown would
+        # delete files that were working before the upgrade.  Just report.
+        console.print(f"[red]Error:[/red] Failed to {_cli_phase_label('upgrade', 'integration', key)}.")
+        console.print(f"[dim]Details:[/dim] {_cli_error_detail(exc)}")
+        console.print("[yellow]The previous integration files may still be in place.[/yellow]")
+        raise typer.Exit(1)
+
+    # Phase 2: Remove stale files from old manifest that are not in the new one
+    old_files = old_manifest.files
+    new_files = new_manifest.files
+    stale_keys = set(old_files) - set(new_files)
+    if stale_keys:
+        stale_manifest = IntegrationManifest(key, project_root, version="stale-cleanup")
+        stale_manifest._files = {k: old_files[k] for k in stale_keys}
+        stale_removed, _ = stale_manifest.uninstall(project_root, force=True)
+        if stale_removed:
+            console.print(f"  Removed {len(stale_removed)} stale file(s) from previous install")
+
+    name = (integration.config or {}).get("name", key)
+    console.print(f"\n[green]✓[/green] Integration '{name}' upgraded successfully")

src/specify_cli/integrations/_query_commands.py

@@ -0,0 +1,464 @@
+"""specify integration list/use/search/info + catalog list/add/remove command handlers."""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import typer
+from rich.table import Table
+
+from .._console import console
+from ..integration_state import (
+    default_integration_key as _default_integration_key,
+    installed_integration_keys as _installed_integration_keys,
+)
+from ._commands import integration_app, integration_catalog_app
+from ._helpers import (
+    _read_integration_json,
+    _resolve_integration_options,
+    _set_default_integration_or_exit,
+)
+
+
+@integration_app.command("list")
+def integration_list(
+    catalog: bool = typer.Option(False, "--catalog", help="Browse full catalog (built-in + community)"),
+):
+    """List available integrations and installed status."""
+    from . import INTEGRATION_REGISTRY
+    from .. import _require_specify_project
+
+    project_root = _require_specify_project()
+    current = _read_integration_json(project_root)
+    default_key = _default_integration_key(current)
+    installed_keys = set(_installed_integration_keys(current))
+
+    if catalog:
+        from .catalog import IntegrationCatalog, IntegrationCatalogError
+
+        ic = IntegrationCatalog(project_root)
+        try:
+            entries = ic.search()
+        except IntegrationCatalogError as exc:
+            console.print(f"[red]Error:[/red] {exc}")
+            raise typer.Exit(1)
+
+        if not entries:
+            console.print("[yellow]No integrations found in catalog.[/yellow]")
+            return
+
+        table = Table(title="Integration Catalog")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name")
+        table.add_column("Version")
+        table.add_column("Source")
+        table.add_column("Status")
+        table.add_column("Multi-install Safe")
+
+        for entry in sorted(entries, key=lambda e: e["id"]):
+            eid = entry["id"]
+            cat_name = entry.get("_catalog_name", "")
+            install_allowed = entry.get("_install_allowed", True)
+            if eid == default_key:
+                status = "[green]installed (default)[/green]"
+            elif eid in installed_keys:
+                status = "[green]installed[/green]"
+            elif eid in INTEGRATION_REGISTRY:
+                status = "built-in"
+            elif install_allowed is False:
+                status = "discovery-only"
+            else:
+                status = ""
+            safe = ""
+            if eid in INTEGRATION_REGISTRY:
+                reg_integ = INTEGRATION_REGISTRY[eid]
+                safe = "yes" if getattr(reg_integ, "multi_install_safe", False) else "no"
+            table.add_row(
+                eid,
+                entry.get("name", eid),
+                entry.get("version", ""),
+                cat_name,
+                status,
+                safe,
+            )
+        console.print(table)
+        return
+
+    if not INTEGRATION_REGISTRY:
+        console.print("[yellow]No integrations available.[/yellow]")
+        return
+
+    table = Table(title="Coding Agent Integrations")
+    table.add_column("Key", style="cyan")
+    table.add_column("Name")
+    table.add_column("Status")
+    table.add_column("CLI Required")
+    table.add_column("Multi-install Safe")
+
+    for key in sorted(INTEGRATION_REGISTRY.keys()):
+        integration = INTEGRATION_REGISTRY[key]
+        cfg = integration.config or {}
+        name = cfg.get("name", key)
+        requires_cli = cfg.get("requires_cli", False)
+        if key == default_key:
+            status = "[green]installed (default)[/green]"
+        elif key in installed_keys:
+            status = "[green]installed[/green]"
+        else:
+            status = ""
+        cli_req = "yes" if requires_cli else "no (IDE)"
+        safe = "yes" if getattr(integration, "multi_install_safe", False) else "no"
+        table.add_row(key, name, status, cli_req, safe)
+
+    console.print(table)
+
+    if installed_keys:
+        console.print(f"\n[dim]Default integration:[/dim] [cyan]{default_key or 'none'}[/cyan]")
+        console.print(f"[dim]Installed integrations:[/dim] [cyan]{', '.join(sorted(installed_keys))}[/cyan]")
+    else:
+        console.print("\n[yellow]No integration currently installed.[/yellow]")
+        console.print("Install one with: [cyan]specify integration install <key>[/cyan]")
+
+
+@integration_app.command("use")
+def integration_use(
+    key: str = typer.Argument(help="Installed integration key to make the default"),
+    force: bool = typer.Option(False, "--force", help="Overwrite existing shared infrastructure files, including customizations, while changing the default"),
+):
+    """Set the default integration without uninstalling other integrations."""
+    from . import get_integration
+    from .. import _require_specify_project
+
+    project_root = _require_specify_project()
+    current = _read_integration_json(project_root)
+    installed_keys = _installed_integration_keys(current)
+    if key not in installed_keys:
+        console.print(f"[red]Error:[/red] Integration '{key}' is not installed.")
+        if installed_keys:
+            console.print(f"[yellow]Installed integrations:[/yellow] {', '.join(installed_keys)}")
+        else:
+            console.print("Install one with: [cyan]specify integration install <key>[/cyan]")
+        raise typer.Exit(1)
+
+    integration = get_integration(key)
+    if integration is None:
+        console.print(f"[red]Error:[/red] Unknown integration '{key}'")
+        raise typer.Exit(1)
+
+    raw_options, parsed_options = _resolve_integration_options(integration, current, key, None)
+    _set_default_integration_or_exit(
+        project_root,
+        current,
+        key,
+        integration,
+        installed_keys,
+        raw_options=raw_options,
+        parsed_options=parsed_options,
+        refresh_templates_force=force,
+        refresh_hint=(
+            "To overwrite customizations, re-run with "
+            f"[cyan]specify integration use {key} --force[/cyan]."
+        ),
+    )
+    console.print(f"[green]✓[/green] Default integration set to [bold]{key}[/bold].")
+
+
+# ===== Integration catalog discovery commands =====
+#
+# These commands mirror the workflow catalog CLI shape:
+#   - `search` / `info` for discovery over the active catalog stack
+#   - `catalog list/add/remove` for managing catalog sources
+#
+# They deliberately do NOT add `integration add/remove/enable/disable/
+# set-priority`: integrations are single-active (install / uninstall / switch),
+# not additive like extensions and presets.
+@integration_app.command("search")
+def integration_search(
+    query: Optional[str] = typer.Argument(None, help="Search query (optional)"),
+    tag: Optional[str] = typer.Option(None, "--tag", help="Filter by tag"),
+    author: Optional[str] = typer.Option(None, "--author", help="Filter by author"),
+):
+    """Search for integrations in the active catalog stack."""
+    from . import INTEGRATION_REGISTRY
+    from .catalog import (
+        IntegrationCatalog,
+        IntegrationCatalogError,
+        IntegrationValidationError,
+    )
+    from .. import _require_specify_project
+
+    project_root = _require_specify_project()
+    integration_config = _read_integration_json(project_root)
+    installed_key = _default_integration_key(integration_config)
+    catalog = IntegrationCatalog(project_root)
+
+    try:
+        results = catalog.search(query=query, tag=tag, author=author)
+    except IntegrationValidationError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        console.print(
+            "\nTip: Check the configuration file path shown above for invalid catalog configuration "
+            "(for example, .specify/integration-catalogs.yml or ~/.specify/integration-catalogs.yml)."
+        )
+        raise typer.Exit(1)
+    except IntegrationCatalogError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        if os.environ.get("SPECKIT_INTEGRATION_CATALOG_URL", "").strip():
+            console.print(
+                "\nTip: Check the SPECKIT_INTEGRATION_CATALOG_URL environment variable for an invalid "
+                "catalog URL, or unset it to use the configured catalog files "
+                "(.specify/integration-catalogs.yml or ~/.specify/integration-catalogs.yml)."
+            )
+        else:
+            console.print("\nTip: The catalog may be temporarily unavailable. Try again later.")
+        raise typer.Exit(1)
+
+    if not results:
+        console.print("\n[yellow]No integrations found matching criteria[/yellow]")
+        if query or tag or author:
+            console.print("\nTry:")
+            console.print("  • Broader search terms")
+            console.print("  • Remove filters")
+            console.print("  • specify integration search (show all)")
+        return
+
+    console.print(f"\n[green]Found {len(results)} integration(s):[/green]\n")
+    for integ in sorted(results, key=lambda e: e.get("id", "")):
+        iid = integ.get("id", "?")
+        name = integ.get("name", iid)
+        version = integ.get("version", "?")
+        console.print(f"[bold]{name}[/bold] ({iid}) v{version}")
+        desc = integ.get("description", "")
+        if desc:
+            console.print(f"  {desc}")
+
+        console.print(f"\n  [dim]Author:[/dim] {integ.get('author', 'Unknown')}")
+        tags = integ.get("tags", [])
+        if isinstance(tags, list) and tags:
+            console.print(f"  [dim]Tags:[/dim] {', '.join(str(t) for t in tags)}")
+
+        cat_name = integ.get("_catalog_name", "")
+        install_allowed = integ.get("_install_allowed", True)
+        if cat_name:
+            if install_allowed:
+                console.print(f"  [dim]Catalog:[/dim] {cat_name}")
+            else:
+                console.print(
+                    f"  [dim]Catalog:[/dim] {cat_name} "
+                    "[yellow](discovery only — not installable)[/yellow]"
+                )
+
+        if iid == installed_key:
+            console.print("\n  [green]✓ Installed[/green] (currently active)")
+        elif iid in INTEGRATION_REGISTRY:
+            console.print(f"\n  [cyan]Install:[/cyan] specify integration install {iid}")
+        elif install_allowed:
+            console.print(
+                "\n  [yellow]Found in catalog.[/yellow] Only built-in integration IDs "
+                "can be installed with 'specify integration install'."
+            )
+        else:
+            console.print(
+                f"\n  [yellow]⚠[/yellow]  Not directly installable from '{cat_name}'."
+            )
+        console.print()
+
+
+@integration_app.command("info")
+def integration_info(
+    integration_id: str = typer.Argument(..., help="Integration ID"),
+):
+    """Show catalog details for a single integration."""
+    from . import INTEGRATION_REGISTRY
+    from .catalog import (
+        IntegrationCatalog,
+        IntegrationCatalogError,
+        IntegrationValidationError,
+    )
+    from .. import _require_specify_project
+
+    project_root = _require_specify_project()
+    catalog = IntegrationCatalog(project_root)
+    installed_key = _default_integration_key(_read_integration_json(project_root))
+
+    try:
+        info = catalog.get_integration_info(integration_id)
+    except IntegrationCatalogError as exc:
+        info = None
+        # Keep the live exception so the fallback branch below can give
+        # different guidance for local-config vs. network failures.
+        catalog_error: Optional[IntegrationCatalogError] = exc
+    else:
+        catalog_error = None
+
+    if info:
+        name = info.get("name", integration_id)
+        version = info.get("version", "?")
+        console.print(f"\n[bold cyan]{name}[/bold cyan] ({integration_id}) v{version}")
+        if info.get("description"):
+            console.print(f"  {info['description']}")
+        console.print()
+
+        console.print(f"  [dim]Author:[/dim] {info.get('author', 'Unknown')}")
+        if info.get("license"):
+            console.print(f"  [dim]License:[/dim] {info['license']}")
+
+        tags = info.get("tags", [])
+        if isinstance(tags, list) and tags:
+            console.print(f"  [dim]Tags:[/dim] {', '.join(str(t) for t in tags)}")
+
+        cat_name = info.get("_catalog_name", "")
+        install_allowed = info.get("_install_allowed", True)
+        if cat_name:
+            install_note = "" if install_allowed else " [yellow](discovery only)[/yellow]"
+            console.print(f"  [dim]Source catalog:[/dim] {cat_name}{install_note}")
+
+        if info.get("repository"):
+            console.print(f"  [dim]Repository:[/dim] {info['repository']}")
+
+        if integration_id == installed_key:
+            console.print("\n  [green]✓ Installed[/green] (currently active)")
+        elif integration_id in INTEGRATION_REGISTRY:
+            console.print("\n  [dim]Built-in integration (not currently active)[/dim]")
+        return
+
+    if integration_id in INTEGRATION_REGISTRY:
+        integration = INTEGRATION_REGISTRY[integration_id]
+        cfg = integration.config or {}
+        name = cfg.get("name", integration_id)
+        console.print(f"\n[bold cyan]{name}[/bold cyan] ({integration_id})")
+        console.print("  [dim]Built-in integration (not listed in catalog)[/dim]")
+        if integration_id == installed_key:
+            console.print("\n  [green]✓ Installed[/green] (currently active)")
+        if catalog_error:
+            console.print(f"\n[yellow]Catalog unavailable:[/yellow] {catalog_error}")
+        return
+
+    if catalog_error:
+        console.print(f"[red]Error:[/red] Could not query integration catalog: {catalog_error}")
+        if isinstance(catalog_error, IntegrationValidationError):
+            console.print(
+                "\nCheck the configuration file path shown above "
+                "(.specify/integration-catalogs.yml or ~/.specify/integration-catalogs.yml), "
+                "or use a built-in integration ID directly."
+            )
+        elif os.environ.get("SPECKIT_INTEGRATION_CATALOG_URL", "").strip():
+            console.print(
+                "\nCheck whether SPECKIT_INTEGRATION_CATALOG_URL is set correctly and reachable, "
+                "or unset it to use the configured catalog files, or use a built-in integration ID directly."
+            )
+        else:
+            console.print("\nTry again when online, or use a built-in integration ID directly.")
+    else:
+        console.print(f"[red]Error:[/red] Integration '{integration_id}' not found")
+        console.print("\nTry: specify integration search")
+    raise typer.Exit(1)
+
+
+@integration_catalog_app.command("list")
+def integration_catalog_list():
+    """List configured integration catalog sources."""
+    from .catalog import IntegrationCatalog, IntegrationCatalogError
+    from .. import _require_specify_project
+
+    project_root = _require_specify_project()
+    catalog = IntegrationCatalog(project_root)
+    env_override = os.environ.get("SPECKIT_INTEGRATION_CATALOG_URL", "").strip()
+
+    try:
+        if env_override:
+            project_configs = None
+            configs = catalog.get_catalog_configs()
+        else:
+            project_configs = catalog.get_project_catalog_configs()
+            configs = project_configs if project_configs is not None else catalog.get_catalog_configs()
+    except IntegrationCatalogError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+    console.print("\n[bold cyan]Integration Catalog Sources:[/bold cyan]\n")
+    if env_override:
+        console.print(
+            "  SPECKIT_INTEGRATION_CATALOG_URL is set; it supersedes configured catalog files."
+        )
+        console.print(
+            "  Project/user catalog sources are not active while the env override is set.\n"
+        )
+        console.print("[bold]Active catalog source from environment (non-removable here):[/bold]\n")
+    elif project_configs is None:
+        console.print("  No project-level catalog sources configured.\n")
+        console.print("[bold]Active catalog sources (non-removable here):[/bold]\n")
+    else:
+        console.print("[bold]Project catalog sources (removable):[/bold]\n")
+
+    for i, cfg in enumerate(configs):
+        install_status = (
+            "[green]install allowed[/green]"
+            if cfg.get("install_allowed")
+            else "[yellow]discovery only[/yellow]"
+        )
+        raw_name = cfg.get("name")
+        display_name = str(raw_name).strip() if raw_name is not None else ""
+        if not display_name:
+            display_name = f"catalog-{i + 1}"
+        if env_override or project_configs is None:
+            console.print(f"  - [bold]{display_name}[/bold] — {install_status}")
+        else:
+            console.print(f"  [{i}] [bold]{display_name}[/bold] — {install_status}")
+        console.print(f"      {cfg.get('url', '')}")
+        if cfg.get("description"):
+            console.print(f"      [dim]{cfg['description']}[/dim]")
+        console.print()
+
+
+@integration_catalog_app.command("add")
+def integration_catalog_add(
+    url: str = typer.Argument(
+        ...,
+        help=(
+            "Catalog URL to add (HTTPS required, except http://localhost, "
+            "http://127.0.0.1, or http://[::1] for local testing)"
+        ),
+    ),
+    name: Optional[str] = typer.Option(None, "--name", help="Catalog name"),
+):
+    """Add an integration catalog source to the project config."""
+    from .catalog import IntegrationCatalog, IntegrationCatalogError
+    from .. import _require_specify_project
+
+    project_root = _require_specify_project()
+    catalog = IntegrationCatalog(project_root)
+
+    # Normalize once here so the success message reflects what was actually
+    # stored. ``IntegrationCatalog.add_catalog`` strips again defensively.
+    normalized_url = url.strip()
+
+    try:
+        catalog.add_catalog(normalized_url, name)
+    except IntegrationCatalogError as exc:
+        # Covers both URL validation (base class) and config-file validation
+        # (IntegrationValidationError subclass).
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+    console.print(f"[green]✓[/green] Catalog source added: {normalized_url}")
+
+
+@integration_catalog_app.command("remove")
+def integration_catalog_remove(
+    index: int = typer.Argument(..., help="Catalog index to remove (from 'catalog list')"),
+):
+    """Remove an integration catalog source by 0-based index."""
+    from .catalog import IntegrationCatalog, IntegrationCatalogError
+    from .. import _require_specify_project
+
+    project_root = _require_specify_project()
+    catalog = IntegrationCatalog(project_root)
+
+    try:
+        removed_name = catalog.remove_catalog(index)
+    except IntegrationCatalogError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+    console.print(f"[green]✓[/green] Catalog source '{removed_name}' removed")

src/specify_cli/integrations/agy/__init__.py

@@ -5,6 +5,7 @@ Antigravity uses ``.agents/skills/speckit-<name>/SKILL.md`` layout (enforced sin
 
 from __future__ import annotations
 
+import re
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -13,6 +14,15 @@ from ..base import SkillsIntegration
 if TYPE_CHECKING:
     from ..manifest import IntegrationManifest
 
+# Note injected into hook sections so agy maps dot-notation command
+# names (from extensions.yml) to the hyphenated skill names it uses.
+# Without this, agy emits ``/speckit.git.commit`` (which does not
+# resolve) instead of ``/speckit-git-commit``.
+_HOOK_COMMAND_NOTE = (
+    "- When constructing slash commands from hook command names, "
+    "replace dots (`.`) with hyphens (`-`). "
+    "For example, `speckit.git.commit` → `/speckit-git-commit`.\n"
+)
 
 
 class AgyIntegration(SkillsIntegration):
@@ -23,8 +33,8 @@ class AgyIntegration(SkillsIntegration):
         "name": "Antigravity",
         "folder": ".agents/",
         "commands_subdir": "skills",
-        "install_url": None,
-        "requires_cli": False,
+        "install_url": "https://antigravity.google/",
+        "requires_cli": True,
     }
     registrar_config = {
         "dir": ".agents/skills",
@@ -34,6 +44,54 @@ class AgyIntegration(SkillsIntegration):
     }
     context_file = "AGENTS.md"
 
+    @staticmethod
+    def _inject_hook_command_note(content: str) -> str:
+        """Insert a dot-to-hyphen note before each hook output instruction.
+
+        Targets the line ``- For each executable hook, output the following``
+        and inserts the note on the line before it, matching its indentation.
+        Skips if the note is already present.
+        """
+        if "replace dots" in content:
+            return content
+
+        def repl(m: re.Match[str]) -> str:
+            indent = m.group(1)
+            instruction = m.group(2)
+            # ``eol`` is empty when the regex matched via ``$`` because the
+            # instruction was the final line of a file with no trailing
+            # newline. Default to ``\n`` so the note never collapses onto
+            # the same line as the instruction.
+            eol = m.group(3) or "\n"
+            return (
+                indent
+                + _HOOK_COMMAND_NOTE.rstrip("\n")
+                + eol
+                + indent
+                + instruction
+                + eol
+            )
+
+        return re.sub(
+            r"(?m)^(\s*)(- For each executable hook, output the following[^\r\n]*)(\r\n|\n|$)",
+            repl,
+            content,
+        )
+
+    def post_process_skill_content(self, content: str) -> str:
+        """Inject the dot-to-hyphen hook command note."""
+        return self._inject_hook_command_note(content)
+
+    def build_exec_args(
+        self,
+        prompt: str,
+        *,
+        model: str | None = None,
+        output_json: bool = True,
+    ) -> list[str] | None:
+        # agy does not support --model or JSON output; both params are ignored
+        return [self._resolve_executable(), "--print", prompt]
+
     def setup(
         self,
         project_root: Path,
@@ -49,4 +107,21 @@ class AgyIntegration(SkillsIntegration):
             fg="yellow",
             err=True,
         )
-        return super().setup(project_root, manifest, parsed_options=parsed_options, **opts)
+        created = super().setup(project_root, manifest, parsed_options=parsed_options, **opts)
+
+        skills_dir = self.skills_dest(project_root).resolve()
+        for path in created:
+            try:
+                path.resolve().relative_to(skills_dir)
+            except ValueError:
+                continue
+            if path.name != "SKILL.md":
+                continue
+
+            content = path.read_bytes().decode("utf-8")
+            updated = self.post_process_skill_content(content)
+            if updated != content:
+                path.write_bytes(updated.encode("utf-8"))
+                self.record_file_in_manifest(path, project_root, manifest)
+
+        return created

src/specify_cli/integrations/base.py

@@ -13,7 +13,10 @@ Provides:
 
 from __future__ import annotations
 
+import json
+import os
 import re
+import shlex
 import shutil
 from abc import ABC
 from dataclasses import dataclass
@@ -25,6 +28,27 @@ import yaml
 if TYPE_CHECKING:
     from .manifest import IntegrationManifest
 
+_HOOK_COMMAND_NOTE = (
+    "- When constructing slash commands from hook command names, "
+    "replace dots (`.`) with hyphens (`-`). "
+    "For example, `speckit.git.commit` → `/speckit-git-commit`.\n"
+)
+
+_CORE_COMMAND_TEMPLATE_ORDER = (
+    "analyze",
+    "clarify",
+    "constitution",
+    "implement",
+    "plan",
+    "checklist",
+    "specify",
+    "tasks",
+    "taskstoissues",
+)
+_CORE_COMMAND_TEMPLATE_RANK = {
+    command: index for index, command in enumerate(_CORE_COMMAND_TEMPLATE_ORDER)
+}
+
 
 # ---------------------------------------------------------------------------
 # IntegrationOption
@@ -138,6 +162,104 @@ class IntegrationBase(ABC):
         """
         return None
 
+    @property
+    def cli_executable(self) -> str:
+        """Executable name used for CLI availability detection.
+
+        Defaults to ``self.key``.  Integrations whose CLI binary name
+        differs from the integration key should override this property.
+        For example, RovoDev's key is ``"rovodev"`` but the binary is
+        ``"acli"``, so its override returns ``"acli"``.
+
+        This property is used by :meth:`is_cli_available` and by
+        ``check_tool()`` when checking whether the integration's CLI
+        tool is installed.  It intentionally does **not** honour the
+        ``SPECKIT_INTEGRATION_<KEY>_EXECUTABLE`` env-var override — that
+        variable controls which binary is *executed* at runtime (see
+        :meth:`_resolve_executable`), whereas ``cli_executable`` names
+        the tool to *detect* on ``PATH``.
+
+        See issue #2597.
+        """
+        return self.key
+
+    def is_cli_available(self) -> bool:
+        """Return ``True`` if this integration's CLI tool is installed.
+
+        The default implementation checks ``shutil.which(self.cli_executable)``.
+        Integrations with non-standard install locations or multiple
+        possible binary names should override this method.
+
+        Examples of integrations that override this:
+
+        * **ClaudeIntegration** — also checks ``~/.claude/local/`` paths
+          that are not on ``PATH``.
+        * **KiroCliIntegration** — accepts both ``kiro-cli`` and the
+          legacy ``kiro`` binary name.
+
+        See issue #2597.
+        """
+        return shutil.which(self.cli_executable) is not None
+
+    def _resolve_executable(self) -> str:
+        """Return the executable for this integration's CLI tool.
+
+        Checks ``SPECKIT_INTEGRATION_<KEY>_EXECUTABLE`` first, allowing
+        operators to override the binary path without modifying the
+        integration configuration — useful when the tool is installed in
+        a non-standard location or a specific version must be pinned.
+        Hyphens in the integration key are replaced with underscores and
+        the key is uppercased so that, for example, ``kiro-cli`` maps to
+        ``SPECKIT_INTEGRATION_KIRO_CLI_EXECUTABLE``.
+
+        Falls back to ``self.key`` when the env var is unset or
+        whitespace-only so existing behaviour is unchanged.
+
+        See issue #2596.
+        """
+        env_name = (
+            f"SPECKIT_INTEGRATION_{self.key.upper().replace('-', '_')}_EXECUTABLE"
+        )
+        override = os.environ.get(env_name, "").strip()
+        return override if override else self.key
+
+    def _apply_extra_args_env_var(self, args: list[str]) -> None:
+        """Append `SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS` env-var value to *args*.
+
+        Operators can inject extra CLI flags into the spawned agent
+        subprocess by setting an env var named for the integration key,
+        e.g. `SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS="--dangerously-skip-permissions"`.
+        The `INTEGRATION` segment scopes the variable to this subsystem
+        so it does not collide with other Spec Kit env-var namespaces.
+        Hyphens in the integration key are replaced with underscores
+        and the key is uppercased
+        (e.g. `kiro-cli` → `SPECKIT_INTEGRATION_KIRO_CLI_EXTRA_ARGS`).
+
+        Useful in CI / non-interactive contexts where the spawned agent
+        needs flags that change its prompt-handling behaviour.
+        Default behaviour (env var unset or whitespace-only) is a no-op
+        — *args* is unchanged. Multi-token values are parsed via
+        `shlex.split`.
+
+        See issue #2595.
+        """
+        env_name = (
+            f"SPECKIT_INTEGRATION_{self.key.upper().replace('-', '_')}_EXTRA_ARGS"
+        )
+        extra = os.environ.get(env_name, "").strip()
+        if not extra:
+            return
+        try:
+            tokens = shlex.split(extra)
+        except ValueError as exc:
+            raise ValueError(
+                f"{env_name} is not parseable as a POSIX-quoted command line "
+                f"(value: {extra!r}). shlex reported: {exc}. "
+                f"Use single or double quotes to group multi-word values, e.g. "
+                f'{env_name}=\'--flag "value with spaces"\'.'
+            ) from exc
+        args.extend(tokens)
+
     def build_command_invocation(self, command_name: str, args: str = "") -> str:
         """Build the native slash-command invocation for a Spec Kit command.
 
@@ -202,6 +324,16 @@ class IntegrationBase(ABC):
             )
             raise NotImplementedError(msg)
 
+        # Windows: ``subprocess.run`` calls ``CreateProcess`` which does not
+        # consult ``PATHEXT``, so a bare command name like ``cursor-agent``
+        # that resolves to ``cursor-agent.cmd`` fails with ``WinError 2``.
+        # Resolve via ``shutil.which`` (which does honor ``PATHEXT``) so
+        # ``.cmd``/``.bat`` shims work transparently.  On POSIX this is a
+        # no-op for absolute paths and a harmless lookup otherwise.
+        resolved = shutil.which(exec_args[0])
+        if resolved:
+            exec_args = [resolved, *exec_args[1:]]
+
         cwd = str(project_root) if project_root else None
 
         if stream:
@@ -277,11 +409,19 @@ class IntegrationBase(ABC):
         return None
 
     def list_command_templates(self) -> list[Path]:
-        """Return sorted list of command template files from the shared directory."""
+        """Return ordered list of command template files from the shared directory."""
         cmd_dir = self.shared_commands_dir()
         if not cmd_dir or not cmd_dir.is_dir():
             return []
-        return sorted(f for f in cmd_dir.iterdir() if f.is_file() and f.suffix == ".md")
+        return sorted(
+            (f for f in cmd_dir.iterdir() if f.is_file() and f.suffix == ".md"),
+            key=lambda f: (
+                _CORE_COMMAND_TEMPLATE_RANK.get(
+                    f.stem, len(_CORE_COMMAND_TEMPLATE_ORDER)
+                ),
+                f.name,
+            ),
+        )
 
     def command_filename(self, template_name: str) -> str:
         """Return the destination filename for a command template.
@@ -482,6 +622,91 @@ class IntegrationBase(ABC):
             lines.append(f"at {plan_path}")
         return "\n".join(lines)
 
+    @staticmethod
+    def _agent_context_extension_enabled(project_root: Path) -> bool:
+        """Return whether the bundled ``agent-context`` extension is enabled.
+
+        The extension is the single source of truth for managing coding
+        agent context/instruction files (e.g. ``CLAUDE.md``,
+        ``.github/copilot-instructions.md``).
+
+        Returns ``True`` (enabled) when:
+        - the extension registry does not exist (legacy project, backwards
+          compatibility), or
+        - the registry has no ``agent-context`` entry (older project layout
+          predating the extension), or
+        - the entry is present and not explicitly disabled.
+
+        Returns ``False`` only when an entry exists with ``enabled: false``.
+        """
+        registry_path = (
+            project_root / ".specify" / "extensions" / ".registry"
+        )
+        if not registry_path.exists():
+            return True
+        try:
+            data = json.loads(registry_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError, UnicodeError):
+            return True
+        if not isinstance(data, dict):
+            return True
+        extensions = data.get("extensions")
+        if not isinstance(extensions, dict):
+            return True
+        entry = extensions.get("agent-context")
+        if not isinstance(entry, dict):
+            return True
+        return entry.get("enabled", True) is not False
+
+    def _resolve_context_markers(self, project_root: Path) -> tuple[str, str]:
+        """Return the (start, end) context markers to use for *project_root*.
+
+        Reads ``context_markers.start`` / ``context_markers.end`` from the
+        agent-context extension config
+        (``.specify/extensions/agent-context/agent-context-config.yml``)
+        when present.  Falls back to the class-level constants
+        ``CONTEXT_MARKER_START`` / ``CONTEXT_MARKER_END`` when the file is
+        missing, the section is absent, or the values are not non-empty
+        strings.
+        """
+        from .._console import console  # local import to avoid cycles
+
+        start = self.CONTEXT_MARKER_START
+        end = self.CONTEXT_MARKER_END
+        config_path = (
+            project_root
+            / ".specify"
+            / "extensions"
+            / "agent-context"
+            / "agent-context-config.yml"
+        )
+        try:
+            raw = config_path.read_text(encoding="utf-8")
+            cfg = yaml.safe_load(raw)
+        except (OSError, UnicodeError, ValueError, yaml.YAMLError):
+            return start, end
+        markers = cfg.get("context_markers") if isinstance(cfg, dict) else None
+        if isinstance(markers, dict):
+            cm_start = markers.get("start")
+            cm_end = markers.get("end")
+            s_valid = isinstance(cm_start, str) and cm_start
+            e_valid = isinstance(cm_end, str) and cm_end
+            if not s_valid and cm_start is not None:
+                console.print(
+                    f"[yellow]agent-context: ignoring invalid context_markers.start "
+                    f"({cm_start!r}), using default[/yellow]"
+                )
+            if not e_valid and cm_end is not None:
+                console.print(
+                    f"[yellow]agent-context: ignoring invalid context_markers.end "
+                    f"({cm_end!r}), using default[/yellow]"
+                )
+            if s_valid:
+                start = cm_start  # type: ignore[assignment]
+            if e_valid:
+                end = cm_end  # type: ignore[assignment]
+        return start, end
+
     def upsert_context_section(
         self,
         project_root: Path,
@@ -490,34 +715,54 @@ class IntegrationBase(ABC):
         """Create or update the managed section in the agent context file.
 
         If the context file does not exist it is created with just the
-        managed section.  If it exists, the content between
-        ``<!-- SPECKIT START -->`` and ``<!-- SPECKIT END -->`` markers
-        is replaced (or appended when no markers are found).
+        managed section.  If it exists, the content between the configured
+        start/end markers (default ``<!-- SPECKIT START -->`` /
+        ``<!-- SPECKIT END -->``) is replaced, or appended when no markers
+        are found. Markers are read from the agent-context extension config
+        (``.specify/extensions/agent-context/agent-context-config.yml``)
+        when present, falling back to the class-level constants.
 
         Returns the path to the context file, or ``None`` when
-        ``context_file`` is not set.
+        ``context_file`` is not set or the ``agent-context`` extension is
+        disabled.
         """
         if not self.context_file:
             return None
 
+        if not self._agent_context_extension_enabled(project_root):
+            return None
+
+        from .._console import console  # local import to avoid cycles
+
+        console.print(
+            "[yellow]Deprecation:[/yellow] Inline agent-context updates during "
+            "integration setup will be disabled in v0.12.0. Context file "
+            "management has moved to the bundled [bold]agent-context[/bold] "
+            "extension. Run [cyan]specify extension disable agent-context[/cyan] "
+            "to opt out early.",
+            highlight=False,
+        )
+
+        marker_start, marker_end = self._resolve_context_markers(project_root)
+
         ctx_path = project_root / self.context_file
         section = (
-            f"{self.CONTEXT_MARKER_START}\n"
+            f"{marker_start}\n"
             f"{self._build_context_section(plan_path)}\n"
-            f"{self.CONTEXT_MARKER_END}\n"
+            f"{marker_end}\n"
         )
 
         if ctx_path.exists():
             content = ctx_path.read_text(encoding="utf-8-sig")
-            start_idx = content.find(self.CONTEXT_MARKER_START)
+            start_idx = content.find(marker_start)
             end_idx = content.find(
-                self.CONTEXT_MARKER_END,
+                marker_end,
                 start_idx if start_idx != -1 else 0,
             )
 
             if start_idx != -1 and end_idx != -1 and end_idx > start_idx:
                 # Replace existing section (include the end marker + newline)
-                end_of_marker = end_idx + len(self.CONTEXT_MARKER_END)
+                end_of_marker = end_idx + len(marker_end)
                 # Consume trailing line ending (CRLF or LF)
                 if end_of_marker < len(content) and content[end_of_marker] == "\r":
                     end_of_marker += 1
@@ -529,7 +774,7 @@ class IntegrationBase(ABC):
                 new_content = content[:start_idx] + section
             elif end_idx != -1:
                 # Corrupted: end marker without start — replace BOF through end marker
-                end_of_marker = end_idx + len(self.CONTEXT_MARKER_END)
+                end_of_marker = end_idx + len(marker_end)
                 if end_of_marker < len(content) and content[end_of_marker] == "\r":
                     end_of_marker += 1
                 if end_of_marker < len(content) and content[end_of_marker] == "\n":
@@ -563,20 +808,27 @@ class IntegrationBase(ABC):
         """Remove the managed section from the agent context file.
 
         Returns ``True`` if the section was found and removed.  If the
-        file becomes empty (or whitespace-only) after removal it is
-        deleted.
+        file becomes empty (or whitespace-only) after removal it is deleted.
+        Markers are read from the agent-context extension config
+        (``.specify/extensions/agent-context/agent-context-config.yml``)
+        when present, falling back to the class-level constants.
         """
         if not self.context_file:
             return False
 
+        if not self._agent_context_extension_enabled(project_root):
+            return False
+
         ctx_path = project_root / self.context_file
         if not ctx_path.exists():
             return False
 
+        marker_start, marker_end = self._resolve_context_markers(project_root)
+
         content = ctx_path.read_text(encoding="utf-8-sig")
-        start_idx = content.find(self.CONTEXT_MARKER_START)
+        start_idx = content.find(marker_start)
         end_idx = content.find(
-            self.CONTEXT_MARKER_END,
+            marker_end,
             start_idx if start_idx != -1 else 0,
         )
 
@@ -587,7 +839,7 @@ class IntegrationBase(ABC):
             return False
 
         removal_start = start_idx
-        removal_end = end_idx + len(self.CONTEXT_MARKER_END)
+        removal_end = end_idx + len(marker_end)
 
         # Consume trailing line ending (CRLF or LF)
         if removal_end < len(content) and content[removal_end] == "\r":
@@ -850,7 +1102,8 @@ class MarkdownIntegration(IntegrationBase):
     ) -> list[str] | None:
         if not self.config or not self.config.get("requires_cli"):
             return None
-        args = [self.key, "-p", prompt]
+        args = [self._resolve_executable(), "-p", prompt]
+        self._apply_extra_args_env_var(args)
         if model:
             args.extend(["--model", model])
         if output_json:
@@ -937,7 +1190,8 @@ class TomlIntegration(IntegrationBase):
     ) -> list[str] | None:
         if not self.config or not self.config.get("requires_cli"):
             return None
-        args = [self.key, "-p", prompt]
+        args = [self._resolve_executable(), "-p", prompt]
+        self._apply_extra_args_env_var(args)
         if model:
             args.extend(["-m", model])
         if output_json:
@@ -1355,7 +1609,8 @@ class SkillsIntegration(IntegrationBase):
     ) -> list[str] | None:
         if not self.config or not self.config.get("requires_cli"):
             return None
-        args = [self.key, "-p", prompt]
+        args = [self._resolve_executable(), "-p", prompt]
+        self._apply_extra_args_env_var(args)
         if model:
             args.extend(["--model", model])
         if output_json:
@@ -1391,15 +1646,53 @@ class SkillsIntegration(IntegrationBase):
             invocation = f"{invocation} {args}"
         return invocation
 
+    @staticmethod
+    def _inject_hook_command_note(content: str) -> str:
+        """Insert a dot-to-hyphen note before each hook output instruction.
+
+        Targets the line ``- For each executable hook, output the following``
+        and inserts the note on the line before it, matching its indentation.
+        Skips individual instructions that already have the note immediately
+        above them.
+        """
+        note = _HOOK_COMMAND_NOTE.rstrip("\n")
+
+        def repl(m: re.Match[str]) -> str:
+            indent = m.group(1)
+            instruction = m.group(2)
+            previous_lines = content[:m.start()].splitlines()
+            if previous_lines and previous_lines[-1] == indent + note:
+                return m.group(0)
+            # ``eol`` is empty when the regex matched via ``$`` because the
+            # instruction was the final line of a file with no trailing
+            # newline. Default to ``\n`` so the note never collapses onto
+            # the same line as the instruction.
+            eol = m.group(3) or "\n"
+            return (
+                indent
+                + note
+                + eol
+                + indent
+                + instruction
+                + eol
+            )
+
+        return re.sub(
+            r"(?m)^([ \t]*)(- For each executable hook, output the following[^\r\n]*)(\r\n|\n|$)",
+            repl,
+            content,
+        )
+
     def post_process_skill_content(self, content: str) -> str:
         """Post-process a SKILL.md file's content after generation.
 
         Called by external skill generators (presets, extensions) to let
         the integration inject agent-specific frontmatter or body
-        transformations.  The default implementation returns *content*
-        unchanged.  Subclasses may override — see ``ClaudeIntegration``.
+        transformations.  The base implementation injects shared skills
+        guidance for converting dotted hook command names to hyphenated
+        slash commands.  Subclasses may override — see ``ClaudeIntegration``.
         """
-        return content
+        return self._inject_hook_command_note(content)
 
     def setup(
         self,
@@ -1502,6 +1795,8 @@ class SkillsIntegration(IntegrationBase):
                 f"{processed_body}"
             )
 
+            skill_content = self.post_process_skill_content(skill_content)
+
             # Write speckit-<name>/SKILL.md
             skill_dir = skills_dir / skill_name
             skill_file = skill_dir / "SKILL.md"

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.
 
@@ -444,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

@@ -2,24 +2,15 @@
 
 from __future__ import annotations
 
+import shutil
 from pathlib import Path
 from typing import Any
 
-import re
-
 import yaml
 
 from ..base import SkillsIntegration
 from ..manifest import IntegrationManifest
 
-# Note injected into hook sections so Claude maps dot-notation command
-# names (from extensions.yml) to the hyphenated skill names it uses.
-_HOOK_COMMAND_NOTE = (
-    "- When constructing slash commands from hook command names, "
-    "replace dots (`.`) with hyphens (`-`). "
-    "For example, `speckit.git.commit` → `/speckit-git-commit`.\n"
-)
-
 # Mapping of command template stem → argument-hint text shown inline
 # when a user invokes the slash command in Claude Code.
 ARGUMENT_HINTS: dict[str, str] = {
@@ -55,6 +46,27 @@ class ClaudeIntegration(SkillsIntegration):
     context_file = "CLAUDE.md"
     multi_install_safe = True
 
+    def is_cli_available(self) -> bool:
+        """Return ``True`` if the Claude Code CLI is installed.
+
+        Claude Code can be installed in multiple locations, not all of
+        which are on ``PATH``:
+
+        1. ``~/.claude/local/claude``                  — ``claude migrate-installer``
+        2. ``~/.claude/local/node_modules/.bin/claude`` — npm-local install (nvm)
+        3. Anywhere on ``PATH``                        — global npm install
+
+        See issues #123, #550, and #2597.
+        """
+        import specify_cli._utils as _utils_mod
+
+        if (
+            _utils_mod.CLAUDE_LOCAL_PATH.is_file()
+            or _utils_mod.CLAUDE_NPM_LOCAL_PATH.is_file()
+        ):
+            return True
+        return shutil.which(self.cli_executable) is not None
+
     @staticmethod
     def inject_argument_hint(content: str, hint: str) -> str:
         """Insert ``argument-hint`` after the first ``description:`` in YAML frontmatter.
@@ -159,41 +171,11 @@ class ClaudeIntegration(SkillsIntegration):
             out.append(line)
         return "".join(out)
 
-    @staticmethod
-    def _inject_hook_command_note(content: str) -> str:
-        """Insert a dot-to-hyphen note before each hook output instruction.
-
-        Targets the line ``- For each executable hook, output the following``
-        and inserts the note on the line before it, matching its indentation.
-        Skips if the note is already present.
-        """
-        if "replace dots" in content:
-            return content
-
-        def repl(m: re.Match[str]) -> str:
-            indent = m.group(1)
-            instruction = m.group(2)
-            eol = m.group(3)
-            return (
-                indent
-                + _HOOK_COMMAND_NOTE.rstrip("\n")
-                + eol
-                + indent
-                + instruction
-                + eol
-            )
-
-        return re.sub(
-            r"(?m)^(\s*)(- For each executable hook, output the following[^\r\n]*)(\r\n|\n|$)",
-            repl,
-            content,
-        )
-
     def post_process_skill_content(self, content: str) -> str:
         """Inject Claude-specific frontmatter flags and hook notes."""
-        updated = self._inject_frontmatter_flag(content, "user-invocable")
+        updated = super().post_process_skill_content(content)
+        updated = self._inject_frontmatter_flag(updated, "user-invocable")
         updated = self._inject_frontmatter_flag(updated, "disable-model-invocation", "false")
-        updated = self._inject_hook_command_note(updated)
         return updated
 
     def setup(
@@ -203,10 +185,9 @@ class ClaudeIntegration(SkillsIntegration):
         parsed_options: dict[str, Any] | None = None,
         **opts: Any,
     ) -> list[Path]:
-        """Install Claude skills, then inject Claude-specific flags and argument-hints."""
+        """Install Claude skills, then inject argument-hints."""
         created = super().setup(project_root, manifest, parsed_options, **opts)
 
-        # Post-process generated skill files
         skills_dir = self.skills_dest(project_root).resolve()
 
         for path in created:
@@ -221,7 +202,7 @@ class ClaudeIntegration(SkillsIntegration):
             content_bytes = path.read_bytes()
             content = content_bytes.decode("utf-8")
 
-            updated = self.post_process_skill_content(content)
+            updated = content
 
             # Inject argument-hint if available for this skill
             skill_dir_name = path.parent.name  # e.g. "speckit-plan"

src/specify_cli/integrations/cline/__init__.py

@@ -0,0 +1,162 @@
+"""Cline IDE integration."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from ..base import MarkdownIntegration
+from ..manifest import IntegrationManifest
+
+
+# Note injected into hook sections so Cline maps dot-notation command
+# names (from extensions.yml) to the hyphenated slash commands it uses.
+_HOOK_COMMAND_NOTE = (
+    "- When constructing slash commands from hook command names, "
+    "replace dots (`.`) with hyphens (`-`). "
+    "For example, `speckit.git.commit` → `/speckit-git-commit`.\n"
+)
+
+
+def format_cline_command_name(cmd_name: str) -> str:
+    """Convert command name to Cline-compatible hyphenated format.
+
+    Cline handles slash-commands optimally when they use hyphens instead of dots.
+    This function converts dot-notation command names to hyphenated format.
+
+    The function is idempotent: already-formatted names are returned unchanged.
+
+    Examples:
+        >>> format_cline_command_name("plan")
+        'speckit-plan'
+        >>> format_cline_command_name("speckit.plan")
+        'speckit-plan'
+        >>> format_cline_command_name("speckit.git.commit")
+        'speckit-git-commit'
+
+    Args:
+        cmd_name: Command name in dot notation (speckit.foo.bar),
+                  hyphenated format (speckit-foo-bar), or plain name (foo)
+
+    Returns:
+        Hyphenated command name with 'speckit-' prefix
+    """
+    cmd_name = cmd_name.replace(".", "-")
+
+    if not cmd_name.startswith("speckit-"):
+        cmd_name = f"speckit-{cmd_name}"
+
+    return cmd_name
+
+
+class ClineIntegration(MarkdownIntegration):
+    """Integration for Cline IDE."""
+
+    key = "cline"
+    config = {
+        "name": "Cline",
+        "folder": ".clinerules/",
+        "commands_subdir": "workflows",
+        "install_url": "https://github.com/cline/cline",
+        "requires_cli": False,
+    }
+    registrar_config = {
+        "dir": ".clinerules/workflows",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": ".md",
+        "inject_name": True,
+        "format_name": format_cline_command_name,
+        "invoke_separator": "-",
+    }
+    context_file = ".clinerules/specify-rules.md"
+    invoke_separator = "-"
+    multi_install_safe = True
+
+    def command_filename(self, template_name: str) -> str:
+        """Cline uses hyphenated filenames (e.g. speckit-git-commit.md)."""
+        return format_cline_command_name(template_name) + ".md"
+
+    def process_template(self, *args, **kwargs):
+        """Ensure shared templates render Cline command references with hyphens."""
+        kwargs.setdefault("invoke_separator", self.invoke_separator)
+        return super().process_template(*args, **kwargs)
+
+    @staticmethod
+    def _inject_hook_command_note(content: str) -> str:
+        """Insert a dot-to-hyphen note before each hook output instruction.
+
+        Targets the line ``- For each executable hook, output the following``
+        and inserts the note on the line before it, matching its indentation.
+        Skips if the note is already present.
+        """
+        if "replace dots" in content:
+            return content
+
+        def repl(m: re.Match[str]) -> str:
+            indent = m.group(1)
+            instruction = m.group(2)
+            eol = m.group(3)
+            return (
+                indent
+                + _HOOK_COMMAND_NOTE.rstrip("\n")
+                + eol
+                + indent
+                + instruction
+                + eol
+            )
+
+        return re.sub(
+            r"(?m)^(\s*)(- For each executable hook, output the following[^\r\n]*)(\r\n|\n|$)",
+            repl,
+            content,
+        )
+
+    @staticmethod
+    def _rewrite_handoff_references(content: str) -> str:
+        """Replace dot-notation agent references in handoffs with hyphens."""
+        return re.sub(
+            r"(?m)^(\s*agent:\s*)(speckit\.[A-Za-z0-9-_]+(?:\.[A-Za-z0-9-_]+)*)",
+            lambda m: f"{m.group(1)}{format_cline_command_name(m.group(2))}",
+            content,
+        )
+
+    def post_process_content(self, content: str) -> str:
+        """Apply Cline-specific transformations to command content."""
+        updated = self._inject_hook_command_note(content)
+        updated = self._rewrite_handoff_references(updated)
+        return updated
+
+    def setup(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        parsed_options: dict[str, Any] | None = None,
+        **opts: Any,
+    ) -> list[Path]:
+        """Install Cline commands and apply post-processing transformations."""
+        created = super().setup(project_root, manifest, parsed_options, **opts)
+
+        # Post-process generated command files
+        dest_dir = self.commands_dest(project_root).resolve()
+
+        for path in created:
+            # Only touch .md files under the commands directory
+            try:
+                path.resolve().relative_to(dest_dir)
+            except ValueError:
+                continue
+            if path.suffix != ".md":
+                continue
+
+            content_bytes = path.read_bytes()
+            content = content_bytes.decode("utf-8")
+
+            updated = self.post_process_content(content)
+
+            if updated != content:
+                path.write_bytes(updated.encode("utf-8"))
+                self.record_file_in_manifest(path, project_root, manifest)
+
+        return created

src/specify_cli/integrations/codex/__init__.py

@@ -37,7 +37,10 @@ class CodexIntegration(SkillsIntegration):
         output_json: bool = True,
     ) -> list[str] | None:
         # Codex uses ``codex exec "prompt"`` for non-interactive mode.
-        args: list[str] = ["codex", "exec", prompt]
+        # Resolve argv[0] via the shared executable resolver so operators can
+        # override the binary with SPECKIT_INTEGRATION_CODEX_EXECUTABLE.
+        args: list[str] = [self._resolve_executable(), "exec", prompt]
+        self._apply_extra_args_env_var(args)
         if model:
             args.extend(["--model", model])
         if output_json:

src/specify_cli/integrations/copilot/__init__.py

@@ -24,6 +24,16 @@ from ..base import IntegrationBase, IntegrationOption, SkillsIntegration
 from ..manifest import IntegrationManifest
 
 
+def _copilot_executable() -> str:
+    """Return the executable name for Copilot CLI on this platform.
+
+    On Windows, subprocess invocation is reliable with `copilot.cmd`.
+    """
+    if os.name == "nt":
+        return "copilot.cmd"
+    return "copilot"
+
+
 def _allow_all() -> bool:
     """Return True if the Copilot CLI should run with full permissions.
 
@@ -124,6 +134,18 @@ class CopilotIntegration(IntegrationBase):
             ),
         ]
 
+    def _resolve_executable(self) -> str:
+        """Return the Copilot CLI executable, respecting the env-var override.
+
+        Checks ``SPECKIT_INTEGRATION_COPILOT_EXECUTABLE`` first.  Falls
+        back to the platform-specific default from ``_copilot_executable()``
+        (``copilot.cmd`` on Windows, ``copilot`` elsewhere) so that
+        existing behaviour is preserved when the env var is unset.
+        """
+        env_name = "SPECKIT_INTEGRATION_COPILOT_EXECUTABLE"
+        override = os.environ.get(env_name, "").strip()
+        return override if override else _copilot_executable()
+
     def build_exec_args(
         self,
         prompt: str,
@@ -138,7 +160,8 @@ class CopilotIntegration(IntegrationBase):
         # Controlled by SPECKIT_COPILOT_ALLOW_ALL_TOOLS env var
         # (default: enabled).  The deprecated SPECKIT_ALLOW_ALL_TOOLS
         # is also honoured as a fallback.
-        args = ["copilot", "-p", prompt]
+        args = [self._resolve_executable(), "-p", prompt]
+        self._apply_extra_args_env_var(args)
         if _allow_all():
             args.append("--yolo")
         if model:
@@ -206,7 +229,12 @@ class CopilotIntegration(IntegrationBase):
             agent_name = f"speckit.{stem}"
             prompt = args or ""
 
-        cli_args = ["copilot", "-p", prompt]
+        cli_args = [self._resolve_executable(), "-p", prompt]
+        # Honour SPECKIT_INTEGRATION_COPILOT_EXTRA_ARGS for real workflow
+        # runs.  `dispatch_command` builds cli_args inline rather than
+        # going through `build_exec_args`, so the hook must be invoked
+        # here too — otherwise the env var is silently ignored.
+        self._apply_extra_args_env_var(cli_args)
         if not skills_mode:
             cli_args.extend(["--agent", agent_name])
         if _allow_all():
@@ -255,57 +283,13 @@ class CopilotIntegration(IntegrationBase):
         return f"speckit.{template_name}.agent.md"
 
     def post_process_skill_content(self, content: str) -> str:
-        """Inject Copilot-specific ``mode:`` field into SKILL.md frontmatter.
+        """Inject shared hook guidance into Copilot skill content.
 
-        Inserts ``mode: speckit.<stem>`` before the closing ``---`` so
-        Copilot can associate the skill with its agent mode.
+        Delegates to :class:`_CopilotSkillsHelper` for shared post-processing.
+        The ``mode:`` frontmatter field is intentionally omitted: VS Code
+        Copilot Agent Skills do not support it (see issue #2799).
         """
-        lines = content.splitlines(keepends=True)
-
-        # Extract skill name from frontmatter to derive the mode value
-        dash_count = 0
-        skill_name = ""
-        for line in lines:
-            stripped = line.rstrip("\n\r")
-            if stripped == "---":
-                dash_count += 1
-                if dash_count == 2:
-                    break
-                continue
-            if dash_count == 1:
-                if stripped.startswith("mode:"):
-                    return content  # already present
-                if stripped.startswith("name:"):
-                    # Parse: name: "speckit-plan" → speckit.plan
-                    val = stripped.split(":", 1)[1].strip().strip('"').strip("'")
-                    # Convert speckit-plan → speckit.plan
-                    if val.startswith("speckit-"):
-                        skill_name = "speckit." + val[len("speckit-"):]
-                    else:
-                        skill_name = val
-
-        if not skill_name:
-            return content
-
-        # Inject mode: before the closing --- of frontmatter
-        out: list[str] = []
-        dash_count = 0
-        injected = False
-        for line in lines:
-            stripped = line.rstrip("\n\r")
-            if stripped == "---":
-                dash_count += 1
-                if dash_count == 2 and not injected:
-                    if line.endswith("\r\n"):
-                        eol = "\r\n"
-                    elif line.endswith("\n"):
-                        eol = "\n"
-                    else:
-                        eol = ""
-                    out.append(f"mode: {skill_name}{eol}")
-                    injected = True
-            out.append(line)
-        return "".join(out)
+        return _CopilotSkillsHelper().post_process_skill_content(content)
 
     def setup(
         self,

src/specify_cli/integrations/cursor_agent/__init__.py

@@ -2,6 +2,12 @@
 
 Cursor Agent uses the ``.cursor/skills/speckit-<name>/SKILL.md`` layout.
 Commands are deprecated; ``--skills`` defaults to ``True``.
+
+The IDE/skills flow is the primary path and works without the
+``cursor-agent`` CLI being installed (``requires_cli=False``).  Workflow
+dispatch via ``cursor-agent -p --trust --approve-mcps --force <prompt>``
+is offered as an opt-in capability — the presence of ``build_exec_args()``
+is what indicates dispatch support, mirroring ``CopilotIntegration``.
 """
 
 from __future__ import annotations
@@ -15,7 +21,12 @@ class CursorAgentIntegration(SkillsIntegration):
         "name": "Cursor",
         "folder": ".cursor/",
         "commands_subdir": "skills",
-        "install_url": None,
+        "install_url": "https://docs.cursor.com/en/cli/overview",
+        # IDE-first integration: ``specify init --ai cursor-agent`` must
+        # work without the ``cursor-agent`` CLI installed (the IDE flow
+        # uses skills directly).  Workflow dispatch additionally requires
+        # the CLI on PATH, but that's enforced at dispatch time via
+        # ``shutil.which`` rather than as a hard ``specify init`` precheck.
         "requires_cli": False,
     }
     registrar_config = {
@@ -28,6 +39,50 @@ class CursorAgentIntegration(SkillsIntegration):
     context_file = ".cursor/rules/specify-rules.mdc"
     multi_install_safe = True
 
+    def build_exec_args(
+        self,
+        prompt: str,
+        *,
+        model: str | None = None,
+        output_json: bool = True,
+    ) -> list[str] | None:
+        """Build CLI arguments for non-interactive ``cursor-agent`` execution.
+
+        Always returns argv (no ``requires_cli`` guard) so workflow
+        dispatch is supported even though the integration's ``config``
+        sets ``requires_cli=False`` to keep the IDE-only flow unblocked.
+        This mirrors ``CopilotIntegration``: dispatch support is signalled
+        by overriding ``build_exec_args()``, not by the ``requires_cli``
+        flag (which is reserved for the ``specify init`` precheck).
+
+        Mandatory headless flags:
+
+        * ``-p`` — print/headless mode (access to all tools)
+        * ``--trust`` — bypass Workspace Trust prompt (CLI exits non-zero
+          otherwise)
+        * ``--approve-mcps`` — auto-approve MCP server loading (otherwise
+          MCP servers stay ``not loaded (needs approval)`` and tool calls
+          to them are silently dropped)
+        * ``--force`` — auto-approve tool invocations (shell/write/MCP),
+          matching the implicit "trusted environment" semantics that other
+          integrations (``claude -p``, ``codex --exec``) get by default
+
+        Together these are the minimum set required to make
+        ``specify workflow run speckit --input integration=cursor-agent``
+        behave the same way as it does for ``claude`` / ``codex``.
+        Verified locally: with ``--approve-mcps --force`` the agent can
+        call any configured MCP server (e.g. ``dingtalk-doc``) and write
+        files during ``/speckit-*`` skill execution; without them the run
+        either drops tool calls or exits non-zero on the first approval
+        prompt.
+        """
+        args = [self.key, "-p", "--trust", "--approve-mcps", "--force", prompt]
+        if model:
+            args.extend(["--model", model])
+        if output_json:
+            args.extend(["--output-format", "json"])
+        return args
+
     @classmethod
     def options(cls) -> list[IntegrationOption]:
         return [

src/specify_cli/integrations/devin/__init__.py

@@ -48,7 +48,8 @@ class DevinIntegration(SkillsIntegration):
         stdout instead of structured JSON. ``requires_cli=True`` is
         kept on the integration for tool detection.
         """
-        args = [self.key, "-p", prompt]
+        args = [self._resolve_executable(), "-p", prompt]
+        self._apply_extra_args_env_var(args)
         if model:
             args.extend(["--model", model])
         return args

src/specify_cli/integrations/hermes/__init__.py

@@ -0,0 +1,280 @@
+"""Hermes Agent integration — skills-based agent.
+
+Hermes Agent (https://github.com/NousResearch/hermes-agent) is an open-source
+AI agent framework by Nous Research.  It stores skills in
+``~/.hermes/skills/`` (user-global) rather than a project-local directory.
+
+Usage::
+
+    specify init my-project --integration hermes
+    specify init --here --ai hermes
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from shutil import rmtree
+from typing import Any
+
+import yaml
+
+from ..base import IntegrationOption, SkillsIntegration
+from ..manifest import IntegrationManifest
+
+
+class HermesIntegration(SkillsIntegration):
+    """Integration for Hermes Agent skills.
+
+    Hermes loads skills from ``~/.hermes/skills/`` (user home directory)
+    rather than a project-local path.  Skills are installed directly to
+    the global directory — no project-local copies are created since
+    Hermes discovers them globally.  A project-local marker directory
+    (``.hermes/skills/`` empty) is created so extension commands (e.g.
+    git) can detect Hermes as an active integration.  Uninstall removes
+    both the marker and all global ``speckit-*`` skills, matching the
+    standard integration teardown behaviour.
+    """
+
+    key = "hermes"
+    config = {
+        "name": "Hermes Agent",
+        "folder": ".hermes/",
+        "commands_subdir": "skills",
+        "install_url": "https://github.com/NousResearch/hermes-agent",
+        "requires_cli": True,
+    }
+    registrar_config = {
+        "dir": "~/.hermes/skills",
+        "detect_dir": ".hermes/skills",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": "/SKILL.md",
+    }
+    context_file = "AGENTS.md"
+
+    # -- Helpers -----------------------------------------------------------
+
+    @staticmethod
+    def _hermes_home_skills_dir() -> Path:
+        """Return ``~/.hermes/skills/`` — the global skills directory."""
+        return Path.home() / ".hermes" / "skills"
+
+    # -- Options -----------------------------------------------------------
+
+    @classmethod
+    def options(cls) -> list[IntegrationOption]:
+        return [
+            IntegrationOption(
+                "--skills",
+                is_flag=True,
+                default=True,
+                help="Install as agent skills (default for Hermes Agent)",
+            ),
+        ]
+
+    # -- Setup -------------------------------------------------------------
+
+    def setup(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        parsed_options: dict[str, Any] | None = None,
+        **opts: Any,
+    ) -> list[Path]:
+        """Install command templates as global Hermes skills.
+
+        Writes each skill directly to
+        ``~/.hermes/skills/speckit-<name>/SKILL.md`` where Hermes
+        discovers them at runtime.  No project-local SKILL.md copies are
+        created — the global directory is the single source of truth.
+        A project-local marker (``.hermes/skills/`` empty) is created
+        so extension commands (e.g. git) can detect Hermes as an active
+        integration.
+        """
+        templates = self.list_command_templates()
+        if not templates:
+            return []
+
+        # Safety check: verify manifest project_root matches (standard pattern)
+        project_root_resolved = project_root.resolve()
+        if manifest.project_root != project_root_resolved:
+            raise ValueError(
+                f"manifest.project_root ({manifest.project_root}) does not match "
+                f"project_root ({project_root_resolved})"
+            )
+
+        script_type = opts.get("script_type", "sh")
+        arg_placeholder = (
+            self.registrar_config.get("args", "$ARGUMENTS")
+            if self.registrar_config
+            else "$ARGUMENTS"
+        )
+
+        global_skills_dir = self._hermes_home_skills_dir()
+        global_skills_dir.mkdir(parents=True, exist_ok=True)
+
+        created: list[Path] = []
+
+        for src_file in templates:
+            raw = src_file.read_text(encoding="utf-8")
+
+            # Derive the skill name from the template stem
+            command_name = src_file.stem  # e.g. "plan"
+            skill_name = f"speckit-{command_name.replace('.', '-')}"
+
+            # Parse frontmatter for description
+            frontmatter: dict[str, Any] = {}
+            if raw.startswith("---"):
+                parts = raw.split("---", 2)
+                if len(parts) >= 3:
+                    try:
+                        fm = yaml.safe_load(parts[1])
+                        if isinstance(fm, dict):
+                            frontmatter = fm
+                    except yaml.YAMLError:
+                        pass
+
+            # Process body through the standard template pipeline
+            processed_body = self.process_template(
+                raw,
+                self.key,
+                script_type,
+                arg_placeholder,
+                context_file=self.context_file or "",
+                invoke_separator=self.invoke_separator,
+            )
+            # Strip the processed frontmatter — we rebuild it for skills.
+            if processed_body.startswith("---"):
+                parts = processed_body.split("---", 2)
+                if len(parts) >= 3:
+                    processed_body = parts[2]
+
+            # Select description
+            description = frontmatter.get("description", "")
+            if not description:
+                description = f"Spec Kit: {command_name} workflow"
+
+            # Build SKILL.md with manually formatted frontmatter
+            def _quote(v: str) -> str:
+                escaped = v.replace("\\", "\\\\").replace('"', '\\"')
+                return f'"{escaped}"'
+
+            skill_content = (
+                f"---\n"
+                f"name: {_quote(skill_name)}\n"
+                f"description: {_quote(description)}\n"
+                f"compatibility: "
+                f"{_quote('Requires spec-kit project structure with .specify/ directory')}\n"
+                f"metadata:\n"
+                f"  author: {_quote('github-spec-kit')}\n"
+                f"  source: {_quote('templates/commands/' + src_file.name)}\n"
+                f"---\n"
+                f"{processed_body}"
+            )
+
+            skill_content = self.post_process_skill_content(skill_content)
+
+            # Write directly to global ~/.hermes/skills/speckit-<name>/SKILL.md
+            skill_dir = global_skills_dir / skill_name
+            skill_dir.mkdir(parents=True, exist_ok=True)
+            skill_file = skill_dir / "SKILL.md"
+            normalized = skill_content.replace("\r\n", "\n")
+            skill_file.write_bytes(normalized.encode("utf-8"))
+            created.append(skill_file)
+
+        # Upsert managed context section into the agent context file
+        self.upsert_context_section(project_root)
+
+        # Create project-local marker directory so extension commands
+        # (e.g. git) can detect Hermes as an active integration.
+        # Hermes itself ignores this directory — skills live globally.
+        (project_root / ".hermes" / "skills").mkdir(parents=True, exist_ok=True)
+
+        return created
+
+    # -- Uninstall ---------------------------------------------------------
+
+    def teardown(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        *,
+        force: bool = False,
+    ) -> tuple[list[Path], list[Path]]:
+        """Uninstall integration files including global Hermes skills.
+
+        Removes the managed context section from AGENTS.md, removes the
+        project-local marker directory (if empty), delegates to
+        ``manifest.uninstall()`` for project-local tracked files, and
+        removes all ``speckit-*`` skills under ``~/.hermes/skills/``.
+
+        Global skills are always removed on teardown — this matches the
+        standard integration behaviour where all files created by the
+        integration are removed on ``specify integration uninstall``.
+        """
+        # Remove managed context section from AGENTS.md
+        self.remove_context_section(project_root)
+
+        # Delegate to manifest for project-local tracked files (scripts,
+        # templates, context entries tracked in the manifest).
+        removed, skipped = manifest.uninstall(project_root, force=force)
+
+        # Remove project-local marker directory if empty
+        local_skills_dir = project_root / ".hermes" / "skills"
+        if local_skills_dir.is_dir() and not any(local_skills_dir.iterdir()):
+            local_skills_dir.rmdir()
+            hermes_dir = project_root / ".hermes"
+            if hermes_dir.is_dir() and not any(hermes_dir.iterdir()):
+                hermes_dir.rmdir()
+
+        # Remove all global Hermes skills for speckit — these are always
+        # removed on uninstall regardless of the force flag, matching the
+        # standard behaviour where all integration files are cleaned up.
+        global_skills_dir = self._hermes_home_skills_dir()
+        if global_skills_dir.is_dir():
+            for skill_dir in sorted(global_skills_dir.iterdir()):
+                if skill_dir.is_dir() and skill_dir.name.startswith("speckit-"):
+                    try:
+                        rmtree(skill_dir)
+                        removed.append(skill_dir)
+                    except OSError:
+                        skipped.append(skill_dir)
+
+        return removed, skipped
+
+    # -- CLI dispatch ------------------------------------------------------
+
+    def build_exec_args(
+        self,
+        prompt: str,
+        *,
+        model: str | None = None,
+        output_json: bool = True,
+    ) -> list[str] | None:
+        """Build Hermes CLI invocation for programmatic dispatch.
+
+        Uses ``hermes chat -Q -q`` for one-shot queries in quiet mode,
+        mapping slash-command invocations to the appropriate skill-based
+        dispatch.
+        """
+        args = [self._resolve_executable(), "chat", "-Q"]
+
+        if model:
+            args.extend(["-m", model])
+        if output_json:
+            args.append("--json")
+
+        # If prompt starts with a slash command, pass it directly
+        # so Hermes can dispatch to the appropriate skill.
+        if prompt.startswith("/"):
+            command, _, remainder = prompt[1:].partition(" ")
+            if command:
+                args.extend(["-s", command])
+                if remainder:
+                    args.extend(["-q", remainder])
+            else:
+                args.extend(["-q", prompt])
+        else:
+            args.extend(["-q", prompt])
+
+        return args

src/specify_cli/integrations/kiro_cli/__init__.py

@@ -1,8 +1,18 @@
 """Kiro CLI integration."""
 
+import shutil
+
 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 +25,21 @@ class KiroCliIntegration(MarkdownIntegration):
     registrar_config = {
         "dir": ".kiro/prompts",
         "format": "markdown",
-        "args": "$ARGUMENTS",
+        "args": _KIRO_ARG_FALLBACK,
         "extension": ".md",
     }
     context_file = "AGENTS.md"
+
+    def is_cli_available(self) -> bool:
+        """Return ``True`` if the Kiro CLI is installed.
+
+        Kiro ships under two binary names: ``kiro-cli`` (preferred) and
+        the legacy ``kiro`` alias.  Either name satisfies the availability
+        check so existing installations continue to work.
+
+        See issue #2597.
+        """
+        return (
+            shutil.which("kiro-cli") is not None
+            or shutil.which("kiro") is not None
+        )

src/specify_cli/integrations/manifest.py

@@ -115,6 +115,7 @@ class IntegrationManifest:
         self.project_root = project_root.resolve()
         self.version = version
         self._files: dict[str, str] = {}  # rel_path → sha256 hex
+        self._recovered_files: set[str] = set()
         self._installed_at: str = ""
 
     # -- Manifest file location -------------------------------------------
@@ -131,6 +132,9 @@ class IntegrationManifest:
 
         Creates parent directories as needed.  Returns the absolute path
         of the written file.
+        If the path was previously marked as recovered via
+        ``record_existing(recovered=True)``, the recovered marker is
+        cleared because the bytes are now produced, not merely observed.
 
         Raises ``ValueError`` if *rel_path* resolves outside the project root.
         """
@@ -144,17 +148,77 @@ class IntegrationManifest:
 
         normalized = abs_path.relative_to(self.project_root).as_posix()
         self._files[normalized] = hashlib.sha256(content).hexdigest()
+        # ``record_file`` writes *produced* content, so any prior
+        # recovered marker for this path is no longer accurate.
+        self._recovered_files.discard(normalized)
         return abs_path
 
-    def record_existing(self, rel_path: str | Path) -> None:
-        """Record the hash of an already-existing file at *rel_path*.
+    def record_existing(self, rel_path: str | Path, *, recovered: bool = False) -> None:
+        """Record the hash of an already-existing regular file at *rel_path*.
 
-        Raises ``ValueError`` if *rel_path* resolves outside the project root.
+        When ``recovered=True``, the path is also marked in the manifest's
+        ``recovered_files`` list to signal that the file's on-disk hash was
+        *observed* during install (because the file already existed and was not
+        overwritten), not *produced* by the install. Future ``refresh_managed``
+        runs should consult ``is_recovered`` before treating the recorded hash
+        as a managed baseline.
+
+        Raises:
+            ValueError: if *rel_path* resolves outside the project root, is
+                a symlink, or is not a regular file. A directory or other
+                non-file path cannot be silently recorded — its hash would
+                be meaningless and ``check_modified``/``uninstall`` would
+                treat the entry as permanently broken.
+            OSError: if the underlying filesystem call (``is_symlink``,
+                ``is_file``, or the file-read used to compute the hash)
+                fails — for example a ``PermissionError`` on the path.
+                Callers should be prepared to handle ``OSError`` (and its
+                subclasses such as ``PermissionError``) in addition to
+                ``ValueError``.
         """
         rel = Path(rel_path)
+        # Cheap lexical pre-check first so absolute / parent-traversal paths
+        # don't trigger a filesystem stat outside the project root before
+        # ``_validate_rel_path`` raises. ``_validate_rel_path`` produces the
+        # canonical error messages used elsewhere.
+        if rel.is_absolute() or ".." in rel.parts:
+            _validate_rel_path(rel, self.project_root)
+            # _validate_rel_path raised for any actually-escaping path. If we reach
+            # here the path normalizes inside root (e.g. ``dir/../file.txt``).
+            # Reject anyway: manifest keys must be canonical so ``check_modified``
+            # and ``uninstall`` cannot key the same file under two paths.
+            raise ValueError(
+                f"Manifest paths must be canonical; '..' segments are not "
+                f"allowed (got {rel})"
+            )
+        # Walk each path component before resolution so a symlinked ancestor
+        # (e.g. ``linked_dir/file.txt`` where ``linked_dir`` is a symlink)
+        # cannot be silently followed by ``_validate_rel_path().resolve()``
+        # down to a target outside the project root. ``_ensure_safe_manifest_directory``
+        # uses the same pattern.
+        _walk = self.project_root
+        for part in rel.parts:
+            _walk = _walk / part
+            if _walk.is_symlink():
+                raise ValueError(
+                    f"Refusing to record symlinked manifest path: {rel} "
+                    f"(symlinked at {_walk.relative_to(self.project_root).as_posix()})"
+                )
         abs_path = _validate_rel_path(rel, self.project_root)
+        if not abs_path.is_file():
+            raise ValueError(
+                f"Manifest path is not a regular file: {rel}"
+            )
         normalized = abs_path.relative_to(self.project_root).as_posix()
         self._files[normalized] = _sha256(abs_path)
+        if recovered:
+            self._recovered_files.add(normalized)
+        else:
+            # ``recovered=False`` means the caller is asserting this path is
+            # managed-baseline now, not merely observed; drop any stale
+            # recovered marker so future is_recovered() queries reflect the
+            # transition. ``discard`` is a no-op when the key is absent.
+            self._recovered_files.discard(normalized)
 
     # -- Querying ---------------------------------------------------------
 
@@ -163,6 +227,37 @@ class IntegrationManifest:
         """Return a copy of the ``{rel_path: sha256}`` mapping."""
         return dict(self._files)
 
+    @property
+    def recovered_files(self) -> set[str]:
+        """Return a copy of the set of paths recorded with ``recovered=True``.
+
+        These entries had their hashes observed (not produced) during install
+        because the file already existed on disk and the install skipped it.
+        Their on-disk bytes may be user customizations — callers that would
+        overwrite based on hash equality (e.g. ``refresh_managed``) MUST check
+        ``is_recovered`` first.
+        """
+        return set(self._recovered_files)
+
+    def is_recovered(self, rel_path: str | Path) -> bool:
+        """Return True if *rel_path* was recorded via ``record_existing(recovered=True)``.
+
+        Input is normalized through the same pipeline as ``record_existing``:
+        absolute paths, paths escaping the project root, AND paths containing
+        ``'..'`` segments are rejected (returned as ``False``). This mirrors
+        ``record_existing``'s canonicalization guard — such paths can never
+        appear as stored keys, so the answer is always ``False``.
+        """
+        rel = Path(rel_path)
+        if rel.is_absolute() or ".." in rel.parts:
+            return False
+        try:
+            abs_path = _validate_rel_path(rel, self.project_root)
+            normalized = abs_path.relative_to(self.project_root).as_posix()
+        except ValueError:
+            return False
+        return normalized in self._recovered_files
+
     def check_modified(self) -> list[str]:
         """Return relative paths of tracked files whose content changed on disk."""
         modified: list[str] = []
@@ -269,6 +364,11 @@ class IntegrationManifest:
             "version": self.version,
             "installed_at": self._installed_at,
             "files": self._files,
+            **(
+                {"recovered_files": sorted(self._recovered_files)}
+                if self._recovered_files
+                else {}
+            ),
         }
         path = self.manifest_path
         content = json.dumps(data, indent=2) + "\n"
@@ -320,6 +420,20 @@ class IntegrationManifest:
         inst._installed_at = data.get("installed_at", "")
         inst._files = files
 
+        recovered = data.get("recovered_files", [])
+        if not isinstance(recovered, list) or not all(
+            isinstance(p, str) for p in recovered
+        ):
+            raise ValueError(
+                f"Integration manifest 'recovered_files' at {path} must be a "
+                "list of string paths"
+            )
+        inst._recovered_files = set(recovered)
+        # Drop any recovered_files entries that don't correspond to tracked
+        # files — defensive against externally-edited or partially-corrupted
+        # manifests. Inconsistent state self-corrects on next save().
+        inst._recovered_files &= set(inst._files.keys())
+
         stored_key = data.get("integration", "")
         if stored_key and stored_key != key:
             raise ValueError(

src/specify_cli/integrations/opencode/__init__.py

@@ -8,12 +8,13 @@ class OpencodeIntegration(MarkdownIntegration):
     config = {
         "name": "opencode",
         "folder": ".opencode/",
-        "commands_subdir": "command",
+        "commands_subdir": "commands",
         "install_url": "https://opencode.ai",
         "requires_cli": True,
     }
     registrar_config = {
-        "dir": ".opencode/command",
+        "dir": ".opencode/commands",
+        "legacy_dir": ".opencode/command",
         "format": "markdown",
         "args": "$ARGUMENTS",
         "extension": ".md",
@@ -27,7 +28,12 @@ class OpencodeIntegration(MarkdownIntegration):
         model: str | None = None,
         output_json: bool = True,
     ) -> list[str] | None:
-        args = [self.key, "run"]
+        args = [self._resolve_executable(), "run"]
+        # Apply operator-injected extra args before the prompt-derived
+        # --command and the canonical --format/-m flags so Spec Kit's
+        # later appends remain authoritative under repeated-flag CLI
+        # semantics.
+        self._apply_extra_args_env_var(args)
 
         message = prompt
         if prompt.startswith("/"):

src/specify_cli/integrations/rovodev/__init__.py

@@ -0,0 +1,263 @@
+"""RovoDev integration — Atlassian Rovo Dev via ``acli rovodev``.
+
+Extends ``SkillsIntegration`` to generate skill files under
+``.rovodev/skills/`` and additionally generates prompt wrappers
+under ``.rovodev/prompts/`` and a ``prompts.yml`` manifest.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ..base import SkillsIntegration
+from ..manifest import IntegrationManifest
+
+
+class RovodevIntegration(SkillsIntegration):
+    """Integration for Atlassian Rovo Dev.
+
+    Uses the skills layout (``speckit-<name>/SKILL.md``) and adds
+    prompt wrappers plus a ``prompts.yml`` manifest on top.
+    Runtime execution dispatches through ``acli rovodev``.
+    """
+
+    key = "rovodev"
+    config = {
+        "name": "RovoDev ACLI",
+        "folder": ".rovodev/",
+        "commands_subdir": "skills",
+        "install_url": "https://www.atlassian.com/software/rovo-dev",
+        "requires_cli": True,
+    }
+    registrar_config = {
+        "dir": ".rovodev/skills",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": "/SKILL.md",
+    }
+    context_file = "AGENTS.md"
+
+    # -- CLI dispatch ------------------------------------------------------
+
+    @property
+    def cli_executable(self) -> str:
+        """Executable name for CLI availability detection (``acli``).
+
+        RovoDev is invoked as ``acli rovodev …`` — ``acli`` is the
+        host binary; ``rovodev`` is a sub-command.  The integration key
+        is ``"rovodev"``, but the binary to detect on ``PATH`` is
+        ``"acli"``.
+
+        See issue #2597.
+        """
+        return "acli"
+
+    def _resolve_executable(self) -> str:
+        """Return the binary to invoke (``acli``).
+
+        RovoDev is invoked as ``acli rovodev …`` — ``acli`` is the executable
+        and ``rovodev`` is a subcommand. The base implementation falls back
+        to ``self.key`` (``"rovodev"``), which is the wrong binary, so we
+        override the fallback to ``"acli"`` while still honouring the
+        standard ``SPECKIT_INTEGRATION_ROVODEV_EXECUTABLE`` env-var override.
+        """
+        env_name = (
+            f"SPECKIT_INTEGRATION_{self.key.upper().replace('-', '_')}_EXECUTABLE"
+        )
+        override = os.environ.get(env_name, "").strip()
+        return override if override else "acli"
+
+    def build_exec_args(
+        self,
+        prompt: str,
+        *,
+        model: str | None = None,
+        output_json: bool = True,
+    ) -> list[str] | None:
+        """Build non-interactive ACLI args for RovoDev.
+
+        RovoDev supports a positional ``message`` for non-interactive runs.
+        ``output_json`` maps to ``--output-schema`` so dispatch callers can
+        request structured output.
+
+        The integration currently does not apply ``model`` overrides because
+        the expected config shape for ``--config-override`` is not yet wired
+        in this adapter.
+
+        Honours the standard env-var contract:
+          - ``SPECKIT_INTEGRATION_ROVODEV_EXECUTABLE`` overrides ``acli``
+          - ``SPECKIT_INTEGRATION_ROVODEV_EXTRA_ARGS`` injects extra CLI flags
+        """
+        _ = model
+        args = [self._resolve_executable(), "rovodev", "run", prompt]
+        self._apply_extra_args_env_var(args)
+        if output_json:
+            args.extend([
+                "--output-schema",
+                '{"type": "object", "properties": {"result": {"type": "string"}}}',
+            ])
+        return args
+
+
+    # -- Prompt wrapper + manifest generation ------------------------------
+
+    @staticmethod
+    def _render_prompt_wrapper(skill_name: str) -> str:
+        return f"use skill {skill_name} $ARGUMENTS\n"
+
+    def _generate_prompt_files(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        skill_paths: list[Path],
+    ) -> tuple[list[Path], list[dict[str, str]]]:
+        """Create thin prompt wrappers for each SKILL.md.
+
+        Skill name is derived from the parent directory name
+        (e.g. ``.rovodev/skills/speckit-plan/SKILL.md`` → ``speckit-plan``).
+
+        Returns (created_files, prompt_entries) where prompt_entries are
+        dicts suitable for inclusion in ``prompts.yml``.
+        """
+        prompts_dir = project_root / ".rovodev" / "prompts"
+        prompts_dir.mkdir(parents=True, exist_ok=True)
+
+        created: list[Path] = []
+        prompt_entries: list[dict[str, str]] = []
+
+        for skill_path in skill_paths:
+            if skill_path.name != "SKILL.md":
+                continue
+
+            skill_name = skill_path.parent.name
+            if not skill_name:
+                continue
+
+            prompt_filename = f"{skill_name}.prompt.md"
+            prompt_file = self.write_file_and_record(
+                self._render_prompt_wrapper(skill_name),
+                prompts_dir / prompt_filename,
+                project_root,
+                manifest,
+            )
+            created.append(prompt_file)
+
+            prompt_entries.append({
+                "name": skill_name,
+                "description": f"Invoke {skill_name} skill",
+                "content_file": f"prompts/{prompt_filename}",
+            })
+
+        return created, prompt_entries
+
+    @staticmethod
+    def _read_prompts_yml(path: Path) -> list[dict[str, Any]]:
+        """Read prompt entries from an existing ``prompts.yml``.
+
+        Returns an empty list if the file is missing, malformed, or
+        contains no valid prompt entries.
+        """
+        if not path.exists():
+            return []
+        try:
+            data = yaml.safe_load(path.read_text(encoding="utf-8"))
+        except (yaml.YAMLError, OSError, UnicodeError):
+            return []
+        if not isinstance(data, dict):
+            return []
+        prompts = data.get("prompts")
+        if not isinstance(prompts, list):
+            return []
+        return [dict(item) for item in prompts if isinstance(item, dict)]
+
+    @staticmethod
+    def _merge_prompt_entries(
+        existing: list[dict[str, Any]],
+        generated: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """Merge *generated* entries into *existing*, preserving user additions.
+
+        - Existing entries whose ``name`` matches a generated entry are
+          replaced in-place (preserving the user's ordering).
+        - Generated entries not already present are appended at the end.
+        - User-added entries (no matching generated name) are kept as-is.
+        """
+        generated_by_name = {e["name"]: e for e in generated if e.get("name")}
+
+        merged: list[dict[str, Any]] = []
+        seen: set[str] = set()
+
+        for entry in existing:
+            name = entry.get("name", "")
+            if name in generated_by_name:
+                merged.append(generated_by_name[name])
+                seen.add(name)
+            else:
+                merged.append(entry)
+
+        for entry in generated:
+            if entry.get("name", "") not in seen:
+                merged.append(entry)
+
+        return merged
+
+    def _merge_prompts_manifest(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        prompt_entries: list[dict[str, str]],
+    ) -> Path | None:
+        """Write ``prompts.yml``, merging with any existing user entries."""
+        if not prompt_entries:
+            return None
+
+        prompts_yml = project_root / ".rovodev" / "prompts.yml"
+        existing = self._read_prompts_yml(prompts_yml)
+        merged = self._merge_prompt_entries(existing, prompt_entries)
+
+        content = yaml.safe_dump(
+            {"prompts": merged},
+            default_flow_style=False,
+            sort_keys=False,
+            allow_unicode=True,
+            width=10_000,
+        )
+        return self.write_file_and_record(
+            content, prompts_yml, project_root, manifest,
+        )
+
+    # -- setup() -----------------------------------------------------------
+
+    def setup(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        parsed_options: dict[str, Any] | None = None,
+        **opts: Any,
+    ) -> list[Path]:
+        """Install RovoDev skills, then generate prompt wrappers and manifest.
+
+        1. ``SkillsIntegration.setup()`` generates skill files and
+           upserts the context section.
+        2. Generates prompt wrappers and ``prompts.yml`` for each skill
+           created in step 1.
+        """
+        created = super().setup(project_root, manifest, parsed_options, **opts)
+
+        # Generate prompt wrappers + merge prompts.yml
+        prompt_files, prompt_entries = self._generate_prompt_files(
+            project_root, manifest, created
+        )
+        created.extend(prompt_files)
+
+        manifest_file = self._merge_prompts_manifest(
+            project_root, manifest, prompt_entries
+        )
+        if manifest_file:
+            created.append(manifest_file)
+
+        return created

src/specify_cli/integrations/vibe/__init__.py

@@ -81,13 +81,13 @@ class VibeIntegration(SkillsIntegration):
             out.append(line)
         return "".join(out)
 
-
     def post_process_skill_content(self, content: str) -> str:
         """
-        Inject Vibe-specific frontmatter flags:
+        Inject shared hook guidance and Vibe-specific frontmatter flags:
         - user-invocable: allows the skill to be invoked by the user (not just other agents)
         """
-        updated = self._inject_frontmatter_flag(content, "user-invocable")
+        updated = super().post_process_skill_content(content)
+        updated = self._inject_frontmatter_flag(updated, "user-invocable")
         return updated
 
     def setup(
@@ -107,27 +107,4 @@ class VibeIntegration(SkillsIntegration):
             err=True,
         )
 
-        created = super().setup(project_root, manifest, parsed_options=parsed_options, **opts)
-
-        # Post-process generated skill files
-        skills_dir = self.skills_dest(project_root).resolve()
-
-        for path in created:
-            # Only touch SKILL.md files under the skills directory
-            try:
-                path.resolve().relative_to(skills_dir)
-            except ValueError:
-                continue
-            if path.name != "SKILL.md":
-                continue
-
-            content_bytes = path.read_bytes()
-            content = content_bytes.decode("utf-8")
-
-            updated = self.post_process_skill_content(content)
-
-            if updated != content:
-                path.write_bytes(updated.encode("utf-8"))
-                self.record_file_in_manifest(path, project_root, manifest)
-
-        return created
+        return super().setup(project_root, manifest, parsed_options=parsed_options, **opts)

src/specify_cli/presets.py

@@ -28,6 +28,8 @@ from packaging import version as pkg_version
 from packaging.specifiers import SpecifierSet, InvalidSpecifier
 
 from .extensions import REINSTALL_COMMAND, ExtensionRegistry, normalize_priority
+from .integrations.base import IntegrationBase
+from ._init_options import is_ai_skills_enabled
 
 
 def _substitute_core_template(
@@ -1048,9 +1050,9 @@ class PresetManager:
                     short_name = cmd_name
                     if short_name.startswith("speckit."):
                         short_name = short_name[len("speckit."):]
-                    desc = SKILL_DESCRIPTIONS.get(
+                    desc = fm.get("description", "") or SKILL_DESCRIPTIONS.get(
                         short_name.replace(".", "-"),
-                        fm.get("description", f"Command: {short_name}"),
+                        f"Command: {short_name}",
                     )
                     init_opts = load_init_options(self.project_root)
                     selected_ai = init_opts.get("ai") if isinstance(init_opts, dict) else ""
@@ -1058,6 +1060,9 @@ class PresetManager:
                         body = registrar.resolve_skill_placeholders(
                             selected_ai, fm, body, self.project_root
                         )
+                        body = self._resolve_skill_command_refs(
+                            body, registrar, selected_ai
+                        )
                     fm_data = registrar.build_skill_frontmatter(
                         selected_ai if isinstance(selected_ai, str) else "",
                         skill_name, desc,
@@ -1097,37 +1102,24 @@ class PresetManager:
     def _get_skills_dir(self) -> Optional[Path]:
         """Return the active skills directory for preset skill overrides.
 
-        Reads ``.specify/init-options.json`` to determine whether skills
-        are enabled and which agent was selected, then delegates to
-        the module-level ``_get_skills_dir()`` helper for the concrete path.
+        Delegates to :func:`resolve_active_skills_dir` which reads
+        init-options, applies the Kimi native-skills fallback, and
+        safely creates the directory when ``ai_skills`` is enabled.
 
-        Kimi is treated as a native-skills agent: if ``ai == "kimi"`` and
-        ``.kimi/skills`` exists, presets should still propagate command
-        overrides to skills even when ``ai_skills`` is false.
-
-        Returns:
-            The skills directory ``Path``, or ``None`` if skills were not
-            enabled and no native-skills fallback applies.
+        Returns ``None`` (instead of raising) when the directory cannot
+        be created due to symlink, containment, or permission issues so
+        that callers can fall back gracefully.
         """
-        from . import load_init_options, _get_skills_dir
-
-        opts = load_init_options(self.project_root)
-        if not isinstance(opts, dict):
-            opts = {}
-        agent = opts.get("ai")
-        if not isinstance(agent, str) or not agent:
+        from . import resolve_active_skills_dir, _print_cli_warning
+        try:
+            return resolve_active_skills_dir(self.project_root)
+        except (ValueError, OSError) as exc:
+            _print_cli_warning(
+                "resolve", "skills directory", None, exc,
+                continuing="Continuing without skill registration.",
+            )
             return None
 
-        ai_skills_enabled = bool(opts.get("ai_skills"))
-        if not ai_skills_enabled and agent != "kimi":
-            return None
-
-        skills_dir = _get_skills_dir(self.project_root, agent)
-        if not skills_dir.is_dir():
-            return None
-
-        return skills_dir
-
     @staticmethod
     def _skill_names_for_command(cmd_name: str) -> tuple[str, str]:
         """Return the modern and legacy skill directory names for a command."""
@@ -1147,6 +1139,23 @@ class PresetManager:
             title_name = title_name[len("speckit."):]
         return title_name.replace(".", " ").replace("-", " ").title()
 
+    @staticmethod
+    def _resolve_skill_command_refs(
+        body: str, registrar: "CommandRegistrar", selected_ai: str
+    ) -> str:
+        """Render ``__SPECKIT_COMMAND_*__`` tokens in a skill body as invocations.
+
+        Looks up the agent's invoke separator and rewrites each
+        ``__SPECKIT_COMMAND_<NAME>__`` placeholder into the matching
+        slash-command invocation — ``/speckit-<cmd>`` for a ``-`` separator,
+        ``/speckit.<cmd>`` for ``.`` — the same rendering the command layer
+        applies via ``CommandRegistrar.register_commands()``.
+        """
+        separator = registrar.AGENT_CONFIGS.get(selected_ai, {}).get(
+            "invoke_separator", "."
+        )
+        return IntegrationBase.resolve_command_refs(body, separator)
+
     def _build_extension_skill_restore_index(self) -> Dict[str, Dict[str, Any]]:
         """Index extension-backed skill restore data by skill directory name."""
         from .extensions import ExtensionManifest, ValidationError
@@ -1254,7 +1263,7 @@ class PresetManager:
         selected_ai = init_opts.get("ai")
         if not isinstance(selected_ai, str):
             return []
-        ai_skills_enabled = bool(init_opts.get("ai_skills"))
+        ai_skills_enabled = is_ai_skills_enabled(init_opts)
         registrar = CommandRegistrar()
         integration = get_integration(selected_ai)
         agent_config = registrar.AGENT_CONFIGS.get(selected_ai, {})
@@ -1314,15 +1323,16 @@ class PresetManager:
                         frontmatter[key] = core_frontmatter[key]
 
             original_desc = frontmatter.get("description", "")
-            enhanced_desc = SKILL_DESCRIPTIONS.get(
+            enhanced_desc = original_desc or SKILL_DESCRIPTIONS.get(
                 short_name,
-                original_desc or f"Spec-kit workflow command: {short_name}",
+                f"Spec-kit workflow command: {short_name}",
             )
             frontmatter = dict(frontmatter)
             frontmatter["description"] = enhanced_desc
             body = registrar.resolve_skill_placeholders(
                 selected_ai, frontmatter, body, self.project_root
             )
+            body = self._resolve_skill_command_refs(body, registrar, selected_ai)
 
             for target_skill_name in target_skill_names:
                 skill_subdir = skills_dir / target_skill_name
@@ -1415,11 +1425,14 @@ class PresetManager:
                     body = registrar.resolve_skill_placeholders(
                         selected_ai, frontmatter, body, self.project_root
                     )
+                    body = self._resolve_skill_command_refs(
+                        body, registrar, selected_ai
+                    )
 
                 original_desc = frontmatter.get("description", "")
-                enhanced_desc = SKILL_DESCRIPTIONS.get(
+                enhanced_desc = original_desc or SKILL_DESCRIPTIONS.get(
                     short_name,
-                    original_desc or f"Spec-kit workflow command: {short_name}",
+                    f"Spec-kit workflow command: {short_name}",
                 )
 
                 frontmatter_data = registrar.build_skill_frontmatter(
@@ -1452,6 +1465,9 @@ class PresetManager:
                     body = registrar.resolve_skill_placeholders(
                         selected_ai, frontmatter, body, self.project_root
                     )
+                    body = self._resolve_skill_command_refs(
+                        body, registrar, selected_ai
+                    )
 
                 command_name = extension_restore["command_name"]
                 title_name = self._skill_title_from_command(command_name)
@@ -1903,12 +1919,24 @@ class PresetCatalog:
             if not url:
                 continue
             self._validate_catalog_url(url)
+            raw_priority = item.get("priority", idx + 1)
+            # Reject bools explicitly: ``bool`` is a subclass of ``int`` so
+            # ``int(True)`` silently returns 1, which would let a YAML
+            # ``priority: true`` slip through as a valid priority of 1. The
+            # sibling integration-catalog reader in ``catalogs.py`` already
+            # guards this; mirror the check here so the three catalog
+            # validators stay consistent.
+            if isinstance(raw_priority, bool):
+                raise PresetValidationError(
+                    f"Invalid priority for catalog '{item.get('name', idx + 1)}': "
+                    f"expected integer, got {raw_priority!r}"
+                )
             try:
-                priority = int(item.get("priority", idx + 1))
+                priority = int(raw_priority)
             except (TypeError, ValueError):
                 raise PresetValidationError(
                     f"Invalid priority for catalog '{item.get('name', idx + 1)}': "
-                    f"expected integer, got {item.get('priority')!r}"
+                    f"expected integer, got {raw_priority!r}"
                 )
             raw_install = item.get("install_allowed", False)
             if isinstance(raw_install, str):

src/specify_cli/shared_infra.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+import re
 import tempfile
 from pathlib import Path
 from typing import Any
@@ -88,7 +89,13 @@ def _shared_relative_path(project_path: Path, dest: Path) -> Path:
     return rel
 
 
-def _ensure_safe_shared_directory(project_path: Path, directory: Path, *, create: bool = True) -> None:
+def _ensure_safe_shared_directory(
+    project_path: Path,
+    directory: Path,
+    *,
+    create: bool = True,
+    context: str = "shared infrastructure directory",
+) -> None:
     """Create a shared infra directory without following symlinked parents."""
     root = project_path.resolve()
     rel = _shared_relative_path(project_path, directory)
@@ -98,24 +105,24 @@ def _ensure_safe_shared_directory(project_path: Path, directory: Path, *, create
         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}")
+            raise SymlinkedSharedPathError(f"Refusing to use symlinked {context}: {label}")
         if current.exists():
             if not current.is_dir():
-                raise ValueError(f"Shared infrastructure directory path is not a directory: {label}")
+                raise ValueError(f"{context.capitalize()} 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
+                raise ValueError(f"{context.capitalize()} escapes project root: {label}") from None
             continue
         if not create:
-            raise ValueError(f"Shared infrastructure directory does not exist: {label}")
+            raise ValueError(f"{context.capitalize()} does not exist: {label}")
         current.mkdir()
         if current.is_symlink():
-            raise SymlinkedSharedPathError(f"Refusing to use symlinked shared infrastructure directory: {label}")
+            raise SymlinkedSharedPathError(f"Refusing to use symlinked {context}: {label}")
         try:
             current.resolve().relative_to(root)
         except (OSError, ValueError):
-            raise ValueError(f"Shared infrastructure directory escapes project root: {label}") from None
+            raise ValueError(f"{context.capitalize()} escapes project root: {label}") from None
 
 
 def _validate_safe_shared_directory(project_path: Path, directory: Path) -> None:
@@ -188,6 +195,37 @@ def _write_shared_bytes(
             temp_path.unlink()
 
 
+_BASH_FORMAT_COMMAND_RE = re.compile(
+    r"\$\(\s*format_speckit_command\s+(['\"]?)([A-Za-z0-9_.-]+)\1(?:\s+[^)]*)?\)"
+)
+_POWERSHELL_FORMAT_COMMAND_RE = re.compile(
+    r"Format-SpecKitCommand\s+-CommandName\s+(['\"])([A-Za-z0-9_.-]+)\1(?:\s+-RepoRoot\s+[^\r\n]+)?"
+)
+
+
+def _format_speckit_command(command_name: str, separator: str) -> str:
+    name = command_name.strip().lstrip("/")
+    if name.startswith("speckit."):
+        name = name[len("speckit.") :]
+    elif name.startswith("speckit-"):
+        name = name[len("speckit-") :]
+    name = name.replace(".", separator)
+    return f"/speckit{separator}{name}"
+
+
+def _resolve_dynamic_command_refs(content: str, separator: str) -> str:
+    """Render script runtime command helpers for managed shared infra copies."""
+
+    content = _BASH_FORMAT_COMMAND_RE.sub(
+        lambda match: _format_speckit_command(match.group(2), separator),
+        content,
+    )
+    return _POWERSHELL_FORMAT_COMMAND_RE.sub(
+        lambda match: f"'{_format_speckit_command(match.group(2), separator)}'",
+        content,
+    )
+
+
 def refresh_shared_templates(
     project_path: Path,
     *,
@@ -359,11 +397,38 @@ def install_shared_infra(
                                 preserved_user_files.append(rel)
                             else:
                                 skipped_files.append(rel)
+                                # Record the existing-on-disk file in the manifest so a
+                                # fresh manifest run against an already-populated
+                                # ``.specify/`` tree does not silently drop it (#2107).
+                                # ``prior_hashes`` is the function-scope snapshot taken
+                                # at entry, so this membership check is O(1) and avoids
+                                # the repeated ``dict(self._files)`` copy that
+                                # ``manifest.files`` performs on every access.
+                                if dst_path.is_file() and rel not in prior_hashes:
+                                    try:
+                                        manifest.record_existing(rel, recovered=True)
+                                    except (OSError, ValueError) as exc:
+                                        # Tolerate races / permission issues / non-file
+                                        # collisions so one weird path does not abort
+                                        # the whole install.
+                                        console.print(
+                                            f"[yellow]⚠[/yellow]  could not record {rel} in manifest: {exc}"
+                                        )
                             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))
+                        content = src_path.read_text(encoding="utf-8")
+                        content = IntegrationBase.resolve_command_refs(content, invoke_separator)
+                        content = _resolve_dynamic_command_refs(content, invoke_separator)
+                        planned_copies.append(
+                            (
+                                dst_path,
+                                rel,
+                                content.encode("utf-8"),
+                                src_path.stat().st_mode & 0o777,
+                            )
+                        )
 
     templates_src = shared_templates_source(core_pack=core_pack, repo_root=repo_root)
     if templates_src.is_dir():
@@ -383,6 +448,23 @@ def install_shared_infra(
                         preserved_user_files.append(rel)
                     else:
                         skipped_files.append(rel)
+                        # Record the existing-on-disk template in the manifest so a
+                        # fresh manifest run against an already-populated
+                        # ``.specify/`` tree does not silently drop it (#2107).
+                        # ``prior_hashes`` is the function-scope snapshot taken at
+                        # entry, so this membership check is O(1) and avoids the
+                        # repeated ``dict(self._files)`` copy that ``manifest.files``
+                        # performs on every access.
+                        if dst.is_file() and rel not in prior_hashes:
+                            try:
+                                manifest.record_existing(rel, recovered=True)
+                            except (OSError, ValueError) as exc:
+                                # Tolerate races / permission issues / non-file
+                                # collisions so one weird path does not abort
+                                # the whole install.
+                                console.print(
+                                    f"[yellow]⚠[/yellow]  could not record {rel} in manifest: {exc}"
+                                )
                     continue
 
                 content = src.read_text(encoding="utf-8")
@@ -401,7 +483,7 @@ def install_shared_infra(
 
     if skipped_files:
         console.print(
-            f"[yellow]⚠[/yellow]  {len(skipped_files)} shared infrastructure file(s) already exist and were not updated:"
+            f"[yellow]⚠[/yellow]  {len(skipped_files)} shared infrastructure path(s) already exist and were not updated:"
         )
         for path in skipped_files:
             console.print(f"    {path}")

src/specify_cli/workflows/engine.py

@@ -11,6 +11,7 @@ The engine is the orchestrator that:
 from __future__ import annotations
 
 import json
+import os
 import re
 import uuid
 from datetime import datetime, timezone
@@ -19,6 +20,10 @@ from typing import Any
 
 import yaml
 
+from ..integration_state import (
+    default_integration_key,
+    try_read_integration_json,
+)
 from .base import RunStatus, StepContext, StepResult, StepStatus
 
 
@@ -143,6 +148,35 @@ def validate_workflow(definition: WorkflowDefinition) -> list[str]:
                     f"Must be 'string', 'number', or 'boolean'."
                 )
 
+            # Validate the default eagerly so authoring mistakes (e.g. a
+            # default not in the declared enum, or a non-numeric default for
+            # a number input) surface at install/validation time instead of
+            # at workflow-execution time. ``"auto"`` for the integration
+            # input is a runtime-resolved sentinel, so only the
+            # enum-membership check is exempted for that exact case — the
+            # declared type is still enforced (e.g. ``type: number`` paired
+            # with ``default: "auto"`` is still rejected).
+            if "default" in input_def:
+                default_value = input_def["default"]
+                is_auto_integration = (
+                    input_name == "integration" and default_value == "auto"
+                )
+                validation_input_def: dict[str, Any] = input_def
+                if is_auto_integration and "enum" in input_def:
+                    validation_input_def = {
+                        key: value
+                        for key, value in input_def.items()
+                        if key != "enum"
+                    }
+                try:
+                    WorkflowEngine._coerce_input(
+                        input_name, default_value, validation_input_def
+                    )
+                except ValueError as exc:
+                    errors.append(
+                        f"Input {input_name!r} has invalid default: {exc}"
+                    )
+
     # -- Steps ------------------------------------------------------------
     if not isinstance(definition.steps, list):
         errors.append("'steps' must be a list.")
@@ -198,6 +232,22 @@ def _validate_steps(
             step_errors = step_impl.validate(step_config)
             errors.extend(step_errors)
 
+        # Validate optional `continue_on_error` field. The engine honours
+        # this on any step that returns StepStatus.FAILED so the pipeline can route
+        # around the failure via a downstream `if` or `switch` (or a
+        # `gate` that surfaces the failure to the operator via message
+        # interpolation). The field must be a literal boolean —
+        # coercion from truthy strings is deliberately not supported so
+        # authoring mistakes surface at validation time rather than
+        # silently changing run semantics.
+        if "continue_on_error" in step_config:
+            coe = step_config["continue_on_error"]
+            if not isinstance(coe, bool):
+                errors.append(
+                    f"Step {step_id!r}: 'continue_on_error' must be a "
+                    f"boolean, got {type(coe).__name__}."
+                )
+
         # Recursively validate nested steps
         for nested_key in ("then", "else", "steps"):
             nested = step_config.get(nested_key)
@@ -231,16 +281,49 @@ def _validate_steps(
 class RunState:
     """Manages workflow run state for persistence and resume."""
 
+    # ``run_id`` is interpolated into a filesystem path (``runs/<run_id>``)
+    # by both ``save()`` and ``load()``. Constrain it to a charset that
+    # cannot contain path separators (``/`` ``\``), parent-directory
+    # segments (``..``), or NULs — anything that could escape the
+    # ``.specify/workflows/runs/`` directory or be mis-interpreted by the
+    # filesystem. The first-character anchor blocks IDs that start with
+    # ``-`` (which would be mistaken for a CLI flag in error messages
+    # and shell completions).
+    _RUN_ID_PATTERN = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$")
+
+    @classmethod
+    def _validate_run_id(cls, run_id: str) -> None:
+        """Raise ``ValueError`` if ``run_id`` is not a safe path component.
+
+        This is the single source of truth for what counts as a valid
+        ``run_id``. ``__init__`` calls it to reject malformed IDs at
+        construction time; ``load`` calls it *before* interpolating the
+        ID into a path so a malicious value cannot probe or read files
+        outside ``.specify/workflows/runs/<run_id>/``.
+        """
+        if not isinstance(run_id, str) or not cls._RUN_ID_PATTERN.match(run_id):
+            raise ValueError(
+                f"Invalid run_id {run_id!r}: must be alphanumeric with "
+                "hyphens/underscores only (and must start with an "
+                "alphanumeric character)."
+            )
+
     def __init__(
         self,
         run_id: str | None = None,
         workflow_id: str = "",
         project_root: Path | None = None,
     ) -> None:
-        self.run_id = run_id or str(uuid.uuid4())[:8]
-        if not re.match(r'^[a-zA-Z0-9][a-zA-Z0-9_-]*$', self.run_id):
-            msg = f"Invalid run_id {self.run_id!r}: must be alphanumeric with hyphens/underscores only."
-            raise ValueError(msg)
+        # ``run_id is None`` (omitted) → auto-generate. An explicit empty
+        # string is *not* the same as "omitted" and must be validated like
+        # any other caller-provided value — otherwise ``__init__("")``
+        # would silently substitute a UUID while ``load("")`` rejects, and
+        # the two entry points would diverge on the empty-string vector.
+        if run_id is None:
+            self.run_id = str(uuid.uuid4())[:8]
+        else:
+            self.run_id = run_id
+        self._validate_run_id(self.run_id)
         self.workflow_id = workflow_id
         self.project_root = project_root or Path(".")
         self.status = RunStatus.CREATED
@@ -281,7 +364,20 @@ class RunState:
 
     @classmethod
     def load(cls, run_id: str, project_root: Path) -> RunState:
-        """Load a run state from disk."""
+        """Load a run state from disk.
+
+        Validates ``run_id`` against ``_RUN_ID_PATTERN`` *before* building
+        the lookup path. Without this guard, a caller passing a value like
+        ``../escape`` (e.g. via ``specify workflow resume`` CLI argument)
+        would interpolate path-traversal segments into
+        ``runs_dir`` below, letting ``state_path.exists()`` probe arbitrary
+        paths and ``json.load`` read attacker-planted JSON from outside
+        the project's ``runs/`` directory. ``__init__`` already runs this
+        check on the stored ``state_data["run_id"]``, but that fires
+        *after* the file lookup — too late to prevent the disclosure.
+        Mirrors the precedent in ``agents._ensure_within_directory``.
+        """
+        cls._validate_run_id(run_id)
         runs_dir = project_root / ".specify" / "workflows" / "runs" / run_id
         state_path = runs_dir / "state.json"
         if not state_path.exists():
@@ -353,10 +449,10 @@ class WorkflowEngine:
         ValueError:
             If the workflow YAML is invalid.
         """
-        path = Path(source)
+        path = Path(source).expanduser()
 
         # Try as a direct file path first
-        if path.suffix in (".yml", ".yaml") and path.exists():
+        if path.suffix.lower() in (".yml", ".yaml") and path.is_file():
             return WorkflowDefinition.from_yaml(path)
 
         # Try as an installed workflow ID
@@ -392,7 +488,7 @@ class WorkflowEngine:
         inputs:
             User-provided input values.
         run_id:
-            Optional run ID (auto-generated if not provided).
+            Optional run ID (uses SPECKIT_WORKFLOW_RUN_ID when set, otherwise auto-generated).
 
         Returns
         -------
@@ -400,8 +496,14 @@ class WorkflowEngine:
         """
         from . import STEP_REGISTRY
 
+        effective_run_id = run_id
+        if effective_run_id is None:
+            env_run_id = os.environ.get("SPECKIT_WORKFLOW_RUN_ID", "").strip()
+            if env_run_id:
+                effective_run_id = env_run_id
+
         state = RunState(
-            run_id=run_id,
+            run_id=effective_run_id,
             workflow_id=definition.id,
             project_root=self.project_root,
         )
@@ -451,8 +553,19 @@ class WorkflowEngine:
         state.save()
         return state
 
-    def resume(self, run_id: str) -> RunState:
-        """Resume a paused or failed workflow run."""
+    def resume(
+        self,
+        run_id: str,
+        inputs: dict[str, Any] | None = None,
+    ) -> RunState:
+        """Resume a paused or failed workflow run.
+
+        When ``inputs`` is provided, the values are merged over the run's
+        persisted inputs and re-resolved through the same typed validation
+        path used by :meth:`execute`, so the resumed step sees updated
+        workflow inputs. Keys not supplied keep their persisted values; an
+        empty/``None`` ``inputs`` leaves the run's inputs unchanged.
+        """
         state = RunState.load(run_id, self.project_root)
         if state.status not in (RunStatus.PAUSED, RunStatus.FAILED):
             msg = f"Cannot resume run {run_id!r} with status {state.status.value!r}."
@@ -468,6 +581,12 @@ class WorkflowEngine:
         else:
             definition = self.load_workflow(state.workflow_id)
 
+        # Merge any newly-supplied inputs over the persisted ones and
+        # re-validate through the same typing path as the initial run.
+        if inputs:
+            merged = {**state.inputs, **inputs}
+            state.inputs = self._resolve_inputs(definition, merged)
+
         # Restore context
         context = StepContext(
             inputs=state.inputs,
@@ -589,7 +708,10 @@ class WorkflowEngine:
 
             # Handle failures
             if result.status == StepStatus.FAILED:
-                # Gate abort (output.aborted) maps to ABORTED status
+                # Gate abort (output.aborted) maps to ABORTED status.
+                # Aborts are deliberate operator decisions, so
+                # `continue_on_error` does NOT override them — that flag
+                # is for transient/expected step failures only.
                 if result.output.get("aborted"):
                     state.status = RunStatus.ABORTED
                     state.append_log(
@@ -598,15 +720,49 @@ class WorkflowEngine:
                             "step_id": step_id,
                         }
                     )
-                else:
-                    state.status = RunStatus.FAILED
+                    state.save()
+                    return
+
+                # `continue_on_error: true` lets the pipeline route
+                # around the failure instead of halting. The step
+                # result (including exit_code, stderr, status) is
+                # still recorded so a downstream `if` or `switch`
+                # can branch on it (or a `gate` can surface it to the
+                # operator via message interpolation). Log a single,
+                # unambiguous event per failure resolution — either
+                # the run continued past it, or it halted.
+                #
+                # Use identity comparison (`is True`) rather than
+                # truthiness so that only a literal boolean enables
+                # the behaviour, even if validation was skipped.
+                # Validation rejects non-bool values at parse time,
+                # but `WorkflowEngine.execute()` does not auto-validate
+                # (see `WorkflowEngine.load_workflow`, whose docstring
+                # explicitly notes "not yet validated; call
+                # `validate_workflow()` or `engine.validate()`
+                # separately"), so a caller passing an unvalidated
+                # definition could otherwise see truthy non-bool
+                # values like the string `"true"` silently change
+                # run semantics.
+                if step_config.get("continue_on_error") is True:
                     state.append_log(
                         {
-                            "event": "step_failed",
+                            "event": "step_continue_on_error",
                             "step_id": step_id,
                             "error": result.error,
                         }
                     )
+                    state.save()
+                    continue
+
+                state.status = RunStatus.FAILED
+                state.append_log(
+                    {
+                        "event": "step_failed",
+                        "step_id": step_id,
+                        "error": result.error,
+                    }
+                )
                 state.save()
                 return
 
@@ -640,22 +796,29 @@ class WorkflowEngine:
                         if not evaluate_condition(condition, context):
                             break
                         # Namespace nested step IDs per iteration
-                        iter_steps = []
-                        for ns in result.next_steps:
+                        # so logs and state keys are unique.
+                        # Execute one step at a time and alias each
+                        # result back to the unprefixed key so that
+                        # later steps in the same body and the loop
+                        # condition see the latest values.
+                        for ns_idx, ns in enumerate(result.next_steps):
                             ns_copy = dict(ns)
-                            if "id" in ns_copy:
-                                ns_copy["id"] = f"{step_id}:{ns_copy['id']}:{_loop_iter + 1}"
-                            iter_steps.append(ns_copy)
-                        self._execute_steps(
-                            iter_steps, context, state, registry,
-                            step_offset=-1,
-                        )
-                        if state.status in (
-                            RunStatus.PAUSED,
-                            RunStatus.FAILED,
-                            RunStatus.ABORTED,
-                        ):
-                            return
+                            orig = ns_copy.get("id")
+                            base_id = orig or f"step-{ns_idx}"
+                            ns_copy["id"] = f"{step_id}:{base_id}:{_loop_iter + 1}"
+                            self._execute_steps(
+                                [ns_copy], context, state, registry,
+                                step_offset=-1,
+                            )
+                            if state.status in (
+                                RunStatus.PAUSED,
+                                RunStatus.FAILED,
+                                RunStatus.ABORTED,
+                            ):
+                                return
+                            if orig and ns_copy["id"] in context.steps:
+                                context.steps[orig] = context.steps[ns_copy["id"]]
+                                state.step_results[orig] = context.steps[ns_copy["id"]]
 
             # Fan-out: execute nested step template per item with unique IDs
             if step_type == "fan-out":
@@ -711,16 +874,73 @@ class WorkflowEngine:
             if not isinstance(input_def, dict):
                 continue
             if name in provided:
-                resolved[name] = self._coerce_input(
-                    name, provided[name], input_def
-                )
+                # Resolve sentinels for explicitly-provided values too: a
+                # caller passing ``{"integration": "auto"}`` (which the
+                # workflow prompt advertises as a valid value) must be
+                # treated identically to omitting the input and letting the
+                # default flow through, so dispatch never sees the literal
+                # sentinel.
+                value = self._resolve_default(name, provided[name])
             elif "default" in input_def:
-                resolved[name] = input_def["default"]
+                value = self._resolve_default(name, input_def["default"])
             elif input_def.get("required", False):
                 msg = f"Required input {name!r} not provided."
                 raise ValueError(msg)
+            else:
+                continue
+
+            # When the ``integration`` default could not be resolved against
+            # project state and falls back to the literal ``"auto"``
+            # sentinel, strip ``enum`` from the input definition before
+            # coercion so a workflow that lists specific integrations in
+            # ``enum`` does not crash at runtime on the sentinel value.
+            # NOTE: only enum-membership is skipped; ``_coerce_input``
+            # still enforces the declared ``type`` against the filtered
+            # definition (``string`` rejects non-strings, ``number`` rejects
+            # bools and uncoercible values, ``boolean`` rejects non-bools),
+            # so ill-typed values still fail fast here.
+            coerce_input_def = input_def
+            if (
+                name == "integration"
+                and value == "auto"
+                and "enum" in input_def
+            ):
+                coerce_input_def = {
+                    key: val
+                    for key, val in input_def.items()
+                    if key != "enum"
+                }
+            resolved[name] = self._coerce_input(name, value, coerce_input_def)
         return resolved
 
+    def _resolve_default(self, name: str, default: Any) -> Any:
+        """Resolve special default sentinels against project state.
+
+        For the ``integration`` input, ``"auto"`` resolves to the integration
+        recorded in ``.specify/integration.json`` so workflows dispatch to the
+        AI the project was actually initialized with, instead of a hardcoded
+        value baked into the workflow YAML.
+        """
+        if name == "integration" and default == "auto":
+            resolved = self._load_project_integration()
+            if resolved is not None:
+                return resolved
+        return default
+
+    def _load_project_integration(self) -> str | None:
+        """Read the default integration key from ``.specify/integration.json``.
+
+        Delegates parsing and schema validation to
+        :func:`try_read_integration_json` — the same low-level helper used by
+        the CLI — so the engine cannot drift from CLI behavior on the parse
+        path. Returns ``None`` when the file is missing, malformed, or
+        written by a newer CLI; callers fall back to the literal default.
+        """
+        state, error = try_read_integration_json(self.project_root)
+        if state is None or error is not None:
+            return None
+        return default_integration_key(state)
+
     @staticmethod
     def _coerce_input(
         name: str, value: Any, input_def: dict[str, Any]
@@ -730,6 +950,13 @@ class WorkflowEngine:
         enum_values = input_def.get("enum")
 
         if input_type == "number":
+            # Reject bools explicitly: ``bool`` is a subclass of ``int`` so
+            # ``float(True)`` succeeds and would silently coerce a YAML
+            # authoring mistake like ``type: number`` + ``default: true``
+            # into ``1``. Fail fast instead.
+            if isinstance(value, bool):
+                msg = f"Input {name!r} expected a number, got {value!r}."
+                raise ValueError(msg)
             try:
                 value = float(value)
                 if value == int(value):
@@ -746,6 +973,17 @@ class WorkflowEngine:
                 else:
                     msg = f"Input {name!r} expected a boolean, got {value!r}."
                     raise ValueError(msg)
+            elif not isinstance(value, bool):
+                msg = f"Input {name!r} expected a boolean, got {value!r}."
+                raise ValueError(msg)
+        elif input_type == "string":
+            # Without this, ``type: string`` accepts any Python value
+            # (numbers, lists, dicts) because nothing else rejects it —
+            # YAML ``default: 5`` would slip through. Require an actual
+            # string so authoring mistakes fail at resolve time.
+            if not isinstance(value, str):
+                msg = f"Input {name!r} expected a string, got {value!r}."
+                raise ValueError(msg)
 
         if enum_values is not None and value not in enum_values:
             msg = (

src/specify_cli/workflows/expressions.py

@@ -102,6 +102,15 @@ def _build_namespace(context: Any) -> dict[str, Any]:
         ns["item"] = context.item
     if hasattr(context, "fan_in"):
         ns["fan_in"] = context.fan_in or {}
+    # Engine-managed runtime metadata. Always present (even outside a
+    # run) so templates referencing it never error: `run_id` falls back
+    # to an empty string when no run is active (dry-run, validation,
+    # ad-hoc evaluator usage). The value is the same one Spec Kit
+    # prints as `Run ID:` at the end of `workflow run` — auto-generated
+    # runs use an 8-character uuid4 hex; operator-supplied ids may be
+    # any alphanumeric string with hyphens or underscores.
+    run_id = getattr(context, "run_id", None) or ""
+    ns["context"] = {"run_id": run_id}
     return ns
 
 

src/specify_cli/workflows/steps/command/__init__.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import shutil
 from pathlib import Path
 from typing import Any
 
@@ -126,12 +125,10 @@ class CommandStep(StepBase):
         if impl is None:
             return None
 
-        # Check if the integration supports CLI dispatch
-        if impl.build_exec_args("test") is None:
-            return None
-
-        # Check if the CLI tool is actually installed
-        if not shutil.which(impl.key):
+        # Check if the CLI tool is actually installed via the integration's
+        # own availability check (honours custom executables, dual binaries,
+        # and non-PATH install paths).  See issue #2597.
+        if not impl.is_cli_available():
             return None
 
         project_root = Path(context.project_root) if context.project_root else None