chore: bump version to 0.9.3

* fix script command hints for agent separators

* Address command hint review feedback

* chore: remove whitespace-only PR churn

* test: fix PowerShell command hint invocation

* fix: preserve hyphens in script command hints

* fix: render managed script command hints

.editorconfig

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

.github/workflows/add-community-extension.lock.yml

@@ -1,4 +1,4 @@
-# gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"f1073a236eb41f9fc2b5b8c1e58c25e02b5a6d18d242887636acc9007dd1542e","compiler_version":"v0.74.8","strict":true,"agent_id":"copilot"}
+# gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"2ace61d3a4e86e81ce7ff110e118981b4d88a06aa351ecdc2c3b64e44b10690f","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"}]}
 #    ___                   _   _      
 #   / _ \                 | | (_)     
@@ -204,23 +204,23 @@ jobs:
         run: |
           bash "${RUNNER_TEMP}/gh-aw/actions/create_prompt_first.sh"
           {
-          cat << 'GH_AW_PROMPT_25355d452b4d239a_EOF'
+          cat << 'GH_AW_PROMPT_767e1d181d9dae54_EOF'
           <system>
-          GH_AW_PROMPT_25355d452b4d239a_EOF
+          GH_AW_PROMPT_767e1d181d9dae54_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_25355d452b4d239a_EOF'
+          cat << 'GH_AW_PROMPT_767e1d181d9dae54_EOF'
           <safe-output-tools>
           Tools: add_comment(max:2), create_pull_request, add_labels(max:3), missing_tool, missing_data, noop
-          GH_AW_PROMPT_25355d452b4d239a_EOF
+          GH_AW_PROMPT_767e1d181d9dae54_EOF
           cat "${RUNNER_TEMP}/gh-aw/prompts/safe_outputs_create_pull_request.md"
-          cat << 'GH_AW_PROMPT_25355d452b4d239a_EOF'
+          cat << 'GH_AW_PROMPT_767e1d181d9dae54_EOF'
           </safe-output-tools>
-          GH_AW_PROMPT_25355d452b4d239a_EOF
+          GH_AW_PROMPT_767e1d181d9dae54_EOF
           cat "${RUNNER_TEMP}/gh-aw/prompts/mcp_cli_tools_prompt.md"
-          cat << 'GH_AW_PROMPT_25355d452b4d239a_EOF'
+          cat << 'GH_AW_PROMPT_767e1d181d9dae54_EOF'
           <github-context>
           The following GitHub context information is available for this workflow:
           {{#if github.actor}}
@@ -252,12 +252,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_25355d452b4d239a_EOF
+          GH_AW_PROMPT_767e1d181d9dae54_EOF
           cat "${RUNNER_TEMP}/gh-aw/prompts/github_mcp_tools_with_safeoutputs_prompt.md"
-          cat << 'GH_AW_PROMPT_25355d452b4d239a_EOF'
+          cat << 'GH_AW_PROMPT_767e1d181d9dae54_EOF'
           </system>
           {{#runtime-import .github/workflows/add-community-extension.md}}
-          GH_AW_PROMPT_25355d452b4d239a_EOF
+          GH_AW_PROMPT_767e1d181d9dae54_EOF
           } > "$GH_AW_PROMPT"
       - name: Interpolate variables and render templates
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
@@ -464,9 +464,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_a6227a6d6ade9e30_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":"true"},"report_incomplete":{}}
-          GH_AW_SAFE_OUTPUTS_CONFIG_a6227a6d6ade9e30_EOF
+          cat > "${RUNNER_TEMP}/gh-aw/safeoutputs/config.json" << 'GH_AW_SAFE_OUTPUTS_CONFIG_95f097d550e5bb4b_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":{}}
+          GH_AW_SAFE_OUTPUTS_CONFIG_95f097d550e5bb4b_EOF
       - name: Generate Safe Outputs Tools
         env:
           GH_AW_TOOLS_META_JSON: |
@@ -722,7 +722,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_6ce4129d4503180e_EOF | "$GH_AW_NODE" "${RUNNER_TEMP}/gh-aw/actions/start_mcp_gateway.cjs"
+          cat << GH_AW_MCP_CONFIG_9f16469ceb45c7f6_EOF | "$GH_AW_NODE" "${RUNNER_TEMP}/gh-aw/actions/start_mcp_gateway.cjs"
           {
             "mcpServers": {
               "github": {
@@ -763,7 +763,7 @@ jobs:
               "payloadDir": "${MCP_GATEWAY_PAYLOAD_DIR}"
             }
           }
-          GH_AW_MCP_CONFIG_6ce4129d4503180e_EOF
+          GH_AW_MCP_CONFIG_9f16469ceb45c7f6_EOF
       - name: Mount MCP servers as CLIs
         id: mount-mcp-clis
         continue-on-error: true
@@ -1079,7 +1079,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: "true"
+          GH_AW_NOOP_REPORT_AS_ISSUE: "false"
         with:
           github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
           script: |
@@ -1556,7 +1556,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\":\"true\"},\"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\":\"false\"},\"report_incomplete\":{}}"
           GH_AW_CI_TRIGGER_TOKEN: ${{ secrets.GH_AW_CI_TRIGGER_TOKEN }}
         with:
           github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

.github/workflows/add-community-preset.lock.yml

@@ -1,4 +1,4 @@
-# gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"f6cbeb7bc3ee4de1c2b3963fbf21525d0add0425a6807a8335f8f9d93e01a44f","compiler_version":"v0.74.8","strict":true,"agent_id":"copilot"}
+# gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"f209d3fbcde6b25fd5099c7b1ea0d3dace8967b23d8049a92566c213ed9ccc5e","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"}]}
 #    ___                   _   _      
 #   / _ \                 | | (_)     
@@ -204,23 +204,23 @@ jobs:
         run: |
           bash "${RUNNER_TEMP}/gh-aw/actions/create_prompt_first.sh"
           {
-          cat << 'GH_AW_PROMPT_26e9904027e0c5a2_EOF'
+          cat << 'GH_AW_PROMPT_c25ce620b285c8e3_EOF'
           <system>
-          GH_AW_PROMPT_26e9904027e0c5a2_EOF
+          GH_AW_PROMPT_c25ce620b285c8e3_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_26e9904027e0c5a2_EOF'
+          cat << 'GH_AW_PROMPT_c25ce620b285c8e3_EOF'
           <safe-output-tools>
           Tools: add_comment(max:2), create_pull_request, add_labels(max:3), missing_tool, missing_data, noop
-          GH_AW_PROMPT_26e9904027e0c5a2_EOF
+          GH_AW_PROMPT_c25ce620b285c8e3_EOF
           cat "${RUNNER_TEMP}/gh-aw/prompts/safe_outputs_create_pull_request.md"
-          cat << 'GH_AW_PROMPT_26e9904027e0c5a2_EOF'
+          cat << 'GH_AW_PROMPT_c25ce620b285c8e3_EOF'
           </safe-output-tools>
-          GH_AW_PROMPT_26e9904027e0c5a2_EOF
+          GH_AW_PROMPT_c25ce620b285c8e3_EOF
           cat "${RUNNER_TEMP}/gh-aw/prompts/mcp_cli_tools_prompt.md"
-          cat << 'GH_AW_PROMPT_26e9904027e0c5a2_EOF'
+          cat << 'GH_AW_PROMPT_c25ce620b285c8e3_EOF'
           <github-context>
           The following GitHub context information is available for this workflow:
           {{#if github.actor}}
@@ -252,12 +252,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_26e9904027e0c5a2_EOF
+          GH_AW_PROMPT_c25ce620b285c8e3_EOF
           cat "${RUNNER_TEMP}/gh-aw/prompts/github_mcp_tools_with_safeoutputs_prompt.md"
-          cat << 'GH_AW_PROMPT_26e9904027e0c5a2_EOF'
+          cat << 'GH_AW_PROMPT_c25ce620b285c8e3_EOF'
           </system>
           {{#runtime-import .github/workflows/add-community-preset.md}}
-          GH_AW_PROMPT_26e9904027e0c5a2_EOF
+          GH_AW_PROMPT_c25ce620b285c8e3_EOF
           } > "$GH_AW_PROMPT"
       - name: Interpolate variables and render templates
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
@@ -464,9 +464,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_36855fee66c4c038_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":"true"},"report_incomplete":{}}
-          GH_AW_SAFE_OUTPUTS_CONFIG_36855fee66c4c038_EOF
+          cat > "${RUNNER_TEMP}/gh-aw/safeoutputs/config.json" << 'GH_AW_SAFE_OUTPUTS_CONFIG_50dbf4670371d6f7_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":{}}
+          GH_AW_SAFE_OUTPUTS_CONFIG_50dbf4670371d6f7_EOF
       - name: Generate Safe Outputs Tools
         env:
           GH_AW_TOOLS_META_JSON: |
@@ -722,7 +722,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_fdc26b942885c376_EOF | "$GH_AW_NODE" "${RUNNER_TEMP}/gh-aw/actions/start_mcp_gateway.cjs"
+          cat << GH_AW_MCP_CONFIG_04e1e53849e8d680_EOF | "$GH_AW_NODE" "${RUNNER_TEMP}/gh-aw/actions/start_mcp_gateway.cjs"
           {
             "mcpServers": {
               "github": {
@@ -763,7 +763,7 @@ jobs:
               "payloadDir": "${MCP_GATEWAY_PAYLOAD_DIR}"
             }
           }
-          GH_AW_MCP_CONFIG_fdc26b942885c376_EOF
+          GH_AW_MCP_CONFIG_04e1e53849e8d680_EOF
       - name: Mount MCP servers as CLIs
         id: mount-mcp-clis
         continue-on-error: true
@@ -1079,7 +1079,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: "true"
+          GH_AW_NOOP_REPORT_AS_ISSUE: "false"
         with:
           github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
           script: |
@@ -1556,7 +1556,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\":\"true\"},\"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\":\"false\"},\"report_incomplete\":{}}"
           GH_AW_CI_TRIGGER_TOKEN: ${{ secrets.GH_AW_CI_TRIGGER_TOKEN }}
         with:
           github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

.github/workflows/docs.yml

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

AGENTS.md

@@ -177,7 +177,24 @@ def _register_builtins() -> None:
 
 Set `context_file` on the integration class. The base integration setup creates or updates the managed Spec Kit section in that file, and uninstall removes the managed section when appropriate.
 
-Only add custom setup logic when the agent needs non-standard behavior. Most integrations do not need wrapper scripts or separate context-update dispatch code.
+The managed section is owned by the bundled `agent-context` extension (`extensions/agent-context/`). All configuration flows through the extension's own config file at `.specify/extensions/agent-context/agent-context-config.yml`:
+
+```yaml
+# Path to the coding agent context file managed by this extension
+context_file: CLAUDE.md
+
+# Delimiters for the managed Spec Kit section
+context_markers:
+  start: "<!-- SPECKIT START -->"
+  end: "<!-- SPECKIT END -->"
+```
+
+- `context_file` is written automatically from the integration's class attribute when `specify init` or `specify integration use` is run.
+- `context_markers.{start,end}` defaults to `IntegrationBase.CONTEXT_MARKER_START` / `CONTEXT_MARKER_END`. Users who want custom markers edit `agent-context-config.yml` directly — both the Python layer (`upsert_context_section()` / `remove_context_section()`) and the bundled scripts (`extensions/agent-context/scripts/bash/update-agent-context.sh` and `.ps1`) read from this single source of truth.
+
+Users can opt out entirely with `specify extension disable agent-context`; while disabled, Spec Kit skips context-file creation, updates, and removal (the gates are inside `upsert_context_section()` and `remove_context_section()`).
+
+Only add custom setup logic when the agent needs non-standard behavior. Integrations no longer require per-agent thin wrapper scripts or shared context-update dispatcher scripts — the `agent-context` extension is fully generic.
 
 ### 5. Test it
 
@@ -409,7 +426,7 @@ When an issue exists, include its number immediately after the prefix — this i
 ## Common Pitfalls
 
 1. **Using shorthand keys for CLI-based integrations**: For CLI-based integrations (`requires_cli: True`), the `key` must match the executable name (e.g., `"cursor-agent"` not `"cursor"`). `shutil.which(key)` is used for CLI tool checks — mismatches require special-case mappings. IDE-based integrations (`requires_cli: False`) are not subject to this constraint.
-2. **Forgetting update scripts**: Both bash and PowerShell thin wrappers and the shared context-update scripts must be updated.
+2. **Forgetting context configuration**: The bundled `agent-context` extension reads from `.specify/extensions/agent-context/agent-context-config.yml`. New integrations only need to set `context_file` on the class — markers and dispatcher scripts are managed centrally.
 3. **Incorrect `requires_cli` value**: Set to `True` only for agents that have a CLI tool; set to `False` for IDE-based agents.
 4. **Wrong argument format**: Use `$ARGUMENTS` for Markdown agents, `{{args}}` for TOML agents.
 5. **Skipping registration**: The import and `_register()` call in `_register_builtins()` must both be added.

CHANGELOG.md

@@ -2,6 +2,76 @@
 
 <!-- insert new changelog below this comment -->
 
+## [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

README.md

@@ -59,6 +59,24 @@ 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.
@@ -133,7 +151,7 @@ Run `specify integration list` to see all available integrations in your install
 
 After running `specify init`, your AI coding agent will have access to these slash commands for structured development. For integrations that support skills mode, passing `--integration <agent> --integration-options="--skills"` installs agent skills instead of slash-command prompt files.
 
-#### Core Commands
+### Core Commands
 
 Essential commands for the Spec-Driven Development workflow:
 
@@ -146,7 +164,7 @@ Essential commands for the Spec-Driven Development workflow:
 | `/speckit.taskstoissues` | `speckit-taskstoissues`| Convert generated task lists into GitHub issues for tracking and execution |
 | `/speckit.implement`     | `speckit-implement`    | Execute all tasks to build the feature according to the plan               |
 
-#### Optional Commands
+### Optional Commands
 
 Additional commands for enhanced quality and validation:
 

docs/community/extensions.md

@@ -56,6 +56,7 @@ 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) |
@@ -70,6 +71,7 @@ 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) |
@@ -77,11 +79,12 @@ 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 — portfolio, lite mode, monorepo, optional V-Model | `process` | Read+Write | [speckit-product-forge](https://github.com/VaiYav/speckit-product-forge) |
+| Product Forge | Full product lifecycle from research to release — express/lite/standard/v-model tracks, living spec + traceability, structured journeys → E2E, monorepo, and selectable doc-structure strategies | `process` | Read+Write | [speckit-product-forge](https://github.com/VaiYav/speckit-product-forge) |
 | Product Spec Extension | Generates PRFAQ, Lean PRD, stakeholder summaries, and technical designs from engineering specs | `docs` | Read+Write | [spec-kit-product](https://github.com/d0whc3r/spec-kit-product) |
 | Project Health Check | Diagnose a Spec Kit project and report health issues across structure, agents, features, scripts, extensions, and git | `visibility` | Read-only | [spec-kit-doctor](https://github.com/KhawarHabibKhan/spec-kit-doctor) |
 | Project Status | Show current SDD workflow progress — active feature, artifact status, task completion, workflow phase, and extensions summary | `visibility` | Read-only | [spec-kit-status](https://github.com/KhawarHabibKhan/spec-kit-status) |
 | QA Testing Extension | Systematic QA testing with browser-driven or CLI-based validation of acceptance criteria from spec | `code` | Read-only | [spec-kit-qa](https://github.com/arunt14/spec-kit-qa) |
+| RAG Azure Builder | Spec Kit extension for onboarding and operating an Azure RAG stack with guided workflows. | `process` | Read+Write | [spec-kit-extension-rag-azure-builder](https://github.com/Sertxito/spec-kit-extension-rag-azure-builder) |
 | Ralph Loop | Autonomous implementation loop using AI agent CLI | `code` | Read+Write | [spec-kit-ralph](https://github.com/Rubiss-Projects/spec-kit-ralph) |
 | Reconcile Extension | Reconcile implementation drift by surgically updating feature artifacts. | `docs` | Read+Write | [spec-kit-reconcile](https://github.com/stn1slv/spec-kit-reconcile) |
 | Red Team | Adversarial review of specs before /speckit.plan — parallel lens agents surface risks that clarify/analyze structurally can't (prompt injection, integrity gaps, cross-spec drift, silent failures). Produces a structured findings report; no auto-edits to specs. | `docs` | Read+Write | [spec-kit-red-team](https://github.com/ashbrener/spec-kit-red-team) |
@@ -111,8 +114,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) |

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 across project-defined agent guidance surfaces and documents intentional deviations | 6 templates, 3 commands | — | [spec-kit-preset-agent-parity-governance](https://github.com/hindermath/spec-kit-preset-agent-parity-governance) |
+| Agent Parity Governance | Keeps shared AI-agent instructions aligned and adds agent-neutral Spec Kit model-routing guidance across project-defined agent guidance surfaces | 9 templates, 3 commands | — | [spec-kit-preset-agent-parity-governance](https://github.com/hindermath/spec-kit-preset-agent-parity-governance) |
 | AIDE In-Place Migration | Adapts the AIDE extension workflow for in-place technology migrations (X → Y pattern) — adds migration objectives, verification gates, knowledge documents, and behavioral equivalence criteria | 2 templates, 8 commands | AIDE extension | [spec-kit-presets](https://github.com/mnriem/spec-kit-presets) |
 | Architecture Governance | Adds secure architecture governance: trust boundaries, threat modeling, STRIDE/CAPEC, S-ADRs, Zero Trust applicability, and OWASP SAMM | 11 templates, 3 commands | — | [spec-kit-preset-architecture-governance](https://github.com/hindermath/spec-kit-preset-architecture-governance) |
 | Canon Core | Adapts original Spec Kit workflow to work together with Canon extension | 2 templates, 8 commands | — | [spec-kit-canon](https://github.com/maximiliamus/spec-kit-canon) |
@@ -27,6 +27,6 @@ The following community-contributed presets customize how Spec Kit behaves — o
 | 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 | 23 templates, 7 commands | — | [spec-kit-workflow-preset](https://github.com/bigsmartben/spec-kit-workflow-preset) |
+| Workflow Preset | Behavior-first specification, design artifacts, and agent-native handoff orchestration — adds requirement-phase behavior drafts, formal BDD/UIF/behavior contracts, optional design artifacts, and scoped implementation handoffs with Core Agent, Vertical Planner Agent, and Worker Agent modes | 22 templates, 8 commands | — | [spec-kit-workflow-preset](https://github.com/bigsmartben/spec-kit-workflow-preset) |
 
 To build and publish your own preset, see the [Presets Publishing Guide](https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md).

docs/installation.md

@@ -88,6 +88,8 @@ 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

docs/reference/integrations.md

@@ -10,6 +10,7 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify
 | [Antigravity (agy)](https://antigravity.google/)                                     | `agy`            | Skills-based integration; skills are installed automatically                                                                               |
 | [Auggie CLI](https://docs.augmentcode.com/cli/overview)                              | `auggie`         |                                                                                                                                           |
 | [Claude Code](https://www.anthropic.com/claude-code)                                 | `claude`         | Skills-based integration; installs skills in `.claude/skills`                                                                              |
+| [Cline](https://github.com/cline/cline)                                              | `cline`          | IDE-based agent                                                                                                                           |
 | [CodeBuddy CLI](https://www.codebuddy.ai/cli)                                        | `codebuddy`      |                                                                                                                                           |
 | [Codex CLI](https://github.com/openai/codex)                                         | `codex`          | Skills-based integration; installs skills into `.agents/skills` and invokes them as `$speckit-<command>` |
 | [Cursor](https://cursor.sh/)                                                         | `cursor-agent`   |                                                                                                                                           |
@@ -18,6 +19,7 @@ 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`          |                                                                                                                                           |

docs/reference/workflows.md

@@ -28,8 +28,18 @@ specify workflow run speckit -i spec="Build a kanban board with drag-and-drop ta
 specify workflow resume <run_id>
 ```
 
+| Option              | Description                                              |
+| ------------------- | -------------------------------------------------------- |
+| `-i` / `--input`    | Updated input values as `key=value` (repeatable)         |
+
 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

docs/upgrade.md

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

extensions/agent-context/README.md

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

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

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

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

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

extensions/agent-context/extension.yml

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

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

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

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

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

extensions/catalog.community.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-05-28T00:00:00Z",
+  "updated_at": "2026-06-02T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
   "extensions": {
     "aide": {
@@ -1246,6 +1246,39 @@
       "created_at": "2026-03-17T00:00:00Z",
       "updated_at": "2026-03-17T00:00:00Z"
     },
+    "linear": {
+      "name": "Linear Integration",
+      "id": "linear",
+      "description": "Mirror spec-kit feature directories into Linear (filesystem → Linear, reconcile-based, unidirectional).",
+      "author": "Ash Brener",
+      "version": "0.2.0",
+      "download_url": "https://github.com/ashbrener/spec-kit-linear/archive/refs/tags/v0.2.0.zip",
+      "repository": "https://github.com/ashbrener/spec-kit-linear",
+      "homepage": "https://github.com/ashbrener/spec-kit-linear",
+      "documentation": "https://github.com/ashbrener/spec-kit-linear/blob/main/README.md",
+      "changelog": "https://github.com/ashbrener/spec-kit-linear/releases",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 5,
+        "hooks": 6
+      },
+      "tags": [
+        "issue-tracking",
+        "linear",
+        "tasks-sync",
+        "lifecycle-mirror",
+        "memory",
+        "cross-repo"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-06-01T00:00:00Z",
+      "updated_at": "2026-06-01T00:00:00Z"
+    },
     "m365": {
       "name": "Microsoft 365 Integration",
       "id": "m365",
@@ -1724,6 +1757,37 @@
       "created_at": "2026-05-04T02:51:52Z",
       "updated_at": "2026-05-04T02:51:52Z"
     },
+    "multi-sites": {
+      "name": "Multi-Sites Spec Kit",
+      "id": "multi-sites",
+      "description": "Multi-site aware specify command with per-site spec folders, auto-increment, and Drupal support",
+      "author": "teeyo",
+      "version": "1.0.0",
+      "download_url": "https://github.com/teeyo/spec-kit-multi-sites/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/teeyo/spec-kit-multi-sites",
+      "homepage": "https://github.com/teeyo/spec-kit-multi-sites",
+      "documentation": "https://github.com/teeyo/spec-kit-multi-sites/blob/main/README.md",
+      "changelog": "https://github.com/teeyo/spec-kit-multi-sites/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 0
+      },
+      "tags": [
+        "multi-site",
+        "drupal",
+        "workflow",
+        "process"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-06-01T00:00:00Z",
+      "updated_at": "2026-06-01T00:00:00Z"
+    },
     "onboard": {
       "name": "Onboard",
       "id": "onboard",
@@ -1950,12 +2014,12 @@
       "name": "Product Spec Extension",
       "id": "product",
       "description": "Generates PRFAQ, Lean PRD, stakeholder summaries, and technical designs from engineering specs.",
-      "author": "spec-kit-product contributors",
-      "version": "0.1.3",
-      "download_url": "https://github.com/d0whc3r/spec-kit-product/releases/download/v0.1.3/product-0.1.3.zip",
+      "author": "d0whc3r",
+      "version": "0.8.3",
+      "download_url": "https://github.com/d0whc3r/spec-kit-product/releases/download/v0.8.3/product-0.8.3.zip",
       "repository": "https://github.com/d0whc3r/spec-kit-product",
-      "homepage": "https://github.com/d0whc3r/spec-kit-product",
-      "documentation": "https://github.com/d0whc3r/spec-kit-product/blob/main/README.md",
+      "homepage": "https://d0whc3r.github.io/spec-kit-product/",
+      "documentation": "https://github.com/d0whc3r/spec-kit-product/wiki",
       "changelog": "https://github.com/d0whc3r/spec-kit-product/blob/main/CHANGELOG.md",
       "license": "MIT",
       "requires": {
@@ -1963,28 +2027,38 @@
       },
       "provides": {
         "commands": 4,
-        "hooks": 6
+        "hooks": 3
       },
       "tags": [
-        "product",
-        "spec",
-        "prd",
         "design",
-        "documentation"
+        "documentation",
+        "jtbd",
+        "lean-prd",
+        "planning",
+        "prd",
+        "prfaq",
+        "product",
+        "product-management",
+        "requirements",
+        "spec",
+        "spec-kit",
+        "spec-kit-extension",
+        "stakeholder",
+        "technical-design"
       ],
       "verified": false,
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-05-26T00:00:00Z",
-      "updated_at": "2026-05-26T00:00:00Z"
+      "updated_at": "2026-06-01T00:00:00Z"
     },
     "product-forge": {
       "name": "Product Forge",
       "id": "product-forge",
-      "description": "Full product lifecycle from research to release — portfolio, lite mode, monorepo, optional V-Model",
+      "description": "Full product lifecycle from research to release — express/lite/standard/v-model tracks, living spec + traceability, structured journeys → E2E, monorepo, and selectable doc-structure strategies",
       "author": "VaiYav",
-      "version": "1.5.1",
-      "download_url": "https://github.com/VaiYav/speckit-product-forge/archive/refs/tags/v1.5.1.zip",
+      "version": "1.6.0",
+      "download_url": "https://github.com/VaiYav/speckit-product-forge/archive/refs/tags/v1.6.0.zip",
       "repository": "https://github.com/VaiYav/speckit-product-forge",
       "homepage": "https://github.com/VaiYav/speckit-product-forge",
       "documentation": "https://github.com/VaiYav/speckit-product-forge/blob/main/README.md",
@@ -1994,7 +2068,7 @@
         "speckit_version": ">=0.1.0"
       },
       "provides": {
-        "commands": 29,
+        "commands": 31,
         "hooks": 0
       },
       "tags": [
@@ -2008,7 +2082,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-03-28T00:00:00Z",
-      "updated_at": "2026-04-24T15:52:00Z"
+      "updated_at": "2026-06-02T00:00:00Z"
     },
     "qa": {
       "name": "QA Testing Extension",
@@ -2040,6 +2114,38 @@
       "created_at": "2026-04-01T00:00:00Z",
       "updated_at": "2026-04-01T00:00:00Z"
     },
+    "rag-azure-builder": {
+      "name": "RAG Azure Builder",
+      "id": "rag-azure-builder",
+      "description": "Spec Kit extension for onboarding and operating an Azure RAG stack with guided workflows.",
+      "author": "Sertxito",
+      "version": "1.2.0",
+      "download_url": "https://github.com/Sertxito/spec-kit-extension-rag-azure-builder/archive/refs/tags/v1.2.0.zip",
+      "repository": "https://github.com/Sertxito/spec-kit-extension-rag-azure-builder",
+      "homepage": "https://github.com/Sertxito/spec-kit-extension-rag-azure-builder",
+      "documentation": "https://github.com/Sertxito/spec-kit-extension-rag-azure-builder#readme",
+      "changelog": "https://github.com/Sertxito/spec-kit-extension-rag-azure-builder/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.0"
+      },
+      "provides": {
+        "commands": 5,
+        "hooks": 0
+      },
+      "tags": [
+        "azure",
+        "rag",
+        "search",
+        "onboarding",
+        "cost-optimization"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-06-01T00:00:00Z",
+      "updated_at": "2026-06-01T00:00:00Z"
+    },
     "ralph": {
       "name": "Ralph Loop",
       "id": "ralph",
@@ -2218,8 +2324,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.0.0",
-      "download_url": "https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd/archive/refs/tags/v1.0.0.zip",
+      "version": "1.1.0",
+      "download_url": "https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd/archive/refs/tags/v1.1.0.zip",
       "repository": "https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd",
       "homepage": "https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd",
       "documentation": "https://github.com/LoogacyStudio/spec-kit-reqnroll-bdd#readme",
@@ -2249,7 +2355,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-05-13T00:00:00Z",
-      "updated_at": "2026-05-13T00:00:00Z"
+      "updated_at": "2026-05-30T00:00:00Z"
     },
     "retro": {
       "name": "Retro Extension",
@@ -2933,13 +3039,13 @@
       "created_at": "2026-03-30T00:00:00Z",
       "updated_at": "2026-05-24T01:07:34Z"
     },
-    "superpowers-bridge": {
-      "name": "Superpowers Bridge",
-      "id": "superpowers-bridge",
+    "superspec": {
+      "name": "Superspec",
+      "id": "superspec",
       "description": "Bridges spec-kit workflows with obra/superpowers capabilities for brainstorming, TDD, code review, and resumable execution.",
       "author": "WangX0111",
-      "version": "1.0.0",
-      "download_url": "https://github.com/WangX0111/superspec/archive/refs/tags/v1.0.0.zip",
+      "version": "1.0.1",
+      "download_url": "https://github.com/WangX0111/superspec/archive/refs/tags/v1.0.1.zip",
       "repository": "https://github.com/WangX0111/superspec",
       "homepage": "https://github.com/WangX0111/superspec",
       "documentation": "https://github.com/WangX0111/superspec/blob/main/README.md",
@@ -2964,7 +3070,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-04-22T00:00:00Z",
-      "updated_at": "2026-04-22T00:00:00Z"
+      "updated_at": "2026-05-30T00:00:00Z"
     },
     "sync": {
       "name": "Spec Sync",
@@ -3501,4 +3607,4 @@
       "updated_at": "2026-04-13T00:00:00Z"
     }
   }
-}
+}

extensions/catalog.json

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

integrations/catalog.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-04-29T00:00:00Z",
+  "updated_at": "2026-05-13T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/integrations/catalog.json",
   "integrations": {
     "claude": {
@@ -12,6 +12,15 @@
       "repository": "https://github.com/github/spec-kit",
       "tags": ["cli", "anthropic"]
     },
+    "cline": {
+      "id": "cline",
+      "name": "Cline",
+      "version": "1.0.0",
+      "description": "Cline IDE integration",
+      "author": "spec-kit-core",
+      "repository": "https://github.com/github/spec-kit",
+      "tags": ["ide"]
+    },
     "copilot": {
       "id": "copilot",
       "name": "GitHub Copilot",

newsletters/2026-May.md

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

presets/catalog.community.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0",
-  "updated_at": "2026-05-27T00:00:00Z",
+  "updated_at": "2026-05-31T00:00:00Z",
   "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json",
   "presets": {
     "a11y-governance": {
@@ -34,11 +34,11 @@
     "agent-parity-governance": {
       "name": "Agent Parity Governance",
       "id": "agent-parity-governance",
-      "version": "0.1.0",
-      "description": "Keeps shared AI-agent guidance aligned across a project-defined set of agent instruction surfaces.",
+      "version": "0.2.0",
+      "description": "Keeps shared AI-agent guidance aligned and adds agent-neutral Spec Kit model-routing guidance across declared agent instruction surfaces.",
       "author": "Thorsten Hindermann",
       "repository": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance",
-      "download_url": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance/archive/refs/tags/v0.1.0.zip",
+      "download_url": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance/archive/refs/tags/v0.2.0.zip",
       "homepage": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance",
       "documentation": "https://github.com/hindermath/spec-kit-preset-agent-parity-governance/blob/main/README.md",
       "license": "MIT",
@@ -46,18 +46,20 @@
         "speckit_version": ">=0.8.0"
       },
       "provides": {
-        "templates": 6,
+        "templates": 9,
         "commands": 3
       },
       "tags": [
         "agents",
         "governance",
         "parity",
+        "agent-md",
         "agent-guidance",
+        "model-routing",
         "multi-agent"
       ],
       "created_at": "2026-04-27T00:00:00Z",
-      "updated_at": "2026-04-27T00:00:00Z"
+      "updated_at": "2026-05-31T00:00:00Z"
     },
     "aide-in-place": {
       "name": "AIDE In-Place Migration",
@@ -593,11 +595,11 @@
     "workflow-preset": {
       "name": "Workflow Preset",
       "id": "workflow-preset",
-      "version": "1.2.0",
+      "version": "1.3.1",
       "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/archive/refs/tags/v1.2.0.zip",
+      "download_url": "https://github.com/bigsmartben/spec-kit-workflow-preset/releases/download/v1.3.1/spec-kit-workflow-preset-v1.3.1.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",
@@ -605,8 +607,8 @@
         "speckit_version": ">=0.8.10.dev0"
       },
       "provides": {
-        "templates": 23,
-        "commands": 7
+        "templates": 22,
+        "commands": 8
       },
       "tags": [
         "behavior",
@@ -616,7 +618,7 @@
         "handoff"
       ],
       "created_at": "2026-05-27T00:00:00Z",
-      "updated_at": "2026-05-27T00:00:00Z"
+      "updated_at": "2026-05-28T00:00:00Z"
     }
   }
 }

pyproject.toml

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

scripts/bash/check-prerequisites.sh

@@ -117,20 +117,20 @@ check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
 # Validate required directories and files
 if [[ ! -d "$FEATURE_DIR" ]]; then
     echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
-    echo "Run __SPECKIT_COMMAND_SPECIFY__ first to create the feature structure." >&2
+    echo "Run $(format_speckit_command specify "$REPO_ROOT") first to create the feature structure." >&2
     exit 1
 fi
 
 if [[ ! -f "$IMPL_PLAN" ]]; then
     echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
-    echo "Run __SPECKIT_COMMAND_PLAN__ first to create the implementation plan." >&2
+    echo "Run $(format_speckit_command plan "$REPO_ROOT") first to create the implementation plan." >&2
     exit 1
 fi
 
 # Check for tasks.md if required
 if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
     echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
-    echo "Run __SPECKIT_COMMAND_TASKS__ first to create the task list." >&2
+    echo "Run $(format_speckit_command tasks "$REPO_ROOT") first to create the task list." >&2
     exit 1
 fi
 

scripts/bash/common.sh

@@ -307,6 +307,83 @@ has_jq() {
     command -v jq >/dev/null 2>&1
 }
 
+get_invoke_separator() {
+    local repo_root="${1:-$(get_repo_root)}"
+    if [[ "${_SPECIFY_INVOKE_SEPARATOR_CACHE_REPO_ROOT:-}" == "$repo_root" && -n "${_SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE:-}" ]]; then
+        printf '%s\n' "$_SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE"
+        return 0
+    fi
+
+    local integration_json="$repo_root/.specify/integration.json"
+    local separator="."
+    local parsed_with_jq=0
+
+    if [[ -f "$integration_json" ]]; then
+        if command -v jq >/dev/null 2>&1; then
+            local jq_separator
+            if jq_separator=$(jq -r '(.default_integration // .integration // "") as $k | if $k == "" then "." else (.integration_settings[$k].invoke_separator // ".") end' "$integration_json" 2>/dev/null); then
+                parsed_with_jq=1
+                case "$jq_separator" in
+                    "."|"-") separator="$jq_separator" ;;
+                esac
+            fi
+        fi
+
+        if [[ "$parsed_with_jq" -eq 0 ]] && command -v python3 >/dev/null 2>&1; then
+            if separator=$(python3 - "$integration_json" <<'PY' 2>/dev/null
+import json
+import sys
+
+try:
+    with open(sys.argv[1], encoding="utf-8") as fh:
+        state = json.load(fh)
+    key = state.get("default_integration") or state.get("integration") or ""
+    settings = state.get("integration_settings")
+    separator = "."
+    if isinstance(key, str) and isinstance(settings, dict):
+        entry = settings.get(key)
+        if isinstance(entry, dict) and entry.get("invoke_separator") in {".", "-"}:
+            separator = entry["invoke_separator"]
+    print(separator)
+except Exception:
+    print(".")
+PY
+); then
+                case "$separator" in
+                    "."|"-") ;;
+                    *) separator="." ;;
+                esac
+            else
+                separator="."
+            fi
+        fi
+    fi
+
+    _SPECIFY_INVOKE_SEPARATOR_CACHE_REPO_ROOT="$repo_root"
+    _SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE="$separator"
+    printf '%s\n' "$separator"
+}
+
+format_speckit_command() {
+    local command_name="$1"
+    local repo_root="${2:-$(get_repo_root)}"
+    local separator
+    if [[ "${_SPECIFY_INVOKE_SEPARATOR_CACHE_REPO_ROOT:-}" == "$repo_root" && -n "${_SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE:-}" ]]; then
+        separator="$_SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE"
+    else
+        separator=$(get_invoke_separator "$repo_root")
+        _SPECIFY_INVOKE_SEPARATOR_CACHE_REPO_ROOT="$repo_root"
+        _SPECIFY_INVOKE_SEPARATOR_CACHE_VALUE="$separator"
+    fi
+
+    command_name="${command_name#/}"
+    command_name="${command_name#speckit.}"
+    command_name="${command_name#speckit-}"
+    command_name="${command_name//./$separator}"
+
+    printf '/speckit%s%s\n' "$separator" "$command_name"
+}
+
 # Escape a string for safe embedding in a JSON value (fallback when jq is unavailable).
 # Handles backslash, double-quote, and JSON-required control character escapes (RFC 8259).
 json_escape() {

scripts/bash/setup-tasks.sh

@@ -35,13 +35,13 @@ fi
 
 if [[ ! -f "$IMPL_PLAN" ]]; then
     echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
-    echo "Run __SPECKIT_COMMAND_PLAN__ first to create the implementation plan." >&2
+    echo "Run $(format_speckit_command plan "$REPO_ROOT") first to create the implementation plan." >&2
     exit 1
 fi
 
 if [[ ! -f "$FEATURE_SPEC" ]]; then
     echo "ERROR: spec.md not found in $FEATURE_DIR" >&2
-    echo "Run __SPECKIT_COMMAND_SPECIFY__ first to create the feature structure." >&2
+    echo "Run $(format_speckit_command specify "$REPO_ROOT") first to create the feature structure." >&2
     exit 1
 fi
 

scripts/powershell/check-prerequisites.ps1

@@ -89,20 +89,23 @@ if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GI
 # Validate required directories and files
 if (-not (Test-Path $paths.FEATURE_DIR -PathType Container)) {
     Write-Output "ERROR: Feature directory not found: $($paths.FEATURE_DIR)"
-    Write-Output "Run __SPECKIT_COMMAND_SPECIFY__ first to create the feature structure."
+    $specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
+    Write-Output "Run $specifyCommand first to create the feature structure."
     exit 1
 }
 
 if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) {
     Write-Output "ERROR: plan.md not found in $($paths.FEATURE_DIR)"
-    Write-Output "Run __SPECKIT_COMMAND_PLAN__ first to create the implementation plan."
+    $planCommand = Format-SpecKitCommand -CommandName 'plan' -RepoRoot $paths.REPO_ROOT
+    Write-Output "Run $planCommand first to create the implementation plan."
     exit 1
 }
 
 # Check for tasks.md if required
 if ($RequireTasks -and -not (Test-Path $paths.TASKS -PathType Leaf)) {
     Write-Output "ERROR: tasks.md not found in $($paths.FEATURE_DIR)"
-    Write-Output "Run __SPECKIT_COMMAND_TASKS__ first to create the task list."
+    $tasksCommand = Format-SpecKitCommand -CommandName 'tasks' -RepoRoot $paths.REPO_ROOT
+    Write-Output "Run $tasksCommand first to create the task list."
     exit 1
 }
 

scripts/powershell/common.ps1

@@ -355,6 +355,58 @@ 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 {

scripts/powershell/setup-tasks.ps1

@@ -28,13 +28,15 @@ if (-not (Test-FeatureJsonMatchesFeatureDir -RepoRoot $paths.REPO_ROOT -ActiveFe
 
 if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) {
     [Console]::Error.WriteLine("ERROR: plan.md not found in $($paths.FEATURE_DIR)")
-    [Console]::Error.WriteLine("Run __SPECKIT_COMMAND_PLAN__ first to create the implementation plan.")
+    $planCommand = Format-SpecKitCommand -CommandName 'plan' -RepoRoot $paths.REPO_ROOT
+    [Console]::Error.WriteLine("Run $planCommand first to create the implementation plan.")
     exit 1
 }
 
 if (-not (Test-Path $paths.FEATURE_SPEC -PathType Leaf)) {
     [Console]::Error.WriteLine("ERROR: spec.md not found in $($paths.FEATURE_DIR)")
-    [Console]::Error.WriteLine("Run __SPECKIT_COMMAND_SPECIFY__ first to create the feature structure.")
+    $specifyCommand = Format-SpecKitCommand -CommandName 'specify' -RepoRoot $paths.REPO_ROOT
+    [Console]::Error.WriteLine("Run $specifyCommand first to create the feature structure.")
     exit 1
 }
 

src/specify_cli/agents.py

@@ -67,6 +67,33 @@ class CommandRegistrar:
             except ImportError:
                 pass  # Circular import during module init; retry on next access
 
+    @staticmethod
+    def _hyphenate_frontmatter_refs(val: Any) -> Any:
+        """Recursively find any dotted references starting with speckit. and hyphenate them."""
+        if isinstance(val, dict):
+            return {
+                k: CommandRegistrar._hyphenate_frontmatter_refs(v)
+                for k, v in val.items()
+            }
+        elif isinstance(val, list):
+            return [CommandRegistrar._hyphenate_frontmatter_refs(x) for x in val]
+        elif isinstance(val, str):
+            return re.sub(
+                r"\bspeckit\.[A-Za-z0-9-_]+(?:\.[A-Za-z0-9-_]+)*\b",
+                lambda m: m.group(0).replace(".", "-"),
+                val,
+            )
+        return val
+
+    @staticmethod
+    def _hyphenate_body_refs(body: str) -> str:
+        """Hyphenate dotted speckit references in command body text."""
+        return re.sub(
+            r"\bspeckit\.[A-Za-z0-9-_]+(?:\.[A-Za-z0-9-_]+)*\b",
+            lambda m: m.group(0).replace(".", "-"),
+            body,
+        )
+
     @staticmethod
     def parse_frontmatter(content: str) -> tuple[dict, str]:
         """Parse YAML frontmatter from Markdown content.
@@ -374,8 +401,15 @@ class CommandRegistrar:
 
         body = body.replace("{ARGS}", "$ARGUMENTS").replace("__AGENT__", agent_name)
 
-        # Resolve __CONTEXT_FILE__ from init-options
-        context_file = init_opts.get("context_file") or ""
+        # Resolve __CONTEXT_FILE__ from the agent-context extension config.
+        # Fall back to init-options.json for projects that haven't migrated.
+        # Local import: _load_agent_context_config lives in __init__.py which
+        # imports agents.py, so a top-level import would be circular.
+        from . import _load_agent_context_config
+        ac_cfg = _load_agent_context_config(project_root)
+        context_file = ac_cfg.get("context_file") or ""
+        if not context_file:
+            context_file = init_opts.get("context_file") or ""
         body = body.replace("__CONTEXT_FILE__", context_file)
 
         return CommandRegistrar.rewrite_project_relative_paths(body)
@@ -401,6 +435,9 @@ class CommandRegistrar:
     ) -> str:
         """Compute the on-disk command or skill name for an agent."""
         if agent_config["extension"] != "/SKILL.md":
+            format_name = agent_config.get("format_name")
+            if format_name:
+                return format_name(cmd_name)
             return cmd_name
 
         short_name = cmd_name
@@ -430,6 +467,13 @@ 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
+
     def register_commands(
         self,
         agent_name: str,
@@ -475,9 +519,11 @@ 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
@@ -509,6 +555,10 @@ class CommandRegistrar:
                 format_name = agent_config.get("format_name")
                 frontmatter["name"] = format_name(cmd_name) if format_name else cmd_name
 
+            if is_cline_ext:
+                frontmatter = self._hyphenate_frontmatter_refs(frontmatter)
+                body = self._hyphenate_body_refs(body)
+
             body = self._convert_argument_placeholder(
                 body, "$ARGUMENTS", agent_config["args"]
             )
@@ -578,7 +628,7 @@ class CommandRegistrar:
 
             registered.append(cmd_name)
 
-            for alias in cmd_info.get("aliases", []):
+            for alias in aliases:
                 alias_output_name = self._compute_output_name(
                     agent_name, alias, agent_config
                 )
@@ -902,22 +952,32 @@ 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:
-                    cmd_file = (
-                        target_dir / f"{output_name}{agent_config['extension']}"
-                    )
-                    if cmd_file.exists() or cmd_file.is_symlink():
-                        cmd_file.unlink()
-                        # For SKILL.md agents each command lives in its own
-                        # subdirectory (e.g. .agents/skills/speckit-ext-cmd/
-                        # SKILL.md).  Remove the parent dir when it becomes
-                        # empty to avoid orphaned directories.
-                        parent = cmd_file.parent
-                        if parent != target_dir and parent.exists():
-                            try:
-                                parent.rmdir()
-                            except OSError:
-                                pass
+                    for name in names_to_clean:
+                        cmd_file = (
+                            target_dir / f"{name}{agent_config['extension']}"
+                        )
+                        try:
+                            self._ensure_inside(cmd_file, target_dir)
+                        except ValueError:
+                            continue
+                        if cmd_file.exists() or cmd_file.is_symlink():
+                            cmd_file.unlink()
+                            # For SKILL.md agents each command lives in its own
+                            # subdirectory (e.g. .agents/skills/speckit-ext-cmd/
+                            # SKILL.md).  Remove the parent dir when it becomes
+                            # empty to avoid orphaned directories.
+                            parent = cmd_file.parent
+                            if parent != target_dir and parent.exists():
+                                try:
+                                    parent.rmdir()
+                                except OSError:
+                                    pass
 
                 if agent_name == "copilot":
                     prompt_file = (

src/specify_cli/commands/extension.py

@@ -1,2 +0,0 @@
-"""specify extension * commands — placeholder for future extraction."""
-from __future__ import annotations

src/specify_cli/commands/init.py

@@ -151,12 +151,15 @@ 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,
-            _write_integration_json,
+            _update_agent_context_config_file,
             ensure_executable_scripts,
             save_init_options,
         )
+        from ..integrations._commands import (
+            _parse_integration_options,
+            _write_integration_json,
+        )
         from ..integration_runtime import with_integration_setting as _with_integration_setting
 
         show_banner()
@@ -394,6 +397,7 @@ 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)
@@ -535,13 +539,10 @@ 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(),
@@ -551,6 +552,47 @@ 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
@@ -686,6 +728,7 @@ 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:
@@ -709,7 +752,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:
+            if cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode or cline_skill_mode:
                 return f"/speckit-{name}"
             return f"/speckit.{name}"
 

src/specify_cli/commands/integration.py

@@ -1,2 +0,0 @@
-"""specify integration * commands — placeholder for future extraction."""
-from __future__ import annotations

src/specify_cli/commands/preset.py

@@ -1,2 +0,0 @@
-"""specify preset * commands — placeholder for future extraction."""
-from __future__ import annotations

src/specify_cli/commands/workflow.py

@@ -1,2 +0,0 @@
-"""specify workflow * commands — placeholder for future extraction."""
-from __future__ import annotations

src/specify_cli/extensions.py

@@ -761,7 +761,28 @@ class ExtensionManager:
         if not ignore_file.exists():
             return None
 
-        lines: List[str] = ignore_file.read_text().splitlines()
+        # Pin UTF-8 explicitly: ``Path.read_text`` defaults to the system
+        # locale codec on Windows (cp1252 / gb2312 / cp932), which silently
+        # corrupts multibyte patterns when the file is shared across
+        # machines with different locales. The next line already
+        # normalises backslashes "so Windows-authored files work" — the
+        # codebase already expects Windows authors to write this file.
+        #
+        # A file that is not valid UTF-8 is a user-authoring mistake, so
+        # surface it as ``ValidationError`` with a pointer to the offending
+        # byte — the same pattern ``ExtensionManifest._load_yaml`` uses
+        # for ``extension.yml`` (see ``UnicodeDecodeError`` handler in
+        # this module). Without the wrap, the raw ``UnicodeDecodeError``
+        # would abort installation with a Python traceback instead of a
+        # clear message naming the file.
+        try:
+            raw = ignore_file.read_text(encoding="utf-8")
+        except UnicodeDecodeError as e:
+            raise ValidationError(
+                f".extensionignore is not valid UTF-8: {ignore_file} "
+                f"({e.reason} at byte {e.start})"
+            )
+        lines: List[str] = raw.splitlines()
 
         # Normalise backslashes in patterns so Windows-authored files work
         normalised: List[str] = []
@@ -1728,13 +1749,59 @@ class ExtensionCatalog(CatalogStackBase):
         from specify_cli.authentication.http import build_request
         return build_request(url)
 
-    def _open_url(self, url: str, timeout: int = 10):
+    def _open_url(
+        self,
+        url: str,
+        timeout: int = 10,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ):
         """Open a URL with provider-based auth, trying each configured provider.
 
         Delegates to :func:`specify_cli.authentication.http.open_url`.
         """
         from specify_cli.authentication.http import open_url
-        return open_url(url, timeout)
+        return open_url(url, timeout, extra_headers=extra_headers)
+
+    def _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.
@@ -2134,9 +2201,15 @@ 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) as response:
+            with self._open_url(download_url, timeout=60, extra_headers=extra_headers) as response:
                 zip_data = response.read()
 
             zip_path.write_bytes(zip_data)
@@ -2413,6 +2486,7 @@ class HookExecutor:
         claude_skill_mode = selected_ai == "claude" and bool(init_options.get("ai_skills"))
         kimi_skill_mode = selected_ai == "kimi"
         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:
@@ -2423,6 +2497,10 @@ class HookExecutor:
             return f"/skill:{skill_name}"
         if cursor_skill_mode and skill_name:
             return f"/{skill_name}"
+        if cline_mode:
+            from .integrations.cline import format_cline_command_name
+
+            return f"/{format_cline_command_name(command_id)}"
 
         return f"/{command_id}"
 

src/specify_cli/integrations/__init__.py

@@ -52,6 +52,7 @@ def _register_builtins() -> None:
     from .auggie import AuggieIntegration
     from .bob import BobIntegration
     from .claude import ClaudeIntegration
+    from .cline import ClineIntegration
     from .codebuddy import CodebuddyIntegration
     from .codex import CodexIntegration
     from .copilot import CopilotIntegration
@@ -85,6 +86,7 @@ def _register_builtins() -> None:
     _register(AuggieIntegration())
     _register(BobIntegration())
     _register(ClaudeIntegration())
+    _register(ClineIntegration())
     _register(CodebuddyIntegration())
     _register(CodexIntegration())
     _register(CopilotIntegration())

src/specify_cli/integrations/_commands.py

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

src/specify_cli/integrations/_helpers.py

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

src/specify_cli/integrations/_install_commands.py

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

src/specify_cli/integrations/_migrate_commands.py

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

src/specify_cli/integrations/_query_commands.py

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

src/specify_cli/integrations/base.py

@@ -13,6 +13,7 @@ Provides:
 
 from __future__ import annotations
 
+import json
 import os
 import re
 import shlex
@@ -549,6 +550,91 @@ class IntegrationBase(ABC):
             lines.append(f"at {plan_path}")
         return "\n".join(lines)
 
+    @staticmethod
+    def _agent_context_extension_enabled(project_root: Path) -> bool:
+        """Return whether the bundled ``agent-context`` extension is enabled.
+
+        The extension is the single source of truth for managing coding
+        agent context/instruction files (e.g. ``CLAUDE.md``,
+        ``.github/copilot-instructions.md``).
+
+        Returns ``True`` (enabled) when:
+        - the extension registry does not exist (legacy project, backwards
+          compatibility), or
+        - the registry has no ``agent-context`` entry (older project layout
+          predating the extension), or
+        - the entry is present and not explicitly disabled.
+
+        Returns ``False`` only when an entry exists with ``enabled: false``.
+        """
+        registry_path = (
+            project_root / ".specify" / "extensions" / ".registry"
+        )
+        if not registry_path.exists():
+            return True
+        try:
+            data = json.loads(registry_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError, UnicodeError):
+            return True
+        if not isinstance(data, dict):
+            return True
+        extensions = data.get("extensions")
+        if not isinstance(extensions, dict):
+            return True
+        entry = extensions.get("agent-context")
+        if not isinstance(entry, dict):
+            return True
+        return entry.get("enabled", True) is not False
+
+    def _resolve_context_markers(self, project_root: Path) -> tuple[str, str]:
+        """Return the (start, end) context markers to use for *project_root*.
+
+        Reads ``context_markers.start`` / ``context_markers.end`` from the
+        agent-context extension config
+        (``.specify/extensions/agent-context/agent-context-config.yml``)
+        when present.  Falls back to the class-level constants
+        ``CONTEXT_MARKER_START`` / ``CONTEXT_MARKER_END`` when the file is
+        missing, the section is absent, or the values are not non-empty
+        strings.
+        """
+        from .._console import console  # local import to avoid cycles
+
+        start = self.CONTEXT_MARKER_START
+        end = self.CONTEXT_MARKER_END
+        config_path = (
+            project_root
+            / ".specify"
+            / "extensions"
+            / "agent-context"
+            / "agent-context-config.yml"
+        )
+        try:
+            raw = config_path.read_text(encoding="utf-8")
+            cfg = yaml.safe_load(raw)
+        except (OSError, UnicodeError, ValueError, yaml.YAMLError):
+            return start, end
+        markers = cfg.get("context_markers") if isinstance(cfg, dict) else None
+        if isinstance(markers, dict):
+            cm_start = markers.get("start")
+            cm_end = markers.get("end")
+            s_valid = isinstance(cm_start, str) and cm_start
+            e_valid = isinstance(cm_end, str) and cm_end
+            if not s_valid and cm_start is not None:
+                console.print(
+                    f"[yellow]agent-context: ignoring invalid context_markers.start "
+                    f"({cm_start!r}), using default[/yellow]"
+                )
+            if not e_valid and cm_end is not None:
+                console.print(
+                    f"[yellow]agent-context: ignoring invalid context_markers.end "
+                    f"({cm_end!r}), using default[/yellow]"
+                )
+            if s_valid:
+                start = cm_start  # type: ignore[assignment]
+            if e_valid:
+                end = cm_end  # type: ignore[assignment]
+        return start, end
+
     def upsert_context_section(
         self,
         project_root: Path,
@@ -557,34 +643,54 @@ class IntegrationBase(ABC):
         """Create or update the managed section in the agent context file.
 
         If the context file does not exist it is created with just the
-        managed section.  If it exists, the content between
-        ``<!-- SPECKIT START -->`` and ``<!-- SPECKIT END -->`` markers
-        is replaced (or appended when no markers are found).
+        managed section.  If it exists, the content between the configured
+        start/end markers (default ``<!-- SPECKIT START -->`` /
+        ``<!-- SPECKIT END -->``) is replaced, or appended when no markers
+        are found. Markers are read from the agent-context extension config
+        (``.specify/extensions/agent-context/agent-context-config.yml``)
+        when present, falling back to the class-level constants.
 
         Returns the path to the context file, or ``None`` when
-        ``context_file`` is not set.
+        ``context_file`` is not set or the ``agent-context`` extension is
+        disabled.
         """
         if not self.context_file:
             return None
 
+        if not self._agent_context_extension_enabled(project_root):
+            return None
+
+        from .._console import console  # local import to avoid cycles
+
+        console.print(
+            "[yellow]Deprecation:[/yellow] Inline agent-context updates during "
+            "integration setup will be disabled in v0.12.0. Context file "
+            "management has moved to the bundled [bold]agent-context[/bold] "
+            "extension. Run [cyan]specify extension disable agent-context[/cyan] "
+            "to opt out early.",
+            highlight=False,
+        )
+
+        marker_start, marker_end = self._resolve_context_markers(project_root)
+
         ctx_path = project_root / self.context_file
         section = (
-            f"{self.CONTEXT_MARKER_START}\n"
+            f"{marker_start}\n"
             f"{self._build_context_section(plan_path)}\n"
-            f"{self.CONTEXT_MARKER_END}\n"
+            f"{marker_end}\n"
         )
 
         if ctx_path.exists():
             content = ctx_path.read_text(encoding="utf-8-sig")
-            start_idx = content.find(self.CONTEXT_MARKER_START)
+            start_idx = content.find(marker_start)
             end_idx = content.find(
-                self.CONTEXT_MARKER_END,
+                marker_end,
                 start_idx if start_idx != -1 else 0,
             )
 
             if start_idx != -1 and end_idx != -1 and end_idx > start_idx:
                 # Replace existing section (include the end marker + newline)
-                end_of_marker = end_idx + len(self.CONTEXT_MARKER_END)
+                end_of_marker = end_idx + len(marker_end)
                 # Consume trailing line ending (CRLF or LF)
                 if end_of_marker < len(content) and content[end_of_marker] == "\r":
                     end_of_marker += 1
@@ -596,7 +702,7 @@ class IntegrationBase(ABC):
                 new_content = content[:start_idx] + section
             elif end_idx != -1:
                 # Corrupted: end marker without start — replace BOF through end marker
-                end_of_marker = end_idx + len(self.CONTEXT_MARKER_END)
+                end_of_marker = end_idx + len(marker_end)
                 if end_of_marker < len(content) and content[end_of_marker] == "\r":
                     end_of_marker += 1
                 if end_of_marker < len(content) and content[end_of_marker] == "\n":
@@ -630,20 +736,27 @@ class IntegrationBase(ABC):
         """Remove the managed section from the agent context file.
 
         Returns ``True`` if the section was found and removed.  If the
-        file becomes empty (or whitespace-only) after removal it is
-        deleted.
+        file becomes empty (or whitespace-only) after removal it is deleted.
+        Markers are read from the agent-context extension config
+        (``.specify/extensions/agent-context/agent-context-config.yml``)
+        when present, falling back to the class-level constants.
         """
         if not self.context_file:
             return False
 
+        if not self._agent_context_extension_enabled(project_root):
+            return False
+
         ctx_path = project_root / self.context_file
         if not ctx_path.exists():
             return False
 
+        marker_start, marker_end = self._resolve_context_markers(project_root)
+
         content = ctx_path.read_text(encoding="utf-8-sig")
-        start_idx = content.find(self.CONTEXT_MARKER_START)
+        start_idx = content.find(marker_start)
         end_idx = content.find(
-            self.CONTEXT_MARKER_END,
+            marker_end,
             start_idx if start_idx != -1 else 0,
         )
 
@@ -654,7 +767,7 @@ class IntegrationBase(ABC):
             return False
 
         removal_start = start_idx
-        removal_end = end_idx + len(self.CONTEXT_MARKER_END)
+        removal_end = end_idx + len(marker_end)
 
         # Consume trailing line ending (CRLF or LF)
         if removal_end < len(content) and content[removal_end] == "\r":

src/specify_cli/integrations/cline/__init__.py

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

src/specify_cli/integrations/copilot/__init__.py

@@ -283,58 +283,13 @@ class CopilotIntegration(IntegrationBase):
         return f"speckit.{template_name}.agent.md"
 
     def post_process_skill_content(self, content: str) -> str:
-        """Inject shared hook guidance and Copilot ``mode:`` frontmatter.
+        """Inject shared hook guidance into Copilot skill content.
 
-        Inserts ``mode: speckit.<stem>`` before the closing ``---`` so
-        Copilot can associate the skill with its agent mode.
+        Delegates to :class:`_CopilotSkillsHelper` for shared post-processing.
+        The ``mode:`` frontmatter field is intentionally omitted: VS Code
+        Copilot Agent Skills do not support it (see issue #2799).
         """
-        updated = _CopilotSkillsHelper().post_process_skill_content(content)
-        lines = updated.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 updated  # 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 updated
-
-        # Inject mode: before the closing --- of frontmatter
-        out: list[str] = []
-        dash_count = 0
-        injected = False
-        for line in lines:
-            stripped = line.rstrip("\n\r")
-            if stripped == "---":
-                dash_count += 1
-                if dash_count == 2 and not injected:
-                    if line.endswith("\r\n"):
-                        eol = "\r\n"
-                    elif line.endswith("\n"):
-                        eol = "\n"
-                    else:
-                        eol = ""
-                    out.append(f"mode: {skill_name}{eol}")
-                    injected = True
-            out.append(line)
-        return "".join(out)
+        return _CopilotSkillsHelper().post_process_skill_content(content)
 
     def setup(
         self,

src/specify_cli/integrations/manifest.py

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

src/specify_cli/shared_infra.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+import re
 import tempfile
 from pathlib import Path
 from typing import Any
@@ -194,6 +195,37 @@ def _write_shared_bytes(
             temp_path.unlink()
 
 
+_BASH_FORMAT_COMMAND_RE = re.compile(
+    r"\$\(\s*format_speckit_command\s+(['\"]?)([A-Za-z0-9_.-]+)\1(?:\s+[^)]*)?\)"
+)
+_POWERSHELL_FORMAT_COMMAND_RE = re.compile(
+    r"Format-SpecKitCommand\s+-CommandName\s+(['\"])([A-Za-z0-9_.-]+)\1(?:\s+-RepoRoot\s+[^\r\n]+)?"
+)
+
+
+def _format_speckit_command(command_name: str, separator: str) -> str:
+    name = command_name.strip().lstrip("/")
+    if name.startswith("speckit."):
+        name = name[len("speckit.") :]
+    elif name.startswith("speckit-"):
+        name = name[len("speckit-") :]
+    name = name.replace(".", separator)
+    return f"/speckit{separator}{name}"
+
+
+def _resolve_dynamic_command_refs(content: str, separator: str) -> str:
+    """Render script runtime command helpers for managed shared infra copies."""
+
+    content = _BASH_FORMAT_COMMAND_RE.sub(
+        lambda match: _format_speckit_command(match.group(2), separator),
+        content,
+    )
+    return _POWERSHELL_FORMAT_COMMAND_RE.sub(
+        lambda match: f"'{_format_speckit_command(match.group(2), separator)}'",
+        content,
+    )
+
+
 def refresh_shared_templates(
     project_path: Path,
     *,
@@ -365,12 +397,30 @@ 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")
                         content = IntegrationBase.resolve_command_refs(content, invoke_separator)
+                        content = _resolve_dynamic_command_refs(content, invoke_separator)
                         planned_copies.append(
                             (
                                 dst_path,
@@ -398,6 +448,23 @@ def install_shared_infra(
                         preserved_user_files.append(rel)
                     else:
                         skipped_files.append(rel)
+                        # Record the existing-on-disk template in the manifest so a
+                        # fresh manifest run against an already-populated
+                        # ``.specify/`` tree does not silently drop it (#2107).
+                        # ``prior_hashes`` is the function-scope snapshot taken at
+                        # entry, so this membership check is O(1) and avoids the
+                        # repeated ``dict(self._files)`` copy that ``manifest.files``
+                        # performs on every access.
+                        if dst.is_file() and rel not in prior_hashes:
+                            try:
+                                manifest.record_existing(rel, recovered=True)
+                            except (OSError, ValueError) as exc:
+                                # Tolerate races / permission issues / non-file
+                                # collisions so one weird path does not abort
+                                # the whole install.
+                                console.print(
+                                    f"[yellow]⚠[/yellow]  could not record {rel} in manifest: {exc}"
+                                )
                     continue
 
                 content = src.read_text(encoding="utf-8")
@@ -416,7 +483,7 @@ def install_shared_infra(
 
     if skipped_files:
         console.print(
-            f"[yellow]⚠[/yellow]  {len(skipped_files)} shared infrastructure file(s) already exist and were not updated:"
+            f"[yellow]⚠[/yellow]  {len(skipped_files)} shared infrastructure path(s) already exist and were not updated:"
         )
         for path in skipped_files:
             console.print(f"    {path}")

src/specify_cli/workflows/engine.py

@@ -232,6 +232,22 @@ def _validate_steps(
             step_errors = step_impl.validate(step_config)
             errors.extend(step_errors)
 
+        # Validate optional `continue_on_error` field. The engine honours
+        # this on any step that returns StepStatus.FAILED so the pipeline can route
+        # around the failure via a downstream `if` or `switch` (or a
+        # `gate` that surfaces the failure to the operator via message
+        # interpolation). The field must be a literal boolean —
+        # coercion from truthy strings is deliberately not supported so
+        # authoring mistakes surface at validation time rather than
+        # silently changing run semantics.
+        if "continue_on_error" in step_config:
+            coe = step_config["continue_on_error"]
+            if not isinstance(coe, bool):
+                errors.append(
+                    f"Step {step_id!r}: 'continue_on_error' must be a "
+                    f"boolean, got {type(coe).__name__}."
+                )
+
         # Recursively validate nested steps
         for nested_key in ("then", "else", "steps"):
             nested = step_config.get(nested_key)
@@ -265,16 +281,49 @@ def _validate_steps(
 class RunState:
     """Manages workflow run state for persistence and resume."""
 
+    # ``run_id`` is interpolated into a filesystem path (``runs/<run_id>``)
+    # by both ``save()`` and ``load()``. Constrain it to a charset that
+    # cannot contain path separators (``/`` ``\``), parent-directory
+    # segments (``..``), or NULs — anything that could escape the
+    # ``.specify/workflows/runs/`` directory or be mis-interpreted by the
+    # filesystem. The first-character anchor blocks IDs that start with
+    # ``-`` (which would be mistaken for a CLI flag in error messages
+    # and shell completions).
+    _RUN_ID_PATTERN = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$")
+
+    @classmethod
+    def _validate_run_id(cls, run_id: str) -> None:
+        """Raise ``ValueError`` if ``run_id`` is not a safe path component.
+
+        This is the single source of truth for what counts as a valid
+        ``run_id``. ``__init__`` calls it to reject malformed IDs at
+        construction time; ``load`` calls it *before* interpolating the
+        ID into a path so a malicious value cannot probe or read files
+        outside ``.specify/workflows/runs/<run_id>/``.
+        """
+        if not isinstance(run_id, str) or not cls._RUN_ID_PATTERN.match(run_id):
+            raise ValueError(
+                f"Invalid run_id {run_id!r}: must be alphanumeric with "
+                "hyphens/underscores only (and must start with an "
+                "alphanumeric character)."
+            )
+
     def __init__(
         self,
         run_id: str | None = None,
         workflow_id: str = "",
         project_root: Path | None = None,
     ) -> None:
-        self.run_id = run_id or str(uuid.uuid4())[:8]
-        if not re.match(r'^[a-zA-Z0-9][a-zA-Z0-9_-]*$', self.run_id):
-            msg = f"Invalid run_id {self.run_id!r}: must be alphanumeric with hyphens/underscores only."
-            raise ValueError(msg)
+        # ``run_id is None`` (omitted) → auto-generate. An explicit empty
+        # string is *not* the same as "omitted" and must be validated like
+        # any other caller-provided value — otherwise ``__init__("")``
+        # would silently substitute a UUID while ``load("")`` rejects, and
+        # the two entry points would diverge on the empty-string vector.
+        if run_id is None:
+            self.run_id = str(uuid.uuid4())[:8]
+        else:
+            self.run_id = run_id
+        self._validate_run_id(self.run_id)
         self.workflow_id = workflow_id
         self.project_root = project_root or Path(".")
         self.status = RunStatus.CREATED
@@ -315,7 +364,20 @@ class RunState:
 
     @classmethod
     def load(cls, run_id: str, project_root: Path) -> RunState:
-        """Load a run state from disk."""
+        """Load a run state from disk.
+
+        Validates ``run_id`` against ``_RUN_ID_PATTERN`` *before* building
+        the lookup path. Without this guard, a caller passing a value like
+        ``../escape`` (e.g. via ``specify workflow resume`` CLI argument)
+        would interpolate path-traversal segments into
+        ``runs_dir`` below, letting ``state_path.exists()`` probe arbitrary
+        paths and ``json.load`` read attacker-planted JSON from outside
+        the project's ``runs/`` directory. ``__init__`` already runs this
+        check on the stored ``state_data["run_id"]``, but that fires
+        *after* the file lookup — too late to prevent the disclosure.
+        Mirrors the precedent in ``agents._ensure_within_directory``.
+        """
+        cls._validate_run_id(run_id)
         runs_dir = project_root / ".specify" / "workflows" / "runs" / run_id
         state_path = runs_dir / "state.json"
         if not state_path.exists():
@@ -491,8 +553,19 @@ class WorkflowEngine:
         state.save()
         return state
 
-    def resume(self, run_id: str) -> RunState:
-        """Resume a paused or failed workflow run."""
+    def resume(
+        self,
+        run_id: str,
+        inputs: dict[str, Any] | None = None,
+    ) -> RunState:
+        """Resume a paused or failed workflow run.
+
+        When ``inputs`` is provided, the values are merged over the run's
+        persisted inputs and re-resolved through the same typed validation
+        path used by :meth:`execute`, so the resumed step sees updated
+        workflow inputs. Keys not supplied keep their persisted values; an
+        empty/``None`` ``inputs`` leaves the run's inputs unchanged.
+        """
         state = RunState.load(run_id, self.project_root)
         if state.status not in (RunStatus.PAUSED, RunStatus.FAILED):
             msg = f"Cannot resume run {run_id!r} with status {state.status.value!r}."
@@ -508,6 +581,12 @@ class WorkflowEngine:
         else:
             definition = self.load_workflow(state.workflow_id)
 
+        # Merge any newly-supplied inputs over the persisted ones and
+        # re-validate through the same typing path as the initial run.
+        if inputs:
+            merged = {**state.inputs, **inputs}
+            state.inputs = self._resolve_inputs(definition, merged)
+
         # Restore context
         context = StepContext(
             inputs=state.inputs,
@@ -629,7 +708,10 @@ class WorkflowEngine:
 
             # Handle failures
             if result.status == StepStatus.FAILED:
-                # Gate abort (output.aborted) maps to ABORTED status
+                # Gate abort (output.aborted) maps to ABORTED status.
+                # Aborts are deliberate operator decisions, so
+                # `continue_on_error` does NOT override them — that flag
+                # is for transient/expected step failures only.
                 if result.output.get("aborted"):
                     state.status = RunStatus.ABORTED
                     state.append_log(
@@ -638,15 +720,49 @@ class WorkflowEngine:
                             "step_id": step_id,
                         }
                     )
-                else:
-                    state.status = RunStatus.FAILED
+                    state.save()
+                    return
+
+                # `continue_on_error: true` lets the pipeline route
+                # around the failure instead of halting. The step
+                # result (including exit_code, stderr, status) is
+                # still recorded so a downstream `if` or `switch`
+                # can branch on it (or a `gate` can surface it to the
+                # operator via message interpolation). Log a single,
+                # unambiguous event per failure resolution — either
+                # the run continued past it, or it halted.
+                #
+                # Use identity comparison (`is True`) rather than
+                # truthiness so that only a literal boolean enables
+                # the behaviour, even if validation was skipped.
+                # Validation rejects non-bool values at parse time,
+                # but `WorkflowEngine.execute()` does not auto-validate
+                # (see `WorkflowEngine.load_workflow`, whose docstring
+                # explicitly notes "not yet validated; call
+                # `validate_workflow()` or `engine.validate()`
+                # separately"), so a caller passing an unvalidated
+                # definition could otherwise see truthy non-bool
+                # values like the string `"true"` silently change
+                # run semantics.
+                if step_config.get("continue_on_error") is True:
                     state.append_log(
                         {
-                            "event": "step_failed",
+                            "event": "step_continue_on_error",
                             "step_id": step_id,
                             "error": result.error,
                         }
                     )
+                    state.save()
+                    continue
+
+                state.status = RunStatus.FAILED
+                state.append_log(
+                    {
+                        "event": "step_failed",
+                        "step_id": step_id,
+                        "error": result.error,
+                    }
+                )
                 state.save()
                 return
 

templates/commands/checklist.md

@@ -74,7 +74,9 @@ 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. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
+2. **IF EXISTS**: Load `/memory/constitution.md` for project principles and governance constraints.
+
+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`
@@ -106,13 +108,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.
 
-3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
+4. **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)
 
-4. **Load feature context**: Read from FEATURE_DIR:
+5. **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
@@ -123,7 +125,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
 
-5. **Generate checklist** - Create "Unit Tests for Requirements":
+6. **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`)
@@ -241,9 +243,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]?"
 
-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.
+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.
 
-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:
+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:
    - Focus areas selected
    - Depth level
    - Actor/timing

templates/commands/clarify.md

@@ -66,7 +66,9 @@ 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. 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).
+2. **IF EXISTS**: Load `/memory/constitution.md` for project principles and governance constraints.
+
+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
@@ -122,7 +124,7 @@ Execution steps:
    - Clarification would not materially change implementation or validation strategy
    - Information is better deferred to planning phase (note internally)
 
-3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+4. 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
@@ -133,7 +135,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.
 
-4. Sequential questioning loop (interactive):
+5. 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:
@@ -169,7 +171,7 @@ Execution steps:
     - Never reveal future queued questions in advance.
     - If no valid questions exist at start, immediately report no critical ambiguities.
 
-5. Integration after EACH accepted answer (incremental update approach):
+6. 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).
@@ -187,7 +189,7 @@ Execution steps:
     - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
     - Keep each inserted clarification minimal and testable (avoid narrative drift).
 
-6. Validation (performed after EACH write plus final pass):
+7. 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.
@@ -195,9 +197,9 @@ Execution steps:
    - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
    - Terminology consistency: same canonical term used across all updated sections.
 
-7. Write the updated spec back to `FEATURE_SPEC`.
+8. Write the updated spec back to `FEATURE_SPEC`.
 
-8. **Re-validate Spec Quality Checklist** (if it exists):
+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:

templates/commands/plan.md

@@ -147,7 +147,14 @@ 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. **Agent context update**:
+3. **Create quickstart validation guide** → `quickstart.md`:
+   - 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

templates/commands/specify.md

@@ -91,7 +91,8 @@ Given that feature description, do this:
 
    **Create the directory and spec file**:
    - `mkdir -p SPECIFY_FEATURE_DIRECTORY`
-   - Copy `templates/spec-template.md` to `SPECIFY_FEATURE_DIRECTORY/spec.md` as the starting point
+   - Resolve the active `spec-template` through the Spec Kit preset/template resolution stack (equivalent to `specify preset resolve spec-template`)
+   - 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
@@ -107,9 +108,11 @@ 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 `templates/spec-template.md` to understand required sections.
+4. Load the resolved active `spec-template` file to understand required sections.
 
-5. Follow this execution flow:
+5. **IF EXISTS**: Load `/memory/constitution.md` for project principles and governance constraints.
+
+6. Follow this execution flow:
     1. Parse user description from arguments
        If empty: ERROR "No feature description provided"
     2. Extract key concepts from description

templates/commands/tasks.md

@@ -63,6 +63,7 @@ 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**:

templates/commands/taskstoissues.md

@@ -51,6 +51,7 @@ 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:
 

tests/conftest.py

@@ -81,3 +81,72 @@ 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")
+    )

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 = [l for l in result.stdout.splitlines() if l.strip().startswith("{")]
+        json_line = [ln for ln in result.stdout.splitlines() if ln.strip().startswith("{")]
         assert json_line, f"No JSON in output: {result.stdout}"
         data = json.loads(json_line[-1])
         assert "BRANCH_NAME" in data

tests/extensions/test_extension_agent_context.py

@@ -0,0 +1,455 @@
+"""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

tests/http_helpers.py

@@ -0,0 +1,15 @@
+"""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

tests/integrations/test_cli.py

@@ -87,7 +87,14 @@ class TestInitIntegrationFlag:
 
         opts = json.loads((project / ".specify" / "init-options.json").read_text(encoding="utf-8"))
         assert opts["integration"] == "copilot"
-        assert opts["context_file"] == ".github/copilot-instructions.md"
+        # context_file lives in the agent-context extension config, not init-options.json
+        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()
 
@@ -323,6 +330,7 @@ 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()

tests/integrations/test_integration_agy.py

@@ -131,5 +131,5 @@ class TestAgyHookCommandNote:
         )
         result = AgyIntegration._inject_hook_command_note(content)
         lines = result.splitlines()
-        note_line = [l for l in lines if "replace dots" in l][0]
+        note_line = [ln for ln in lines if "replace dots" in ln][0]
         assert note_line.startswith("   "), "Note should preserve indentation"

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):
-        """init-options.json must include context_file for the active integration."""
-        import json
+        """agent-context extension config must include context_file for the active integration."""
+        import yaml
         from typer.testing import CliRunner
         from specify_cli import app
 
@@ -243,15 +243,17 @@ class MarkdownIntegrationTests:
         finally:
             os.chdir(old_cwd)
         assert result.exit_code == 0
-        opts = json.loads((project / ".specify" / "init-options.json").read_text())
+        ext_cfg_path = project / ".specify" / "extensions" / "agent-context" / "agent-context-config.yml"
+        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 opts.get("context_file") == i.context_file, (
-            f"Expected context_file={i.context_file!r}, got {opts.get('context_file')!r}"
+        assert ext_cfg.get("context_file") == i.context_file, (
+            f"Expected context_file={i.context_file!r}, got {ext_cfg.get('context_file')!r}"
         )
 
     # -- Complete file inventory ------------------------------------------
 
     COMMAND_STEMS = [
+        "agent-context.update",
         "analyze", "checklist", "clarify", "constitution",
         "implement", "plan", "specify", "tasks", "taskstoissues",
     ]
@@ -267,10 +269,10 @@ class MarkdownIntegrationTests:
             files.append(f"{cmd_dir}/speckit.{stem}.md")
 
         # Framework files
-        files.append(f".specify/integration.json")
-        files.append(f".specify/init-options.json")
+        files.append(".specify/integration.json")
+        files.append(".specify/init-options.json")
         files.append(f".specify/integrations/{self.KEY}.manifest.json")
-        files.append(f".specify/integrations/speckit.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",
@@ -291,6 +293,16 @@ 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)

tests/integrations/test_integration_base_skills.py

@@ -357,8 +357,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):
-        """init-options.json must include context_file for the active integration."""
-        import json
+        """agent-context extension config must include context_file for the active integration."""
+        import yaml
         from typer.testing import CliRunner
         from specify_cli import app
 
@@ -374,10 +374,11 @@ class SkillsIntegrationTests:
         finally:
             os.chdir(old_cwd)
         assert result.exit_code == 0
-        opts = json.loads((project / ".specify" / "init-options.json").read_text())
+        ext_cfg_path = project / ".specify" / "extensions" / "agent-context" / "agent-context-config.yml"
+        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 opts.get("context_file") == i.context_file, (
-            f"Expected context_file={i.context_file!r}, got {opts.get('context_file')!r}"
+        assert ext_cfg.get("context_file") == i.context_file, (
+            f"Expected context_file={i.context_file!r}, got {ext_cfg.get('context_file')!r}"
         )
 
     # -- IntegrationOption ------------------------------------------------
@@ -402,9 +403,11 @@ class SkillsIntegrationTests:
         skills_prefix = i.config["folder"].rstrip("/") + "/" + i.config.get("commands_subdir", "skills")
 
         files = []
-        # Skill files
+        # Skill files (core commands)
         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",
@@ -443,6 +446,15 @@ 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)

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):
-        """init-options.json must include context_file for the active integration."""
-        import json
+        """agent-context extension config must include context_file for the active integration."""
+        import yaml
         from typer.testing import CliRunner
         from specify_cli import app
 
@@ -474,15 +474,17 @@ class TomlIntegrationTests:
         finally:
             os.chdir(old_cwd)
         assert result.exit_code == 0
-        opts = json.loads((project / ".specify" / "init-options.json").read_text())
+        ext_cfg_path = project / ".specify" / "extensions" / "agent-context" / "agent-context-config.yml"
+        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 opts.get("context_file") == i.context_file, (
-            f"Expected context_file={i.context_file!r}, got {opts.get('context_file')!r}"
+        assert ext_cfg.get("context_file") == i.context_file, (
+            f"Expected context_file={i.context_file!r}, got {ext_cfg.get('context_file')!r}"
         )
 
     # -- Complete file inventory ------------------------------------------
 
     COMMAND_STEMS = [
+        "agent-context.update",
         "analyze",
         "checklist",
         "clarify",
@@ -543,6 +545,16 @@ 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)

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 = [l for l in lines if not l.startswith("# Source:")]
+            yaml_lines = [ln for ln in lines if not ln.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 = [l for l in lines if not l.startswith("# Source:")]
+        yaml_lines = [ln for ln in lines if not ln.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):
-        """init-options.json must include context_file for the active integration."""
-        import json
+        """agent-context extension config must include context_file for the active integration."""
+        import yaml
         from typer.testing import CliRunner
         from specify_cli import app
 
@@ -353,15 +353,17 @@ class YamlIntegrationTests:
         finally:
             os.chdir(old_cwd)
         assert result.exit_code == 0
-        opts = json.loads((project / ".specify" / "init-options.json").read_text())
+        ext_cfg_path = project / ".specify" / "extensions" / "agent-context" / "agent-context-config.yml"
+        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 opts.get("context_file") == i.context_file, (
-            f"Expected context_file={i.context_file!r}, got {opts.get('context_file')!r}"
+        assert ext_cfg.get("context_file") == i.context_file, (
+            f"Expected context_file={i.context_file!r}, got {ext_cfg.get('context_file')!r}"
         )
 
     # -- Complete file inventory ------------------------------------------
 
     COMMAND_STEMS = [
+        "agent-context.update",
         "analyze",
         "checklist",
         "clarify",
@@ -422,6 +424,16 @@ 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)

tests/integrations/test_integration_claude.py

@@ -3,6 +3,7 @@
 import codecs
 import json
 import os
+from pathlib import Path
 from unittest.mock import patch
 
 import yaml
@@ -577,3 +578,204 @@ 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"
+        )

tests/integrations/test_integration_cline.py

@@ -0,0 +1,223 @@
+"""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)

tests/integrations/test_integration_copilot.py

@@ -147,6 +147,21 @@ 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
@@ -178,6 +193,7 @@ 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",
@@ -187,6 +203,7 @@ 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",
@@ -198,6 +215,14 @@ 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",
@@ -238,6 +263,7 @@ 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",
@@ -247,6 +273,7 @@ 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",
@@ -258,6 +285,14 @@ 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",
@@ -391,8 +426,8 @@ class TestCopilotSkillsMode:
 
     # -- Copilot-specific post-processing ---------------------------------
 
-    def test_post_process_skill_content_injects_mode(self):
-        """post_process_skill_content() should inject mode: field."""
+    def test_post_process_skill_content_does_not_inject_mode(self):
+        """post_process_skill_content() must NOT inject mode: — VS Code Copilot does not support it."""
         copilot = self._make_copilot()
         content = (
             "---\n"
@@ -402,10 +437,10 @@ class TestCopilotSkillsMode:
             "\nBody content\n"
         )
         updated = copilot.post_process_skill_content(content)
-        assert "mode: speckit.plan" in updated
+        assert "mode:" not in updated
 
     def test_post_process_skill_content_injects_hook_note(self):
-        """post_process_skill_content() should inject shared hook guidance."""
+        """post_process_skill_content() should inject shared hook guidance but not mode:."""
         copilot = self._make_copilot()
         content = (
             "---\n"
@@ -416,7 +451,7 @@ class TestCopilotSkillsMode:
         )
         updated = copilot.post_process_skill_content(content)
         assert "replace dots" in updated
-        assert "mode: speckit.specify" in updated
+        assert "mode:" not in updated
 
     def test_post_process_idempotent(self):
         """post_process_skill_content() must be idempotent."""
@@ -432,8 +467,8 @@ class TestCopilotSkillsMode:
         second = copilot.post_process_skill_content(first)
         assert first == second
 
-    def test_skills_have_mode_in_frontmatter(self, tmp_path):
-        """Generated SKILL.md files should have mode: field from post-processing."""
+    def test_skills_do_not_have_mode_in_frontmatter(self, tmp_path):
+        """Generated SKILL.md files must NOT contain mode: — VS Code Copilot does not support it."""
         copilot = self._make_copilot()
         created, _ = self._setup_skills(copilot, tmp_path)
         skill_files = [f for f in created if f.name == "SKILL.md"]
@@ -442,11 +477,7 @@ class TestCopilotSkillsMode:
             content = f.read_text(encoding="utf-8")
             parts = content.split("---", 2)
             fm = yaml.safe_load(parts[1])
-            assert "mode" in fm, f"{f} frontmatter missing 'mode'"
-            # mode should be speckit.<stem>
-            skill_dir_name = f.parent.name
-            stem = skill_dir_name.removeprefix("speckit-")
-            assert fm["mode"] == f"speckit.{stem}"
+            assert "mode" not in fm, f"{f} frontmatter must not contain unsupported 'mode' field"
 
     def test_skills_hook_sections_explain_dotted_command_conversion(self, tmp_path):
         """Generated skills with hook sections should include shared hook guidance."""
@@ -624,10 +655,20 @@ 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
+            # Skill files (core + extension-installed agent-context command)
             *[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",

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

tests/integrations/test_integration_generic.py

@@ -185,6 +185,20 @@ class TestGenericIntegration:
         )
         assert "__CONTEXT_FILE__" not in content
 
+    def test_plan_defines_quickstart_as_validation_guide(self, tmp_path):
+        """The generated plan command should keep quickstart.md out of implementation scope."""
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        plan_file = tmp_path / ".custom" / "cmds" / "speckit.plan.md"
+        assert plan_file.exists()
+        content = plan_file.read_text(encoding="utf-8")
+
+        assert "Create quickstart validation guide" in content
+        assert "runnable validation scenarios" in content
+        assert "Do not include full implementation code" in content
+        assert "implementation details belong in `tasks.md` and the implementation phase" in content
+
     def test_implement_loads_constitution_context(self, tmp_path):
         """The generated implement command should load constitution governance context."""
         i = get_integration("generic")
@@ -195,6 +209,39 @@ class TestGenericIntegration:
         content = implement_file.read_text(encoding="utf-8")
         assert ".specify/memory/constitution.md" in content
 
+    @pytest.mark.parametrize(
+        "command_stem",
+        [
+            "analyze",
+            "checklist",
+            "clarify",
+            "implement",
+            "plan",
+            "specify",
+            "tasks",
+            "taskstoissues",
+        ],
+    )
+    def test_command_loads_constitution_context(self, tmp_path, command_stem):
+        """Every command except constitution must reference constitution.md."""
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        cmd_file = tmp_path / ".custom" / "cmds" / f"speckit.{command_stem}.md"
+        assert cmd_file.exists(), f"Command file missing: {cmd_file.name}"
+        content = cmd_file.read_text(encoding="utf-8")
+        assert "constitution.md" in content, (
+            f"speckit.{command_stem}.md must reference constitution.md"
+        )
+
+    def test_constitution_command_exists(self, tmp_path):
+        """The constitution command itself must exist but is not required to load itself."""
+        i = get_integration("generic")
+        m = IntegrationManifest("generic", tmp_path)
+        i.setup(tmp_path, m, parsed_options={"commands_dir": ".custom/cmds"})
+        cmd_file = tmp_path / ".custom" / "cmds" / "speckit.constitution.md"
+        assert cmd_file.exists()
+
     # -- CLI --------------------------------------------------------------
 
     def test_cli_generic_without_commands_dir_fails(self, tmp_path):
@@ -211,8 +258,8 @@ class TestGenericIntegration:
         assert result.exit_code != 0
 
     def test_init_options_includes_context_file(self, tmp_path):
-        """init-options.json must include context_file for the generic integration."""
-        import json
+        """agent-context extension config must include context_file for the generic integration."""
+        import yaml
         from typer.testing import CliRunner
         from specify_cli import app
 
@@ -229,8 +276,9 @@ class TestGenericIntegration:
         finally:
             os.chdir(old_cwd)
         assert result.exit_code == 0
-        opts = json.loads((project / ".specify" / "init-options.json").read_text())
-        assert opts.get("context_file") == "AGENTS.md"
+        ext_cfg_path = project / ".specify" / "extensions" / "agent-context" / "agent-context-config.yml"
+        ext_cfg = yaml.safe_load(ext_cfg_path.read_text(encoding="utf-8")) if ext_cfg_path.exists() else {}
+        assert ext_cfg.get("context_file") == "AGENTS.md"
 
     def test_complete_file_inventory_sh(self, tmp_path):
         """Every file produced by specify init --integration generic --ai-commands-dir ... --script sh."""
@@ -265,6 +313,14 @@ class TestGenericIntegration:
             ".myagent/commands/speckit.specify.md",
             ".myagent/commands/speckit.tasks.md",
             ".myagent/commands/speckit.taskstoissues.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/init-options.json",
             ".specify/integration.json",
             ".specify/integrations/generic.manifest.json",
@@ -321,6 +377,14 @@ class TestGenericIntegration:
             ".myagent/commands/speckit.specify.md",
             ".myagent/commands/speckit.tasks.md",
             ".myagent/commands/speckit.taskstoissues.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/init-options.json",
             ".specify/integration.json",
             ".specify/integrations/generic.manifest.json",

tests/integrations/test_integration_hermes.py

@@ -241,10 +241,15 @@ class TestHermesIntegration(SkillsIntegrationTests):
             p.relative_to(project).as_posix()
             for p in project.rglob("*") if p.is_file()
         )
-        # Ensure no .hermes/skills/speckit-*/SKILL.md in project dir
-        hermes_skill_files = [f for f in actual if f.startswith(".hermes/skills/speckit-")]
+        # Ensure no core .hermes/skills/speckit-*/SKILL.md in project dir
+        # (extension-installed skills like agent-context-update may appear)
+        hermes_skill_files = [
+            f for f in actual
+            if f.startswith(".hermes/skills/speckit-")
+            and "agent-context" not in f
+        ]
         assert hermes_skill_files == [], (
-            f"Expected no local SKILL.md files, found: {hermes_skill_files}"
+            f"Expected no local core SKILL.md files, found: {hermes_skill_files}"
         )
         # Ensure the marker exists (empty dir won't appear in file listing)
         assert (project / ".hermes" / "skills").is_dir()
@@ -274,9 +279,15 @@ class TestHermesIntegration(SkillsIntegrationTests):
             p.relative_to(project).as_posix()
             for p in project.rglob("*") if p.is_file()
         )
-        hermes_skill_files = [f for f in actual if f.startswith(".hermes/skills/speckit-")]
+        # Ensure no core .hermes/skills/speckit-*/SKILL.md in project dir
+        # (extension-installed skills like agent-context-update may appear)
+        hermes_skill_files = [
+            f for f in actual
+            if f.startswith(".hermes/skills/speckit-")
+            and "agent-context" not in f
+        ]
         assert hermes_skill_files == [], (
-            f"Expected no local SKILL.md files, found: {hermes_skill_files}"
+            f"Expected no local core SKILL.md files, found: {hermes_skill_files}"
         )
         assert (project / ".hermes" / "skills").is_dir()
 
@@ -342,6 +353,10 @@ class TestHermesAutoPromote:
         assert (home / ".hermes" / "skills" / "speckit-plan" / "SKILL.md").exists()
         # Local marker should exist
         assert (target / ".hermes" / "skills").is_dir()
-        # No SKILL.md files in project-local dir
-        local_skills = list((target / ".hermes" / "skills").iterdir())
+        # No core SKILL.md files in project-local dir
+        # (extension-installed skills like agent-context-update may appear)
+        local_skills = [
+            d for d in (target / ".hermes" / "skills").iterdir()
+            if "agent-context" not in d.name
+        ]
         assert local_skills == [], f"Local skills dir should be empty, got: {local_skills}"

tests/integrations/test_integration_subcommand.py

@@ -3,7 +3,6 @@
 import json
 import os
 
-import pytest
 from typer.testing import CliRunner
 
 from specify_cli import app
@@ -185,7 +184,8 @@ class TestIntegrationInstall:
         finally:
             os.chdir(old_cwd)
         assert result.exit_code == 0
-        normalized = " ".join(result.output.split())
+        output = strip_ansi(result.output)
+        normalized = " ".join(output.split())
         assert "already installed" in normalized
         assert "specify integration use codex" in normalized
         assert "specify integration upgrade codex" in normalized
@@ -241,9 +241,9 @@ class TestIntegrationInstall:
         opts["speckit_version"] = "0.6.1"
         init_options.write_text(json.dumps(opts), encoding="utf-8")
 
-        import specify_cli
+        import specify_cli.integrations._commands as _int_cmds
 
-        monkeypatch.setattr(specify_cli, "get_speckit_version", lambda: "0.8.11")
+        monkeypatch.setattr(_int_cmds, "get_speckit_version", lambda: "0.8.11")
 
         result = _run_in_project(project, [
             "integration", "install", "codex",
@@ -255,7 +255,7 @@ class TestIntegrationInstall:
         assert updated["speckit_version"] == "0.8.11"
         assert updated["integration"] == "claude"
         assert updated["ai"] == "claude"
-        assert updated["context_file"] == "CLAUDE.md"
+        assert "context_file" not in updated
 
     def test_install_additional_preserves_shared_manifest(self, tmp_path):
         project = _init_project(tmp_path, "claude")
@@ -897,11 +897,10 @@ class TestIntegrationSwitch:
         assert copilot_git_feature.exists(), "Git extension skill should exist for Copilot skills mode"
         assert not copilot_agent_file.exists(), "Copilot skills mode should not create extension .agent.md files"
 
-        # Verify Copilot-specific frontmatter: mode field should map from
-        # skill name (speckit-git-feature) back to dot notation (speckit.git-feature)
+        # Verify Copilot skill frontmatter does NOT contain mode: — VS Code Copilot does not support it
         skill_content = copilot_git_feature.read_text(encoding="utf-8")
-        assert "mode: speckit.git-feature" in skill_content, (
-            "Copilot skill frontmatter should contain mode mapped from skill name"
+        assert "mode:" not in skill_content, (
+            "Copilot skill frontmatter must not contain unsupported 'mode' field"
         )
 
         registry = json.loads(
@@ -1209,9 +1208,9 @@ class TestIntegrationUpgrade:
         opts["speckit_version"] = "0.6.1"
         init_options.write_text(json.dumps(opts), encoding="utf-8")
 
-        import specify_cli
+        import specify_cli.integrations._commands as _int_cmds
 
-        monkeypatch.setattr(specify_cli, "get_speckit_version", lambda: "0.8.11")
+        monkeypatch.setattr(_int_cmds, "get_speckit_version", lambda: "0.8.11")
 
         result = _run_in_project(project, [
             "integration", "upgrade", "claude",
@@ -1235,9 +1234,9 @@ class TestIntegrationUpgrade:
         opts["speckit_version"] = "0.6.1"
         init_options.write_text(json.dumps(opts), encoding="utf-8")
 
-        import specify_cli
+        import specify_cli.integrations._commands as _int_cmds
 
-        monkeypatch.setattr(specify_cli, "get_speckit_version", lambda: "0.8.11")
+        monkeypatch.setattr(_int_cmds, "get_speckit_version", lambda: "0.8.11")
 
         result = _run_in_project(project, [
             "integration", "upgrade", "claude",
@@ -1250,7 +1249,7 @@ class TestIntegrationUpgrade:
         assert updated["speckit_version"] == "0.8.11"
         assert updated["integration"] == "gemini"
         assert updated["ai"] == "gemini"
-        assert updated["context_file"] == "GEMINI.md"
+        assert "context_file" not in updated
 
     def test_upgrade_does_not_persist_state_when_shared_infra_refresh_fails(self, tmp_path, monkeypatch):
         project = _init_project(tmp_path, "claude")
@@ -1376,11 +1375,16 @@ class TestIntegrationUpgrade:
         new_commands = sorted(canonical.glob("speckit.*.md"))
         assert len(new_commands) > 0, "Commands should exist in .opencode/commands/"
 
-        # Stale files removed from legacy dir
-        remaining = list(legacy.glob("speckit.*.md"))
-        assert len(remaining) == 0, (
-            f"Legacy .opencode/command/ should have no speckit files after upgrade, "
-            f"found: {[f.name for f in remaining]}"
+        # Stale files removed from legacy dir (extension-installed commands
+        # like agent-context.update may still appear — only check the original
+        # core command stems that should have been migrated).
+        core_remaining = [
+            f for f in legacy.glob("speckit.*.md")
+            if "agent-context" not in f.name
+        ]
+        assert len(core_remaining) == 0, (
+            f"Legacy .opencode/command/ should have no core speckit files after upgrade, "
+            f"found: {[f.name for f in core_remaining]}"
         )
 
 
@@ -1466,7 +1470,7 @@ class TestScriptTypeValidation:
 class TestParseIntegrationOptionsEqualsForm:
     def test_equals_form_parsed(self):
         """--commands-dir=./x should be parsed the same as --commands-dir ./x."""
-        from specify_cli import _parse_integration_options
+        from specify_cli.integrations._commands import _parse_integration_options
         from specify_cli.integrations import get_integration
 
         integration = get_integration("generic")

tests/integrations/test_manifest.py

@@ -34,6 +34,57 @@ class TestManifestRecordFile:
         assert m.files["existing.txt"] == _sha256(f)
 
 
+class TestManifestRecordExistingErrors:
+    """Error-case coverage for ``record_existing`` symlink + non-file guards.
+
+    Added in #2483 — Copilot review flagged these as un-tested regressions
+    after the ``is_symlink``/``is_file`` guards were introduced.
+    """
+
+    def test_rejects_symlink_target(self, tmp_path):
+        target = tmp_path / "target.txt"
+        target.write_text("target content", encoding="utf-8")
+        link = tmp_path / "link.txt"
+        link.symlink_to(target)
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="symlinked"):
+            m.record_existing("link.txt")
+
+    def test_rejects_dangling_symlink(self, tmp_path):
+        # A symlink pointing nowhere should still be rejected before the
+        # ``is_file()`` check (which would itself be False on a dangler).
+        link = tmp_path / "dangler.txt"
+        link.symlink_to(tmp_path / "no-such-target.txt")
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="symlinked"):
+            m.record_existing("dangler.txt")
+
+    def test_rejects_directory_path(self, tmp_path):
+        (tmp_path / "a_dir").mkdir()
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="not a regular file"):
+            m.record_existing("a_dir")
+
+    def test_rejects_missing_path(self, tmp_path):
+        # ``is_file()`` is False for non-existent paths too; the same error
+        # surface keeps callers from having to distinguish "missing" from
+        # "wrong kind" — both mean "cannot hash this".
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="not a regular file"):
+            m.record_existing("never-existed.txt")
+
+    def test_lexical_prevalidation_for_absolute_path(self, tmp_path):
+        # ``record_existing`` must reject absolute paths via the lexical
+        # pre-check, NOT via the filesystem-touching ``is_symlink()`` call.
+        # Verified by passing an absolute path that points to a directory
+        # outside the project root — the canonical "Absolute paths" error
+        # must surface before any stat on the absolute path.
+        m = IntegrationManifest("test", tmp_path)
+        abs_path = "C:\\tmp\\escape.txt" if sys.platform == "win32" else "/tmp/escape.txt"
+        with pytest.raises(ValueError, match="Absolute paths"):
+            m.record_existing(abs_path)
+
+
 class TestManifestPathTraversal:
     def test_record_file_rejects_parent_traversal(self, tmp_path):
         m = IntegrationManifest("test", tmp_path)
@@ -245,3 +296,160 @@ class TestManifestLoadValidation:
         path.write_text("{not valid json", encoding="utf-8")
         with pytest.raises(ValueError, match="invalid JSON"):
             IntegrationManifest.load("bad", tmp_path)
+
+    def test_load_filters_recovered_files_not_in_files(self, tmp_path):
+        # Finding B (Round-9): a recovered_files entry referencing a path
+        # not present in files indicates an internally-inconsistent manifest
+        # (e.g. external edit). load() filters those entries silently so the
+        # manifest self-heals on next save(); is_recovered then returns the
+        # truthful False for the orphan.
+        path = tmp_path / ".specify" / "integrations" / "test.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text(json.dumps({
+            "integration": "test",
+            "files": {"kept.txt": "abc123"},
+            "recovered_files": ["kept.txt", "orphan.txt"],
+        }), encoding="utf-8")
+        m = IntegrationManifest.load("test", tmp_path)
+        assert m.recovered_files == {"kept.txt"}
+        assert m.is_recovered("kept.txt") is True
+        assert m.is_recovered("orphan.txt") is False
+
+
+class TestManifestRecoveredFiles:
+    """Coverage for the ``recovered_files`` channel added in #2483.
+
+    When ``shared_infra`` skips an existing file (because the user already has
+    it on disk) it now records the file with ``recovered=True``. The path
+    appears in ``manifest.recovered_files`` and ``is_recovered(path)`` returns
+    True. ``refresh_managed`` (out of scope for this PR) consults this list
+    before treating the recorded hash as a managed baseline, defending against
+    silent overwrite of user customizations after manifest loss.
+    """
+
+    def test_record_existing_default_is_not_recovered(self, tmp_path):
+        (tmp_path / "f.txt").write_text("x", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("f.txt")
+        assert m.is_recovered("f.txt") is False
+        assert m.recovered_files == set()
+
+    def test_record_existing_with_recovered_flag(self, tmp_path):
+        (tmp_path / "f.txt").write_text("x", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("f.txt", recovered=True)
+        assert m.is_recovered("f.txt") is True
+        assert m.recovered_files == {"f.txt"}
+        # File still hashed normally so check_modified/uninstall keep working
+        assert m.files["f.txt"] == _sha256(tmp_path / "f.txt")
+
+    def test_recovered_files_round_trips_through_save_load(self, tmp_path):
+        (tmp_path / "a.txt").write_text("aaa", encoding="utf-8")
+        (tmp_path / "b.txt").write_text("bbb", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path, version="9.9")
+        m.record_existing("a.txt", recovered=True)
+        m.record_existing("b.txt")  # not recovered
+        m.save()
+        loaded = IntegrationManifest.load("test", tmp_path)
+        assert loaded.is_recovered("a.txt") is True
+        assert loaded.is_recovered("b.txt") is False
+        assert loaded.recovered_files == {"a.txt"}
+
+    def test_save_omits_empty_recovered_files(self, tmp_path):
+        m = IntegrationManifest("test", tmp_path)
+        m.record_file("f.txt", "x")
+        path = m.save()
+        data = json.loads(path.read_text(encoding="utf-8"))
+        assert "recovered_files" not in data
+
+    def test_load_rejects_non_list_recovered_files(self, tmp_path):
+        path = tmp_path / ".specify" / "integrations" / "bad.manifest.json"
+        path.parent.mkdir(parents=True)
+        path.write_text(
+            json.dumps({"files": {}, "recovered_files": "not-a-list"}),
+            encoding="utf-8",
+        )
+        with pytest.raises(ValueError, match="recovered_files"):
+            IntegrationManifest.load("bad", tmp_path)
+
+    def test_is_recovered_absolute_path_returns_false(self, tmp_path):
+        # Copilot round-5 finding: passing an absolute path silently returned
+        # False because the stored keys are relative POSIX strings. Round-7
+        # made this explicit: ``is_recovered`` now rejects absolute paths
+        # up front via a lexical ``rel.is_absolute()`` guard and returns
+        # False without calling ``_validate_rel_path`` at all — matching
+        # ``record_existing``'s canonical-key guard so the two methods
+        # agree on which inputs can ever be stored keys.
+        (tmp_path / "f.txt").write_text("x", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("f.txt", recovered=True)
+        import sys
+        abs_input = "C:\\tmp\\f.txt" if sys.platform == "win32" else "/tmp/f.txt"
+        assert m.is_recovered(abs_input) is False
+
+    def test_is_recovered_escaping_path_returns_false(self, tmp_path):
+        # A relative path containing ``..`` segments cannot be a stored key:
+        # Round-7 added the same lexical ``".." in rel.parts`` guard to
+        # ``is_recovered`` that ``record_existing`` already enforces, so the
+        # method returns False immediately without reaching
+        # ``_validate_rel_path``. The try/except around ``_validate_rel_path``
+        # remains as defense-in-depth for paths that pass the lexical guard
+        # but still resolve outside the project root via a symlinked
+        # ancestor.
+        m = IntegrationManifest("test", tmp_path)
+        # Don't record anything — the path is impossible to record anyway.
+        assert m.is_recovered("../escape.txt") is False
+
+    def test_record_existing_clears_recovered_when_false(self, tmp_path):
+        # Finding A: re-recording the same path with recovered=False must
+        # drop the prior recovered marker (transition to managed baseline).
+        f = tmp_path / "x.txt"
+        f.write_text("v1", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("x.txt", recovered=True)
+        assert m.is_recovered("x.txt") is True
+        m.record_existing("x.txt", recovered=False)
+        assert m.is_recovered("x.txt") is False
+
+    def test_record_file_clears_recovered(self, tmp_path):
+        # Finding A: record_file writes produced content; the path can no
+        # longer be considered "merely observed" once we wrote bytes.
+        (tmp_path / "y.txt").write_text("observed", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("y.txt", recovered=True)
+        assert m.is_recovered("y.txt") is True
+        m.record_file("y.txt", "produced")
+        assert m.is_recovered("y.txt") is False
+
+    def test_is_recovered_rejects_dotdot_segment(self, tmp_path):
+        # Finding B: record_existing rejects ``..`` segments via the lexical
+        # pre-check; is_recovered must match that behavior and return False
+        # without raising, mirroring the canonicalization guard.
+        (tmp_path / "z.txt").write_text("v1", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        m.record_existing("z.txt", recovered=True)
+        # Same file via dotdot-normalizing path — must be False, not raise.
+        assert m.is_recovered("subdir/../z.txt") is False
+
+
+class TestRecordExistingNewGuards:
+    """Coverage for the two new guards added by Copilot's 2026-05-18 review."""
+
+    def test_rejects_symlinked_ancestor(self, tmp_path):
+        real_dir = tmp_path / "real_dir"
+        real_dir.mkdir()
+        (real_dir / "file.txt").write_text("payload", encoding="utf-8")
+        (tmp_path / "linked_dir").symlink_to(real_dir, target_is_directory=True)
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match="symlinked"):
+            m.record_existing("linked_dir/file.txt")
+
+    def test_rejects_inside_root_dotdot_with_explicit_message(self, tmp_path):
+        # ``dir/../file.txt`` normalizes inside root, so the old "escapes
+        # project root" message was misleading. The new message names the
+        # actual reason: canonicalization.
+        (tmp_path / "dir").mkdir()
+        (tmp_path / "file.txt").write_text("x", encoding="utf-8")
+        m = IntegrationManifest("test", tmp_path)
+        with pytest.raises(ValueError, match=r"canonical|'\.\.' segments"):
+            m.record_existing("dir/../file.txt")

tests/self_upgrade_helpers.py

@@ -0,0 +1,64 @@
+"""Shared fixtures and helpers for `specify self upgrade` tests.
+
+These helpers patch subprocess, PATH lookup, and release-tag resolution so
+the focused test modules stay isolated from the real environment.
+"""
+
+import os
+import subprocess
+
+import pytest
+from typer.testing import CliRunner
+
+from specify_cli._version import (
+    _InstallMethod,
+    _UpgradePlan,
+    _assemble_installer_argv,
+    _detect_install_method,
+    _verify_upgrade,
+)
+from tests.conftest import strip_ansi
+from tests.http_helpers import mock_urlopen_response
+
+__all__ = (
+    "SENTINEL_GH_TOKEN",
+    "SENTINEL_GITHUB_TOKEN",
+    "_InstallMethod",
+    "_UpgradePlan",
+    "_assemble_installer_argv",
+    "_completed_process",
+    "_detect_install_method",
+    "_verify_upgrade",
+    "mock_urlopen_response",
+    "requires_posix",
+    "runner",
+    "strip_ansi",
+)
+
+runner = CliRunner()
+
+# Some installer error-path tests create a relative `./uv` fixture, `chdir`
+# into the tmp dir, and assert POSIX executable-bit semantics (chmod / X_OK).
+# None of that maps cleanly onto Windows: `os.access(path, X_OK)` ignores the
+# mode bits, and pytest cannot rmtree a tmp dir that is still the cwd, so the
+# fixtures raise PermissionError during teardown. Skip these on Windows — the
+# realistic absolute-path and bare-PATH-command branches stay covered there.
+requires_posix = pytest.mark.skipif(
+    os.name == "nt",
+    reason="relative-path / executable-bit semantics are POSIX-only",
+)
+
+SENTINEL_GH_TOKEN = "SENTINEL-GH-TOKEN-VALUE"
+SENTINEL_GITHUB_TOKEN = "SENTINEL-GITHUB-TOKEN-VALUE"
+
+
+def _completed_process(
+    returncode: int, stdout: str = "", stderr: str = ""
+) -> subprocess.CompletedProcess:
+    """Build a subprocess.CompletedProcess for installer / verification calls."""
+    return subprocess.CompletedProcess(
+        args=["mocked"],
+        returncode=returncode,
+        stdout=stdout,
+        stderr=stderr,
+    )

tests/test_authentication.py

@@ -573,7 +573,9 @@ class TestAuthenticatedHttp:
         mock_opener = MagicMock()
         def fake_open(req, timeout=None):
             captured["req"] = req
-            resp = MagicMock(); resp.__enter__ = lambda s: s; resp.__exit__ = MagicMock(return_value=False)
+            resp = MagicMock()
+            resp.__enter__ = lambda s: s
+            resp.__exit__ = MagicMock(return_value=False)
             return resp
         mock_opener.open.side_effect = fake_open
         with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
@@ -588,7 +590,9 @@ class TestAuthenticatedHttp:
         captured = {}
         def fake_urlopen(req, timeout=None):
             captured["req"] = req
-            resp = MagicMock(); resp.__enter__ = lambda s: s; resp.__exit__ = MagicMock(return_value=False)
+            resp = MagicMock()
+            resp.__enter__ = lambda s: s
+            resp.__exit__ = MagicMock(return_value=False)
             return resp
         with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=fake_urlopen):
             open_url("https://example.com/file.json")
@@ -601,7 +605,9 @@ class TestAuthenticatedHttp:
         captured = {}
         def fake_urlopen(req, timeout=None):
             captured["req"] = req
-            resp = MagicMock(); resp.__enter__ = lambda s: s; resp.__exit__ = MagicMock(return_value=False)
+            resp = MagicMock()
+            resp.__enter__ = lambda s: s
+            resp.__exit__ = MagicMock(return_value=False)
             return resp
         with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=fake_urlopen):
             open_url("https://github.com/org/repo")
@@ -615,12 +621,16 @@ class TestAuthenticatedHttp:
         self._set_config(monkeypatch, [_github_entry()])
         call_count = 0
         def fake_side_effect(req, timeout=None):
-            nonlocal call_count; call_count += 1
+            nonlocal call_count
+            call_count += 1
             if call_count == 1:
                 raise urllib.error.HTTPError("url", 401, "Unauthorized", {}, None)
-            resp = MagicMock(); resp.__enter__ = lambda s: s; resp.__exit__ = MagicMock(return_value=False)
+            resp = MagicMock()
+            resp.__enter__ = lambda s: s
+            resp.__exit__ = MagicMock(return_value=False)
             return resp
-        mock_opener = MagicMock(); mock_opener.open.side_effect = fake_side_effect
+        mock_opener = MagicMock()
+        mock_opener.open.side_effect = fake_side_effect
         with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener), \
              patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=fake_side_effect):
             open_url("https://github.com/org/repo")
@@ -692,7 +702,6 @@ class TestLoadConfigCaching:
         """_load_config() should call load_auth_config only once per process."""
         from unittest.mock import patch
         from specify_cli.authentication import http as _mod
-        from specify_cli.authentication.config import AuthConfigEntry
         # Allow the real load path (no override)
         monkeypatch.setattr(_mod, "_config_override", None)
         monkeypatch.setattr(_mod, "_config_cache", None)
@@ -825,8 +834,11 @@ class TestFetchLatestReleaseTagDelegation:
         def side_effect(req, timeout=None):
             captured["request"] = req
             body = _json.dumps({"tag_name": "v9.9.9"}).encode()
-            resp = MagicMock(); resp.read.return_value = body
-            cm = MagicMock(); cm.__enter__.return_value = resp; cm.__exit__.return_value = False
+            resp = MagicMock()
+            resp.read.return_value = body
+            cm = MagicMock()
+            cm.__enter__.return_value = resp
+            cm.__exit__.return_value = False
             return cm
         return captured, side_effect
 
@@ -836,7 +848,8 @@ class TestFetchLatestReleaseTagDelegation:
         monkeypatch.setenv("GH_TOKEN", "forwarded-sentinel")
         self._set_config(monkeypatch, [_github_entry()])
         captured, side_effect = self._capture_request()
-        mock_opener = MagicMock(); mock_opener.open.side_effect = side_effect
+        mock_opener = MagicMock()
+        mock_opener.open.side_effect = side_effect
         with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
             _fetch_latest_release_tag()
         assert captured["request"].get_header("Authorization") == "Bearer forwarded-sentinel"

tests/test_commands_package.py

@@ -13,12 +13,6 @@ def test_commands_init_importable():
     assert callable(mod.register)
 
 
-def test_commands_stubs_importable():
-    for name in ("integration", "preset", "extension", "workflow"):
-        mod = importlib.import_module(f"specify_cli.commands.{name}")
-        assert mod is not None
-
-
 def test_agent_config_importable():
     from specify_cli._agent_config import (
         AGENT_CONFIG,
@@ -35,7 +29,7 @@ def test_agent_config_importable():
 
 
 def test_agent_config_re_exported_from_init():
-    from specify_cli import AGENT_CONFIG, AI_ASSISTANT_ALIASES, AI_ASSISTANT_HELP, SCRIPT_TYPE_CHOICES
+    from specify_cli import AGENT_CONFIG, SCRIPT_TYPE_CHOICES
     assert isinstance(AGENT_CONFIG, dict)
     assert "sh" in SCRIPT_TYPE_CHOICES
 

tests/test_console_imports.py

@@ -2,12 +2,7 @@
 from specify_cli import (
     console,
     StepTracker,
-    get_key,
     select_with_arrows,
-    BannerGroup,
-    show_banner,
-    BANNER,
-    TAGLINE,
 )
 
 

tests/test_extension_skills.py

@@ -21,7 +21,6 @@ from pathlib import Path
 from specify_cli.extensions import (
     ExtensionManifest,
     ExtensionManager,
-    ExtensionError,
 )
 
 
@@ -241,7 +240,7 @@ class TestExtensionSkillRegistration:
         """Skills should be created when ai_skills is enabled."""
         project_dir, skills_dir = skills_project
         manager = ExtensionManager(project_dir)
-        manifest = manager.install_from_directory(
+        manager.install_from_directory(
             extension_dir, "0.1.0", register_commands=False
         )
 
@@ -784,7 +783,7 @@ class TestExtensionSkillEdgeCases:
         )
 
         manager = ExtensionManager(project_dir)
-        manifest = manager.install_from_directory(
+        manager.install_from_directory(
             ext_dir, "0.1.0", register_commands=False
         )
 
@@ -803,7 +802,7 @@ class TestExtensionSkillEdgeCases:
         ext_dir = _create_extension_dir(temp_dir, ext_id="test-ext")
 
         manager = ExtensionManager(project_dir)
-        manifest = manager.install_from_directory(
+        manager.install_from_directory(
             ext_dir, "0.1.0", register_commands=False
         )
 
@@ -819,10 +818,10 @@ class TestExtensionSkillEdgeCases:
         ext_dir_b = _create_extension_dir(temp_dir, ext_id="ext-b")
 
         manager = ExtensionManager(project_dir)
-        manifest_a = manager.install_from_directory(
+        manager.install_from_directory(
             ext_dir_a, "0.1.0", register_commands=False
         )
-        manifest_b = manager.install_from_directory(
+        manager.install_from_directory(
             ext_dir_b, "0.1.0", register_commands=False
         )
 
@@ -880,7 +879,7 @@ class TestExtensionSkillEdgeCases:
 
         manager = ExtensionManager(project_dir)
         # Should not raise
-        manifest = manager.install_from_directory(
+        manager.install_from_directory(
             ext_dir, "0.1.0", register_commands=False
         )
 

tests/test_extensions.py

@@ -1315,6 +1315,42 @@ $ARGUMENTS
         assert not (skills_dir / "speckit-specify" / "SKILL.md").exists()
         assert not (skills_dir / "speckit-shortcut" / "SKILL.md").exists()
 
+    def test_unregister_commands_handles_legacy_dot_notated_files(self, project_dir):
+        """Unregister should clean up both legacy dot-notated and new hyphenated files."""
+        # 1. Mock an agent that uses hyphenated/formatted names (e.g. Cline)
+        from specify_cli.agents import CommandRegistrar as AgentCommandRegistrar
+        registrar = AgentCommandRegistrar()
+
+        # We'll use "cline" since it has format_name
+        assert "cline" in registrar.AGENT_CONFIGS
+        cline_config = registrar.AGENT_CONFIGS["cline"]
+        cline_dir = project_dir / cline_config["dir"]
+        cline_dir.mkdir(parents=True, exist_ok=True)
+
+        # 2. Create both legacy and new files
+        # Command name: speckit.git.commit
+        # Formatted name: speckit-git-commit
+        cmd_name = "speckit.git.commit"
+        formatted_name = "speckit-git-commit"
+
+        legacy_file = cline_dir / f"{cmd_name}.md"
+        formatted_file = cline_dir / f"{formatted_name}.md"
+
+        legacy_file.write_text("legacy body")
+        formatted_file.write_text("formatted body")
+
+        assert legacy_file.exists()
+        assert formatted_file.exists()
+
+        # 3. Call unregister
+        registrar.unregister_commands({"cline": [cmd_name]}, project_dir)
+
+        # 4. Verify both are gone
+        assert not legacy_file.exists(), "Legacy dot-notated file should be removed"
+        assert (
+            not formatted_file.exists()
+        ), "Formatted hyphenated file should be removed"
+
     def test_register_commands_for_all_agents_distinguishes_codex_from_amp(self, extension_dir, project_dir):
         """A Codex project under .agents/skills should not implicitly activate Amp."""
         skills_dir = project_dir / ".agents" / "skills"
@@ -2768,17 +2804,33 @@ class TestExtensionCatalog:
             zf.writestr("extension.yml", "id: test-ext\nname: Test\nversion: 1.0.0\n")
         zip_bytes = zip_buf.getvalue()
 
-        mock_response = MagicMock()
-        mock_response.read.return_value = zip_bytes
-        mock_response.__enter__ = lambda s: s
-        mock_response.__exit__ = MagicMock(return_value=False)
+        release_response = MagicMock()
+        release_response.read.return_value = json.dumps(
+            {
+                "assets": [
+                    {
+                        "name": "test-ext.zip",
+                        "url": "https://api.github.com/repos/org/repo/releases/assets/1",
+                    }
+                ]
+            }
+        ).encode()
+        release_response.__enter__ = lambda s: s
+        release_response.__exit__ = MagicMock(return_value=False)
 
-        captured = {}
+        asset_response = MagicMock()
+        asset_response.read.return_value = zip_bytes
+        asset_response.__enter__ = lambda s: s
+        asset_response.__exit__ = MagicMock(return_value=False)
+
+        captured = []
         mock_opener = MagicMock()
 
         def fake_open(req, timeout=None):
-            captured["req"] = req
-            return mock_response
+            captured.append(req)
+            if req.full_url.endswith("/releases/tags/v1"):
+                return release_response
+            return asset_response
 
         mock_opener.open.side_effect = fake_open
 
@@ -2793,7 +2845,56 @@ class TestExtensionCatalog:
              patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
             catalog.download_extension("test-ext", target_dir=temp_dir)
 
-        assert captured["req"].get_header("Authorization") == "Bearer ghp_testtoken"
+        assert captured[0].full_url == "https://api.github.com/repos/org/repo/releases/tags/v1"
+        assert captured[0].get_header("Authorization") == "Bearer ghp_testtoken"
+        assert captured[1].full_url == "https://api.github.com/repos/org/repo/releases/assets/1"
+        assert captured[1].get_header("Authorization") == "Bearer ghp_testtoken"
+        assert captured[1].get_header("Accept") == "application/octet-stream"
+
+    def test_download_extension_accepts_direct_github_rest_asset_url(self, temp_dir, monkeypatch):
+        """download_extension can use a GitHub REST release asset URL directly."""
+        from unittest.mock import patch, MagicMock
+        import zipfile
+        import io
+
+        monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")
+        self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")
+        catalog = self._make_catalog(temp_dir)
+
+        zip_buf = io.BytesIO()
+        with zipfile.ZipFile(zip_buf, "w") as zf:
+            zf.writestr("extension.yml", "id: test-ext\nname: Test\nversion: 1.0.0\n")
+        zip_bytes = zip_buf.getvalue()
+
+        asset_response = MagicMock()
+        asset_response.read.return_value = zip_bytes
+        asset_response.__enter__ = lambda s: s
+        asset_response.__exit__ = MagicMock(return_value=False)
+
+        captured = []
+        mock_opener = MagicMock()
+
+        def fake_open(req, timeout=None):
+            captured.append(req)
+            return asset_response
+
+        mock_opener.open.side_effect = fake_open
+
+        ext_info = {
+            "id": "test-ext",
+            "name": "Test Extension",
+            "version": "1.0.0",
+            "download_url": "https://api.github.com/repos/org/repo/releases/assets/1",
+        }
+
+        with patch.object(catalog, "get_extension_info", return_value=ext_info), \
+             patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
+            catalog.download_extension("test-ext", target_dir=temp_dir)
+
+        assert len(captured) == 1
+        assert captured[0].full_url == "https://api.github.com/repos/org/repo/releases/assets/1"
+        assert captured[0].get_header("Authorization") == "Bearer ghp_testtoken"
+        assert captured[0].get_header("Accept") == "application/octet-stream"
 
 
 
@@ -3322,9 +3423,13 @@ class TestExtensionIgnore:
                 else:
                     p.write_text(content)
 
-        # Write .extensionignore
+        # Write .extensionignore. Pinned to UTF-8 so non-ASCII patterns
+        # in tests (see ``test_extensionignore_utf8_patterns``) survive
+        # the round-trip on Windows runners with non-UTF-8 default locales.
         if ignore_content is not None:
-            (ext_dir / ".extensionignore").write_text(ignore_content)
+            (ext_dir / ".extensionignore").write_text(
+                ignore_content, encoding="utf-8"
+            )
 
         return ext_dir
 
@@ -3554,6 +3659,73 @@ class TestExtensionIgnore:
         assert (dest / "docs" / "guide.md").exists()
         assert not (dest / "docs" / "internal" / "draft.md").exists()
 
+    def test_extensionignore_utf8_patterns(self, temp_dir, valid_manifest_data):
+        """Non-ASCII patterns in .extensionignore work on every locale.
+
+        ``Path.read_text`` defaults to the system locale codec on Windows
+        (cp1252 / gb2312 / cp932). Without an explicit ``encoding="utf-8"``,
+        a pattern like ``ドキュメント/`` written by a UTF-8 host becomes
+        mojibake on a cp1252 host and silently fails to match — leaking
+        files the author intended to exclude. The existing
+        ``test_extensionignore_windows_backslash_patterns`` already shows
+        the codebase treats this as a Windows-author-friendly file; UTF-8
+        is part of that same contract.
+        """
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={
+                "ドキュメント/private.md": "secret",
+                "ドキュメント/public.md": "public",
+                "docs/guide.md": "# Guide",
+                "café/résumé.txt": "draft",
+            },
+            ignore_content="ドキュメント/\ncafé/\n",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        # Multibyte patterns excluded.
+        assert not (dest / "ドキュメント").exists()
+        assert not (dest / "café").exists()
+        # ASCII path with no matching pattern is unaffected.
+        assert (dest / "docs" / "guide.md").exists()
+
+    def test_extensionignore_invalid_utf8_raises_validation_error(
+        self, temp_dir, valid_manifest_data
+    ):
+        """A non-UTF-8 ``.extensionignore`` surfaces as ``ValidationError``.
+
+        Pinning ``encoding="utf-8"`` on the reader means an
+        ``.extensionignore`` written in some other codec (cp1252, etc.)
+        now triggers ``UnicodeDecodeError`` instead of silently
+        mojibake-ing patterns. Wrap that exception as ``ValidationError``
+        with a pointer to the offending byte — the same pattern
+        ``ExtensionManifest._load_yaml`` uses for ``extension.yml`` —
+        so installation aborts with a user-friendly message instead of a
+        raw Python traceback.
+        """
+        ext_dir = self._make_extension(temp_dir, valid_manifest_data)
+        # Write an .extensionignore whose bytes are not valid UTF-8.
+        # 0xE9 is 'é' in cp1252 but an invalid lead byte in UTF-8.
+        (ext_dir / ".extensionignore").write_bytes(b"caf\xe9/\n")
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        with pytest.raises(
+            ValidationError, match=r"\.extensionignore is not valid UTF-8"
+        ):
+            manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
     def test_extensionignore_star_does_not_cross_directories(self, temp_dir, valid_manifest_data):
         """'*' should NOT match across directory boundaries (gitignore semantics)."""
         ext_dir = self._make_extension(
@@ -3807,6 +3979,67 @@ class TestExtensionAddCLI:
         assert "bundled with spec-kit" in result.output
         assert "reinstall" in result.output.lower()
 
+    def test_add_from_url_prompts_before_spinner(self, tmp_path):
+        """Confirm prompt for --from <url> must fire before the console.status spinner.
+
+        Regression test for #2783: typer.confirm() inside console.status()
+        was overwritten by the Rich spinner, making the command appear hung.
+        """
+        from typer.testing import CliRunner
+        from unittest.mock import patch, MagicMock
+        from specify_cli import app
+
+        project_dir = tmp_path / "test-project"
+        project_dir.mkdir()
+        (project_dir / ".specify").mkdir()
+
+        call_order: list[str] = []
+
+        original_status = MagicMock()
+
+        def record_status(*args, **kwargs):
+            call_order.append("spinner")
+            return original_status
+
+        runner = CliRunner()
+        with patch.object(Path, "cwd", return_value=project_dir), \
+             patch("specify_cli.console.status", side_effect=record_status), \
+             patch("typer.confirm", side_effect=lambda *a, **kw: (call_order.append("confirm"), False)[-1]):
+            result = runner.invoke(
+                app,
+                ["extension", "add", "my-ext", "--from", "https://example.com/ext.zip"],
+                catch_exceptions=True,
+            )
+
+        assert "confirm" in call_order, "confirm prompt was never called"
+        # The confirm must fire BEFORE the spinner is entered
+        if "spinner" in call_order:
+            assert call_order.index("confirm") < call_order.index("spinner"), \
+                f"confirm must precede spinner, got: {call_order}"
+        assert result.exit_code == 0  # user declined → clean exit
+
+    def test_add_from_url_cancel_exits_cleanly(self, tmp_path):
+        """Declining the --from <url> confirmation should exit with code 0."""
+        from typer.testing import CliRunner
+        from unittest.mock import patch
+        from specify_cli import app
+
+        project_dir = tmp_path / "test-project"
+        project_dir.mkdir()
+        (project_dir / ".specify").mkdir()
+
+        runner = CliRunner()
+        with patch.object(Path, "cwd", return_value=project_dir), \
+             patch("typer.confirm", return_value=False):
+            result = runner.invoke(
+                app,
+                ["extension", "add", "my-ext", "--from", "https://example.com/ext.zip"],
+                catch_exceptions=True,
+            )
+
+        assert result.exit_code == 0
+        assert "Cancelled" in result.output
+
 
 class TestDownloadExtensionBundled:
     """Tests for download_extension handling of bundled extensions."""
@@ -4555,6 +4788,43 @@ class TestHookInvocationRendering:
         assert execution["command"] == "speckit.tasks"
         assert execution["invocation"] == "$speckit-tasks"
 
+    def test_cline_hooks_render_hyphenated_invocation(self, project_dir):
+        """Cline projects should render /speckit-* invocations."""
+        init_options = project_dir / ".specify" / "init-options.json"
+        init_options.parent.mkdir(parents=True, exist_ok=True)
+        init_options.write_text(json.dumps({"ai": "cline"}))
+
+        hook_executor = HookExecutor(project_dir)
+        execution = hook_executor.execute_hook(
+            {
+                "extension": "test-ext",
+                "command": "speckit.tasks",
+                "optional": False,
+            }
+        )
+
+        assert execution["command"] == "speckit.tasks"
+        assert execution["invocation"] == "/speckit-tasks"
+
+    def test_cline_hooks_render_extension_command(self, project_dir):
+        """Cline projects should render /speckit-my-ext-cmd for extension hooks."""
+        init_options = project_dir / ".specify" / "init-options.json"
+        init_options.parent.mkdir(parents=True, exist_ok=True)
+        init_options.write_text(json.dumps({"ai": "cline"}))
+
+        hook_executor = HookExecutor(project_dir)
+        # Test with a non-speckit. command
+        execution = hook_executor.execute_hook(
+            {
+                "extension": "test-ext",
+                "command": "my-extension.do-something",
+                "optional": False,
+            }
+        )
+
+        assert execution["command"] == "my-extension.do-something"
+        assert execution["invocation"] == "/speckit-my-extension-do-something"
+
     def test_non_skill_command_keeps_slash_invocation(self, project_dir):
         """Custom hook commands should keep slash invocation style."""
         init_options = project_dir / ".specify" / "init-options.json"
@@ -4690,3 +4960,157 @@ class TestExtensionRemoveCLI:
             )
 
         assert "2 commands" in result.output
+
+
+class TestClineExtensionHyphenation:
+    """Test that Cline integration uses hyphenated commands and frontmatter references."""
+
+    def _setup_mock_extension(self, tmp_path, ai_name):
+        import yaml
+        import json
+
+        # 1. Setup mock project
+        project_dir = tmp_path / "project"
+        project_dir.mkdir()
+        (project_dir / ".specify").mkdir()
+
+        init_options = project_dir / ".specify" / "init-options.json"
+        init_options.write_text(json.dumps({"ai": ai_name}), encoding="utf-8")
+
+        if ai_name == "cline":
+            commands_dest_dir = project_dir / ".clinerules" / "workflows"
+        else:
+            commands_dest_dir = project_dir / ".agents" / "commands"
+        commands_dest_dir.mkdir(parents=True, exist_ok=True)
+
+        # 2. Setup mock extension directory
+        ext_dir = tmp_path / "mock-ext"
+        ext_dir.mkdir()
+
+        manifest_data = {
+            "schema_version": "1.0",
+            "extension": {
+                "id": "mock-ext",
+                "name": "Mock Extension",
+                "version": "1.0.0",
+                "description": f"Mock extension for {ai_name} tests",
+                "author": "Tester",
+                "repository": "https://github.com/test/mock-ext",
+                "license": "MIT",
+            },
+            "requires": {
+                "speckit_version": ">=0.1.0",
+            },
+            "provides": {
+                "commands": [
+                    {
+                        "name": "speckit.mock-ext.hello",
+                        "file": "commands/hello.md",
+                        "description": "Test hello command",
+                        "aliases": ["speckit.mock-ext.greet"]
+                    }
+                ]
+            }
+        }
+
+        with open(ext_dir / "extension.yml", "w", encoding="utf-8") as f:
+            yaml.dump(manifest_data, f)
+
+        commands_dir = ext_dir / "commands"
+        commands_dir.mkdir()
+
+        # Command file with dotted speckit references in frontmatter and body
+        cmd_content = """---
+description: "Test hello command"
+agent: speckit.tasks
+handoffs:
+  - agent: speckit.iterate.start
+    message: "Hand off to start"
+---
+
+# Test Hello Command
+
+Please refer to speckit.mock-ext.greet for instructions.
+$ARGUMENTS
+"""
+        (commands_dir / "hello.md").write_text(cmd_content, encoding="utf-8")
+
+        return project_dir, ext_dir, commands_dest_dir
+
+    def test_cline_extension_hyphenation(self, tmp_path):
+        from typer.testing import CliRunner
+        from unittest.mock import patch
+        from specify_cli import app
+        from specify_cli.agents import CommandRegistrar
+
+        project_dir, ext_dir, cline_workflows_dir = self._setup_mock_extension(tmp_path, "cline")
+
+        # 3. Run specify extension add
+        runner = CliRunner()
+        with patch.object(Path, "cwd", return_value=project_dir):
+            result = runner.invoke(
+                app, ["extension", "add", str(ext_dir), "--dev"], catch_exceptions=False
+            )
+
+        # Verify CLI printed hyphenated commands
+        # Note: We assert that the primary command 'speckit-mock-ext-hello' is printed,
+        # but we do not assert that the alias 'speckit-mock-ext-greet' is printed in the console
+        # because manifest.commands only lists primary commands.
+        assert "speckit-mock-ext-hello" in result.output
+        assert "speckit.mock-ext.hello" not in result.output
+
+        # Verify on-disk command names are hyphenated
+        hello_file = cline_workflows_dir / "speckit-mock-ext-hello.md"
+        greet_file = cline_workflows_dir / "speckit-mock-ext-greet.md"
+
+        assert hello_file.exists()
+        assert greet_file.exists()
+
+        # Verify frontmatter in the generated files is recursively hyphenated
+        hello_text = hello_file.read_text(encoding="utf-8")
+        hello_fm, hello_body = CommandRegistrar.parse_frontmatter(hello_text)
+        assert hello_fm["agent"] == "speckit-tasks"
+        assert hello_fm["handoffs"][0]["agent"] == "speckit-iterate-start"
+
+        # Verify body references are hyphenated for Cline
+        assert "speckit-mock-ext-greet" in hello_body
+        assert "speckit.mock-ext.greet" not in hello_body
+
+    def test_non_cline_extension_no_hyphenation(self, tmp_path):
+        from typer.testing import CliRunner
+        from unittest.mock import patch
+        from specify_cli import app
+        from specify_cli.agents import CommandRegistrar
+
+        project_dir, ext_dir, claude_commands_dir = self._setup_mock_extension(tmp_path, "claude")
+
+        # 3. Run specify extension add
+        runner = CliRunner()
+        with patch.object(Path, "cwd", return_value=project_dir):
+            result = runner.invoke(
+                app, ["extension", "add", str(ext_dir), "--dev"], catch_exceptions=False
+            )
+
+        # Verify CLI printed dotted commands
+        # Note: We assert that the primary command 'speckit.mock-ext.hello' is printed,
+        # but we do not assert that the alias 'speckit.mock-ext.greet' is printed in the console
+        # because manifest.commands only lists primary commands.
+        assert "speckit.mock-ext.hello" in result.output
+        assert "speckit-mock-ext-hello" not in result.output
+
+        # Verify on-disk command names are dotted
+        hello_file = claude_commands_dir / "speckit.mock-ext.hello.md"
+        greet_file = claude_commands_dir / "speckit.mock-ext.greet.md"
+
+        assert hello_file.exists()
+        assert greet_file.exists()
+
+        # Verify frontmatter references are still dotted
+        hello_text = hello_file.read_text(encoding="utf-8")
+        hello_fm, hello_body = CommandRegistrar.parse_frontmatter(hello_text)
+        assert hello_fm["agent"] == "speckit.tasks"
+        assert hello_fm["handoffs"][0]["agent"] == "speckit.iterate.start"
+
+        # Verify body references are still dotted for non-Cline
+        assert "speckit.mock-ext.greet" in hello_body
+        assert "speckit-mock-ext-greet" not in hello_body

tests/test_presets.py

@@ -2269,6 +2269,85 @@ class TestInitOptions:
 
         assert load_init_options(project_dir) == {}
 
+    @pytest.mark.parametrize(
+        "value",
+        ["名前-プロジェクト", "café-résumé", "Ωmega-Δelta", "🚀-launch"],
+    )
+    def test_save_load_round_trip_preserves_non_ascii(self, project_dir, value):
+        """Non-ASCII values round-trip via explicit UTF-8 encoding.
+
+        ``Path.write_text`` / ``Path.read_text`` default to the system
+        locale codec on Windows (cp1252 / gb2312 / cp932). Without
+        ``encoding="utf-8"`` pinned on both ends, a project name like
+        ``café`` written on a UTF-8 host becomes garbled or unreadable on
+        a cp1252 host (and vice versa). Pin UTF-8 explicitly so init
+        options round-trip across machines and CI.
+
+        Note: this test only meaningfully exercises the encoding pin
+        because ``save_init_options`` now writes JSON with
+        ``ensure_ascii=False`` — otherwise ``json.dumps`` would output
+        ASCII-only ``\\uXXXX`` escapes and the encoding pin would be a
+        no-op for any value here. ``test_save_writes_real_utf8_bytes``
+        below asserts that contract directly.
+        """
+        from specify_cli import save_init_options, load_init_options
+
+        save_init_options(project_dir, {"ai": "claude", "project_name": value})
+
+        loaded = load_init_options(project_dir)
+        assert loaded["project_name"] == value
+
+    def test_save_writes_real_utf8_bytes(self, project_dir):
+        """The on-disk file contains real UTF-8 bytes, not ``\\uXXXX`` escapes.
+
+        Pinning ``encoding="utf-8"`` on ``write_text`` only makes a
+        difference when the serialiser actually emits non-ASCII
+        characters. With ``ensure_ascii=False`` on ``json.dumps`` the
+        non-ASCII bytes hit the file, so the encoding pin is the thing
+        that decides between cp1252 garbage and clean UTF-8 on Windows.
+
+        This test pins that behaviour: the on-disk bytes are valid UTF-8
+        and contain the multi-byte encoding of ``café``, not its
+        ``\\u00e9`` escape form. Reviewers can verify that removing
+        ``ensure_ascii=False`` or ``encoding="utf-8"`` from the writer
+        breaks this test, which is what Copilot's review pointed out the
+        original round-trip test failed to do.
+        """
+        from specify_cli import save_init_options
+
+        save_init_options(project_dir, {"project_name": "café"})
+
+        opts_file = project_dir / ".specify" / "init-options.json"
+        raw = opts_file.read_bytes()
+        # 'café' in UTF-8 ends with bytes 0xC3 0xA9 ('é'). The cp1252
+        # encoding of 'é' is the single byte 0xE9. The JSON-escape form
+        # would be the 6-byte literal '\\u00e9'. We assert the UTF-8 form
+        # is present so the test pins the actual contract.
+        assert b"caf\xc3\xa9" in raw, (
+            "Expected UTF-8 bytes for 'café' in the on-disk file, "
+            f"got: {raw!r}"
+        )
+        # And the whole file decodes cleanly as UTF-8.
+        raw.decode("utf-8")
+
+    def test_load_returns_empty_on_locale_corrupted_file(self, project_dir):
+        """A file written in a non-UTF-8 codec falls back to {}, not crash.
+
+        Simulates a file produced by an old client (or by a peer machine
+        with a different default locale) that contains bytes invalid as
+        UTF-8. ``load_init_options`` should fall back to ``{}`` per the
+        existing contract — never propagate a raw ``UnicodeDecodeError``
+        to the CLI surface.
+        """
+        from specify_cli import load_init_options
+
+        opts_file = project_dir / ".specify" / "init-options.json"
+        opts_file.parent.mkdir(parents=True, exist_ok=True)
+        # 0xE9 is 'é' in cp1252 but an invalid lead byte in UTF-8.
+        opts_file.write_bytes(b'{"project_name": "caf\xe9"}')
+
+        assert load_init_options(project_dir) == {}
+
 
 class TestPresetSkills:
     """Tests for preset skill registration and unregistration.

tests/test_self_upgrade_detection.py

@@ -0,0 +1,887 @@
+"""Detection, argv assembly, and dry-run tests for `specify self upgrade`."""
+
+import importlib.metadata
+import json
+import os
+import subprocess
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+import specify_cli
+from specify_cli import app
+
+from tests.self_upgrade_helpers import (
+    _InstallMethod,
+    _assemble_installer_argv,
+    _completed_process,
+    _detect_install_method,
+    mock_urlopen_response,
+    runner,
+    strip_ansi,
+)
+
+
+class TestDetectionUvTool:
+    """Tier-1 path-prefix detection for uv-tool installs."""
+
+    def test_posix_uv_tool_prefix_matches(self, uv_tool_argv0):
+        method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.UV_TOOL
+        assert signals.matched_tier == 1
+        assert "uv/tools/specify-cli" in signals.matched_prefix.replace("\\", "/")
+
+    def test_detection_is_deterministic(self, uv_tool_argv0):
+        a = _detect_install_method()
+        b = _detect_install_method()
+        assert a == b == _InstallMethod.UV_TOOL
+
+    def test_no_argv_match_falls_through_to_unsupported(self, unsupported_argv0):
+        with patch("specify_cli._version.shutil.which", return_value=None), patch(
+            "specify_cli._version._editable_marker_seen", return_value=False
+        ):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UNSUPPORTED
+
+    def test_include_signals_false_returns_bare_enum(self, uv_tool_argv0):
+        result = _detect_install_method(include_signals=False)
+        assert isinstance(result, _InstallMethod)
+
+    def test_bare_argv0_is_resolved_via_path_lookup(self, monkeypatch, tmp_path):
+        if os.name == "nt":
+            monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))
+            fake_dir = tmp_path / "uv" / "tools" / "specify-cli" / "bin"
+        else:
+            monkeypatch.setenv("HOME", str(tmp_path))
+            fake_dir = (
+                tmp_path / ".local" / "share" / "uv" / "tools" / "specify-cli" / "bin"
+            )
+        fake_dir.mkdir(parents=True)
+        fake_specify = fake_dir / "specify"
+        fake_specify.write_text("#!/usr/bin/env python\n")
+        monkeypatch.setattr("sys.argv", ["specify"])
+        with patch(
+            "specify_cli._version.shutil.which",
+            side_effect=lambda name: str(fake_specify) if name == "specify" else None,
+        ):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UV_TOOL
+
+    def test_prefix_match_does_not_accept_sibling_directory(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        fake_dir = tmp_path / ".local" / "share" / "uv" / "tools" / "specify-cli2" / "bin"
+        fake_dir.mkdir(parents=True)
+        fake_specify = fake_dir / "specify"
+        fake_specify.write_text("#!/usr/bin/env python\n")
+        monkeypatch.setattr("sys.argv", [str(fake_specify)])
+        with patch("specify_cli._version.shutil.which", return_value=None), patch(
+            "specify_cli._version._editable_marker_seen", return_value=False
+        ):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UNSUPPORTED
+
+    def test_tier3_uv_tool_when_registry_lists_exact_name(
+        self,
+        monkeypatch,
+        tmp_path,
+    ):
+        monkeypatch.setattr("sys.argv", [str(tmp_path / "missing" / "specify")])
+
+        def fake_which(name):
+            return "uv" if name == "uv" else None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["uv", "tool", "list"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="specify-cli v0.7.6\nother-tool v1.2.3\n",
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.UV_TOOL
+        assert signals.matched_tier == 3
+        assert "uv tool list" in signals.installer_registries_consulted
+
+    def test_unresolved_bare_argv0_skips_tier3_registry_detection(self, monkeypatch):
+        monkeypatch.setattr("sys.argv", ["specify"])
+
+        def fake_which(name):
+            return "uv" if name == "uv" else None
+
+        def fake_run(argv, *args, **kwargs):
+            return subprocess.CompletedProcess(
+                args=argv,
+                returncode=0,
+                stdout="specify-cli v0.7.6\n",
+                stderr="",
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.UNSUPPORTED
+        assert signals.installer_registries_consulted == ()
+
+    def test_bare_argv0_missing_path_resolution_allows_tier3_registry_detection(
+        self, monkeypatch, tmp_path
+    ):
+        missing_specify = tmp_path / "missing" / "specify"
+        monkeypatch.setattr("sys.argv", ["specify"])
+
+        def fake_which(name):
+            if name == "specify":
+                return str(missing_specify)
+            if name == "uv":
+                return "uv"
+            return None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["uv", "tool", "list"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="specify-cli v0.7.6\n",
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method, signals = _detect_install_method(include_signals=True)
+
+        assert method == _InstallMethod.UV_TOOL
+        assert signals.matched_tier == 3
+        assert "uv tool list" in signals.installer_registries_consulted
+
+    def test_missing_relative_argv0_falls_back_to_entrypoint_name_lookup(
+        self, monkeypatch, tmp_path
+    ):
+        if os.name == "nt":
+            monkeypatch.setenv("LOCALAPPDATA", str(tmp_path))
+            fake_dir = tmp_path / "uv" / "tools" / "specify-cli" / "bin"
+        else:
+            monkeypatch.setenv("HOME", str(tmp_path))
+            fake_dir = (
+                tmp_path / ".local" / "share" / "uv" / "tools" / "specify-cli" / "bin"
+            )
+        fake_dir.mkdir(parents=True)
+        fake_specify = fake_dir / "specify"
+        fake_specify.write_text("#!/usr/bin/env python\n")
+        monkeypatch.setattr("sys.argv", ["./bin/specify"])
+
+        def fake_which(name):
+            return str(fake_specify) if name == "specify" else None
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which):
+            method = _detect_install_method()
+
+        assert method == _InstallMethod.UV_TOOL
+
+    def test_tier3_uv_tool_ignores_substring_false_positive(
+        self,
+        unsupported_argv0,
+    ):
+        def fake_which(name):
+            return "uv" if name == "uv" else None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["uv", "tool", "list"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="my-specify-cli-helper v0.1.0\n",
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UNSUPPORTED
+
+    def test_tier3_uv_tool_does_not_override_absolute_unsupported_entrypoint(
+        self,
+        unsupported_argv0,
+    ):
+        def fake_which(name):
+            return "uv" if name == "uv" else None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["uv", "tool", "list"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="specify-cli v0.7.6\n",
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UNSUPPORTED
+
+    def test_tier3_uv_tool_does_not_override_resolved_bare_unsupported_entrypoint(
+        self,
+        monkeypatch,
+        tmp_path,
+    ):
+        venv_bin = tmp_path / "venv" / "bin"
+        venv_bin.mkdir(parents=True)
+        fake_specify = venv_bin / "specify"
+        fake_specify.write_text("#!/usr/bin/env python\n")
+        fake_specify.chmod(0o755)
+        monkeypatch.setattr("sys.argv", ["specify"])
+
+        def fake_which(name):
+            if name == "specify":
+                return str(fake_specify)
+            if name == "uv":
+                return "uv"
+            return None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["uv", "tool", "list"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="specify-cli v0.7.6\n",
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.UNSUPPORTED
+        assert signals.matched_tier is None
+        assert signals.installer_registries_consulted == ()
+
+
+class TestPrefixExpansion:
+    """Path-prefix expansion edge cases."""
+
+    def test_literal_dollar_without_variable_name_is_preserved(self, tmp_path):
+        prefix_path = tmp_path / "specify-$-cache" / "tools" / "specify-cli"
+        prefix = str(prefix_path)
+
+        expanded = specify_cli._version._expand_prefix(prefix)
+
+        assert expanded == prefix_path.resolve()
+
+    def test_unresolved_posix_variable_is_rejected(self):
+        assert specify_cli._version._expand_prefix("$SPECIFY_MISSING/specify-cli/") is None
+
+    def test_absolute_prefix_resolve_oserror_is_rejected(self, tmp_path):
+        prefix = str(tmp_path / "specify-cli")
+
+        with patch("pathlib.Path.resolve", side_effect=OSError("bad path")):
+            assert specify_cli._version._expand_prefix(prefix) is None
+
+
+class TestArgv0Resolution:
+    """Entrypoint path resolution edge cases."""
+
+    def test_absolute_argv0_resolve_oserror_returns_original_path(self, tmp_path):
+        argv0 = tmp_path / "specify"
+
+        with patch("pathlib.Path.resolve", side_effect=OSError("bad path")):
+            assert specify_cli._version._resolved_argv0_path(str(argv0)) == argv0
+
+    def test_path_lookup_resolve_oserror_returns_unresolved_lookup_path(self):
+        with patch(
+            "specify_cli._version.shutil.which", return_value="/broken/specify"
+        ), patch("pathlib.Path.resolve", side_effect=OSError("bad path")):
+            result = specify_cli._version._resolved_argv0_path("specify")
+
+        # Compare as Path objects: on Windows the same logical path renders
+        # with backslashes, so a raw string compare against the POSIX form
+        # would spuriously fail.
+        assert result == Path("/broken/specify")
+
+
+class TestArgvAssemblyUvTool:
+    """uv-tool installer argv shape."""
+
+    def test_stable_tag_produces_expected_argv(self):
+        with patch("specify_cli._version.shutil.which", return_value="uv"):
+            argv = _assemble_installer_argv(_InstallMethod.UV_TOOL, "v0.7.6")
+        assert argv == [
+            "uv",
+            "tool",
+            "install",
+            "specify-cli",
+            "--force",
+            "--from",
+            "git+https://github.com/github/spec-kit.git@v0.7.6",
+        ]
+
+    def test_dev_suffix_tag_embedded_literally(self):
+        with patch("specify_cli._version.shutil.which", return_value="uv"):
+            argv = _assemble_installer_argv(_InstallMethod.UV_TOOL, "v0.8.0.dev0")
+        assert "git+https://github.com/github/spec-kit.git@v0.8.0.dev0" in argv
+        assert (
+            "upgrade" not in argv
+        )  # never `uv tool upgrade` — does not accept --tag pinning
+
+    def test_missing_uv_returns_no_installer_argv(self):
+        with patch("specify_cli._version.shutil.which", return_value=None):
+            assert _assemble_installer_argv(_InstallMethod.UV_TOOL, "v0.7.6") is None
+
+
+class TestBareUpgradeUvTool:
+    """uv-tool happy path, bare invocation."""
+
+    def test_happy_path_end_to_end(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),  # installer
+                _completed_process(0, stdout="specify 0.7.6\n"),  # verify
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Upgrading specify-cli 0.7.5 → v0.7.6 via uv tool:" in out
+        assert "Upgraded specify-cli: 0.7.5 → 0.7.6" in out
+        assert mock_run.call_count == 2
+        for call in mock_run.call_args_list:
+            assert call.kwargs.get("shell", False) is False
+
+    def test_one_user_action_no_prompt(self, uv_tool_argv0, clean_environ):
+        # The single `invoke` represents the single user action — no prompt.
+        # If a prompt existed, runner.invoke would hang waiting for input.
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 0
+
+
+class TestAlreadyLatestUvTool:
+    """already on latest, no installer launched."""
+
+    def test_already_latest_exits_zero_no_subprocess(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.6"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        assert "Already on latest release: v0.7.6" in strip_ansi(result.output)
+        assert mock_run.call_count == 0
+
+    def test_trailing_zero_equivalent_version_reports_latest_not_newer(
+        self, uv_tool_argv0, clean_environ
+    ):
+        # Version("1.0") == Version("1.0.0") under packaging even though their
+        # canonical strings differ. The no-op message must use Version equality
+        # so this prints "Already on latest release", not "... or newer".
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="1.0"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v1.0.0"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Already on latest release: v1.0.0" in out
+        assert "or newer" not in out
+        assert mock_run.call_count == 0
+
+    def test_dev_build_ahead_of_release_reports_newer_noop(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.7.dev0"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        assert "Already on latest release or newer: 0.7.7.dev0" in strip_ansi(result.output)
+        assert mock_run.call_count == 0
+
+    def test_unparseable_current_version_does_not_false_noop(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="release-main"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Already on latest release" not in out
+        assert "Upgrading specify-cli release-main → v0.7.6 via uv tool:" in out
+        assert mock_run.call_count == 2
+
+    def test_unparseable_resolved_target_fails_before_literal_noop(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="release-main"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "release-main"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 1
+        out = strip_ansi(result.output)
+        assert "not a comparable version" in out
+        assert "release-main" not in out
+        assert "Already on latest release" not in out
+        assert mock_run.call_count == 0
+
+    def test_pinned_older_tag_still_runs_installer(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.6"
+        ):
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.5\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade", "--tag", "v0.7.5"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Already on latest release" not in out
+        # A pinned older tag is a downgrade and must be labelled as such.
+        assert "Downgrading specify-cli 0.7.6 → v0.7.5 via uv tool:" in out
+        assert "Upgrading specify-cli" not in out
+        assert mock_run.call_count == 2
+
+    def test_pinned_rc_tag_uses_canonical_version_equality_for_noop(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="1.0.0rc1"
+        ):
+            result = runner.invoke(app, ["self", "upgrade", "--tag", "v1.0.0-rc1"])
+
+        assert result.exit_code == 0
+        assert "Already on requested release: v1.0.0-rc1" in strip_ansi(result.output)
+
+
+class TestDryRunUvTool:
+    """--dry-run preview path + --dry-run combined with --tag."""
+
+    def test_dry_run_without_tag_resolves_network_but_no_subprocess(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Dry run — no changes will be made." in out
+        assert "Detected install method: uv tool" in out
+        assert "Current version: 0.7.5" in out
+        assert "Target version: v0.7.6" in out
+        assert "Command that would be executed:" in out
+        assert mock_run.call_count == 0
+
+    def test_dry_run_with_tag_skips_network(self, uv_tool_argv0, clean_environ):
+        # --dry-run with --tag must NOT hit the network.
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ), patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "v0.8.0"],
+            )
+        assert result.exit_code == 0
+        assert "Target version: v0.8.0" in strip_ansi(result.output)
+        mock_urlopen.assert_not_called()
+
+    def test_dry_run_rejects_unparseable_network_tag_before_preview(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+            mock_urlopen.return_value = mock_urlopen_response(
+                {"tag_name": "v0.9.0;echo unsafe"}
+            )
+            result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+
+        out = strip_ansi(result.output)
+        assert result.exit_code == 1
+        assert "not a comparable version" in out
+        assert "v0.9.0;echo unsafe" not in out
+        assert "Command that would be executed:" not in out
+        assert mock_run.call_count == 0
+
+    def test_dry_run_with_missing_uv_flags_unresolved_installer(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value=None
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Command that would be executed: (installer uv not found on PATH)" in out
+        assert "uv tool install" not in out
+        assert mock_run.call_count == 0
+
+
+# ===========================================================================
+# Phase 4 — User Story 2: `pipx` immediate upgrade (P2)
+# ===========================================================================
+
+
+class TestDetectionPipx:
+    """Pipx detection — tier 1 (path) and tier 3 (registry)."""
+
+    def test_posix_pipx_prefix_matches(self, pipx_argv0):
+        method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.PIPX
+        assert signals.matched_tier == 1
+
+    def test_tier3_pipx_when_no_prefix_match_but_registry_lists_it(
+        self,
+        monkeypatch,
+        tmp_path,
+    ):
+        monkeypatch.setattr("sys.argv", [str(tmp_path / "missing" / "specify")])
+
+        def fake_which(name):
+            return "pipx" if name == "pipx" else None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["pipx", "list", "--json"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout='{"venvs":{"specify-cli":{}}}',
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.PIPX
+        assert signals.matched_tier == 3
+        assert "pipx list --json" in signals.installer_registries_consulted
+
+    def test_tier3_pipx_does_not_override_absolute_unsupported_entrypoint(
+        self,
+        unsupported_argv0,
+    ):
+        def fake_which(name):
+            return "pipx" if name == "pipx" else None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["pipx", "list", "--json"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout='{"venvs":{"specify-cli":{}}}',
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UNSUPPORTED
+
+    def test_tier3_pipx_ignores_malformed_json_output(
+        self,
+        unsupported_argv0,
+    ):
+        def fake_which(name):
+            return "pipx" if name == "pipx" else None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["pipx", "list", "--json"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="not json but mentions specify-cli",
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method = _detect_install_method()
+        assert method == _InstallMethod.UNSUPPORTED
+
+    def test_tier3_both_uv_tool_and_pipx_match_is_treated_as_unsupported(
+        self,
+        monkeypatch,
+        tmp_path,
+    ):
+        monkeypatch.setattr("sys.argv", [str(tmp_path / "missing" / "specify")])
+
+        def fake_which(name):
+            if name == "uv":
+                return "uv"
+            if name == "pipx":
+                return "pipx"
+            return None
+
+        def fake_run(argv, *args, **kwargs):
+            if argv[:3] == ["uv", "tool", "list"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout="specify-cli v0.7.6\n",
+                    stderr="",
+                )
+            if argv[:3] == ["pipx", "list", "--json"]:
+                return subprocess.CompletedProcess(
+                    args=argv,
+                    returncode=0,
+                    stdout='{"venvs":{"specify-cli":{}}}',
+                    stderr="",
+                )
+            return subprocess.CompletedProcess(
+                args=argv, returncode=1, stdout="", stderr=""
+            )
+
+        with patch("specify_cli._version.shutil.which", side_effect=fake_which), patch(
+            "specify_cli._version.subprocess.run", side_effect=fake_run
+        ), patch("specify_cli._version._editable_marker_seen", return_value=False):
+            method, signals = _detect_install_method(include_signals=True)
+        assert method == _InstallMethod.UNSUPPORTED
+        assert signals.matched_tier is None
+        assert "uv tool list" in signals.installer_registries_consulted
+        assert "pipx list --json" in signals.installer_registries_consulted
+
+
+class TestEditableInstallMetadata:
+    @pytest.mark.skipif(
+        not hasattr(importlib.metadata, "InvalidMetadataError"),
+        reason=(
+            "importlib.metadata.InvalidMetadataError does not exist on this "
+            "Python; _editable_direct_url_path only catches it when present, so "
+            "fabricating it would exercise a path that cannot fire in production"
+        ),
+    )
+    def test_editable_marker_false_when_metadata_is_invalid(self):
+        invalid_metadata_error = importlib.metadata.InvalidMetadataError
+
+        with patch(
+            "importlib.metadata.distribution",
+            side_effect=invalid_metadata_error("bad metadata"),
+        ):
+            assert specify_cli._version._editable_marker_seen() is False
+            assert specify_cli._version._source_checkout_path() is None
+
+    def test_direct_url_editable_install_marks_source_checkout(self, tmp_path):
+        project_root = tmp_path / "spec-kit"
+        project_root.mkdir()
+        (project_root / ".git").mkdir()
+
+        class FakeDist:
+            files = []
+
+            def read_text(self, name):
+                if name == "direct_url.json":
+                    return json.dumps(
+                        {
+                            "dir_info": {"editable": True},
+                            "url": project_root.as_uri(),
+                        }
+                    )
+                return None
+
+            def locate_file(self, file):
+                return file
+
+        with patch("importlib.metadata.distribution", return_value=FakeDist()):
+            assert specify_cli._version._editable_marker_seen() is True
+            assert specify_cli._version._source_checkout_path() == project_root.resolve()
+
+    def test_editable_marker_false_without_explicit_editable_metadata(self, tmp_path):
+        repo_root = tmp_path / "repo"
+        repo_root.mkdir()
+        (repo_root / ".git").mkdir()
+        venv_file = repo_root / ".venv" / "lib" / "python3.13" / "site-packages" / "specify_cli.py"
+        venv_file.parent.mkdir(parents=True)
+        venv_file.write_text("# installed module\n")
+
+        class FakeDist:
+            files = ["specify_cli.py"]
+
+            def read_text(self, name):
+                return None
+
+            def locate_file(self, file):
+                return venv_file
+
+        with patch("importlib.metadata.distribution", return_value=FakeDist()):
+            assert specify_cli._version._editable_marker_seen() is False
+
+
+class TestTagValidationWhitespace:
+    def test_tag_whitespace_is_trimmed_before_validation(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v9.9.9"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.8.0\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade", "--tag", " v0.8.0 "])
+
+        assert result.exit_code == 0
+        assert "v0.8.0" in strip_ansi(result.output)
+
+
+class TestArgvAssemblyPipx:
+    """pipx installer argv shape — pipx 1.5+ uses positional PACKAGE_SPEC, never `--spec` or `upgrade`."""
+
+    def test_pipx_argv_uses_install_force_positional_not_upgrade(self):
+        with patch("specify_cli._version.shutil.which", return_value="pipx"):
+            argv = _assemble_installer_argv(_InstallMethod.PIPX, "v0.7.6")
+        assert argv == [
+            "pipx",
+            "install",
+            "--force",
+            "git+https://github.com/github/spec-kit.git@v0.7.6",
+        ]
+        assert "upgrade" not in argv  # pipx upgrade does not accept arbitrary refs
+        assert "--spec" not in argv  # pipx 1.5+ dropped the --spec flag
+
+    def test_missing_pipx_returns_no_installer_argv(self):
+        with patch("specify_cli._version.shutil.which", return_value=None):
+            assert _assemble_installer_argv(_InstallMethod.PIPX, "v0.7.6") is None
+
+
+class TestBareUpgradePipx:
+    """pipx happy path."""
+
+    def test_happy_path(self, pipx_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="pipx"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "via pipx:" in out
+        assert "Upgraded specify-cli: 0.7.5 → 0.7.6" in out
+
+
+class TestDetectionShortCircuit:
+    """Tier-1 path-prefix matches short-circuit before registry checks."""
+
+    def test_pipx_argv0_prefix_short_circuits_before_registry_checks(
+        self,
+        pipx_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli._version.shutil.which", return_value="/usr/bin/X"), patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run:
+            method = _detect_install_method()
+        assert method == _InstallMethod.PIPX
+        mock_run.assert_not_called()
+
+
+class TestDryRunPipx:
+    def test_dry_run_preview_names_pipx(self, pipx_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="pipx"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+        assert result.exit_code == 0
+        assert "Detected install method: pipx" in strip_ansi(result.output)
+        assert mock_run.call_count == 0

tests/test_self_upgrade_execution.py

@@ -0,0 +1,542 @@
+"""Installer execution, verification, and error-path tests for `specify self upgrade`."""
+
+import errno
+import subprocess
+from unittest.mock import patch
+
+from specify_cli import app
+
+from tests.self_upgrade_helpers import (
+    _completed_process,
+    mock_urlopen_response,
+    requires_posix,
+    runner,
+    strip_ansi,
+)
+
+# ===========================================================================
+# Phase 6 — User Story 4: failure recovery (P2)
+# ===========================================================================
+
+
+class TestInstallerMissing:
+    """Installer disappeared between detection and run → exit 3."""
+
+    def test_uv_missing_exits_3(self, uv_tool_argv0, clean_environ):
+        which_results = {"specify": "/usr/local/bin/specify"}
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda n: which_results.get(n)
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 3
+        out = strip_ansi(result.output)
+        assert "Installer uv not found on PATH; reinstall it and retry." in out
+        assert "Upgrading specify-cli" not in out
+
+    def test_pipx_missing_exits_3(self, pipx_argv0, clean_environ):
+        which_results = {}
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda n: which_results.get(n)
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 3
+        assert "Installer pipx not found on PATH" in strip_ansi(result.output)
+
+    def test_absolute_installer_path_does_not_require_path_lookup(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "installer-bin" / "uv"
+        fake_uv.parent.mkdir()
+        fake_uv.write_text("#!/bin/sh\n")
+        fake_uv.chmod(0o755)
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ), patch(
+            "specify_cli._version._verify_upgrade", return_value="0.7.6"
+        ), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                str(fake_uv),
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(0)]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 0
+
+    @requires_posix
+    def test_relative_installer_path_does_not_require_path_lookup(
+        self, monkeypatch, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "uv"
+        fake_uv.write_text("#!/bin/sh\n")
+        fake_uv.chmod(0o755)
+        monkeypatch.chdir(tmp_path)
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ), patch(
+            "specify_cli._version._verify_upgrade", return_value="0.7.6"
+        ), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                "./uv",
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(0)]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        assert mock_run.call_args.args[0][0] == "./uv"
+
+    @requires_posix
+    def test_relative_installer_path_missing_gets_path_specific_message(
+        self, monkeypatch, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        monkeypatch.chdir(tmp_path)
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                "./uv",
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 3
+        assert (
+            "Installer path ./uv no longer exists; reinstall it and retry."
+            in strip_ansi(result.output)
+        )
+        assert "not found on PATH" not in strip_ansi(result.output)
+
+    def test_resolved_absolute_installer_removed_before_exec_gets_missing_path_message(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "installer-bin" / "uv"
+        fake_uv.parent.mkdir()
+        fake_uv.write_text("#!/bin/sh\n")
+        fake_uv.chmod(0o755)
+
+        def fake_run(argv, *args, **kwargs):
+            fake_uv.unlink()
+            raise FileNotFoundError(str(fake_uv))
+
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which",
+            side_effect=lambda name: str(fake_uv) if name == "uv" else None,
+        ), patch("specify_cli._version.subprocess.run", side_effect=fake_run), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 3
+        assert (
+            f"Installer path {fake_uv} no longer exists; reinstall it and retry."
+            in strip_ansi(result.output)
+        )
+
+    def test_absolute_installer_path_not_executable_gets_specific_message(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "installer-bin" / "uv"
+        fake_uv.parent.mkdir()
+        fake_uv.write_text("#!/bin/sh\n")
+        fake_uv.chmod(0o644)
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version.os.access", return_value=False), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                str(fake_uv),
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 3
+        assert (
+            f"Installer path {fake_uv} is not an executable file; fix the path or reinstall it and retry."
+            in strip_ansi(result.output)
+        )
+
+    @requires_posix
+    def test_relative_installer_path_not_executable_gets_path_specific_message(
+        self, monkeypatch, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "uv"
+        fake_uv.write_text("#!/bin/sh\n")
+        fake_uv.chmod(0o644)
+        monkeypatch.chdir(tmp_path)
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version.os.access", return_value=False), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                "./uv",
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        out = strip_ansi(result.output)
+        assert result.exit_code == 3
+        assert (
+            "Installer path ./uv is not an executable file; fix the path or reinstall it and retry."
+            in out
+        )
+        assert "Installer ./uv is not executable" not in out
+
+    def test_real_installer_exit_126_is_not_treated_as_invalid_path(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(126)]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 126
+        out = strip_ansi(result.output)
+        assert "Upgrade failed. Installer exit code: 126." in out
+        assert "not an executable file" not in out
+
+    def test_absolute_installer_path_missing_gets_path_specific_message(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "missing-installer" / "uv"
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                str(fake_uv),
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 3
+        assert (
+            f"Installer path {fake_uv} no longer exists; reinstall it and retry."
+            in strip_ansi(result.output)
+        )
+        mock_run.assert_not_called()
+
+    def test_exec_oserror_is_treated_as_invalid_installer(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "installer-bin" / "uv"
+        fake_uv.parent.mkdir()
+        fake_uv.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+        fake_uv.chmod(0o755)
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                str(fake_uv),
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ), patch(
+            "specify_cli._version.subprocess.run",
+            side_effect=PermissionError("Permission denied"),
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 3
+        out = strip_ansi(result.output)
+        assert f"Installer path {fake_uv} is not an executable file" in out
+        assert "not found on PATH" not in out
+
+    def test_bare_invalid_installer_message_does_not_call_it_a_path(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                "uv",
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ), patch(
+            "specify_cli._version.subprocess.run",
+            side_effect=PermissionError("Permission denied"),
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 3
+        out = strip_ansi(result.output)
+        assert "Installer uv is not executable" in out
+        assert "Installer path uv" not in out
+
+    def test_exec_oserror_errno_is_treated_as_invalid_installer(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "installer-bin" / "uv"
+        fake_uv.parent.mkdir()
+        fake_uv.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+        fake_uv.chmod(0o755)
+        invalid_error = OSError(errno.ENOEXEC, "Exec format error")
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                str(fake_uv),
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ), patch("specify_cli._version.subprocess.run", side_effect=invalid_error):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 3
+        out = strip_ansi(result.output)
+        assert f"Installer path {fake_uv} is not an executable file" in out
+        assert "not found on PATH" not in out
+
+    def test_transient_exec_oserror_is_not_treated_as_invalid_installer(
+        self, uv_tool_argv0, clean_environ, tmp_path
+    ):
+        fake_uv = tmp_path / "installer-bin" / "uv"
+        fake_uv.parent.mkdir()
+        fake_uv.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+        fake_uv.chmod(0o755)
+        transient_error = OSError(errno.EMFILE, "Too many open files")
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"), patch(
+            "specify_cli._version._assemble_installer_argv",
+            return_value=[
+                str(fake_uv),
+                "tool",
+                "install",
+                "specify-cli",
+                "--force",
+                "--from",
+                "git+https://github.com/github/spec-kit.git@v0.7.6",
+            ],
+        ), patch("specify_cli._version.subprocess.run", side_effect=transient_error):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        # Transient/unknown OSErrors are re-raised rather than mapped to the
+        # invalid-installer exit 3, so the CLI surfaces them as an uncaught
+        # error: exit code 1 with the original OSError preserved.
+        assert result.exit_code == 1
+        assert isinstance(result.exception, OSError)
+
+
+class TestInstallerFailed:
+    """Installer non-zero exit → propagate code, print rollback hint."""
+
+    def test_installer_exit_2_propagates(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(2)]  # installer fails
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Upgrade failed. Installer exit code: 2." in out
+        assert "Try again or run the command manually:" in out
+        assert "git+https://github.com/github/spec-kit.git@v0.7.6" in out
+        assert (
+            "To pin back to the previous version: "
+            "uv tool install specify-cli --force --from "
+            "git+https://github.com/github/spec-kit.git@v0.7.5"
+        ) in out
+        # No verification attempted after a failed installer run.
+        assert mock_run.call_count == 1
+
+    def test_installer_exit_127_propagates(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(127)]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 127
+
+    def test_installer_timeout_prints_timeout_specific_message(
+        self, uv_tool_argv0, clean_environ, monkeypatch
+    ):
+        monkeypatch.setenv("SPECIFY_UPGRADE_TIMEOUT_SECS", "12")
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                subprocess.TimeoutExpired(cmd=["uv"], timeout=12)
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 124
+        out = strip_ansi(result.output)
+        assert "Upgrade timed out while waiting for the installer subprocess." in out
+        assert "SPECIFY_UPGRADE_TIMEOUT_SECS=12" in out
+
+    def test_non_finite_timeout_warns_and_runs_without_timeout(
+        self, uv_tool_argv0, clean_environ, monkeypatch
+    ):
+        monkeypatch.setenv("SPECIFY_UPGRADE_TIMEOUT_SECS", "nan")
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        assert "Ignoring invalid SPECIFY_UPGRADE_TIMEOUT_SECS='nan'" in strip_ansi(
+            result.output
+        )
+        assert mock_run.call_args_list[0].kwargs["timeout"] is None
+
+    def test_real_installer_exit_124_is_not_treated_as_timeout(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(124)]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 124
+        out = strip_ansi(result.output)
+        assert "Upgrade failed. Installer exit code: 124." in out
+        assert "Upgrade timed out while waiting for the installer subprocess." not in out
+
+    def test_pipx_failure_prints_pipx_rollback_hint(self, pipx_argv0, clean_environ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="pipx"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(2)]
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert (
+            "To pin back to the previous version: pipx install --force "
+            "git+https://github.com/github/spec-kit.git@v0.7.5"
+        ) in out
+
+    def test_rollback_hint_accepts_normalizable_stable_snapshot(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="v0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(2)]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert (
+            "To pin back to the previous version: uv tool install specify-cli --force "
+            "--from git+https://github.com/github/spec-kit.git@v0.7.5"
+        ) in out
+        assert "Previous version was not an exact stable release tag" not in out
+
+    def test_prerelease_failure_degrades_rollback_hint_to_releases_page(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="1.0.0rc1"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v1.0.0"})
+            mock_run.side_effect = [_completed_process(2)]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Previous version was not an exact stable release tag" in out
+        assert "https://github.com/github/spec-kit/releases" in out
+        assert "git+https://github.com/github/spec-kit.git@v1.0.0rc1" not in out

tests/test_self_upgrade_guidance.py

@@ -0,0 +1,184 @@
+"""Non-upgradable path guidance tests for `specify self upgrade`."""
+
+from unittest.mock import patch
+
+from specify_cli import app
+
+from tests.self_upgrade_helpers import (
+    mock_urlopen_response,
+    runner,
+    strip_ansi,
+)
+
+# ===========================================================================
+# Phase 5 — User Story 3: non-upgradable path guidance (P3)
+# ===========================================================================
+
+
+class TestUvxEphemeral:
+    """uvx ephemeral path emits exact one-liner, no installer call."""
+
+    def test_uvx_argv0_prints_exact_one_liner_and_exits_zero(
+        self,
+        uvx_ephemeral_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run:
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 0
+        expected = (
+            "Running via uvx (ephemeral); the next uvx invocation already "
+            "resolves to latest — no upgrade action needed."
+        )
+        assert expected in strip_ansi(result.output)
+        assert mock_run.call_count == 0
+
+    def test_offline_still_exits_zero_without_tag_resolution(
+        self,
+        uvx_ephemeral_argv0,
+        clean_environ,
+    ):
+        with patch(
+            "specify_cli.authentication.http.urllib.request.urlopen",
+            side_effect=AssertionError("non-upgradable uvx path must not hit network"),
+        ):
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 0
+        assert "uvx (ephemeral)" in strip_ansi(result.output)
+
+
+class TestSourceCheckout:
+    """Editable install path emits git pull guidance."""
+
+    def test_source_checkout_prints_git_pull_guidance(
+        self,
+        unsupported_argv0,
+        tmp_path,
+        clean_environ,
+    ):
+        fake_tree = tmp_path / "worktree"
+        fake_tree.mkdir()
+        (fake_tree / ".git").mkdir()
+
+        with patch("specify_cli._version._editable_marker_seen", return_value=True), patch(
+            "specify_cli._version._source_checkout_path", return_value=fake_tree
+        ), patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run:
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert f"Running from a source checkout at {fake_tree}" in out
+        assert "git pull" in out
+        assert "pip install -e ." in out
+        assert mock_run.call_count == 0
+
+    def test_source_checkout_without_path_mentions_checkout_directory(
+        self,
+        unsupported_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli._version._editable_marker_seen", return_value=True), patch(
+            "specify_cli._version._source_checkout_path", return_value=None
+        ), patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run:
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        out = strip_ansi(result.output)
+        assert result.exit_code == 0
+        assert "checkout path could not be detected" in out
+        assert "from your checkout directory" in out
+        assert "(path unavailable)" not in out
+        assert mock_run.call_count == 0
+
+
+class TestUnsupported:
+    """Unsupported path enumerates manual reinstall commands."""
+
+    def test_unsupported_prints_both_reinstall_commands(
+        self,
+        unsupported_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli._version._editable_marker_seen", return_value=False), patch(
+            "specify_cli._version.shutil.which", return_value=None
+        ), patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run:
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Could not identify your install method automatically" in out
+        assert (
+            "uv tool install specify-cli --force --from "
+            "git+https://github.com/github/spec-kit.git@vX.Y.Z"
+        ) in out
+        assert (
+            "pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z"
+            in out
+        )
+        assert mock_run.call_count == 0
+
+    def test_unsupported_offline_degrades_to_placeholder_manual_commands(
+        self,
+        unsupported_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli._version._editable_marker_seen", return_value=False), patch(
+            "specify_cli._version.shutil.which", return_value=None
+        ), patch(
+            "specify_cli.authentication.http.urllib.request.urlopen",
+            side_effect=AssertionError("unsupported guidance should not require network"),
+        ):
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Could not identify your install method automatically" in out
+        assert (
+            "uv tool install specify-cli --force --from "
+            "git+https://github.com/github/spec-kit.git@vX.Y.Z"
+        ) in out
+        assert (
+            "pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z"
+            in out
+        )
+
+
+class TestDryRunNonUpgradablePaths:
+    """--dry-run on non-upgradable paths emits guidance, not preview."""
+
+    def test_dry_run_on_uvx_ephemeral_emits_guidance_not_preview(
+        self,
+        uvx_ephemeral_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Dry run — no changes will be made." not in out
+        assert "uvx (ephemeral)" in out
+
+    def test_dry_run_on_unsupported_emits_manual_commands(
+        self,
+        unsupported_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli._version._editable_marker_seen", return_value=False), patch(
+            "specify_cli._version.shutil.which", return_value=None
+        ), patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            result = runner.invoke(app, ["self", "upgrade", "--dry-run"])
+        assert result.exit_code == 0
+        assert "Could not identify your install method" in strip_ansi(result.output)

tests/test_self_upgrade_verification.py

@@ -0,0 +1,649 @@
+"""Verification, resolution, and validation tests for `specify self upgrade`."""
+
+import urllib.error
+from unittest.mock import patch
+
+import pytest
+import specify_cli
+from specify_cli import app
+
+from tests.self_upgrade_helpers import (
+    SENTINEL_GH_TOKEN,
+    SENTINEL_GITHUB_TOKEN,
+    _InstallMethod,
+    _UpgradePlan,
+    _completed_process,
+    _verify_upgrade,
+    mock_urlopen_response,
+    runner,
+    strip_ansi,
+)
+
+# ===========================================================================
+# Phase 6 — User Story 4: failure recovery (P2)
+# ===========================================================================
+
+
+class TestVerificationMismatch:
+    """Installer says 0 but the binary is still the old version → exit 2."""
+
+    def test_installer_ok_but_verify_returns_old_version(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),  # installer OK
+                _completed_process(0, stdout="specify 0.7.5\n"),  # verify: OLD!
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Verification failed" in out
+        assert "resolves to 0.7.5 (expected v0.7.6)" in out
+        assert "The new version may take effect on your next invocation." in out
+
+    def test_verify_nonzero_exit_is_not_treated_as_success(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(1, stdout="specify 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Verification failed" in out
+        assert "(unknown) (expected v0.7.6)" in out
+
+    def test_verify_accepts_pep440_equivalent_rc_version(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.9.0"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v9.9.9"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 1.0.0rc1\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade", "--tag", "v1.0.0-rc1"])
+
+        assert result.exit_code == 0
+        assert "Upgraded specify-cli: 0.9.0 → 1.0.0rc1" in strip_ansi(result.output)
+
+    def test_verify_accepts_specify_cli_binary_name_in_version_output(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify-cli version 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        assert "Upgraded specify-cli: 0.7.5 → 0.7.6" in strip_ansi(result.output)
+
+    def test_verify_accepts_capitalized_binary_name_in_version_output(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="Specify, version 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        assert "Upgraded specify-cli: 0.7.5 → 0.7.6" in strip_ansi(result.output)
+
+    def test_verify_rejects_output_without_parseable_version(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify version unknown\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Verification failed" in out
+        assert "(unknown) (expected v0.7.6)" in out
+
+    def test_verify_uses_current_entrypoint_when_not_on_path(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        assert uv_tool_argv0.exists()
+        assert uv_tool_argv0.is_file()
+
+        plan = _UpgradePlan(
+            method=_InstallMethod.UV_TOOL,
+            current_version="0.7.5",
+            target_tag="v0.7.6",
+            installer_argv=["/usr/bin/uv", "tool", "install", "specify-cli"],
+            preview_summary="",
+            pre_upgrade_snapshot="0.7.5",
+        )
+
+        with patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: None
+        ), patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.os.access", return_value=True
+        ):
+            mock_run.return_value = _completed_process(0, stdout="specify 0.7.6\n")
+            verified = _verify_upgrade(plan)
+
+        assert verified == "0.7.6"
+        assert mock_run.call_args.args[0][0] == str(uv_tool_argv0)
+        assert mock_run.call_args.kwargs["timeout"] == specify_cli._version._VERIFY_TIMEOUT_SECS
+
+    def test_verify_falls_back_to_path_when_current_entrypoint_is_not_executable(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        plan = _UpgradePlan(
+            method=_InstallMethod.UV_TOOL,
+            current_version="0.7.5",
+            target_tag="v0.7.6",
+            installer_argv=["/usr/bin/uv", "tool", "install", "specify-cli"],
+            preview_summary="",
+            pre_upgrade_snapshot="0.7.5",
+        )
+
+        with patch(
+            "specify_cli._version.shutil.which",
+            side_effect=lambda name: "/usr/local/bin/specify" if name == "specify" else None,
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version.os.access", return_value=False
+        ):
+            mock_run.return_value = _completed_process(0, stdout="specify 0.7.6\n")
+            verified = _verify_upgrade(plan)
+
+        assert verified == "0.7.6"
+        assert mock_run.call_args.args[0][0] == "/usr/local/bin/specify"
+
+    def test_verify_ignores_python_entrypoint_and_falls_back_to_specify(
+        self,
+        clean_environ,
+        tmp_path,
+    ):
+        fake_python = tmp_path / "python3"
+        fake_python.write_text("#!/bin/sh\n")
+        fake_python.chmod(0o755)
+
+        plan = _UpgradePlan(
+            method=_InstallMethod.UV_TOOL,
+            current_version="0.7.5",
+            target_tag="v0.7.6",
+            installer_argv=["/usr/bin/uv", "tool", "install", "specify-cli"],
+            preview_summary="",
+            pre_upgrade_snapshot="0.7.5",
+        )
+
+        with patch(
+            "specify_cli._version.shutil.which", side_effect=lambda name: "/usr/local/bin/specify" if name == "specify" else None
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version.sys.argv", [str(fake_python)]
+        ), patch(
+            "specify_cli._version.os.access", return_value=True
+        ):
+            mock_run.return_value = _completed_process(0, stdout="specify 0.7.6\n")
+            verified = _verify_upgrade(plan)
+
+        assert verified == "0.7.6"
+        assert mock_run.call_args.args[0][0] == "/usr/local/bin/specify"
+
+    def test_verify_accepts_specify_cli_named_current_entrypoint(
+        self,
+        clean_environ,
+        tmp_path,
+    ):
+        fake_specify_cli = tmp_path / "specify-cli"
+        fake_specify_cli.write_text("#!/bin/sh\n")
+        fake_specify_cli.chmod(0o755)
+
+        plan = _UpgradePlan(
+            method=_InstallMethod.UV_TOOL,
+            current_version="0.7.5",
+            target_tag="v0.7.6",
+            installer_argv=["/usr/bin/uv", "tool", "install", "specify-cli"],
+            preview_summary="",
+            pre_upgrade_snapshot="0.7.5",
+        )
+
+        with patch("specify_cli._version.shutil.which", return_value=None), patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch("specify_cli._version.sys.argv", [str(fake_specify_cli)]), patch(
+            "specify_cli._version.os.access", return_value=True
+        ):
+            mock_run.return_value = _completed_process(0, stdout="specify 0.7.6\n")
+            verified = _verify_upgrade(plan)
+
+        assert verified == "0.7.6"
+        assert mock_run.call_args.args[0][0] == str(fake_specify_cli)
+
+
+class TestResolutionFailures:
+    """Pre-installer resolution failure → exit 1, reusing the resolver category strings."""
+
+    def test_offline_exits_1_with_phase1_string(self, uv_tool_argv0, clean_environ):
+        with patch(
+            "specify_cli.authentication.http.urllib.request.urlopen",
+            side_effect=urllib.error.URLError("nope"),
+        ):
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 1
+        assert "Upgrade aborted: offline or timeout" in strip_ansi(result.output)
+
+    def test_rate_limited_exits_1(self, uv_tool_argv0, clean_environ):
+        err = urllib.error.HTTPError(
+            url="https://api.github.com",
+            code=403,
+            msg="rate limited",
+            hdrs={},  # type: ignore[arg-type]
+            fp=None,
+        )
+        with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=err):
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 1
+        assert (
+            "Upgrade aborted: rate limited (configure ~/.specify/auth.json with a GitHub token)"
+            in strip_ansi(result.output)
+        )
+
+    def test_http_500_exits_1(self, uv_tool_argv0, clean_environ):
+        err = urllib.error.HTTPError(
+            url="https://api.github.com",
+            code=500,
+            msg="srv err",
+            hdrs={},  # type: ignore[arg-type]
+            fp=None,
+        )
+        with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=err):
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 1
+        assert "Upgrade aborted: HTTP 500" in strip_ansi(result.output)
+
+    @pytest.mark.parametrize(
+        "code, expected",
+        [
+            # 429 (Too Many Requests / secondary rate limit) gets the same
+            # actionable token hint as 403; other statuses surface verbatim.
+            (
+                429,
+                "Upgrade aborted: rate limited (configure ~/.specify/auth.json "
+                "with a GitHub token)",
+            ),
+            (404, "Upgrade aborted: HTTP 404"),
+            (502, "Upgrade aborted: HTTP 502"),
+        ],
+    )
+    def test_http_error_categorization(
+        self, code, expected, uv_tool_argv0, clean_environ
+    ):
+        err = urllib.error.HTTPError(
+            url="https://api.github.com",
+            code=code,
+            msg="err",
+            hdrs={},  # type: ignore[arg-type]
+            fp=None,
+        )
+        with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=err):
+            result = runner.invoke(app, ["self", "upgrade"])
+        assert result.exit_code == 1
+        assert expected in strip_ansi(result.output)
+
+    def test_unparseable_resolved_release_tag_exits_1_without_traceback(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.subprocess.run"
+        ) as mock_run, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version._get_installed_version", return_value="0.7.5"):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "release-main"})
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 1
+        out = strip_ansi(result.output)
+        assert "resolved release tag is not a comparable version" in out
+        assert "release-main" not in out
+        assert "Traceback" not in out
+        assert mock_run.call_count == 0
+
+
+class TestTagValidation:
+    """--tag regex enforcement."""
+
+    def test_valid_stable_tag(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "v0.7.6"],
+            )
+        assert result.exit_code == 0
+
+    def test_valid_dev_suffix_tag(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "v0.8.0.dev0"],
+            )
+        assert result.exit_code == 0
+        assert "Target version: v0.8.0.dev0" in strip_ansi(result.output)
+
+    def test_valid_rc_tag(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "v1.0.0-rc1"],
+            )
+        assert result.exit_code == 0
+
+    def test_valid_beta_dot_tag_uses_pep440_equivalent_for_noop(
+        self, uv_tool_argv0, clean_environ
+    ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="1.0.0b1"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--tag", "v1.0.0-beta.1"],
+            )
+        assert result.exit_code == 0
+        assert "Already on requested release: v1.0.0-beta.1" in strip_ansi(
+            result.output
+        )
+
+    def test_valid_build_metadata_tag(self, uv_tool_argv0, clean_environ):
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "v0.8.0+build.42"],
+            )
+        assert result.exit_code == 0
+        assert "Target version: v0.8.0+build.42" in strip_ansi(result.output)
+
+    def test_uppercase_v_prefix_is_folded_to_lowercase(
+        self, uv_tool_argv0, clean_environ
+    ):
+        # A pasted uppercase `V` prefix is accepted and normalized to `v` so
+        # the git ref matches the canonical lowercase release tag.
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "V0.7.6"],
+            )
+        assert result.exit_code == 0
+        assert "Target version: v0.7.6" in strip_ansi(result.output)
+
+    def test_valid_prerelease_with_build_metadata_tag(
+        self, uv_tool_argv0, clean_environ
+    ):
+        # Prerelease and build-metadata suffixes compose (PEP 440 / semver).
+        with patch("specify_cli._version.shutil.which", return_value="uv"), patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            result = runner.invoke(
+                app,
+                ["self", "upgrade", "--dry-run", "--tag", "v1.0.0-rc1+build.42"],
+            )
+        assert result.exit_code == 0
+        assert "Target version: v1.0.0-rc1+build.42" in strip_ansi(result.output)
+
+    @pytest.mark.parametrize(
+        "bad_tag",
+        [
+            "latest",
+            "0.7.5",
+            "main",
+            "v7",
+            "",
+            "v1.2.3abc",
+            "v1.2.3...",
+            "v1.2.3++",
+            "v\uff11.2.3",
+            "v1.\u0662.3",
+        ],
+    )
+    def test_invalid_tags_rejected(self, bad_tag, uv_tool_argv0, clean_environ):
+        result = runner.invoke(app, ["self", "upgrade", "--tag", bad_tag])
+        assert result.exit_code == 1
+        output = strip_ansi(result.output)
+        assert "Invalid --tag" in output or "expected vMAJOR.MINOR.PATCH" in output
+
+
+class TestUnknownCurrent:
+    """'unknown' current version renders literally in notice and success message."""
+
+    def test_unknown_current_renders_literal_in_notice(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="unknown"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 0
+        out = strip_ansi(result.output)
+        assert "Upgrading specify-cli unknown → v0.7.6 via uv tool:" in out
+        assert "Upgraded specify-cli: unknown → 0.7.6" in out
+
+    def test_unknown_current_rollback_hint_degrades(
+        self,
+        uv_tool_argv0,
+        clean_environ,
+    ):
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="unknown"
+        ):
+            mock_urlopen.return_value = mock_urlopen_response({"tag_name": "v0.7.6"})
+            mock_run.side_effect = [_completed_process(2)]  # installer fails
+            result = runner.invoke(app, ["self", "upgrade"])
+
+        assert result.exit_code == 2
+        out = strip_ansi(result.output)
+        assert "Could not determine the previous version" in out
+        assert "https://github.com/github/spec-kit/releases" in out
+
+
+class TestTokenScrubbing:
+    """GH_TOKEN / GITHUB_TOKEN are stripped from every child env."""
+
+    def test_env_passed_to_subprocess_has_no_github_tokens(
+        self,
+        uv_tool_argv0,
+        monkeypatch,
+    ):
+        monkeypatch.setenv("GH_TOKEN", SENTINEL_GH_TOKEN)
+        monkeypatch.setenv("GITHUB_TOKEN", SENTINEL_GITHUB_TOKEN)
+        response = mock_urlopen_response({"tag_name": "v0.7.6"})
+
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli.authentication.http.urllib.request.build_opener"
+        ) as mock_build_opener, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = response
+            mock_build_opener.return_value.open.return_value = response
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            runner.invoke(app, ["self", "upgrade"])
+
+        assert mock_run.call_count >= 1
+        for call in mock_run.call_args_list:
+            env_kwarg = call.kwargs.get("env") or {}
+            assert "GH_TOKEN" not in env_kwarg, f"env leaked GH_TOKEN: {env_kwarg!r}"
+            assert "GITHUB_TOKEN" not in env_kwarg
+            for v in env_kwarg.values():
+                assert SENTINEL_GH_TOKEN not in v
+                assert SENTINEL_GITHUB_TOKEN not in v
+
+    def test_env_scrubbing_is_case_insensitive(
+        self,
+        uv_tool_argv0,
+        monkeypatch,
+    ):
+        monkeypatch.setenv("gh_token", SENTINEL_GH_TOKEN)
+        monkeypatch.setenv("GitHub_Token", SENTINEL_GITHUB_TOKEN)
+        response = mock_urlopen_response({"tag_name": "v0.7.6"})
+
+        with patch("specify_cli.authentication.http.urllib.request.urlopen") as mock_urlopen, patch(
+            "specify_cli.authentication.http.urllib.request.build_opener"
+        ) as mock_build_opener, patch(
+            "specify_cli._version.shutil.which", return_value="uv"
+        ), patch("specify_cli._version.subprocess.run") as mock_run, patch(
+            "specify_cli._version._get_installed_version", return_value="0.7.5"
+        ):
+            mock_urlopen.return_value = response
+            mock_build_opener.return_value.open.return_value = response
+            mock_run.side_effect = [
+                _completed_process(0),
+                _completed_process(0, stdout="specify 0.7.6\n"),
+            ]
+            runner.invoke(app, ["self", "upgrade"])
+
+        assert mock_run.call_count >= 1
+        for call in mock_run.call_args_list:
+            env_kwarg = call.kwargs.get("env") or {}
+            assert "gh_token" not in env_kwarg
+            assert "GitHub_Token" not in env_kwarg
+            for v in env_kwarg.values():
+                assert SENTINEL_GH_TOKEN not in v
+                assert SENTINEL_GITHUB_TOKEN not in v
+
+    def test_env_scrubbing_removes_github_token_variants(self, monkeypatch):
+        monkeypatch.setenv("GH_PAT", "gh-pat")
+        monkeypatch.setenv("GH_TOKEN_FILE", "gh-token-file")
+        monkeypatch.setenv("GH_ENTERPRISE_TOKEN", "enterprise-gh")
+        monkeypatch.setenv("GH_ENTERPRISE_SECRET", "enterprise-secret")
+        monkeypatch.setenv("GH_ENTERPRISE_PRIVATE_KEY", "enterprise-key")
+        monkeypatch.setenv("GITHUB_PAT", "github-pat")
+        monkeypatch.setenv("GITHUB_TOKEN_PATH", "github-token-path")
+        monkeypatch.setenv("GITHUB_ENTERPRISE_TOKEN", "enterprise-github")
+        monkeypatch.setenv("GITHUB_API_TOKEN", "api-token")
+        monkeypatch.setenv("GITHUB_APP_PRIVATE_KEY", "app-private-key")
+        monkeypatch.setenv("GITHUB_OAUTH_CLIENT_SECRET", "oauth-secret")
+        monkeypatch.setenv("HOMEBREW_GITHUB_API_TOKEN", "homebrew-token")
+        monkeypatch.setenv("NOTGITHUB_TOKEN", "not-github-kept")
+        monkeypatch.setenv("GHOST_API_TOKEN", "ghost-kept")
+        monkeypatch.setenv("GHIDRA_API_KEY", "ghidra-kept")
+        monkeypatch.setenv("UNRELATED_TOKEN", "kept")
+
+        env = specify_cli._version._scrubbed_env()
+
+        assert "GH_PAT" not in env
+        assert "GH_TOKEN_FILE" not in env
+        assert "GH_ENTERPRISE_TOKEN" not in env
+        assert "GH_ENTERPRISE_SECRET" not in env
+        assert "GH_ENTERPRISE_PRIVATE_KEY" not in env
+        assert "GITHUB_PAT" not in env
+        assert "GITHUB_TOKEN_PATH" not in env
+        assert "GITHUB_ENTERPRISE_TOKEN" not in env
+        assert "GITHUB_API_TOKEN" not in env
+        assert "GITHUB_APP_PRIVATE_KEY" not in env
+        assert "GITHUB_OAUTH_CLIENT_SECRET" not in env
+        assert "HOMEBREW_GITHUB_API_TOKEN" not in env
+        assert env["NOTGITHUB_TOKEN"] == "not-github-kept"
+        assert env["GHOST_API_TOKEN"] == "ghost-kept"
+        assert env["GHIDRA_API_KEY"] == "ghidra-kept"
+        assert env["UNRELATED_TOKEN"] == "kept"
+
+    def test_env_scrubbing_strips_noncredential_github_vars_by_design(
+        self, monkeypatch
+    ):
+        # The scrub is intentionally broad: every GH_/GITHUB_-prefixed name is
+        # removed from the installer subprocess env, including non-credential
+        # context vars. This is a deliberate fail-safe so credential-adjacent
+        # names that lack a recognized suffix (e.g. GH_TOKEN_FILE,
+        # GITHUB_TOKEN_PATH, asserted above) can never leak. The installer
+        # (`uv tool install` / `pipx install` of a public package) does not
+        # consume routing/context vars like GITHUB_REPOSITORY, so nothing the
+        # subprocess needs is lost by stripping them.
+        monkeypatch.setenv("GH_HOST", "github.example.com")
+        monkeypatch.setenv("GH_CONFIG_DIR", "/home/u/.config/gh")
+        monkeypatch.setenv("GITHUB_REPOSITORY", "github/spec-kit")
+        monkeypatch.setenv("GITHUB_WORKSPACE", "/home/runner/work")
+        monkeypatch.setenv("GITHUB_USER", "octocat")
+
+        env = specify_cli._version._scrubbed_env()
+
+        assert "GH_HOST" not in env
+        assert "GH_CONFIG_DIR" not in env
+        assert "GITHUB_REPOSITORY" not in env
+        assert "GITHUB_WORKSPACE" not in env
+        assert "GITHUB_USER" not in env

tests/test_setup_tasks.py

@@ -13,8 +13,10 @@ from tests.conftest import requires_bash
 PROJECT_ROOT = Path(__file__).resolve().parent.parent
 COMMON_SH = PROJECT_ROOT / "scripts" / "bash" / "common.sh"
 SETUP_TASKS_SH = PROJECT_ROOT / "scripts" / "bash" / "setup-tasks.sh"
+CHECK_PREREQ_SH = PROJECT_ROOT / "scripts" / "bash" / "check-prerequisites.sh"
 COMMON_PS = PROJECT_ROOT / "scripts" / "powershell" / "common.ps1"
 SETUP_TASKS_PS = PROJECT_ROOT / "scripts" / "powershell" / "setup-tasks.ps1"
+CHECK_PREREQ_PS = PROJECT_ROOT / "scripts" / "powershell" / "check-prerequisites.ps1"
 TASKS_TEMPLATE = PROJECT_ROOT / "templates" / "tasks-template.md"
  
 HAS_PWSH = shutil.which("pwsh") is not None
@@ -30,6 +32,7 @@ def _install_bash_scripts(repo: Path) -> None:
     d.mkdir(parents=True, exist_ok=True)
     shutil.copy(COMMON_SH, d / "common.sh")
     shutil.copy(SETUP_TASKS_SH, d / "setup-tasks.sh")
+    shutil.copy(CHECK_PREREQ_SH, d / "check-prerequisites.sh")
  
  
 def _install_ps_scripts(repo: Path) -> None:
@@ -37,6 +40,7 @@ def _install_ps_scripts(repo: Path) -> None:
     d.mkdir(parents=True, exist_ok=True)
     shutil.copy(COMMON_PS, d / "common.ps1")
     shutil.copy(SETUP_TASKS_PS, d / "setup-tasks.ps1")
+    shutil.copy(CHECK_PREREQ_PS, d / "check-prerequisites.ps1")
  
  
 def _install_core_tasks_template(repo: Path) -> None:
@@ -57,6 +61,25 @@ def _minimal_feature(repo: Path) -> Path:
     (feat / "spec.md").write_text("# spec\n", encoding="utf-8")
     (feat / "plan.md").write_text("# plan\n", encoding="utf-8")
     return feat
+
+
+def _write_integration_state(repo: Path, integration: str = "claude", separator: str = "-") -> None:
+    specify_dir = repo / ".specify"
+    specify_dir.mkdir(parents=True, exist_ok=True)
+    state = {
+        "integration": integration,
+        "default_integration": integration,
+        "installed_integrations": [integration],
+        "integration_settings": {
+            integration: {
+                "invoke_separator": separator,
+            },
+        },
+    }
+    (specify_dir / "integration.json").write_text(
+        json.dumps(state),
+        encoding="utf-8",
+    )
  
  
 def _clean_env() -> dict[str, str]:
@@ -71,6 +94,38 @@ def _clean_env() -> dict[str, str]:
     return env
  
  
+def _run_bash_format_command(repo: Path, command_name: str) -> subprocess.CompletedProcess:
+    script = repo / ".specify" / "scripts" / "bash" / "common.sh"
+    return subprocess.run(
+        ["bash", "-c", 'source "$1"; format_speckit_command "$2" "$PWD"', "bash", str(script), command_name],
+        cwd=repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+
+def _run_powershell_format_command(repo: Path, command_name: str) -> subprocess.CompletedProcess:
+    script = repo / ".specify" / "scripts" / "powershell" / "common.ps1"
+    exe = "pwsh" if HAS_PWSH else _POWERSHELL
+    return subprocess.run(
+        [
+            exe,
+            "-NoProfile",
+            "-Command",
+            '& { param($common, $commandName) . $common; Format-SpecKitCommand -CommandName $commandName -RepoRoot (Get-Location).Path }',
+            str(script),
+            command_name,
+        ],
+        cwd=repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+
 def _git_init(repo: Path) -> None:
     subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
     subprocess.run(
@@ -123,7 +178,7 @@ def test_setup_tasks_bash_core_template_resolved(tasks_repo: Path) -> None:
     setup-tasks.sh --json should exit 0 and return an absolute, existing
     TASKS_TEMPLATE path pointing to the core template.
     """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
     script = tasks_repo / ".specify" / "scripts" / "bash" / "setup-tasks.sh"
  
     result = subprocess.run(
@@ -150,7 +205,7 @@ def test_setup_tasks_bash_override_wins(tasks_repo: Path) -> None:
     When an override exists at .specify/templates/overrides/tasks-template.md,
     setup-tasks.sh --json must return the override path, not the core path.
     """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
  
     # Create the override
     overrides_dir = tasks_repo / ".specify" / "templates" / "overrides"
@@ -187,7 +242,7 @@ def test_setup_tasks_bash_extension_wins_over_core(tasks_repo: Path) -> None:
     When an extension template exists, setup-tasks.sh --json must resolve
     tasks-template.md from the extension before falling back to the core path.
     """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
  
     # FIX: real extension layout is .specify/extensions/<id>/templates/<name>.md
     extension_dir = (
@@ -225,7 +280,7 @@ def test_setup_tasks_bash_preset_wins_over_extension(tasks_repo: Path) -> None:
     When both preset and extension templates exist, setup-tasks.sh --json must
     resolve the preset path because presets outrank extensions.
     """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
  
     # FIX: real extension layout is .specify/extensions/<id>/templates/<name>.md
     extension_dir = (
@@ -269,7 +324,7 @@ def test_setup_tasks_bash_preset_priority_order(tasks_repo: Path) -> None:
     When two presets both provide tasks-template.md, the one listed first in
     .specify/presets/.registry wins.
     """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
  
     # resolve_template reads .specify/presets/.registry as a JSON object with a
     # "presets" map where each entry has a numeric "priority" (lower = higher
@@ -329,7 +384,7 @@ def test_setup_tasks_bash_missing_template_errors(tasks_repo: Path) -> None:
     When tasks-template.md is absent from all locations, setup-tasks.sh must
     exit non-zero and print a helpful ERROR message to stderr.
     """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
  
     # Remove the core template so no template exists anywhere
     core = tasks_repo / ".specify" / "templates" / "tasks-template.md"
@@ -345,12 +400,138 @@ def test_setup_tasks_bash_missing_template_errors(tasks_repo: Path) -> None:
         check=False,
         env=_clean_env(),
     )
- 
+
     assert result.returncode != 0
     assert "ERROR" in result.stderr
     assert "tasks-template" in result.stderr
  
  
+@requires_bash
+def test_bash_command_hint_defaults_to_dot_without_integration_json(tasks_repo: Path) -> None:
+    integration_json = tasks_repo / ".specify" / "integration.json"
+    if integration_json.exists():
+        integration_json.unlink()
+
+    result = _run_bash_format_command(tasks_repo, "plan")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit.plan"
+
+
+@requires_bash
+def test_bash_command_hint_rejects_invalid_invoke_separator(tasks_repo: Path) -> None:
+    _write_integration_state(tasks_repo, "claude", "/")
+
+    result = _run_bash_format_command(tasks_repo, "plan")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit.plan"
+
+
+@requires_bash
+def test_bash_command_hint_normalizes_mixed_separators(tasks_repo: Path) -> None:
+    _write_integration_state(tasks_repo, "copilot", ".")
+
+    result = _run_bash_format_command(tasks_repo, "/speckit-git.commit")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit.git.commit"
+
+    _write_integration_state(tasks_repo, "claude", "-")
+
+    result = _run_bash_format_command(tasks_repo, "speckit.git-commit")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit-git-commit"
+
+
+@requires_bash
+def test_bash_command_hint_preserves_hyphens_inside_segments(tasks_repo: Path) -> None:
+    _write_integration_state(tasks_repo, "copilot", ".")
+
+    result = _run_bash_format_command(tasks_repo, "speckit.jira.sync-status")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit.jira.sync-status"
+
+
+@requires_bash
+def test_bash_command_hint_caches_invoke_separator_per_process(tasks_repo: Path) -> None:
+    _write_integration_state(tasks_repo, "claude", "-")
+    script = tasks_repo / ".specify" / "scripts" / "bash" / "common.sh"
+    dot_state = {
+        "integration": "copilot",
+        "default_integration": "copilot",
+        "installed_integrations": ["copilot"],
+        "integration_settings": {"copilot": {"invoke_separator": "."}},
+    }
+
+    result = subprocess.run(
+        [
+            "bash",
+            "-c",
+            'source "$1"; format_speckit_command plan "$PWD"; printf "%s" "$2" > .specify/integration.json; format_speckit_command tasks "$PWD"',
+            "bash",
+            str(script),
+            json.dumps(dot_state),
+        ],
+        cwd=tasks_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.splitlines() == ["/speckit-plan", "/speckit-tasks"]
+
+
+@requires_bash
+def test_setup_tasks_bash_uses_invoke_separator_in_plan_hint(tasks_repo: Path) -> None:
+    _write_integration_state(tasks_repo, "claude", "-")
+    feat = tasks_repo / "specs" / "001-my-feature"
+    feat.mkdir(parents=True, exist_ok=True)
+    (feat / "spec.md").write_text("# spec\n", encoding="utf-8")
+
+    script = tasks_repo / ".specify" / "scripts" / "bash" / "setup-tasks.sh"
+
+    result = subprocess.run(
+        ["bash", str(script), "--json"],
+        cwd=tasks_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+    assert result.returncode != 0
+    assert "Run /speckit-plan first" in result.stderr
+    assert "/speckit.plan" not in result.stderr
+
+
+@requires_bash
+def test_check_prerequisites_bash_uses_invoke_separator_in_tasks_hint(
+    tasks_repo: Path,
+) -> None:
+    _write_integration_state(tasks_repo, "claude", "-")
+    _minimal_feature(tasks_repo)
+
+    script = tasks_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
+
+    result = subprocess.run(
+        ["bash", str(script), "--require-tasks"],
+        cwd=tasks_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+    assert result.returncode != 0
+    assert "Run /speckit-tasks first" in result.stderr
+    assert "/speckit.tasks" not in result.stderr
+
+
 @requires_bash
 def test_setup_tasks_bash_passes_custom_branch_when_feature_json_valid(
     tasks_repo: Path,
@@ -413,11 +594,10 @@ def test_setup_tasks_bash_fails_custom_branch_without_feature_json(
         check=False,
         env=_clean_env(),
     )
- 
+
     assert result.returncode != 0
     assert "Not on a feature branch" in result.stderr
  
- 
 # ===========================================================================
 # POWERSHELL TESTS
 # ===========================================================================
@@ -429,7 +609,7 @@ def test_setup_tasks_ps_core_template_resolved(tasks_repo: Path) -> None:
     setup-tasks.ps1 -Json should exit 0 and return an absolute, existing
     TASKS_TEMPLATE path.
     """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
     script = tasks_repo / ".specify" / "scripts" / "powershell" / "setup-tasks.ps1"
     exe = "pwsh" if HAS_PWSH else _POWERSHELL
  
@@ -457,7 +637,7 @@ def test_setup_tasks_ps_override_wins(tasks_repo: Path) -> None:
     When an override exists at .specify/templates/overrides/tasks-template.md,
     setup-tasks.ps1 -Json must return the override path, not the core path.
     """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
  
     overrides_dir = tasks_repo / ".specify" / "templates" / "overrides"
     overrides_dir.mkdir(parents=True, exist_ok=True)
@@ -493,7 +673,7 @@ def test_setup_tasks_ps_missing_template_errors(tasks_repo: Path) -> None:
     When tasks-template.md is absent from all locations, setup-tasks.ps1 must
     exit non-zero and write a helpful error to stderr.
     """
-    feat = _minimal_feature(tasks_repo)
+    _minimal_feature(tasks_repo)
  
     core = tasks_repo / ".specify" / "templates" / "tasks-template.md"
     core.unlink()
@@ -514,6 +694,87 @@ def test_setup_tasks_ps_missing_template_errors(tasks_repo: Path) -> None:
     assert "tasks-template" in result.stderr.lower() or "tasks-template" in result.stdout.lower()
  
  
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_powershell_command_hint_normalizes_mixed_separators(
+    tasks_repo: Path,
+) -> None:
+    _write_integration_state(tasks_repo, "copilot", ".")
+
+    result = _run_powershell_format_command(tasks_repo, "/speckit-git.commit")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit.git.commit"
+
+    _write_integration_state(tasks_repo, "claude", "-")
+
+    result = _run_powershell_format_command(tasks_repo, "speckit.git-commit")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit-git-commit"
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_powershell_command_hint_preserves_hyphens_inside_segments(
+    tasks_repo: Path,
+) -> None:
+    _write_integration_state(tasks_repo, "copilot", ".")
+
+    result = _run_powershell_format_command(tasks_repo, "speckit.jira.sync-status")
+
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "/speckit.jira.sync-status"
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_setup_tasks_ps_uses_invoke_separator_in_plan_hint(tasks_repo: Path) -> None:
+    _write_integration_state(tasks_repo, "claude", "-")
+    feat = tasks_repo / "specs" / "001-my-feature"
+    feat.mkdir(parents=True, exist_ok=True)
+    (feat / "spec.md").write_text("# spec\n", encoding="utf-8")
+
+    script = tasks_repo / ".specify" / "scripts" / "powershell" / "setup-tasks.ps1"
+    exe = "pwsh" if HAS_PWSH else _POWERSHELL
+
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(script), "-Json"],
+        cwd=tasks_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+    output = result.stderr + result.stdout
+    assert result.returncode != 0
+    assert "Run /speckit-plan first" in output
+    assert "/speckit.plan" not in output
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_check_prerequisites_ps_uses_invoke_separator_in_tasks_hint(
+    tasks_repo: Path,
+) -> None:
+    _write_integration_state(tasks_repo, "claude", "-")
+    _minimal_feature(tasks_repo)
+
+    script = tasks_repo / ".specify" / "scripts" / "powershell" / "check-prerequisites.ps1"
+    exe = "pwsh" if HAS_PWSH else _POWERSHELL
+
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(script), "-RequireTasks"],
+        cwd=tasks_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+
+    output = result.stderr + result.stdout
+    assert result.returncode != 0
+    assert "Run /speckit-tasks first" in output
+    assert "/speckit.tasks" not in output
+
+
 @pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
 def test_setup_tasks_ps_passes_custom_branch_when_feature_json_valid(
     tasks_repo: Path,
@@ -581,4 +842,3 @@ def test_setup_tasks_ps_fails_custom_branch_without_feature_json(
  
     assert result.returncode != 0
     assert "Not on a feature branch" in result.stderr
- 

tests/test_timestamp_branches.py

@@ -923,7 +923,7 @@ class TestDryRun:
         assert re.match(r"^\d{8}-\d{6}-ts-feat$", branch), f"unexpected: {branch}"
         # Verify no side effects
         branches = subprocess.run(
-            ["git", "branch", "--list", f"*ts-feat*"],
+            ["git", "branch", "--list", "*ts-feat*"],
             cwd=git_repo,
             capture_output=True,
             text=True,

tests/test_upgrade.py

@@ -1,14 +1,14 @@
 """Tests for the `specify self` sub-app (`self check` and `self upgrade`).
 
 Network isolation contract (SC-004 / FR-014): every test that exercises
-`specify self check` or `_fetch_latest_release_tag()` MUST mock
-`urllib.request.urlopen` so no real outbound call ever reaches
-api.github.com. The `self upgrade` stub tests do not need that patch because
-the stub is contractually network-free. Run this module under `pytest-socket`
-(if installed) with `--disable-socket` as an extra safety net.
+`specify self check` or `_fetch_latest_release_tag()` MUST mock the outbound
+urllib path it expects (`urlopen` for unauthenticated requests, `build_opener`
+for authenticated requests) so no real outbound call ever reaches api.github.com.
+Tests for non-network `self upgrade` behavior should keep that contract explicit
+with local mocks. Run this module under `pytest-socket` (if installed) with
+`--disable-socket` as an extra safety net.
 """
 
-import json
 import urllib.error
 import importlib.metadata
 from unittest.mock import MagicMock, patch
@@ -24,6 +24,7 @@ from specify_cli._version import (
     _normalize_tag,
 )
 from tests.conftest import strip_ansi
+from tests.http_helpers import mock_urlopen_response
 
 runner = CliRunner()
 
@@ -35,16 +36,6 @@ _RATE_LIMITED_REASON = (
 )
 
 
-def _mock_urlopen_response(payload: dict) -> MagicMock:
-    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
-
-
 def _http_error(code: int, message: str = "error") -> urllib.error.HTTPError:
     return urllib.error.HTTPError(
         url="https://api.github.com/repos/github/spec-kit/releases/latest",
@@ -55,39 +46,6 @@ def _http_error(code: int, message: str = "error") -> urllib.error.HTTPError:
     )
 
 
-class TestSelfUpgradeStub:
-    """Pins the `specify self upgrade` stub output + exit code (contract §3.5, FR-016)."""
-
-    def test_prints_exactly_three_lines_and_exits_zero(self):
-        result = runner.invoke(app, ["self", "upgrade"])
-        assert result.exit_code == 0
-        lines = strip_ansi(result.output).strip().splitlines()
-        assert lines == [
-            "specify self upgrade is not implemented yet.",
-            "Run 'specify self check' to see whether a newer release is available.",
-            "Actual self-upgrade is planned as follow-up work.",
-        ]
-
-    def test_stub_makes_no_network_call(self):
-        # The stub must not hit the network via either urllib path:
-        # unauthenticated requests use urlopen() directly; authenticated ones
-        # go through build_opener(...).open().  Both are patched so that any
-        # accidental network call raises immediately.
-        network_error = AssertionError("stub must not hit the network")
-        with (
-            patch(
-                "specify_cli.authentication.http.urllib.request.urlopen",
-                side_effect=network_error,
-            ),
-            patch(
-                "specify_cli.authentication.http.urllib.request.build_opener",
-                side_effect=network_error,
-            ),
-        ):
-            result = runner.invoke(app, ["self", "upgrade"])
-        assert result.exit_code == 0
-
-
 class TestIsNewer:
     def test_latest_strictly_greater_returns_true(self):
         assert _is_newer("0.8.0", "0.7.4") is True
@@ -151,7 +109,7 @@ class TestUserStory1:
     def test_newer_available_prints_update_and_install_command(self):
         with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
             "specify_cli.authentication.http.urllib.request.urlopen",
-            return_value=_mock_urlopen_response({"tag_name": "v0.9.0"}),
+            return_value=mock_urlopen_response({"tag_name": "v0.9.0"}),
         ):
             result = runner.invoke(app, ["self", "check"])
         output = strip_ansi(result.output)
@@ -164,7 +122,7 @@ class TestUserStory1:
     def test_up_to_date_prints_current_only(self):
         with patch("specify_cli._version._get_installed_version", return_value="0.9.0"), patch(
             "specify_cli.authentication.http.urllib.request.urlopen",
-            return_value=_mock_urlopen_response({"tag_name": "v0.9.0"}),
+            return_value=mock_urlopen_response({"tag_name": "v0.9.0"}),
         ):
             result = runner.invoke(app, ["self", "check"])
         output = strip_ansi(result.output)
@@ -176,7 +134,7 @@ class TestUserStory1:
     def test_dev_build_ahead_of_release_is_up_to_date(self):
         with patch("specify_cli._version._get_installed_version", return_value="0.7.5.dev0"), patch(
             "specify_cli.authentication.http.urllib.request.urlopen",
-            return_value=_mock_urlopen_response({"tag_name": "v0.7.4"}),
+            return_value=mock_urlopen_response({"tag_name": "v0.7.4"}),
         ):
             result = runner.invoke(app, ["self", "check"])
         output = strip_ansi(result.output)
@@ -187,26 +145,46 @@ class TestUserStory1:
     def test_unknown_installed_still_prints_latest_and_reinstall(self):
         with patch("specify_cli._version._get_installed_version", return_value="unknown"), patch(
             "specify_cli.authentication.http.urllib.request.urlopen",
-            return_value=_mock_urlopen_response({"tag_name": "v0.7.4"}),
+            return_value=mock_urlopen_response({"tag_name": "v0.7.4"}),
         ):
             result = runner.invoke(app, ["self", "check"])
         output = strip_ansi(result.output)
         assert result.exit_code == 0
         assert "Current version could not be determined" in output
+        assert "Latest release: v0.7.4" in output
         assert "0.7.4" in output
         assert "git+https://github.com/github/spec-kit.git@v0.7.4" in output
+        assert "specify self upgrade" in output
+        assert "pipx install --force git+https://github.com/github/spec-kit.git@v0.7.4" in output
 
-    def test_unparseable_tag_routes_to_indeterminate(self):
+    def test_unknown_installed_uses_placeholder_when_latest_tag_is_invalid(self):
+        with patch("specify_cli._version._get_installed_version", return_value="unknown"), patch(
+            "specify_cli.authentication.http.urllib.request.urlopen",
+            return_value=mock_urlopen_response({"tag_name": "v0.9.0;echo unsafe"}),
+        ):
+            result = runner.invoke(app, ["self", "check"])
+        output = strip_ansi(result.output)
+        assert result.exit_code == 0
+        assert "Latest release: vX.Y.Z" in output
+        assert "Could not validate latest release tag from GitHub." in output
+        assert "git+https://github.com/github/spec-kit.git@vX.Y.Z" in output
+        assert "v0.9.0;echo unsafe" not in output
+
+    def test_unparseable_tag_reports_validation_failure_without_raw_tag(self):
         with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
             "specify_cli.authentication.http.urllib.request.urlopen",
-            return_value=_mock_urlopen_response({"tag_name": "not-a-version"}),
+            return_value=mock_urlopen_response({"tag_name": "not-a-version"}),
         ):
             result = runner.invoke(app, ["self", "check"])
         output = strip_ansi(result.output)
         assert result.exit_code == 0
         assert "Update available" not in output
-        assert "Up to date" in output
+        assert "Up to date" not in output
+        assert "Could not validate latest release tag from GitHub." in output
+        assert "Latest release: vX.Y.Z" in output
         assert "0.7.4" in output
+        assert "not-a-version" not in output
+        assert "git+https://github.com/github/spec-kit.git@vX.Y.Z" in output
 
 
 class TestFailureCategorization:
@@ -306,13 +284,25 @@ class TestUserStory2:
 def _capture_request_via_urlopen():
     captured = {}
 
-    def _side_effect(req, timeout=None):
+    def _side_effect(req, *args, **kwargs):
         captured["request"] = req
-        return _mock_urlopen_response({"tag_name": "v0.7.4"})
+        return mock_urlopen_response({"tag_name": "v0.7.4"})
 
     return captured, _side_effect
 
 
+def _capture_request_via_auth_opener():
+    captured = {}
+
+    def _side_effect(req, *args, **kwargs):
+        captured["request"] = req
+        return mock_urlopen_response({"tag_name": "v0.7.4"})
+
+    opener = MagicMock()
+    opener.open.side_effect = _side_effect
+    return captured, opener
+
+
 def _inject_github_config(monkeypatch, token_env="GH_TOKEN"):
     from tests.auth_helpers import inject_github_config
     inject_github_config(monkeypatch, token_env)
@@ -323,10 +313,11 @@ class TestUserStory3:
         monkeypatch.setenv("GH_TOKEN", SENTINEL_GH_TOKEN)
         monkeypatch.delenv("GITHUB_TOKEN", raising=False)
         _inject_github_config(monkeypatch, token_env="GH_TOKEN")
-        captured, side_effect = _capture_request_via_urlopen()
-        mock_opener = MagicMock()
-        mock_opener.open.side_effect = side_effect
-        with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
+        captured, opener = _capture_request_via_auth_opener()
+        with patch(
+            "specify_cli.authentication.http.urllib.request.build_opener",
+            return_value=opener,
+        ):
             _fetch_latest_release_tag()
         req = captured["request"]
         assert req.get_header("Authorization") == f"Bearer {SENTINEL_GH_TOKEN}"
@@ -335,10 +326,11 @@ class TestUserStory3:
         monkeypatch.delenv("GH_TOKEN", raising=False)
         monkeypatch.setenv("GITHUB_TOKEN", SENTINEL_GITHUB_TOKEN)
         _inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")
-        captured, side_effect = _capture_request_via_urlopen()
-        mock_opener = MagicMock()
-        mock_opener.open.side_effect = side_effect
-        with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
+        captured, opener = _capture_request_via_auth_opener()
+        with patch(
+            "specify_cli.authentication.http.urllib.request.build_opener",
+            return_value=opener,
+        ):
             _fetch_latest_release_tag()
         req = captured["request"]
         assert req.get_header("Authorization") == f"Bearer {SENTINEL_GITHUB_TOKEN}"
@@ -376,10 +368,11 @@ class TestUserStory3:
         monkeypatch.setenv("GH_TOKEN", "   ")
         monkeypatch.setenv("GITHUB_TOKEN", SENTINEL_GITHUB_TOKEN)
         _inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")
-        captured, side_effect = _capture_request_via_urlopen()
-        mock_opener = MagicMock()
-        mock_opener.open.side_effect = side_effect
-        with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):
+        captured, opener = _capture_request_via_auth_opener()
+        with patch(
+            "specify_cli.authentication.http.urllib.request.build_opener",
+            return_value=opener,
+        ):
             _fetch_latest_release_tag()
         req = captured["request"]
         assert req.get_header("Authorization") == f"Bearer {SENTINEL_GITHUB_TOKEN}"

tests/test_utils_assets_imports.py

@@ -1,7 +1,6 @@
 """Regression guard: utility and asset symbols importable from specify_cli."""
 from specify_cli import (
-    run_command, check_tool, is_git_repo, init_git_repo,
-    handle_vscode_settings, merge_json_files,
+    check_tool, is_git_repo, merge_json_files,
     get_speckit_version,
     CLAUDE_LOCAL_PATH, CLAUDE_NPM_LOCAL_PATH,
 )

tests/test_version_imports.py

@@ -23,7 +23,6 @@ def test_version_symbols_available_from_star_import():
 
 def test_version_module_symbols_directly_importable():
     from specify_cli._version import (
-        GITHUB_API_LATEST,
         _fetch_latest_release_tag,
         _get_installed_version,
         _is_newer,

tests/test_workflows.py

@@ -520,6 +520,7 @@ class TestCommandStep:
         assert result.output["integration"] == "gemini"
 
     def test_step_override_model(self):
+        from unittest.mock import patch
         from specify_cli.workflows.steps.command import CommandStep
         from specify_cli.workflows.base import StepContext
 
@@ -531,10 +532,12 @@ class TestCommandStep:
             "model": "opus-4",
             "input": {},
         }
-        result = step.execute(config, ctx)
+        with patch("specify_cli.workflows.steps.command.shutil.which", return_value=None):
+            result = step.execute(config, ctx)
         assert result.output["model"] == "opus-4"
 
     def test_options_merge(self):
+        from unittest.mock import patch
         from specify_cli.workflows.steps.command import CommandStep
         from specify_cli.workflows.base import StepContext
 
@@ -546,7 +549,8 @@ class TestCommandStep:
             "options": {"thinking-budget": 32768},
             "input": {},
         }
-        result = step.execute(config, ctx)
+        with patch("specify_cli.workflows.steps.command.shutil.which", return_value=None):
+            result = step.execute(config, ctx)
         assert result.output["options"]["max-tokens"] == 8000
         assert result.output["options"]["thinking-budget"] == 32768
 
@@ -2375,6 +2379,306 @@ steps:
         assert state.step_results["stamp"]["output"]["stdout"].strip() == "explicit-456"
 
 
+# ===== continue_on_error Tests =====
+#
+# Locks the contract documented in workflows/README.md "Error Handling"
+# section: when a step returns `StepResult(status=StepStatus.FAILED, ...)` and
+# `continue_on_error: true` is declared, the engine records the step's
+# `output` (with `exit_code` and `stderr` from the failure) and its
+# `status` (sibling key on `steps.<id>`, not nested under `output`)
+# and continues to the next sibling step instead of halting the run.
+# Gate aborts (`output.aborted`) still halt regardless of the flag.
+# Unhandled exceptions raised out of `step_impl.execute()` are out of
+# scope for this flag — they propagate to `WorkflowEngine.execute()`
+# and abort the run.
+
+
+class TestContinueOnError:
+    """Test the `continue_on_error` step-level field."""
+
+    def test_undeclared_failure_halts_run(self, project_dir):
+        """Default behaviour (no `continue_on_error`): a failing step
+        halts the workflow run with `status == StepStatus.FAILED`.
+
+        Locks the byte-equivalent default — workflows that do not
+        declare the flag must behave exactly as before this feature.
+        """
+        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+        from specify_cli.workflows.base import RunStatus
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "halt-on-fail"
+  name: "Halt On Fail"
+  version: "1.0.0"
+steps:
+  - id: fail-step
+    type: shell
+    run: "exit 7"
+  - id: after
+    type: shell
+    run: "echo should-not-run"
+""")
+        engine = WorkflowEngine(project_dir)
+        state = engine.execute(definition)
+
+        assert state.status == RunStatus.FAILED
+        assert "fail-step" in state.step_results
+        assert state.step_results["fail-step"]["output"]["exit_code"] == 7
+        # Subsequent step never executes when the flag is absent.
+        assert "after" not in state.step_results
+
+    def test_declared_and_fired_continues_run(self, project_dir):
+        """`continue_on_error: true` + failing step: the run keeps
+        going, the failed step's result is recorded, and the
+        downstream step runs.
+        """
+        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+        from specify_cli.workflows.base import RunStatus
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "continue-past-fail"
+  name: "Continue Past Fail"
+  version: "1.0.0"
+steps:
+  - id: flaky-step
+    type: shell
+    run: "exit 42"
+    continue_on_error: true
+  - id: after
+    type: shell
+    run: "echo did-run"
+""")
+        engine = WorkflowEngine(project_dir)
+        state = engine.execute(definition)
+
+        assert state.status == RunStatus.COMPLETED
+        # Failed step's exit_code is preserved so downstream branching
+        # can inspect it.
+        assert state.step_results["flaky-step"]["output"]["exit_code"] == 42
+        assert state.step_results["flaky-step"]["status"] == "failed"
+        # Downstream step ran successfully.
+        assert state.step_results["after"]["output"]["exit_code"] == 0
+
+    def test_declared_but_step_succeeded_is_noop(self, project_dir):
+        """`continue_on_error: true` on a step that succeeds is a
+        no-op — the flag only changes behaviour on StepStatus.FAILED status.
+        """
+        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+        from specify_cli.workflows.base import RunStatus
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "flag-but-success"
+  name: "Flag But Success"
+  version: "1.0.0"
+steps:
+  - id: ok-step
+    type: shell
+    run: "echo ok"
+    continue_on_error: true
+  - id: after
+    type: shell
+    run: "echo done"
+""")
+        engine = WorkflowEngine(project_dir)
+        state = engine.execute(definition)
+
+        assert state.status == RunStatus.COMPLETED
+        assert state.step_results["ok-step"]["status"] == "completed"
+        assert state.step_results["ok-step"]["output"]["exit_code"] == 0
+        assert state.step_results["after"]["output"]["exit_code"] == 0
+
+    def test_if_branch_routes_around_failure(self, project_dir):
+        """End-to-end: `continue_on_error` + `if` cleanly routes around
+        a failure. The recovery branch runs; the success branch does
+        not.
+
+        Mirrors the canonical usage pattern from the original feature
+        discussion in issue #2591.
+        """
+        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+        from specify_cli.workflows.base import RunStatus
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "route-around"
+  name: "Route Around Failure"
+  version: "1.0.0"
+steps:
+  - id: heavy-thing
+    type: shell
+    run: "exit 1"
+    continue_on_error: true
+  - id: check-result
+    type: if
+    condition: "{{ steps.heavy-thing.output.exit_code != 0 }}"
+    then:
+      - id: recovery
+        type: shell
+        run: "echo recovery-ran"
+    else:
+      - id: happy-path
+        type: shell
+        run: "echo happy-path-ran"
+""")
+        engine = WorkflowEngine(project_dir)
+        state = engine.execute(definition)
+
+        assert state.status == RunStatus.COMPLETED
+        assert "recovery" in state.step_results
+        assert "happy-path" not in state.step_results
+
+    def test_gate_abort_still_halts_with_continue_on_error(
+        self, project_dir, monkeypatch
+    ):
+        """`continue_on_error` does NOT override a deliberate gate
+        abort. `output.aborted` always halts the run with
+        `status == ABORTED`.
+
+        Aborts are explicit operator decisions; continue_on_error
+        is for transient/expected step failures only.
+        """
+        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+        from specify_cli.workflows.base import RunStatus
+        from specify_cli.workflows.steps.gate import GateStep
+        from specify_cli.workflows.steps import gate as gate_module
+
+        # Force the gate step into interactive mode and feed a "reject"
+        # choice so the abort path actually runs in the test env
+        # (default behaviour returns StepStatus.PAUSED when stdin is not a TTY).
+        # Swap sys.stdin itself for a stub: setattr on the real
+        # TextIOWrapper's `isatty` method is not assignable under some
+        # runners (e.g. pytest with capture disabled).
+        class _TTYStdin:
+            def isatty(self) -> bool:
+                return True
+
+        monkeypatch.setattr(gate_module.sys, "stdin", _TTYStdin())
+        monkeypatch.setattr(
+            GateStep, "_prompt", staticmethod(lambda _msg, _opts: "reject")
+        )
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "gate-abort-halts"
+  name: "Gate Abort Halts"
+  version: "1.0.0"
+steps:
+  - id: gate-step
+    type: gate
+    message: "Approve?"
+    options: [approve, reject]
+    on_reject: abort
+    continue_on_error: true
+  - id: should-not-run
+    type: shell
+    run: "echo nope"
+""")
+        engine = WorkflowEngine(project_dir)
+        state = engine.execute(definition)
+
+        assert state.status == RunStatus.ABORTED
+        assert "should-not-run" not in state.step_results
+
+    def test_validation_rejects_non_bool_continue_on_error(self):
+        """`continue_on_error` must be a literal boolean; coerced
+        strings like `"true"` are rejected at validation time so
+        authoring mistakes surface before execution.
+        """
+        from specify_cli.workflows.engine import (
+            WorkflowDefinition,
+            validate_workflow,
+        )
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "bad-coe"
+  name: "Bad COE"
+  version: "1.0.0"
+steps:
+  - id: step-one
+    type: shell
+    run: "true"
+    continue_on_error: "true"
+""")
+        errors = validate_workflow(definition)
+        assert any(
+            "continue_on_error" in e and "boolean" in e for e in errors
+        ), errors
+
+    def test_validation_accepts_bool_continue_on_error(self):
+        """Boolean values pass validation cleanly."""
+        from specify_cli.workflows.engine import (
+            WorkflowDefinition,
+            validate_workflow,
+        )
+
+        for value in (True, False):
+            yaml_value = "true" if value else "false"
+            definition = WorkflowDefinition.from_string(f"""
+schema_version: "1.0"
+workflow:
+  id: "good-coe"
+  name: "Good COE"
+  version: "1.0.0"
+steps:
+  - id: step-one
+    type: shell
+    run: "true"
+    continue_on_error: {yaml_value}
+""")
+            errors = validate_workflow(definition)
+            assert errors == [], errors
+
+    def test_engine_ignores_truthy_non_bool_continue_on_error(self, project_dir):
+        """Defense-in-depth: even if a caller bypasses
+        `validate_workflow()` and feeds the engine a definition with
+        `continue_on_error: "true"` (a string), the engine must NOT
+        honour the flag — only a literal boolean enables the
+        behaviour. `WorkflowEngine.execute()` does not auto-validate
+        (the `WorkflowEngine.load_workflow` docstring explicitly
+        notes the definition is "not yet validated; call
+        `validate_workflow()` or `engine.validate()` separately"),
+        so the engine guards against truthy non-bool values itself
+        via an identity check rather than truthiness.
+        """
+        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+        from specify_cli.workflows.base import RunStatus
+
+        # Bypass `validate_workflow()` — execute() is what would
+        # be called by a caller that skipped validation.
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "string-coe"
+  name: "String COE"
+  version: "1.0.0"
+steps:
+  - id: fail-step
+    type: shell
+    run: "exit 1"
+    continue_on_error: "true"
+  - id: should-not-run
+    type: shell
+    run: "echo should-not-run"
+""")
+        engine = WorkflowEngine(project_dir)
+        state = engine.execute(definition)
+
+        # String "true" is truthy but not a literal boolean, so the
+        # engine must treat the step as a halting failure.
+        assert state.status == RunStatus.FAILED
+        assert "should-not-run" not in state.step_results
+
+
 # ===== State Persistence Tests =====
 
 class TestRunState:
@@ -2412,6 +2716,112 @@ class TestRunState:
         with pytest.raises(FileNotFoundError):
             RunState.load("nonexistent", project_dir)
 
+    @pytest.mark.parametrize(
+        "malicious_run_id",
+        [
+            # Parent-directory traversal — the classic path-escape vector.
+            "../escape",
+            "..",
+            "../../etc/passwd",
+            # Embedded path separators — both POSIX and Windows.
+            "foo/bar",
+            "foo\\bar",
+            # Leading non-alphanumeric characters that the existing
+            # pattern's anchor blocks (would be mistaken for CLI flags
+            # or hidden files in shell completions / error messages).
+            ".hidden",
+            "-flag",
+            # NUL byte — some filesystems treat the prefix as a valid
+            # path and silently truncate at the NUL.
+            "foo\x00bar",
+            # Empty string — degenerate case, matches no file but the
+            # validator should reject it before any I/O.
+            "",
+        ],
+    )
+    def test_load_rejects_path_traversal(self, project_dir, malicious_run_id):
+        """``RunState.load`` validates ``run_id`` before touching the
+        filesystem.
+
+        Without this guard, a value like ``../escape`` passed via
+        ``specify workflow resume`` would interpolate path-traversal
+        segments into the lookup path. ``state_path.exists()`` would
+        probe arbitrary paths the process can read (a file-existence
+        oracle) and ``json.load`` would happily parse attacker-planted
+        JSON from outside ``.specify/workflows/runs/``. The check must
+        fire *before* the path is built — ``__init__``'s identical
+        regex on ``state_data["run_id"]`` fires too late.
+        """
+        from specify_cli.workflows.engine import RunState
+
+        # Plant a state.json *outside* the legitimate ``runs/`` directory
+        # at the location ``../escape`` would traverse to, so a missing
+        # guard would surface as a successful load rather than a
+        # ``FileNotFoundError`` (which would be ambiguous with the
+        # not-found case).
+        runs_dir = project_dir / ".specify" / "workflows" / "runs"
+        runs_dir.mkdir(parents=True, exist_ok=True)
+        attacker_dir = project_dir / ".specify" / "workflows" / "escape"
+        attacker_dir.mkdir(exist_ok=True)
+        (attacker_dir / "state.json").write_text(
+            json.dumps(
+                {
+                    "run_id": "pwned",
+                    "workflow_id": "attacker-owned",
+                    "status": "created",
+                }
+            ),
+            encoding="utf-8",
+        )
+
+        with pytest.raises(ValueError, match="Invalid run_id"):
+            RunState.load(malicious_run_id, project_dir)
+
+    @pytest.mark.parametrize(
+        "bad_run_id",
+        [
+            # One vector per category from ``test_load_rejects_path_traversal``
+            # — enough to prove both entry points agree without re-running
+            # the full attack matrix here.
+            "../escape",    # parent-directory traversal
+            "foo/bar",      # embedded path separator
+            ".hidden",      # leading non-alphanumeric
+            "",             # empty / degenerate
+        ],
+    )
+    def test_init_and_load_share_validation(self, project_dir, bad_run_id):
+        """``__init__`` *and* ``load`` reject the same malformed IDs.
+
+        The two entry points must stay in sync — drift would let an ID
+        slip in via one path that the other would reject, producing
+        confusing crashes mid-workflow. The previous version of this
+        test only exercised ``__init__`` and ``_validate_run_id`` (the
+        shared helper), so a regression in ``load`` — e.g. someone
+        deleting the ``cls._validate_run_id(run_id)`` call there — could
+        slip through despite ``__init__`` and the helper staying
+        aligned. We now hit ``load`` directly with the same vector so
+        any drift between the two call sites is caught by this test.
+        """
+        from specify_cli.workflows.engine import RunState
+
+        # ``__init__`` rejects up front.
+        with pytest.raises(ValueError, match="Invalid run_id"):
+            RunState(run_id=bad_run_id)
+
+        # The shared helper rejects the value too (sanity check that the
+        # ``__init__`` rejection came from the validator, not some
+        # unrelated constructor failure).
+        with pytest.raises(ValueError, match="Invalid run_id"):
+            RunState._validate_run_id(bad_run_id)
+
+        # And ``load`` rejects it *before* touching the filesystem. This
+        # is the assertion the previous version was missing: without it,
+        # a regression in ``load`` (e.g. forgetting to call the
+        # validator before building the path) would not be caught even
+        # though ``__init__`` and the helper still agreed.
+        with pytest.raises(ValueError, match="Invalid run_id"):
+            RunState.load(bad_run_id, project_dir)
+
     def test_append_log(self, project_dir):
         from specify_cli.workflows.engine import RunState
 
@@ -2722,3 +3132,118 @@ steps:
         assert state.status == RunStatus.COMPLETED
         assert "do-plan" in state.step_results
         assert "do-specify" not in state.step_results
+
+
+class TestResumeWithInputs:
+    """Test that `workflow resume` can accept updated workflow inputs."""
+
+    _WF_CMD = """
+schema_version: "1.0"
+workflow:
+  id: "resume-cmd-wf"
+  name: "Resume Cmd WF"
+  version: "1.0.0"
+inputs:
+  cmd:
+    type: string
+    default: "exit 1"
+steps:
+  - id: s
+    type: shell
+    run: "{{ inputs.cmd }}"
+"""
+
+    _WF_NUM = """
+schema_version: "1.0"
+workflow:
+  id: "resume-num-wf"
+  name: "Resume Num WF"
+  version: "1.0.0"
+inputs:
+  count:
+    type: number
+    default: 1
+steps:
+  - id: gate
+    type: gate
+    message: "Review"
+    options: [approve, reject]
+"""
+
+    def _engine(self, project_dir):
+        from specify_cli.workflows.engine import WorkflowEngine
+        return WorkflowEngine(project_dir)
+
+    def test_resume_with_input_reruns_step_with_new_value(self, project_dir):
+        from specify_cli.workflows.engine import WorkflowDefinition
+        from specify_cli.workflows.base import RunStatus
+
+        definition = WorkflowDefinition.from_string(self._WF_CMD)
+        engine = self._engine(project_dir)
+
+        state = engine.execute(definition)
+        assert state.status == RunStatus.FAILED  # "exit 1" fails
+
+        resumed = engine.resume(state.run_id, {"cmd": "exit 0"})
+        assert resumed.status == RunStatus.COMPLETED
+        assert resumed.inputs["cmd"] == "exit 0"
+
+    def test_resume_without_input_preserves_inputs(self, project_dir):
+        from specify_cli.workflows.engine import WorkflowDefinition
+        from specify_cli.workflows.base import RunStatus
+
+        definition = WorkflowDefinition.from_string(self._WF_CMD)
+        engine = self._engine(project_dir)
+
+        state = engine.execute(definition)
+        assert state.status == RunStatus.FAILED
+
+        resumed = engine.resume(state.run_id)
+        assert resumed.status == RunStatus.FAILED  # still "exit 1"
+        assert resumed.inputs["cmd"] == "exit 1"
+
+    def test_resume_merges_and_coerces_typed_input(self, project_dir):
+        import json as _json
+        from specify_cli.workflows.engine import WorkflowDefinition
+        from specify_cli.workflows.base import RunStatus
+
+        definition = WorkflowDefinition.from_string(self._WF_NUM)
+        engine = self._engine(project_dir)
+
+        state = engine.execute(definition)
+        assert state.status == RunStatus.PAUSED
+
+        resumed = engine.resume(state.run_id, {"count": "5"})
+        assert resumed.inputs["count"] == 5  # coerced string -> number
+
+        inputs_file = (
+            project_dir / ".specify" / "workflows" / "runs" / state.run_id / "inputs.json"
+        )
+        assert _json.loads(inputs_file.read_text())["inputs"]["count"] == 5
+
+    def test_resume_invalid_typed_input_raises(self, project_dir):
+        from specify_cli.workflows.engine import WorkflowDefinition
+
+        definition = WorkflowDefinition.from_string(self._WF_NUM)
+        engine = self._engine(project_dir)
+
+        state = engine.execute(definition)
+        with pytest.raises(ValueError):
+            engine.resume(state.run_id, {"count": "not-a-number"})
+
+    def test_cli_resume_input_invalid_format_errors(self, project_dir):
+        from typer.testing import CliRunner
+        from unittest.mock import patch
+        from specify_cli import app
+        from specify_cli.workflows.engine import WorkflowDefinition
+
+        definition = WorkflowDefinition.from_string(self._WF_NUM)
+        state = self._engine(project_dir).execute(definition)
+
+        runner = CliRunner()
+        with patch.object(Path, "cwd", return_value=project_dir):
+            result = runner.invoke(
+                app, ["workflow", "resume", state.run_id, "--input", "bogus"]
+            )
+        assert result.exit_code == 1
+        assert "Invalid input format" in result.stdout

workflows/README.md

@@ -219,6 +219,83 @@ Aggregate results from fan-out steps:
   output: {}
 ```
 
+## Error Handling
+
+By default, any step that returns `StepResult(status=StepStatus.FAILED, ...)`
+at runtime halts the entire run — most commonly a `shell` or
+`command` step exiting non-zero. Set `continue_on_error: true` on
+a step to record its result and continue to the next sibling step
+instead. When the failure was a non-zero exit, the exit code
+remains available on `steps.<id>.output.exit_code` so a downstream
+`if` or `switch` can branch on it (or a `gate` can surface it to
+the operator via `{{ }}` interpolation in `message`):
+
+```yaml
+- id: heavy-thing
+  type: command
+  integration: claude
+  command: speckit.heavy-thing
+  continue_on_error: true
+
+- id: check-result
+  type: if
+  condition: "{{ steps.heavy-thing.output.exit_code != 0 }}"
+  then:
+    - id: review
+      type: gate
+      message: "Step failed (exit {{ steps.heavy-thing.output.exit_code }}). Approve to run the recovery path, or reject to leave the failure recorded and move on."
+      on_reject: skip
+    - id: recover
+      type: if
+      condition: "{{ steps.review.output.choice == 'approve' }}"
+      then:
+        - id: rerun
+          command: speckit.recovery
+  else:
+    - id: next-thing
+      command: speckit.next-thing
+```
+
+A few things worth knowing about that example:
+
+- Both gate options (`approve`, `reject`) return `StepStatus.COMPLETED`;
+  `on_reject: skip` controls only whether the engine aborts on reject
+  (it doesn't, with `skip`) — it does **not** auto-skip subsequent
+  sibling steps in the `then:` list. Downstream branching is the
+  workflow author's responsibility: read
+  `{{ steps.<gate-id>.output.choice }}` in a follow-up `if`, `switch`,
+  or expression, as the `recover` step above does.
+- `on_reject` has three values: `abort` (default — reject → `StepStatus.FAILED`
+  with `output.aborted = True`, halts the run), `skip` (reject →
+  `StepStatus.COMPLETED`, author handles branching as shown), and `retry`
+  (reject → `StepStatus.PAUSED` so the next `specify workflow resume` re-runs
+  the gate).
+- Gates do not automatically re-run the failed step. To express a
+  retry path, either define custom gate options and branch on the
+  choice downstream, or wrap the failing step in your own loop.
+
+**Notes:**
+
+- The field must be a literal boolean (`true` / `false`); coerced
+  strings like `"true"` are rejected at validation time.
+- **Scope: returned failures only.** The flag applies to step results
+  with `status=StepStatus.FAILED`. Unhandled exceptions raised out of a step's
+  `execute()` method are caught one level up by `WorkflowEngine.execute()`,
+  logged as `workflow_failed`, and abort the run regardless of
+  `continue_on_error`. If a step author wants the flag to cover an
+  exceptional path, the step must catch the exception internally and
+  return `StepResult(status=StepStatus.FAILED, ...)` with the failure encoded in
+  `output` (e.g. `exit_code`, `stderr`, or a custom field).
+- Gate aborts (`on_reject: abort` chosen by the operator) always halt
+  the run — `continue_on_error` does not override them. The flag is
+  for transient/expected step failures, not for overriding deliberate
+  operator decisions.
+- Structural validation runs up-front: `specify workflow run` rejects
+  invalid workflow definitions before the run is created, so
+  validation failures never reach this code path.
+- When the flag is omitted, behaviour is byte-equivalent to before
+  this feature.
+
 ## Expressions
 
 Workflow definitions use `{{ expression }}` syntax for dynamic values: