chore: bump version to 0.8.12

fix(codex): inject dot-to-hyphen hook command note in Codex skills (#2503 )
* fix(codex): inject dot-to-hyphen hook command note in Codex skills Hook commands in `.specify/extensions.yml` use dotted ids like `speckit.git.commit`, but Codex skills are named with hyphens (`speckit-git-commit`). The Claude integration handles this via an explicit instruction injected into each generated SKILL.md by `ClaudeIntegration.post_process_skill_content`, but the Codex integration had no such override, so Codex would emit `/speckit.git.commit` (which does not resolve) instead of `/speckit-git-commit`. This adds the same `_inject_hook_command_note` helper and a `post_process_skill_content` override to `CodexIntegration`, plus a small `setup()` override that applies the post-process to each generated SKILL.md (mirroring the pattern in `ClaudeIntegration`). Also widens the existing `test_non_claude_post_process_is_identity` test to use `agy` (another `SkillsIntegration` with no override), since asserting identity behavior on Codex would now incorrectly fail. Tests: - New `TestCodexHookCommandNote` class mirrors `TestClaudeHookCommandNote`: setup-level injection, no-op when no hook block is present, idempotency, and indentation preservation. - `pytest tests/` → 2866 passed, 34 skipped. Signed-off-by: Chao Zhang <1175468+picklebento@users.noreply.github.com> * fix(codex): handle empty eol when instruction is final line without newline The hook-note injection regex allowed end-of-string matches via ``$``, which left the captured ``eol`` empty. When the matched indent was also empty, the substitution concatenated the note onto the same line as the instruction. Default ``eol`` to ``\n`` when the capture is empty. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Signed-off-by: Chao Zhang <1175468+picklebento@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-07-04 04:45:43 +08:00 · 2026-05-20 14:10:09 +00:00 · 2026-05-20 09:04:47 -05:00 · 2026-05-20 06:56:50 -05:00 · 2026-05-20 06:35:56 -05:00 · 2026-05-20 06:11:09 -05:00
30 changed files with 1862 additions and 400 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,52 @@

 <!-- insert new changelog below this comment -->

+## [0.8.12] - 2026-05-20
+
+### Changed
+
+- fix(codex): inject dot-to-hyphen hook command note in Codex skills (#2503)
+- Update Squad Bridge extension to v1.3.0 (#2645)
+- Update Superpowers Implementation Bridge extension to v0.5.0 (#2644)
+- Add Team Assign extension to community catalog (#2642)
+- refactor: migrate extension catalog stack parsing to shared base (#2576)
+- Update Architecture Workflow extension to v1.1.0 (#2588)
+-  fix(workflow): support integration: auto to follow project's initialized AI (#2421)
+- Add Superpowers Implementation Bridge extension to community catalog (#2586)
+- Add Interactive HTML Preview extension to community catalog (#2585)
+- chore: release 0.8.11, begin 0.8.12.dev0 development (#2584)
+- Update Agent Governance extension to v1.1.0 (#2583)
+
+## [0.8.11] - 2026-05-15
+
+### Changed
+
+- refactor: extract _version.py from __init__.py (PR-3/8) (#2550)
+- Add Time Machine extension to community catalog (#2580)
+- fix(powershell): ensure UTF-8 templates are written without BOM (#2280)
+- docs: document high-assurance spec workflow (#2518)
+- docs: fix script name in directory tree examples (#2555)
+- Fix preset skill description precedence (#2538)
+- fix(integration): clarify multi-install guidance (#2549)
+- feat: add version feature reporting (#2548)
+- Add Architecture Workflow extension to community catalog (#2565)
+- chore: release 0.8.10, begin 0.8.11.dev0 development (#2562)
+
+## [0.8.10] - 2026-05-14
+
+### Changed
+
+- docs: streamline install section and add community overview (#2561)
+- Move community extensions table from README to docs site (#2560)
+- Add Agent Governance extension to community catalog (#2559)
+- Add Reqnroll BDD extension to community catalog (#2545)
+- fix(cli): harden extension registration and discovery workflows (#2499)
+- refactor: extract _assets.py and _utils.py from __init__.py (PR-2/8) (#2543)
+- fix(opencode): use commands/ directory (plural) to match OpenCode docs (#2453)
+- refactor: extract _console.py from __init__.py (PR-1/8) (#2474)
+- Fix constitution reference in README (#2491)
+- chore: release 0.8.9, begin 0.8.10.dev0 development (#2532)
+
 ## [0.8.9] - 2026-05-12

 ### Changed
--- a/README.md
+++ b/README.md
@@ -404,11 +404,12 @@ At this stage, your project folder contents should resemble the following:
    ├── memory
    │  └── constitution.md
    ├── scripts
-    │  ├── check-prerequisites.sh
-    │  ├── common.sh
-    │  ├── create-new-feature.sh
-    │  ├── setup-plan.sh
-    │  └── update-claude-md.sh
+    │  └── bash
+    │      ├── check-prerequisites.sh
+    │      ├── common.sh
+    │      ├── create-new-feature.sh
+    │      ├── setup-plan.sh
+    │      └── setup-tasks.sh
    ├── specs
    │  └── 001-create-taskify
    │      └── spec.md
@@ -465,11 +466,12 @@ The output of this step will include a number of implementation detail documents
 ├── memory
 │  └── constitution.md
 ├── scripts
-│  ├── check-prerequisites.sh
-│  ├── common.sh
-│  ├── create-new-feature.sh
-│  ├── setup-plan.sh
-│  └── update-claude-md.sh
+│  └── bash
+│      ├── check-prerequisites.sh
+│      ├── common.sh
+│      ├── create-new-feature.sh
+│      ├── setup-plan.sh
+│      └── setup-tasks.sh
 ├── specs
 │  └── 001-create-taskify
 │      ├── contracts
--- a/docs/community/extensions.md
+++ b/docs/community/extensions.md
@@ -28,6 +28,7 @@ The following community-contributed extensions are available in [`catalog.commun
 | API Evolve | Managed API contract evolution — breaking-change detection, semver enforcement, deprecation orchestration, and lifecycle gates across REST, GraphQL, and gRPC | `process` | Read+Write | [spec-kit-api-evolve](https://github.com/Quratulain-bilal/spec-kit-api-evolve) |
 | Architect Impact Previewer | Predicts architectural impact, complexity, and risks of proposed changes before implementation. | `visibility` | Read-only | [spec-kit-architect-preview](https://github.com/UmmeHabiba1312/spec-kit-architect-preview) |
 | Architecture Guard | Continuous architecture governance for AI-assisted development. Reviews specs, plans, and code for architecture drift, producing structured refactor tasks and evolution proposals. | `process` | Read+Write | [spec-kit-architecture-guard](https://github.com/DyanGalih/spec-kit-architecture-guard) |
+| Architecture Workflow | Generate or reverse project-level 4+1 architecture view artifacts and synthesis | `docs` | Read+Write | [spec-kit-arch](https://github.com/bigsmartben/spec-kit-arch) |
 | Archive Extension | Archive merged features into main project memory. | `docs` | Read+Write | [spec-kit-archive](https://github.com/stn1slv/spec-kit-archive) |
 | Azure DevOps Integration | Sync user stories and tasks to Azure DevOps work items using OAuth authentication | `integration` | Read+Write | [spec-kit-azure-devops](https://github.com/pragya247/spec-kit-azure-devops) |
 | Blueprint | Stay code-literate in AI-driven development: review a complete code blueprint for every task from spec artifacts before /speckit.implement runs | `docs` | Read+Write | [spec-kit-blueprint](https://github.com/chordpli/spec-kit-blueprint) |
@@ -50,6 +51,7 @@ The following community-contributed extensions are available in [`catalog.commun
 | Fleet Orchestrator | Orchestrate a full feature lifecycle with human-in-the-loop gates across all SpecKit phases | `process` | Read+Write | [spec-kit-fleet](https://github.com/sharathsatish/spec-kit-fleet) |
 | GitHub Issues Integration 1 | Generate spec artifacts from GitHub Issues - import issues, sync updates, and maintain bidirectional traceability | `integration` | Read+Write | [spec-kit-github-issues](https://github.com/Fatima367/spec-kit-github-issues) |
 | GitHub Issues Integration 2 | Creates and syncs local specs from an existing GitHub issue | `integration` | Read+Write | [spec-kit-issue](https://github.com/aaronrsun/spec-kit-issue) |
+| Interactive HTML Preview | Generate self-contained interactive HTML prototypes from Spec Kit artifacts | `docs` | Read+Write | [spec-kit-preview](https://github.com/bigsmartben/spec-kit-preview) |
 | Intelligent Agent Orchestrator | Cross-catalog agent discovery and intelligent prompt-to-command routing | `process` | Read+Write | [spec-kit-orchestrator](https://github.com/pragya247/spec-kit-orchestrator) |
 | Iterate | Iterate on spec documents with a two-phase define-and-apply workflow — refine specs mid-implementation and go straight back to building | `docs` | Read+Write | [spec-kit-iterate](https://github.com/imviancagrace/spec-kit-iterate) |
 | Jira Integration | Create Jira Epics, Stories, and Issues from spec-kit specifications and task breakdowns with configurable hierarchy and custom field support | `integration` | Read+Write | [spec-kit-jira](https://github.com/mbachorik/spec-kit-jira) |
@@ -104,11 +106,14 @@ The following community-contributed extensions are available in [`catalog.commun
 | Spec Validate | Comprehension validation, review gating, and approval state for spec-kit artifacts — staged quizzes, peer review SLA, and a hard gate before /speckit.implement | `process` | Read+Write | [spec-kit-spec-validate](https://github.com/aeltayeb/spec-kit-spec-validate) |
 | Spec2Cloud | Spec-driven workflow tuned for shipping to Azure | `process` | Read+Write | [spec2cloud](https://github.com/Azure-Samples/Spec2Cloud) |
 | SpecTest | Auto-generate test scaffolds from spec criteria, map coverage, and find untested requirements | `code` | Read+Write | [spec-kit-spectest](https://github.com/Quratulain-bilal/spec-kit-spectest) |
-| Squad Bridge | Bootstrap and synchronize a Squad agent team from your Speckit spec and tasks | `process` | Read+Write | [spec-kit-squad](https://github.com/jwill824/spec-kit-squad) |
+| Squad Bridge | Bootstrap and synchronize a Squad agent team from your Speckit spec and tasks. | `process` | Read+Write | [spec-kit-squad](https://github.com/jwill824/spec-kit-squad) |
 | Staff Review Extension | Staff-engineer-level code review that validates implementation against spec, checks security, performance, and test coverage | `code` | Read-only | [spec-kit-staff-review](https://github.com/arunt14/spec-kit-staff-review) |
 | Status Report | Project status, feature progress, and next-action recommendations for spec-driven workflows | `visibility` | Read-only | [Open-Agent-Tools/spec-kit-status](https://github.com/Open-Agent-Tools/spec-kit-status) |
 | Superpowers Bridge | Orchestrates obra/superpowers skills within the spec-kit SDD workflow across the full lifecycle (clarification, TDD, review, verification, critique, debugging, branch completion) | `process` | Read+Write | [superpowers-bridge](https://github.com/RbBtSn0w/spec-kit-extensions/tree/main/superpowers-bridge) |
 | Superpowers Bridge (WangX0111) | Bridges spec-kit with obra/superpowers (brainstorming, TDD, subagent, code-review) into a unified, resumable workflow with graceful degradation and session progress tracking | `process` | Read+Write | [superspec](https://github.com/WangX0111/superspec) |
+| 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) |
+| Team Assign | Assign tasks.md items to human engineers, split into subtasks, and generate a per-engineer workboard | `process` | Read+Write | [spec-kit-team-assign](https://github.com/tarunkumarbhati/spec-kit-team-assign) |
+| Time Machine | Retroactively apply the full SDD workflow to existing codebases — analyse, spec, and ship feature-by-feature | `process` | Read+Write | [spec-kit-time-machine](https://github.com/teeyo/spec-kit-time-machine) |
 | TinySpec | Lightweight single-file workflow for small tasks — skip the heavy multi-step SDD process | `process` | Read+Write | [spec-kit-tinyspec](https://github.com/Quratulain-bilal/spec-kit-tinyspec) |
 | Token Consumption Analyzer | Captures, analyzes, and compares token consumption across SDD workflows | `visibility` | Read-only | [spec-kit-token-analyzer](https://github.com/coderandhiker/spec-kit-token-analyzer) |
 | V-Model Extension Pack | Enforces V-Model paired generation of development specs and test specs with full traceability | `docs` | Read+Write | [spec-kit-v-model](https://github.com/leocamello/spec-kit-v-model) |
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -94,7 +94,10 @@ After initialization, you should see the following commands available in your co
 - `/speckit.plan` - Generate implementation plans  
 - `/speckit.tasks` - Break down into actionable tasks

-The `.specify/scripts` directory will contain both `.sh` and `.ps1` scripts.
+Scripts are installed into a variant subdirectory matching the chosen script type:
+
+- `.specify/scripts/bash/` — contains `.sh` scripts (default on Linux/macOS)
+- `.specify/scripts/powershell/` — contains `.ps1` scripts (default on Windows)

 ## Troubleshooting

--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -5,11 +5,19 @@ This guide will help you get started with Spec-Driven Development using Spec Kit
 > [!NOTE]
 > All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`.

-## The 6-Step Process
+## Recommended Workflow

 > [!TIP]
 > **Context Awareness**: Spec Kit commands automatically detect the active feature based on your current Git branch (e.g., `001-feature-name`). To switch between different specifications, simply switch Git branches.

+After installing Spec Kit and defining your project constitution, quick experiments can use the lean feature path: `/speckit.specify` -> `/speckit.plan` -> `/speckit.tasks` -> `/speckit.implement`. For production features or any work with meaningful ambiguity, treat `/speckit.clarify`, `/speckit.checklist`, and `/speckit.analyze` as regular quality gates:
+
+```text
+/speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.checklist -> /speckit.plan -> /speckit.tasks -> /speckit.analyze -> /speckit.implement
+```
+
+Use `/speckit.clarify` to reduce requirement ambiguity before planning, `/speckit.checklist` to validate requirements quality before planning, and `/speckit.analyze` to check spec/plan/task consistency before implementation starts. You can repeat `/speckit.analyze` after implementation as an extra review, but keep the first analysis before `/speckit.implement` so gaps are caught while the plan and tasks can still be adjusted.
+
 ### Step 1: Install Specify

 **In your terminal**, run the `specify` CLI command to initialize your project:
@@ -24,10 +32,13 @@ uvx --from git+https://github.com/github/spec-kit.git specify init .

 > [!NOTE]
 > You can also install the CLI persistently with `pipx`:
+>
 > ```bash
 > pipx install git+https://github.com/github/spec-kit.git
 > ```
+>
 > After installing with `pipx`, run `specify` directly instead of `uvx --from ... specify`, for example:
+>
 > ```bash
 > specify init <PROJECT_NAME>
 > specify init .
@@ -56,7 +67,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 /speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.
 ```

-### Step 4: Refine the Spec
+### Step 4: Refine and Validate the Spec

 **In the chat**, use the `/speckit.clarify` slash command to identify and resolve ambiguities in your specification. You can provide specific focus areas as arguments.

@@ -64,6 +75,12 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 /speckit.clarify Focus on security and performance requirements.
 ```

+Then validate the requirements with `/speckit.checklist` before creating the technical plan:
+
+```bash
+/speckit.checklist
+```
+
 ### Step 5: Create a Technical Implementation Plan

 **In the chat**, use the `/speckit.plan` slash command to provide your tech stack and architecture choices.
@@ -72,7 +89,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 /speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.
 ```

-### Step 6: Break Down and Implement
+### Step 6: Break Down, Analyze, and Implement

 **In the chat**, use the `/speckit.tasks` slash command to create an actionable task list.

@@ -80,13 +97,13 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 /speckit.tasks
 ```

-Optionally, validate the plan with `/speckit.analyze`:
+Validate cross-artifact consistency with `/speckit.analyze` before implementation:

 ```markdown
 /speckit.analyze
 ```

-Then, use the `/speckit.implement` slash command to execute the plan.
+Use the `/speckit.implement` slash command to execute the plan.

 ```markdown
 /speckit.implement
@@ -159,7 +176,7 @@ Generate an actionable task list using the `/speckit.tasks` command:

 ### Step 7: Validate and Implement

-Have your coding agent audit the implementation plan using `/speckit.analyze`:
+Have your coding agent audit the spec, plan, and tasks with `/speckit.analyze` before implementation:

 ```bash
 /speckit.analyze
@@ -179,7 +196,7 @@ Finally, implement the solution:
 - **Be explicit** about what you're building and why
 - **Don't focus on tech stack** during specification phase
 - **Iterate and refine** your specifications before implementation
- **Validate** the plan before coding begins
+- **Validate** requirements and plans before coding begins
 - **Let the coding agent handle** the implementation details

 ## Next Steps
--- a/docs/reference/core.md
+++ b/docs/reference/core.md
@@ -77,6 +77,16 @@ specify version

 Displays the Spec Kit CLI version, Python version, platform, and architecture.

+To inspect local CLI capabilities without checking the network:
+
+```bash
+specify version --features
+specify version --features --json
+```
+
+The JSON form is intended for scripts and coding agents that need to choose a
+workflow based on the installed CLI's supported features.
+
 A quick version check is also available via:

 ```bash
--- a/extensions/catalog.community.json
+++ b/extensions/catalog.community.json
@@ -1,6 +1,6 @@
 {
  "schema_version": "1.0",
-  "updated_at": "2026-05-14T00:00:00Z",
+  "updated_at": "2026-05-20T00:00:00Z",
  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
  "extensions": {
    "aide": {
@@ -73,8 +73,8 @@
      "id": "agent-governance",
      "description": "Project-local agent governance memory and context projection.",
      "author": "bigben",
-      "version": "1.0.0",
-      "download_url": "https://github.com/bigsmartben/spec-kit-agent-governance/archive/refs/tags/v1.0.0.zip",
+      "version": "1.1.0",
+      "download_url": "https://github.com/bigsmartben/spec-kit-agent-governance/archive/refs/tags/v1.1.0.zip",
      "repository": "https://github.com/bigsmartben/spec-kit-agent-governance",
      "homepage": "https://github.com/bigsmartben/spec-kit-agent-governance",
      "documentation": "https://github.com/bigsmartben/spec-kit-agent-governance/blob/main/README.md",
@@ -103,7 +103,7 @@
      "downloads": 0,
      "stars": 0,
      "created_at": "2026-05-14T00:00:00Z",
-      "updated_at": "2026-05-14T00:00:00Z"
+      "updated_at": "2026-05-15T00:00:00Z"
    },
    "agent-orchestrator": {
      "name": "Intelligent Agent Orchestrator",
@@ -174,6 +174,37 @@
      "created_at": "2026-05-07T00:00:00Z",
      "updated_at": "2026-05-07T00:00:00Z"
    },
+    "arch": {
+      "name": "Architecture Workflow",
+      "id": "arch",
+      "description": "Generate or reverse project-level 4+1 architecture view artifacts and synthesis",
+      "author": "bigsmartben",
+      "version": "1.1.0",
+      "download_url": "https://github.com/bigsmartben/spec-kit-arch/archive/refs/tags/v1.1.0.zip",
+      "repository": "https://github.com/bigsmartben/spec-kit-arch",
+      "homepage": "https://github.com/bigsmartben/spec-kit-arch",
+      "documentation": "https://github.com/bigsmartben/spec-kit-arch/blob/main/README.md",
+      "changelog": "https://github.com/bigsmartben/spec-kit-arch/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.10.dev0"
+      },
+      "provides": {
+        "commands": 2,
+        "hooks": 0
+      },
+      "tags": [
+        "architecture",
+        "4plus1",
+        "workflow",
+        "design"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-14T00:00:00Z",
+      "updated_at": "2026-05-15T00:00:00Z"
+    },
    "architect-preview": {
      "name": "Architect Impact Previewer",
      "id": "architect-preview",
@@ -1883,6 +1914,37 @@
      "created_at": "2026-03-18T00:00:00Z",
      "updated_at": "2026-03-18T00:00:00Z"
    },
+    "preview": {
+      "name": "Interactive HTML Preview",
+      "id": "preview",
+      "description": "Generate self-contained interactive HTML prototypes from Spec Kit artifacts",
+      "author": "bigsmartben",
+      "version": "1.0.0",
+      "download_url": "https://github.com/bigsmartben/spec-kit-preview/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/bigsmartben/spec-kit-preview",
+      "homepage": "https://github.com/bigsmartben/spec-kit-preview",
+      "documentation": "https://github.com/bigsmartben/spec-kit-preview/blob/main/README.md",
+      "changelog": "https://github.com/bigsmartben/spec-kit-preview/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.10.dev0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 0
+      },
+      "tags": [
+        "preview",
+        "prototype",
+        "html",
+        "ux"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-15T00:00:00Z",
+      "updated_at": "2026-05-15T00:00:00Z"
+    },
    "product-forge": {
      "name": "Product Forge",
      "id": "product-forge",
@@ -2550,6 +2612,55 @@
      "created_at": "2026-04-30T00:00:00Z",
      "updated_at": "2026-04-30T00:00:00Z"
    },
+    "speckit-superpowers-bridge": {
+      "name": "Superpowers Implementation Bridge",
+      "id": "speckit-superpowers-bridge",
+      "description": "Thin orchestrator between Spec Kit (design) and Superpowers (implementation). Cross-agent.",
+      "author": "lihan3238",
+      "version": "0.5.0",
+      "download_url": "https://github.com/lihan3238/speckit-superpowers-bridge/releases/download/v0.5.0/speckit-superpowers-bridge-v0.5.0.zip",
+      "repository": "https://github.com/lihan3238/speckit-superpowers-bridge",
+      "homepage": "https://github.com/lihan3238/speckit-superpowers-bridge",
+      "documentation": "https://github.com/lihan3238/speckit-superpowers-bridge#readme",
+      "changelog": "https://github.com/lihan3238/speckit-superpowers-bridge/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.10",
+        "tools": [
+          {
+            "name": "powershell",
+            "version": ">=5.1",
+            "required": false
+          },
+          {
+            "name": "bash",
+            "version": ">=4.0",
+            "required": false
+          },
+          {
+            "name": "jq",
+            "version": ">=1.6",
+            "required": false
+          }
+        ]
+      },
+      "provides": {
+        "commands": 3,
+        "hooks": 5
+      },
+      "tags": [
+        "bridge",
+        "superpowers",
+        "cross-agent",
+        "tdd",
+        "workflow"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-15T00:00:00Z",
+      "updated_at": "2026-05-20T00:00:00Z"
+    },
    "speckit-utils": {
      "name": "SDD Utilities",
      "id": "speckit-utils",
@@ -2618,21 +2729,21 @@
    "squad": {
      "name": "Squad Bridge",
      "id": "squad",
-      "description": "Bootstrap and synchronize a Squad agent team from your Spec Kit spec and tasks.",
+      "description": "Bootstrap and synchronize a Squad agent team from your Speckit spec and tasks.",
      "author": "jwill824",
-      "version": "1.1.0",
-      "download_url": "https://github.com/jwill824/spec-kit-squad/archive/refs/tags/v1.1.0.zip",
+      "version": "1.3.0",
+      "download_url": "https://github.com/jwill824/spec-kit-squad/archive/refs/tags/v1.3.0.zip",
      "repository": "https://github.com/jwill824/spec-kit-squad",
      "homepage": "https://github.com/jwill824/spec-kit-squad",
      "documentation": "https://github.com/jwill824/spec-kit-squad/blob/main/README.md",
      "changelog": "https://github.com/jwill824/spec-kit-squad/blob/main/docs/CHANGELOG.md",
      "license": "MIT",
      "requires": {
-        "speckit_version": ">=0.1.0",
+        "speckit_version": ">=0.8.11",
        "tools": [
          {
            "name": "@bradygaster/squad-cli",
-            "version": ">=0.1.0",
+            "version": ">=0.9.4",
            "required": true
          }
        ]
@@ -2652,7 +2763,7 @@
      "downloads": 0,
      "stars": 0,
      "created_at": "2026-04-29T00:00:00Z",
-      "updated_at": "2026-04-29T00:00:00Z"
+      "updated_at": "2026-05-20T00:00:00Z"
    },
    "staff-review": {
      "name": "Staff Review Extension",
@@ -2854,6 +2965,74 @@
      "created_at": "2026-03-02T00:00:00Z",
      "updated_at": "2026-03-02T00:00:00Z"
    },
+    "team-assign": {
+      "name": "Team Assign",
+      "id": "team-assign",
+      "description": "Assign tasks.md items to human engineers, split into subtasks, and generate a per-engineer workboard",
+      "author": "tarunkumarbhati",
+      "version": "1.0.0",
+      "download_url": "https://github.com/tarunkumarbhati/spec-kit-team-assign/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/tarunkumarbhati/spec-kit-team-assign",
+      "homepage": "https://github.com/tarunkumarbhati/spec-kit-team-assign",
+      "documentation": "https://github.com/tarunkumarbhati/spec-kit-team-assign/blob/main/README.md",
+      "changelog": "https://github.com/tarunkumarbhati/spec-kit-team-assign/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 3
+      },
+      "tags": [
+        "team",
+        "assignment",
+        "process",
+        "planning",
+        "subtasks"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-20T00:00:00Z",
+      "updated_at": "2026-05-20T00:00:00Z"
+    },
+    "time-machine": {
+      "name": "Time Machine",
+      "id": "time-machine",
+      "description": "Retroactively apply the full SDD workflow to existing codebases — analyse, spec, and ship feature-by-feature",
+      "author": "te3yo",
+      "version": "1.1.0",
+      "download_url": "https://github.com/teeyo/spec-kit-time-machine/archive/refs/tags/v1.1.0.zip",
+      "repository": "https://github.com/teeyo/spec-kit-time-machine",
+      "homepage": "https://github.com/teeyo/spec-kit-time-machine",
+      "documentation": "https://github.com/teeyo/spec-kit-time-machine",
+      "changelog": "https://github.com/teeyo/spec-kit-time-machine/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0",
+        "tools": [
+          {
+            "name": "git",
+            "required": true
+          }
+        ]
+      },
+      "provides": {
+        "commands": 3,
+        "hooks": 1
+      },
+      "tags": [
+        "brownfield",
+        "automation",
+        "workflow",
+        "process"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-05-15T00:00:00Z",
+      "updated_at": "2026-05-15T00:00:00Z"
+    },
    "tinyspec": {
      "name": "TinySpec",
      "id": "tinyspec",
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.8.10.dev0"
+version = "0.8.12"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [
--- a/scripts/powershell/create-new-feature.ps1
+++ b/scripts/powershell/create-new-feature.ps1
@@ -350,7 +350,10 @@ if (-not $DryRun) {
    if (-not (Test-Path -PathType Leaf $specFile)) {
        $template = Resolve-Template -TemplateName 'spec-template' -RepoRoot $repoRoot
        if ($template -and (Test-Path $template)) {
-            Copy-Item $template $specFile -Force
+            # Read the template content and write it to the spec file with UTF-8 encoding without BOM
+            $content = [System.IO.File]::ReadAllText($template)
+            $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+            [System.IO.File]::WriteAllText($specFile, $content, $utf8NoBom)
        } else {
            New-Item -ItemType File -Path $specFile -Force | Out-Null
        }
--- a/scripts/powershell/setup-plan.ps1
+++ b/scripts/powershell/setup-plan.ps1
@@ -36,8 +36,10 @@ New-Item -ItemType Directory -Path $paths.FEATURE_DIR -Force | Out-Null
 # Copy plan template if it exists, otherwise note it or create empty file
 $template = Resolve-Template -TemplateName 'plan-template' -RepoRoot $paths.REPO_ROOT
 if ($template -and (Test-Path $template)) { 
-    Copy-Item $template $paths.IMPL_PLAN -Force
-    Write-Output "Copied plan template to $($paths.IMPL_PLAN)"
+    # Read the template content and write it to the implementation plan file with UTF-8 encoding without BOM
+    $content = [System.IO.File]::ReadAllText($template)
+    $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+    [System.IO.File]::WriteAllText($paths.IMPL_PLAN, $content, $utf8NoBom)
 } else {
    Write-Warning "Plan template not found"
    # Create a basic plan file if template doesn't exist
--- a/src/specify_cli/init.py
+++ b/src/specify_cli/init.py
@@ -32,12 +32,9 @@ import zipfile
 import shutil
 import json
 import shlex
-import urllib.error
-import urllib.request
 import yaml
 from pathlib import Path

-from packaging.version import InvalidVersion, Version
 from typing import Any, Optional

 import typer
@@ -58,7 +55,7 @@ from .integration_state import (
    installed_integration_keys as _installed_integration_keys,
    integration_setting as _integration_setting,
    integration_settings as _integration_settings,
-    normalize_integration_state as _normalize_integration_state,
+    try_read_integration_json as _try_read_integration_json,
    write_integration_json as _write_integration_json_file,
 )
 from .shared_infra import (
@@ -95,8 +92,12 @@ from ._utils import (
    merge_json_files as merge_json_files,
    run_command as run_command,
 )
-
-GITHUB_API_LATEST = "https://api.github.com/repos/github/spec-kit/releases/latest"
+from ._version import (
+    GITHUB_API_LATEST as GITHUB_API_LATEST,
+    self_app as _self_app,
+    self_check as self_check,
+    self_upgrade as self_upgrade,
+)

 def _build_agent_config() -> dict[str, dict[str, Any]]:
    """Derive AGENT_CONFIG from INTEGRATION_REGISTRY."""
@@ -229,9 +230,10 @@ def _install_shared_infra(
 ) -> bool:
    """Install shared infrastructure files into *project_path*.

-    Copies ``.specify/scripts/`` and ``.specify/templates/`` from the
-    bundled core_pack or source checkout.  Tracks all installed files
-    in ``speckit.manifest.json``.
+    Copies ``.specify/scripts/<variant>/`` and ``.specify/templates/`` from
+    the bundled core_pack or source checkout, where ``<variant>`` is
+    ``bash`` when *script_type* is ``"sh"`` and ``powershell`` when it is
+    ``"ps"``.  Tracks all installed files in ``speckit.manifest.json``.

    Page templates are processed to resolve ``__SPECKIT_COMMAND_<NAME>__``
    placeholders using *invoke_separator* (``"."`` for markdown agents,
@@ -1155,15 +1157,59 @@ def check():
    if not any(agent_results.values()):
        console.print("[dim]Tip: Install a coding agent for the best experience[/dim]")

+
+def _feature_capabilities() -> dict[str, bool]:
+    """Return stable local CLI capability flags for humans and agents."""
+    return {
+        "controlled_multi_install_integrations": True,
+        "integration_use_command": True,
+        "multi_install_safe_registry_metadata": True,
+        "integration_upgrade_command": True,
+        "self_check_command": True,
+        "workflow_catalog": True,
+        "bundled_templates": True,
+    }
+
+
@app.command()
-def version():
+def version(
+    features: bool = typer.Option(
+        False,
+        "--features",
+        help="Show local CLI feature capabilities.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit feature capabilities as JSON. Requires --features.",
+    ),
+):
    """Display version and system information."""
    import platform

-    show_banner()
-
    cli_version = get_speckit_version()

+    if json_output and not features:
+        console.print("[red]Error:[/red] --json requires --features.")
+        raise typer.Exit(1)
+
+    if features:
+        capabilities = _feature_capabilities()
+        if json_output:
+            payload = {"version": cli_version, "features": capabilities}
+            console.print(json.dumps(payload, indent=2))
+            return
+
+        console.print(f"Spec Kit CLI: {cli_version}")
+        console.print()
+        console.print("Features:")
+        for key, enabled in capabilities.items():
+            label = key.replace("_", " ")
+            console.print(f"- {label}: {'yes' if enabled else 'no'}")
+        return
+
+    show_banner()
+
    info_table = Table(show_header=False, box=None, padding=(0, 2))
    info_table.add_column("Key", style="cyan", justify="right")
    info_table.add_column("Value", style="white")
@@ -1185,156 +1231,7 @@ def version():
    console.print(panel)
    console.print()

-def _get_installed_version() -> str:
-    """Return the installed specify-cli distribution version or 'unknown'.
-
-    Uses importlib.metadata so the value reflects what was actually installed
-    by pip/uv/pipx — not a value read from pyproject.toml. This is
-    intentional for `specify self check`, which should reason about the
-    installed distribution rather than a source-tree fallback. Callers must
-    treat the sentinel string 'unknown' as an indeterminate value (see FR-020).
-    """
-
-    import importlib.metadata
-
-    metadata_errors = [importlib.metadata.PackageNotFoundError]
-    invalid_metadata_error = getattr(importlib.metadata, "InvalidMetadataError", None)
-    if invalid_metadata_error is not None:
-        metadata_errors.append(invalid_metadata_error)
-
-    try:
-        return importlib.metadata.version("specify-cli")
-    except tuple(metadata_errors):
-        return "unknown"
-
-def _normalize_tag(tag: str) -> str:
-    """Strip exactly one leading 'v' from a release tag.
-
-    Returns the rest of the string unchanged. This handles the common
-    'vX.Y.Z' tag convention in this repo; it MUST NOT strip more
-    aggressively (e.g., two leading 'v's keeps one).
-    """
-    return tag[1:] if tag.startswith("v") else tag
-
-def _is_newer(latest: str, current: str) -> bool:
-    """Return True iff `latest` is strictly greater than `current` under PEP 440.
-
-    Returns False whenever either side is 'unknown' or fails to parse; this
-    keeps the comparison indeterminate (rather than crashing or falsely
-    recommending a downgrade) on edge inputs.
-    """
-    if latest == "unknown" or current == "unknown":
-        return False
-    try:
-        return Version(latest) > Version(current)
-    except InvalidVersion:
-        return False
-
-
-def _fetch_latest_release_tag() -> tuple[str | None, str | None]:
-    """Return (tag, failure_category). Exactly one outbound call, 5 s timeout.
-
-    On success: (tag_name, None).
-    On a documented network/HTTP failure (added in T029/T030): (None, category).
-    On anything else — including a malformed response body — the exception
-    propagates; there is no catch-all (research D-006).
-    """
-    from .authentication.http import open_url
-
-    try:
-        with open_url(
-            GITHUB_API_LATEST,
-            timeout=5,
-            extra_headers={"Accept": "application/vnd.github+json"},
-        ) as resp:
-            payload = json.loads(resp.read().decode("utf-8"))
-            tag = payload.get("tag_name")
-            if not isinstance(tag, str) or not tag:
-                raise ValueError("GitHub API response missing valid tag_name")
-            return tag, None
-    except urllib.error.HTTPError as e:
-        # Order matters: HTTPError is a subclass of URLError.
-        if e.code == 403:
-            return None, (
-                "rate limited (configure ~/.specify/auth.json with a GitHub token)"
-            )
-        return None, f"HTTP {e.code}"
-    except (urllib.error.URLError, OSError):
-        return None, "offline or timeout"
-
-
-# ===== Self Commands =====
-self_app = typer.Typer(
-    name="self",
-    help="Manage the specify CLI itself (read-only check and reserved upgrade command).",
-    add_completion=False,
-)
-app.add_typer(self_app, name="self")
-
-@self_app.command("check")
-def self_check() -> None:
-    """Check whether a newer specify-cli release is available. Read-only.
-
-    This command only checks for updates; it does not modify your installation.
-    The reserved (and currently non-destructive) `specify self upgrade` command
-    is the name that a future release will use for actual self-upgrade — its
-    behavior is not implemented in this release and is intentionally out of
-    scope here. See `specify self upgrade --help` for its current status.
-    """
-
-    installed = _get_installed_version()
-    tag, failure_reason = _fetch_latest_release_tag()
-
-    if tag is None:
-        # Graceful-failure path (FR-008). `failure_reason` is one of the
-        # enumerated strings produced by _fetch_latest_release_tag() — it
-        # never contains a URL, headers, response body, or traceback.
-        assert failure_reason is not None
-        console.print(f"Installed: {installed}")
-        console.print(f"[yellow]Could not check latest release:[/yellow] {failure_reason}")
-        return
-
-    latest_normalized = _normalize_tag(tag)
-
-    if installed == "unknown":
-        # FR-020: surface the latest release and the recovery action even
-        # when the local distribution metadata is unavailable.
-        console.print("Current version could not be determined.")
-        console.print(f"Latest release: {latest_normalized}")
-        console.print("\nTo reinstall:")
-        console.print("  uv tool install specify-cli --force \\")
-        console.print(f"    --from git+https://github.com/github/spec-kit.git@{tag}")
-        return
-
-    if _is_newer(latest_normalized, installed):
-        console.print(f"[green]Update available:[/green] {installed} → {latest_normalized}")
-        console.print("\nTo upgrade:")
-        console.print("  uv tool install specify-cli --force \\")
-        console.print(f"    --from git+https://github.com/github/spec-kit.git@{tag}")
-        return
-
-    # Installed is parseable AND is >= latest → "up to date" (FR-006).
-    # Also reached when the tag is unparseable (InvalidVersion) → _is_newer
-    # returns False, and the up-to-date branch is the safer default per
-    # FR-004 / test T016.
-    console.print(f"[green]Up to date:[/green] {installed}")
-
-
-@self_app.command("upgrade")
-def self_upgrade() -> None:
-    """Reserved command surface for self-upgrade; not implemented in this release.
-
-    This command is a documented non-destructive stub in this release: it
-    performs no outbound network request, no install-method detection, and
-    invokes no installer. It prints a three-line guidance message and exits 0.
-    Actual self-upgrade is planned as follow-up work.
-
-    Use `specify self check` today to see whether a newer release is available
-    and to get a copy-pasteable reinstall command.
-    """
-    console.print("specify self upgrade is not implemented yet.")
-    console.print("Run 'specify self check' to see whether a newer release is available.")
-    console.print("Actual self-upgrade is planned as follow-up work.")
+app.add_typer(_self_app, name="self")


 # ===== Extension Commands =====
@@ -1386,35 +1283,37 @@ integration_app.add_typer(integration_catalog_app, name="catalog")


 def _read_integration_json(project_root: Path) -> dict[str, Any]:
-    """Load ``.specify/integration.json``. Returns normalized state when present."""
+    """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
-    if not path.exists():
-        return {}
-    try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
-        console.print(f"[red]Error:[/red] {path} contains invalid 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] {exc}")
-        raise typer.Exit(1)
-    except OSError as exc:
+        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] {exc}")
-        raise typer.Exit(1)
-    if not isinstance(data, dict):
-        console.print(f"[red]Error:[/red] {path} must contain a JSON object, got {type(data).__name__}.")
-        console.print(f"Please fix or delete {INTEGRATION_JSON} and retry.")
-        raise typer.Exit(1)
-    schema = data.get("integration_state_schema")
-    if isinstance(schema, int) and not isinstance(schema, bool) and schema > INTEGRATION_STATE_SCHEMA:
+        console.print(f"[dim]Details:[/dim] {error.detail}")
+    elif error.kind == "not_object":
        console.print(
-            f"[red]Error:[/red] {path} uses integration state schema {schema}, "
+            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)
-    return _normalize_integration_state(data)
+    raise typer.Exit(1)


 def _write_integration_json(
@@ -1696,10 +1595,18 @@ def integration_install(

    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"Run [cyan]specify integration upgrade {key}[/cyan] to reinstall managed files, "
-            f"or [cyan]specify integration uninstall {key}[/cyan] first."
+            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:
@@ -1719,8 +1626,12 @@ def integration_install(
                "integrations are declared multi-install safe."
            )
            console.print(
-                f"Run [cyan]specify integration switch {key}[/cyan] to replace the default "
-                f"integration, or retry with [cyan]--force[/cyan] to opt in."
+                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)

--- a/src/specify_cli/_version.py
+++ b/src/specify_cli/_version.py
@@ -0,0 +1,173 @@
+"""Version checking and self-update commands for specify_cli.
+
+Pure helpers for comparing PEP 440 versions and fetching the latest GitHub
+release tag.  The ``self_app`` Typer sub-command group is co-located here so
+all version-related logic lives in one place.
+
+Dependencies: stdlib + packaging + ._console only (no other internal imports
+at module level, keeping this layer thin and circular-import-safe).
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+
+import typer
+from packaging.version import InvalidVersion, Version
+
+from ._console import console
+
+GITHUB_API_LATEST = "https://api.github.com/repos/github/spec-kit/releases/latest"
+
+
+def _get_installed_version() -> str:
+    """Return the installed specify-cli distribution version or 'unknown'.
+
+    Uses importlib.metadata so the value reflects what was actually installed
+    by pip/uv/pipx — not a value read from pyproject.toml. This is
+    intentional for `specify self check`, which should reason about the
+    installed distribution rather than a source-tree fallback. Callers must
+    treat the sentinel string 'unknown' as an indeterminate value (see FR-020).
+    """
+    import importlib.metadata
+
+    metadata_errors = [importlib.metadata.PackageNotFoundError]
+    invalid_metadata_error = getattr(importlib.metadata, "InvalidMetadataError", None)
+    if invalid_metadata_error is not None:
+        metadata_errors.append(invalid_metadata_error)
+
+    try:
+        return importlib.metadata.version("specify-cli")
+    except tuple(metadata_errors):
+        return "unknown"
+
+
+def _normalize_tag(tag: str) -> str:
+    """Strip exactly one leading 'v' from a release tag.
+
+    Returns the rest of the string unchanged. This handles the common
+    'vX.Y.Z' tag convention in this repo; it MUST NOT strip more
+    aggressively (e.g., two leading 'v's keeps one).
+    """
+    return tag[1:] if tag.startswith("v") else tag
+
+
+def _is_newer(latest: str, current: str) -> bool:
+    """Return True iff `latest` is strictly greater than `current` under PEP 440.
+
+    Returns False whenever either side is 'unknown' or fails to parse; this
+    keeps the comparison indeterminate (rather than crashing or falsely
+    recommending a downgrade) on edge inputs.
+    """
+    if latest == "unknown" or current == "unknown":
+        return False
+    try:
+        return Version(latest) > Version(current)
+    except InvalidVersion:
+        return False
+
+
+def _fetch_latest_release_tag() -> tuple[str | None, str | None]:
+    """Return (tag, failure_category). Exactly one outbound call, 5 s timeout.
+
+    On success: (tag_name, None).
+    On a documented network/HTTP failure (added in T029/T030): (None, category).
+    On anything else — including a malformed response body — the exception
+    propagates; there is no catch-all (research D-006).
+    """
+    from .authentication.http import open_url
+
+    try:
+        with open_url(
+            GITHUB_API_LATEST,
+            timeout=5,
+            extra_headers={"Accept": "application/vnd.github+json"},
+        ) as resp:
+            payload = json.loads(resp.read().decode("utf-8"))
+            tag = payload.get("tag_name")
+            if not isinstance(tag, str) or not tag:
+                raise ValueError("GitHub API response missing valid tag_name")
+            return tag, None
+    except urllib.error.HTTPError as e:
+        # Order matters: HTTPError is a subclass of URLError.
+        if e.code == 403:
+            return None, (
+                "rate limited (configure ~/.specify/auth.json with a GitHub token)"
+            )
+        return None, f"HTTP {e.code}"
+    except (urllib.error.URLError, OSError):
+        return None, "offline or timeout"
+
+
+# ===== Self Commands =====
+
+self_app = typer.Typer(
+    name="self",
+    help="Manage the specify CLI itself (read-only check and reserved upgrade command).",
+    add_completion=False,
+)
+
+
+@self_app.command("check")
+def self_check() -> None:
+    """Check whether a newer specify-cli release is available. Read-only.
+
+    This command only checks for updates; it does not modify your installation.
+    The reserved (and currently non-destructive) `specify self upgrade` command
+    is the name that a future release will use for actual self-upgrade — its
+    behavior is not implemented in this release and is intentionally out of
+    scope here. See `specify self upgrade --help` for its current status.
+    """
+    installed = _get_installed_version()
+    tag, failure_reason = _fetch_latest_release_tag()
+
+    if tag is None:
+        # Graceful-failure path (FR-008). `failure_reason` is one of the
+        # enumerated strings produced by _fetch_latest_release_tag() — it
+        # never contains a URL, headers, response body, or traceback.
+        assert failure_reason is not None
+        console.print(f"Installed: {installed}")
+        console.print(f"[yellow]Could not check latest release:[/yellow] {failure_reason}")
+        return
+
+    latest_normalized = _normalize_tag(tag)
+
+    if installed == "unknown":
+        # FR-020: surface the latest release and the recovery action even
+        # when the local distribution metadata is unavailable.
+        console.print("Current version could not be determined.")
+        console.print(f"Latest release: {latest_normalized}")
+        console.print("\nTo reinstall:")
+        console.print("  uv tool install specify-cli --force \\")
+        console.print(f"    --from git+https://github.com/github/spec-kit.git@{tag}")
+        return
+
+    if _is_newer(latest_normalized, installed):
+        console.print(f"[green]Update available:[/green] {installed} → {latest_normalized}")
+        console.print("\nTo upgrade:")
+        console.print("  uv tool install specify-cli --force \\")
+        console.print(f"    --from git+https://github.com/github/spec-kit.git@{tag}")
+        return
+
+    # Installed is parseable AND is >= latest → "up to date" (FR-006).
+    # Also reached when the tag is unparseable (InvalidVersion) → _is_newer
+    # returns False, and the up-to-date branch is the safer default per
+    # FR-004 / test T016.
+    console.print(f"[green]Up to date:[/green] {installed}")
+
+
+@self_app.command("upgrade")
+def self_upgrade() -> None:
+    """Reserved command surface for self-upgrade; not implemented in this release.
+
+    This command is a documented non-destructive stub in this release: it
+    performs no outbound network request, no install-method detection, and
+    invokes no installer. It prints a three-line guidance message and exits 0.
+    Actual self-upgrade is planned as follow-up work.
+
+    Use `specify self check` today to see whether a newer release is available
+    and to get a copy-pasteable reinstall command.
+    """
+    console.print("specify self upgrade is not implemented yet.")
+    console.print("Run 'specify self check' to see whether a newer release is available.")
+    console.print("Actual self-upgrade is planned as follow-up work.")
--- a/src/specify_cli/extensions.py
+++ b/src/specify_cli/extensions.py
@@ -25,6 +25,8 @@ import yaml
 from packaging import version as pkg_version
 from packaging.specifiers import SpecifierSet, InvalidSpecifier

+from .catalogs import CatalogEntry as BaseCatalogEntry, CatalogStackBase
+
 _FALLBACK_CORE_COMMAND_NAMES = frozenset({
    "analyze",
    "checklist",
@@ -107,13 +109,8 @@ def normalize_priority(value: Any, default: int = 10) -> int:


@dataclass
-class CatalogEntry:
+class CatalogEntry(BaseCatalogEntry):
    """Represents a single catalog entry in the catalog stack."""
-    url: str
-    name: str
-    priority: int
-    install_allowed: bool
-    description: str = ""


 class ExtensionManifest:
@@ -1666,12 +1663,16 @@ class CommandRegistrar:
        return self.register_commands_for_agent("claude", manifest, extension_dir, project_root)


-class ExtensionCatalog:
+class ExtensionCatalog(CatalogStackBase):
    """Manages extension catalog fetching, caching, and searching."""

    DEFAULT_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json"
    COMMUNITY_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json"
    CACHE_DURATION = 3600  # 1 hour in seconds
+    CONFIG_FILENAME = "extension-catalogs.yml"
+    ENTRY_CLASS = CatalogEntry
+    ERROR_TYPE = ValidationError
+    VALIDATION_ERROR_TYPE = ValidationError

    def __init__(self, project_root: Path):
        """Initialize extension catalog manager.
@@ -1685,27 +1686,6 @@ class ExtensionCatalog:
        self.cache_file = self.cache_dir / "catalog.json"
        self.cache_metadata_file = self.cache_dir / "catalog-metadata.json"

-    def _validate_catalog_url(self, url: str) -> None:
-        """Validate that a catalog URL uses HTTPS (localhost HTTP allowed).
-
-        Args:
-            url: URL to validate
-
-        Raises:
-            ValidationError: If URL is invalid or uses non-HTTPS scheme
-        """
-        from urllib.parse import urlparse
-
-        parsed = urlparse(url)
-        is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
-        if parsed.scheme != "https" and not (parsed.scheme == "http" and is_localhost):
-            raise ValidationError(
-                f"Catalog URL must use HTTPS (got {parsed.scheme}://). "
-                "HTTP is only allowed for localhost."
-            )
-        if not parsed.netloc:
-            raise ValidationError("Catalog URL must be a valid URL with a host.")
-
    def _make_request(self, url: str):
        """Build a urllib Request, adding auth headers when a provider matches.

@@ -1722,81 +1702,6 @@ class ExtensionCatalog:
        from specify_cli.authentication.http import open_url
        return open_url(url, timeout)

-    def _load_catalog_config(self, config_path: Path) -> Optional[List[CatalogEntry]]:
-        """Load catalog stack configuration from a YAML file.
-
-        Args:
-            config_path: Path to extension-catalogs.yml
-
-        Returns:
-            Ordered list of CatalogEntry objects, or None if file doesn't exist.
-
-        Raises:
-            ValidationError: If any catalog entry has an invalid URL,
-                the file cannot be parsed, a priority value is invalid,
-                or the file exists but contains no valid catalog entries
-                (fail-closed for security).
-        """
-        if not config_path.exists():
-            return None
-        try:
-            data = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
-        except (yaml.YAMLError, OSError, UnicodeError) as e:
-            raise ValidationError(
-                f"Failed to read catalog config {config_path}: {e}"
-            )
-        catalogs_data = data.get("catalogs", [])
-        if not catalogs_data:
-            # File exists but has no catalogs key or empty list - fail closed
-            raise ValidationError(
-                f"Catalog config {config_path} exists but contains no 'catalogs' entries. "
-                f"Remove the file to use built-in defaults, or add valid catalog entries."
-            )
-        if not isinstance(catalogs_data, list):
-            raise ValidationError(
-                f"Invalid catalog config: 'catalogs' must be a list, got {type(catalogs_data).__name__}"
-            )
-        entries: List[CatalogEntry] = []
-        skipped_entries: List[int] = []
-        for idx, item in enumerate(catalogs_data):
-            if not isinstance(item, dict):
-                raise ValidationError(
-                    f"Invalid catalog entry at index {idx}: expected a mapping, got {type(item).__name__}"
-                )
-            url = str(item.get("url", "")).strip()
-            if not url:
-                skipped_entries.append(idx)
-                continue
-            self._validate_catalog_url(url)
-            try:
-                priority = int(item.get("priority", idx + 1))
-            except (TypeError, ValueError):
-                raise ValidationError(
-                    f"Invalid priority for catalog '{item.get('name', idx + 1)}': "
-                    f"expected integer, got {item.get('priority')!r}"
-                )
-            raw_install = item.get("install_allowed", False)
-            if isinstance(raw_install, str):
-                install_allowed = raw_install.strip().lower() in ("true", "yes", "1")
-            else:
-                install_allowed = bool(raw_install)
-            entries.append(CatalogEntry(
-                url=url,
-                name=str(item.get("name", f"catalog-{idx + 1}")),
-                priority=priority,
-                install_allowed=install_allowed,
-                description=str(item.get("description", "")),
-            ))
-        entries.sort(key=lambda e: e.priority)
-        if not entries:
-            # All entries were invalid (missing URLs) - fail closed for security
-            raise ValidationError(
-                f"Catalog config {config_path} contains {len(catalogs_data)} entries but none have valid URLs "
-                f"(entries at indices {skipped_entries} were skipped). "
-                f"Each catalog entry must have a 'url' field."
-            )
-        return entries
-
    def get_active_catalogs(self) -> List[CatalogEntry]:
        """Get the ordered list of active catalogs.

@@ -1826,24 +1731,44 @@ class ExtensionCatalog:
                        file=sys.stderr,
                    )
                    self._non_default_catalog_warning_shown = True
-            return [CatalogEntry(url=catalog_url, name="custom", priority=1, install_allowed=True, description="Custom catalog via SPECKIT_CATALOG_URL")]
+            return [
+                self._entry(
+                    url=catalog_url,
+                    name="custom",
+                    priority=1,
+                    install_allowed=True,
+                    description="Custom catalog via SPECKIT_CATALOG_URL",
+                )
+            ]

        # 2. Project-level config overrides all defaults
-        project_config_path = self.project_root / ".specify" / "extension-catalogs.yml"
+        project_config_path = self.project_root / ".specify" / self.CONFIG_FILENAME
        catalogs = self._load_catalog_config(project_config_path)
        if catalogs is not None:
            return catalogs

        # 3. User-level config
-        user_config_path = Path.home() / ".specify" / "extension-catalogs.yml"
+        user_config_path = Path.home() / ".specify" / self.CONFIG_FILENAME
        catalogs = self._load_catalog_config(user_config_path)
        if catalogs is not None:
            return catalogs

        # 4. Built-in default stack
        return [
-            CatalogEntry(url=self.DEFAULT_CATALOG_URL, name="default", priority=1, install_allowed=True, description="Built-in catalog of installable extensions"),
-            CatalogEntry(url=self.COMMUNITY_CATALOG_URL, name="community", priority=2, install_allowed=False, description="Community-contributed extensions (discovery only)"),
+            self._entry(
+                url=self.DEFAULT_CATALOG_URL,
+                name="default",
+                priority=1,
+                install_allowed=True,
+                description="Built-in catalog of installable extensions",
+            ),
+            self._entry(
+                url=self.COMMUNITY_CATALOG_URL,
+                name="community",
+                priority=2,
+                install_allowed=False,
+                description="Community-contributed extensions (discovery only)",
+            ),
        ]

    def get_catalog_url(self) -> str:
--- a/src/specify_cli/integration_state.py
+++ b/src/specify_cli/integration_state.py
@@ -3,6 +3,7 @@
 from __future__ import annotations

 import json
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any

@@ -11,6 +12,67 @@ INTEGRATION_JSON = ".specify/integration.json"
 INTEGRATION_STATE_SCHEMA = 1


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

 from __future__ import annotations

+import re
+from pathlib import Path
+from typing import Any
+
 from ..base import IntegrationOption, SkillsIntegration
+from ..manifest import IntegrationManifest
+
+# Note injected into hook sections so Codex maps dot-notation command
+# names (from extensions.yml) to the hyphenated skill names it uses.
+# Without this, Codex emits ``/speckit.git.commit`` (which does not
+# resolve) instead of ``/speckit-git-commit``.
+_HOOK_COMMAND_NOTE = (
+    "- When constructing slash commands from hook command names, "
+    "replace dots (`.`) with hyphens (`-`). "
+    "For example, `speckit.git.commit` → `/speckit-git-commit`.\n"
+)


 class CodexIntegration(SkillsIntegration):
@@ -54,3 +69,68 @@ class CodexIntegration(SkillsIntegration):
                help="Install as agent skills (default for Codex)",
            ),
        ]
+
+    @staticmethod
+    def _inject_hook_command_note(content: str) -> str:
+        """Insert a dot-to-hyphen note before each hook output instruction.
+
+        Targets the line ``- For each executable hook, output the following``
+        and inserts the note on the line before it, matching its indentation.
+        Skips if the note is already present.
+        """
+        if "replace dots" in content:
+            return content
+
+        def repl(m: re.Match[str]) -> str:
+            indent = m.group(1)
+            instruction = m.group(2)
+            # ``eol`` is empty when the regex matched via ``$`` because the
+            # instruction was the final line of a file with no trailing
+            # newline. Default to ``\n`` so the note never collapses onto
+            # the same line as the instruction.
+            eol = m.group(3) or "\n"
+            return (
+                indent
+                + _HOOK_COMMAND_NOTE.rstrip("\n")
+                + eol
+                + indent
+                + instruction
+                + eol
+            )
+
+        return re.sub(
+            r"(?m)^(\s*)(- For each executable hook, output the following[^\r\n]*)(\r\n|\n|$)",
+            repl,
+            content,
+        )
+
+    def post_process_skill_content(self, content: str) -> str:
+        """Inject the dot-to-hyphen hook command note."""
+        return self._inject_hook_command_note(content)
+
+    def setup(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        parsed_options: dict[str, Any] | None = None,
+        **opts: Any,
+    ) -> list[Path]:
+        """Install Codex skills, then inject the hook command note."""
+        created = super().setup(project_root, manifest, parsed_options, **opts)
+
+        skills_dir = self.skills_dest(project_root).resolve()
+        for path in created:
+            try:
+                path.resolve().relative_to(skills_dir)
+            except ValueError:
+                continue
+            if path.name != "SKILL.md":
+                continue
+
+            content = path.read_bytes().decode("utf-8")
+            updated = self.post_process_skill_content(content)
+            if updated != content:
+                path.write_bytes(updated.encode("utf-8"))
+                self.record_file_in_manifest(path, project_root, manifest)
+
+        return created
--- a/src/specify_cli/presets.py
+++ b/src/specify_cli/presets.py
@@ -1048,9 +1048,9 @@ class PresetManager:
                    short_name = cmd_name
                    if short_name.startswith("speckit."):
                        short_name = short_name[len("speckit."):]
-                    desc = SKILL_DESCRIPTIONS.get(
+                    desc = fm.get("description", "") or SKILL_DESCRIPTIONS.get(
                        short_name.replace(".", "-"),
-                        fm.get("description", f"Command: {short_name}"),
+                        f"Command: {short_name}",
                    )
                    init_opts = load_init_options(self.project_root)
                    selected_ai = init_opts.get("ai") if isinstance(init_opts, dict) else ""
@@ -1314,9 +1314,9 @@ class PresetManager:
                        frontmatter[key] = core_frontmatter[key]

            original_desc = frontmatter.get("description", "")
-            enhanced_desc = SKILL_DESCRIPTIONS.get(
+            enhanced_desc = original_desc or SKILL_DESCRIPTIONS.get(
                short_name,
-                original_desc or f"Spec-kit workflow command: {short_name}",
+                f"Spec-kit workflow command: {short_name}",
            )
            frontmatter = dict(frontmatter)
            frontmatter["description"] = enhanced_desc
@@ -1417,9 +1417,9 @@ class PresetManager:
                    )

                original_desc = frontmatter.get("description", "")
-                enhanced_desc = SKILL_DESCRIPTIONS.get(
+                enhanced_desc = original_desc or SKILL_DESCRIPTIONS.get(
                    short_name,
-                    original_desc or f"Spec-kit workflow command: {short_name}",
+                    f"Spec-kit workflow command: {short_name}",
                )

                frontmatter_data = registrar.build_skill_frontmatter(
--- a/src/specify_cli/workflows/engine.py
+++ b/src/specify_cli/workflows/engine.py
@@ -19,6 +19,10 @@ from typing import Any

 import yaml

+from ..integration_state import (
+    default_integration_key,
+    try_read_integration_json,
+)
 from .base import RunStatus, StepContext, StepResult, StepStatus


@@ -143,6 +147,35 @@ def validate_workflow(definition: WorkflowDefinition) -> list[str]:
                    f"Must be 'string', 'number', or 'boolean'."
                )

+            # Validate the default eagerly so authoring mistakes (e.g. a
+            # default not in the declared enum, or a non-numeric default for
+            # a number input) surface at install/validation time instead of
+            # at workflow-execution time. ``"auto"`` for the integration
+            # input is a runtime-resolved sentinel, so only the
+            # enum-membership check is exempted for that exact case — the
+            # declared type is still enforced (e.g. ``type: number`` paired
+            # with ``default: "auto"`` is still rejected).
+            if "default" in input_def:
+                default_value = input_def["default"]
+                is_auto_integration = (
+                    input_name == "integration" and default_value == "auto"
+                )
+                validation_input_def: dict[str, Any] = input_def
+                if is_auto_integration and "enum" in input_def:
+                    validation_input_def = {
+                        key: value
+                        for key, value in input_def.items()
+                        if key != "enum"
+                    }
+                try:
+                    WorkflowEngine._coerce_input(
+                        input_name, default_value, validation_input_def
+                    )
+                except ValueError as exc:
+                    errors.append(
+                        f"Input {input_name!r} has invalid default: {exc}"
+                    )
+
    # -- Steps ------------------------------------------------------------
    if not isinstance(definition.steps, list):
        errors.append("'steps' must be a list.")
@@ -711,16 +744,73 @@ class WorkflowEngine:
            if not isinstance(input_def, dict):
                continue
            if name in provided:
-                resolved[name] = self._coerce_input(
-                    name, provided[name], input_def
-                )
+                # Resolve sentinels for explicitly-provided values too: a
+                # caller passing ``{"integration": "auto"}`` (which the
+                # workflow prompt advertises as a valid value) must be
+                # treated identically to omitting the input and letting the
+                # default flow through, so dispatch never sees the literal
+                # sentinel.
+                value = self._resolve_default(name, provided[name])
            elif "default" in input_def:
-                resolved[name] = input_def["default"]
+                value = self._resolve_default(name, input_def["default"])
            elif input_def.get("required", False):
                msg = f"Required input {name!r} not provided."
                raise ValueError(msg)
+            else:
+                continue
+
+            # When the ``integration`` default could not be resolved against
+            # project state and falls back to the literal ``"auto"``
+            # sentinel, strip ``enum`` from the input definition before
+            # coercion so a workflow that lists specific integrations in
+            # ``enum`` does not crash at runtime on the sentinel value.
+            # NOTE: only enum-membership is skipped; ``_coerce_input``
+            # still enforces the declared ``type`` against the filtered
+            # definition (``string`` rejects non-strings, ``number`` rejects
+            # bools and uncoercible values, ``boolean`` rejects non-bools),
+            # so ill-typed values still fail fast here.
+            coerce_input_def = input_def
+            if (
+                name == "integration"
+                and value == "auto"
+                and "enum" in input_def
+            ):
+                coerce_input_def = {
+                    key: val
+                    for key, val in input_def.items()
+                    if key != "enum"
+                }
+            resolved[name] = self._coerce_input(name, value, coerce_input_def)
        return resolved

+    def _resolve_default(self, name: str, default: Any) -> Any:
+        """Resolve special default sentinels against project state.
+
+        For the ``integration`` input, ``"auto"`` resolves to the integration
+        recorded in ``.specify/integration.json`` so workflows dispatch to the
+        AI the project was actually initialized with, instead of a hardcoded
+        value baked into the workflow YAML.
+        """
+        if name == "integration" and default == "auto":
+            resolved = self._load_project_integration()
+            if resolved is not None:
+                return resolved
+        return default
+
+    def _load_project_integration(self) -> str | None:
+        """Read the default integration key from ``.specify/integration.json``.
+
+        Delegates parsing and schema validation to
+        :func:`try_read_integration_json` — the same low-level helper used by
+        the CLI — so the engine cannot drift from CLI behavior on the parse
+        path. Returns ``None`` when the file is missing, malformed, or
+        written by a newer CLI; callers fall back to the literal default.
+        """
+        state, error = try_read_integration_json(self.project_root)
+        if state is None or error is not None:
+            return None
+        return default_integration_key(state)
+
    @staticmethod
    def _coerce_input(
        name: str, value: Any, input_def: dict[str, Any]
@@ -730,6 +820,13 @@ class WorkflowEngine:
        enum_values = input_def.get("enum")

        if input_type == "number":
+            # Reject bools explicitly: ``bool`` is a subclass of ``int`` so
+            # ``float(True)`` succeeds and would silently coerce a YAML
+            # authoring mistake like ``type: number`` + ``default: true``
+            # into ``1``. Fail fast instead.
+            if isinstance(value, bool):
+                msg = f"Input {name!r} expected a number, got {value!r}."
+                raise ValueError(msg)
            try:
                value = float(value)
                if value == int(value):
@@ -746,6 +843,17 @@ class WorkflowEngine:
                else:
                    msg = f"Input {name!r} expected a boolean, got {value!r}."
                    raise ValueError(msg)
+            elif not isinstance(value, bool):
+                msg = f"Input {name!r} expected a boolean, got {value!r}."
+                raise ValueError(msg)
+        elif input_type == "string":
+            # Without this, ``type: string`` accepts any Python value
+            # (numbers, lists, dicts) because nothing else rejects it —
+            # YAML ``default: 5`` would slip through. Require an actual
+            # string so authoring mistakes fail at resolve time.
+            if not isinstance(value, str):
+                msg = f"Input {name!r} expected a string, got {value!r}."
+                raise ValueError(msg)

        if enum_values is not None and value not in enum_values:
            msg = (
--- a/tests/integrations/test_cli.py
+++ b/tests/integrations/test_cli.py
@@ -1219,6 +1219,30 @@ class TestIntegrationCatalogDiscoveryCLI:
        assert "contains invalid JSON" in normalized_output
        assert "integration.json" in normalized_output

+    def test_search_rejects_non_utf8_integration_json_before_catalog_lookup(
+        self, tmp_path, monkeypatch
+    ):
+        """A non-UTF8 ``integration.json`` must surface a clear error and
+        avoid falling through to the catalog lookup, mirroring the malformed-JSON
+        case but for the ``UnicodeDecodeError`` branch in ``_read_integration_json``."""
+        project = self._make_project(tmp_path)
+        # 0xFF is invalid as the leading byte of any UTF-8 sequence, so
+        # ``Path.read_text(encoding="utf-8")`` raises ``UnicodeDecodeError``.
+        (project / ".specify" / "integration.json").write_bytes(b"\xff\xfe\x00\x00")
+
+        from specify_cli.integrations.catalog import IntegrationCatalog
+
+        def fail_search(self, **kwargs):
+            raise AssertionError("catalog search should not be called")
+
+        monkeypatch.setattr(IntegrationCatalog, "search", fail_search)
+
+        result = self._invoke(["integration", "search"], project)
+        normalized_output = _normalize_cli_output(result.output)
+        assert result.exit_code == 1
+        assert "not valid UTF-8" in normalized_output
+        assert "integration.json" in normalized_output
+
    def test_search_filters_by_tag(self, tmp_path, monkeypatch):
        project = self._make_project(tmp_path)
        self._patch_catalog(monkeypatch)
--- a/tests/integrations/test_integration_claude.py
+++ b/tests/integrations/test_integration_claude.py
@@ -487,13 +487,15 @@ class TestClaudeDisableModelInvocation:
        assert "disable-model-invocation" not in fm
        assert "user-invocable" not in fm

-    def test_non_claude_post_process_is_identity(self, tmp_path):
-        """Non-Claude integrations should not modify skill content."""
-        codex = get_integration("codex")
-        if codex is None:
-            return  # codex not registered in this build
+    def test_skills_default_post_process_is_identity(self, tmp_path):
+        """SkillsIntegration agents without an override leave content unchanged."""
+        # ``agy`` is a plain SkillsIntegration with no post-process override,
+        # so it stands in for the base-class default behavior.
+        agy = get_integration("agy")
+        if agy is None:
+            return  # agy not registered in this build
        content = "---\nname: test\n---\nBody"
-        assert codex.post_process_skill_content(content) == content
+        assert agy.post_process_skill_content(content) == content


 class TestClaudeHookCommandNote:
--- a/tests/integrations/test_integration_codex.py
+++ b/tests/integrations/test_integration_codex.py
@@ -1,5 +1,8 @@
 """Tests for CodexIntegration."""

+from specify_cli.integrations import get_integration
+from specify_cli.integrations.manifest import IntegrationManifest
+
 from .test_integration_base_skills import SkillsIntegrationTests


@@ -25,3 +28,89 @@ class TestCodexAutoPromote:

        assert result.exit_code == 0, f"init --ai codex failed: {result.output}"
        assert (target / ".agents" / "skills" / "speckit-plan" / "SKILL.md").exists()
+
+
+class TestCodexHookCommandNote:
+    """Verify dot-to-hyphen normalization note is injected in hook sections.
+
+    Hook commands in ``extensions.yml`` use dotted ids like
+    ``speckit.git.commit`` but Codex skills are named with hyphens
+    (``speckit-git-commit``). Without this note, Codex emits
+    ``/speckit.git.commit``, which does not resolve.
+    """
+
+    def test_hook_note_injected_in_skills_with_hooks(self, tmp_path):
+        """Skills that have hook sections should get the normalization note."""
+        i = get_integration("codex")
+        m = IntegrationManifest("codex", tmp_path)
+        i.setup(tmp_path, m, script_type="sh")
+        specify_skill = tmp_path / ".agents/skills/speckit-specify/SKILL.md"
+        assert specify_skill.exists()
+        content = specify_skill.read_text(encoding="utf-8")
+        assert "replace dots" in content, (
+            "speckit-specify should have dot-to-hyphen hook note"
+        )
+
+    def test_hook_note_not_in_skills_without_hooks(self):
+        """Skills without hook sections should not get the note."""
+        from specify_cli.integrations.codex import CodexIntegration
+
+        content = "---\nname: test\ndescription: test\n---\n\nNo hooks here.\n"
+        result = CodexIntegration._inject_hook_command_note(content)
+        assert "replace dots" not in result
+
+    def test_hook_note_idempotent(self):
+        """Injecting the note twice should not duplicate it."""
+        from specify_cli.integrations.codex import CodexIntegration
+
+        content = (
+            "---\nname: test\n---\n\n"
+            "- For each executable hook, output the following based on its flag:\n"
+        )
+        once = CodexIntegration._inject_hook_command_note(content)
+        twice = CodexIntegration._inject_hook_command_note(once)
+        assert once == twice, "Hook note injection should be idempotent"
+
+    def test_hook_note_preserves_indentation(self):
+        """The injected note should match the indentation of the target line."""
+        from specify_cli.integrations.codex import CodexIntegration
+
+        content = (
+            "---\nname: test\n---\n\n"
+            "   - For each executable hook, output the following\n"
+        )
+        result = CodexIntegration._inject_hook_command_note(content)
+        lines = result.splitlines()
+        note_line = [l for l in lines if "replace dots" in l][0]
+        assert note_line.startswith("   "), "Note should preserve indentation"
+
+    def test_hook_note_when_instruction_is_final_line_without_newline(self):
+        """Note must not collapse onto the instruction line when the file
+        ends without a trailing newline and the preceding line is not blank.
+        """
+        from specify_cli.integrations.codex import CodexIntegration
+
+        # No blank line before the instruction and no trailing newline:
+        # this is the case where the captured ``eol`` is empty and the
+        # captured indent is also empty, so a missing line separator would
+        # cause the note and instruction to collapse onto one line.
+        content = (
+            "---\nname: test\n---\n"
+            "Body line\n"
+            "- For each executable hook, output the following"
+        )
+        result = CodexIntegration._inject_hook_command_note(content)
+        lines = result.splitlines()
+        note_line_idx = next(
+            i for i, l in enumerate(lines) if "replace dots" in l
+        )
+        instruction_line_idx = next(
+            i for i, l in enumerate(lines)
+            if l.lstrip().startswith("- For each executable hook")
+        )
+        assert note_line_idx < instruction_line_idx, (
+            "Note must appear before the instruction"
+        )
+        assert "For each executable hook" not in lines[note_line_idx], (
+            "Note and instruction must not be on the same line"
+        )
--- a/tests/integrations/test_integration_subcommand.py
+++ b/tests/integrations/test_integration_subcommand.py
@@ -163,7 +163,30 @@ class TestIntegrationInstall:
        assert "already installed" in result.output
        normalized = " ".join(result.output.split())
        assert "specify integration upgrade copilot" in normalized
-        assert "specify integration uninstall copilot" in normalized
+        assert "already the default integration" in normalized
+        assert "No files were changed" in normalized
+        assert "specify integration uninstall copilot" not in normalized
+
+    def test_install_already_installed_non_default_guides_use(self, tmp_path):
+        project = _init_project(tmp_path, "claude")
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            install = runner.invoke(app, [
+                "integration", "install", "codex",
+                "--script", "sh",
+            ], catch_exceptions=False)
+            assert install.exit_code == 0, install.output
+
+            result = runner.invoke(app, ["integration", "install", "codex"])
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0
+        normalized = " ".join(result.output.split())
+        assert "already installed" in normalized
+        assert "specify integration use codex" in normalized
+        assert "specify integration upgrade codex" in normalized
+        assert "specify integration uninstall codex" not in normalized

    def test_install_different_when_one_exists(self, tmp_path):
        project = _init_project(tmp_path, "copilot")
@@ -176,7 +199,11 @@ class TestIntegrationInstall:
        assert result.exit_code != 0
        assert "Installed integrations: copilot" in result.output
        assert "Default integration: copilot" in result.output
-        assert "--force" in result.output
+        normalized = " ".join(result.output.split())
+        assert "To replace the default integration" in normalized
+        assert "specify integration switch claude" in normalized
+        assert "To install 'claude' alongside" in normalized
+        assert "retry the same install command with --force" in normalized

    def test_install_multi_safe_integration(self, tmp_path):
        project = _init_project(tmp_path, "claude")
@@ -261,7 +288,11 @@ class TestIntegrationInstall:
        assert result.exit_code != 0
        assert "Installed integrations: copilot" in result.output
        assert "multi-install safe" in result.output
-        assert "--force" in result.output
+        normalized = " ".join(result.output.split())
+        assert "To replace the default integration" in normalized
+        assert "specify integration switch claude" in normalized
+        assert "To install 'claude' alongside" in normalized
+        assert "retry the same install command with --force" in normalized

    def test_install_multi_unsafe_allowed_with_force(self, tmp_path):
        project = _init_project(tmp_path, "copilot")
--- a/tests/test_authentication.py
+++ b/tests/test_authentication.py
@@ -832,7 +832,7 @@ class TestFetchLatestReleaseTagDelegation:

    def test_gh_token_forwarded_when_configured(self, monkeypatch):
        from unittest.mock import MagicMock, patch
-        from specify_cli import _fetch_latest_release_tag
+        from specify_cli._version import _fetch_latest_release_tag
        monkeypatch.setenv("GH_TOKEN", "forwarded-sentinel")
        self._set_config(monkeypatch, [_github_entry()])
        captured, side_effect = self._capture_request()
@@ -843,7 +843,7 @@ class TestFetchLatestReleaseTagDelegation:

    def test_no_config_means_no_auth(self, monkeypatch):
        from unittest.mock import patch
-        from specify_cli import _fetch_latest_release_tag
+        from specify_cli._version import _fetch_latest_release_tag
        self._set_config(monkeypatch, [])
        captured, side_effect = self._capture_request()
        with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect):
@@ -852,7 +852,7 @@ class TestFetchLatestReleaseTagDelegation:

    def test_accept_header_present(self, monkeypatch):
        from unittest.mock import patch
-        from specify_cli import _fetch_latest_release_tag
+        from specify_cli._version import _fetch_latest_release_tag
        self._set_config(monkeypatch, [])
        captured, side_effect = self._capture_request()
        with patch("specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect):
--- a/tests/test_cli_version.py
+++ b/tests/test_cli_version.py
@@ -1,5 +1,6 @@
-"""Tests for the --version CLI flag."""
+"""Tests for CLI version reporting."""

+import json
 from unittest.mock import patch

 from typer.testing import CliRunner
@@ -33,3 +34,46 @@ class TestVersionFlag:
            result = runner.invoke(app, ["--version", "init"])
        assert result.exit_code == 0
        assert "specify 0.7.2" in result.output
+
+
+class TestVersionCommand:
+    """Test the `specify version` subcommand."""
+
+    def test_version_features_text(self):
+        """specify version --features prints local capability flags."""
+        with patch("specify_cli.get_speckit_version", return_value="1.2.3"):
+            result = runner.invoke(app, ["version", "--features"])
+
+        assert result.exit_code == 0
+        assert "Spec Kit CLI: 1.2.3" in result.output
+        assert "Features:" in result.output
+        assert "- controlled multi install integrations: yes" in result.output
+        assert "- integration use command: yes" in result.output
+        assert "- self check command: yes" in result.output
+
+    def test_version_features_json(self):
+        """specify version --features --json prints machine-readable capabilities."""
+        with patch("specify_cli.get_speckit_version", return_value="1.2.3"):
+            result = runner.invoke(app, ["version", "--features", "--json"])
+
+        assert result.exit_code == 0
+        payload = json.loads(result.output)
+        assert payload == {
+            "version": "1.2.3",
+            "features": {
+                "controlled_multi_install_integrations": True,
+                "integration_use_command": True,
+                "multi_install_safe_registry_metadata": True,
+                "integration_upgrade_command": True,
+                "self_check_command": True,
+                "workflow_catalog": True,
+                "bundled_templates": True,
+            },
+        }
+
+    def test_version_json_requires_features(self):
+        """specify version --json is rejected until a JSON surface exists."""
+        result = runner.invoke(app, ["version", "--json"])
+
+        assert result.exit_code != 0
+        assert "--json requires --features" in result.output
--- a/tests/test_extensions.py
+++ b/tests/test_extensions.py
@@ -1846,7 +1846,7 @@ Run {SCRIPT}
        registrar = CommandRegistrar()
        from specify_cli.extensions import ExtensionManifest
        manifest = ExtensionManifest(ext_dir / "extension.yml")
-        registered = registrar.register_commands_for_agent("codex", manifest, ext_dir, project_dir)
+        registrar.register_commands_for_agent("codex", manifest, ext_dir, project_dir)

        skill_subdir = skills_dir / "speckit-cleanup-ext-run"
        assert skill_subdir.exists(), "Skill subdirectory should exist after registration"
@@ -2580,7 +2580,8 @@ class TestExtensionCatalog:
    def test_download_extension_sends_auth_header(self, temp_dir, monkeypatch):
        """download_extension passes Authorization header when a provider is configured."""
        from unittest.mock import patch, MagicMock
-        import zipfile, io
+        import zipfile
+        import io

        monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")
        self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")
@@ -2854,6 +2855,110 @@ class TestCatalogStack:
        assert len(entries) == 1
        assert entries[0].url == "http://localhost:8000/catalog.json"

+    @pytest.mark.parametrize(
+        "config_content", ["[]\n", "false\n", "0\n", "''\n", "- item\n"]
+    )
+    def test_load_catalog_config_rejects_non_mapping_roots(
+        self, temp_dir, config_content
+    ):
+        """Malformed roots raise ValidationError, not fallback or AttributeError."""
+        project_dir = self._make_project(temp_dir)
+        config_path = project_dir / ".specify" / "extension-catalogs.yml"
+        config_path.write_text(config_content, encoding="utf-8")
+
+        catalog = ExtensionCatalog(project_dir)
+
+        with pytest.raises(
+            ValidationError, match="expected a YAML mapping at the root"
+        ) as exc_info:
+            catalog.get_active_catalogs()
+        assert str(config_path) in str(exc_info.value)
+
+    def test_load_catalog_config_rejects_boolean_priority(self, temp_dir):
+        """Boolean priorities are rejected instead of being coerced to 1 or 0."""
+        import yaml as yaml_module
+
+        project_dir = self._make_project(temp_dir)
+        config_path = project_dir / ".specify" / "extension-catalogs.yml"
+        config_path.write_text(
+            yaml_module.dump(
+                {
+                    "catalogs": [
+                        {
+                            "name": "bad-priority",
+                            "url": "https://example.com/catalog.json",
+                            "priority": True,
+                        }
+                    ]
+                }
+            ),
+            encoding="utf-8",
+        )
+
+        catalog = ExtensionCatalog(project_dir)
+
+        with pytest.raises(
+            ValidationError, match="Invalid priority|expected integer"
+        ) as exc_info:
+            catalog.get_active_catalogs()
+        assert str(config_path) in str(exc_info.value)
+
+    def test_load_catalog_config_defaults_blank_names(self, temp_dir):
+        """Blank and null names normalize by valid catalog order."""
+        import yaml as yaml_module
+
+        project_dir = self._make_project(temp_dir)
+        config_path = project_dir / ".specify" / "extension-catalogs.yml"
+        config_path.write_text(
+            yaml_module.dump(
+                {
+                    "catalogs": [
+                        {"name": "skipped", "url": "   "},
+                        {"name": None, "url": "https://one.example.com/catalog.json"},
+                        {"name": "   ", "url": "https://two.example.com/catalog.json"},
+                    ]
+                }
+            ),
+            encoding="utf-8",
+        )
+
+        catalog = ExtensionCatalog(project_dir)
+
+        assert [entry.name for entry in catalog.get_active_catalogs()] == [
+            "catalog-1",
+            "catalog-2",
+        ]
+
+    @pytest.mark.parametrize(
+        ("url", "expected_detail"),
+        [
+            ("relative/catalog.json", "HTTPS"),
+            ("https:///no-host", "valid URL with a host"),
+        ],
+    )
+    def test_load_catalog_config_invalid_url_includes_context(
+        self, temp_dir, url, expected_detail
+    ):
+        """Invalid catalog URLs include the config path and entry index."""
+        import yaml as yaml_module
+
+        project_dir = self._make_project(temp_dir)
+        config_path = project_dir / ".specify" / "extension-catalogs.yml"
+        config_path.write_text(
+            yaml_module.dump({"catalogs": [{"name": "bad", "url": url}]}),
+            encoding="utf-8",
+        )
+
+        catalog = ExtensionCatalog(project_dir)
+
+        with pytest.raises(ValidationError) as exc_info:
+            catalog.get_active_catalogs()
+        message = str(exc_info.value)
+        assert "Invalid catalog URL" in message
+        assert str(config_path) in message
+        assert "index 0" in message
+        assert expected_detail in message
+
    # --- Merge conflict resolution ---

    def test_merge_conflict_higher_priority_wins(self, temp_dir):
--- a/tests/test_presets.py
+++ b/tests/test_presets.py
@@ -2266,6 +2266,37 @@ class TestPresetSkills:
        )
        return skill_dir

+    def _create_command_preset(self, temp_dir, preset_id, command_name, description, body):
+        preset_dir = temp_dir / preset_id
+        preset_dir.mkdir()
+        (preset_dir / "commands").mkdir()
+        command_file = f"{command_name}.md"
+        (preset_dir / "commands" / command_file).write_text(
+            f"---\ndescription: {description}\n---\n\n{body}\n"
+        )
+        manifest_data = {
+            "schema_version": "1.0",
+            "preset": {
+                "id": preset_id,
+                "name": preset_id,
+                "version": "1.0.0",
+                "description": "Test",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "templates": [
+                    {
+                        "type": "command",
+                        "name": command_name,
+                        "file": f"commands/{command_file}",
+                    }
+                ]
+            },
+        }
+        with open(preset_dir / "preset.yml", "w") as f:
+            yaml.dump(manifest_data, f)
+        return preset_dir
+
    def test_skill_overridden_on_preset_install(self, project_dir, temp_dir):
        """When --ai-skills was used, a preset command override should update the skill."""
        # Simulate --ai-skills having been used: write init-options + create skill
@@ -2290,6 +2321,120 @@ class TestPresetSkills:
        metadata = manager.registry.get("self-test")
        assert "speckit-specify" in metadata.get("registered_skills", [])

+    def test_core_command_override_skill_uses_preset_command_description(self, project_dir, temp_dir):
+        """Preset skill overrides for core commands should keep preset frontmatter descriptions."""
+        self._write_init_options(project_dir, ai="claude")
+        skills_dir = project_dir / ".claude" / "skills"
+        self._create_skill(skills_dir, "speckit-taskstoissues")
+
+        preset_dir = temp_dir / "taskstoissues-description"
+        preset_dir.mkdir()
+        (preset_dir / "commands").mkdir()
+        (preset_dir / "commands" / "speckit.repro.taskstoissues.md").write_text(
+            "---\n"
+            "description: COMMAND-FRONTMATTER-DESCRIPTION\n"
+            "---\n\n"
+            "# Repro command body\n"
+        )
+        manifest_data = {
+            "schema_version": "1.0",
+            "preset": {
+                "id": "taskstoissues-description",
+                "name": "Taskstoissues Description",
+                "version": "1.0.0",
+                "description": "Test",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "templates": [
+                    {
+                        "type": "command",
+                        "name": "speckit.taskstoissues",
+                        "file": "commands/speckit.repro.taskstoissues.md",
+                        "description": "MANIFEST-DESCRIPTION",
+                        "replaces": "speckit.taskstoissues",
+                        "strategy": "replace",
+                    }
+                ]
+            },
+        }
+        with open(preset_dir / "preset.yml", "w") as f:
+            yaml.dump(manifest_data, f)
+
+        manager = PresetManager(project_dir)
+        manager.install_from_directory(preset_dir, "0.1.5")
+
+        skill_file = skills_dir / "speckit-taskstoissues" / "SKILL.md"
+        content = skill_file.read_text()
+        assert "description: COMMAND-FRONTMATTER-DESCRIPTION" in content
+        assert "Convert tasks from tasks.md into GitHub issues." not in content
+        assert "source: preset:taskstoissues-description" in content
+
+    def test_core_skill_restore_uses_core_command_description(self, project_dir, temp_dir):
+        """Core skill restore should keep core command frontmatter descriptions."""
+        self._write_init_options(project_dir, ai="claude")
+        skills_dir = project_dir / ".claude" / "skills"
+        self._create_skill(skills_dir, "speckit-taskstoissues")
+
+        core_cmds = project_dir / ".specify" / "templates" / "commands"
+        core_cmds.mkdir(parents=True, exist_ok=True)
+        (core_cmds / "taskstoissues.md").write_text(
+            "---\n"
+            "description: CORE-FRONTMATTER-DESCRIPTION\n"
+            "---\n\n"
+            "core taskstoissues body\n"
+        )
+        preset_dir = self._create_command_preset(
+            temp_dir,
+            "taskstoissues-restore",
+            "speckit.taskstoissues",
+            "PRESET-FRONTMATTER-DESCRIPTION",
+            "preset taskstoissues body\n",
+        )
+
+        manager = PresetManager(project_dir)
+        manager.install_from_directory(preset_dir, "0.1.5")
+        manager.remove("taskstoissues-restore")
+
+        skill_file = skills_dir / "speckit-taskstoissues" / "SKILL.md"
+        content = skill_file.read_text()
+        assert "description: CORE-FRONTMATTER-DESCRIPTION" in content
+        assert "Convert tasks from tasks.md into GitHub issues." not in content
+        assert "source: templates/commands/taskstoissues.md" in content
+        assert "core taskstoissues body" in content
+
+    def test_override_skill_reconcile_uses_override_command_description(self, project_dir, temp_dir):
+        """Override skill reconciliation should keep override frontmatter descriptions."""
+        self._write_init_options(project_dir, ai="claude")
+        skills_dir = project_dir / ".claude" / "skills"
+        self._create_skill(skills_dir, "speckit-taskstoissues")
+
+        overrides_dir = project_dir / ".specify" / "templates" / "overrides"
+        overrides_dir.mkdir(parents=True)
+        (overrides_dir / "speckit.taskstoissues.md").write_text(
+            "---\n"
+            "description: OVERRIDE-FRONTMATTER-DESCRIPTION\n"
+            "---\n\n"
+            "override taskstoissues body\n"
+        )
+        preset_dir = self._create_command_preset(
+            temp_dir,
+            "taskstoissues-reconcile",
+            "speckit.taskstoissues",
+            "PRESET-FRONTMATTER-DESCRIPTION",
+            "preset taskstoissues body\n",
+        )
+
+        manager = PresetManager(project_dir)
+        manager.install_from_directory(preset_dir, "0.1.5")
+
+        skill_file = skills_dir / "speckit-taskstoissues" / "SKILL.md"
+        content = skill_file.read_text()
+        assert "description: OVERRIDE-FRONTMATTER-DESCRIPTION" in content
+        assert "Convert tasks from tasks.md into GitHub issues." not in content
+        assert "source: override:speckit.taskstoissues" in content
+        assert "override taskstoissues body" in content
+
    def test_skill_not_updated_when_ai_skills_disabled(self, project_dir, temp_dir):
        """When --ai-skills was NOT used, preset install should not touch skills."""
        self._write_init_options(project_dir, ai="qwen", ai_skills=False)
--- a/tests/test_timestamp_branches.py
+++ b/tests/test_timestamp_branches.py
@@ -115,6 +115,36 @@ def ext_ps_git_repo(tmp_path: Path) -> Path:
    return tmp_path


+@pytest.fixture
+def ps_git_repo(tmp_path: Path) -> Path:
+    """Create a temp git repo with PowerShell scripts and a BOM-prefixed template."""
+    subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True)
+    subprocess.run(
+        ["git", "config", "user.email", "test@example.com"], cwd=tmp_path, check=True
+    )
+    subprocess.run(
+        ["git", "config", "user.name", "Test User"], cwd=tmp_path, check=True
+    )
+    subprocess.run(
+        ["git", "commit", "--allow-empty", "-m", "init", "-q"],
+        cwd=tmp_path,
+        check=True,
+    )
+    ps_dir = tmp_path / "scripts" / "powershell"
+    ps_dir.mkdir(parents=True)
+    shutil.copy(CREATE_FEATURE_PS, ps_dir / "create-new-feature.ps1")
+    common_ps = PROJECT_ROOT / "scripts" / "powershell" / "common.ps1"
+    shutil.copy(common_ps, ps_dir / "common.ps1")
+    templates_dir = tmp_path / ".specify" / "templates"
+    templates_dir.mkdir(parents=True)
+    # Write a BOM-prefixed template to ensure the WriteAllText fix is actually exercised.
+    # If WriteAllText regresses, the output file will contain the BOM.
+    bom = b"\xef\xbb\xbf"
+    template_content = "# Feature Spec\n\nDescribe the feature here.\n"
+    (templates_dir / "spec-template.md").write_bytes(bom + template_content.encode("utf-8"))
+    return tmp_path
+
+
@pytest.fixture
 def no_git_dir(tmp_path: Path) -> Path:
    """Create a temp directory without git, but with scripts."""
@@ -381,6 +411,7 @@ class TestGetFeaturePathsSinglePrefix:
        assert result.returncode == 0, result.stderr
        assert result.stdout.strip() == str(tmp_path / "specs" / "001-target-spec")

+
    @pytest.mark.skipif(not _has_pwsh(), reason="pwsh not installed")
    def test_ps_specify_feature_prefixed_resolves_by_prefix(self, git_repo: Path):
        """PowerShell Get-FeaturePathsEnv: same prefix stripping as bash."""
@@ -650,6 +681,45 @@ class TestAllowExistingBranchPowerShell:
        assert "$switchBranchError = git checkout -q $branchName 2>&1 | Out-String" in contents
        assert "exists but could not be checked out.`n$($switchBranchError.Trim())" in contents

+    @pytest.mark.skipif(not _has_pwsh(), reason="pwsh not installed")
+    @pytest.mark.skipif(
+        os.name != "nt" or shutil.which("powershell.exe") is None,
+        reason="Windows PowerShell not installed",
+    )
+    def test_ps_spec_file_written_without_bom(self, ps_git_repo: Path):
+        """spec.md generated from a BOM-prefixed template must not contain a UTF-8 BOM."""
+        result = subprocess.run(
+            [
+                "powershell.exe",
+                "-NoProfile",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                str(CREATE_FEATURE_PS),
+                "-ShortName",
+                "bom-check",
+                "BOM check feature",
+            ],
+            cwd=ps_git_repo,
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 0, result.stderr
+
+        spec_file = next((ps_git_repo / "specs").rglob("spec.md"), None)
+        assert spec_file is not None, (
+            f"spec.md was not created.\nstdout: {result.stdout}\nstderr: {result.stderr}"
+        )
+
+        raw = spec_file.read_bytes()
+        assert not raw.startswith(b"\xef\xbb\xbf"), (
+            f"spec.md must not start with a UTF-8 BOM — got first 3 bytes: {raw[:3]!r}"
+        )
+        # Verify template content was copied (not just an empty New-Item fallback)
+        assert "Feature Spec" in raw.decode("utf-8"), (
+            "spec.md does not contain template content — WriteAllText path was not exercised"
+        )
+

 class TestGitExtensionParity:
    def test_bash_extension_surfaces_checkout_errors(self):
@@ -904,30 +974,6 @@ def run_ps_script(cwd: Path, *args: str) -> subprocess.CompletedProcess:
    return subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)


-@pytest.fixture
-def ps_git_repo(tmp_path: Path) -> Path:
-    """Create a temp git repo with PowerShell scripts and .specify dir."""
-    subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True)
-    subprocess.run(
-        ["git", "config", "user.email", "test@example.com"], cwd=tmp_path, check=True
-    )
-    subprocess.run(
-        ["git", "config", "user.name", "Test User"], cwd=tmp_path, check=True
-    )
-    subprocess.run(
-        ["git", "commit", "--allow-empty", "-m", "init", "-q"],
-        cwd=tmp_path,
-        check=True,
-    )
-    ps_dir = tmp_path / "scripts" / "powershell"
-    ps_dir.mkdir(parents=True)
-    shutil.copy(CREATE_FEATURE_PS, ps_dir / "create-new-feature.ps1")
-    common_ps = PROJECT_ROOT / "scripts" / "powershell" / "common.ps1"
-    shutil.copy(common_ps, ps_dir / "common.ps1")
-    (tmp_path / ".specify" / "templates").mkdir(parents=True)
-    return tmp_path
-
-
@pytest.mark.skipif(not _has_pwsh(), reason="pwsh not available")
 class TestPowerShellDryRun:
    def test_ps_dry_run_outputs_name(self, ps_git_repo: Path):
@@ -1259,13 +1305,13 @@ class TestFeatureDirectoryResolution:
            pytest.fail("FEATURE_DIR not found in PowerShell output")


+
 # ── Description Quoting Tests (issue #2339) ──────────────────────────────────


@requires_bash
 class TestDescriptionQuoting:
    """Descriptions with quotes, apostrophes, and backslashes must not break the script.
-
    Regression tests for https://github.com/github/spec-kit/issues/2339
    """

@@ -1273,9 +1319,9 @@ class TestDescriptionQuoting:
        "description",
        [
            "Add user's profile page",
-            "Fix the \"login\" bug",
+            'Fix the "login" bug',
            "Handle path\\with\\backslashes",
-            "It's a \"complex\" feature\\here",
+            'It\'s a "complex" feature\\here',
        ],
        ids=["apostrophe", "double-quotes", "backslashes", "mixed"],
    )
@@ -1290,16 +1336,22 @@ class TestDescriptionQuoting:
        "description",
        [
            "Add user's profile page",
-            "Fix the \"login\" bug",
+            'Fix the "login" bug',
            "Handle path\\with\\backslashes",
-            "It's a \"complex\" feature\\here",
+            'It\'s a "complex" feature\\here',
        ],
        ids=["apostrophe", "double-quotes", "backslashes", "mixed"],
    )
    def test_ext_script_handles_special_chars(self, ext_git_repo: Path, description: str):
        """Extension create-new-feature.sh succeeds with special characters in description."""
        script = (
-            ext_git_repo / ".specify" / "extensions" / "git" / "scripts" / "bash" / "create-new-feature.sh"
+            ext_git_repo
+            / ".specify"
+            / "extensions"
+            / "git"
+            / "scripts"
+            / "bash"
+            / "create-new-feature.sh"
        )
        result = subprocess.run(
            ["bash", str(script), "--dry-run", "--short-name", "feat", description],
@@ -1321,3 +1373,4 @@ class TestDescriptionQuoting:
        """Plain description without special characters continues to work."""
        result = run_script(git_repo, "--dry-run", "--short-name", "feat", "Add login feature")
        assert result.returncode == 0, result.stderr
+        
--- a/tests/test_upgrade.py
+++ b/tests/test_upgrade.py
@@ -16,12 +16,12 @@ from unittest.mock import MagicMock, patch
 import pytest
 from typer.testing import CliRunner

-from specify_cli import (
-    _get_installed_version,
+from specify_cli import app
+from specify_cli._version import (
    _fetch_latest_release_tag,
+    _get_installed_version,
    _is_newer,
    _normalize_tag,
-    app,
 )
 from tests.conftest import strip_ansi

@@ -149,7 +149,7 @@ class TestNormalizeTag:

 class TestUserStory1:
    def test_newer_available_prints_update_and_install_command(self):
-        with patch("specify_cli._get_installed_version", return_value="0.7.4"), patch(
+        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"}),
        ):
@@ -162,7 +162,7 @@ class TestUserStory1:
        assert "git+https://github.com/github/spec-kit.git@v0.9.0" in output

    def test_up_to_date_prints_current_only(self):
-        with patch("specify_cli._get_installed_version", return_value="0.9.0"), patch(
+        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"}),
        ):
@@ -174,7 +174,7 @@ class TestUserStory1:
        assert "git+https://" not in output

    def test_dev_build_ahead_of_release_is_up_to_date(self):
-        with patch("specify_cli._get_installed_version", return_value="0.7.5.dev0"), patch(
+        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"}),
        ):
@@ -185,7 +185,7 @@ class TestUserStory1:
        assert "Up to date" in output

    def test_unknown_installed_still_prints_latest_and_reinstall(self):
-        with patch("specify_cli._get_installed_version", return_value="unknown"), patch(
+        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"}),
        ):
@@ -197,7 +197,7 @@ class TestUserStory1:
        assert "git+https://github.com/github/spec-kit.git@v0.7.4" in output

    def test_unparseable_tag_routes_to_indeterminate(self):
-        with patch("specify_cli._get_installed_version", return_value="0.7.4"), patch(
+        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"}),
        ):
@@ -269,7 +269,7 @@ class TestUserStory2:
    def test_failure_prints_installed_plus_one_line_reason(
        self, expected_reason, side_effect
    ):
-        with patch("specify_cli._get_installed_version", return_value="0.7.4"), patch(
+        with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
            "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
        ):
            result = runner.invoke(app, ["self", "check"])
@@ -283,7 +283,7 @@ class TestUserStory2:

    @pytest.mark.parametrize("_expected_reason, side_effect", _FAILURE_CASES)
    def test_failure_exits_zero(self, _expected_reason, side_effect):
-        with patch("specify_cli._get_installed_version", return_value="0.7.4"), patch(
+        with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
            "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
        ):
            result = runner.invoke(app, ["self", "check"])
@@ -293,7 +293,7 @@ class TestUserStory2:
    def test_failure_output_contains_no_traceback_no_url(
        self, _expected_reason, side_effect
    ):
-        with patch("specify_cli._get_installed_version", return_value="0.7.4"), patch(
+        with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
            "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
        ):
            result = runner.invoke(app, ["self", "check"])
@@ -390,7 +390,7 @@ class TestUserStory3:
    ):
        monkeypatch.setenv("GH_TOKEN", SENTINEL_GH_TOKEN)
        monkeypatch.delenv("GITHUB_TOKEN", raising=False)
-        with patch("specify_cli._get_installed_version", return_value="0.7.4"), patch(
+        with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
            "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
        ):
            result = runner.invoke(app, ["self", "check"])
@@ -403,7 +403,7 @@ class TestUserStory3:
    ):
        monkeypatch.delenv("GH_TOKEN", raising=False)
        monkeypatch.setenv("GITHUB_TOKEN", SENTINEL_GITHUB_TOKEN)
-        with patch("specify_cli._get_installed_version", return_value="0.7.4"), patch(
+        with patch("specify_cli._version._get_installed_version", return_value="0.7.4"), patch(
            "specify_cli.authentication.http.urllib.request.urlopen", side_effect=side_effect
        ):
            result = runner.invoke(app, ["self", "check"])
--- a/tests/test_version_imports.py
+++ b/tests/test_version_imports.py
@@ -0,0 +1,41 @@
+"""Regression guard: version symbols must remain importable from specify_cli."""
+from specify_cli import (
+    GITHUB_API_LATEST,
+    self_check,
+    self_upgrade,
+)
+
+
+def test_version_symbols_importable():
+    assert isinstance(GITHUB_API_LATEST, str)
+    assert GITHUB_API_LATEST.startswith("https://")
+    assert callable(self_check)
+    assert callable(self_upgrade)
+
+
+def test_version_symbols_available_from_star_import():
+    namespace = {}
+    exec("from specify_cli import *", namespace)
+
+    for symbol in ("GITHUB_API_LATEST", "self_check", "self_upgrade"):
+        assert symbol in namespace
+
+
+def test_version_module_symbols_directly_importable():
+    from specify_cli._version import (
+        GITHUB_API_LATEST,
+        _fetch_latest_release_tag,
+        _get_installed_version,
+        _is_newer,
+        _normalize_tag,
+        self_app,
+        self_check,
+        self_upgrade,
+    )
+    assert callable(_get_installed_version)
+    assert callable(_normalize_tag)
+    assert callable(_is_newer)
+    assert callable(_fetch_latest_release_tag)
+    assert callable(self_check)
+    assert callable(self_upgrade)
+    assert self_app is not None
--- a/tests/test_workflows.py
+++ b/tests/test_workflows.py
@@ -1495,6 +1495,394 @@ steps:
        with pytest.raises(ValueError, match="Required input"):
            engine.execute(definition, {})

+    def test_integration_auto_default_uses_project_integration(self, project_dir):
+        """`integration: auto` should resolve to .specify/integration.json's integration."""
+        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
+
+        specify_dir = project_dir / ".specify"
+        specify_dir.mkdir(parents=True, exist_ok=True)
+        (specify_dir / "integration.json").write_text(
+            json.dumps({"integration": "opencode", "version": "0.7.4"}),
+            encoding="utf-8",
+        )
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "auto-default"
+  name: "Auto Default"
+  version: "1.0.0"
+inputs:
+  integration:
+    type: string
+    default: "auto"
+""")
+        engine = WorkflowEngine(project_dir)
+        resolved = engine._resolve_inputs(definition, {})
+        assert resolved["integration"] == "opencode"
+
+    def test_integration_auto_default_falls_back_when_no_integration_json(self, project_dir):
+        """`integration: auto` should keep the literal "auto" when project state is missing.
+
+        The engine itself must not invent an integration when
+        ``.specify/integration.json`` is absent; any later validation or
+        command resolution will handle an unresolved ``"auto"`` value.
+        """
+        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "auto-fallback"
+  name: "Auto Fallback"
+  version: "1.0.0"
+inputs:
+  integration:
+    type: string
+    default: "auto"
+""")
+        engine = WorkflowEngine(project_dir)
+        resolved = engine._resolve_inputs(definition, {})
+        assert resolved["integration"] == "auto"
+
+    def test_integration_explicit_input_overrides_auto(self, project_dir):
+        """An explicit --input integration=X must win over `auto` even when integration.json exists."""
+        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
+
+        specify_dir = project_dir / ".specify"
+        specify_dir.mkdir(parents=True, exist_ok=True)
+        (specify_dir / "integration.json").write_text(
+            json.dumps({"integration": "opencode"}),
+            encoding="utf-8",
+        )
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "explicit-wins"
+  name: "Explicit Wins"
+  version: "1.0.0"
+inputs:
+  integration:
+    type: string
+    default: "auto"
+""")
+        engine = WorkflowEngine(project_dir)
+        resolved = engine._resolve_inputs(definition, {"integration": "claude"})
+        assert resolved["integration"] == "claude"
+
+    def test_integration_explicit_auto_resolves_like_default(self, project_dir):
+        """Passing ``integration=auto`` explicitly must resolve the sentinel,
+        not pass it through as a literal — the workflow prompt advertises
+        ``auto`` as a valid value, so the dispatch path must never see it.
+        """
+        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
+
+        specify_dir = project_dir / ".specify"
+        specify_dir.mkdir(parents=True, exist_ok=True)
+        (specify_dir / "integration.json").write_text(
+            json.dumps({"integration": "opencode"}),
+            encoding="utf-8",
+        )
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "explicit-auto"
+  name: "Explicit Auto"
+  version: "1.0.0"
+inputs:
+  integration:
+    type: string
+    default: "auto"
+""")
+        engine = WorkflowEngine(project_dir)
+        resolved = engine._resolve_inputs(definition, {"integration": "auto"})
+        assert resolved["integration"] == "opencode"
+
+    def test_integration_auto_ignores_malformed_integration_json(self, project_dir):
+        """A malformed integration.json must not crash — fall back to the literal default."""
+        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
+
+        specify_dir = project_dir / ".specify"
+        specify_dir.mkdir(parents=True, exist_ok=True)
+        (specify_dir / "integration.json").write_text("{not json", encoding="utf-8")
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "auto-malformed"
+  name: "Auto Malformed"
+  version: "1.0.0"
+inputs:
+  integration:
+    type: string
+    default: "auto"
+""")
+        engine = WorkflowEngine(project_dir)
+        resolved = engine._resolve_inputs(definition, {})
+        assert resolved["integration"] == "auto"
+
+    def test_integration_auto_ignores_non_utf8_integration_json(self, project_dir):
+        """A non-UTF8 integration.json must not crash — fall back to the literal default."""
+        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
+
+        specify_dir = project_dir / ".specify"
+        specify_dir.mkdir(parents=True, exist_ok=True)
+        # 0xFF is invalid as the leading byte of a UTF-8 sequence, so
+        # ``Path.read_text(encoding="utf-8")`` raises UnicodeDecodeError.
+        (specify_dir / "integration.json").write_bytes(b"\xff\xfe\x00\x00")
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "auto-non-utf8"
+  name: "Auto Non UTF-8"
+  version: "1.0.0"
+inputs:
+  integration:
+    type: string
+    default: "auto"
+""")
+        engine = WorkflowEngine(project_dir)
+        resolved = engine._resolve_inputs(definition, {})
+        assert resolved["integration"] == "auto"
+
+    def test_integration_auto_resolves_modern_normalized_state(self, project_dir):
+        """`integration: auto` must resolve modern state files that record
+        ``default_integration`` / ``installed_integrations`` and omit the
+        legacy ``integration`` field."""
+        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
+
+        specify_dir = project_dir / ".specify"
+        specify_dir.mkdir(parents=True, exist_ok=True)
+        (specify_dir / "integration.json").write_text(
+            json.dumps(
+                {
+                    "version": "0.8.3",
+                    "integration_state_schema": 1,
+                    "default_integration": "claude",
+                    "installed_integrations": ["claude", "copilot"],
+                    "integration_settings": {},
+                }
+            ),
+            encoding="utf-8",
+        )
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "auto-modern"
+  name: "Auto Modern"
+  version: "1.0.0"
+inputs:
+  integration:
+    type: string
+    default: "auto"
+""")
+        engine = WorkflowEngine(project_dir)
+        resolved = engine._resolve_inputs(definition, {})
+        assert resolved["integration"] == "claude"
+
+    def test_integration_auto_rejects_future_state_schema(self, project_dir):
+        """`integration: auto` must not silently use a state file written by a newer
+        CLI (``integration_state_schema`` greater than the current supported value);
+        the resolver falls back to the literal default rather than guessing."""
+        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
+        from specify_cli.integration_state import INTEGRATION_STATE_SCHEMA
+
+        specify_dir = project_dir / ".specify"
+        specify_dir.mkdir(parents=True, exist_ok=True)
+        (specify_dir / "integration.json").write_text(
+            json.dumps(
+                {
+                    "version": "99.0.0",
+                    "integration_state_schema": INTEGRATION_STATE_SCHEMA + 1,
+                    "default_integration": "claude",
+                    "installed_integrations": ["claude"],
+                    "integration_settings": {},
+                }
+            ),
+            encoding="utf-8",
+        )
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "auto-future-schema"
+  name: "Auto Future Schema"
+  version: "1.0.0"
+inputs:
+  integration:
+    type: string
+    default: "auto"
+""")
+        engine = WorkflowEngine(project_dir)
+        resolved = engine._resolve_inputs(definition, {})
+        assert resolved["integration"] == "auto"
+
+    def test_default_value_is_validated_against_enum(self, project_dir):
+        """Defaults must run through the same coercion/enum check as provided inputs."""
+        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "default-enum"
+  name: "Default Enum"
+  version: "1.0.0"
+inputs:
+  scope:
+    type: string
+    default: "not-in-enum"
+    enum: ["full", "backend-only", "frontend-only"]
+""")
+        engine = WorkflowEngine(project_dir)
+        with pytest.raises(ValueError, match="not in allowed values"):
+            engine._resolve_inputs(definition, {})
+
+    def test_default_value_is_coerced_to_declared_type(self, project_dir):
+        """A numeric default declared as a string should still be coerced like a provided input."""
+        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "default-coerce"
+  name: "Default Coerce"
+  version: "1.0.0"
+inputs:
+  retries:
+    type: number
+    default: "3"
+""")
+        engine = WorkflowEngine(project_dir)
+        resolved = engine._resolve_inputs(definition, {})
+        assert resolved["retries"] == 3
+        assert isinstance(resolved["retries"], int)
+
+    def test_validate_workflow_rejects_invalid_default(self):
+        """Authoring-time validation should reject defaults that violate enum."""
+        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "bad-default"
+  name: "Bad Default"
+  version: "1.0.0"
+inputs:
+  scope:
+    type: string
+    default: "not-in-enum"
+    enum: ["full", "backend-only", "frontend-only"]
+steps:
+  - id: noop
+    type: gate
+    message: "noop"
+    options: [approve]
+""")
+        errors = validate_workflow(definition)
+        assert any("invalid default" in e for e in errors), errors
+
+    def test_validate_workflow_exempts_integration_auto_sentinel(self):
+        """``integration: auto`` is a runtime-resolved sentinel and must not fail validation."""
+        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "auto-ok"
+  name: "Auto OK"
+  version: "1.0.0"
+inputs:
+  integration:
+    type: string
+    default: "auto"
+    enum: ["copilot", "claude", "gemini"]
+steps:
+  - id: noop
+    type: gate
+    message: "noop"
+    options: [approve]
+""")
+        errors = validate_workflow(definition)
+        assert not any("invalid default" in e for e in errors), errors
+
+    def test_validate_workflow_still_checks_type_for_auto_sentinel(self):
+        """The ``auto`` exemption only skips enum-membership; declared type is still enforced."""
+        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "auto-bad-type"
+  name: "Auto Bad Type"
+  version: "1.0.0"
+inputs:
+  integration:
+    type: number
+    default: "auto"
+steps:
+  - id: noop
+    type: gate
+    message: "noop"
+    options: [approve]
+""")
+        errors = validate_workflow(definition)
+        assert any("invalid default" in e for e in errors), errors
+
+    def test_validate_workflow_rejects_bool_default_for_number_type(self):
+        """``type: number`` paired with a bool default must fail — bool is a
+        subclass of int so ``float(True)`` would otherwise silently coerce
+        ``true`` to ``1``.
+        """
+        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "bool-as-number"
+  name: "Bool As Number"
+  version: "1.0.0"
+inputs:
+  count:
+    type: number
+    default: true
+steps:
+  - id: noop
+    type: gate
+    message: "noop"
+    options: [approve]
+""")
+        errors = validate_workflow(definition)
+        assert any("invalid default" in e for e in errors), errors
+
+    def test_validate_workflow_rejects_non_string_default_for_string_type(self):
+        """``type: string`` must require an actual string — a numeric YAML
+        default like ``5`` would otherwise slip through unvalidated.
+        """
+        from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "number-as-string"
+  name: "Number As String"
+  version: "1.0.0"
+inputs:
+  label:
+    type: string
+    default: 5
+steps:
+  - id: noop
+    type: gate
+    message: "noop"
+    options: [approve]
+""")
+        errors = validate_workflow(definition)
+        assert any("invalid default" in e for e in errors), errors
+

 # ===== State Persistence Tests =====

--- a/workflows/speckit/workflow.yml
+++ b/workflows/speckit/workflow.yml
@@ -7,9 +7,23 @@ workflow:
  description: "Runs specify → plan → tasks → implement with review gates"

 requires:
-  speckit_version: ">=0.7.2"
+  # 0.8.5 is the first release with engine-side resolution of the
+  # ``integration: "auto"`` default. Older versions would treat "auto"
+  # as a literal integration key and fail at dispatch.
+  speckit_version: ">=0.8.5"
  integrations:
-    any: ["copilot", "claude", "gemini"]
+    # The four commands below (specify, plan, tasks, implement) are core
+    # spec-kit commands provided by every integration. The list here is an
+    # advisory, non-exhaustive compatibility hint following the documented
+    # ``any: [...]`` schema -- it is NOT a closed set. The workflow runs
+    # against any integration the project was initialized with, including
+    # ones not listed below, as long as that integration provides the four
+    # core commands referenced in ``steps``.
+    any:
+      - "claude"
+      - "copilot"
+      - "gemini"
+      - "opencode"

 inputs:
  spec:
@@ -18,8 +32,8 @@ inputs:
    prompt: "Describe what you want to build"
  integration:
    type: string
-    default: "copilot"
-    prompt: "Integration to use (e.g. claude, copilot, gemini)"
+    default: "auto"
+    prompt: "Integration to use (e.g. claude, copilot, gemini; 'auto' uses the project's initialized integration)"
  scope:
    type: string
    default: "full"
Author	SHA1	Message	Date
github-actions[bot]	f16468f21f	chore: bump version to 0.8.12	2026-05-20 14:10:09 +00:00
Chao Z	9735145289	fix(codex): inject dot-to-hyphen hook command note in Codex skills (#2503 ) * fix(codex): inject dot-to-hyphen hook command note in Codex skills Hook commands in `.specify/extensions.yml` use dotted ids like `speckit.git.commit`, but Codex skills are named with hyphens (`speckit-git-commit`). The Claude integration handles this via an explicit instruction injected into each generated SKILL.md by `ClaudeIntegration.post_process_skill_content`, but the Codex integration had no such override, so Codex would emit `/speckit.git.commit` (which does not resolve) instead of `/speckit-git-commit`. This adds the same `_inject_hook_command_note` helper and a `post_process_skill_content` override to `CodexIntegration`, plus a small `setup()` override that applies the post-process to each generated SKILL.md (mirroring the pattern in `ClaudeIntegration`). Also widens the existing `test_non_claude_post_process_is_identity` test to use `agy` (another `SkillsIntegration` with no override), since asserting identity behavior on Codex would now incorrectly fail. Tests: - New `TestCodexHookCommandNote` class mirrors `TestClaudeHookCommandNote`: setup-level injection, no-op when no hook block is present, idempotency, and indentation preservation. - `pytest tests/` → 2866 passed, 34 skipped. Signed-off-by: Chao Zhang <1175468+picklebento@users.noreply.github.com> * fix(codex): handle empty eol when instruction is final line without newline The hook-note injection regex allowed end-of-string matches via ``$``, which left the captured ``eol`` empty. When the matched indent was also empty, the substitution concatenated the note onto the same line as the instruction. Default ``eol`` to ``\n`` when the capture is empty. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Signed-off-by: Chao Zhang <1175468+picklebento@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-20 09:04:47 -05:00
Manfred Riem	68a031c768	Update Squad Bridge extension to v1.3.0 (#2645 ) Update squad extension submitted by @jwill824: - extensions/catalog.community.json (version, download_url, speckit_version, tools version, description, updated_at) - docs/community/extensions.md community extensions table Closes #2608	2026-05-20 06:56:50 -05:00
Manfred Riem	a59381ae30	Update Superpowers Implementation Bridge extension to v0.5.0 (#2644 ) Update speckit-superpowers-bridge extension submitted by @lihan3238: - extensions/catalog.community.json (version, download_url, updated_at) Closes #2601	2026-05-20 06:35:56 -05:00
Manfred Riem	975498e11d	Add Team Assign extension to community catalog (#2642 ) Add team-assign extension submitted by @tarunkumarbhati to: - extensions/catalog.community.json (alphabetical order) - docs/community/extensions.md community extensions table Closes #2597	2026-05-20 06:11:09 -05:00
WOLIKIMCHENG	51e6a140e2	refactor: migrate extension catalog stack parsing to shared base (#2576 ) Co-authored-by: root <1647273252@qq.com>	2026-05-18 07:02:18 -05:00
Manfred Riem	81e9ecd4d9	Update Architecture Workflow extension to v1.1.0 (#2588 ) Update arch extension submitted by @bigsmartben: - extensions/catalog.community.json (version, download_url, description, commands count, updated_at) - docs/community/extensions.md community extensions table Closes #2577	2026-05-15 16:21:34 -05:00
Quratulain-bilal	409ec59704	fix(workflow): support integration: auto to follow project's initialized AI (#2421 ) * fix(workflow): support integration: auto to follow project's initialized AI Closes #2406 (squashed) * fix(workflow): combine JSONDecodeError and UnicodeDecodeError handling Address Copilot feedback: UnicodeDecodeError can be raised by both read_text() and json.loads(), so combining the handlers ensures both cases produce a consistent, clear error message. * fix(workflows): honor integration_state schema guard and modern state in 'integration: auto' Three Copilot follow-ups on PR #2421: 1. engine.py:799 — `_load_project_integration` was bypassing the same schema guard `_read_integration_json` enforces. It now reads the schema field directly, returns None on a future schema (so the workflow falls back to the literal 'auto' default rather than guessing), and routes through `normalize_integration_state` / `default_integration_key` so modern installs that record `default_integration` / `installed_integrations` (without the legacy top-level `integration` field) resolve correctly. 2. test_workflows.py — added two regression cases: - `integration: auto` resolves a modern normalized state file - `integration: auto` falls back when the state file declares a newer `integration_state_schema` than this CLI supports 3. test_cli.py — added a CLI-level regression for the `UnicodeDecodeError` branch in `_read_integration_json` to match the existing malformed-JSON coverage. * refactor(integration): extract shared try_read_integration_json helper Address Copilot review on PR #2421: Both `_read_integration_json` (CLI) and `_load_project_integration` (workflow engine) were parsing `.specify/integration.json` independently, duplicating the schema guard and risking drift between the two readers. Extract the parse + schema validation into a single low-level helper `try_read_integration_json` in `integration_state.py` that returns either the normalized state or a structured `IntegrationReadError`. Both callers now delegate to this helper: - CLI keeps its loud-fail UX: each error kind ("decode", "os", "not_object", "schema_too_new") is translated into the existing console message + typer.Exit(1). - Engine keeps its silent fallback: any error simply returns None so `integration: auto` falls back to the workflow's literal default. This eliminates the divergence Copilot flagged without changing observable behavior for either caller. * fix(integration): distinguish missing file from non-regular path Address Copilot review on PR #2421: `try_read_integration_json` was collapsing two distinct cases into a single `(None, None)` return: 1. `.specify/integration.json` truly missing — silent fallback is correct. 2. Path exists but is a directory, socket, or other non-regular file — this is a misconfiguration the CLI should surface loudly. Split the check: `exists()` falsey returns `(None, None)`; existing-but- not-a-regular-file returns `(None, IntegrationReadError(kind="os", ...))` so the CLI's loud-fail path produces an actionable error while the engine still treats it as a fallback to the workflow's literal default. * docs(workflow): clarify version pin, advisory integrations list, enum exemption - workflow.yml: fix comment that said 0.8.3 was first release with auto resolution; the pin is >=0.8.5 so the comment now matches the pin. - workflow.yml: clarify that requires.integrations.any is an advisory, non-exhaustive compatibility hint, not a closed set. - engine.py: clarify that the auto-sentinel exemption only skips enum membership; declared type is still enforced through _coerce_input. * fix(workflow): resolve auto sentinel for provided values; report stat errors Two Copilot findings fixed: 1. _resolve_inputs only resolved the ``integration: auto`` sentinel when it came from the input default. A caller explicitly providing ``{"integration": "auto"}`` (which the workflow prompt advertises as a valid value) bypassed _resolve_default and the literal "auto" leaked to dispatch. Provided values now go through the same resolution path as defaults, and the enum-membership exemption applies in both cases. Regression test added. 2. try_read_integration_json used Path.exists() / Path.is_file() as a pre-check. Both return False on some OSErrors (e.g. permission errors during stat), which silently treated an unreadable-but-present file as missing — the engine fell back without warning and the CLI failed to surface the loud error. The pre-check is gone: read_text() is attempted directly, FileNotFoundError means missing (silent fallback), IsADirectoryError and other OSErrors become loud IntegrationReadError. * fix(workflow): enforce declared type for string inputs, reject bool-as-number Two Copilot findings fixed: 1. _coerce_input previously coerced/validated only ``number`` and ``boolean`` types, so ``type: string`` silently accepted any Python value (numbers, lists, dicts). A YAML authoring mistake like ``type: string`` + ``default: 5`` slipped through. Strings are now required to actually be strings; non-strings raise ValueError, which surfaces as an ``invalid default`` error from validate_workflow. 2. ``type: number`` accepted ``default: true`` because ``bool`` is a subclass of ``int`` (``float(True) == 1.0``). Bools are now rejected explicitly in the number path so the YAML mistake fails fast. The boolean path is also tightened to reject non-bool / non-string values for symmetry. Comment on the auto-sentinel enum exemption updated to reflect the stronger guarantee. Regression tests added for both rejections. * fix(cli): drop unused normalize_integration_state import to satisfy ruff CI's `uvx ruff check src/` flagged this as F401: the symbol was imported under a private alias but never referenced. Tests stay green after removal.	2026-05-15 16:03:33 -05:00
Manfred Riem	b36c34f171	Add Superpowers Implementation Bridge extension to community catalog (#2586 ) Add speckit-superpowers-bridge extension submitted by @lihan3238 to: - extensions/catalog.community.json (alphabetical order) - docs/community/extensions.md community extensions table Closes #2581	2026-05-15 15:41:59 -05:00
Manfred Riem	8bd20a2f5f	Add Interactive HTML Preview extension to community catalog (#2585 ) Add preview extension submitted by @bigsmartben to: - extensions/catalog.community.json (alphabetical order) - docs/community/extensions.md community extensions table Closes #2578	2026-05-15 15:13:33 -05:00
Manfred Riem	4c610a20dc	chore: release 0.8.11, begin 0.8.12.dev0 development (#2584 ) * chore: bump version to 0.8.11 * chore: begin 0.8.12.dev0 development --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>	2026-05-15 15:08:38 -05:00
Manfred Riem	27700387b6	Update Agent Governance extension to v1.1.0 (#2583 ) Update agent-governance extension submitted by @bigsmartben: - extensions/catalog.community.json (version, download_url, updated_at) Closes #2569	2026-05-15 14:59:46 -05:00
darion-yaphet	d947fda96f	refactor: extract _version.py from __init__.py (PR-3/8) (#2550 ) * refactor: extract _version.py from __init__.py (PR-3/8) Move version-checking helpers and `specify self` sub-commands into a focused `_version.py` module. Moved symbols: - GITHUB_API_LATEST — GitHub releases API endpoint constant - _get_installed_version — importlib.metadata-based version lookup - _normalize_tag — strip leading 'v' from release tag strings - _is_newer — PEP 440 version comparison - _fetch_latest_release_tag — single outbound call to GitHub API - self_app — Typer sub-app for `specify self` - self_check, self_upgrade — `specify self check/upgrade` commands Dependency rule: _version.py imports only stdlib + packaging + ._console. Backward compatibility: GITHUB_API_LATEST, self_check, self_upgrade remain importable from specify_cli via re-exports in __init__.py. Update test_upgrade.py to import helpers from specify_cli._version and patch at the correct module path (specify_cli._version.). Add test_version_imports.py as regression guard. fix(tests): update _fetch_latest_release_tag import path in test_authentication.py PR-3 moved _fetch_latest_release_tag from specify_cli into specify_cli._version. test_upgrade.py was updated at the time, but test_authentication.py::TestFetchLatestReleaseTagDelegation still imported from the old location, causing ImportError on all three delegation tests. Update all three inline imports to the correct module path.	2026-05-15 13:12:24 -05:00
Manfred Riem	13c167e107	Add Time Machine extension to community catalog (#2580 ) * Add Time Machine extension to community catalog Add time-machine extension submitted by @teeyo to: - extensions/catalog.community.json (alphabetical order) - docs/community/extensions.md community extensions table Closes #2568 * Fix alphabetical ordering of time-machine entry Move time-machine before tinyspec in both catalog JSON (by ID) and docs table (by name), since time < tiny alphabetically.	2026-05-15 08:43:02 -05:00
Nimra Akram	f684305e51	fix(powershell): ensure UTF-8 templates are written without BOM (#2280 ) * fix(powershell): strip BOM from templates and ensure No-BOM output * fix: address review feedback on encoding and naming for all ps scripts * fix: address copilot feedback (encoding detection and variable naming) * fix: remove duplicate comments in setup-plan.ps1 * test: verify spec.md is written without UTF-8 BOM * test: also verify BOM-free output under Windows PowerShell 5.1 * fix * fix: resolve merge conflict with main, add TestDescriptionQuoting * fix: resolve TestDescriptionQuoting string quoting conflict with main * test: restore PowerShell prefix-stripping parity test in TestGetFeaturePathsSinglePrefix * fix: remove trailing whitespace from module docstring blank lines * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * test: seed ps_git_repo with BOM-prefixed template to exercise WriteAllText fix * fix: remove duplicate ps_git_repo fixture, restore ext_ps_git_repo * fix: remove unrelated TestDescriptionQuoting and restore original test_ps_specify_feature_prefixed_resolves_by_prefix --------- Co-authored-by: Nimraakram22 <nimra.akram123451@gmail.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>	2026-05-15 07:39:17 -05:00
Asish Kumar	b774282058	docs: document high-assurance spec workflow (#2518 ) * docs: document high-assurance workflow * docs: clarify analyze workflow gate Signed-off-by: Asish Kumar <officialasishkumar@gmail.com> --------- Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>	2026-05-15 07:12:59 -05:00
darion-yaphet	6322a4d429	docs: fix script name in directory tree examples (#2555 ) * docs: fix script name in directory tree examples Replace update-claude-md.sh with the actual filename setup-tasks.sh in two directory tree examples (Steps 2 and 4 of the detailed walkthrough). * docs: fix .specify/scripts layout to show bash/ and powershell/ subdirs install_shared_infra() installs scripts under .specify/scripts/bash/ (script_type="sh") or .specify/scripts/powershell/ (script_type="ps"), not directly under .specify/scripts/. Update docs/installation.md and the _install_shared_infra docstring to reflect the actual on-disk layout. * docs: update README tree examples to show scripts/bash/ subdirectory Scripts are installed under .specify/scripts/bash/ (or powershell/) not directly under .specify/scripts/. Fix both tree diagrams in the Detailed Process walkthrough to match the actual on-disk layout.	2026-05-14 15:14:52 -05:00
WOLIKIMCHENG	be382804c7	Fix preset skill description precedence (#2538 ) * Fix preset skill description precedence * Fix skill description precedence during restore --------- Co-authored-by: root <1647273252@qq.com>	2026-05-14 14:59:38 -05:00
Pascal THUET	c87081a50a	fix(integration): clarify multi-install guidance (#2549 )	2026-05-14 13:46:48 -05:00
Pascal THUET	e6afba9429	feat: add version feature reporting (#2548 )	2026-05-14 12:52:14 -05:00
Manfred Riem	c1a1653aca	Add Architecture Workflow extension to community catalog (#2565 ) Add arch extension submitted by @bigsmartben to: - extensions/catalog.community.json (alphabetical order) - docs/community/extensions.md community extensions table Closes #2556	2026-05-14 12:10:47 -05:00
Manfred Riem	0e5b59fcaa	chore: release 0.8.10, begin 0.8.11.dev0 development (#2562 ) * chore: bump version to 0.8.10 * chore: begin 0.8.11.dev0 development --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>	2026-05-14 10:20:54 -05:00