chore: bump version to 0.8.15

2026-07-04 04:45:43 +08:00 · 2026-05-27 11:28:33 +00:00
129 changed files with 2413 additions and 16822 deletions
--- a/.editorconfig
+++ b/.editorconfig
@@ -1,28 +0,0 @@
 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
--- a/.github/workflows/add-community-extension.lock.yml
+++ b/.github/workflows/add-community-extension.lock.yml
@@ -1,4 +1,4 @@
-# gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"2ace61d3a4e86e81ce7ff110e118981b4d88a06aa351ecdc2c3b64e44b10690f","compiler_version":"v0.74.8","strict":true,"agent_id":"copilot"}
+# gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"1583d46477aa35f00e2c7ab97f06bacf4f6e21bdaa9d58b0ef704a588e588a7e","compiler_version":"v0.74.8","strict":true,"agent_id":"copilot"}
 # gh-aw-manifest: {"version":1,"secrets":["COPILOT_GITHUB_TOKEN","GH_AW_CI_TRIGGER_TOKEN","GH_AW_GITHUB_MCP_SERVER_TOKEN","GH_AW_GITHUB_TOKEN","GITHUB_TOKEN"],"actions":[{"repo":"actions/checkout","sha":"de0fac2e4500dabe0009e67214ff5f5447ce83dd","version":"v6.0.2"},{"repo":"actions/download-artifact","sha":"3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c","version":"v8.0.1"},{"repo":"actions/github-script","sha":"3a2844b7e9c422d3c10d287c895573f7108da1b3","version":"v9.0.0"},{"repo":"actions/setup-node","sha":"48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e","version":"v6.4.0"},{"repo":"actions/upload-artifact","sha":"043fb46d1a93c77aae656e7c1c64a875d1fc6a0a","version":"v7.0.1"},{"repo":"github/gh-aw-actions/setup","sha":"efa55847f72aadb03490d955263ff911bf758700","version":"v0.74.8"}],"containers":[{"image":"ghcr.io/github/gh-aw-firewall/agent:0.25.49"},{"image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.25.49"},{"image":"ghcr.io/github/gh-aw-firewall/squid:0.25.49"},{"image":"ghcr.io/github/gh-aw-mcpg:v0.3.9","digest":"sha256:64828b42a4482f58fab16509d7f8f495a6d97c972a98a68aff20543531ac0388","pinned_image":"ghcr.io/github/gh-aw-mcpg:v0.3.9@sha256:64828b42a4482f58fab16509d7f8f495a6d97c972a98a68aff20543531ac0388"},{"image":"ghcr.io/github/github-mcp-server:v1.0.4"},{"image":"node:lts-alpine","digest":"sha256:d1b3b4da11eefd5941e7f0b9cf17783fc99d9c6fc34884a665f40a06dbdfc94f","pinned_image":"node:lts-alpine@sha256:d1b3b4da11eefd5941e7f0b9cf17783fc99d9c6fc34884a665f40a06dbdfc94f"}]}
 #    ___                   _   _      
 #   / _ \                 | | (_)     
@@ -38,7 +38,7 @@
 #   - actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 (source v9)
 #   - actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
 #   - actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-#   - github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+#   - github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
 #
 # Container images used:
 #   - ghcr.io/github/gh-aw-firewall/agent:0.25.49
@@ -52,6 +52,8 @@ name: "Add Community Extension from Issue Submission"
 on:
  issues:
    types:
    - opened
    - edited
    - labeled
  # skip-bots: # Skip-bots processed as bot check in pre-activation job
  # - github-actions # Skip-bots processed as bot check in pre-activation job
@@ -90,7 +92,7 @@ jobs:
    steps:
      - name: Setup Scripts
        id: setup
-        uses: github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+        uses: github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
        with:
          destination: ${{ runner.temp }}/gh-aw/actions
          job-name: ${{ github.job }}
@@ -204,23 +206,23 @@ jobs:
        run: |
          bash "${RUNNER_TEMP}/gh-aw/actions/create_prompt_first.sh"
          {
-          cat << 'GH_AW_PROMPT_767e1d181d9dae54_EOF'
+          cat << 'GH_AW_PROMPT_2b92c540a0b471a7_EOF'
          <system>
-          GH_AW_PROMPT_767e1d181d9dae54_EOF
+          GH_AW_PROMPT_2b92c540a0b471a7_EOF
          cat "${RUNNER_TEMP}/gh-aw/prompts/xpia.md"
          cat "${RUNNER_TEMP}/gh-aw/prompts/temp_folder_prompt.md"
          cat "${RUNNER_TEMP}/gh-aw/prompts/markdown.md"
          cat "${RUNNER_TEMP}/gh-aw/prompts/safe_outputs_prompt.md"
-          cat << 'GH_AW_PROMPT_767e1d181d9dae54_EOF'
+          cat << 'GH_AW_PROMPT_2b92c540a0b471a7_EOF'
          <safe-output-tools>
          Tools: add_comment(max:2), create_pull_request, add_labels(max:3), missing_tool, missing_data, noop
-          GH_AW_PROMPT_767e1d181d9dae54_EOF
+          GH_AW_PROMPT_2b92c540a0b471a7_EOF
          cat "${RUNNER_TEMP}/gh-aw/prompts/safe_outputs_create_pull_request.md"
-          cat << 'GH_AW_PROMPT_767e1d181d9dae54_EOF'
+          cat << 'GH_AW_PROMPT_2b92c540a0b471a7_EOF'
          </safe-output-tools>
-          GH_AW_PROMPT_767e1d181d9dae54_EOF
+          GH_AW_PROMPT_2b92c540a0b471a7_EOF
          cat "${RUNNER_TEMP}/gh-aw/prompts/mcp_cli_tools_prompt.md"
-          cat << 'GH_AW_PROMPT_767e1d181d9dae54_EOF'
+          cat << 'GH_AW_PROMPT_2b92c540a0b471a7_EOF'
          <github-context>
          The following GitHub context information is available for this workflow:
          {{#if github.actor}}
@@ -252,12 +254,12 @@ jobs:
            - **Note**: If a branch you need is not in the list above and is not listed as an additional fetched ref, it has NOT been checked out. For private repositories you cannot fetch it without proper authentication. If the branch is required and not available, exit with an error and ask the user to add it to the `fetch:` option of the `checkout:` configuration (e.g., `fetch: ["refs/pulls/open/*"]` for all open PR refs, or `fetch: ["main", "feature/my-branch"]` for specific branches).
          </github-context>
-          GH_AW_PROMPT_767e1d181d9dae54_EOF
+          GH_AW_PROMPT_2b92c540a0b471a7_EOF
          cat "${RUNNER_TEMP}/gh-aw/prompts/github_mcp_tools_with_safeoutputs_prompt.md"
-          cat << 'GH_AW_PROMPT_767e1d181d9dae54_EOF'
+          cat << 'GH_AW_PROMPT_2b92c540a0b471a7_EOF'
          </system>
          {{#runtime-import .github/workflows/add-community-extension.md}}
-          GH_AW_PROMPT_767e1d181d9dae54_EOF
+          GH_AW_PROMPT_2b92c540a0b471a7_EOF
          } > "$GH_AW_PROMPT"
      - name: Interpolate variables and render templates
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
@@ -368,7 +370,7 @@ jobs:
    steps:
      - name: Setup Scripts
        id: setup
-        uses: github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+        uses: github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
        with:
          destination: ${{ runner.temp }}/gh-aw/actions
          job-name: ${{ github.job }}
@@ -464,9 +466,9 @@ jobs:
          mkdir -p "${RUNNER_TEMP}/gh-aw/safeoutputs"
          mkdir -p /tmp/gh-aw/safeoutputs
          mkdir -p /tmp/gh-aw/mcp-logs/safeoutputs
-          cat > "${RUNNER_TEMP}/gh-aw/safeoutputs/config.json" << 'GH_AW_SAFE_OUTPUTS_CONFIG_95f097d550e5bb4b_EOF'
+          cat > "${RUNNER_TEMP}/gh-aw/safeoutputs/config.json" << 'GH_AW_SAFE_OUTPUTS_CONFIG_66c58b0f685caa27_EOF'
-          {"add_comment":{"max":2},"add_labels":{"allowed":["extension-submission","validation-passed","validation-failed","needs-info"],"max":3},"create_pull_request":{"draft":true,"labels":["extension-submission","automated"],"max":1,"max_patch_files":100,"max_patch_size":1024,"protect_top_level_dot_folders":true,"protected_files":["package.json","bun.lockb","bunfig.toml","deno.json","deno.jsonc","deno.lock","global.json","NuGet.Config","Directory.Packages.props","mix.exs","mix.lock","go.mod","go.sum","stack.yaml","stack.yaml.lock","pom.xml","build.gradle","build.gradle.kts","settings.gradle","settings.gradle.kts","gradle.properties","package-lock.json","yarn.lock","pnpm-lock.yaml","npm-shrinkwrap.json","requirements.txt","Pipfile","Pipfile.lock","pyproject.toml","setup.py","setup.cfg","Gemfile","Gemfile.lock","uv.lock","CODEOWNERS","DESIGN.md","CONTRIBUTING.md","SECURITY.md","CODE_OF_CONDUCT.md","AGENTS.md","CLAUDE.md","GEMINI.md"],"protected_files_policy":"blocked","title_prefix":"[extension] "},"create_report_incomplete_issue":{},"missing_data":{},"missing_tool":{},"noop":{"max":1,"report-as-issue":"false"},"report_incomplete":{}}
+          {"add_comment":{"max":2},"add_labels":{"allowed":["extension-submission","validation-passed","validation-failed","needs-info"],"max":3},"create_pull_request":{"draft":true,"labels":["extension-submission","automated"],"max":1,"max_patch_files":100,"max_patch_size":1024,"protect_top_level_dot_folders":true,"protected_files":["package.json","bun.lockb","bunfig.toml","deno.json","deno.jsonc","deno.lock","global.json","NuGet.Config","Directory.Packages.props","mix.exs","mix.lock","go.mod","go.sum","stack.yaml","stack.yaml.lock","pom.xml","build.gradle","build.gradle.kts","settings.gradle","settings.gradle.kts","gradle.properties","package-lock.json","yarn.lock","pnpm-lock.yaml","npm-shrinkwrap.json","requirements.txt","Pipfile","Pipfile.lock","pyproject.toml","setup.py","setup.cfg","Gemfile","Gemfile.lock","uv.lock","CODEOWNERS","DESIGN.md","CONTRIBUTING.md","SECURITY.md","CODE_OF_CONDUCT.md","AGENTS.md","CLAUDE.md","GEMINI.md"],"protected_files_policy":"blocked","title_prefix":"[extension] "},"create_report_incomplete_issue":{},"missing_data":{},"missing_tool":{},"noop":{"max":1,"report-as-issue":"true"},"report_incomplete":{}}
-          GH_AW_SAFE_OUTPUTS_CONFIG_95f097d550e5bb4b_EOF
+          GH_AW_SAFE_OUTPUTS_CONFIG_66c58b0f685caa27_EOF
      - name: Generate Safe Outputs Tools
        env:
          GH_AW_TOOLS_META_JSON: |
@@ -722,7 +724,7 @@ jobs:
          mkdir -p /home/runner/.copilot
          GH_AW_NODE=$(which node 2>/dev/null || command -v node 2>/dev/null || echo node)
-          cat << GH_AW_MCP_CONFIG_9f16469ceb45c7f6_EOF | "$GH_AW_NODE" "${RUNNER_TEMP}/gh-aw/actions/start_mcp_gateway.cjs"
+          cat << GH_AW_MCP_CONFIG_881a93100a972629_EOF | "$GH_AW_NODE" "${RUNNER_TEMP}/gh-aw/actions/start_mcp_gateway.cjs"
          {
            "mcpServers": {
              "github": {
@@ -763,7 +765,7 @@ jobs:
              "payloadDir": "${MCP_GATEWAY_PAYLOAD_DIR}"
            }
          }
-          GH_AW_MCP_CONFIG_9f16469ceb45c7f6_EOF
+          GH_AW_MCP_CONFIG_881a93100a972629_EOF
      - name: Mount MCP servers as CLIs
        id: mount-mcp-clis
        continue-on-error: true
@@ -1045,7 +1047,7 @@ jobs:
    steps:
      - name: Setup Scripts
        id: setup
-        uses: github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+        uses: github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
        with:
          destination: ${{ runner.temp }}/gh-aw/actions
          job-name: ${{ github.job }}
@@ -1079,7 +1081,7 @@ jobs:
          GH_AW_WORKFLOW_NAME: "Add Community Extension from Issue Submission"
          GH_AW_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          GH_AW_AGENT_CONCLUSION: ${{ needs.agent.result }}
-          GH_AW_NOOP_REPORT_AS_ISSUE: "false"
+          GH_AW_NOOP_REPORT_AS_ISSUE: "true"
        with:
          github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
          script: |
@@ -1186,7 +1188,7 @@ jobs:
    steps:
      - name: Setup Scripts
        id: setup
-        uses: github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+        uses: github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
        with:
          destination: ${{ runner.temp }}/gh-aw/actions
          job-name: ${{ github.job }}
@@ -1382,7 +1384,7 @@ jobs:
    steps:
      - name: Setup Scripts
        id: setup
-        uses: github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+        uses: github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
        with:
          destination: ${{ runner.temp }}/gh-aw/actions
          job-name: ${{ github.job }}
@@ -1454,7 +1456,7 @@ jobs:
    steps:
      - name: Setup Scripts
        id: setup
-        uses: github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+        uses: github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
        with:
          destination: ${{ runner.temp }}/gh-aw/actions
          job-name: ${{ github.job }}
@@ -1556,7 +1558,7 @@ jobs:
          GH_AW_ALLOWED_DOMAINS: "api.business.githubcopilot.com,api.enterprise.githubcopilot.com,api.github.com,api.githubcopilot.com,api.individual.githubcopilot.com,api.snapcraft.io,archive.ubuntu.com,azure.archive.ubuntu.com,crl.geotrust.com,crl.globalsign.com,crl.identrust.com,crl.sectigo.com,crl.thawte.com,crl.usertrust.com,crl.verisign.com,crl3.digicert.com,crl4.digicert.com,crls.ssl.com,github.com,host.docker.internal,json-schema.org,json.schemastore.org,keyserver.ubuntu.com,ocsp.digicert.com,ocsp.geotrust.com,ocsp.globalsign.com,ocsp.identrust.com,ocsp.sectigo.com,ocsp.ssl.com,ocsp.thawte.com,ocsp.usertrust.com,ocsp.verisign.com,packagecloud.io,packages.cloud.google.com,packages.microsoft.com,ppa.launchpad.net,raw.githubusercontent.com,registry.npmjs.org,s.symcb.com,s.symcd.com,security.ubuntu.com,telemetry.enterprise.githubcopilot.com,ts-crl.ws.symantec.com,ts-ocsp.ws.symantec.com,www.googleapis.com"
          GITHUB_SERVER_URL: ${{ github.server_url }}
          GITHUB_API_URL: ${{ github.api_url }}
-          GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: "{\"add_comment\":{\"max\":2},\"add_labels\":{\"allowed\":[\"extension-submission\",\"validation-passed\",\"validation-failed\",\"needs-info\"],\"max\":3},\"create_pull_request\":{\"draft\":true,\"labels\":[\"extension-submission\",\"automated\"],\"max\":1,\"max_patch_files\":100,\"max_patch_size\":1024,\"protect_top_level_dot_folders\":true,\"protected_files\":[\"package.json\",\"bun.lockb\",\"bunfig.toml\",\"deno.json\",\"deno.jsonc\",\"deno.lock\",\"global.json\",\"NuGet.Config\",\"Directory.Packages.props\",\"mix.exs\",\"mix.lock\",\"go.mod\",\"go.sum\",\"stack.yaml\",\"stack.yaml.lock\",\"pom.xml\",\"build.gradle\",\"build.gradle.kts\",\"settings.gradle\",\"settings.gradle.kts\",\"gradle.properties\",\"package-lock.json\",\"yarn.lock\",\"pnpm-lock.yaml\",\"npm-shrinkwrap.json\",\"requirements.txt\",\"Pipfile\",\"Pipfile.lock\",\"pyproject.toml\",\"setup.py\",\"setup.cfg\",\"Gemfile\",\"Gemfile.lock\",\"uv.lock\",\"CODEOWNERS\",\"DESIGN.md\",\"CONTRIBUTING.md\",\"SECURITY.md\",\"CODE_OF_CONDUCT.md\",\"AGENTS.md\",\"CLAUDE.md\",\"GEMINI.md\"],\"protected_files_policy\":\"blocked\",\"title_prefix\":\"[extension] \"},\"create_report_incomplete_issue\":{},\"missing_data\":{},\"missing_tool\":{},\"noop\":{\"max\":1,\"report-as-issue\":\"false\"},\"report_incomplete\":{}}"
+          GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: "{\"add_comment\":{\"max\":2},\"add_labels\":{\"allowed\":[\"extension-submission\",\"validation-passed\",\"validation-failed\",\"needs-info\"],\"max\":3},\"create_pull_request\":{\"draft\":true,\"labels\":[\"extension-submission\",\"automated\"],\"max\":1,\"max_patch_files\":100,\"max_patch_size\":1024,\"protect_top_level_dot_folders\":true,\"protected_files\":[\"package.json\",\"bun.lockb\",\"bunfig.toml\",\"deno.json\",\"deno.jsonc\",\"deno.lock\",\"global.json\",\"NuGet.Config\",\"Directory.Packages.props\",\"mix.exs\",\"mix.lock\",\"go.mod\",\"go.sum\",\"stack.yaml\",\"stack.yaml.lock\",\"pom.xml\",\"build.gradle\",\"build.gradle.kts\",\"settings.gradle\",\"settings.gradle.kts\",\"gradle.properties\",\"package-lock.json\",\"yarn.lock\",\"pnpm-lock.yaml\",\"npm-shrinkwrap.json\",\"requirements.txt\",\"Pipfile\",\"Pipfile.lock\",\"pyproject.toml\",\"setup.py\",\"setup.cfg\",\"Gemfile\",\"Gemfile.lock\",\"uv.lock\",\"CODEOWNERS\",\"DESIGN.md\",\"CONTRIBUTING.md\",\"SECURITY.md\",\"CODE_OF_CONDUCT.md\",\"AGENTS.md\",\"CLAUDE.md\",\"GEMINI.md\"],\"protected_files_policy\":\"blocked\",\"title_prefix\":\"[extension] \"},\"create_report_incomplete_issue\":{},\"missing_data\":{},\"missing_tool\":{},\"noop\":{\"max\":1,\"report-as-issue\":\"true\"},\"report_incomplete\":{}}"
          GH_AW_CI_TRIGGER_TOKEN: ${{ secrets.GH_AW_CI_TRIGGER_TOKEN }}
        with:
          github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
--- a/.github/workflows/add-community-extension.md
+++ b/.github/workflows/add-community-extension.md
@@ -4,7 +4,7 @@ emoji: "🧩"
 on:
  issues:
-    types: [labeled]
+    types: [opened, edited, labeled]
  skip-bots: [github-actions, copilot, dependabot]
 tools:
@@ -22,8 +22,6 @@ checkout:
  fetch-depth: 0
 safe-outputs:
  noop:
    report-as-issue: false
  create-pull-request:
    title-prefix: "[extension] "
    labels: [extension-submission, automated]
@@ -49,9 +47,14 @@ or update entries in the community extension catalog.
 ## Triggering Conditions
-This workflow only triggers when the `extension-submission` label is added to an
+This workflow triggers on issue events. **Only process the issue if ALL of these
-issue. Before processing, verify that the issue title starts with `[Extension]:`.
+conditions are met:**
-If it does not, stop without commenting.
+
 1. The issue has the `extension-submission` label
 2. The issue title starts with `[Extension]:`
 If the issue does not meet these conditions, add a brief comment explaining that
 this workflow only processes extension submission issues, then stop.
 ## Step 1 — Read and Parse the Issue
--- a/.github/workflows/add-community-preset.lock.yml
+++ b/.github/workflows/add-community-preset.lock.yml
@@ -1,4 +1,4 @@
-# gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"f209d3fbcde6b25fd5099c7b1ea0d3dace8967b23d8049a92566c213ed9ccc5e","compiler_version":"v0.74.8","strict":true,"agent_id":"copilot"}
+# gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"6111bd4a1cd2c363f1f05f185164e08883d6df79da732a8c07b9aa602ed7dfe6","compiler_version":"v0.74.8","strict":true,"agent_id":"copilot"}
 # gh-aw-manifest: {"version":1,"secrets":["COPILOT_GITHUB_TOKEN","GH_AW_CI_TRIGGER_TOKEN","GH_AW_GITHUB_MCP_SERVER_TOKEN","GH_AW_GITHUB_TOKEN","GITHUB_TOKEN"],"actions":[{"repo":"actions/checkout","sha":"de0fac2e4500dabe0009e67214ff5f5447ce83dd","version":"v6.0.2"},{"repo":"actions/download-artifact","sha":"3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c","version":"v8.0.1"},{"repo":"actions/github-script","sha":"3a2844b7e9c422d3c10d287c895573f7108da1b3","version":"v9.0.0"},{"repo":"actions/setup-node","sha":"48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e","version":"v6.4.0"},{"repo":"actions/upload-artifact","sha":"043fb46d1a93c77aae656e7c1c64a875d1fc6a0a","version":"v7.0.1"},{"repo":"github/gh-aw-actions/setup","sha":"efa55847f72aadb03490d955263ff911bf758700","version":"v0.74.8"}],"containers":[{"image":"ghcr.io/github/gh-aw-firewall/agent:0.25.49"},{"image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.25.49"},{"image":"ghcr.io/github/gh-aw-firewall/squid:0.25.49"},{"image":"ghcr.io/github/gh-aw-mcpg:v0.3.9","digest":"sha256:64828b42a4482f58fab16509d7f8f495a6d97c972a98a68aff20543531ac0388","pinned_image":"ghcr.io/github/gh-aw-mcpg:v0.3.9@sha256:64828b42a4482f58fab16509d7f8f495a6d97c972a98a68aff20543531ac0388"},{"image":"ghcr.io/github/github-mcp-server:v1.0.4"},{"image":"node:lts-alpine","digest":"sha256:d1b3b4da11eefd5941e7f0b9cf17783fc99d9c6fc34884a665f40a06dbdfc94f","pinned_image":"node:lts-alpine@sha256:d1b3b4da11eefd5941e7f0b9cf17783fc99d9c6fc34884a665f40a06dbdfc94f"}]}
 #    ___                   _   _      
 #   / _ \                 | | (_)     
@@ -38,7 +38,7 @@
 #   - actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 (source v9)
 #   - actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
 #   - actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-#   - github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+#   - github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
 #
 # Container images used:
 #   - ghcr.io/github/gh-aw-firewall/agent:0.25.49
@@ -52,6 +52,8 @@ name: "Add Community Preset from Issue Submission"
 on:
  issues:
    types:
    - opened
    - edited
    - labeled
  # skip-bots: # Skip-bots processed as bot check in pre-activation job
  # - github-actions # Skip-bots processed as bot check in pre-activation job
@@ -90,7 +92,7 @@ jobs:
    steps:
      - name: Setup Scripts
        id: setup
-        uses: github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+        uses: github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
        with:
          destination: ${{ runner.temp }}/gh-aw/actions
          job-name: ${{ github.job }}
@@ -204,23 +206,23 @@ jobs:
        run: |
          bash "${RUNNER_TEMP}/gh-aw/actions/create_prompt_first.sh"
          {
-          cat << 'GH_AW_PROMPT_c25ce620b285c8e3_EOF'
+          cat << 'GH_AW_PROMPT_fc7609016a7d28af_EOF'
          <system>
-          GH_AW_PROMPT_c25ce620b285c8e3_EOF
+          GH_AW_PROMPT_fc7609016a7d28af_EOF
          cat "${RUNNER_TEMP}/gh-aw/prompts/xpia.md"
          cat "${RUNNER_TEMP}/gh-aw/prompts/temp_folder_prompt.md"
          cat "${RUNNER_TEMP}/gh-aw/prompts/markdown.md"
          cat "${RUNNER_TEMP}/gh-aw/prompts/safe_outputs_prompt.md"
-          cat << 'GH_AW_PROMPT_c25ce620b285c8e3_EOF'
+          cat << 'GH_AW_PROMPT_fc7609016a7d28af_EOF'
          <safe-output-tools>
          Tools: add_comment(max:2), create_pull_request, add_labels(max:3), missing_tool, missing_data, noop
-          GH_AW_PROMPT_c25ce620b285c8e3_EOF
+          GH_AW_PROMPT_fc7609016a7d28af_EOF
          cat "${RUNNER_TEMP}/gh-aw/prompts/safe_outputs_create_pull_request.md"
-          cat << 'GH_AW_PROMPT_c25ce620b285c8e3_EOF'
+          cat << 'GH_AW_PROMPT_fc7609016a7d28af_EOF'
          </safe-output-tools>
-          GH_AW_PROMPT_c25ce620b285c8e3_EOF
+          GH_AW_PROMPT_fc7609016a7d28af_EOF
          cat "${RUNNER_TEMP}/gh-aw/prompts/mcp_cli_tools_prompt.md"
-          cat << 'GH_AW_PROMPT_c25ce620b285c8e3_EOF'
+          cat << 'GH_AW_PROMPT_fc7609016a7d28af_EOF'
          <github-context>
          The following GitHub context information is available for this workflow:
          {{#if github.actor}}
@@ -252,12 +254,12 @@ jobs:
            - **Note**: If a branch you need is not in the list above and is not listed as an additional fetched ref, it has NOT been checked out. For private repositories you cannot fetch it without proper authentication. If the branch is required and not available, exit with an error and ask the user to add it to the `fetch:` option of the `checkout:` configuration (e.g., `fetch: ["refs/pulls/open/*"]` for all open PR refs, or `fetch: ["main", "feature/my-branch"]` for specific branches).
          </github-context>
-          GH_AW_PROMPT_c25ce620b285c8e3_EOF
+          GH_AW_PROMPT_fc7609016a7d28af_EOF
          cat "${RUNNER_TEMP}/gh-aw/prompts/github_mcp_tools_with_safeoutputs_prompt.md"
-          cat << 'GH_AW_PROMPT_c25ce620b285c8e3_EOF'
+          cat << 'GH_AW_PROMPT_fc7609016a7d28af_EOF'
          </system>
          {{#runtime-import .github/workflows/add-community-preset.md}}
-          GH_AW_PROMPT_c25ce620b285c8e3_EOF
+          GH_AW_PROMPT_fc7609016a7d28af_EOF
          } > "$GH_AW_PROMPT"
      - name: Interpolate variables and render templates
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
@@ -368,7 +370,7 @@ jobs:
    steps:
      - name: Setup Scripts
        id: setup
-        uses: github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+        uses: github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
        with:
          destination: ${{ runner.temp }}/gh-aw/actions
          job-name: ${{ github.job }}
@@ -464,9 +466,9 @@ jobs:
          mkdir -p "${RUNNER_TEMP}/gh-aw/safeoutputs"
          mkdir -p /tmp/gh-aw/safeoutputs
          mkdir -p /tmp/gh-aw/mcp-logs/safeoutputs
-          cat > "${RUNNER_TEMP}/gh-aw/safeoutputs/config.json" << 'GH_AW_SAFE_OUTPUTS_CONFIG_50dbf4670371d6f7_EOF'
+          cat > "${RUNNER_TEMP}/gh-aw/safeoutputs/config.json" << 'GH_AW_SAFE_OUTPUTS_CONFIG_9e8dea0461236832_EOF'
-          {"add_comment":{"max":2},"add_labels":{"allowed":["preset-submission","validation-passed","validation-failed","needs-info"],"max":3},"create_pull_request":{"draft":true,"labels":["preset-submission","automated"],"max":1,"max_patch_files":100,"max_patch_size":1024,"protect_top_level_dot_folders":true,"protected_files":["package.json","bun.lockb","bunfig.toml","deno.json","deno.jsonc","deno.lock","global.json","NuGet.Config","Directory.Packages.props","mix.exs","mix.lock","go.mod","go.sum","stack.yaml","stack.yaml.lock","pom.xml","build.gradle","build.gradle.kts","settings.gradle","settings.gradle.kts","gradle.properties","package-lock.json","yarn.lock","pnpm-lock.yaml","npm-shrinkwrap.json","requirements.txt","Pipfile","Pipfile.lock","pyproject.toml","setup.py","setup.cfg","Gemfile","Gemfile.lock","uv.lock","CODEOWNERS","DESIGN.md","CONTRIBUTING.md","SECURITY.md","CODE_OF_CONDUCT.md","AGENTS.md","CLAUDE.md","GEMINI.md"],"protected_files_policy":"blocked","title_prefix":"[preset] "},"create_report_incomplete_issue":{},"missing_data":{},"missing_tool":{},"noop":{"max":1,"report-as-issue":"false"},"report_incomplete":{}}
+          {"add_comment":{"max":2},"add_labels":{"allowed":["preset-submission","validation-passed","validation-failed","needs-info"],"max":3},"create_pull_request":{"draft":true,"labels":["preset-submission","automated"],"max":1,"max_patch_files":100,"max_patch_size":1024,"protect_top_level_dot_folders":true,"protected_files":["package.json","bun.lockb","bunfig.toml","deno.json","deno.jsonc","deno.lock","global.json","NuGet.Config","Directory.Packages.props","mix.exs","mix.lock","go.mod","go.sum","stack.yaml","stack.yaml.lock","pom.xml","build.gradle","build.gradle.kts","settings.gradle","settings.gradle.kts","gradle.properties","package-lock.json","yarn.lock","pnpm-lock.yaml","npm-shrinkwrap.json","requirements.txt","Pipfile","Pipfile.lock","pyproject.toml","setup.py","setup.cfg","Gemfile","Gemfile.lock","uv.lock","CODEOWNERS","DESIGN.md","CONTRIBUTING.md","SECURITY.md","CODE_OF_CONDUCT.md","AGENTS.md","CLAUDE.md","GEMINI.md"],"protected_files_policy":"blocked","title_prefix":"[preset] "},"create_report_incomplete_issue":{},"missing_data":{},"missing_tool":{},"noop":{"max":1,"report-as-issue":"true"},"report_incomplete":{}}
-          GH_AW_SAFE_OUTPUTS_CONFIG_50dbf4670371d6f7_EOF
+          GH_AW_SAFE_OUTPUTS_CONFIG_9e8dea0461236832_EOF
      - name: Generate Safe Outputs Tools
        env:
          GH_AW_TOOLS_META_JSON: |
@@ -722,7 +724,7 @@ jobs:
          mkdir -p /home/runner/.copilot
          GH_AW_NODE=$(which node 2>/dev/null || command -v node 2>/dev/null || echo node)
-          cat << GH_AW_MCP_CONFIG_04e1e53849e8d680_EOF | "$GH_AW_NODE" "${RUNNER_TEMP}/gh-aw/actions/start_mcp_gateway.cjs"
+          cat << GH_AW_MCP_CONFIG_c8953ff00c8ee9ee_EOF | "$GH_AW_NODE" "${RUNNER_TEMP}/gh-aw/actions/start_mcp_gateway.cjs"
          {
            "mcpServers": {
              "github": {
@@ -763,7 +765,7 @@ jobs:
              "payloadDir": "${MCP_GATEWAY_PAYLOAD_DIR}"
            }
          }
-          GH_AW_MCP_CONFIG_04e1e53849e8d680_EOF
+          GH_AW_MCP_CONFIG_c8953ff00c8ee9ee_EOF
      - name: Mount MCP servers as CLIs
        id: mount-mcp-clis
        continue-on-error: true
@@ -1045,7 +1047,7 @@ jobs:
    steps:
      - name: Setup Scripts
        id: setup
-        uses: github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+        uses: github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
        with:
          destination: ${{ runner.temp }}/gh-aw/actions
          job-name: ${{ github.job }}
@@ -1079,7 +1081,7 @@ jobs:
          GH_AW_WORKFLOW_NAME: "Add Community Preset from Issue Submission"
          GH_AW_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          GH_AW_AGENT_CONCLUSION: ${{ needs.agent.result }}
-          GH_AW_NOOP_REPORT_AS_ISSUE: "false"
+          GH_AW_NOOP_REPORT_AS_ISSUE: "true"
        with:
          github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
          script: |
@@ -1186,7 +1188,7 @@ jobs:
    steps:
      - name: Setup Scripts
        id: setup
-        uses: github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+        uses: github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
        with:
          destination: ${{ runner.temp }}/gh-aw/actions
          job-name: ${{ github.job }}
@@ -1382,7 +1384,7 @@ jobs:
    steps:
      - name: Setup Scripts
        id: setup
-        uses: github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+        uses: github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
        with:
          destination: ${{ runner.temp }}/gh-aw/actions
          job-name: ${{ github.job }}
@@ -1454,7 +1456,7 @@ jobs:
    steps:
      - name: Setup Scripts
        id: setup
-        uses: github/gh-aw-actions/setup@b11be78086764c43fa463398aed7ffdcf40549c1 # v0.77.0
+        uses: github/gh-aw-actions/setup@318d7f4901f78b85e25b91709cf0109ac9b425f6 # v0.74.9
        with:
          destination: ${{ runner.temp }}/gh-aw/actions
          job-name: ${{ github.job }}
@@ -1556,7 +1558,7 @@ jobs:
          GH_AW_ALLOWED_DOMAINS: "api.business.githubcopilot.com,api.enterprise.githubcopilot.com,api.github.com,api.githubcopilot.com,api.individual.githubcopilot.com,api.snapcraft.io,archive.ubuntu.com,azure.archive.ubuntu.com,crl.geotrust.com,crl.globalsign.com,crl.identrust.com,crl.sectigo.com,crl.thawte.com,crl.usertrust.com,crl.verisign.com,crl3.digicert.com,crl4.digicert.com,crls.ssl.com,github.com,host.docker.internal,json-schema.org,json.schemastore.org,keyserver.ubuntu.com,ocsp.digicert.com,ocsp.geotrust.com,ocsp.globalsign.com,ocsp.identrust.com,ocsp.sectigo.com,ocsp.ssl.com,ocsp.thawte.com,ocsp.usertrust.com,ocsp.verisign.com,packagecloud.io,packages.cloud.google.com,packages.microsoft.com,ppa.launchpad.net,raw.githubusercontent.com,registry.npmjs.org,s.symcb.com,s.symcd.com,security.ubuntu.com,telemetry.enterprise.githubcopilot.com,ts-crl.ws.symantec.com,ts-ocsp.ws.symantec.com,www.googleapis.com"
          GITHUB_SERVER_URL: ${{ github.server_url }}
          GITHUB_API_URL: ${{ github.api_url }}
-          GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: "{\"add_comment\":{\"max\":2},\"add_labels\":{\"allowed\":[\"preset-submission\",\"validation-passed\",\"validation-failed\",\"needs-info\"],\"max\":3},\"create_pull_request\":{\"draft\":true,\"labels\":[\"preset-submission\",\"automated\"],\"max\":1,\"max_patch_files\":100,\"max_patch_size\":1024,\"protect_top_level_dot_folders\":true,\"protected_files\":[\"package.json\",\"bun.lockb\",\"bunfig.toml\",\"deno.json\",\"deno.jsonc\",\"deno.lock\",\"global.json\",\"NuGet.Config\",\"Directory.Packages.props\",\"mix.exs\",\"mix.lock\",\"go.mod\",\"go.sum\",\"stack.yaml\",\"stack.yaml.lock\",\"pom.xml\",\"build.gradle\",\"build.gradle.kts\",\"settings.gradle\",\"settings.gradle.kts\",\"gradle.properties\",\"package-lock.json\",\"yarn.lock\",\"pnpm-lock.yaml\",\"npm-shrinkwrap.json\",\"requirements.txt\",\"Pipfile\",\"Pipfile.lock\",\"pyproject.toml\",\"setup.py\",\"setup.cfg\",\"Gemfile\",\"Gemfile.lock\",\"uv.lock\",\"CODEOWNERS\",\"DESIGN.md\",\"CONTRIBUTING.md\",\"SECURITY.md\",\"CODE_OF_CONDUCT.md\",\"AGENTS.md\",\"CLAUDE.md\",\"GEMINI.md\"],\"protected_files_policy\":\"blocked\",\"title_prefix\":\"[preset] \"},\"create_report_incomplete_issue\":{},\"missing_data\":{},\"missing_tool\":{},\"noop\":{\"max\":1,\"report-as-issue\":\"false\"},\"report_incomplete\":{}}"
+          GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: "{\"add_comment\":{\"max\":2},\"add_labels\":{\"allowed\":[\"preset-submission\",\"validation-passed\",\"validation-failed\",\"needs-info\"],\"max\":3},\"create_pull_request\":{\"draft\":true,\"labels\":[\"preset-submission\",\"automated\"],\"max\":1,\"max_patch_files\":100,\"max_patch_size\":1024,\"protect_top_level_dot_folders\":true,\"protected_files\":[\"package.json\",\"bun.lockb\",\"bunfig.toml\",\"deno.json\",\"deno.jsonc\",\"deno.lock\",\"global.json\",\"NuGet.Config\",\"Directory.Packages.props\",\"mix.exs\",\"mix.lock\",\"go.mod\",\"go.sum\",\"stack.yaml\",\"stack.yaml.lock\",\"pom.xml\",\"build.gradle\",\"build.gradle.kts\",\"settings.gradle\",\"settings.gradle.kts\",\"gradle.properties\",\"package-lock.json\",\"yarn.lock\",\"pnpm-lock.yaml\",\"npm-shrinkwrap.json\",\"requirements.txt\",\"Pipfile\",\"Pipfile.lock\",\"pyproject.toml\",\"setup.py\",\"setup.cfg\",\"Gemfile\",\"Gemfile.lock\",\"uv.lock\",\"CODEOWNERS\",\"DESIGN.md\",\"CONTRIBUTING.md\",\"SECURITY.md\",\"CODE_OF_CONDUCT.md\",\"AGENTS.md\",\"CLAUDE.md\",\"GEMINI.md\"],\"protected_files_policy\":\"blocked\",\"title_prefix\":\"[preset] \"},\"create_report_incomplete_issue\":{},\"missing_data\":{},\"missing_tool\":{},\"noop\":{\"max\":1,\"report-as-issue\":\"true\"},\"report_incomplete\":{}}"
          GH_AW_CI_TRIGGER_TOKEN: ${{ secrets.GH_AW_CI_TRIGGER_TOKEN }}
        with:
          github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
--- a/.github/workflows/add-community-preset.md
+++ b/.github/workflows/add-community-preset.md
@@ -4,7 +4,7 @@ emoji: "🎨"
 on:
  issues:
-    types: [labeled]
+    types: [opened, edited, labeled]
  skip-bots: [github-actions, copilot, dependabot]
 tools:
@@ -22,8 +22,6 @@ checkout:
  fetch-depth: 0
 safe-outputs:
  noop:
    report-as-issue: false
  create-pull-request:
    title-prefix: "[preset] "
    labels: [preset-submission, automated]
@@ -49,9 +47,14 @@ or update entries in the community preset catalog.
 ## Triggering Conditions
-This workflow only triggers when the `preset-submission` label is added to an
+This workflow triggers on issue events. **Only process the issue if ALL of these
-issue. Before processing, verify that the issue title starts with `[Preset]:`.
+conditions are met:**
-If it does not, stop without commenting.
+
 1. The issue has the `preset-submission` label
 2. The issue title starts with `[Preset]:`
 If the issue does not meet these conditions, add a brief comment explaining that
 this workflow only processes preset submission issues, then stop.
 ## Step 1 — Read and Parse the Issue
--- a/.github/workflows/codeql.yml
+++ b/.github/workflows/codeql.yml
@@ -22,11 +22,11 @@ jobs:
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Initialize CodeQL
-        uses: github/codeql-action/init@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4
+        uses: github/codeql-action/init@9e0d7b8d25671d64c341c19c0152d693099fb5ba # v4
        with:
          languages: ${{ matrix.language }}
      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4
+        uses: github/codeql-action/analyze@9e0d7b8d25671d64c341c19c0152d693099fb5ba # v4
        with:
          category: "/language:${{ matrix.language }}"
--- a/.github/workflows/docs.yml
+++ b/.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@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5.3.0
+        uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5.2.0
        with:
          dotnet-version: '8.x'
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -147,12 +147,12 @@ class CodexIntegration(SkillsIntegration):
 | Field | Location | Purpose |
 |---|---|---|
-| `key` | Class attribute | Unique identifier; for most CLI-based integrations this matches the executable name, but see `cli_executable` below for exceptions |
+| `key` | Class attribute | Unique identifier; for CLI-based integrations (`requires_cli: True`), must match the CLI executable name |
 | `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` 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"`).
+**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"`).
 ### 3. Register it
@@ -177,24 +177,7 @@ 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.
-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`:
+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.
 ```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
@@ -222,37 +205,11 @@ 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.
@@ -424,46 +381,34 @@ Implementation: Extends `YamlIntegration` (parallel to `TomlIntegration`):
 ## Branch Naming Convention
-Branches follow one of two patterns depending on whether an issue exists:
+All branches **must** follow this pattern:
 ```
-<type>/<number>-<short-slug>   # when an issue is created first
+<type>/<number>-<short-slug>
 <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.
+Where `<number>` is either an issue number or a PR number — whichever is created first.
 | 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` |
+| `docs/` | Documentation changes | `docs/2677-branch-naming-convention` |
 | `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
+1. Always include the issue or PR number immediately after the prefix — 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`), `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`.
+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 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.
+2. **Forgetting update scripts**: Both bash and PowerShell thin wrappers and the shared context-update scripts must be updated.
 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.
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,118 +2,6 @@
 <!-- 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
--- a/README.md
+++ b/README.md
@@ -22,7 +22,10 @@
 - [🤔 What is Spec-Driven Development?](#-what-is-spec-driven-development)
 - [⚡ Get Started](#-get-started)
 - [📽️ Video Overview](#️-video-overview)
- [🌍 Community](#-community)
+- [🧩 Community Extensions](#-community-extensions)
 - [🎨 Community Presets](#-community-presets)
 - [🚶 Community Walkthroughs](#-community-walkthroughs)
 - [🛠️ Community Friends](#️-community-friends)
 - [🤖 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)
@@ -59,24 +62,6 @@ specify init my-project --integration copilot
 cd my-project
 ```
 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
 # 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 your desired release tag)
 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`. 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).
 ### 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.
@@ -127,19 +112,31 @@ 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
+## 🧩 Community Extensions
-Explore community-contributed resources on the [Spec Kit docs site](https://github.github.io/spec-kit/):
+Community-contributed extensions add new commands, hooks, and capabilities to Spec Kit. See the full list on the [Community Extensions](https://github.github.io/spec-kit/community/extensions.html) page.
 - [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 contributions are independently created and maintained by their respective authors. Review source code before installation and use at your own discretion.
+> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. Review extension source code before installation and use at your own discretion.
-Want to contribute? See the [Extension Publishing Guide](extensions/EXTENSION-PUBLISHING-GUIDE.md) or the [Presets Publishing Guide](presets/PUBLISHING.md).
+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.
 ## 🤖 Supported AI Coding Agent Integrations
@@ -151,7 +148,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:
@@ -164,7 +161,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:
@@ -209,7 +206,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](https://github.github.io/spec-kit/community/extensions.html) 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](#-community-extensions) above for what's available.
 ### Presets — Customize Existing Workflows
@@ -284,7 +281,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://pipx.pypa.io/) for persistent installation
+- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pypa.github.io/pipx/) for persistent installation
 - [Python 3.11+](https://www.python.org/downloads/)
 - [Git](https://git-scm.com/downloads)
--- a/docs/community/extensions.md
+++ b/docs/community/extensions.md
@@ -27,7 +27,7 @@ The following community-contributed extensions are available in [`catalog.commun
 | 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 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) |
 | 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) |
@@ -56,7 +56,6 @@ The following community-contributed extensions are available in [`catalog.commun
 | 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) |
@@ -71,7 +70,6 @@ The following community-contributed extensions are available in [`catalog.commun
 | 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) |
@@ -79,12 +77,11 @@ The following community-contributed extensions are available in [`catalog.commun
 | 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 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) |
 | 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) |
@@ -114,8 +111,8 @@ The following community-contributed extensions are available in [`catalog.commun
 | 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) |
 | 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) |
--- a/docs/community/presets.md
+++ b/docs/community/presets.md
@@ -8,7 +8,7 @@ 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 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) |
+| Agent Parity Governance | Keeps shared AI-agent instructions aligned across project-defined agent guidance surfaces and documents intentional deviations | 6 templates, 3 commands | — | [spec-kit-preset-agent-parity-governance](https://github.com/hindermath/spec-kit-preset-agent-parity-governance) |
 | AIDE In-Place Migration | Adapts the AIDE extension workflow for in-place technology migrations (X → Y pattern) — adds migration objectives, verification gates, knowledge documents, and behavioral equivalence criteria | 2 templates, 8 commands | AIDE extension | [spec-kit-presets](https://github.com/mnriem/spec-kit-presets) |
 | Architecture Governance | Adds secure architecture governance: trust boundaries, threat modeling, STRIDE/CAPEC, S-ADRs, Zero Trust applicability, and OWASP SAMM | 11 templates, 3 commands | — | [spec-kit-preset-architecture-governance](https://github.com/hindermath/spec-kit-preset-architecture-governance) |
 | Canon Core | Adapts original Spec Kit workflow to work together with Canon extension | 2 templates, 8 commands | — | [spec-kit-canon](https://github.com/maximiliamus/spec-kit-canon) |
@@ -23,10 +23,9 @@ The following community-contributed presets customize how Spec Kit behaves — o
 | 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, 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) |
+| Security Governance | Adds secure development governance: memory-safe-language preference, secure code generation, 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).
--- a/docs/index.md
+++ b/docs/index.md
@@ -43,7 +43,7 @@ Run `specify init` with your agent of choice and Spec Kit sets up the right comm
 ### Make it your own
-<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.
+<span class="pillar-stat">91 community extensions</span> (50+ authors), <span class="pillar-stat">18 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.
 Including entirely different SDD processes:
@@ -82,7 +82,7 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a
 <div class="stats-grid">
  <div class="stat-item">
-    <span class="stat-number">106K+</span>
+    <span class="stat-number">96K+</span>
    <span class="stat-label">GitHub stars</span>
  </div>
  <div class="stat-item">
@@ -94,11 +94,11 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a
    <span class="stat-label">Integrations</span>
  </div>
  <div class="stat-item">
-    <span class="stat-number">105</span>
+    <span class="stat-number">91</span>
    <span class="stat-label">Extensions</span>
  </div>
  <div class="stat-item">
-    <span class="stat-number">22</span>
+    <span class="stat-number">18</span>
    <span class="stat-label">Presets</span>
  </div>
  <div class="stat-item">
@@ -150,5 +150,3 @@ 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>
--- a/docs/install/pipx.md
+++ b/docs/install/pipx.md
@@ -1,6 +1,6 @@
 # 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/).
+[pipx](https://pypa.github.io/pipx/) is a tool for installing Python CLI applications in isolated environments. It does not require [uv](https://docs.astral.sh/uv/).
 ## Install Specify CLI
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -4,7 +4,7 @@
 - **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://pipx.pypa.io/) for persistent installation
+- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pypa.github.io/pipx/) for persistent installation
 - [Python 3.11+](https://www.python.org/downloads/)
 - [Git](https://git-scm.com/downloads)
@@ -88,8 +88,6 @@ 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
--- a/docs/reference/integrations.md
+++ b/docs/reference/integrations.md
@@ -10,7 +10,6 @@ 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`   |                                                                                                                                           |
@@ -19,7 +18,6 @@ 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`          |                                                                                                                                           |
@@ -33,7 +31,6 @@ 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                                                                               |
--- a/docs/reference/workflows.md
+++ b/docs/reference/workflows.md
@@ -11,7 +11,6 @@ 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.
@@ -21,25 +20,7 @@ Example:
 specify workflow run speckit -i spec="Build a kanban board with drag-and-drop task management" -i scope=full
 ```
-With `--json`, a single machine-readable object is printed instead of formatted text (the default output is unchanged when the flag is omitted):
+> **Note:** All workflow commands require a project already initialized with `specify init`.
 ```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
@@ -47,29 +28,14 @@ specify workflow run my-pipeline.yml --json
 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
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -8,10 +8,8 @@
 | What to Upgrade | Command | When to Use |
 |----------------|---------|-------------|
-| **CLI Tool (recommended)** | `specify self upgrade` | Latest stable release, in place. Auto-detects whether you installed via `uv tool` or `pipx`. |
+| **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 — 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 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 — 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 |
@@ -21,32 +19,12 @@
 The CLI tool (`specify`) is separate from your project files. Upgrade it to get the latest features and bug fixes.
-### Recommended: `specify self upgrade`
+Before upgrading, you can check whether a newer released version is available:
 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):
@@ -76,14 +54,10 @@ 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
 ```
-`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.
+This shows installed tools and confirms the CLI is working. Use `specify version` to confirm which persistent CLI version is currently on your `PATH`.
 ---
@@ -212,8 +186,8 @@ Restart your IDE to refresh the command list.
 ### Scenario 1: "I just want new slash commands"
 ```bash
-# Upgrade CLI (auto-detects uv tool vs pipx install)
+# Upgrade CLI (if using persistent install)
-specify self upgrade
+uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
 # Update project files to get new commands
 specify init --here --force --integration copilot
@@ -230,7 +204,7 @@ cp .specify/memory/constitution.md /tmp/constitution-backup.md
 cp -r .specify/templates /tmp/templates-backup
 # 2. Upgrade CLI
-specify self upgrade
+uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
 # 3. Update project
 specify init --here --force --integration copilot
@@ -414,19 +388,15 @@ Only Spec Kit infrastructure files:
 ### "CLI upgrade doesn't seem to work"
-If a command behaves like an older Spec Kit version, first ask the CLI itself:
+If a command behaves like an older Spec Kit version, first check for local CLI drift:
 ```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:
+Verify the installation:
 ```bash
 # Check installed tools
--- a/extensions/README.md
+++ b/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](https://github.github.io/spec-kit/community/extensions.html) page for the full list of available community-contributed extensions.
+See the [Community Extensions](../README.md#-community-extensions) section in the main README for the full list of available community-contributed extensions.
 For the raw catalog data, see [`catalog.community.json`](catalog.community.json).
--- a/extensions/agent-context/README.md
+++ b/extensions/agent-context/README.md
@@ -1,57 +0,0 @@
 # 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()`).
--- a/extensions/agent-context/agent-context-config.yml
+++ b/extensions/agent-context/agent-context-config.yml
@@ -1,15 +0,0 @@
 # 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 -->"
--- a/extensions/agent-context/commands/speckit.agent-context.update.md
+++ b/extensions/agent-context/commands/speckit.agent-context.update.md
@@ -1,26 +0,0 @@
 ---
 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`.
--- a/extensions/agent-context/extension.yml
+++ b/extensions/agent-context/extension.yml
@@ -1,34 +0,0 @@
 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"
--- a/extensions/agent-context/scripts/bash/update-agent-context.sh
+++ b/extensions/agent-context/scripts/bash/update-agent-context.sh
@@ -1,200 +0,0 @@
 #!/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"
--- a/extensions/agent-context/scripts/powershell/update-agent-context.ps1
+++ b/extensions/agent-context/scripts/powershell/update-agent-context.ps1
@@ -1,237 +0,0 @@
 #!/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"
--- a/extensions/catalog.community.json
+++ b/extensions/catalog.community.json
@@ -1,6 +1,6 @@
 {
  "schema_version": "1.0",
-  "updated_at": "2026-06-04T00:00:00Z",
+  "updated_at": "2026-05-26T00:00:00Z",
  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
  "extensions": {
    "aide": {
@@ -240,10 +240,10 @@
    "architecture-guard": {
      "name": "Architecture Guard",
      "id": "architecture-guard",
-      "description": "Framework-agnostic architecture review extension for validating implementation against governance and architecture constitutions, detecting architectural drift, and generating non-blocking refactor tasks.",
+      "description": "Continuous architecture governance for AI-assisted development. Reviews specs, plans, and code for architecture drift, producing structured refactor tasks and evolution proposals.",
      "author": "DyanGalih",
-      "version": "1.8.9",
+      "version": "1.8.4",
-      "download_url": "https://github.com/DyanGalih/spec-kit-architecture-guard/archive/refs/tags/v1.8.9.zip",
+      "download_url": "https://github.com/DyanGalih/spec-kit-architecture-guard/archive/refs/tags/v1.8.4.zip",
      "repository": "https://github.com/DyanGalih/spec-kit-architecture-guard",
      "homepage": "https://github.com/DyanGalih/spec-kit-architecture-guard",
      "documentation": "https://github.com/DyanGalih/spec-kit-architecture-guard/blob/main/README.md",
@@ -258,18 +258,17 @@
      },
      "tags": [
        "architecture",
        "spec-kit",
        "review",
        "refactor",
        "workflow",
        "governance",
-        "guardrails"
+        "drift-detection",
        "refactor",
        "monolithic",
        "microservices"
      ],
      "verified": false,
      "downloads": 0,
      "stars": 0,
      "created_at": "2026-05-05T07:26:00Z",
-      "updated_at": "2026-05-27T00:00:00Z"
+      "updated_at": "2026-05-11T14:58:00Z"
    },
    "archive": {
      "name": "Archive Extension",
@@ -1246,39 +1245,6 @@
      "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",
@@ -1757,37 +1723,6 @@
      "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",
@@ -2014,12 +1949,12 @@
      "name": "Product Spec Extension",
      "id": "product",
      "description": "Generates PRFAQ, Lean PRD, stakeholder summaries, and technical designs from engineering specs.",
-      "author": "d0whc3r",
+      "author": "spec-kit-product contributors",
-      "version": "0.8.3",
+      "version": "0.1.3",
-      "download_url": "https://github.com/d0whc3r/spec-kit-product/releases/download/v0.8.3/product-0.8.3.zip",
+      "download_url": "https://github.com/d0whc3r/spec-kit-product/releases/download/v0.1.3/product-0.1.3.zip",
      "repository": "https://github.com/d0whc3r/spec-kit-product",
-      "homepage": "https://d0whc3r.github.io/spec-kit-product/",
+      "homepage": "https://github.com/d0whc3r/spec-kit-product",
-      "documentation": "https://github.com/d0whc3r/spec-kit-product/wiki",
+      "documentation": "https://github.com/d0whc3r/spec-kit-product/blob/main/README.md",
      "changelog": "https://github.com/d0whc3r/spec-kit-product/blob/main/CHANGELOG.md",
      "license": "MIT",
      "requires": {
@@ -2027,38 +1962,28 @@
      },
      "provides": {
        "commands": 4,
-        "hooks": 3
+        "hooks": 6
      },
      "tags": [
        "design",
        "documentation",
        "jtbd",
        "lean-prd",
        "planning",
        "prd",
        "prfaq",
        "product",
        "product-management",
        "requirements",
        "spec",
-        "spec-kit",
+        "prd",
-        "spec-kit-extension",
+        "design",
-        "stakeholder",
+        "documentation"
        "technical-design"
      ],
      "verified": false,
      "downloads": 0,
      "stars": 0,
      "created_at": "2026-05-26T00:00:00Z",
-      "updated_at": "2026-06-01T00:00:00Z"
+      "updated_at": "2026-05-26T00:00:00Z"
    },
    "product-forge": {
      "name": "Product Forge",
      "id": "product-forge",
-      "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",
+      "description": "Full product lifecycle from research to release — portfolio, lite mode, monorepo, optional V-Model",
      "author": "VaiYav",
-      "version": "1.6.0",
+      "version": "1.5.1",
-      "download_url": "https://github.com/VaiYav/speckit-product-forge/archive/refs/tags/v1.6.0.zip",
+      "download_url": "https://github.com/VaiYav/speckit-product-forge/archive/refs/tags/v1.5.1.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",
@@ -2068,7 +1993,7 @@
        "speckit_version": ">=0.1.0"
      },
      "provides": {
-        "commands": 31,
+        "commands": 29,
        "hooks": 0
      },
      "tags": [
@@ -2082,7 +2007,7 @@
      "downloads": 0,
      "stars": 0,
      "created_at": "2026-03-28T00:00:00Z",
-      "updated_at": "2026-06-02T00:00:00Z"
+      "updated_at": "2026-04-24T15:52:00Z"
    },
    "qa": {
      "name": "QA Testing Extension",
@@ -2114,38 +2039,6 @@
      "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",
@@ -2324,8 +2217,8 @@
      "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",
+      "version": "1.0.0",
-      "download_url": "https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd/archive/refs/tags/v1.1.0.zip",
+      "download_url": "https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd/archive/refs/tags/v1.0.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",
@@ -2355,7 +2248,7 @@
      "downloads": 0,
      "stars": 0,
      "created_at": "2026-05-13T00:00:00Z",
-      "updated_at": "2026-05-30T00:00:00Z"
+      "updated_at": "2026-05-13T00:00:00Z"
    },
    "retro": {
      "name": "Retro Extension",
@@ -2756,8 +2649,8 @@
      "id": "speckit-superpowers-bridge",
      "description": "Thin orchestrator between Spec Kit (design) and Superpowers (implementation). Cross-agent.",
      "author": "lihan3238",
-      "version": "1.0.2",
+      "version": "0.5.0",
-      "download_url": "https://github.com/lihan3238/speckit-superpowers-bridge/releases/download/v1.0.2/speckit-superpowers-bridge-v1.0.2.zip",
+      "download_url": "https://github.com/lihan3238/speckit-superpowers-bridge/releases/download/v0.5.0/speckit-superpowers-bridge-v0.5.0.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",
@@ -2798,7 +2691,7 @@
      "downloads": 0,
      "stars": 0,
      "created_at": "2026-05-15T00:00:00Z",
-      "updated_at": "2026-06-04T00:00:00Z"
+      "updated_at": "2026-05-20T00:00:00Z"
    },
    "speckit-utils": {
      "name": "SDD Utilities",
@@ -3039,13 +2932,13 @@
      "created_at": "2026-03-30T00:00:00Z",
      "updated_at": "2026-05-24T01:07:34Z"
    },
-    "superspec": {
+    "superpowers-bridge": {
-      "name": "Superspec",
+      "name": "Superpowers Bridge",
-      "id": "superspec",
+      "id": "superpowers-bridge",
      "description": "Bridges spec-kit workflows with obra/superpowers capabilities for brainstorming, TDD, code review, and resumable execution.",
      "author": "WangX0111",
-      "version": "1.0.1",
+      "version": "1.0.0",
-      "download_url": "https://github.com/WangX0111/superspec/archive/refs/tags/v1.0.1.zip",
+      "download_url": "https://github.com/WangX0111/superspec/archive/refs/tags/v1.0.0.zip",
      "repository": "https://github.com/WangX0111/superspec",
      "homepage": "https://github.com/WangX0111/superspec",
      "documentation": "https://github.com/WangX0111/superspec/blob/main/README.md",
@@ -3070,7 +2963,7 @@
      "downloads": 0,
      "stars": 0,
      "created_at": "2026-04-22T00:00:00Z",
-      "updated_at": "2026-05-30T00:00:00Z"
+      "updated_at": "2026-04-22T00:00:00Z"
    },
    "sync": {
      "name": "Spec Sync",
--- a/extensions/catalog.json
+++ b/extensions/catalog.json
@@ -3,20 +3,6 @@
  "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",
--- a/integrations/catalog.json
+++ b/integrations/catalog.json
@@ -1,6 +1,6 @@
 {
  "schema_version": "1.0",
-  "updated_at": "2026-06-02T00:00:00Z",
+  "updated_at": "2026-04-29T00:00:00Z",
  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/integrations/catalog.json",
  "integrations": {
    "claude": {
@@ -12,15 +12,6 @@
      "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",
@@ -174,15 +165,6 @@
      "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",
@@ -290,15 +272,6 @@
      "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"]
    }
  }
 }
--- a/newsletters/2026-May.md
+++ b/newsletters/2026-May.md
@@ -1,138 +0,0 @@
 # 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)
--- a/presets/catalog.community.json
+++ b/presets/catalog.community.json
@@ -1,6 +1,6 @@
 {
  "schema_version": "1.0",
-  "updated_at": "2026-06-03T00:00:00Z",
+  "updated_at": "2026-05-26T00: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.2.0",
+      "version": "0.1.0",
-      "description": "Keeps shared AI-agent guidance aligned and adds agent-neutral Spec Kit model-routing guidance across declared agent instruction surfaces.",
+      "description": "Keeps shared AI-agent guidance aligned across a project-defined set of agent instruction surfaces.",
      "author": "Thorsten Hindermann",
      "repository": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance",
-      "download_url": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance/archive/refs/tags/v0.2.0.zip",
+      "download_url": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance/archive/refs/tags/v0.1.0.zip",
      "homepage": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance",
      "documentation": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance/blob/main/README.md",
      "license": "MIT",
@@ -46,20 +46,18 @@
        "speckit_version": ">=0.8.0"
      },
      "provides": {
-        "templates": 9,
+        "templates": 6,
        "commands": 3
      },
      "tags": [
        "agents",
        "governance",
        "parity",
        "agent-md",
        "agent-guidance",
        "model-routing",
        "multi-agent"
      ],
      "created_at": "2026-04-27T00:00:00Z",
-      "updated_at": "2026-05-31T00:00:00Z"
+      "updated_at": "2026-04-27T00:00:00Z"
    },
    "aide-in-place": {
      "name": "AIDE In-Place Migration",
@@ -474,11 +472,11 @@
    "security-governance": {
      "name": "Security Governance",
      "id": "security-governance",
-      "version": "0.4.0",
+      "version": "0.3.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.",
+      "description": "Adds memory-safe-language preference, secure code generation, 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.4.0.zip",
+      "download_url": "https://github.com/hindermath/spec-kit-preset-security-governance/archive/refs/tags/v0.3.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",
@@ -501,20 +499,12 @@
        "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-05-26T00:00:00Z"
+      "updated_at": "2026-05-22T00:00:00Z"
    },
    "spec2cloud": {
      "name": "Spec2Cloud",
@@ -591,34 +581,6 @@
        "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"
    }
  }
 }
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.9.5.dev0"
+version = "0.8.15"
 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,7 +40,6 @@ 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>`)
--- a/scripts/bash/check-prerequisites.sh
+++ b/scripts/bash/check-prerequisites.sh
@@ -78,12 +78,13 @@ done
 SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/common.sh"
-# Get feature paths
+# Get feature paths and validate branch
 _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 (no validation)
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
 if $PATHS_ONLY; then
    if $JSON_MODE; then
        # Minimal JSON paths payload (no validation performed)
@@ -111,26 +112,23 @@ 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 $(format_speckit_command specify "$REPO_ROOT") first to create the feature structure." >&2
+    echo "Run /speckit.specify 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 $(format_speckit_command plan "$REPO_ROOT") first to create the implementation plan." >&2
+    echo "Run /speckit.plan 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 $(format_speckit_command tasks "$REPO_ROOT") first to create the task list." >&2
+    echo "Run /speckit.tasks first to create the task list." >&2
    exit 1
 fi
--- a/scripts/bash/common.sh
+++ b/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_COMMAND_PLAN__ can skip git branch pattern checks).
+# and matches the resolved active FEATURE_DIR (so /speckit.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_COMMAND_SPECIFY__)
+    #   2. .specify/feature.json "feature_directory" key (persisted by /speckit.specify)
    #   3. Branch-name-based prefix lookup (legacy fallback)
    local feature_dir
    if [[ -n "${SPECIFY_FEATURE_DIRECTORY:-}" ]]; then
@@ -307,83 +307,6 @@ 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() {
@@ -719,3 +642,4 @@ except Exception:
    printf '%s' "$content"
    return 0
 }
--- a/scripts/bash/setup-plan.sh
+++ b/scripts/bash/setup-plan.sh
@@ -40,31 +40,15 @@ fi
 # Ensure the feature directory exists
 mkdir -p "$FEATURE_DIR"
-# Copy plan template if plan doesn't already exist
+# Copy plan template if it exists
-if [[ -f "$IMPL_PLAN" ]]; then
+TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT") || true
-    if $JSON_MODE; then
+if [[ -n "$TEMPLATE" ]] && [[ -f "$TEMPLATE" ]]; then
-        echo "Plan already exists at $IMPL_PLAN, skipping template copy" >&2
+    cp "$TEMPLATE" "$IMPL_PLAN"
-    else
+    echo "Copied plan template to $IMPL_PLAN"
        echo "Plan already exists at $IMPL_PLAN, skipping template copy"
    fi
 else
-    TEMPLATE=$(resolve_template "plan-template" "$REPO_ROOT") || true
+    echo "Warning: Plan template not found"
-    if [[ -n "$TEMPLATE" ]] && [[ -f "$TEMPLATE" ]]; then
+    # Create a basic plan file if template doesn't exist
-        cp "$TEMPLATE" "$IMPL_PLAN"
+    touch "$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
--- a/scripts/bash/setup-tasks.sh
+++ b/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 $(format_speckit_command plan "$REPO_ROOT") first to create the implementation plan." >&2
+    echo "Run /speckit.plan first to create the implementation plan." >&2
    exit 1
 fi
 if [[ ! -f "$FEATURE_SPEC" ]]; then
    echo "ERROR: spec.md not found in $FEATURE_DIR" >&2
-    echo "Run $(format_speckit_command specify "$REPO_ROOT") first to create the feature structure." >&2
+    echo "Run /speckit.specify first to create the feature structure." >&2
    exit 1
 fi
--- a/scripts/powershell/check-prerequisites.ps1
+++ b/scripts/powershell/check-prerequisites.ps1
@@ -56,10 +56,14 @@ EXAMPLES:
 # Source common functions
 . "$PSScriptRoot/common.ps1"
-# Get feature paths
+# Get feature paths and validate branch
 $paths = Get-FeaturePathsEnv
-# If paths-only mode, output paths and exit (no validation)
+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 ($PathsOnly) {
    if ($Json) {
        [PSCustomObject]@{
@@ -81,31 +85,23 @@ 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)"
-    $specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
+    Write-Output "Run /speckit.specify first to create the feature structure."
    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)"
-    $planCommand = Format-SpecKitCommand -CommandName 'plan' -RepoRoot $paths.REPO_ROOT
+    Write-Output "Run /speckit.plan first to create the implementation plan."
    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)"
-    $tasksCommand = Format-SpecKitCommand -CommandName 'tasks' -RepoRoot $paths.REPO_ROOT
+    Write-Output "Run /speckit.tasks first to create the task list."
    Write-Output "Run $tasksCommand first to create the task list."
    exit 1
 }
--- a/scripts/powershell/common.ps1
+++ b/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_COMMAND_PLAN__ can skip git branch pattern checks).
+# active FEATURE_DIR from Get-FeaturePathsEnv (so /speckit.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_COMMAND_SPECIFY__)
+    #   2. .specify/feature.json "feature_directory" key (persisted by /speckit.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) {
@@ -355,58 +355,6 @@ function Test-DirHasFiles {
    }
 }
 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 {
--- a/scripts/powershell/setup-plan.ps1
+++ b/scripts/powershell/setup-plan.ps1
@@ -33,25 +33,17 @@ 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 plan doesn't already exist
+# Copy plan template if it exists, otherwise note it or create empty file
-if (Test-Path $paths.IMPL_PLAN -PathType Leaf) {
+$template = Resolve-Template -TemplateName 'plan-template' -RepoRoot $paths.REPO_ROOT
-    if ($Json) {
+if ($template -and (Test-Path $template)) { 
-        [Console]::Error.WriteLine("Plan already exists at $($paths.IMPL_PLAN), skipping template copy")
+    # Read the template content and write it to the implementation plan file with UTF-8 encoding without BOM
-    } else {
+    $content = [System.IO.File]::ReadAllText($template)
-        Write-Output "Plan already exists at $($paths.IMPL_PLAN), skipping template copy"
+    $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
-    }
+    [System.IO.File]::WriteAllText($paths.IMPL_PLAN, $content, $utf8NoBom)
 } else {
-    $template = Resolve-Template -TemplateName 'plan-template' -RepoRoot $paths.REPO_ROOT
+    Write-Warning "Plan template not found"
-    if ($template -and (Test-Path $template)) {
+    # Create a basic plan file if template doesn't exist
-        # Read the template content and write it to the implementation plan file with UTF-8 encoding without BOM
+    New-Item -ItemType File -Path $paths.IMPL_PLAN -Force | Out-Null
        $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
--- a/scripts/powershell/setup-tasks.ps1
+++ b/scripts/powershell/setup-tasks.ps1
@@ -28,15 +28,13 @@ 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)")
-    $planCommand = Format-SpecKitCommand -CommandName 'plan' -RepoRoot $paths.REPO_ROOT
+    [Console]::Error.WriteLine("Run /speckit.plan first to create the implementation plan.")
    [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)")
-    $specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
+    [Console]::Error.WriteLine("Run /speckit.specify first to create the feature structure.")
    [Console]::Error.WriteLine("Run $specifyCommand first to create the feature structure.")
    exit 1
 }
--- a/src/specify_cli/init.py
+++ b/src/specify_cli/init.py
--- a/src/specify_cli/_init_options.py
+++ b/src/specify_cli/_init_options.py
@@ -1,36 +0,0 @@
 """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
--- a/src/specify_cli/_utils.py
+++ b/src/specify_cli/_utils.py
@@ -38,44 +38,32 @@ def run_command(cmd: list[str], check_return: bool = True, capture: bool = False
 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)
+        tool: Name of the tool to check
        tracker: StepTracker | None to update with results
    Returns:
        True if tool is found, False otherwise
    """
-    found: bool
+    # Special handling for Claude CLI local installs
-
+    # See: https://github.com/github/spec-kit/issues/123
-    # Delegate to the integration's is_cli_available() when the tool
+    # See: https://github.com/github/spec-kit/issues/550
-    # key matches a registered integration.  This removes the need for
+    # Claude Code can be installed in two local paths:
-    # hard-coded special cases here (e.g. Claude local paths, kiro dual
+    #   1. ~/.claude/local/claude          (after `claude migrate-installer`)
-    # binaries, rovodev/acli mismatch).  See issue #2597.
+    #   2. ~/.claude/local/node_modules/.bin/claude  (npm-local install, e.g. via nvm)
-    try:
+    # Neither path may be on the system PATH, so we check them explicitly.
-        from specify_cli.integrations import get_integration
+    if tool == "claude":
-
+        if CLAUDE_LOCAL_PATH.is_file() or CLAUDE_NPM_LOCAL_PATH.is_file():
        impl = get_integration(tool)
        if impl is not None:
            found = impl.is_cli_available()
            if tracker:
-                if found:
+                tracker.complete(tool, "available")
-                    tracker.complete(tool, "available")
+            return True
                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").
+    if tool == "kiro-cli":
-    found = shutil.which(tool) is not None
+        # Kiro currently supports both executable names. Prefer kiro-cli and
        # accept kiro as a compatibility fallback.
        found = shutil.which("kiro-cli") is not None or shutil.which("kiro") is not None
    else:
        found = shutil.which(tool) is not None
    if tracker:
        if found:
--- a/src/specify_cli/_version.py
+++ b/src/specify_cli/_version.py
--- a/src/specify_cli/agents.py
+++ b/src/specify_cli/agents.py
@@ -15,8 +15,6 @@ 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."""
@@ -69,33 +67,6 @@ 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.
@@ -361,6 +332,11 @@ 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 = {}
@@ -398,15 +374,8 @@ class CommandRegistrar:
        body = body.replace("{ARGS}", "$ARGUMENTS").replace("__AGENT__", agent_name)
-        # Resolve __CONTEXT_FILE__ from the agent-context extension config.
+        # Resolve __CONTEXT_FILE__ from init-options
-        # Fall back to init-options.json for projects that haven't migrated.
+        context_file = init_opts.get("context_file") or ""
        # 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)
@@ -432,9 +401,6 @@ 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
@@ -464,36 +430,6 @@ 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,
@@ -503,7 +439,6 @@ class CommandRegistrar:
        project_root: Path,
        context_note: str = None,
        _resolved_dir: Path = None,
        link_outputs: bool = False,
    ) -> List[str]:
        """Register commands for a specific agent.
@@ -518,9 +453,6 @@ class CommandRegistrar:
                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
@@ -539,11 +471,9 @@ class CommandRegistrar:
        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
@@ -575,10 +505,6 @@ 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"]
            )
@@ -633,22 +559,14 @@ 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)
-            self._write_registered_output(
+            dest_file.write_text(output, encoding="utf-8")
                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 aliases:
+            for alias in cmd_info.get("aliases", []):
                alias_output_name = self._compute_output_name(
                    agent_name, alias, agent_config
                )
@@ -707,56 +625,13 @@ class CommandRegistrar:
                )
                self._ensure_inside(alias_file, commands_dir)
                alias_file.parent.mkdir(parents=True, exist_ok=True)
-                self._write_registered_output(
+                alias_file.write_text(alias_output, encoding="utf-8")
                    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.
@@ -779,28 +654,15 @@ class CommandRegistrar:
    ) -> Path:
        """Return the agent command directory, falling back to legacy_dir.
-        Supports project-relative paths (e.g. ``.claude/skills/``),
+        When the canonical directory (``agent_config["dir"]``) does not
-        home-relative paths (e.g. ``~/.hermes/skills``), and absolute
+        exist but a ``legacy_dir`` is configured and present on disk,
-        paths — the ``agent_config["dir"]`` value is resolved verbatim
+        returns the legacy path and emits a deprecation warning advising
-        when absolute or starting with ``~/``, or joined with
+        the user to upgrade.
        ``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"]
+        agent_dir = project_root / 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:
@@ -825,8 +687,6 @@ 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.
@@ -836,13 +696,6 @@ 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
@@ -850,73 +703,12 @@ 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():
            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
                        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()
+            if agent_dir.exists():
            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,
@@ -926,20 +718,11 @@ class CommandRegistrar:
                        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
@@ -950,7 +733,6 @@ 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.
@@ -964,8 +746,6 @@ 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
@@ -975,15 +755,10 @@ class CommandRegistrar:
        for agent_name, agent_config in self.AGENT_CONFIGS.items():
            if agent_config.get("extension") == "/SKILL.md":
                continue
            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():
+            if agent_dir.exists():
                try:
                    registered = self.register_commands(
                        agent_name,
@@ -993,7 +768,6 @@ class CommandRegistrar:
                        project_root,
                        context_note=context_note,
                        _resolved_dir=agent_dir,
                        link_outputs=link_outputs,
                    )
                    if registered:
                        results[agent_name] = registered
@@ -1038,32 +812,22 @@ class CommandRegistrar:
                output_name = self._compute_output_name(
                    agent_name, cmd_name, agent_config
                )
                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 = (
-                        cmd_file = (
+                        target_dir / f"{output_name}{agent_config['extension']}"
-                            target_dir / f"{name}{agent_config['extension']}"
+                    )
-                        )
+                    if cmd_file.exists():
-                        try:
+                        cmd_file.unlink()
-                            self._ensure_inside(cmd_file, target_dir)
+                        # For SKILL.md agents each command lives in its own
-                        except ValueError:
+                        # subdirectory (e.g. .agents/skills/speckit-ext-cmd/
-                            continue
+                        # SKILL.md).  Remove the parent dir when it becomes
-                        if cmd_file.exists() or cmd_file.is_symlink():
+                        # empty to avoid orphaned directories.
-                            cmd_file.unlink()
+                        parent = cmd_file.parent
-                            # For SKILL.md agents each command lives in its own
+                        if parent != target_dir and parent.exists():
-                            # subdirectory (e.g. .agents/skills/speckit-ext-cmd/
+                            try:
-                            # SKILL.md).  Remove the parent dir when it becomes
+                                parent.rmdir()
-                            # empty to avoid orphaned directories.
+                            except OSError:
-                            parent = cmd_file.parent
+                                pass
                            if parent != target_dir and parent.exists():
                                try:
                                    parent.rmdir()
                                except OSError:
                                    pass
                if agent_name == "copilot":
                    prompt_file = (
--- a/src/specify_cli/commands/extension.py
+++ b/src/specify_cli/commands/extension.py
@@ -0,0 +1,2 @@
 """specify extension * commands — placeholder for future extraction."""
 from __future__ import annotations
--- a/src/specify_cli/commands/init.py
+++ b/src/specify_cli/commands/init.py
@@ -151,15 +151,12 @@ def register(app: typer.Typer) -> None:
        # Lazy imports to avoid circular dependency — __init__.py imports this module
        from .. import (
            _install_shared_infra_or_exit,
            _parse_integration_options,
            _print_cli_warning,
-            _update_agent_context_config_file,
+            _write_integration_json,
            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()
@@ -397,7 +394,6 @@ def register(app: typer.Typer) -> None:
            ("constitution", "Constitution setup"),
            ("git", "Install git extension"),
            ("workflow", "Install bundled workflow"),
            ("agent-context", "Install agent-context extension"),
            ("final", "Finalize"),
        ]:
            tracker.add(key, label)
@@ -539,10 +535,13 @@ def register(app: typer.Typer) -> None:
                    sanitized_wf = str(wf_err).replace('\n', ' ').strip()
                    tracker.error("workflow", f"install failed: {sanitized_wf[:120]}")
                ensure_executable_scripts(project_path, tracker=tracker)
                init_opts = {
                    "ai": selected_ai,
                    "integration": resolved_integration.key,
                    "branch_numbering": branch_numbering or "sequential",
                    "context_file": resolved_integration.context_file,
                    "here": here,
                    "script": selected_script,
                    "speckit_version": get_speckit_version(),
@@ -552,47 +551,6 @@ def register(app: typer.Typer) -> None:
                    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
@@ -728,7 +686,6 @@ def register(app: typer.Typer) -> None:
        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:
@@ -752,7 +709,7 @@ def register(app: typer.Typer) -> None:
                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:
+            if cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode:
                return f"/speckit-{name}"
            return f"/speckit.{name}"
--- a/src/specify_cli/commands/integration.py
+++ b/src/specify_cli/commands/integration.py
@@ -0,0 +1,2 @@
 """specify integration * commands — placeholder for future extraction."""
 from __future__ import annotations
--- a/src/specify_cli/commands/preset.py
+++ b/src/specify_cli/commands/preset.py
@@ -0,0 +1,2 @@
 """specify preset * commands — placeholder for future extraction."""
 from __future__ import annotations
--- a/src/specify_cli/commands/workflow.py
+++ b/src/specify_cli/commands/workflow.py
@@ -0,0 +1,2 @@
 """specify workflow * commands — placeholder for future extraction."""
 from __future__ import annotations
--- a/src/specify_cli/extensions.py
+++ b/src/specify_cli/extensions.py
@@ -26,15 +26,14 @@ 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",
@@ -762,28 +761,7 @@ class ExtensionManager:
        if not ignore_file.exists():
            return None
-        # Pin UTF-8 explicitly: ``Path.read_text`` defaults to the system
+        lines: List[str] = ignore_file.read_text().splitlines()
        # 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] = []
@@ -831,59 +809,20 @@ class ExtensionManager:
        be created due to symlink, containment, or permission issues so
        that callers can fall back gracefully.
        """
-        from . import (
+        from . import resolve_active_skills_dir, _print_cli_warning
            _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)
+            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
        if skills_dir is None:
            return None
        opts = load_init_options(self.project_root)
        if not isinstance(opts, dict):
            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)
        from .agents import CommandRegistrar
        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.
@@ -895,8 +834,6 @@ 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).
@@ -949,18 +886,9 @@ class ExtensionManager:
            # Check if skill already exists before creating the directory
            skill_subdir = skills_dir / skill_name
            skill_file = skill_subdir / "SKILL.md"
-            cache_root = extension_dir / ".specify-dev" / "extension-skills"
+            if skill_file.exists():
-            cache_file = cache_root / skill_name / "SKILL.md"
+                # Do not overwrite user-customized skills
-            CommandRegistrar._ensure_inside(cache_file, cache_root)
+                continue
            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.
@@ -1012,35 +940,11 @@ class ExtensionManager:
                    skill_content
                )
-            if link_outputs:
+            skill_file.write_text(skill_content, encoding="utf-8")
                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],
@@ -1211,8 +1115,6 @@ 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.
@@ -1221,10 +1123,6 @@ 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
@@ -1246,34 +1144,14 @@ class ExtensionManager:
        # Check if already installed
        if self.registry.is_installed(manifest.id):
-            if not force:
+            raise ExtensionError(
-                raise ExtensionError(
+                f"Extension '{manifest.id}' is already installed. "
-                    f"Extension '{manifest.id}' is already installed. "
+                f"Use 'specify extension remove {manifest.id}' first."
-                    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():
@@ -1288,43 +1166,17 @@ class ExtensionManager:
            registrar = CommandRegistrar()
            # Register for all detected agents
            registered_commands = registrar.register_commands_for_all_agents(
-                manifest,
+                manifest, dest_dir, self.project_root
                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(
+        registered_skills = self._register_extension_skills(manifest, dest_dir)
            manifest, dest_dir, link_outputs=link_commands
        )
        # 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,
@@ -1343,7 +1195,6 @@ class ExtensionManager:
        zip_path: Path,
        speckit_version: str,
        priority: int = 10,
        force: bool = False,
    ) -> ExtensionManifest:
        """Install extension from ZIP file.
@@ -1351,8 +1202,6 @@ 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
@@ -1399,9 +1248,7 @@ class ExtensionManager:
                raise ValidationError("No extension.yml found in ZIP file")
            # Install from extracted directory
-            return self.install_from_directory(
+            return self.install_from_directory(extension_dir, speckit_version, priority=priority)
                extension_dir, speckit_version, priority=priority, force=force
            )
    def remove(self, extension_id: str, keep_config: bool = False) -> bool:
        """Remove an installed extension.
@@ -1583,10 +1430,9 @@ 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 ai_skills_enabled
+            and bool(init_options.get("ai_skills"))
            and bool(agent_config)
            and agent_config.get("extension") != "/SKILL.md"
        )
@@ -1761,8 +1607,7 @@ 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:
@@ -1770,25 +1615,20 @@ 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(
@@ -1803,13 +1643,10 @@ 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(
+        return self.register_commands_for_agent("claude", manifest, extension_dir, project_root)
            "claude", manifest, extension_dir, project_root, link_outputs=link_outputs
        )
 class ExtensionCatalog(CatalogStackBase):
@@ -1843,59 +1680,13 @@ class ExtensionCatalog(CatalogStackBase):
        from specify_cli.authentication.http import build_request
        return build_request(url)
-    def _open_url(
+    def _open_url(self, url: str, timeout: int = 10):
        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, extra_headers=extra_headers)
+        return open_url(url, timeout)
    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
        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
        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:
            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.
@@ -2295,15 +2086,9 @@ class ExtensionCatalog(CatalogStackBase):
        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, extra_headers=extra_headers) as response:
+            with self._open_url(download_url, timeout=60) as response:
                zip_data = response.read()
            zip_path.write_bytes(zip_data)
@@ -2576,12 +2361,10 @@ class HookExecutor:
        init_options = self._load_init_options()
        selected_ai = init_options.get("ai")
-        ai_skills_enabled = is_ai_skills_enabled(init_options)
+        codex_skill_mode = selected_ai == "codex" and bool(init_options.get("ai_skills"))
-        codex_skill_mode = selected_ai == "codex" and ai_skills_enabled
+        claude_skill_mode = selected_ai == "claude" and bool(init_options.get("ai_skills"))
        claude_skill_mode = selected_ai == "claude" and ai_skills_enabled
        kimi_skill_mode = selected_ai == "kimi"
-        cursor_skill_mode = selected_ai == "cursor-agent" and ai_skills_enabled
+        cursor_skill_mode = selected_ai == "cursor-agent" and bool(init_options.get("ai_skills"))
        cline_mode = selected_ai == "cline"
        skill_name = self._skill_name_from_command(command_id)
        if codex_skill_mode and skill_name:
@@ -2592,10 +2375,6 @@ 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}"
--- a/src/specify_cli/integrations/init.py
+++ b/src/specify_cli/integrations/init.py
@@ -52,7 +52,6 @@ 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
@@ -62,7 +61,6 @@ 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
@@ -74,7 +72,6 @@ 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
@@ -87,7 +84,6 @@ def _register_builtins() -> None:
    _register(AuggieIntegration())
    _register(BobIntegration())
    _register(ClaudeIntegration())
    _register(ClineIntegration())
    _register(CodebuddyIntegration())
    _register(CodexIntegration())
    _register(CopilotIntegration())
@@ -97,7 +93,6 @@ def _register_builtins() -> None:
    _register(GeminiIntegration())
    _register(GenericIntegration())
    _register(GooseIntegration())
    _register(HermesIntegration())
    _register(IflowIntegration())
    _register(JunieIntegration())
    _register(KilocodeIntegration())
@@ -109,7 +104,6 @@ def _register_builtins() -> None:
    _register(QodercliIntegration())
    _register(QwenIntegration())
    _register(RooIntegration())
    _register(RovodevIntegration())
    _register(ShaiIntegration())
    _register(TabnineIntegration())
    _register(TraeIntegration())
--- a/src/specify_cli/integrations/_commands.py
+++ b/src/specify_cli/integrations/_commands.py
@@ -1,34 +0,0 @@
 """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")
--- a/src/specify_cli/integrations/_helpers.py
+++ b/src/specify_cli/integrations/_helpers.py
@@ -1,402 +0,0 @@
 """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
--- a/src/specify_cli/integrations/_install_commands.py
+++ b/src/specify_cli/integrations/_install_commands.py
@@ -1,309 +0,0 @@
 """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}")
--- a/src/specify_cli/integrations/_migrate_commands.py
+++ b/src/specify_cli/integrations/_migrate_commands.py
@@ -1,490 +0,0 @@
 """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")
--- a/src/specify_cli/integrations/_query_commands.py
+++ b/src/specify_cli/integrations/_query_commands.py
@@ -1,464 +0,0 @@
 """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")
--- a/src/specify_cli/integrations/agy/init.py
+++ b/src/specify_cli/integrations/agy/init.py
@@ -5,7 +5,6 @@ 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
@@ -14,15 +13,6 @@ 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):
@@ -33,8 +23,8 @@ class AgyIntegration(SkillsIntegration):
        "name": "Antigravity",
        "folder": ".agents/",
        "commands_subdir": "skills",
-        "install_url": "https://antigravity.google/",
+        "install_url": None,
-        "requires_cli": True,
+        "requires_cli": False,
    }
    registrar_config = {
        "dir": ".agents/skills",
@@ -44,54 +34,6 @@ 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,
@@ -107,21 +49,4 @@ class AgyIntegration(SkillsIntegration):
            fg="yellow",
            err=True,
        )
-        created = super().setup(project_root, manifest, parsed_options=parsed_options, **opts)
+        return 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
--- a/src/specify_cli/integrations/base.py
+++ b/src/specify_cli/integrations/base.py
@@ -13,10 +13,7 @@ Provides:
 from __future__ import annotations
 import json
 import os
 import re
 import shlex
 import shutil
 from abc import ABC
 from dataclasses import dataclass
@@ -28,27 +25,6 @@ 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
@@ -162,104 +138,6 @@ 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.
@@ -324,16 +202,6 @@ 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:
@@ -409,19 +277,11 @@ class IntegrationBase(ABC):
        return None
    def list_command_templates(self) -> list[Path]:
-        """Return ordered list of command template files from the shared directory."""
+        """Return sorted 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(
+        return sorted(f for f in cmd_dir.iterdir() if f.is_file() and f.suffix == ".md")
            (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.
@@ -622,91 +482,6 @@ 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,
@@ -715,54 +490,34 @@ 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 the configured
+        managed section.  If it exists, the content between
-        start/end markers (default ``<!-- SPECKIT START -->`` /
+        ``<!-- SPECKIT START -->`` and ``<!-- SPECKIT END -->`` markers
-        ``<!-- SPECKIT END -->``) is replaced, or appended when no markers
+        is replaced (or appended when no markers are found).
        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 or the ``agent-context`` extension is
+        ``context_file`` is not set.
        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"{marker_start}\n"
+            f"{self.CONTEXT_MARKER_START}\n"
            f"{self._build_context_section(plan_path)}\n"
-            f"{marker_end}\n"
+            f"{self.CONTEXT_MARKER_END}\n"
        )
        if ctx_path.exists():
            content = ctx_path.read_text(encoding="utf-8-sig")
-            start_idx = content.find(marker_start)
+            start_idx = content.find(self.CONTEXT_MARKER_START)
            end_idx = content.find(
-                marker_end,
+                self.CONTEXT_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(marker_end)
+                end_of_marker = end_idx + len(self.CONTEXT_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
@@ -774,7 +529,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(marker_end)
+                end_of_marker = end_idx + len(self.CONTEXT_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":
@@ -808,27 +563,20 @@ 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
-        Markers are read from the agent-context extension config
+        deleted.
        (``.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(marker_start)
+        start_idx = content.find(self.CONTEXT_MARKER_START)
        end_idx = content.find(
-            marker_end,
+            self.CONTEXT_MARKER_END,
            start_idx if start_idx != -1 else 0,
        )
@@ -839,7 +587,7 @@ class IntegrationBase(ABC):
            return False
        removal_start = start_idx
-        removal_end = end_idx + len(marker_end)
+        removal_end = end_idx + len(self.CONTEXT_MARKER_END)
        # Consume trailing line ending (CRLF or LF)
        if removal_end < len(content) and content[removal_end] == "\r":
@@ -1102,8 +850,7 @@ class MarkdownIntegration(IntegrationBase):
    ) -> list[str] | None:
        if not self.config or not self.config.get("requires_cli"):
            return None
-        args = [self._resolve_executable(), "-p", prompt]
+        args = [self.key, "-p", prompt]
        self._apply_extra_args_env_var(args)
        if model:
            args.extend(["--model", model])
        if output_json:
@@ -1190,8 +937,7 @@ class TomlIntegration(IntegrationBase):
    ) -> list[str] | None:
        if not self.config or not self.config.get("requires_cli"):
            return None
-        args = [self._resolve_executable(), "-p", prompt]
+        args = [self.key, "-p", prompt]
        self._apply_extra_args_env_var(args)
        if model:
            args.extend(["-m", model])
        if output_json:
@@ -1609,8 +1355,7 @@ class SkillsIntegration(IntegrationBase):
    ) -> list[str] | None:
        if not self.config or not self.config.get("requires_cli"):
            return None
-        args = [self._resolve_executable(), "-p", prompt]
+        args = [self.key, "-p", prompt]
        self._apply_extra_args_env_var(args)
        if model:
            args.extend(["--model", model])
        if output_json:
@@ -1646,53 +1391,15 @@ 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 base implementation injects shared skills
+        transformations.  The default implementation returns *content*
-        guidance for converting dotted hook command names to hyphenated
+        unchanged.  Subclasses may override — see ``ClaudeIntegration``.
        slash commands.  Subclasses may override — see ``ClaudeIntegration``.
        """
-        return self._inject_hook_command_note(content)
+        return content
    def setup(
        self,
@@ -1795,8 +1502,6 @@ 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"
--- a/src/specify_cli/integrations/claude/init.py
+++ b/src/specify_cli/integrations/claude/init.py
@@ -2,15 +2,24 @@
 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] = {
@@ -46,27 +55,6 @@ 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.
@@ -171,11 +159,41 @@ 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 = super().post_process_skill_content(content)
+        updated = self._inject_frontmatter_flag(content, "user-invocable")
        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(
@@ -185,9 +203,10 @@ class ClaudeIntegration(SkillsIntegration):
        parsed_options: dict[str, Any] | None = None,
        **opts: Any,
    ) -> list[Path]:
-        """Install Claude skills, then inject argument-hints."""
+        """Install Claude skills, then inject Claude-specific flags and 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:
@@ -202,7 +221,7 @@ class ClaudeIntegration(SkillsIntegration):
            content_bytes = path.read_bytes()
            content = content_bytes.decode("utf-8")
-            updated = content
+            updated = self.post_process_skill_content(content)
            # Inject argument-hint if available for this skill
            skill_dir_name = path.parent.name  # e.g. "speckit-plan"
--- a/src/specify_cli/integrations/cline/init.py
+++ b/src/specify_cli/integrations/cline/init.py
@@ -1,162 +0,0 @@
 """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
--- a/src/specify_cli/integrations/codex/init.py
+++ b/src/specify_cli/integrations/codex/init.py
@@ -6,7 +6,22 @@ Commands are deprecated; ``--skills`` defaults to ``True``.
 from __future__ import annotations
 import re
 from pathlib import Path
 from typing import Any
 from ..base import IntegrationOption, SkillsIntegration
 from ..manifest import IntegrationManifest
 # Note injected into hook sections so Codex maps dot-notation command
 # names (from extensions.yml) to the hyphenated skill names it uses.
 # Without this, Codex 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 CodexIntegration(SkillsIntegration):
@@ -37,10 +52,7 @@ class CodexIntegration(SkillsIntegration):
        output_json: bool = True,
    ) -> list[str] | None:
        # Codex uses ``codex exec "prompt"`` for non-interactive mode.
-        # Resolve argv[0] via the shared executable resolver so operators can
+        args: list[str] = ["codex", "exec", prompt]
        # 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:
@@ -57,3 +69,68 @@ class CodexIntegration(SkillsIntegration):
                help="Install as agent skills (default for Codex)",
            ),
        ]
    @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 setup(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        parsed_options: dict[str, Any] | None = None,
        **opts: Any,
    ) -> list[Path]:
        """Install Codex skills, then inject the hook command note."""
        created = super().setup(project_root, manifest, 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
--- a/src/specify_cli/integrations/copilot/init.py
+++ b/src/specify_cli/integrations/copilot/init.py
@@ -134,18 +134,6 @@ 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,
@@ -160,8 +148,7 @@ 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 = [self._resolve_executable(), "-p", prompt]
+        args = [_copilot_executable(), "-p", prompt]
        self._apply_extra_args_env_var(args)
        if _allow_all():
            args.append("--yolo")
        if model:
@@ -229,12 +216,7 @@ class CopilotIntegration(IntegrationBase):
            agent_name = f"speckit.{stem}"
            prompt = args or ""
-        cli_args = [self._resolve_executable(), "-p", prompt]
+        cli_args = [_copilot_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():
@@ -283,13 +265,57 @@ class CopilotIntegration(IntegrationBase):
        return f"speckit.{template_name}.agent.md"
    def post_process_skill_content(self, content: str) -> str:
-        """Inject shared hook guidance into Copilot skill content.
+        """Inject Copilot-specific ``mode:`` field into SKILL.md frontmatter.
-        Delegates to :class:`_CopilotSkillsHelper` for shared post-processing.
+        Inserts ``mode: speckit.<stem>`` before the closing ``---`` so
-        The ``mode:`` frontmatter field is intentionally omitted: VS Code
+        Copilot can associate the skill with its agent mode.
        Copilot Agent Skills do not support it (see issue #2799).
        """
-        return _CopilotSkillsHelper().post_process_skill_content(content)
+        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)
    def setup(
        self,
--- a/src/specify_cli/integrations/cursor_agent/init.py
+++ b/src/specify_cli/integrations/cursor_agent/init.py
@@ -2,12 +2,6 @@
 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
@@ -21,12 +15,7 @@ class CursorAgentIntegration(SkillsIntegration):
        "name": "Cursor",
        "folder": ".cursor/",
        "commands_subdir": "skills",
-        "install_url": "https://docs.cursor.com/en/cli/overview",
+        "install_url": None,
        # 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 = {
@@ -39,50 +28,6 @@ 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 [
--- a/src/specify_cli/integrations/devin/init.py
+++ b/src/specify_cli/integrations/devin/init.py
@@ -48,8 +48,7 @@ class DevinIntegration(SkillsIntegration):
        stdout instead of structured JSON. ``requires_cli=True`` is
        kept on the integration for tool detection.
        """
-        args = [self._resolve_executable(), "-p", prompt]
+        args = [self.key, "-p", prompt]
        self._apply_extra_args_env_var(args)
        if model:
            args.extend(["--model", model])
        return args
--- a/src/specify_cli/integrations/hermes/init.py
+++ b/src/specify_cli/integrations/hermes/init.py
@@ -1,280 +0,0 @@
 """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
--- a/src/specify_cli/integrations/kiro_cli/init.py
+++ b/src/specify_cli/integrations/kiro_cli/init.py
@@ -1,7 +1,5 @@
 """Kiro CLI integration."""
 import shutil
 from ..base import MarkdownIntegration
@@ -29,17 +27,3 @@ class KiroCliIntegration(MarkdownIntegration):
        "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
        )
--- a/src/specify_cli/integrations/manifest.py
+++ b/src/specify_cli/integrations/manifest.py
@@ -115,7 +115,6 @@ 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 -------------------------------------------
@@ -132,9 +131,6 @@ 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.
        """
@@ -148,77 +144,17 @@ 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, *, recovered: bool = False) -> None:
+    def record_existing(self, rel_path: str | Path) -> None:
-        """Record the hash of an already-existing regular file at *rel_path*.
+        """Record the hash of an already-existing file at *rel_path*.
-        When ``recovered=True``, the path is also marked in the manifest's
+        Raises ``ValueError`` if *rel_path* resolves outside the project root.
        ``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 ---------------------------------------------------------
@@ -227,37 +163,6 @@ 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] = []
@@ -364,11 +269,6 @@ 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"
@@ -420,20 +320,6 @@ 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(
--- a/src/specify_cli/integrations/opencode/init.py
+++ b/src/specify_cli/integrations/opencode/init.py
@@ -28,12 +28,7 @@ class OpencodeIntegration(MarkdownIntegration):
        model: str | None = None,
        output_json: bool = True,
    ) -> list[str] | None:
-        args = [self._resolve_executable(), "run"]
+        args = [self.key, "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("/"):
--- a/src/specify_cli/integrations/rovodev/init.py
+++ b/src/specify_cli/integrations/rovodev/init.py
@@ -1,263 +0,0 @@
 """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
--- a/src/specify_cli/integrations/vibe/init.py
+++ b/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 shared hook guidance and Vibe-specific frontmatter flags:
+        Inject Vibe-specific frontmatter flags:
        - user-invocable: allows the skill to be invoked by the user (not just other agents)
        """
-        updated = super().post_process_skill_content(content)
+        updated = self._inject_frontmatter_flag(content, "user-invocable")
        updated = self._inject_frontmatter_flag(updated, "user-invocable")
        return updated
    def setup(
@@ -107,4 +107,27 @@ class VibeIntegration(SkillsIntegration):
            err=True,
        )
-        return super().setup(project_root, manifest, parsed_options=parsed_options, **opts)
+        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
--- a/src/specify_cli/presets.py
+++ b/src/specify_cli/presets.py
@@ -28,8 +28,6 @@ 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(
@@ -1060,9 +1058,6 @@ 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,
@@ -1139,23 +1134,6 @@ 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
@@ -1263,7 +1241,7 @@ class PresetManager:
        selected_ai = init_opts.get("ai")
        if not isinstance(selected_ai, str):
            return []
-        ai_skills_enabled = is_ai_skills_enabled(init_opts)
+        ai_skills_enabled = bool(init_opts.get("ai_skills"))
        registrar = CommandRegistrar()
        integration = get_integration(selected_ai)
        agent_config = registrar.AGENT_CONFIGS.get(selected_ai, {})
@@ -1332,7 +1310,6 @@ class PresetManager:
            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
@@ -1425,9 +1402,6 @@ 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 = original_desc or SKILL_DESCRIPTIONS.get(
@@ -1465,9 +1439,6 @@ 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)
--- a/src/specify_cli/shared_infra.py
+++ b/src/specify_cli/shared_infra.py
@@ -3,7 +3,6 @@
 from __future__ import annotations
 import os
 import re
 import tempfile
 from pathlib import Path
 from typing import Any
@@ -195,37 +194,6 @@ 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,
    *,
@@ -397,38 +365,11 @@ 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
-                        content = src_path.read_text(encoding="utf-8")
+                        planned_copies.append((dst_path, rel, src_path.read_bytes(), src_path.stat().st_mode & 0o777))
                        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():
@@ -448,23 +389,6 @@ 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")
@@ -483,7 +407,7 @@ def install_shared_infra(
    if skipped_files:
        console.print(
-            f"[yellow]⚠[/yellow]  {len(skipped_files)} shared infrastructure path(s) already exist and were not updated:"
+            f"[yellow]⚠[/yellow]  {len(skipped_files)} shared infrastructure file(s) already exist and were not updated:"
        )
        for path in skipped_files:
            console.print(f"    {path}")
--- a/src/specify_cli/workflows/engine.py
+++ b/src/specify_cli/workflows/engine.py
@@ -11,7 +11,6 @@ The engine is the orchestrator that:
 from __future__ import annotations
 import json
 import os
 import re
 import uuid
 from datetime import datetime, timezone
@@ -232,22 +231,6 @@ 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)
@@ -281,49 +264,16 @@ 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:
-        # ``run_id is None`` (omitted) → auto-generate. An explicit empty
+        self.run_id = run_id or str(uuid.uuid4())[:8]
-        # string is *not* the same as "omitted" and must be validated like
+        if not re.match(r'^[a-zA-Z0-9][a-zA-Z0-9_-]*$', self.run_id):
-        # any other caller-provided value — otherwise ``__init__("")``
+            msg = f"Invalid run_id {self.run_id!r}: must be alphanumeric with hyphens/underscores only."
-        # would silently substitute a UUID while ``load("")`` rejects, and
+            raise ValueError(msg)
        # 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
@@ -364,20 +314,7 @@ 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():
@@ -449,10 +386,10 @@ class WorkflowEngine:
        ValueError:
            If the workflow YAML is invalid.
        """
-        path = Path(source).expanduser()
+        path = Path(source)
        # Try as a direct file path first
-        if path.suffix.lower() in (".yml", ".yaml") and path.is_file():
+        if path.suffix in (".yml", ".yaml") and path.exists():
            return WorkflowDefinition.from_yaml(path)
        # Try as an installed workflow ID
@@ -488,7 +425,7 @@ class WorkflowEngine:
        inputs:
            User-provided input values.
        run_id:
-            Optional run ID (uses SPECKIT_WORKFLOW_RUN_ID when set, otherwise auto-generated).
+            Optional run ID (auto-generated if not provided).
        Returns
        -------
@@ -496,14 +433,8 @@ 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=effective_run_id,
+            run_id=run_id,
            workflow_id=definition.id,
            project_root=self.project_root,
        )
@@ -553,19 +484,8 @@ class WorkflowEngine:
        state.save()
        return state
-    def resume(
+    def resume(self, run_id: str) -> RunState:
-        self,
+        """Resume a paused or failed workflow run."""
        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}."
@@ -581,12 +501,6 @@ 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,
@@ -708,10 +622,7 @@ 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(
@@ -720,49 +631,15 @@ class WorkflowEngine:
                            "step_id": step_id,
                        }
                    )
-                    state.save()
+                else:
-                    return
+                    state.status = RunStatus.FAILED
                # `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_continue_on_error",
+                            "event": "step_failed",
                            "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
--- a/src/specify_cli/workflows/expressions.py
+++ b/src/specify_cli/workflows/expressions.py
@@ -102,15 +102,6 @@ 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
--- a/src/specify_cli/workflows/steps/command/init.py
+++ b/src/specify_cli/workflows/steps/command/init.py
@@ -2,6 +2,7 @@
 from __future__ import annotations
 import shutil
 from pathlib import Path
 from typing import Any
@@ -125,10 +126,12 @@ class CommandStep(StepBase):
        if impl is None:
            return None
-        # Check if the CLI tool is actually installed via the integration's
+        # Check if the integration supports CLI dispatch
-        # own availability check (honours custom executables, dual binaries,
+        if impl.build_exec_args("test") is None:
-        # and non-PATH install paths).  See issue #2597.
+            return None
-        if not impl.is_cli_available():
+
        # Check if the CLI tool is actually installed
        if not shutil.which(impl.key):
            return None
        project_root = Path(context.project_root) if context.project_root else None
--- a/src/specify_cli/workflows/steps/prompt/init.py
+++ b/src/specify_cli/workflows/steps/prompt/init.py
@@ -2,6 +2,7 @@
 from __future__ import annotations
 import shutil
 from pathlib import Path
 from typing import Any
@@ -114,15 +115,10 @@ class PromptStep(StepBase):
            return None
        exec_args = impl.build_exec_args(prompt, model=model, output_json=False)
-
+        if exec_args is None:
        # 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
-        # Prompt dispatch executes exec_args directly; require a non-empty argv.
+        if not shutil.which(impl.key):
        if not exec_args:
            return None
        import subprocess
--- a/templates/commands/checklist.md
+++ b/templates/commands/checklist.md
@@ -74,9 +74,7 @@ You **MUST** consider the user input before proceeding (if not empty).
   - All file paths must be absolute.
   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
-2. **IF EXISTS**: Load `/memory/constitution.md` for project principles and governance constraints.
+2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
 3. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
   - Be generated from the user's phrasing + extracted signals from spec/plan/tasks
   - Only ask about information that materially changes checklist content
   - Be skipped individually if already unambiguous in `$ARGUMENTS`
@@ -108,13 +106,13 @@ You **MUST** consider the user input before proceeding (if not empty).
   Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
-4. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
+3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
   - Derive checklist theme (e.g., security, review, deploy, ux)
   - Consolidate explicit must-have items mentioned by user
   - Map focus selections to category scaffolding
   - Infer any missing context from spec/plan/tasks (do NOT hallucinate)
-5. **Load feature context**: Read from FEATURE_DIR:
+4. **Load feature context**: Read from FEATURE_DIR:
   - spec.md: Feature requirements and scope
   - plan.md (if exists): Technical details, dependencies
   - tasks.md (if exists): Implementation tasks
@@ -125,7 +123,7 @@ You **MUST** consider the user input before proceeding (if not empty).
   - Use progressive disclosure: add follow-on retrieval only if gaps detected
   - If source docs are large, generate interim summary items instead of embedding raw text
-6. **Generate checklist** - Create "Unit Tests for Requirements":
+5. **Generate checklist** - Create "Unit Tests for Requirements":
   - Create `FEATURE_DIR/checklists/` directory if it doesn't exist
   - Generate unique checklist filename:
     - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
@@ -243,9 +241,9 @@ You **MUST** consider the user input before proceeding (if not empty).
   - ✅ "Are [edge cases/scenarios] addressed in requirements?"
   - ✅ "Does the spec define [missing aspect]?"
-7. **Structure Reference**: Generate the checklist following the canonical template in `templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
+6. **Structure Reference**: Generate the checklist following the canonical template in `templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
-8. **Report**: Output full path to checklist file, item count, and summarize whether the run created a new file or appended to an existing one. Summarize:
+7. **Report**: Output full path to checklist file, item count, and summarize whether the run created a new file or appended to an existing one. Summarize:
   - Focus areas selected
   - Depth level
   - Actor/timing
--- a/templates/commands/clarify.md
+++ b/templates/commands/clarify.md
@@ -66,9 +66,7 @@ Execution steps:
   - If JSON parsing fails, abort and instruct user to re-run `__SPECKIT_COMMAND_SPECIFY__` or verify feature branch environment.
   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
-2. **IF EXISTS**: Load `/memory/constitution.md` for project principles and governance constraints.
+2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
 3. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
   Functional Scope & Behavior:
   - Core user goals & success criteria
@@ -124,7 +122,7 @@ Execution steps:
   - Clarification would not materially change implementation or validation strategy
   - Information is better deferred to planning phase (note internally)
-4. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
    - Maximum of 5 total questions across the whole session.
    - Each question must be answerable with EITHER:
       - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
@@ -135,7 +133,7 @@ Execution steps:
    - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
    - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
-5. Sequential questioning loop (interactive):
+4. Sequential questioning loop (interactive):
    - Present EXACTLY ONE question at a time.
    - For multiple‑choice questions:
       - **Analyze all options** and determine the **most suitable option** based on:
@@ -171,7 +169,7 @@ Execution steps:
    - Never reveal future queued questions in advance.
    - If no valid questions exist at start, immediately report no critical ambiguities.
-6. Integration after EACH accepted answer (incremental update approach):
+5. Integration after EACH accepted answer (incremental update approach):
    - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
    - For the first integrated answer in this session:
       - Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
@@ -189,7 +187,7 @@ Execution steps:
    - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
    - Keep each inserted clarification minimal and testable (avoid narrative drift).
-7. Validation (performed after EACH write plus final pass):
+6. Validation (performed after EACH write plus final pass):
   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
   - Total asked (accepted) questions ≤ 5.
   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
@@ -197,26 +195,7 @@ Execution steps:
   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
   - Terminology consistency: same canonical term used across all updated sections.
-8. Write the updated spec back to `FEATURE_SPEC`.
+7. Write the updated spec back to `FEATURE_SPEC`.
 9. **Re-validate Spec Quality Checklist** (if it exists):
   - Check if `FEATURE_DIR/checklists/requirements.md` exists.
   - If it does NOT exist, skip this step silently.
   - If it exists:
     1. Read the checklist file.
     2. Identify all GitHub task-list checkbox lines — lines matching `- [ ]`, `- [x]`, or `- [X]` (case-insensitive, tolerant of leading whitespace for nested items) outside of code fences. Ignore all other content (headings, notes, non-checkbox bullets, metadata).
     3. For each checkbox line, record its current marker state (checked or unchecked) and item text into a before-snapshot list.
     4. Re-evaluate each checkbox item against the **updated** spec (the version just saved in step 7).
     5. For each checkbox item, update only if the checked/unchecked state actually changes:
        - If the item now passes and was unchecked: change `[ ]` to `[x]`.
        - If the item now fails and was checked: change `[x]`/`[X]` to `[ ]`.
        - If the state is unchanged: leave the marker as-is (preserve existing case to avoid cosmetic diffs).
     6. Save the updated checklist file. **Only toggle the `[ ]`/`[x]` marker portion of checkbox lines whose state changed.** All other file content — headings, metadata, notes, line ordering, whitespace — must remain unchanged to avoid noisy diffs.
     7. Compare the before-snapshot with the current state to compute three lists for the Completion Report:
        - **Newly passing**: items that changed from unchecked to checked.
        - **Regressions**: items that changed from checked to unchecked.
        - **Still unchecked**: items that remain unchecked.
     8. Record the before/after pass counts as checked/total checkbox items (e.g., "12/16 → 15/16 items passing").
 Behavior rules:
@@ -269,7 +248,6 @@ Report completion (after questioning loop ends or early termination):
 - Number of questions asked & answered.
 - Path to updated spec.
 - Sections touched (list names).
 - Spec quality checklist status (if `FEATURE_DIR/checklists/requirements.md` was re-validated): show before/after pass counts (e.g., "Spec Quality Checklist: 12/16 → 15/16 items passing") and list any items that changed state — both newly checked (unchecked → checked) and any regressions (checked → unchecked). If any items remain unchecked, list them as areas needing attention.
 - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
 - If any Outstanding or Deferred remain, recommend whether to proceed to `__SPECKIT_COMMAND_PLAN__` or run `__SPECKIT_COMMAND_CLARIFY__` again later post-plan.
 - Suggested next command.
@@ -277,6 +255,5 @@ Report completion (after questioning loop ends or early termination):
 ## Done When
 - [ ] Spec ambiguities identified and clarifications integrated into spec file
 - [ ] Spec quality checklist re-validated against updated spec (if `FEATURE_DIR/checklists/requirements.md` exists)
 - [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
- [ ] Completion reported to user with questions answered, sections touched, checklist status, and coverage summary
+- [ ] Completion reported to user with questions answered, sections touched, and coverage summary
--- a/templates/commands/plan.md
+++ b/templates/commands/plan.md
@@ -147,14 +147,7 @@ Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generate
   - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
   - Skip if project is purely internal (build scripts, one-off tools, etc.)
-3. **Create quickstart validation guide** → `quickstart.md`:
+3. **Agent context update**:
   - Document runnable validation scenarios that prove the feature works end-to-end
   - Include prerequisites, setup commands, test/run commands, and expected outcomes
   - Use links or references to contracts and data model details instead of duplicating them
   - Do not include full implementation code, model/service/controller bodies, migrations, or complete test suites
   - Keep this artifact as a validation/run guide; implementation details belong in `tasks.md` and the implementation phase
 4. **Agent context update**:
   - Update the plan reference between the `<!-- SPECKIT START -->` and `<!-- SPECKIT END -->` markers in `__CONTEXT_FILE__` to point to the plan file created in step 1 (the IMPL_PLAN path)
 **Output**: data-model.md, /contracts/*, quickstart.md, updated agent context file
--- a/templates/commands/specify.md
+++ b/templates/commands/specify.md
@@ -91,8 +91,7 @@ Given that feature description, do this:
   **Create the directory and spec file**:
   - `mkdir -p SPECIFY_FEATURE_DIRECTORY`
-   - Resolve the active `spec-template` through the Spec Kit preset/template resolution stack (equivalent to `specify preset resolve spec-template`)
+   - Copy `templates/spec-template.md` to `SPECIFY_FEATURE_DIRECTORY/spec.md` as the starting point
   - Copy the resolved `spec-template` file to `SPECIFY_FEATURE_DIRECTORY/spec.md` as the starting point
   - Set `SPEC_FILE` to `SPECIFY_FEATURE_DIRECTORY/spec.md`
   - Persist the resolved path to `.specify/feature.json`:
     ```json
@@ -108,11 +107,9 @@ Given that feature description, do this:
   - The spec directory name and the git branch name are independent — they may be the same but that is the user's choice
   - The spec directory and file are always created by this command, never by the hook
-4. Load the resolved active `spec-template` file to understand required sections.
+4. Load `templates/spec-template.md` to understand required sections.
-5. **IF EXISTS**: Load `/memory/constitution.md` for project principles and governance constraints.
+5. Follow this execution flow:
 6. Follow this execution flow:
    1. Parse user description from arguments
       If empty: ERROR "No feature description provided"
    2. Extract key concepts from description
--- a/templates/commands/tasks.md
+++ b/templates/commands/tasks.md
@@ -63,7 +63,6 @@ You **MUST** consider the user input before proceeding (if not empty).
 2. **Load design documents**: Read from FEATURE_DIR:
   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
   - **Optional**: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios)
   - **IF EXISTS**: Load `/memory/constitution.md` for project principles and governance constraints
   - Note: Not all projects have all documents. Generate tasks based on what's available.
 3. **Execute task generation workflow**:
--- a/templates/commands/taskstoissues.md
+++ b/templates/commands/taskstoissues.md
@@ -51,7 +51,6 @@ You **MUST** consider the user input before proceeding (if not empty).
 ## Outline
 1. Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
 1. **IF EXISTS**: Load `/memory/constitution.md` for project principles and governance constraints.
 1. From the executed script, extract the path to **tasks**.
 1. Get the Git remote by running:
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -81,72 +81,3 @@ def _isolate_auth_config(monkeypatch):
    # Also clear the per-process cache so tests that unset _config_override
    # won't see a previously cached real-file result.
    monkeypatch.setattr(_auth_http, "_config_cache", None)
@pytest.fixture
 def clean_environ(monkeypatch):
    """Strip any real GH_TOKEN / GITHUB_TOKEN from the test environment."""
    monkeypatch.delenv("GH_TOKEN", raising=False)
    monkeypatch.delenv("GITHUB_TOKEN", raising=False)
 def _fake_self_upgrade_argv0(monkeypatch, tmp_path, env_name, path_parts):
    """Create a fake executable under tmp_path and point sys.argv[0] at it."""
    monkeypatch.setenv(env_name, str(tmp_path))
    fake_dir = tmp_path.joinpath(*path_parts)
    fake_dir.mkdir(parents=True)
    fake_specify = fake_dir / ("specify.exe" if os.name == "nt" else "specify")
    fake_specify.write_text("#!/usr/bin/env python\n")
    fake_specify.chmod(0o755)
    monkeypatch.setattr("sys.argv", [str(fake_specify)])
    return fake_specify
@pytest.fixture
 def uv_tool_argv0(monkeypatch, tmp_path):
    """Point sys.argv[0] at a simulated `uv tool` install path under tmp HOME."""
    if os.name == "nt":
        return _fake_self_upgrade_argv0(
            monkeypatch, tmp_path, "LOCALAPPDATA", ("uv", "tools", "specify-cli", "bin")
        )
    return _fake_self_upgrade_argv0(
        monkeypatch,
        tmp_path,
        "HOME",
        (".local", "share", "uv", "tools", "specify-cli", "bin"),
    )
@pytest.fixture
 def pipx_argv0(monkeypatch, tmp_path):
    """Point sys.argv[0] at a simulated pipx install path under tmp HOME."""
    if os.name == "nt":
        return _fake_self_upgrade_argv0(
            monkeypatch, tmp_path, "LOCALAPPDATA", ("pipx", "venvs", "specify-cli", "bin")
        )
    return _fake_self_upgrade_argv0(
        monkeypatch, tmp_path, "HOME", (".local", "pipx", "venvs", "specify-cli", "bin")
    )
@pytest.fixture
 def uvx_ephemeral_argv0(monkeypatch, tmp_path):
    """Point sys.argv[0] at a simulated uvx ephemeral-cache path under tmp HOME."""
    if os.name == "nt":
        return _fake_self_upgrade_argv0(
            monkeypatch,
            tmp_path,
            "LOCALAPPDATA",
            ("uv", "cache", "archive-v0", "abc123", "bin"),
        )
    return _fake_self_upgrade_argv0(
        monkeypatch, tmp_path, "HOME", (".cache", "uv", "archive-v0", "abc123", "bin")
    )
@pytest.fixture
 def unsupported_argv0(monkeypatch, tmp_path):
    """Point sys.argv[0] at a path that does not match any installer prefix."""
    return _fake_self_upgrade_argv0(
        monkeypatch, tmp_path, "HOME", ("random", "location", "bin")
    )
--- a/tests/extensions/git/test_git_extension.py
+++ b/tests/extensions/git/test_git_extension.py
@@ -371,7 +371,7 @@ class TestCreateFeaturePowerShell:
        )
        assert result.returncode == 0, result.stderr
        # pwsh may prefix warnings to stdout; find the JSON line
-        json_line = [ln for ln in result.stdout.splitlines() if ln.strip().startswith("{")]
+        json_line = [l for l in result.stdout.splitlines() if l.strip().startswith("{")]
        assert json_line, f"No JSON in output: {result.stdout}"
        data = json.loads(json_line[-1])
        assert "BRANCH_NAME" in data
--- a/tests/extensions/test_extension_agent_context.py
+++ b/tests/extensions/test_extension_agent_context.py
@@ -1,455 +0,0 @@
 """Tests for the bundled ``agent-context`` extension and related plumbing."""
 from __future__ import annotations
 import json
 from pathlib import Path
 import yaml
 from specify_cli import (
    _load_agent_context_config,
    _save_agent_context_config,
    load_init_options,
    save_init_options,
 )
 from specify_cli.integrations.base import IntegrationBase
 from specify_cli.integrations.claude import ClaudeIntegration
 PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
 EXT_DIR = PROJECT_ROOT / "extensions" / "agent-context"
 def _write_ext_config(project_root: Path, **overrides: object) -> None:
    """Write a minimal agent-context extension config."""
    cfg: dict = {
        "context_file": overrides.get("context_file", ""),
        "context_markers": overrides.get(
            "context_markers",
            {
                "start": IntegrationBase.CONTEXT_MARKER_START,
                "end": IntegrationBase.CONTEXT_MARKER_END,
            },
        ),
    }
    _save_agent_context_config(project_root, cfg)
 # ── Bundled extension layout ─────────────────────────────────────────────────
 class TestExtensionLayout:
    """The bundled agent-context extension ships a complete package."""
    def test_extension_yml_exists(self):
        assert (EXT_DIR / "extension.yml").is_file()
    def test_extension_yml_has_required_fields(self):
        manifest = yaml.safe_load((EXT_DIR / "extension.yml").read_text())
        assert manifest["extension"]["id"] == "agent-context"
        assert manifest["extension"]["name"] == "Coding Agent Context"
        assert manifest["extension"]["author"] == "spec-kit-core"
        # Provides at least the manual update command
        commands = {c["name"] for c in manifest["provides"]["commands"]}
        assert "speckit.agent-context.update" in commands
    def test_readme_exists(self):
        readme = EXT_DIR / "README.md"
        assert readme.is_file()
        text = readme.read_text(encoding="utf-8")
        assert "Coding Agent Context Extension" in text
    def test_config_template_exists(self):
        cfg = EXT_DIR / "agent-context-config.yml"
        assert cfg.is_file()
        parsed = yaml.safe_load(cfg.read_text(encoding="utf-8"))
        assert "context_file" in parsed
        assert "context_markers" in parsed
    def test_command_file_exists(self):
        cmd = EXT_DIR / "commands" / "speckit.agent-context.update.md"
        assert cmd.is_file()
        assert "agent-context-config.yml" in cmd.read_text(encoding="utf-8")
    def test_bundled_scripts_exist(self):
        assert (EXT_DIR / "scripts" / "bash" / "update-agent-context.sh").is_file()
        assert (EXT_DIR / "scripts" / "powershell" / "update-agent-context.ps1").is_file()
    def test_bash_script_reads_extension_config(self):
        text = (EXT_DIR / "scripts" / "bash" / "update-agent-context.sh").read_text(
            encoding="utf-8"
        )
        # The script must consult the extension config, not init-options.json
        assert "agent-context-config.yml" in text
        assert "context_file" in text
        assert "context_markers" in text
 # ── Catalog registration ─────────────────────────────────────────────────────
 class TestCatalogEntry:
    def test_catalog_lists_agent_context_as_bundled(self):
        catalog = json.loads(
            (PROJECT_ROOT / "extensions" / "catalog.json").read_text(encoding="utf-8")
        )
        entry = catalog["extensions"]["agent-context"]
        assert entry["bundled"] is True
        assert entry["id"] == "agent-context"
        assert entry["author"] == "spec-kit-core"
 # ── Marker resolution from extension config ──────────────────────────────────
 class _CtxIntegration(ClaudeIntegration):
    """Use Claude as a concrete integration with a context_file."""
 class TestContextMarkerResolution:
    def test_defaults_when_ext_config_missing(self, tmp_path):
        i = _CtxIntegration()
        start, end = i._resolve_context_markers(tmp_path)
        assert start == IntegrationBase.CONTEXT_MARKER_START
        assert end == IntegrationBase.CONTEXT_MARKER_END
    def test_defaults_when_markers_field_missing(self, tmp_path):
        """Config file exists with context_file but no context_markers key."""
        cfg_path = (
            tmp_path / ".specify" / "extensions" / "agent-context"
            / "agent-context-config.yml"
        )
        cfg_path.parent.mkdir(parents=True, exist_ok=True)
        cfg_path.write_text("context_file: CLAUDE.md\n", encoding="utf-8")
        i = _CtxIntegration()
        start, end = i._resolve_context_markers(tmp_path)
        assert start == IntegrationBase.CONTEXT_MARKER_START
        assert end == IntegrationBase.CONTEXT_MARKER_END
    def test_custom_markers_respected(self, tmp_path):
        _write_ext_config(
            tmp_path,
            context_markers={"start": "<!-- BEGIN -->", "end": "<!-- END -->"},
        )
        i = _CtxIntegration()
        start, end = i._resolve_context_markers(tmp_path)
        assert start == "<!-- BEGIN -->"
        assert end == "<!-- END -->"
    def test_partial_override_falls_back_for_missing_side(self, tmp_path):
        _write_ext_config(tmp_path, context_markers={"start": "<!-- ONLY START -->"})
        i = _CtxIntegration()
        start, end = i._resolve_context_markers(tmp_path)
        assert start == "<!-- ONLY START -->"
        assert end == IntegrationBase.CONTEXT_MARKER_END
    def test_invalid_markers_fall_back(self, tmp_path):
        _write_ext_config(tmp_path, context_markers={"start": 42, "end": ""})
        i = _CtxIntegration()
        start, end = i._resolve_context_markers(tmp_path)
        assert start == IntegrationBase.CONTEXT_MARKER_START
        assert end == IntegrationBase.CONTEXT_MARKER_END
 # ── upsert_context_section / remove_context_section honor markers ───────────
 class TestUpsertWithCustomMarkers:
    def _setup(self, tmp_path: Path, markers: dict | None = None) -> _CtxIntegration:
        _write_ext_config(
            tmp_path,
            context_file="CLAUDE.md",
            **({"context_markers": markers} if markers is not None else {}),
        )
        return _CtxIntegration()
    def test_upsert_uses_default_markers(self, tmp_path):
        i = self._setup(tmp_path)
        result = i.upsert_context_section(tmp_path)
        assert result is not None
        text = (tmp_path / "CLAUDE.md").read_text(encoding="utf-8")
        assert IntegrationBase.CONTEXT_MARKER_START in text
        assert IntegrationBase.CONTEXT_MARKER_END in text
    def test_upsert_uses_custom_markers(self, tmp_path):
        i = self._setup(
            tmp_path, {"start": "<!-- BEGIN -->", "end": "<!-- END -->"}
        )
        i.upsert_context_section(tmp_path)
        text = (tmp_path / "CLAUDE.md").read_text(encoding="utf-8")
        assert "<!-- BEGIN -->" in text
        assert "<!-- END -->" in text
        # Defaults must not appear
        assert IntegrationBase.CONTEXT_MARKER_START not in text
        assert IntegrationBase.CONTEXT_MARKER_END not in text
    def test_upsert_replaces_existing_custom_section(self, tmp_path):
        i = self._setup(
            tmp_path, {"start": "<!-- BEGIN -->", "end": "<!-- END -->"}
        )
        ctx = tmp_path / "CLAUDE.md"
        ctx.write_text(
            "# header\n\n<!-- BEGIN -->\nold body\n<!-- END -->\n\nfooter\n",
            encoding="utf-8",
        )
        i.upsert_context_section(tmp_path, plan_path="specs/001-foo/plan.md")
        text = ctx.read_text(encoding="utf-8")
        assert "old body" not in text
        assert "specs/001-foo/plan.md" in text
        assert text.startswith("# header\n")
        assert "footer" in text
    def test_remove_uses_custom_markers(self, tmp_path):
        i = self._setup(
            tmp_path, {"start": "<!-- BEGIN -->", "end": "<!-- END -->"}
        )
        ctx = tmp_path / "CLAUDE.md"
        ctx.write_text(
            "preamble\n\n<!-- BEGIN -->\nbody\n<!-- END -->\nepilogue\n",
            encoding="utf-8",
        )
        removed = i.remove_context_section(tmp_path)
        assert removed is True
        remaining = ctx.read_text(encoding="utf-8")
        assert "<!-- BEGIN -->" not in remaining
        assert "<!-- END -->" not in remaining
        assert "body" not in remaining
        assert "preamble" in remaining
        assert "epilogue" in remaining
    def test_remove_with_default_markers_unchanged_when_custom_in_file(self, tmp_path):
        # Extension config absent → default markers used. File contains only
        # custom markers — nothing should be removed.
        i = _CtxIntegration()
        ctx = tmp_path / "CLAUDE.md"
        original = "x\n<!-- BEGIN -->\nbody\n<!-- END -->\n"
        ctx.write_text(original, encoding="utf-8")
        assert i.remove_context_section(tmp_path) is False
        assert ctx.read_text(encoding="utf-8") == original
 # ── Extension disabled gates setup/teardown ──────────────────────────────────
 def _write_registry(project_root: Path, *, enabled: bool) -> None:
    registry = project_root / ".specify" / "extensions" / ".registry"
    registry.parent.mkdir(parents=True, exist_ok=True)
    registry.write_text(
        json.dumps(
            {
                "schema_version": "1.0",
                "extensions": {
                    "agent-context": {
                        "version": "1.0.0",
                        "enabled": enabled,
                    }
                },
            }
        ),
        encoding="utf-8",
    )
 class TestExtensionEnabledGate:
    def test_enabled_helper_default_when_no_registry(self, tmp_path):
        assert IntegrationBase._agent_context_extension_enabled(tmp_path) is True
    def test_enabled_helper_when_entry_present(self, tmp_path):
        _write_registry(tmp_path, enabled=True)
        assert IntegrationBase._agent_context_extension_enabled(tmp_path) is True
    def test_disabled_helper_when_entry_disabled(self, tmp_path):
        _write_registry(tmp_path, enabled=False)
        assert IntegrationBase._agent_context_extension_enabled(tmp_path) is False
    def test_upsert_skipped_when_disabled(self, tmp_path):
        _write_registry(tmp_path, enabled=False)
        i = _CtxIntegration()
        result = i.upsert_context_section(tmp_path)
        assert result is None
        assert not (tmp_path / "CLAUDE.md").exists()
    def test_remove_skipped_when_disabled(self, tmp_path):
        _write_registry(tmp_path, enabled=False)
        i = _CtxIntegration()
        ctx = tmp_path / "CLAUDE.md"
        original = (
            f"head\n{IntegrationBase.CONTEXT_MARKER_START}\nbody\n"
            f"{IntegrationBase.CONTEXT_MARKER_END}\ntail\n"
        )
        ctx.write_text(original, encoding="utf-8")
        assert i.remove_context_section(tmp_path) is False
        # File must be unchanged when extension is disabled
        assert ctx.read_text(encoding="utf-8") == original
 # ── Extension config writers ─────────────────────────────────────────────────
 class TestExtensionConfigWriters:
    def test_clear_init_options_clears_ext_config_context_file(self, tmp_path):
        from specify_cli import _clear_init_options_for_integration
        save_init_options(
            tmp_path,
            {"integration": "claude", "ai": "claude"},
        )
        _write_ext_config(tmp_path, context_file="CLAUDE.md")
        _clear_init_options_for_integration(tmp_path, "claude")
        cfg = _load_agent_context_config(tmp_path)
        assert cfg.get("context_file") == ""
    def test_clear_init_options_creates_ext_config_when_missing(self, tmp_path):
        from specify_cli import _clear_init_options_for_integration
        save_init_options(
            tmp_path,
            {"integration": "claude", "ai": "claude"},
        )
        _clear_init_options_for_integration(tmp_path, "claude")
        cfg = _load_agent_context_config(tmp_path)
        assert cfg.get("context_file") == ""
    def test_clear_init_options_removes_legacy_context_keys_even_when_not_active(
        self, tmp_path
    ):
        from specify_cli import _clear_init_options_for_integration
        save_init_options(
            tmp_path,
            {
                "integration": "copilot",
                "ai": "copilot",
                "context_file": "CLAUDE.md",
                "context_markers": {"start": "<!-- X -->", "end": "<!-- Y -->"},
            },
        )
        _clear_init_options_for_integration(tmp_path, "claude")
        opts = load_init_options(tmp_path)
        assert opts["integration"] == "copilot"
        assert opts["ai"] == "copilot"
        assert "context_file" not in opts
        assert "context_markers" not in opts
    def test_update_init_options_writes_context_file_to_ext_config(self, tmp_path):
        from specify_cli import _update_init_options_for_integration
        # Pre-create the extension config so _update_init_options_for_integration
        # updates it (rather than skipping it when ext config doesn't exist yet).
        _write_ext_config(tmp_path, context_file="")
        i = _CtxIntegration()
        _update_init_options_for_integration(tmp_path, i, script_type="sh")
        # init-options.json must NOT have context_file or context_markers
        opts = load_init_options(tmp_path)
        assert "context_file" not in opts
        assert "context_markers" not in opts
        # Extension config must have them
        cfg = _load_agent_context_config(tmp_path)
        assert cfg["context_file"] == i.context_file
        assert "context_markers" in cfg
    def test_update_init_options_preserves_custom_markers(self, tmp_path):
        from specify_cli import _update_init_options_for_integration
        _write_ext_config(
            tmp_path,
            context_file="",
            context_markers={"start": "<!-- B -->", "end": "<!-- E -->"},
        )
        i = _CtxIntegration()
        _update_init_options_for_integration(tmp_path, i)
        cfg = _load_agent_context_config(tmp_path)
        assert cfg["context_markers"] == {"start": "<!-- B -->", "end": "<!-- E -->"}
    def test_reinit_preserves_custom_markers(self, tmp_path):
        """specify init (reinit) must not overwrite user-customised markers."""
        from specify_cli import _update_agent_context_config_file
        # Simulate existing project with custom markers
        _write_ext_config(
            tmp_path,
            context_file="CLAUDE.md",
            context_markers={"start": "<!-- CUSTOM -->", "end": "<!-- /CUSTOM -->"},
        )
        # Re-running init updates context_file but must preserve markers
        _update_agent_context_config_file(
            tmp_path, "CLAUDE.md", preserve_markers=True
        )
        cfg = _load_agent_context_config(tmp_path)
        assert cfg["context_markers"] == {
            "start": "<!-- CUSTOM -->",
            "end": "<!-- /CUSTOM -->",
        }
 # ── Deprecation warning on upsert ────────────────────────────────────────────
 class TestDeprecationWarning:
    def test_upsert_emits_deprecation_warning(self, tmp_path, capsys):
        """upsert_context_section must emit a deprecation notice on stdout."""
        from tests.conftest import strip_ansi
        i = _CtxIntegration()
        _write_ext_config(tmp_path, context_file="CLAUDE.md")
        i.upsert_context_section(tmp_path)
        captured = capsys.readouterr()
        plain = strip_ansi(captured.out)
        assert "Deprecation" in plain
        assert "v0.12.0" in plain
        assert "agent-context" in plain
    def test_upsert_no_warning_when_disabled(self, tmp_path, capsys):
        """No deprecation warning when agent-context extension is disabled."""
        _write_registry(tmp_path, enabled=False)
        i = _CtxIntegration()
        i.upsert_context_section(tmp_path)
        captured = capsys.readouterr()
        assert "Deprecation" not in captured.out
 # ── Corrupt / invalid extension config ───────────────────────────────────────
 class TestCorruptExtensionConfig:
    def test_marker_resolution_with_corrupt_yaml(self, tmp_path):
        """Corrupt YAML in agent-context-config.yml falls back to defaults."""
        cfg_path = (
            tmp_path / ".specify" / "extensions" / "agent-context"
            / "agent-context-config.yml"
        )
        cfg_path.parent.mkdir(parents=True, exist_ok=True)
        cfg_path.write_text(": invalid: yaml: {{{\n", encoding="utf-8")
        i = _CtxIntegration()
        start, end = i._resolve_context_markers(tmp_path)
        assert start == IntegrationBase.CONTEXT_MARKER_START
        assert end == IntegrationBase.CONTEXT_MARKER_END
    def test_upsert_with_corrupt_config_uses_defaults(self, tmp_path):
        """upsert_context_section still works when config YAML is corrupt."""
        cfg_path = (
            tmp_path / ".specify" / "extensions" / "agent-context"
            / "agent-context-config.yml"
        )
        cfg_path.parent.mkdir(parents=True, exist_ok=True)
        cfg_path.write_text("not valid yaml: {{{\n", encoding="utf-8")
        i = _CtxIntegration()
        result = i.upsert_context_section(tmp_path)
        assert result is not None
        text = (tmp_path / "CLAUDE.md").read_text(encoding="utf-8")
        assert IntegrationBase.CONTEXT_MARKER_START in text
        assert IntegrationBase.CONTEXT_MARKER_END in text
    def test_marker_resolution_with_non_dict_yaml(self, tmp_path):
        """Config file containing a scalar (not a dict) falls back to defaults."""
        cfg_path = (
            tmp_path / ".specify" / "extensions" / "agent-context"
            / "agent-context-config.yml"
        )
        cfg_path.parent.mkdir(parents=True, exist_ok=True)
        cfg_path.write_text("just a string\n", encoding="utf-8")
        i = _CtxIntegration()
        start, end = i._resolve_context_markers(tmp_path)
        assert start == IntegrationBase.CONTEXT_MARKER_START
        assert end == IntegrationBase.CONTEXT_MARKER_END
--- a/tests/http_helpers.py
+++ b/tests/http_helpers.py
@@ -1,15 +0,0 @@
 """HTTP test helpers shared by version-related CLI tests."""
 import json
 from unittest.mock import MagicMock
 def mock_urlopen_response(payload: dict) -> MagicMock:
    """Build a urlopen context-manager mock whose read returns JSON."""
    body = json.dumps(payload).encode("utf-8")
    resp = MagicMock()
    resp.read.return_value = body
    cm = MagicMock()
    cm.__enter__.return_value = resp
    cm.__exit__.return_value = False
    return cm
--- a/tests/integrations/test_base.py
+++ b/tests/integrations/test_base.py
@@ -121,11 +121,6 @@ class TestBasePrimitives:
        assert len(templates) > 0
        assert all(t.suffix == ".md" for t in templates)
    def test_list_command_templates_keeps_checklist_after_plan(self):
        i = StubIntegration()
        stems = [template.stem for template in i.list_command_templates()]
        assert stems.index("plan") < stems.index("checklist")
    def test_command_filename_default(self):
        i = StubIntegration()
        assert i.command_filename("plan") == "speckit.plan.md"
--- a/tests/integrations/test_cli.py
+++ b/tests/integrations/test_cli.py
@@ -87,14 +87,7 @@ class TestInitIntegrationFlag:
        opts = json.loads((project / ".specify" / "init-options.json").read_text(encoding="utf-8"))
        assert opts["integration"] == "copilot"
-        # context_file lives in the agent-context extension config, not init-options.json
+        assert opts["context_file"] == ".github/copilot-instructions.md"
        assert "context_file" not in opts
        import yaml as _yaml
        ext_cfg_path = project / ".specify" / "extensions" / "agent-context" / "agent-context-config.yml"
        assert ext_cfg_path.exists(), "agent-context extension config must be created on init"
        ext_cfg = _yaml.safe_load(ext_cfg_path.read_text(encoding="utf-8"))
        assert ext_cfg["context_file"] == ".github/copilot-instructions.md"
        assert (project / ".specify" / "integrations" / "copilot.manifest.json").exists()
@@ -330,7 +323,6 @@ class TestInitIntegrationFlag:
    def test_shared_infra_skip_warning_displayed(self, tmp_path, capsys):
        """Console warning is displayed when files are skipped."""
        from specify_cli import _install_shared_infra
        from tests.conftest import strip_ansi
        project = tmp_path / "warn-test"
        project.mkdir()
@@ -931,23 +923,7 @@ class TestGitExtensionAutoInstall:
 class TestSharedInfraCommandRefs:
-    """Verify _install_shared_infra resolves __SPECKIT_COMMAND_*__ in shared infra."""
+    """Verify _install_shared_infra resolves __SPECKIT_COMMAND_*__ in page templates."""
    @staticmethod
    def _combined_script_content(project, script_type):
        script_dir = "bash" if script_type == "sh" else "powershell"
        suffix = "sh" if script_type == "sh" else "ps1"
        names = [
            f"check-prerequisites.{suffix}",
            f"common.{suffix}",
            f"setup-tasks.{suffix}",
        ]
        return "\n".join(
            (project / ".specify" / "scripts" / script_dir / name).read_text(
                encoding="utf-8"
            )
            for name in names
        )
    def test_dot_separator_in_page_templates(self, tmp_path):
        """Markdown agents get /speckit.<name> in page templates."""
@@ -992,46 +968,6 @@ class TestSharedInfraCommandRefs:
        assert "__SPECKIT_COMMAND_" not in content
        assert "/speckit-tasks" in content
    @pytest.mark.parametrize("script_type", ["sh", "ps"])
    def test_dot_separator_in_shared_scripts(self, tmp_path, script_type):
        """Markdown agents get /speckit.<name> in shared script hints."""
        from specify_cli import _install_shared_infra
        project = tmp_path / f"dot-script-{script_type}"
        project.mkdir()
        (project / ".specify").mkdir()
        _install_shared_infra(project, script_type, invoke_separator=".")
        content = self._combined_script_content(project, script_type)
        assert "__SPECKIT_COMMAND_" not in content
        assert "/speckit.specify" in content
        assert "/speckit.plan" in content
        assert "/speckit.tasks" in content
        assert "/speckit-specify" not in content
        assert "/speckit-plan" not in content
        assert "/speckit-tasks" not in content
    @pytest.mark.parametrize("script_type", ["sh", "ps"])
    def test_hyphen_separator_in_shared_scripts(self, tmp_path, script_type):
        """Skills agents get /speckit-<name> in shared script hints."""
        from specify_cli import _install_shared_infra
        project = tmp_path / f"hyphen-script-{script_type}"
        project.mkdir()
        (project / ".specify").mkdir()
        _install_shared_infra(project, script_type, invoke_separator="-")
        content = self._combined_script_content(project, script_type)
        assert "__SPECKIT_COMMAND_" not in content
        assert "/speckit-specify" in content
        assert "/speckit-plan" in content
        assert "/speckit-tasks" in content
        assert "/speckit.specify" not in content
        assert "/speckit.plan" not in content
        assert "/speckit.tasks" not in content
    def test_full_init_claude_resolves_page_templates(self, tmp_path):
        """Full CLI init with Claude (skills agent) produces hyphen refs in page templates."""
        from typer.testing import CliRunner
@@ -1059,10 +995,6 @@ class TestSharedInfraCommandRefs:
        assert "/speckit-plan" in content, "Claude (skills) should use /speckit-plan"
        assert "__SPECKIT_COMMAND_" not in content
        script_content = self._combined_script_content(project, "sh")
        assert "/speckit-specify" in script_content
        assert "/speckit.specify" not in script_content
    def test_full_init_copilot_resolves_page_templates(self, tmp_path):
        """Full CLI init with Copilot (markdown agent) produces dot refs in page templates."""
        from typer.testing import CliRunner
@@ -1090,10 +1022,6 @@ class TestSharedInfraCommandRefs:
        assert "/speckit.plan" in content, "Copilot (markdown) should use /speckit.plan"
        assert "__SPECKIT_COMMAND_" not in content
        script_content = self._combined_script_content(project, "sh")
        assert "/speckit.specify" in script_content
        assert "/speckit-specify" not in script_content
    def test_full_init_copilot_skills_resolves_page_templates(self, tmp_path):
        """Full CLI init with Copilot --skills produces hyphen refs in page templates."""
        from typer.testing import CliRunner
@@ -1123,10 +1051,6 @@ class TestSharedInfraCommandRefs:
        assert "/speckit.plan" not in content, "dot-notation leaked into Copilot skills page template"
        assert "__SPECKIT_COMMAND_" not in content
        script_content = self._combined_script_content(project, "sh")
        assert "/speckit-specify" in script_content
        assert "/speckit.specify" not in script_content
 class TestIntegrationCatalogDiscoveryCLI:
    """End-to-end CLI tests for `integration search`, `info`, and `catalog …`.
--- a/tests/integrations/test_extra_args.py
+++ b/tests/integrations/test_extra_args.py
@@ -1,638 +0,0 @@
 """Tests for the per-integration `SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS` and
 `SPECKIT_INTEGRATION_<KEY>_EXECUTABLE` env-var hooks.
 The hooks are implemented in `IntegrationBase._apply_extra_args_env_var` and
 `IntegrationBase._resolve_executable` and wired into every concrete
 `build_exec_args` — `MarkdownIntegration`, `TomlIntegration`,
 `SkillsIntegration`, plus override integrations.
 These tests cover both the shared mechanisms (via `SkillsIntegration` stubs
 near the top of the file) and override integrations end-to-end (further down).
 See issues #2595 and #2596."""
 import os
 import pytest
 from specify_cli.integrations.base import (
    MarkdownIntegration,
    SkillsIntegration,
    TomlIntegration,
 )
 class _ClaudeStub(SkillsIntegration):
    """Minimal Claude-like SkillsIntegration for testing."""
    key = "claude"
    config = {
        "name": "Claude (test stub)",
        "folder": ".claude/",
        "commands_subdir": "skills",
        "install_url": None,
        "requires_cli": True,
    }
    registrar_config = {
        "dir": ".claude/skills",
        "format": "markdown",
        "args": "$ARGUMENTS",
        "extension": "/SKILL.md",
    }
    context_file = "CLAUDE.md"
 class _KiroCliStub(SkillsIntegration):
    """SkillsIntegration with a hyphenated key to exercise key
    normalization (`kiro-cli` → `KIRO_CLI`)."""
    key = "kiro-cli"
    config = {
        "name": "Kiro CLI (test stub)",
        "folder": ".kiro/",
        "commands_subdir": "commands",
        "install_url": None,
        "requires_cli": True,
    }
    registrar_config = {
        "dir": ".kiro/commands",
        "format": "markdown",
        "args": "$ARGUMENTS",
        "extension": ".md",
    }
    context_file = "KIRO.md"
 class _NoCliStub(SkillsIntegration):
    """SkillsIntegration with requires_cli=False — build_exec_args
    must return None and the env-var hook must not fire."""
    key = "no-cli"
    config = {
        "name": "No-CLI agent (test stub)",
        "folder": ".no-cli/",
        "commands_subdir": "commands",
        "install_url": None,
        "requires_cli": False,
    }
    registrar_config = {
        "dir": ".no-cli/commands",
        "format": "markdown",
        "args": "$ARGUMENTS",
        "extension": ".md",
    }
    context_file = "NOCLI.md"
 class _MarkdownAgentStub(MarkdownIntegration):
    """Bare MarkdownIntegration subclass — does NOT override
    `build_exec_args`. Locks the base implementation in
    `MarkdownIntegration.build_exec_args` for the common case
    (most concrete integrations: Amp, Auggie, Generic, …)."""
    key = "md-agent"
    config = {
        "name": "Markdown agent (test stub)",
        "folder": ".md-agent/",
        "commands_subdir": "commands",
        "install_url": None,
        "requires_cli": True,
    }
    registrar_config = {
        "dir": ".md-agent/commands",
        "format": "markdown",
        "args": "$ARGUMENTS",
        "extension": ".md",
    }
    context_file = "MDAGENT.md"
 class _TomlAgentStub(TomlIntegration):
    """Bare TomlIntegration subclass — does NOT override
    `build_exec_args`. Locks the base implementation in
    `TomlIntegration.build_exec_args` (Gemini, Tabnine)."""
    key = "toml-agent"
    config = {
        "name": "TOML agent (test stub)",
        "folder": ".toml-agent/",
        "commands_subdir": "commands",
        "install_url": None,
        "requires_cli": True,
    }
    registrar_config = {
        "dir": ".toml-agent/commands",
        "format": "toml",
        "args": "$ARGUMENTS",
        "extension": ".toml",
    }
    context_file = "TOMLAGENT.md"
@pytest.fixture(autouse=True)
 def _clean_extra_args_env(monkeypatch):
    """Strip any leaked SPECKIT_INTEGRATION_*_EXTRA_ARGS and
    SPECKIT_INTEGRATION_*_EXECUTABLE vars from the test env so a
    developer's shell setting doesn't pollute results."""
    for key in list(os.environ):
        if key.startswith("SPECKIT_INTEGRATION_") and (
            key.endswith("_EXTRA_ARGS") or key.endswith("_EXECUTABLE")
        ):
            monkeypatch.delenv(key, raising=False)
 def test_env_var_unset_byte_identical_argv():
    """Default behaviour: env var unset → no extra args inserted.
    Locks the backward-compatibility guarantee that existing
    operators see no change.
    """
    args = _ClaudeStub().build_exec_args("hello prompt")
    assert args == ["claude", "-p", "hello prompt", "--output-format", "json"]
 def test_env_var_set_flag_inserted_before_model_and_output_format(
    monkeypatch,
 ):
    monkeypatch.setenv(
        "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS", "--dangerously-skip-permissions"
    )
    args = _ClaudeStub().build_exec_args("hello prompt", model="sonnet")
    assert args == [
        "claude",
        "-p",
        "hello prompt",
        "--dangerously-skip-permissions",
        "--model",
        "sonnet",
        "--output-format",
        "json",
    ]
 def test_env_var_multi_token_parsed_via_shlex(monkeypatch):
    monkeypatch.setenv(
        "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS",
        "--dangerously-skip-permissions --max-turns 3",
    )
    args = _ClaudeStub().build_exec_args("p")
    assert args == [
        "claude",
        "-p",
        "p",
        "--dangerously-skip-permissions",
        "--max-turns",
        "3",
        "--output-format",
        "json",
    ]
 def test_malformed_quoting_raises_actionable_value_error(monkeypatch):
    """An unmatched quote in the env-var value must surface a clear
    error naming the offending env var and showing the invalid value,
    rather than crashing workflow dispatch with a bare shlex traceback."""
    monkeypatch.setenv(
        "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS",
        '--flag "unterminated',
    )
    with pytest.raises(ValueError) as excinfo:
        _ClaudeStub().build_exec_args("p")
    msg = str(excinfo.value)
    assert "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS" in msg
    assert "--flag \"unterminated" in msg
 def test_env_var_empty_or_whitespace_is_noop(monkeypatch):
    """An env var set to '' or '   ' is treated as unset."""
    monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS", "   ")
    args = _ClaudeStub().build_exec_args("p")
    assert args == ["claude", "-p", "p", "--output-format", "json"]
 def test_other_integration_env_var_ignored(monkeypatch):
    """`SPECKIT_INTEGRATION_GEMINI_EXTRA_ARGS` set must NOT leak into
    Claude's argv (per-integration scoping)."""
    monkeypatch.setenv("SPECKIT_INTEGRATION_GEMINI_EXTRA_ARGS", "--gemini-only-flag")
    args = _ClaudeStub().build_exec_args("p")
    assert args == ["claude", "-p", "p", "--output-format", "json"]
 def test_key_normalization_hyphen_to_underscore_uppercase(monkeypatch):
    """`kiro-cli` key looks up `SPECKIT_INTEGRATION_KIRO_CLI_EXTRA_ARGS`
    (hyphens replaced with underscores, then uppercased)."""
    monkeypatch.setenv(
        "SPECKIT_INTEGRATION_KIRO_CLI_EXTRA_ARGS", "--some-kiro-flag"
    )
    args = _KiroCliStub().build_exec_args("p")
    assert args == [
        "kiro-cli",
        "-p",
        "p",
        "--some-kiro-flag",
        "--output-format",
        "json",
    ]
 def test_requires_cli_false_returns_none(monkeypatch):
    """`requires_cli: False` short-circuits to None — the env-var
    hook is never reached and no argv is built."""
    monkeypatch.setenv("SPECKIT_INTEGRATION_NO_CLI_EXTRA_ARGS", "--should-not-appear")
    assert _NoCliStub().build_exec_args("p") is None
 # ---------------------------------------------------------------------------
 # Base-class coverage
 #
 # Most integrations inherit `build_exec_args` from `MarkdownIntegration`
 # or `TomlIntegration` without overriding it. The tests above use
 # `SkillsIntegration` stubs (which share the same hook mechanism) — these
 # tests exercise the two other base implementations directly so all three
 # concrete bases are covered.
 # ---------------------------------------------------------------------------
 def test_markdown_integration_base_honours_extra_args(monkeypatch):
    """A bare `MarkdownIntegration` subclass — which does not override
    `build_exec_args` — must honour the env var via the base
    implementation. Covers the most common integration pattern."""
    monkeypatch.setenv(
        "SPECKIT_INTEGRATION_MD_AGENT_EXTRA_ARGS", "--debug --max-tokens 100"
    )
    args = _MarkdownAgentStub().build_exec_args("p")
    assert args == [
        "md-agent",
        "-p",
        "p",
        "--debug",
        "--max-tokens",
        "100",
        "--output-format",
        "json",
    ]
 def test_toml_integration_base_honours_extra_args(monkeypatch):
    """A bare `TomlIntegration` subclass — which does not override
    `build_exec_args` — must honour the env var via the base
    implementation. Covers Gemini/Tabnine-style integrations."""
    monkeypatch.setenv(
        "SPECKIT_INTEGRATION_TOML_AGENT_EXTRA_ARGS", "--yolo"
    )
    args = _TomlAgentStub().build_exec_args("p", model="gemini-pro")
    # TomlIntegration uses `-m` for model (vs Markdown's `--model`).
    assert args == [
        "toml-agent",
        "-p",
        "p",
        "--yolo",
        "-m",
        "gemini-pro",
        "--output-format",
        "json",
    ]
 # ---------------------------------------------------------------------------
 # Override-integration coverage
 #
 # CodexIntegration, DevinIntegration, OpencodeIntegration and
 # CopilotIntegration each override `build_exec_args` rather than using the
 # base implementations. The env-var hook must be wired into every override
 # so the documented behaviour ("works for every requires_cli integration")
 # is honoured. These tests lock that contract per integration.
 # ---------------------------------------------------------------------------
 def test_codex_integration_honours_extra_args(monkeypatch):
    from specify_cli.integrations.codex import CodexIntegration
    monkeypatch.setenv("SPECKIT_INTEGRATION_CODEX_EXTRA_ARGS", "--sandbox read-only")
    args = CodexIntegration().build_exec_args("p", model="gpt-5")
    assert args == [
        "codex",
        "exec",
        "p",
        "--sandbox",
        "read-only",
        "--model",
        "gpt-5",
        "--json",
    ]
 def test_devin_integration_honours_extra_args(monkeypatch):
    from specify_cli.integrations.devin import DevinIntegration
    monkeypatch.setenv("SPECKIT_INTEGRATION_DEVIN_EXTRA_ARGS", "--no-confirm")
    args = DevinIntegration().build_exec_args("p")
    assert args == ["devin", "-p", "p", "--no-confirm"]
 def test_opencode_integration_honours_extra_args(monkeypatch):
    from specify_cli.integrations.opencode import OpencodeIntegration
    monkeypatch.setenv("SPECKIT_INTEGRATION_OPENCODE_EXTRA_ARGS", "--quiet")
    args = OpencodeIntegration().build_exec_args("p")
    assert args == [
        "opencode",
        "run",
        "--quiet",
        "--format",
        "json",
        "p",
    ]
 def test_opencode_extra_args_cannot_clobber_prompt_derived_command(
    monkeypatch,
 ):
    """Operator-injected extra args must appear BEFORE the prompt-derived
    ``--command <X>`` so that Spec Kit's command selection wins under
    repeated-flag CLI semantics (last value typically takes precedence).
    Locks against the regression where an operator setting
    ``SPECKIT_INTEGRATION_OPENCODE_EXTRA_ARGS="--command malicious"`` could redirect
    a slash-prefixed prompt to a different command.
    """
    from specify_cli.integrations.opencode import OpencodeIntegration
    monkeypatch.setenv(
        "SPECKIT_INTEGRATION_OPENCODE_EXTRA_ARGS", "--command operator-override"
    )
    args = OpencodeIntegration().build_exec_args("/speckit body text")
    # Prompt-derived "--command speckit" appears AFTER the
    # operator-injected one, so a CLI that resolves repeated flags
    # last-wins will honour Spec Kit's choice.
    assert args == [
        "opencode",
        "run",
        "--command",
        "operator-override",
        "--command",
        "speckit",
        "--format",
        "json",
        "body text",
    ]
 def test_copilot_integration_honours_extra_args(monkeypatch):
    from specify_cli.integrations.copilot import (
        CopilotIntegration,
        _copilot_executable,
    )
    # Disable --yolo so the argv shape stays deterministic.
    monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
    monkeypatch.setenv(
        "SPECKIT_INTEGRATION_COPILOT_EXTRA_ARGS", "--allow-tool 'shell(echo)'"
    )
    args = CopilotIntegration().build_exec_args("p")
    # `_copilot_executable()` returns "copilot.cmd" on Windows and
    # "copilot" elsewhere; the test must mirror that to stay portable.
    assert args == [
        _copilot_executable(),
        "-p",
        "p",
        "--allow-tool",
        "shell(echo)",
        "--output-format",
        "json",
    ]
 # ---------------------------------------------------------------------------
 # `dispatch_command` end-to-end coverage
 #
 # Workflow execution calls `impl.dispatch_command(...)`, not
 # `build_exec_args` directly. `IntegrationBase.dispatch_command` delegates
 # to `build_exec_args` (so the override fixes above flow through), but
 # `CopilotIntegration` overrides `dispatch_command` and constructs
 # `cli_args` inline — the hook must be invoked there too or the env var
 # is silently ignored at workflow runtime. These tests monkeypatch
 # `subprocess.run` and assert the env-var args reach the executed argv.
 # ---------------------------------------------------------------------------
 class _RunCapture:
    """Test double that captures argv passed to subprocess.run."""
    def __init__(self):
        self.captured_args: list[str] | None = None
    def __call__(self, args, **kwargs):
        self.captured_args = list(args)
        class _Result:
            returncode = 0
            stdout = ""
            stderr = ""
        return _Result()
 def test_copilot_dispatch_command_includes_extra_args(monkeypatch):
    """Locks the bypass fix: `CopilotIntegration.dispatch_command`
    must honour `SPECKIT_INTEGRATION_COPILOT_EXTRA_ARGS`, not just `build_exec_args`.
    """
    import subprocess
    from specify_cli.integrations.copilot import CopilotIntegration
    capture = _RunCapture()
    monkeypatch.setattr(subprocess, "run", capture)
    monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
    monkeypatch.setenv(
        "SPECKIT_INTEGRATION_COPILOT_EXTRA_ARGS", "--allow-tool 'shell(echo)'"
    )
    CopilotIntegration().dispatch_command(
        "speckit.plan", args="body", stream=False
    )
    assert capture.captured_args is not None
    # Hook inserted between `-p prompt` and the canonical Copilot flags.
    p_idx = capture.captured_args.index("-p")
    agent_idx = capture.captured_args.index("--agent")
    extra_idx = capture.captured_args.index("--allow-tool")
    assert p_idx < extra_idx < agent_idx
    assert "shell(echo)" in capture.captured_args
 def test_codex_dispatch_command_includes_extra_args(monkeypatch):
    """Lock the inherited `IntegrationBase.dispatch_command` path:
    Codex (and by transitivity Devin, Opencode) flow through
    `build_exec_args`, so the env var must reach argv at workflow
    runtime.
    """
    import subprocess
    from specify_cli.integrations.codex import CodexIntegration
    capture = _RunCapture()
    monkeypatch.setattr(subprocess, "run", capture)
    monkeypatch.setenv("SPECKIT_INTEGRATION_CODEX_EXTRA_ARGS", "--sandbox read-only")
    CodexIntegration().dispatch_command(
        "speckit.plan", args="body", stream=False
    )
    assert capture.captured_args is not None
    assert "--sandbox" in capture.captured_args
    assert "read-only" in capture.captured_args
 # ---------------------------------------------------------------------------
 # SPECKIT_INTEGRATION_<KEY>_EXECUTABLE tests
 #
 # The `_resolve_executable()` method on `IntegrationBase` checks
 # `SPECKIT_INTEGRATION_<KEY>_EXECUTABLE` and, when set, substitutes that
 # value for `self.key` as the first token in argv.  The tests below lock
 # the behaviour across shared and override integration paths:
 #   - the shared SkillsIntegration/MarkdownIntegration/TomlIntegration bases,
 #   - representative override integrations,
 #   - the hyphen→underscore key normalisation, and
 #   - whitespace/unset no-op guarantee.
 # ---------------------------------------------------------------------------
 def test_executable_env_var_unset_uses_key():
    """Default: no override → executable is the integration key."""
    args = _ClaudeStub().build_exec_args("p")
    assert args[0] == "claude"
 def test_executable_env_var_replaces_first_argv_token(monkeypatch):
    """Setting the env var substitutes the executable name in argv."""
    monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXECUTABLE", "/opt/claude/bin/claude")
    args = _ClaudeStub().build_exec_args("hello")
    assert args[0] == "/opt/claude/bin/claude"
    assert args[1:] == ["-p", "hello", "--output-format", "json"]
 def test_executable_env_var_whitespace_only_falls_back_to_key(monkeypatch):
    """Whitespace-only value is treated as unset → falls back to self.key."""
    monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXECUTABLE", "   ")
    args = _ClaudeStub().build_exec_args("p")
    assert args[0] == "claude"
 def test_executable_env_var_key_normalization_hyphen_to_underscore(monkeypatch):
    """`kiro-cli` key maps to `SPECKIT_INTEGRATION_KIRO_CLI_EXECUTABLE`."""
    monkeypatch.setenv("SPECKIT_INTEGRATION_KIRO_CLI_EXECUTABLE", "/usr/local/bin/kiro-cli")
    args = _KiroCliStub().build_exec_args("p")
    assert args[0] == "/usr/local/bin/kiro-cli"
 def test_executable_env_var_other_integration_ignored(monkeypatch):
    """`SPECKIT_INTEGRATION_GEMINI_EXECUTABLE` must NOT affect Claude."""
    monkeypatch.setenv("SPECKIT_INTEGRATION_GEMINI_EXECUTABLE", "/custom/gemini")
    args = _ClaudeStub().build_exec_args("p")
    assert args[0] == "claude"
 def test_executable_env_var_markdown_integration(monkeypatch):
    """MarkdownIntegration base honours the executable env var."""
    monkeypatch.setenv("SPECKIT_INTEGRATION_MD_AGENT_EXECUTABLE", "/custom/md-agent")
    args = _MarkdownAgentStub().build_exec_args("p")
    assert args[0] == "/custom/md-agent"
 def test_executable_env_var_toml_integration(monkeypatch):
    """TomlIntegration base honours the executable env var."""
    monkeypatch.setenv("SPECKIT_INTEGRATION_TOML_AGENT_EXECUTABLE", "/custom/toml-agent")
    args = _TomlAgentStub().build_exec_args("p")
    assert args[0] == "/custom/toml-agent"
 def test_executable_env_var_requires_cli_false_returns_none(monkeypatch):
    """`requires_cli: False` still returns None even when executable is set."""
    monkeypatch.setenv("SPECKIT_INTEGRATION_NO_CLI_EXECUTABLE", "/custom/no-cli")
    assert _NoCliStub().build_exec_args("p") is None
 def test_executable_env_var_codex_integration(monkeypatch):
    """CodexIntegration honours the executable env var."""
    from specify_cli.integrations.codex import CodexIntegration
    monkeypatch.setenv("SPECKIT_INTEGRATION_CODEX_EXECUTABLE", "/opt/codex")
    args = CodexIntegration().build_exec_args("p")
    assert args[0] == "/opt/codex"
    assert args[1] == "exec"
 def test_executable_env_var_devin_integration(monkeypatch):
    """DevinIntegration honours the executable env var."""
    from specify_cli.integrations.devin import DevinIntegration
    monkeypatch.setenv("SPECKIT_INTEGRATION_DEVIN_EXECUTABLE", "/opt/devin")
    args = DevinIntegration().build_exec_args("p")
    assert args[0] == "/opt/devin"
 def test_executable_env_var_opencode_integration(monkeypatch):
    """OpencodeIntegration honours the executable env var."""
    from specify_cli.integrations.opencode import OpencodeIntegration
    monkeypatch.setenv("SPECKIT_INTEGRATION_OPENCODE_EXECUTABLE", "/opt/opencode")
    args = OpencodeIntegration().build_exec_args("p")
    assert args[0] == "/opt/opencode"
    assert args[1] == "run"
 def test_executable_env_var_copilot_integration(monkeypatch):
    """CopilotIntegration honours the executable env var, overriding the
    platform-specific default from `_copilot_executable()`."""
    from specify_cli.integrations.copilot import CopilotIntegration
    monkeypatch.setenv("SPECKIT_INTEGRATION_COPILOT_EXECUTABLE", "/opt/copilot")
    monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
    args = CopilotIntegration().build_exec_args("p")
    assert args[0] == "/opt/copilot"
 def test_executable_env_var_copilot_unset_uses_platform_default(monkeypatch):
    """When `SPECKIT_INTEGRATION_COPILOT_EXECUTABLE` is unset, Copilot
    falls back to the platform-specific default from `_copilot_executable()`."""
    from specify_cli.integrations.copilot import CopilotIntegration, _copilot_executable
    monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
    args = CopilotIntegration().build_exec_args("p")
    assert args[0] == _copilot_executable()
 def test_executable_env_var_copilot_dispatch_command(monkeypatch):
    """CopilotIntegration.dispatch_command honours the executable env var."""
    import subprocess
    from specify_cli.integrations.copilot import CopilotIntegration
    capture = _RunCapture()
    monkeypatch.setattr(subprocess, "run", capture)
    monkeypatch.setenv("SPECKIT_INTEGRATION_COPILOT_EXECUTABLE", "/opt/copilot")
    monkeypatch.setenv("SPECKIT_COPILOT_ALLOW_ALL_TOOLS", "0")
    CopilotIntegration().dispatch_command("speckit.plan", args="body", stream=False)
    assert capture.captured_args is not None
    assert capture.captured_args[0] == "/opt/copilot"
 def test_executable_and_extra_args_both_honoured(monkeypatch):
    """Both the executable override and extra args env vars can be set
    simultaneously — they are independent hooks."""
    monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXECUTABLE", "/opt/claude")
    monkeypatch.setenv(
        "SPECKIT_INTEGRATION_CLAUDE_EXTRA_ARGS", "--dangerously-skip-permissions"
    )
    args = _ClaudeStub().build_exec_args("hello", model="sonnet")
    assert args == [
        "/opt/claude",
        "-p",
        "hello",
        "--dangerously-skip-permissions",
        "--model",
        "sonnet",
        "--output-format",
        "json",
    ]
--- a/tests/integrations/test_integration_agy.py
+++ b/tests/integrations/test_integration_agy.py
@@ -1,7 +1,5 @@
 """Tests for AgyIntegration (Antigravity)."""
 from specify_cli.integrations import get_integration
 from .test_integration_base_skills import SkillsIntegrationTests
@@ -14,21 +12,10 @@ class TestAgyIntegration(SkillsIntegrationTests):
    def test_options_include_skills_flag(self):
        """Override inherited test: AgyIntegration should not expose a --skills flag because .agents/ is its only layout."""
        from specify_cli.integrations import get_integration
        i = get_integration(self.KEY)
        skills_opts = [o for o in i.options() if o.name == "--skills"]
        assert len(skills_opts) == 0
    def test_requires_cli_is_true(self):
        """agy is a CLI tool; requires_cli must be True."""
        i = get_integration(self.KEY)
        assert i.config["requires_cli"] is True
    def test_install_url_is_set(self):
        """install_url must point to the official installation page."""
        i = get_integration(self.KEY)
        assert i.config["install_url"] == "https://antigravity.google/"
 class TestAgyAutoPromote:
    """--ai agy auto-promotes to integration path."""
@@ -39,7 +26,7 @@ class TestAgyAutoPromote:
        runner = CliRunner()
        target = tmp_path / "test-proj"
-        result = runner.invoke(app, ["init", str(target), "--ai", "agy", "--no-git", "--script", "sh", "--ignore-agent-tools"])
+        result = runner.invoke(app, ["init", str(target), "--ai", "agy", "--no-git", "--script", "sh"])
        assert result.exit_code == 0, f"init --ai agy failed: {result.output}"
        assert (target / ".agents" / "skills" / "speckit-plan" / "SKILL.md").exists()
@@ -49,87 +36,10 @@ class TestAgyAutoPromote:
        from typer.testing import CliRunner
        from specify_cli import app
-        # Click >= 8.2 separates stdout and stderr natively
+        # Click >= 8.2 separates stdout and stderr natively, mix_stderr is removed
        runner = CliRunner()
        target = tmp_path / "test-proj2"
-        result = runner.invoke(app, ["init", str(target), "--ai", "agy", "--no-git", "--script", "sh", "--ignore-agent-tools"])
+        result = runner.invoke(app, ["init", str(target), "--ai", "agy", "--no-git", "--script", "sh"])
        assert result.exit_code == 0
        assert "Warning: The .agents/ layout requires Antigravity v1.20.5 or newer" in result.stderr
 class TestAgyBuildExecArgs:
    """agy non-interactive execution argument building."""
    def test_build_exec_args_returns_print_command(self):
        """build_exec_args should return ['agy', '--print', prompt]."""
        from specify_cli.integrations import get_integration
        i = get_integration("agy")
        result = i.build_exec_args("describe my feature")
        assert result == ["agy", "--print", "describe my feature"]
    def test_build_exec_args_ignores_model(self):
        """agy does not support --model; model param must be ignored."""
        from specify_cli.integrations import get_integration
        i = get_integration("agy")
        result = i.build_exec_args("my prompt", model="gemini-pro")
        assert result == ["agy", "--print", "my prompt"]
    def test_build_exec_args_ignores_output_json(self):
        """agy does not support JSON output; output_json param must be ignored."""
        from specify_cli.integrations import get_integration
        i = get_integration("agy")
        result = i.build_exec_args("my prompt", output_json=False)
        assert result == ["agy", "--print", "my prompt"]
 class TestAgyHookCommandNote:
    """Verify dot-to-hyphen normalization note is injected into hook sections."""
    def test_hook_note_injected_in_skills_with_hooks(self, tmp_path):
        """Skills with hook sections should contain the normalization note."""
        from specify_cli.integrations import get_integration
        from specify_cli.integrations.manifest import IntegrationManifest
        i = get_integration("agy")
        m = IntegrationManifest("agy", tmp_path)
        i.setup(tmp_path, m, script_type="sh")
        specify_skill = tmp_path / ".agents/skills/speckit-specify/SKILL.md"
        assert specify_skill.exists()
        content = specify_skill.read_text(encoding="utf-8")
        assert "replace dots" in content, (
            "speckit-specify should have dot-to-hyphen hook note"
        )
    def test_hook_note_not_in_skills_without_hooks(self):
        """Skills without hook sections should not get the note."""
        from specify_cli.integrations.agy import AgyIntegration
        content = "---\nname: test\ndescription: test\n---\n\nNo hooks here.\n"
        result = AgyIntegration._inject_hook_command_note(content)
        assert "replace dots" not in result
    def test_hook_note_idempotent(self):
        """Injecting the note twice must not duplicate it."""
        from specify_cli.integrations.agy import AgyIntegration
        content = (
            "---\nname: test\n---\n\n"
            "- For each executable hook, output the following based on its flag:\n"
        )
        once = AgyIntegration._inject_hook_command_note(content)
        twice = AgyIntegration._inject_hook_command_note(once)
        assert once == twice, "Hook note injection should be idempotent"
    def test_hook_note_preserves_indentation(self):
        """The injected note must match the indentation of the target line."""
        from specify_cli.integrations.agy import AgyIntegration
        content = (
            "---\nname: test\n---\n\n"
            "   - For each executable hook, output the following\n"
        )
        result = AgyIntegration._inject_hook_command_note(content)
        lines = result.splitlines()
        note_line = [ln for ln in lines if "replace dots" in ln][0]
        assert note_line.startswith("   "), "Note should preserve indentation"
--- a/tests/integrations/test_integration_base_markdown.py
+++ b/tests/integrations/test_integration_base_markdown.py
@@ -226,8 +226,8 @@ class MarkdownIntegrationTests:
        assert len(commands) > 0, f"No command files in {cmd_dir}"
    def test_init_options_includes_context_file(self, tmp_path):
-        """agent-context extension config must include context_file for the active integration."""
+        """init-options.json must include context_file for the active integration."""
-        import yaml
+        import json
        from typer.testing import CliRunner
        from specify_cli import app
@@ -243,19 +243,17 @@ class MarkdownIntegrationTests:
        finally:
            os.chdir(old_cwd)
        assert result.exit_code == 0
-        ext_cfg_path = project / ".specify" / "extensions" / "agent-context" / "agent-context-config.yml"
+        opts = json.loads((project / ".specify" / "init-options.json").read_text())
        ext_cfg = yaml.safe_load(ext_cfg_path.read_text(encoding="utf-8")) if ext_cfg_path.exists() else {}
        i = get_integration(self.KEY)
-        assert ext_cfg.get("context_file") == i.context_file, (
+        assert opts.get("context_file") == i.context_file, (
-            f"Expected context_file={i.context_file!r}, got {ext_cfg.get('context_file')!r}"
+            f"Expected context_file={i.context_file!r}, got {opts.get('context_file')!r}"
        )
    # -- Complete file inventory ------------------------------------------
    COMMAND_STEMS = [
-        "agent-context.update",
+        "analyze", "checklist", "clarify", "constitution",
-        "analyze", "clarify", "constitution", "implement",
+        "implement", "plan", "specify", "tasks", "taskstoissues",
        "plan", "checklist", "specify", "tasks", "taskstoissues",
    ]
    def _expected_files(self, script_variant: str) -> list[str]:
@@ -269,10 +267,10 @@ class MarkdownIntegrationTests:
            files.append(f"{cmd_dir}/speckit.{stem}.md")
        # Framework files
-        files.append(".specify/integration.json")
+        files.append(f".specify/integration.json")
-        files.append(".specify/init-options.json")
+        files.append(f".specify/init-options.json")
        files.append(f".specify/integrations/{self.KEY}.manifest.json")
-        files.append(".specify/integrations/speckit.manifest.json")
+        files.append(f".specify/integrations/speckit.manifest.json")
        if script_variant == "sh":
            for name in ["check-prerequisites.sh", "common.sh", "create-new-feature.sh",
@@ -293,16 +291,6 @@ class MarkdownIntegrationTests:
        files.append(".specify/workflows/speckit/workflow.yml")
        files.append(".specify/workflows/workflow-registry.json")
        # Bundled agent-context extension
        files.append(".specify/extensions.yml")
        files.append(".specify/extensions/.registry")
        files.append(".specify/extensions/agent-context/README.md")
        files.append(".specify/extensions/agent-context/agent-context-config.yml")
        files.append(".specify/extensions/agent-context/commands/speckit.agent-context.update.md")
        files.append(".specify/extensions/agent-context/extension.yml")
        files.append(".specify/extensions/agent-context/scripts/bash/update-agent-context.sh")
        files.append(".specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1")
        # Agent context file (if set)
        if i.context_file:
            files.append(i.context_file)
--- a/tests/integrations/test_integration_base_skills.py
+++ b/tests/integrations/test_integration_base_skills.py
@@ -100,8 +100,8 @@ class SkillsIntegrationTests:
        skill_files = [f for f in created if "scripts" not in f.parts]
        expected_commands = {
-            "analyze", "clarify", "constitution", "implement",
+            "analyze", "checklist", "clarify", "constitution",
-            "plan", "checklist", "specify", "tasks", "taskstoissues",
+            "implement", "plan", "specify", "tasks", "taskstoissues",
        }
        # Derive command names from the skill directory names
@@ -176,39 +176,6 @@ class SkillsIntegrationTests:
                f"skills agents must use /speckit-<name>"
            )
    def test_hook_sections_explain_dotted_command_conversion(self, tmp_path):
        """Generated skills with hook sections must explain dotted command conversion."""
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        i.setup(tmp_path, m)
        specify_skill = i.skills_dest(tmp_path) / "speckit-specify" / "SKILL.md"
        assert specify_skill.exists()
        content = specify_skill.read_text(encoding="utf-8")
        assert "replace dots" in content, (
            "speckit-specify should explain dotted hook command conversion"
        )
        assert content.count("replace dots") == content.count(
            "- For each executable hook, output the following"
        )
    def test_hook_note_injected_for_each_instruction_independently(self):
        """Existing hook notes should not suppress later missing notes."""
        content = (
            "---\n"
            "name: test\n"
            "---\n\n"
            "- When constructing slash commands from hook command names, "
            "replace dots (`.`) with hyphens (`-`). "
            "For example, `speckit.git.commit` → `/speckit-git-commit`.\n"
            "- For each executable hook, output the following first block:\n"
            "\n"
            "- For each executable hook, output the following second block:\n"
        )
        result = SkillsIntegration._inject_hook_command_note(content)
        assert result.count("replace dots (`.`) with hyphens") == 2
    def test_skill_body_has_content(self, tmp_path):
        """Each SKILL.md body should contain template content after the frontmatter."""
        i = get_integration(self.KEY)
@@ -357,8 +324,8 @@ class SkillsIntegrationTests:
        assert skills_dir.is_dir(), f"Skills directory {skills_dir} not created"
    def test_init_options_includes_context_file(self, tmp_path):
-        """agent-context extension config must include context_file for the active integration."""
+        """init-options.json must include context_file for the active integration."""
-        import yaml
+        import json
        from typer.testing import CliRunner
        from specify_cli import app
@@ -374,11 +341,10 @@ class SkillsIntegrationTests:
        finally:
            os.chdir(old_cwd)
        assert result.exit_code == 0
-        ext_cfg_path = project / ".specify" / "extensions" / "agent-context" / "agent-context-config.yml"
+        opts = json.loads((project / ".specify" / "init-options.json").read_text())
        ext_cfg = yaml.safe_load(ext_cfg_path.read_text(encoding="utf-8")) if ext_cfg_path.exists() else {}
        i = get_integration(self.KEY)
-        assert ext_cfg.get("context_file") == i.context_file, (
+        assert opts.get("context_file") == i.context_file, (
-            f"Expected context_file={i.context_file!r}, got {ext_cfg.get('context_file')!r}"
+            f"Expected context_file={i.context_file!r}, got {opts.get('context_file')!r}"
        )
    # -- IntegrationOption ------------------------------------------------
@@ -393,8 +359,8 @@ class SkillsIntegrationTests:
    # -- Complete file inventory ------------------------------------------
    _SKILL_COMMANDS = [
-        "analyze", "clarify", "constitution", "implement",
+        "analyze", "checklist", "clarify", "constitution",
-        "plan", "checklist", "specify", "tasks", "taskstoissues",
+        "implement", "plan", "specify", "tasks", "taskstoissues",
    ]
    def _expected_files(self, script_variant: str) -> list[str]:
@@ -403,11 +369,9 @@ class SkillsIntegrationTests:
        skills_prefix = i.config["folder"].rstrip("/") + "/" + i.config.get("commands_subdir", "skills")
        files = []
-        # Skill files (core commands)
+        # Skill files
        for cmd in self._SKILL_COMMANDS:
            files.append(f"{skills_prefix}/speckit-{cmd}/SKILL.md")
        # Extension-installed skill (agent-context)
        files.append(f"{skills_prefix}/speckit-agent-context-update/SKILL.md")
        # Integration metadata
        files += [
            ".specify/init-options.json",
@@ -446,15 +410,6 @@ class SkillsIntegrationTests:
            ".specify/workflows/speckit/workflow.yml",
            ".specify/workflows/workflow-registry.json",
        ]
        # Bundled agent-context extension
        files.append(".specify/extensions.yml")
        files.append(".specify/extensions/.registry")
        files.append(".specify/extensions/agent-context/README.md")
        files.append(".specify/extensions/agent-context/agent-context-config.yml")
        files.append(".specify/extensions/agent-context/commands/speckit.agent-context.update.md")
        files.append(".specify/extensions/agent-context/extension.yml")
        files.append(".specify/extensions/agent-context/scripts/bash/update-agent-context.sh")
        files.append(".specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1")
        # Agent context file (if set)
        if i.context_file:
            files.append(i.context_file)
--- a/tests/integrations/test_integration_base_toml.py
+++ b/tests/integrations/test_integration_base_toml.py
@@ -457,8 +457,8 @@ class TomlIntegrationTests:
        assert len(commands) > 0, f"No command files in {cmd_dir}"
    def test_init_options_includes_context_file(self, tmp_path):
-        """agent-context extension config must include context_file for the active integration."""
+        """init-options.json must include context_file for the active integration."""
-        import yaml
+        import json
        from typer.testing import CliRunner
        from specify_cli import app
@@ -474,23 +474,21 @@ class TomlIntegrationTests:
        finally:
            os.chdir(old_cwd)
        assert result.exit_code == 0
-        ext_cfg_path = project / ".specify" / "extensions" / "agent-context" / "agent-context-config.yml"
+        opts = json.loads((project / ".specify" / "init-options.json").read_text())
        ext_cfg = yaml.safe_load(ext_cfg_path.read_text(encoding="utf-8")) if ext_cfg_path.exists() else {}
        i = get_integration(self.KEY)
-        assert ext_cfg.get("context_file") == i.context_file, (
+        assert opts.get("context_file") == i.context_file, (
-            f"Expected context_file={i.context_file!r}, got {ext_cfg.get('context_file')!r}"
+            f"Expected context_file={i.context_file!r}, got {opts.get('context_file')!r}"
        )
    # -- Complete file inventory ------------------------------------------
    COMMAND_STEMS = [
        "agent-context.update",
        "analyze",
        "checklist",
        "clarify",
        "constitution",
        "implement",
        "plan",
        "checklist",
        "specify",
        "tasks",
        "taskstoissues",
@@ -545,16 +543,6 @@ class TomlIntegrationTests:
        files.append(".specify/workflows/speckit/workflow.yml")
        files.append(".specify/workflows/workflow-registry.json")
        # Bundled agent-context extension
        files.append(".specify/extensions.yml")
        files.append(".specify/extensions/.registry")
        files.append(".specify/extensions/agent-context/README.md")
        files.append(".specify/extensions/agent-context/agent-context-config.yml")
        files.append(".specify/extensions/agent-context/commands/speckit.agent-context.update.md")
        files.append(".specify/extensions/agent-context/extension.yml")
        files.append(".specify/extensions/agent-context/scripts/bash/update-agent-context.sh")
        files.append(".specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1")
        # Agent context file (if set)
        if i.context_file:
            files.append(i.context_file)
--- a/tests/integrations/test_integration_base_yaml.py
+++ b/tests/integrations/test_integration_base_yaml.py
@@ -152,7 +152,7 @@ class YamlIntegrationTests:
            content = f.read_text(encoding="utf-8")
            # Strip trailing source comment before parsing
            lines = content.split("\n")
-            yaml_lines = [ln for ln in lines if not ln.startswith("# Source:")]
+            yaml_lines = [l for l in lines if not l.startswith("# Source:")]
            try:
                parsed = yaml.safe_load("\n".join(yaml_lines))
            except Exception as exc:
@@ -183,7 +183,7 @@ class YamlIntegrationTests:
        content = cmd_files[0].read_text(encoding="utf-8")
        # Strip source comment for parsing
        lines = content.split("\n")
-        yaml_lines = [ln for ln in lines if not ln.startswith("# Source:")]
+        yaml_lines = [l for l in lines if not l.startswith("# Source:")]
        parsed = yaml.safe_load("\n".join(yaml_lines))
        assert "description:" not in parsed["prompt"]
@@ -336,8 +336,8 @@ class YamlIntegrationTests:
        assert len(commands) > 0, f"No command files in {cmd_dir}"
    def test_init_options_includes_context_file(self, tmp_path):
-        """agent-context extension config must include context_file for the active integration."""
+        """init-options.json must include context_file for the active integration."""
-        import yaml
+        import json
        from typer.testing import CliRunner
        from specify_cli import app
@@ -353,23 +353,21 @@ class YamlIntegrationTests:
        finally:
            os.chdir(old_cwd)
        assert result.exit_code == 0
-        ext_cfg_path = project / ".specify" / "extensions" / "agent-context" / "agent-context-config.yml"
+        opts = json.loads((project / ".specify" / "init-options.json").read_text())
        ext_cfg = yaml.safe_load(ext_cfg_path.read_text(encoding="utf-8")) if ext_cfg_path.exists() else {}
        i = get_integration(self.KEY)
-        assert ext_cfg.get("context_file") == i.context_file, (
+        assert opts.get("context_file") == i.context_file, (
-            f"Expected context_file={i.context_file!r}, got {ext_cfg.get('context_file')!r}"
+            f"Expected context_file={i.context_file!r}, got {opts.get('context_file')!r}"
        )
    # -- Complete file inventory ------------------------------------------
    COMMAND_STEMS = [
        "agent-context.update",
        "analyze",
        "checklist",
        "clarify",
        "constitution",
        "implement",
        "plan",
        "checklist",
        "specify",
        "tasks",
        "taskstoissues",
@@ -424,16 +422,6 @@ class YamlIntegrationTests:
        files.append(".specify/workflows/speckit/workflow.yml")
        files.append(".specify/workflows/workflow-registry.json")
        # Bundled agent-context extension
        files.append(".specify/extensions.yml")
        files.append(".specify/extensions/.registry")
        files.append(".specify/extensions/agent-context/README.md")
        files.append(".specify/extensions/agent-context/agent-context-config.yml")
        files.append(".specify/extensions/agent-context/commands/speckit.agent-context.update.md")
        files.append(".specify/extensions/agent-context/extension.yml")
        files.append(".specify/extensions/agent-context/scripts/bash/update-agent-context.sh")
        files.append(".specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1")
        # Agent context file (if set)
        if i.context_file:
            files.append(i.context_file)
--- a/tests/integrations/test_integration_claude.py
+++ b/tests/integrations/test_integration_claude.py
@@ -3,13 +3,12 @@
 import codecs
 import json
 import os
 from pathlib import Path
 from unittest.mock import patch
 import yaml
 from specify_cli.integrations import INTEGRATION_REGISTRY, get_integration
-from specify_cli.integrations.base import IntegrationBase, SkillsIntegration
+from specify_cli.integrations.base import IntegrationBase
 from specify_cli.integrations.claude import ARGUMENT_HINTS
 from specify_cli.integrations.manifest import IntegrationManifest
@@ -488,8 +487,8 @@ class TestClaudeDisableModelInvocation:
        assert "disable-model-invocation" not in fm
        assert "user-invocable" not in fm
-    def test_skills_default_post_process_preserves_content_without_hooks(self, tmp_path):
+    def test_skills_default_post_process_is_identity(self, tmp_path):
-        """SkillsIntegration agents without an override preserve non-hook content."""
+        """SkillsIntegration agents without an override leave content unchanged."""
        # ``agy`` is a plain SkillsIntegration with no post-process override,
        # so it stands in for the base-class default behavior.
        agy = get_integration("agy")
@@ -506,7 +505,7 @@ class TestClaudeHookCommandNote:
        """Skills that have hook sections should get the normalization note."""
        i = get_integration("claude")
        m = IntegrationManifest("claude", tmp_path)
-        i.setup(tmp_path, m, script_type="sh")
+        created = i.setup(tmp_path, m, script_type="sh")
        specify_skill = tmp_path / ".claude/skills/speckit-specify/SKILL.md"
        assert specify_skill.exists()
        content = specify_skill.read_text(encoding="utf-8")
@@ -517,54 +516,35 @@ class TestClaudeHookCommandNote:
    def test_hook_note_not_in_skills_without_hooks(self, tmp_path):
        """Skills without hook sections should not get the note."""
        from specify_cli.integrations.claude import ClaudeIntegration
        content = "---\nname: test\ndescription: test\n---\n\nNo hooks here.\n"
-        result = SkillsIntegration._inject_hook_command_note(content)
+        result = ClaudeIntegration._inject_hook_command_note(content)
        assert "replace dots" not in result
    def test_hook_note_idempotent(self, tmp_path):
        """Injecting the note twice should not duplicate it."""
        from specify_cli.integrations.claude import ClaudeIntegration
        content = (
            "---\nname: test\n---\n\n"
            "- For each executable hook, output the following based on its flag:\n"
        )
-        once = SkillsIntegration._inject_hook_command_note(content)
+        once = ClaudeIntegration._inject_hook_command_note(content)
-        twice = SkillsIntegration._inject_hook_command_note(once)
+        twice = ClaudeIntegration._inject_hook_command_note(once)
        assert once == twice, "Hook note injection should be idempotent"
    def test_hook_note_fills_missing_repeated_instructions(self, tmp_path):
        """Already-noted hook sections should not suppress later sections."""
        from specify_cli.integrations.base import _HOOK_COMMAND_NOTE
        content = (
            "---\nname: test\n---\n\n"
            f"{_HOOK_COMMAND_NOTE}"
            "- For each executable hook, output the following based on its flag:\n"
            "\n"
            "  - For each executable hook, output the following based on its flag:\n"
        )
        result = SkillsIntegration._inject_hook_command_note(content)
        assert result.count("replace dots (`.`) with hyphens") == 2
    def test_hook_note_not_suppressed_by_unrelated_phrase(self, tmp_path):
        """Unrelated text should not trip the hook-note idempotence guard."""
        content = (
            "---\nname: test\n---\n\n"
            "This paragraph says replace dots in a different context.\n"
            "- For each executable hook, output the following based on its flag:\n"
        )
        result = SkillsIntegration._inject_hook_command_note(content)
        assert "This paragraph says replace dots in a different context." in result
        assert result.count("replace dots (`.`) with hyphens") == 1
    def test_hook_note_preserves_indentation(self, tmp_path):
        """The injected note should match the indentation of the target line."""
        from specify_cli.integrations.claude import ClaudeIntegration
        content = (
            "---\nname: test\n---\n\n"
            "   - For each executable hook, output the following\n"
        )
-        result = SkillsIntegration._inject_hook_command_note(content)
+        result = ClaudeIntegration._inject_hook_command_note(content)
        lines = result.splitlines()
-        note_line = [line for line in lines if "replace dots" in line][0]
+        note_line = [l for l in lines if "replace dots" in l][0]
        assert note_line.startswith("   "), "Note should preserve indentation"
    def test_post_process_injects_all_claude_flags(self):
@@ -578,204 +558,3 @@ class TestClaudeHookCommandNote:
        assert "user-invocable: true" in result
        assert "disable-model-invocation: false" in result
        assert "replace dots" in result
 class TestSpeckitManifestRecordsSkippedFiles:
    """Regression test for issue #2107.
    ``install_shared_infra`` must record every shared-infrastructure file
    under ``.specify/`` in ``speckit.manifest.json``, including files that
    were *skipped* because they already existed on disk and ``force=False``.
    Before the fix, the skip branches in the scripts and templates loops
    appended to ``skipped_files`` without calling ``manifest.record_existing``.
    So when ``install_shared_infra`` ran with a fresh (or lost) manifest
    against an already-populated ``.specify/`` tree, every file went down the
    skip path, ``planned_copies`` and ``planned_templates`` stayed empty, and
    ``manifest.save()`` wrote an empty ``files`` field — leaving the
    integration believing nothing was installed.
    Reproduction (without the fix) using ``install_shared_infra`` directly:
        install_shared_infra(p, "sh", ..., force=False)   # 1st run → 10 files
        (p / ".specify/integrations/speckit.manifest.json").unlink()
        install_shared_infra(p, "sh", ..., force=False)   # 2nd run → 0 files
                                                          # ^^ BUG: empty
    """
    def _read_manifest_files(self, project_path: Path) -> dict:
        manifest_path = (
            project_path / ".specify" / "integrations" / "speckit.manifest.json"
        )
        assert manifest_path.exists(), (
            f"speckit.manifest.json not written at {manifest_path}"
        )
        data = json.loads(manifest_path.read_text(encoding="utf-8"))
        # ``IntegrationManifest.save`` serialises a ``files`` dict — assert
        # the schema explicitly so a regression to a different key (e.g.
        # the internal ``_files`` attribute name) fails loudly instead of
        # being masked by a silent fallback.
        assert isinstance(data, dict), (
            f"manifest root is not a dict, got {type(data).__name__}"
        )
        assert "files" in data, (
            f"manifest missing 'files' key, got keys: {sorted(data.keys())}"
        )
        files = data["files"]
        assert isinstance(files, dict), (
            f"manifest 'files' is not a dict, got {type(files).__name__}"
        )
        return files
    def test_install_shared_infra_records_skipped_files(self, tmp_path):
        """With ``force=False`` and ``.specify/`` already populated, the
        manifest must still record every file — the skip branches are not
        allowed to drop files from the manifest."""
        from rich.console import Console
        from specify_cli.shared_infra import install_shared_infra
        # Resolve the project's own packaged sources by walking up from this
        # test file to the repo root (which contains ``scripts/`` and
        # ``templates/`` that ``shared_scripts_source`` looks for).
        repo_root = Path(__file__).resolve().parents[2]
        console = Console(quiet=True)
        # First run — fresh project, manifest gets populated normally.
        install_shared_infra(
            tmp_path,
            "sh",
            version="0.0.0",
            core_pack=None,
            repo_root=repo_root,
            console=console,
            force=False,
        )
        first_files = self._read_manifest_files(tmp_path)
        assert first_files, "first install produced an empty manifest"
        # Simulate a lost manifest while ``.specify/`` is still on disk
        # (e.g. the manifest was deleted, corrupted, or the layout was
        # extracted out-of-band).
        manifest_path = (
            tmp_path / ".specify" / "integrations" / "speckit.manifest.json"
        )
        manifest_path.unlink()
        # Second run — every file already exists, so every iteration takes
        # the skip branch. With the fix, those files are still recorded.
        install_shared_infra(
            tmp_path,
            "sh",
            version="0.0.0",
            core_pack=None,
            repo_root=repo_root,
            console=console,
            force=False,
        )
        second_files = self._read_manifest_files(tmp_path)
        assert second_files, (
            "speckit.manifest.json files dict is empty after install with "
            "skipped files (issue #2107) — every file went down the skip "
            "branch but none were recorded"
        )
        # The recovered manifest must cover everything the first run tracked.
        missing = set(first_files) - set(second_files)
        assert not missing, (
            f"these files were tracked on the first install but missing after "
            f"the skipped-files re-install: {sorted(missing)[:5]}"
        )
    def test_install_shared_infra_handles_directory_at_script_destination(
        self, tmp_path
    ):
        """A non-file (directory) at a script's destination must NOT crash
        ``install_shared_infra`` and must NOT be recorded in the manifest —
        the path still appears in the user-visible skipped-paths warning.
        """
        from io import StringIO
        from rich.console import Console
        from specify_cli.shared_infra import install_shared_infra
        repo_root = Path(__file__).resolve().parents[2]
        output = StringIO()
        console = Console(file=output, force_terminal=False, width=200)
        # Pre-create the .specify/scripts/bash tree, then plant a directory
        # where a script file is expected so the skip branch hits a
        # non-regular-file path.
        bash_dir = tmp_path / ".specify" / "scripts" / "bash"
        bash_dir.mkdir(parents=True)
        (bash_dir / "common.sh").mkdir()  # collision: dir where file expected
        # Must not crash.
        install_shared_infra(
            tmp_path,
            "sh",
            version="0.0.0",
            core_pack=None,
            repo_root=repo_root,
            console=console,
            force=False,
        )
        files = self._read_manifest_files(tmp_path)
        assert ".specify/scripts/bash/common.sh" not in files, (
            "directory at script dst must not be recorded in the manifest"
        )
        text = output.getvalue()
        assert "common.sh" in text, (
            "directory-at-script-dst path must surface in the skipped warning"
        )
    def test_install_shared_infra_handles_directory_at_template_destination(
        self, tmp_path
    ):
        """Symmetric coverage for the templates loop: a directory at a
        template's destination must NOT crash install nor be recorded."""
        from io import StringIO
        from rich.console import Console
        from specify_cli.shared_infra import install_shared_infra
        repo_root = Path(__file__).resolve().parents[2]
        output = StringIO()
        console = Console(file=output, force_terminal=False, width=200)
        templates_dir = tmp_path / ".specify" / "templates"
        templates_dir.mkdir(parents=True)
        src_templates = repo_root / "templates"
        real_template = next(
            (
                p.name
                for p in src_templates.iterdir()
                if p.is_file()
                and not p.name.startswith(".")
                and p.name != "vscode-settings.json"
            ),
            None,
        )
        assert real_template, (
            "no real template found in repo to collide against"
        )
        (templates_dir / real_template).mkdir()  # collision
        install_shared_infra(
            tmp_path,
            "sh",
            version="0.0.0",
            core_pack=None,
            repo_root=repo_root,
            console=console,
            force=False,
        )
        files = self._read_manifest_files(tmp_path)
        template_rel = f".specify/templates/{real_template}"
        assert template_rel not in files, (
            "directory at template dst must not be recorded in manifest"
        )
        text = output.getvalue()
        assert real_template in text, (
            "directory-at-template-dst path must surface in the skipped warning"
        )
--- a/tests/integrations/test_integration_cline.py
+++ b/tests/integrations/test_integration_cline.py
@@ -1,223 +0,0 @@
 """Tests for ClineIntegration."""
 import os
 import pytest
 from specify_cli.integrations import get_integration
 from specify_cli.integrations.cline import format_cline_command_name
 from .test_integration_base_markdown import MarkdownIntegrationTests
 class TestClineCommandNameFormatter:
    """Test the Cline command name formatter."""
    def test_simple_name_without_prefix(self):
        """Test formatting a simple name without 'speckit.' prefix."""
        assert format_cline_command_name("plan") == "speckit-plan"
        assert format_cline_command_name("tasks") == "speckit-tasks"
        assert format_cline_command_name("specify") == "speckit-specify"
    def test_name_with_speckit_prefix(self):
        """Test formatting a name that already has 'speckit.' prefix."""
        assert format_cline_command_name("speckit.plan") == "speckit-plan"
        assert format_cline_command_name("speckit.tasks") == "speckit-tasks"
    def test_extension_command_name(self):
        """Test formatting extension command names with dots."""
        assert (
            format_cline_command_name("speckit.my-extension.example")
            == "speckit-my-extension-example"
        )
        assert (
            format_cline_command_name("my-extension.example")
            == "speckit-my-extension-example"
        )
    def test_idempotent_already_hyphenated(self):
        """Test that already-hyphenated names are returned unchanged (idempotent)."""
        assert format_cline_command_name("speckit-plan") == "speckit-plan"
        assert (
            format_cline_command_name("speckit-my-extension-example")
            == "speckit-my-extension-example"
        )
 class TestClineIntegration(MarkdownIntegrationTests):
    KEY = "cline"
    FOLDER = ".clinerules/"
    COMMANDS_SUBDIR = "workflows"
    REGISTRAR_DIR = ".clinerules/workflows"
    CONTEXT_FILE = ".clinerules/specify-rules.md"
    @pytest.mark.parametrize(
        "cmd_name, expected_filename",
        [
            ("plan", "speckit-plan.md"),
            ("speckit.plan", "speckit-plan.md"),
            ("speckit.git.commit", "speckit-git-commit.md"),
            ("speckit", "speckit-speckit.md"),
            ("speckitfoo", "speckit-speckitfoo.md"),
        ],
    )
    def test_cline_command_filename(self, cmd_name, expected_filename):
        """Verify Cline uses hyphenated filenames."""
        cline = get_integration("cline")
        assert cline.command_filename(cmd_name) == expected_filename
    def test_cline_invoke_separator(self):
        """Verify Cline uses hyphen as invoke separator."""
        cline = get_integration("cline")
        assert cline.invoke_separator == "-"
        assert cline.registrar_config["invoke_separator"] == "-"
    def test_cline_name_injection_and_formatting(self):
        """Verify Cline has inject_name and format_name configured."""
        cline = get_integration("cline")
        assert cline.registrar_config["inject_name"] is True
        assert cline.registrar_config["format_name"] == format_cline_command_name
    def test_cline_handoff_rewrite(self):
        """Verify Cline rewrites agent: speckit.foo to agent: speckit-foo."""
        cline = get_integration("cline")
        content = "---\nagent: speckit.plan\n---\n"
        rewritten = cline._rewrite_handoff_references(content)
        assert rewritten == "---\nagent: speckit-plan\n---\n"
    def test_cline_hook_instruction_injection(self):
        """Verify Cline injects the dot-to-hyphen note for hooks."""
        cline = get_integration("cline")
        content = "- For each executable hook, output the following:\n"
        injected = cline._inject_hook_command_note(content)
        assert "replace dots (`.`) with hyphens (`-`)" in injected
        assert "- For each executable hook, output the following:" in injected
    # -- Overrides for MarkdownIntegrationTests ---------------------------
    def test_setup_creates_files(self, tmp_path):
        from specify_cli.integrations.manifest import IntegrationManifest
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        assert len(created) > 0
        cmd_files = [
            f
            for f in created
            if "scripts" not in f.parts
            and f.suffix == ".md"
            and f.name != i.context_file
        ]
        for f in cmd_files:
            assert f.exists()
            assert f.name.startswith("speckit-")
            assert f.name.endswith(".md")
        specify_file = next(
            (f for f in cmd_files if f.name == "speckit-specify.md"), None
        )
        assert specify_file is not None
        specify_contents = specify_file.read_text(encoding="utf-8")
        assert "/speckit-plan" in specify_contents
        assert "/speckit.plan" not in specify_contents
    def test_integration_flag_creates_files(self, tmp_path):
        from typer.testing import CliRunner
        from specify_cli import app
        project = tmp_path / f"int-{self.KEY}"
        project.mkdir()
        old_cwd = os.getcwd()
        try:
            os.chdir(project)
            runner = CliRunner()
            result = runner.invoke(
                app,
                [
                    "init",
                    "--here",
                    "--integration",
                    self.KEY,
                    "--script",
                    "sh",
                    "--no-git",
                    "--ignore-agent-tools",
                ],
                catch_exceptions=False,
            )
        finally:
            os.chdir(old_cwd)
        assert result.exit_code == 0
        i = get_integration(self.KEY)
        cmd_dir = i.commands_dest(project)
        assert cmd_dir.is_dir()
        commands = sorted(cmd_dir.glob("speckit-*"))
        assert len(commands) > 0
    def _expected_files(self, script_variant: str) -> list[str]:
        """Override to expect hyphenated speckit- prefix."""
        i = get_integration(self.KEY)
        cmd_dir = i.registrar_config["dir"]
        files = []
        # Command files
        for stem in (
            self.COMMANDS_SUBDIR_STEMS
            if hasattr(self, "COMMANDS_SUBDIR_STEMS")
            else self.COMMAND_STEMS
        ):
            files.append(f"{cmd_dir}/speckit-{stem.replace('.', '-')}.md")
        # Framework files
        files.append(".specify/integration.json")
        files.append(".specify/init-options.json")
        files.append(f".specify/integrations/{self.KEY}.manifest.json")
        files.append(".specify/integrations/speckit.manifest.json")
        if script_variant == "sh":
            for name in [
                "check-prerequisites.sh",
                "common.sh",
                "create-new-feature.sh",
                "setup-plan.sh",
                "setup-tasks.sh",
            ]:
                files.append(f".specify/scripts/bash/{name}")
        else:
            for name in [
                "check-prerequisites.ps1",
                "common.ps1",
                "create-new-feature.ps1",
                "setup-plan.ps1",
                "setup-tasks.ps1",
            ]:
                files.append(f".specify/scripts/powershell/{name}")
        for name in [
            "checklist-template.md",
            "constitution-template.md",
            "plan-template.md",
            "spec-template.md",
            "tasks-template.md",
        ]:
            files.append(f".specify/templates/{name}")
        files.append(".specify/memory/constitution.md")
        # Bundled workflow
        files.append(".specify/workflows/speckit/workflow.yml")
        files.append(".specify/workflows/workflow-registry.json")
        # Bundled agent-context extension
        files.append(".specify/extensions.yml")
        files.append(".specify/extensions/.registry")
        files.append(".specify/extensions/agent-context/README.md")
        files.append(".specify/extensions/agent-context/agent-context-config.yml")
        files.append(".specify/extensions/agent-context/commands/speckit.agent-context.update.md")
        files.append(".specify/extensions/agent-context/extension.yml")
        files.append(".specify/extensions/agent-context/scripts/bash/update-agent-context.sh")
        files.append(".specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1")
        # Agent context file (if set)
        if i.context_file:
            files.append(i.context_file)
        return sorted(files)
--- a/tests/integrations/test_integration_codex.py
+++ b/tests/integrations/test_integration_codex.py
@@ -71,34 +71,6 @@ class TestCodexHookCommandNote:
        twice = CodexIntegration._inject_hook_command_note(once)
        assert once == twice, "Hook note injection should be idempotent"
    def test_hook_note_fills_missing_repeated_instructions(self):
        """Already-noted hook sections should not suppress later sections."""
        from specify_cli.integrations.base import _HOOK_COMMAND_NOTE
        from specify_cli.integrations.codex import CodexIntegration
        content = (
            "---\nname: test\n---\n\n"
            f"{_HOOK_COMMAND_NOTE}"
            "- For each executable hook, output the following based on its flag:\n"
            "\n"
            "  - For each executable hook, output the following based on its flag:\n"
        )
        result = CodexIntegration._inject_hook_command_note(content)
        assert result.count("replace dots (`.`) with hyphens") == 2
    def test_hook_note_not_suppressed_by_unrelated_phrase(self):
        """Unrelated text should not trip the hook-note idempotence guard."""
        from specify_cli.integrations.codex import CodexIntegration
        content = (
            "---\nname: test\n---\n\n"
            "This paragraph says replace dots in a different context.\n"
            "- For each executable hook, output the following based on its flag:\n"
        )
        result = CodexIntegration._inject_hook_command_note(content)
        assert "This paragraph says replace dots in a different context." in result
        assert result.count("replace dots (`.`) with hyphens") == 1
    def test_hook_note_preserves_indentation(self):
        """The injected note should match the indentation of the target line."""
        from specify_cli.integrations.codex import CodexIntegration
@@ -109,7 +81,7 @@ class TestCodexHookCommandNote:
        )
        result = CodexIntegration._inject_hook_command_note(content)
        lines = result.splitlines()
-        note_line = [line for line in lines if "replace dots" in line][0]
+        note_line = [l for l in lines if "replace dots" in l][0]
        assert note_line.startswith("   "), "Note should preserve indentation"
    def test_hook_note_when_instruction_is_final_line_without_newline(self):
@@ -130,11 +102,11 @@ class TestCodexHookCommandNote:
        result = CodexIntegration._inject_hook_command_note(content)
        lines = result.splitlines()
        note_line_idx = next(
-            i for i, line in enumerate(lines) if "replace dots" in line
+            i for i, l in enumerate(lines) if "replace dots" in l
        )
        instruction_line_idx = next(
-            i for i, line in enumerate(lines)
+            i for i, l in enumerate(lines)
-            if line.lstrip().startswith("- For each executable hook")
+            if l.lstrip().startswith("- For each executable hook")
        )
        assert note_line_idx < instruction_line_idx, (
            "Note must appear before the instruction"
--- a/tests/integrations/test_integration_copilot.py
+++ b/tests/integrations/test_integration_copilot.py
@@ -127,8 +127,8 @@ class TestCopilotIntegration:
        agent_files = sorted(agents_dir.glob("speckit.*.agent.md"))
        assert len(agent_files) == 9
        expected_commands = {
-            "analyze", "clarify", "constitution", "implement",
+            "analyze", "checklist", "clarify", "constitution",
-            "plan", "checklist", "specify", "tasks", "taskstoissues",
+            "implement", "plan", "specify", "tasks", "taskstoissues",
        }
        actual_commands = {f.name.removeprefix("speckit.").removesuffix(".agent.md") for f in agent_files}
        assert actual_commands == expected_commands
@@ -147,21 +147,6 @@ class TestCopilotIntegration:
            assert "__SPECKIT_COMMAND_" not in content, f"{agent_file.name} has unprocessed __SPECKIT_COMMAND_*__"
            assert "\nscripts:\n" not in content
    def test_specify_agent_resolves_active_spec_template(self, tmp_path):
        """Generated specify agent must not hardcode the core spec template."""
        from specify_cli.integrations.copilot import CopilotIntegration
        copilot = CopilotIntegration()
        m = IntegrationManifest("copilot", tmp_path)
        copilot.setup(tmp_path, m)
        specify_file = tmp_path / ".github" / "agents" / "speckit.specify.agent.md"
        content = specify_file.read_text(encoding="utf-8")
        assert "specify preset resolve spec-template" in content
        assert "resolved active `spec-template`" in content
        assert "Copy `.specify/templates/spec-template.md`" not in content
        assert "Load `.specify/templates/spec-template.md`" not in content
    def test_plan_references_correct_context_file(self, tmp_path):
        """The generated plan command must reference copilot's context file."""
        from specify_cli.integrations.copilot import CopilotIntegration
@@ -193,7 +178,6 @@ class TestCopilotIntegration:
        assert result.exit_code == 0
        actual = sorted(p.relative_to(project).as_posix() for p in project.rglob("*") if p.is_file())
        expected = sorted([
            ".github/agents/speckit.agent-context.update.agent.md",
            ".github/agents/speckit.analyze.agent.md",
            ".github/agents/speckit.checklist.agent.md",
            ".github/agents/speckit.clarify.agent.md",
@@ -203,7 +187,6 @@ class TestCopilotIntegration:
            ".github/agents/speckit.specify.agent.md",
            ".github/agents/speckit.tasks.agent.md",
            ".github/agents/speckit.taskstoissues.agent.md",
            ".github/prompts/speckit.agent-context.update.prompt.md",
            ".github/prompts/speckit.analyze.prompt.md",
            ".github/prompts/speckit.checklist.prompt.md",
            ".github/prompts/speckit.clarify.prompt.md",
@@ -215,14 +198,6 @@ class TestCopilotIntegration:
            ".github/prompts/speckit.taskstoissues.prompt.md",
            ".vscode/settings.json",
            ".github/copilot-instructions.md",
            ".specify/extensions.yml",
            ".specify/extensions/.registry",
            ".specify/extensions/agent-context/README.md",
            ".specify/extensions/agent-context/agent-context-config.yml",
            ".specify/extensions/agent-context/commands/speckit.agent-context.update.md",
            ".specify/extensions/agent-context/extension.yml",
            ".specify/extensions/agent-context/scripts/bash/update-agent-context.sh",
            ".specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1",
            ".specify/integration.json",
            ".specify/init-options.json",
            ".specify/integrations/copilot.manifest.json",
@@ -263,7 +238,6 @@ class TestCopilotIntegration:
        assert result.exit_code == 0
        actual = sorted(p.relative_to(project).as_posix() for p in project.rglob("*") if p.is_file())
        expected = sorted([
            ".github/agents/speckit.agent-context.update.agent.md",
            ".github/agents/speckit.analyze.agent.md",
            ".github/agents/speckit.checklist.agent.md",
            ".github/agents/speckit.clarify.agent.md",
@@ -273,7 +247,6 @@ class TestCopilotIntegration:
            ".github/agents/speckit.specify.agent.md",
            ".github/agents/speckit.tasks.agent.md",
            ".github/agents/speckit.taskstoissues.agent.md",
            ".github/prompts/speckit.agent-context.update.prompt.md",
            ".github/prompts/speckit.analyze.prompt.md",
            ".github/prompts/speckit.checklist.prompt.md",
            ".github/prompts/speckit.clarify.prompt.md",
@@ -285,14 +258,6 @@ class TestCopilotIntegration:
            ".github/prompts/speckit.taskstoissues.prompt.md",
            ".vscode/settings.json",
            ".github/copilot-instructions.md",
            ".specify/extensions.yml",
            ".specify/extensions/.registry",
            ".specify/extensions/agent-context/README.md",
            ".specify/extensions/agent-context/agent-context-config.yml",
            ".specify/extensions/agent-context/commands/speckit.agent-context.update.md",
            ".specify/extensions/agent-context/extension.yml",
            ".specify/extensions/agent-context/scripts/bash/update-agent-context.sh",
            ".specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1",
            ".specify/integration.json",
            ".specify/init-options.json",
            ".specify/integrations/copilot.manifest.json",
@@ -321,8 +286,8 @@ class TestCopilotSkillsMode:
    """Tests for Copilot integration in --skills mode."""
    _SKILL_COMMANDS = [
-        "analyze", "clarify", "constitution", "implement",
+        "analyze", "checklist", "clarify", "constitution",
-        "plan", "checklist", "specify", "tasks", "taskstoissues",
+        "implement", "plan", "specify", "tasks", "taskstoissues",
    ]
    def _make_copilot(self):
@@ -426,8 +391,8 @@ class TestCopilotSkillsMode:
    # -- Copilot-specific post-processing ---------------------------------
-    def test_post_process_skill_content_does_not_inject_mode(self):
+    def test_post_process_skill_content_injects_mode(self):
-        """post_process_skill_content() must NOT inject mode: — VS Code Copilot does not support it."""
+        """post_process_skill_content() should inject mode: field."""
        copilot = self._make_copilot()
        content = (
            "---\n"
@@ -437,21 +402,7 @@ class TestCopilotSkillsMode:
            "\nBody content\n"
        )
        updated = copilot.post_process_skill_content(content)
-        assert "mode:" not in updated
+        assert "mode: speckit.plan" in updated
    def test_post_process_skill_content_injects_hook_note(self):
        """post_process_skill_content() should inject shared hook guidance but not mode:."""
        copilot = self._make_copilot()
        content = (
            "---\n"
            'name: "speckit-specify"\n'
            'description: "Specify workflow"\n'
            "---\n"
            "\n- For each executable hook, output the following\n"
        )
        updated = copilot.post_process_skill_content(content)
        assert "replace dots" in updated
        assert "mode:" not in updated
    def test_post_process_idempotent(self):
        """post_process_skill_content() must be idempotent."""
@@ -467,8 +418,8 @@ class TestCopilotSkillsMode:
        second = copilot.post_process_skill_content(first)
        assert first == second
-    def test_skills_do_not_have_mode_in_frontmatter(self, tmp_path):
+    def test_skills_have_mode_in_frontmatter(self, tmp_path):
-        """Generated SKILL.md files must NOT contain mode: — VS Code Copilot does not support it."""
+        """Generated SKILL.md files should have mode: field from post-processing."""
        copilot = self._make_copilot()
        created, _ = self._setup_skills(copilot, tmp_path)
        skill_files = [f for f in created if f.name == "SKILL.md"]
@@ -477,15 +428,11 @@ class TestCopilotSkillsMode:
            content = f.read_text(encoding="utf-8")
            parts = content.split("---", 2)
            fm = yaml.safe_load(parts[1])
-            assert "mode" not in fm, f"{f} frontmatter must not contain unsupported 'mode' field"
+            assert "mode" in fm, f"{f} frontmatter missing 'mode'"
-
+            # mode should be speckit.<stem>
-    def test_skills_hook_sections_explain_dotted_command_conversion(self, tmp_path):
+            skill_dir_name = f.parent.name
-        """Generated skills with hook sections should include shared hook guidance."""
+            stem = skill_dir_name.removeprefix("speckit-")
-        copilot = self._make_copilot()
+            assert fm["mode"] == f"speckit.{stem}"
        self._setup_skills(copilot, tmp_path)
        specify_skill = tmp_path / ".github" / "skills" / "speckit-specify" / "SKILL.md"
        content = specify_skill.read_text(encoding="utf-8")
        assert "replace dots" in content
    # -- Template processing ----------------------------------------------
@@ -655,20 +602,10 @@ class TestCopilotSkillsMode:
        assert result.exit_code == 0, f"init failed: {result.output}"
        actual = sorted(p.relative_to(project).as_posix() for p in project.rglob("*") if p.is_file())
        expected = sorted([
-            # Skill files (core + extension-installed agent-context command)
+            # Skill files
            *[f".github/skills/speckit-{cmd}/SKILL.md" for cmd in self._SKILL_COMMANDS],
            ".github/skills/speckit-agent-context-update/SKILL.md",
            # Context file
            ".github/copilot-instructions.md",
            # Bundled agent-context extension
            ".specify/extensions.yml",
            ".specify/extensions/.registry",
            ".specify/extensions/agent-context/README.md",
            ".specify/extensions/agent-context/agent-context-config.yml",
            ".specify/extensions/agent-context/commands/speckit.agent-context.update.md",
            ".specify/extensions/agent-context/extension.yml",
            ".specify/extensions/agent-context/scripts/bash/update-agent-context.sh",
            ".specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1",
            # Integration metadata
            ".specify/init-options.json",
            ".specify/integration.json",
--- a/tests/integrations/test_integration_cursor_agent.py
+++ b/tests/integrations/test_integration_cursor_agent.py
@@ -1,7 +1,6 @@
 """Tests for CursorAgentIntegration."""
 from pathlib import Path
 from urllib.parse import urlparse
 from specify_cli.integrations import get_integration
 from specify_cli.integrations.manifest import IntegrationManifest
@@ -107,157 +106,3 @@ class TestCursorAgentAutoPromote:
        assert result.exit_code == 0, f"init --ai cursor-agent failed: {result.output}"
        assert (target / ".cursor" / "skills" / "speckit-plan" / "SKILL.md").exists()
 class TestCursorAgentCliDispatch:
    """Verify the CLI dispatch path for cursor-agent (issue #2629).
    The ``cursor-agent`` CLI supports headless execution via ``-p`` (with
    full tool access including write/shell) and requires ``--trust`` to
    bypass the Workspace Trust prompt.  These tests pin the exact argv
    shape that the workflow runner will use.
    """
    def test_requires_cli_is_false_for_ide_first_flow(self):
        """``requires_cli`` must stay False so the IDE-only flow keeps working.
        ``specify init --ai cursor-agent`` (without ``--ignore-agent-tools``)
        treats ``requires_cli=True`` as a hard precheck and fails when the
        ``cursor-agent`` CLI isn't on PATH — even though the Cursor IDE
        / skills flow can run without it.  Workflow dispatch support is
        signalled by overriding ``build_exec_args()`` instead, mirroring
        ``CopilotIntegration``.
        """
        i = get_integration("cursor-agent")
        assert i.config.get("requires_cli") is False
    def test_install_url_is_set(self):
        i = get_integration("cursor-agent")
        url = i.config.get("install_url")
        assert url is not None
        # CodeQL: use a hostname comparison instead of a substring check
        # to avoid the "Incomplete URL substring sanitization" warning
        # (substring "cursor.com" can also appear in attacker-controlled
        # positions of an arbitrary URL).
        host = (urlparse(url).hostname or "").lower()
        assert host == "cursor.com" or host.endswith(".cursor.com")
    def test_build_exec_args_default_includes_headless_flags_and_json(self):
        """Default argv emits the full headless flag set: -p --trust
        --approve-mcps --force, then prompt, then --output-format json.
        """
        i = get_integration("cursor-agent")
        args = i.build_exec_args("/speckit-specify some-feature")
        assert args == [
            "cursor-agent", "-p", "--trust", "--approve-mcps", "--force",
            "/speckit-specify some-feature",
            "--output-format", "json",
        ]
    def test_build_exec_args_text_output_omits_format(self):
        i = get_integration("cursor-agent")
        args = i.build_exec_args("/speckit-plan", output_json=False)
        assert args == [
            "cursor-agent", "-p", "--trust", "--approve-mcps", "--force",
            "/speckit-plan",
        ]
    def test_build_exec_args_with_model(self):
        i = get_integration("cursor-agent")
        args = i.build_exec_args(
            "/speckit-specify", model="sonnet-4-thinking", output_json=False
        )
        assert args == [
            "cursor-agent", "-p", "--trust", "--approve-mcps", "--force",
            "/speckit-specify",
            "--model", "sonnet-4-thinking",
        ]
    def test_build_exec_args_contains_mandatory_headless_flags(self):
        """The four headless flags must always appear together.
        ``--approve-mcps`` is required so MCP servers (e.g. dingtalk-doc)
        actually load in headless mode; ``--force`` is required so the
        agent doesn't block on tool-call approval prompts during the
        speckit workflow.  Together with ``-p`` and ``--trust`` they
        bring cursor-agent's headless behaviour in line with
        ``claude -p`` / ``codex --exec`` from spec-kit's perspective.
        """
        i = get_integration("cursor-agent")
        args = i.build_exec_args("/speckit-implement", output_json=False)
        for flag in ("-p", "--trust", "--approve-mcps", "--force"):
            assert flag in args, f"missing mandatory headless flag: {flag}"
    def test_build_exec_args_supports_dispatch_without_requires_cli(self):
        """``build_exec_args`` must return argv even though ``requires_cli``
        is ``False``.
        ``CursorAgentIntegration`` opts out of the ``requires_cli`` hard
        precheck (so ``specify init`` doesn't fail when the CLI isn't on
        PATH) but still supports workflow dispatch.  The presence of a
        non-``None`` argv from ``build_exec_args()`` is what the engine
        keys off — pin that invariant.
        """
        i = get_integration("cursor-agent")
        assert i.config.get("requires_cli") is False
        argv = i.build_exec_args("/speckit-plan", output_json=False)
        assert argv is not None
        assert argv[0] == "cursor-agent"
    def test_build_command_invocation_uses_hyphenated_skill_name(self):
        """SkillsIntegration: /speckit-plan (not /speckit.plan)."""
        i = get_integration("cursor-agent")
        assert i.build_command_invocation("speckit.plan", "feature-x") == "/speckit-plan feature-x"
        assert i.build_command_invocation("plan") == "/speckit-plan"
    def test_dispatch_command_resolves_cmd_shim_for_subprocess(self):
        """``.cmd`` shims must be resolved to their full path before ``subprocess.run``.
        ``cursor-agent`` (and other npm-installed CLIs on Windows) ship as
        ``cursor-agent.cmd`` wrappers.  ``shutil.which`` honors ``PATHEXT``
        and finds them, but Python's ``subprocess.run`` calls
        ``CreateProcess`` which does **not** consult ``PATHEXT`` and fails
        with ``WinError 2`` on a bare ``["cursor-agent", ...]`` argv.  The
        fix in ``base.py::dispatch_command`` resolves ``exec_args[0]`` via
        ``shutil.which`` so the full ``.cmd`` path is what reaches
        ``CreateProcess``.
        """
        from unittest.mock import patch, MagicMock
        i = get_integration("cursor-agent")
        mock_result = MagicMock()
        mock_result.returncode = 0
        mock_result.stdout = "ok"
        mock_result.stderr = ""
        fake_path = r"C:\Users\foo\AppData\Local\cursor-agent\cursor-agent.CMD"
        with patch(
            "specify_cli.integrations.base.shutil.which", return_value=fake_path
        ), patch("subprocess.run", return_value=mock_result) as mock_run:
            result = i.dispatch_command(
                "speckit.plan", args="feature-x", stream=False, timeout=5
            )
        assert result["exit_code"] == 0
        argv = mock_run.call_args[0][0]
        assert argv[0] == fake_path, f"expected resolved .CMD path, got: {argv[0]!r}"
        assert argv[1:6] == ["-p", "--trust", "--approve-mcps", "--force", "/speckit-plan feature-x"]
    def test_dispatch_command_passthrough_when_shutil_which_finds_nothing(self):
        """If ``shutil.which`` returns ``None``, leave argv unchanged so the
        existing ``FileNotFoundError`` path remains observable to callers."""
        from unittest.mock import patch, MagicMock
        i = get_integration("cursor-agent")
        mock_result = MagicMock()
        mock_result.returncode = 0
        mock_result.stdout = ""
        mock_result.stderr = ""
        with patch(
            "specify_cli.integrations.base.shutil.which", return_value=None
        ), patch("subprocess.run", return_value=mock_result) as mock_run:
            i.dispatch_command("speckit.plan", stream=False, timeout=5)
        argv = mock_run.call_args[0][0]
        assert argv[0] == "cursor-agent"
--- a/tests/integrations/test_integration_forge.py
+++ b/tests/integrations/test_integration_forge.py
@@ -330,7 +330,7 @@ class TestForgeCommandRegistrar:
        assert "speckit.my-extension.example" in registered
        # Check the generated file has hyphenated name in frontmatter
-        forge_cmd = tmp_path / ".forge" / "commands" / "speckit-my-extension-example.md"
+        forge_cmd = tmp_path / ".forge" / "commands" / "speckit.my-extension.example.md"
        assert forge_cmd.exists()
        content = forge_cmd.read_text(encoding="utf-8")
@@ -378,7 +378,7 @@ class TestForgeCommandRegistrar:
        )
        # Check the alias file has hyphenated name in frontmatter
-        alias_file = tmp_path / ".forge" / "commands" / "speckit-my-extension-ex.md"
+        alias_file = tmp_path / ".forge" / "commands" / "speckit.my-extension.ex.md"
        assert alias_file.exists()
        content = alias_file.read_text(encoding="utf-8")
@@ -467,7 +467,7 @@ class TestForgeCommandRegistrar:
        assert "speckit.git.feature" in registered
-        forge_cmd = tmp_path / ".forge" / "commands" / "speckit-git-feature.md"
+        forge_cmd = tmp_path / ".forge" / "commands" / "speckit.git.feature.md"
        assert forge_cmd.exists(), "Expected Forge command file was not created"
        content = forge_cmd.read_text(encoding="utf-8")
--- a/Show More
+++ b/Show More
		`@@ -0,0 +1,2 @@`
							`"""specify extension * commands — placeholder for future extraction."""`
							`from __future__ import annotations`
		`@@ -0,0 +1,2 @@`
							`"""specify integration * commands — placeholder for future extraction."""`
							`from __future__ import annotations`
		`@@ -0,0 +1,2 @@`
							`"""specify preset * commands — placeholder for future extraction."""`
							`from __future__ import annotations`
		`@@ -0,0 +1,2 @@`
							`"""specify workflow * commands — placeholder for future extraction."""`
							`from __future__ import annotations`