chore: bump version to 0.8.16

docs: update landing page stats and branch naming convention (#2727 )
* docs: update landing page stats and branch naming convention - Update community extensions: 91 → 105 - Update extension authors: 50+ → 60+ - Update presets: 18 → 22 - Update GitHub stars: 96K+ → 106K+ - Add last-updated date to landing page - Clarify branch naming convention for PR-only changes * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
2026-07-03 20:36:23 +08:00 · 2026-05-27 21:34:55 +00:00 · 2026-05-27 16:33:33 -05:00 · 2026-05-27 13:00:58 -05:00 · 2026-05-27 12:49:54 -05:00 · 2026-05-27 09:52:57 -05:00
23 changed files with 959 additions and 52 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -381,25 +381,26 @@ Implementation: Extends `YamlIntegration` (parallel to `TomlIntegration`):

 ## Branch Naming Convention

-All branches **must** follow this pattern:
+Branches follow one of two patterns depending on whether an issue exists:

 ```
-<type>/<number>-<short-slug>
+<type>/<number>-<short-slug>   # when an issue is created first
+<type>/<short-slug>            # when no issue exists (PR-only changes)
 ```

-Where `<number>` is either an issue number or a PR number — whichever is created first.
+When an issue exists, include its number immediately after the prefix — this is what makes branches traceable. For small or self-contained changes that go straight to a PR without a tracking issue, omit the number.

 | Prefix | When to use | Example |
 |---|---|---|
 | `feat/` | New features | `feat/2342-workflow-cli-alignment` |
 | `fix/` | Bug fixes | `fix/2653-paths-only-validation` |
-| `docs/` | Documentation changes | `docs/2677-branch-naming-convention` |
+| `docs/` | Documentation changes | `docs/2677-branch-naming-convention`, `docs/update-landing-stats` |
 | `community/` | Community catalog additions | `community/2492-add-mde-extension` |
 | `chore/` | Maintenance, tooling, CI | `chore/2366-editorconfig` |

 **Rules:**

-1. Always include the issue or PR number immediately after the prefix — this is what makes branches traceable
+1. Include the issue number when one exists — this is what makes branches traceable
 2. Use kebab-case for the slug
 3. Keep the slug short — enough to identify the work without looking up the issue

--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,20 @@

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

+## [0.8.16] - 2026-05-27
+
+### Changed
+
+- docs: update landing page stats and branch naming convention (#2727)
+- feat(workflows): expose {{ context.run_id }} template variable (#2664)
+- fix: resolve __SPECKIT_COMMAND_*__ refs in preset skill rendering (#2717) (#2718)
+- Add Workflow Preset to community catalog (#2725)
+- fix: paths-only skips branch validation, setup-plan preserves existing plan (#2672)
+- docs: fix broken pipx homepage URLs to point to pipx.pypa.io (#2670)
+- Update Architecture Guard extension to v1.8.9 (#2723)
+- Re-validate spec quality checklist after clarify updates spec (#2715)
+- chore: release 0.8.15, begin 0.8.16.dev0 development (#2722)
+
 ## [0.8.15] - 2026-05-27

 ### Changed
--- a/README.md
+++ b/README.md
@@ -281,7 +281,7 @@ Our research and experimentation focus on:

 - **Linux/macOS/Windows**
 - [Supported](#-supported-ai-coding-agent-integrations) AI coding agent.
- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pypa.github.io/pipx/) for persistent installation
+- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pipx.pypa.io/) for persistent installation
 - [Python 3.11+](https://www.python.org/downloads/)
 - [Git](https://git-scm.com/downloads)

--- a/docs/community/extensions.md
+++ b/docs/community/extensions.md
@@ -27,7 +27,7 @@ The following community-contributed extensions are available in [`catalog.commun
 | AI-Driven Engineering (AIDE) | A structured 7-step workflow for building new projects from scratch with AI assistants — from vision through implementation | `process` | Read+Write | [aide](https://github.com/mnriem/spec-kit-extensions/tree/main/aide) |
 | API Evolve | Managed API contract evolution — breaking-change detection, semver enforcement, deprecation orchestration, and lifecycle gates across REST, GraphQL, and gRPC | `process` | Read+Write | [spec-kit-api-evolve](https://github.com/Quratulain-bilal/spec-kit-api-evolve) |
 | Architect Impact Previewer | Predicts architectural impact, complexity, and risks of proposed changes before implementation. | `visibility` | Read-only | [spec-kit-architect-preview](https://github.com/UmmeHabiba1312/spec-kit-architect-preview) |
-| Architecture Guard | 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 Guard | Framework-agnostic architecture review extension for validating implementation against governance and architecture constitutions, detecting architectural drift, and generating non-blocking refactor tasks | `process` | Read+Write | [spec-kit-architecture-guard](https://github.com/DyanGalih/spec-kit-architecture-guard) |
 | Architecture Workflow | Generate or reverse project-level 4+1 architecture view artifacts and synthesis | `docs` | Read+Write | [spec-kit-arch](https://github.com/bigsmartben/spec-kit-arch) |
 | Archive Extension | Archive merged features into main project memory. | `docs` | Read+Write | [spec-kit-archive](https://github.com/stn1slv/spec-kit-archive) |
 | Azure DevOps Integration | Sync user stories and tasks to Azure DevOps work items using OAuth authentication | `integration` | Read+Write | [spec-kit-azure-devops](https://github.com/pragya247/spec-kit-azure-devops) |
--- a/docs/community/presets.md
+++ b/docs/community/presets.md
@@ -27,5 +27,6 @@ The following community-contributed presets customize how Spec Kit behaves — o
 | Spec2Cloud | Spec-driven workflow tuned for shipping to Azure: spec → plan → tasks → implement → deploy | 5 templates, 8 commands | — | [spec2cloud](https://github.com/Azure-Samples/Spec2Cloud) |
 | Table of Contents Navigation | Adds a navigable Table of Contents to generated spec.md, plan.md, and tasks.md documents | 3 templates, 3 commands | — | [spec-kit-preset-toc-navigation](https://github.com/Quratulain-bilal/spec-kit-preset-toc-navigation) |
 | VS Code Ask Questions | Enhances the clarify command to use `vscode/askQuestions` for batched interactive questioning. | 1 command | — | [spec-kit-presets](https://github.com/fdcastel/spec-kit-presets) |
+| Workflow Preset | Behavior-first specification, design artifacts, and agent-native handoff orchestration — adds requirement-phase behavior drafts, formal BDD/UIF/behavior contracts, optional design artifacts, and scoped implementation handoffs with Core Agent, Vertical Planner Agent, and Worker Agent modes | 23 templates, 7 commands | — | [spec-kit-workflow-preset](https://github.com/bigsmartben/spec-kit-workflow-preset) |

 To build and publish your own preset, see the [Presets Publishing Guide](https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md).
--- a/docs/index.md
+++ b/docs/index.md
@@ -43,7 +43,7 @@ Run `specify init` with your agent of choice and Spec Kit sets up the right comm

 ### Make it your own

-<span class="pillar-stat">91 community extensions</span> (50+ authors), <span class="pillar-stat">18 presets</span>, and growing. Tune the core process with presets, extend it with extensions, orchestrate it with workflows, or replace it entirely. Build and publish your own.
+<span class="pillar-stat">105 community extensions</span> (60+ authors), <span class="pillar-stat">22 presets</span>, and growing. Tune the core process with presets, extend it with extensions, orchestrate it with workflows, or replace it entirely. Build and publish your own.

 Including entirely different SDD processes:

@@ -82,7 +82,7 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a

 <div class="stats-grid">
  <div class="stat-item">
-    <span class="stat-number">96K+</span>
+    <span class="stat-number">106K+</span>
    <span class="stat-label">GitHub stars</span>
  </div>
  <div class="stat-item">
@@ -94,11 +94,11 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a
    <span class="stat-label">Integrations</span>
  </div>
  <div class="stat-item">
-    <span class="stat-number">91</span>
+    <span class="stat-number">105</span>
    <span class="stat-label">Extensions</span>
  </div>
  <div class="stat-item">
-    <span class="stat-number">18</span>
+    <span class="stat-number">22</span>
    <span class="stat-label">Presets</span>
  </div>
  <div class="stat-item">
@@ -150,3 +150,5 @@ specify init my-project --integration copilot
 Ready to start? Follow the [Quick Start Guide](quickstart.md).

 </div>
+
+<p class="text-end small text-body-secondary">Last updated: May 27, 2026</p>
--- a/docs/install/pipx.md
+++ b/docs/install/pipx.md
@@ -1,6 +1,6 @@
 # Installing with pipx

-[pipx](https://pypa.github.io/pipx/) is a tool for installing Python CLI applications in isolated environments. It does not require [uv](https://docs.astral.sh/uv/).
+[pipx](https://pipx.pypa.io/) is a tool for installing Python CLI applications in isolated environments. It does not require [uv](https://docs.astral.sh/uv/).

 ## Install Specify CLI

--- a/docs/installation.md
+++ b/docs/installation.md
@@ -4,7 +4,7 @@

 - **Linux/macOS** (or Windows; PowerShell scripts now supported without WSL)
 - AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [Codebuddy CLI](https://www.codebuddy.ai/cli), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [Pi Coding Agent](https://pi.dev)
- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pypa.github.io/pipx/) for persistent installation
+- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pipx.pypa.io/) for persistent installation
 - [Python 3.11+](https://www.python.org/downloads/)
 - [Git](https://git-scm.com/downloads)

--- a/extensions/catalog.community.json
+++ b/extensions/catalog.community.json
@@ -1,6 +1,6 @@
 {
  "schema_version": "1.0",
-  "updated_at": "2026-05-26T00:00:00Z",
+  "updated_at": "2026-05-27T00:00:00Z",
  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
  "extensions": {
    "aide": {
@@ -240,10 +240,10 @@
    "architecture-guard": {
      "name": "Architecture Guard",
      "id": "architecture-guard",
-      "description": "Continuous architecture governance for AI-assisted development. Reviews specs, plans, and code for architecture drift, producing structured refactor tasks and evolution proposals.",
+      "description": "Framework-agnostic architecture review extension for validating implementation against governance and architecture constitutions, detecting architectural drift, and generating non-blocking refactor tasks.",
      "author": "DyanGalih",
-      "version": "1.8.4",
-      "download_url": "https://github.com/DyanGalih/spec-kit-architecture-guard/archive/refs/tags/v1.8.4.zip",
+      "version": "1.8.9",
+      "download_url": "https://github.com/DyanGalih/spec-kit-architecture-guard/archive/refs/tags/v1.8.9.zip",
      "repository": "https://github.com/DyanGalih/spec-kit-architecture-guard",
      "homepage": "https://github.com/DyanGalih/spec-kit-architecture-guard",
      "documentation": "https://github.com/DyanGalih/spec-kit-architecture-guard/blob/main/README.md",
@@ -258,17 +258,18 @@
      },
      "tags": [
        "architecture",
-        "governance",
-        "drift-detection",
+        "spec-kit",
+        "review",
        "refactor",
-        "monolithic",
-        "microservices"
+        "workflow",
+        "governance",
+        "guardrails"
      ],
      "verified": false,
      "downloads": 0,
      "stars": 0,
      "created_at": "2026-05-05T07:26:00Z",
-      "updated_at": "2026-05-11T14:58:00Z"
+      "updated_at": "2026-05-27T00:00:00Z"
    },
    "archive": {
      "name": "Archive Extension",
--- a/presets/catalog.community.json
+++ b/presets/catalog.community.json
@@ -1,6 +1,6 @@
 {
  "schema_version": "1.0",
-  "updated_at": "2026-05-26T00:00:00Z",
+  "updated_at": "2026-05-27T00:00:00Z",
  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json",
  "presets": {
    "a11y-governance": {
@@ -581,6 +581,34 @@
        "clarify",
        "interactive"
      ]
+    },
+    "workflow-preset": {
+      "name": "Workflow Preset",
+      "id": "workflow-preset",
+      "version": "1.2.0",
+      "description": "Behavior-first specification, design artifacts, and agent-native handoff orchestration.",
+      "author": "bigsmartben",
+      "repository": "https://github.com/bigsmartben/spec-kit-workflow-preset",
+      "download_url": "https://github.com/bigsmartben/spec-kit-workflow-preset/archive/refs/tags/v1.2.0.zip",
+      "homepage": "https://github.com/bigsmartben/spec-kit-workflow-preset",
+      "documentation": "https://github.com/bigsmartben/spec-kit-workflow-preset/blob/main/README.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.8.10.dev0"
+      },
+      "provides": {
+        "templates": 23,
+        "commands": 7
+      },
+      "tags": [
+        "behavior",
+        "bdd",
+        "planning",
+        "implementation",
+        "handoff"
+      ],
+      "created_at": "2026-05-27T00:00:00Z",
+      "updated_at": "2026-05-27T00:00:00Z"
    }
  }
 }
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.8.15"
+version = "0.8.16"
 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/bash/check-prerequisites.sh
+++ b/scripts/bash/check-prerequisites.sh
@@ -78,13 +78,12 @@ done
 SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/common.sh"

-# Get feature paths and validate branch
+# Get feature paths
 _paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
 eval "$_paths_output"
 unset _paths_output
-check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1

-# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+# If paths-only mode, output paths and exit (no validation)
 if $PATHS_ONLY; then
    if $JSON_MODE; then
        # Minimal JSON paths payload (no validation performed)
@@ -112,6 +111,9 @@ if $PATHS_ONLY; then
    exit 0
 fi

+# Validate branch name
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
 # Validate required directories and files
 if [[ ! -d "$FEATURE_DIR" ]]; then
    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
--- a/scripts/bash/setup-plan.sh
+++ b/scripts/bash/setup-plan.sh
@@ -40,15 +40,31 @@ fi
 # Ensure the feature directory exists
 mkdir -p "$FEATURE_DIR"

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

 # Output results
--- a/scripts/powershell/check-prerequisites.ps1
+++ b/scripts/powershell/check-prerequisites.ps1
@@ -56,14 +56,10 @@ EXAMPLES:
 # Source common functions
 . "$PSScriptRoot/common.ps1"

-# Get feature paths and validate branch
+# Get feature paths
 $paths = Get-FeaturePathsEnv

-if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GIT)) { 
-    exit 1 
-}
-
-# If paths-only mode, output paths and exit (support combined -Json -PathsOnly)
+# If paths-only mode, output paths and exit (no validation)
 if ($PathsOnly) {
    if ($Json) {
        [PSCustomObject]@{
@@ -85,6 +81,11 @@ if ($PathsOnly) {
    exit 0
 }

+# Validate branch name
+if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GIT)) {
+    exit 1
+}
+
 # Validate required directories and files
 if (-not (Test-Path $paths.FEATURE_DIR -PathType Container)) {
    Write-Output "ERROR: Feature directory not found: $($paths.FEATURE_DIR)"
--- a/scripts/powershell/setup-plan.ps1
+++ b/scripts/powershell/setup-plan.ps1
@@ -33,17 +33,25 @@ if (-not (Test-FeatureJsonMatchesFeatureDir -RepoRoot $paths.REPO_ROOT -ActiveFe
 # Ensure the feature directory exists
 New-Item -ItemType Directory -Path $paths.FEATURE_DIR -Force | Out-Null

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

 # Output results
--- a/src/specify_cli/presets.py
+++ b/src/specify_cli/presets.py
@@ -28,6 +28,7 @@ from packaging import version as pkg_version
 from packaging.specifiers import SpecifierSet, InvalidSpecifier

 from .extensions import REINSTALL_COMMAND, ExtensionRegistry, normalize_priority
+from .integrations.base import IntegrationBase


 def _substitute_core_template(
@@ -1058,6 +1059,9 @@ class PresetManager:
                        body = registrar.resolve_skill_placeholders(
                            selected_ai, fm, body, self.project_root
                        )
+                        body = self._resolve_skill_command_refs(
+                            body, registrar, selected_ai
+                        )
                    fm_data = registrar.build_skill_frontmatter(
                        selected_ai if isinstance(selected_ai, str) else "",
                        skill_name, desc,
@@ -1134,6 +1138,23 @@ class PresetManager:
            title_name = title_name[len("speckit."):]
        return title_name.replace(".", " ").replace("-", " ").title()

+    @staticmethod
+    def _resolve_skill_command_refs(
+        body: str, registrar: "CommandRegistrar", selected_ai: str
+    ) -> str:
+        """Render ``__SPECKIT_COMMAND_*__`` tokens in a skill body as invocations.
+
+        Looks up the agent's invoke separator and rewrites each
+        ``__SPECKIT_COMMAND_<NAME>__`` placeholder into the matching
+        slash-command invocation — ``/speckit-<cmd>`` for a ``-`` separator,
+        ``/speckit.<cmd>`` for ``.`` — the same rendering the command layer
+        applies via ``CommandRegistrar.register_commands()``.
+        """
+        separator = registrar.AGENT_CONFIGS.get(selected_ai, {}).get(
+            "invoke_separator", "."
+        )
+        return IntegrationBase.resolve_command_refs(body, separator)
+
    def _build_extension_skill_restore_index(self) -> Dict[str, Dict[str, Any]]:
        """Index extension-backed skill restore data by skill directory name."""
        from .extensions import ExtensionManifest, ValidationError
@@ -1310,6 +1331,7 @@ class PresetManager:
            body = registrar.resolve_skill_placeholders(
                selected_ai, frontmatter, body, self.project_root
            )
+            body = self._resolve_skill_command_refs(body, registrar, selected_ai)

            for target_skill_name in target_skill_names:
                skill_subdir = skills_dir / target_skill_name
@@ -1402,6 +1424,9 @@ class PresetManager:
                    body = registrar.resolve_skill_placeholders(
                        selected_ai, frontmatter, body, self.project_root
                    )
+                    body = self._resolve_skill_command_refs(
+                        body, registrar, selected_ai
+                    )

                original_desc = frontmatter.get("description", "")
                enhanced_desc = original_desc or SKILL_DESCRIPTIONS.get(
@@ -1439,6 +1464,9 @@ class PresetManager:
                    body = registrar.resolve_skill_placeholders(
                        selected_ai, frontmatter, body, self.project_root
                    )
+                    body = self._resolve_skill_command_refs(
+                        body, registrar, selected_ai
+                    )

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


--- a/templates/commands/clarify.md
+++ b/templates/commands/clarify.md
@@ -197,6 +197,25 @@ Execution steps:

 7. Write the updated spec back to `FEATURE_SPEC`.

+8. **Re-validate Spec Quality Checklist** (if it exists):
+   - Check if `FEATURE_DIR/checklists/requirements.md` exists.
+   - If it does NOT exist, skip this step silently.
+   - If it exists:
+     1. Read the checklist file.
+     2. Identify all GitHub task-list checkbox lines — lines matching `- [ ]`, `- [x]`, or `- [X]` (case-insensitive, tolerant of leading whitespace for nested items) outside of code fences. Ignore all other content (headings, notes, non-checkbox bullets, metadata).
+     3. For each checkbox line, record its current marker state (checked or unchecked) and item text into a before-snapshot list.
+     4. Re-evaluate each checkbox item against the **updated** spec (the version just saved in step 7).
+     5. For each checkbox item, update only if the checked/unchecked state actually changes:
+        - If the item now passes and was unchecked: change `[ ]` to `[x]`.
+        - If the item now fails and was checked: change `[x]`/`[X]` to `[ ]`.
+        - If the state is unchanged: leave the marker as-is (preserve existing case to avoid cosmetic diffs).
+     6. Save the updated checklist file. **Only toggle the `[ ]`/`[x]` marker portion of checkbox lines whose state changed.** All other file content — headings, metadata, notes, line ordering, whitespace — must remain unchanged to avoid noisy diffs.
+     7. Compare the before-snapshot with the current state to compute three lists for the Completion Report:
+        - **Newly passing**: items that changed from unchecked to checked.
+        - **Regressions**: items that changed from checked to unchecked.
+        - **Still unchecked**: items that remain unchecked.
+     8. Record the before/after pass counts as checked/total checkbox items (e.g., "12/16 → 15/16 items passing").
+
 Behavior rules:

 - If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
@@ -248,6 +267,7 @@ Report completion (after questioning loop ends or early termination):
 - Number of questions asked & answered.
 - Path to updated spec.
 - Sections touched (list names).
+- Spec quality checklist status (if `FEATURE_DIR/checklists/requirements.md` was re-validated): show before/after pass counts (e.g., "Spec Quality Checklist: 12/16 → 15/16 items passing") and list any items that changed state — both newly checked (unchecked → checked) and any regressions (checked → unchecked). If any items remain unchecked, list them as areas needing attention.
 - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
 - If any Outstanding or Deferred remain, recommend whether to proceed to `__SPECKIT_COMMAND_PLAN__` or run `__SPECKIT_COMMAND_CLARIFY__` again later post-plan.
 - Suggested next command.
@@ -255,5 +275,6 @@ Report completion (after questioning loop ends or early termination):
 ## Done When

 - [ ] Spec ambiguities identified and clarifications integrated into spec file
+- [ ] Spec quality checklist re-validated against updated spec (if `FEATURE_DIR/checklists/requirements.md` exists)
 - [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
- [ ] Completion reported to user with questions answered, sections touched, and coverage summary
+- [ ] Completion reported to user with questions answered, sections touched, checklist status, and coverage summary
--- a/tests/test_check_prerequisites_paths_only.py
+++ b/tests/test_check_prerequisites_paths_only.py
@@ -0,0 +1,205 @@
+"""Tests for check-prerequisites --paths-only skipping branch validation (#2653)."""
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from tests.conftest import requires_bash
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+COMMON_SH = PROJECT_ROOT / "scripts" / "bash" / "common.sh"
+CHECK_PREREQS_SH = PROJECT_ROOT / "scripts" / "bash" / "check-prerequisites.sh"
+COMMON_PS = PROJECT_ROOT / "scripts" / "powershell" / "common.ps1"
+CHECK_PREREQS_PS = PROJECT_ROOT / "scripts" / "powershell" / "check-prerequisites.ps1"
+
+HAS_PWSH = shutil.which("pwsh") is not None
+_POWERSHELL = shutil.which("powershell.exe") or shutil.which("powershell")
+
+
+def _install_bash_scripts(repo: Path) -> None:
+    d = repo / ".specify" / "scripts" / "bash"
+    d.mkdir(parents=True, exist_ok=True)
+    shutil.copy(COMMON_SH, d / "common.sh")
+    shutil.copy(CHECK_PREREQS_SH, d / "check-prerequisites.sh")
+
+
+def _install_ps_scripts(repo: Path) -> None:
+    d = repo / ".specify" / "scripts" / "powershell"
+    d.mkdir(parents=True, exist_ok=True)
+    shutil.copy(COMMON_PS, d / "common.ps1")
+    shutil.copy(CHECK_PREREQS_PS, d / "check-prerequisites.ps1")
+
+
+def _clean_env() -> dict[str, str]:
+    env = os.environ.copy()
+    for key in list(env):
+        if key.startswith("SPECIFY_"):
+            env.pop(key)
+    return env
+
+
+def _git_init(repo: Path) -> None:
+    subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
+    subprocess.run(
+        ["git", "config", "user.email", "test@example.com"], cwd=repo, check=True
+    )
+    subprocess.run(["git", "config", "user.name", "Test User"], cwd=repo, check=True)
+    subprocess.run(
+        ["git", "commit", "--allow-empty", "-m", "init", "-q"], cwd=repo, check=True
+    )
+
+
+@pytest.fixture
+def prereq_repo(tmp_path: Path) -> Path:
+    repo = tmp_path / "proj"
+    repo.mkdir()
+    _git_init(repo)
+    (repo / ".specify").mkdir()
+    _install_bash_scripts(repo)
+    _install_ps_scripts(repo)
+    return repo
+
+
+# ── Bash tests ────────────────────────────────────────────────────────────
+
+
+@requires_bash
+def test_paths_only_succeeds_on_non_spec_branch(prereq_repo: Path) -> None:
+    """--paths-only must return paths without branch validation (main branch)."""
+    script = prereq_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
+    result = subprocess.run(
+        ["bash", str(script), "--json", "--paths-only"],
+        cwd=prereq_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode == 0, result.stderr
+    data = json.loads(result.stdout)
+    assert "REPO_ROOT" in data
+    assert "BRANCH" in data
+    assert "FEATURE_DIR" in data
+
+
+@requires_bash
+def test_paths_only_succeeds_on_spec_branch(prereq_repo: Path) -> None:
+    """--paths-only must also work on a properly named spec branch."""
+    subprocess.run(
+        ["git", "checkout", "-q", "-b", "001-my-feature"],
+        cwd=prereq_repo,
+        check=True,
+    )
+    script = prereq_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
+    result = subprocess.run(
+        ["bash", str(script), "--json", "--paths-only"],
+        cwd=prereq_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode == 0, result.stderr
+    data = json.loads(result.stdout)
+    assert "FEATURE_DIR" in data
+    assert "001-my-feature" in data.get("BRANCH", "")
+
+
+@requires_bash
+def test_paths_only_text_mode_on_non_spec_branch(prereq_repo: Path) -> None:
+    """--paths-only without --json must return text paths on a non-spec branch."""
+    script = prereq_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
+    result = subprocess.run(
+        ["bash", str(script), "--paths-only"],
+        cwd=prereq_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode == 0, result.stderr
+    assert "REPO_ROOT:" in result.stdout
+    assert "FEATURE_DIR:" in result.stdout
+
+
+@requires_bash
+def test_normal_mode_still_validates_branch(prereq_repo: Path) -> None:
+    """Without --paths-only, branch validation must still fail on main."""
+    script = prereq_repo / ".specify" / "scripts" / "bash" / "check-prerequisites.sh"
+    result = subprocess.run(
+        ["bash", str(script), "--json"],
+        cwd=prereq_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode != 0
+    assert "Not on a feature branch" in result.stderr
+
+
+# ── PowerShell tests ──────────────────────────────────────────────────────
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_ps_paths_only_succeeds_on_non_spec_branch(prereq_repo: Path) -> None:
+    """-PathsOnly must return paths without branch validation (main branch)."""
+    script = prereq_repo / ".specify" / "scripts" / "powershell" / "check-prerequisites.ps1"
+    exe = "pwsh" if HAS_PWSH else _POWERSHELL
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(script), "-Json", "-PathsOnly"],
+        cwd=prereq_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode == 0, result.stderr
+    data = json.loads(result.stdout)
+    assert "REPO_ROOT" in data
+    assert "BRANCH" in data
+    assert "FEATURE_DIR" in data
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_ps_paths_only_succeeds_on_spec_branch(prereq_repo: Path) -> None:
+    """-PathsOnly must also work on a properly named spec branch."""
+    subprocess.run(
+        ["git", "checkout", "-q", "-b", "001-my-feature"],
+        cwd=prereq_repo,
+        check=True,
+    )
+    script = prereq_repo / ".specify" / "scripts" / "powershell" / "check-prerequisites.ps1"
+    exe = "pwsh" if HAS_PWSH else _POWERSHELL
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(script), "-Json", "-PathsOnly"],
+        cwd=prereq_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode == 0, result.stderr
+    data = json.loads(result.stdout)
+    assert "FEATURE_DIR" in data
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_ps_normal_mode_still_validates_branch(prereq_repo: Path) -> None:
+    """Without -PathsOnly, branch validation must still fail on main."""
+    script = prereq_repo / ".specify" / "scripts" / "powershell" / "check-prerequisites.ps1"
+    exe = "pwsh" if HAS_PWSH else _POWERSHELL
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(script), "-Json"],
+        cwd=prereq_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode != 0
+    assert "Not on a feature branch" in result.stderr
--- a/tests/test_presets.py
+++ b/tests/test_presets.py
@@ -2346,6 +2346,154 @@ class TestPresetSkills:
        metadata = manager.registry.get("self-test")
        assert "speckit-specify" in metadata.get("registered_skills", [])

+    def test_register_skills_resolves_command_refs(self, project_dir, temp_dir):
+        """Preset skill overrides must resolve __SPECKIT_COMMAND_*__ tokens (issue #2717).
+
+        ``_register_skills()`` previously ran only ``resolve_skill_placeholders()``,
+        so command cross-references leaked into SKILL.md as raw placeholders
+        instead of rendering as ``/speckit-<cmd>`` like the command layer.
+        """
+        self._write_init_options(project_dir, ai="claude")
+        skills_dir = project_dir / ".claude" / "skills"
+        self._create_skill(skills_dir, "speckit-specify")
+
+        preset_dir = self._create_command_preset(
+            temp_dir,
+            "cmdref-install",
+            "speckit.specify",
+            "Override specify",
+            "Run `__SPECKIT_COMMAND_SPECIFY__` then `__SPECKIT_COMMAND_PLAN__`.\n",
+        )
+
+        manager = PresetManager(project_dir)
+        manager.install_from_directory(preset_dir, "0.1.5")
+
+        content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()
+        assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked into SKILL.md"
+        # Claude's invoke_separator is "-", so tokens render as /speckit-<cmd>.
+        assert "/speckit-specify" in content
+        assert "/speckit-plan" in content
+
+    def test_restore_skill_resolves_command_refs(self, project_dir, temp_dir):
+        """Skill restore on preset removal must also resolve command tokens (issue #2717)."""
+        self._write_init_options(project_dir, ai="claude")
+        skills_dir = project_dir / ".claude" / "skills"
+        self._create_skill(skills_dir, "speckit-specify")
+
+        core_cmds = project_dir / ".specify" / "templates" / "commands"
+        core_cmds.mkdir(parents=True, exist_ok=True)
+        (core_cmds / "specify.md").write_text(
+            "---\ndescription: Core specify\n---\n\n"
+            "Then run `__SPECKIT_COMMAND_PLAN__`.\n"
+        )
+
+        preset_dir = self._create_command_preset(
+            temp_dir,
+            "cmdref-restore",
+            "speckit.specify",
+            "Override specify",
+            "Override body\n",
+        )
+        manager = PresetManager(project_dir)
+        manager.install_from_directory(preset_dir, "0.1.5")
+        manager.remove("cmdref-restore")
+
+        content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()
+        assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on restore"
+        assert "/speckit-plan" in content
+
+    def test_reconcile_override_skill_resolves_command_refs(self, project_dir, temp_dir):
+        """Reconcile's project-override restore must resolve command tokens (issue #2717).
+
+        When a preset that overrode a command is removed and a project override
+        becomes the winning layer, ``_reconcile_skills`` rewrites the skill from
+        the override body — which must also render ``__SPECKIT_COMMAND_*__`` tokens.
+        """
+        self._write_init_options(project_dir, ai="claude")
+        skills_dir = project_dir / ".claude" / "skills"
+        self._create_skill(skills_dir, "speckit-specify")
+
+        # Project override wins once the preset is removed; its body carries a
+        # command cross-reference token. No core template exists for "specify",
+        # so the skill is restored exclusively via the reconcile override branch.
+        overrides_dir = project_dir / ".specify" / "templates" / "overrides"
+        overrides_dir.mkdir(parents=True, exist_ok=True)
+        (overrides_dir / "speckit.specify.md").write_text(
+            "---\ndescription: Override specify\n---\n\n"
+            "Then run `__SPECKIT_COMMAND_PLAN__`.\n"
+        )
+
+        preset_dir = self._create_command_preset(
+            temp_dir,
+            "cmdref-reconcile",
+            "speckit.specify",
+            "Preset specify",
+            "Preset body\n",
+        )
+        manager = PresetManager(project_dir)
+        manager.install_from_directory(preset_dir, "0.1.5")
+        manager.remove("cmdref-reconcile")
+
+        content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()
+        assert "override:speckit.specify" in content, "skill should be restored from the project override"
+        assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on reconcile"
+        assert "/speckit-plan" in content
+
+    def test_extension_restore_resolves_command_refs(self, project_dir, temp_dir):
+        """Extension-backed skill restore must resolve command tokens (issue #2717).
+
+        When a preset override is removed and the skill is restored from an
+        extension command body, ``__SPECKIT_COMMAND_*__`` tokens in that body
+        must render as slash-command invocations like the core-template path.
+        """
+        self._write_init_options(project_dir, ai="claude")
+        skills_dir = project_dir / ".claude" / "skills"
+        self._create_skill(skills_dir, "speckit-fakeext-cmd", body="original extension skill")
+
+        extension_dir = project_dir / ".specify" / "extensions" / "fakeext"
+        (extension_dir / "commands").mkdir(parents=True, exist_ok=True)
+        (extension_dir / "commands" / "cmd.md").write_text(
+            "---\ndescription: Extension fakeext cmd\n---\n\n"
+            "Then run `__SPECKIT_COMMAND_PLAN__`.\n"
+        )
+        extension_manifest = {
+            "schema_version": "1.0",
+            "extension": {
+                "id": "fakeext",
+                "name": "Fake Extension",
+                "version": "1.0.0",
+                "description": "Test",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "commands": [
+                    {
+                        "name": "speckit.fakeext.cmd",
+                        "file": "commands/cmd.md",
+                        "description": "Fake extension command",
+                    }
+                ]
+            },
+        }
+        with open(extension_dir / "extension.yml", "w") as f:
+            yaml.dump(extension_manifest, f)
+
+        preset_dir = self._create_command_preset(
+            temp_dir,
+            "cmdref-ext-restore",
+            "speckit.fakeext.cmd",
+            "Override fakeext cmd",
+            "Override body\n",
+        )
+        manager = PresetManager(project_dir)
+        manager.install_from_directory(preset_dir, "0.1.5")
+        manager.remove("cmdref-ext-restore")
+
+        content = (skills_dir / "speckit-fakeext-cmd" / "SKILL.md").read_text()
+        assert "source: extension:fakeext" in content, "skill should be restored from the extension"
+        assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on extension restore"
+        assert "/speckit-plan" in content
+
    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")
--- a/tests/test_setup_plan_no_overwrite.py
+++ b/tests/test_setup_plan_no_overwrite.py
@@ -0,0 +1,216 @@
+"""Tests for setup-plan preserving existing plan.md (#2653)."""
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from tests.conftest import requires_bash
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+COMMON_SH = PROJECT_ROOT / "scripts" / "bash" / "common.sh"
+SETUP_PLAN_SH = PROJECT_ROOT / "scripts" / "bash" / "setup-plan.sh"
+COMMON_PS = PROJECT_ROOT / "scripts" / "powershell" / "common.ps1"
+SETUP_PLAN_PS = PROJECT_ROOT / "scripts" / "powershell" / "setup-plan.ps1"
+PLAN_TEMPLATE = PROJECT_ROOT / "templates" / "plan-template.md"
+
+HAS_PWSH = shutil.which("pwsh") is not None
+_POWERSHELL = shutil.which("powershell.exe") or shutil.which("powershell")
+
+
+def _install_bash_scripts(repo: Path) -> None:
+    d = repo / ".specify" / "scripts" / "bash"
+    d.mkdir(parents=True, exist_ok=True)
+    shutil.copy(COMMON_SH, d / "common.sh")
+    shutil.copy(SETUP_PLAN_SH, d / "setup-plan.sh")
+
+
+def _install_ps_scripts(repo: Path) -> None:
+    d = repo / ".specify" / "scripts" / "powershell"
+    d.mkdir(parents=True, exist_ok=True)
+    shutil.copy(COMMON_PS, d / "common.ps1")
+    shutil.copy(SETUP_PLAN_PS, d / "setup-plan.ps1")
+
+
+def _minimal_templates(repo: Path) -> None:
+    tdir = repo / ".specify" / "templates"
+    tdir.mkdir(parents=True, exist_ok=True)
+    shutil.copy(PLAN_TEMPLATE, tdir / "plan-template.md")
+
+
+def _clean_env() -> dict[str, str]:
+    env = os.environ.copy()
+    for key in list(env):
+        if key.startswith("SPECIFY_"):
+            env.pop(key)
+    return env
+
+
+def _git_init(repo: Path) -> None:
+    subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
+    subprocess.run(
+        ["git", "config", "user.email", "test@example.com"], cwd=repo, check=True
+    )
+    subprocess.run(["git", "config", "user.name", "Test User"], cwd=repo, check=True)
+    subprocess.run(
+        ["git", "commit", "--allow-empty", "-m", "init", "-q"], cwd=repo, check=True
+    )
+
+
+@pytest.fixture
+def plan_repo(tmp_path: Path) -> Path:
+    repo = tmp_path / "proj"
+    repo.mkdir()
+    _git_init(repo)
+    subprocess.run(
+        ["git", "checkout", "-q", "-b", "001-my-feature"],
+        cwd=repo,
+        check=True,
+    )
+    (repo / ".specify").mkdir()
+    _minimal_templates(repo)
+    _install_bash_scripts(repo)
+    _install_ps_scripts(repo)
+    return repo
+
+
+# ── Bash tests ────────────────────────────────────────────────────────────
+
+
+@requires_bash
+def test_setup_plan_creates_plan_when_missing(plan_repo: Path) -> None:
+    """First run must create plan.md from the template."""
+    script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"
+    result = subprocess.run(
+        ["bash", str(script), "--json"],
+        cwd=plan_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode == 0, result.stderr
+    data = json.loads(result.stdout)
+    plan_path = Path(data["IMPL_PLAN"])
+    assert plan_path.is_file()
+    # Template content should be present
+    content = plan_path.read_text(encoding="utf-8")
+    assert len(content) > 0
+
+
+@requires_bash
+def test_setup_plan_preserves_existing_plan(plan_repo: Path) -> None:
+    """Rerun must not overwrite an existing plan.md."""
+    feat = plan_repo / "specs" / "001-my-feature"
+    feat.mkdir(parents=True)
+    existing_content = "# My carefully authored plan\n\nDo not overwrite me.\n"
+    (feat / "plan.md").write_text(existing_content, encoding="utf-8")
+
+    script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"
+    result = subprocess.run(
+        ["bash", str(script), "--json"],
+        cwd=plan_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode == 0, result.stderr
+    # Plan must be unchanged
+    assert (feat / "plan.md").read_text(encoding="utf-8") == existing_content
+
+
+@requires_bash
+def test_setup_plan_skip_message_on_stderr_in_json_mode(plan_repo: Path) -> None:
+    """In --json mode, status messages must go to stderr, not stdout."""
+    feat = plan_repo / "specs" / "001-my-feature"
+    feat.mkdir(parents=True)
+    (feat / "plan.md").write_text("# existing\n", encoding="utf-8")
+
+    script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"
+    result = subprocess.run(
+        ["bash", str(script), "--json"],
+        cwd=plan_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode == 0, result.stderr
+    # stdout must be valid JSON (no status messages mixed in)
+    data = json.loads(result.stdout)
+    assert "IMPL_PLAN" in data
+    # The skip message should be on stderr
+    assert "already exists" in result.stderr
+
+
+@requires_bash
+def test_setup_plan_json_parseable_on_first_run(plan_repo: Path) -> None:
+    """In --json mode, first-run stdout must be parseable JSON (no status on stdout)."""
+    script = plan_repo / ".specify" / "scripts" / "bash" / "setup-plan.sh"
+    result = subprocess.run(
+        ["bash", str(script), "--json"],
+        cwd=plan_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode == 0, result.stderr
+    data = json.loads(result.stdout)
+    assert "IMPL_PLAN" in data
+    assert "Copied plan template" in result.stderr
+
+
+# ── PowerShell tests ──────────────────────────────────────────────────────
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_ps_setup_plan_creates_plan_when_missing(plan_repo: Path) -> None:
+    """First run must create plan.md from the template."""
+    script = plan_repo / ".specify" / "scripts" / "powershell" / "setup-plan.ps1"
+    exe = "pwsh" if HAS_PWSH else _POWERSHELL
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(script), "-Json"],
+        cwd=plan_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode == 0, result.stderr
+    data = json.loads(result.stdout)
+    plan_path = Path(data["IMPL_PLAN"])
+    assert plan_path.is_file()
+    content = plan_path.read_text(encoding="utf-8")
+    assert len(content) > 0
+
+
+@pytest.mark.skipif(not (HAS_PWSH or _POWERSHELL), reason="no PowerShell available")
+def test_ps_setup_plan_preserves_existing_plan(plan_repo: Path) -> None:
+    """Rerun must not overwrite an existing plan.md."""
+    feat = plan_repo / "specs" / "001-my-feature"
+    feat.mkdir(parents=True)
+    existing_content = "# My carefully authored plan\n\nDo not overwrite me.\n"
+    (feat / "plan.md").write_text(existing_content, encoding="utf-8")
+
+    script = plan_repo / ".specify" / "scripts" / "powershell" / "setup-plan.ps1"
+    exe = "pwsh" if HAS_PWSH else _POWERSHELL
+    result = subprocess.run(
+        [exe, "-NoProfile", "-File", str(script), "-Json"],
+        cwd=plan_repo,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=_clean_env(),
+    )
+    assert result.returncode == 0, result.stderr
+    assert (feat / "plan.md").read_text(encoding="utf-8") == existing_content
+    # stdout must be valid JSON (no status messages mixed in)
+    data = json.loads(result.stdout)
+    assert "IMPL_PLAN" in data
+    # The skip message should be on stderr
+    assert "already exists" in result.stderr
--- a/tests/test_workflows.py
+++ b/tests/test_workflows.py
@@ -333,6 +333,44 @@ class TestExpressions:
        result = evaluate_expression("{{ steps.tasks.output.task_list[0].file }}", ctx)
        assert result == "a.md"

+    def test_context_run_id_resolves(self):
+        """``{{ context.run_id }}`` resolves to ``StepContext.run_id``.
+
+        Locks the contract from issue #2590: workflow templates can
+        reference the engine-assigned run id for telemetry, artifact
+        metadata, or per-run scratch isolation.
+        """
+        from specify_cli.workflows.expressions import evaluate_expression
+        from specify_cli.workflows.base import StepContext
+
+        ctx = StepContext(run_id="a1b2c3d4")
+        assert evaluate_expression("{{ context.run_id }}", ctx) == "a1b2c3d4"
+
+    def test_context_run_id_defaults_to_empty_when_unset(self):
+        """``{{ context.run_id }}`` resolves to ``""`` when no run is
+        active (dry-run, validation, ad-hoc evaluator usage) rather
+        than raising — workflows referencing the variable never error
+        outside a run context.
+        """
+        from specify_cli.workflows.expressions import evaluate_expression
+        from specify_cli.workflows.base import StepContext
+
+        # No run_id set on the context.
+        ctx = StepContext()
+        assert evaluate_expression("{{ context.run_id }}", ctx) == ""
+
+    def test_context_run_id_string_interpolation(self):
+        """Run id interpolates inside a larger template string — the
+        common pattern for stamping shell commands and artifact paths
+        with the run id.
+        """
+        from specify_cli.workflows.expressions import evaluate_expression
+        from specify_cli.workflows.base import StepContext
+
+        ctx = StepContext(run_id="deadbeef")
+        result = evaluate_expression("RUN_ID={{ context.run_id }}", ctx)
+        assert result == "RUN_ID=deadbeef"
+

 # ===== Integration Dispatch Tests =====

@@ -2154,6 +2192,147 @@ steps:
        assert "retry-loop:step-b:2" in state.step_results


+# ===== context.run_id Tests =====
+#
+# End-to-end coverage for the `{{ context.run_id }}` template
+# variable introduced in issue #2590. Locks resolution inside the
+# three step types the acceptance criteria called out — shell `run:`,
+# command `input.args:`, and switch `expression:` — plus the
+# "workflow doesn't reference it" backward-compat path.
+
+
+class TestContextRunId:
+    """End-to-end tests for `{{ context.run_id }}` in workflow YAML."""
+
+    def test_shell_run_resolves_run_id(self, project_dir):
+        """`run: "echo {{ context.run_id }}"` substitutes the
+        engine-assigned run id into the spawned shell, and the
+        same value appears on `state.run_id`.
+        """
+        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "stamp-run-id"
+  name: "Stamp Run Id"
+  version: "1.0.0"
+steps:
+  - id: stamp
+    type: shell
+    run: "echo RUN_ID={{ context.run_id }}"
+""")
+        engine = WorkflowEngine(project_dir)
+        state = engine.execute(definition, run_id="abc12345")
+
+        assert state.run_id == "abc12345"
+        stdout = state.step_results["stamp"]["output"]["stdout"]
+        assert stdout.strip() == "RUN_ID=abc12345"
+
+    def test_command_input_args_resolves_run_id(self, project_dir):
+        """`input.args: "{{ context.run_id }}"` is resolved by
+        `CommandStep` and recorded in step output, even when CLI
+        dispatch is unavailable (no integration installed). Covers
+        the artifact-metadata use case from the issue.
+        """
+        from unittest.mock import patch
+        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "command-stamp"
+  name: "Command Stamp"
+  version: "1.0.0"
+  integration: claude
+steps:
+  - id: tag-artifact
+    command: speckit.specify
+    input:
+      args: "{{ context.run_id }}"
+""")
+        engine = WorkflowEngine(project_dir)
+        with patch(
+            "specify_cli.workflows.steps.command.shutil.which",
+            return_value=None,
+        ):
+            state = engine.execute(definition, run_id="cafef00d")
+
+        # Even when dispatch fails (no CLI), the resolved input is
+        # recorded so downstream observers see the run id in artifact
+        # metadata.
+        assert state.step_results["tag-artifact"]["output"]["input"]["args"] == "cafef00d"
+
+    def test_switch_expression_matches_on_run_id(self, project_dir):
+        """`switch` over `{{ context.run_id }}` matches against case
+        keys, and the nested branch can ALSO reference
+        `{{ context.run_id }}`. Demonstrates the run id is a
+        first-class value in the expression engine (not just a
+        string-interpolation token) AND that it propagates into
+        nested step execution via the recursive `_execute_steps`
+        traversal.
+        """
+        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+        from specify_cli.workflows.base import RunStatus
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "switch-on-run-id"
+  name: "Switch On Run Id"
+  version: "1.0.0"
+steps:
+  - id: route
+    type: switch
+    expression: "{{ context.run_id }}"
+    cases:
+      target-run:
+        - id: matched-branch
+          type: shell
+          run: "echo nested-run-id={{ context.run_id }}"
+    default:
+      - id: default-branch
+        type: shell
+        run: "echo defaulted"
+""")
+        engine = WorkflowEngine(project_dir)
+        state = engine.execute(definition, run_id="target-run")
+
+        assert state.status == RunStatus.COMPLETED
+        assert state.step_results["route"]["output"]["matched_case"] == "target-run"
+        assert "matched-branch" in state.step_results
+        assert "default-branch" not in state.step_results
+        # The nested branch sees the same run id — propagation through
+        # recursive `_execute_steps` is intact.
+        nested_stdout = state.step_results["matched-branch"]["output"]["stdout"]
+        assert nested_stdout.strip() == "nested-run-id=target-run"
+
+    def test_workflow_without_context_reference_unchanged(self, project_dir):
+        """Workflows that do not reference `{{ context.run_id }}`
+        continue to run exactly as before. Locks the byte-equivalent
+        default required by the issue's acceptance criteria.
+        """
+        from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
+        from specify_cli.workflows.base import RunStatus
+
+        definition = WorkflowDefinition.from_string("""
+schema_version: "1.0"
+workflow:
+  id: "no-context-ref"
+  name: "No Context Ref"
+  version: "1.0.0"
+steps:
+  - id: only-step
+    type: shell
+    run: "echo hello"
+""")
+        engine = WorkflowEngine(project_dir)
+        state = engine.execute(definition)
+
+        assert state.status == RunStatus.COMPLETED
+        assert state.step_results["only-step"]["output"]["stdout"].strip() == "hello"
+
+
 # ===== State Persistence Tests =====

 class TestRunState:
--- a/workflows/README.md
+++ b/workflows/README.md
@@ -239,6 +239,33 @@ message: "{{ status | default('pending') }}"

 Supported filters: `default`, `join`, `contains`, `map`.

+### Runtime Context
+
+`{{ context.* }}` exposes engine-managed runtime metadata for the
+current run:
+
+| Variable | Description |
+|----------|-------------|
+| `context.run_id` | The current workflow run id (the same value Spec Kit prints as `Run ID:` at the end of `workflow run`). Auto-generated runs are 8-character hex from `uuid4`; operator-supplied ids may be any alphanumeric string with hyphens or underscores. Empty string outside a run context. |
+
+```yaml
+# Stamp telemetry events with the run id for cross-system join.
+- id: emit-event
+  type: shell
+  run: 'echo "{\"run_id\":\"{{ context.run_id }}\",\"event\":\"started\"}" >> events.jsonl'
+
+# Per-run scratch directory.
+- id: prep-scratch
+  type: shell
+  run: 'mkdir -p /tmp/run-{{ context.run_id }}'
+
+# Pass run id into a command for artifact metadata.
+- id: tag-artifact
+  command: speckit.specify
+  input:
+    args: "{{ context.run_id }}"
+```
+
 ## Input Types

 Workflow inputs are type-checked and coerced from CLI string values:
Author	SHA1	Message	Date
github-actions[bot]	424a14e655	chore: bump version to 0.8.16	2026-05-27 21:34:55 +00:00
Manfred Riem	b58a121771	docs: update landing page stats and branch naming convention (#2727 ) * docs: update landing page stats and branch naming convention - Update community extensions: 91 → 105 - Update extension authors: 50+ → 60+ - Update presets: 18 → 22 - Update GitHub stars: 96K+ → 106K+ - Add last-updated date to landing page - Clarify branch naming convention for PR-only changes * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>	2026-05-27 16:33:33 -05:00
Huy Do	c6afe4cde1	feat(workflows): expose {{ context.run_id }} template variable (#2664 ) * feat(workflows): expose `{{ context.run_id }}` template variable Closes #2590. Surfaces the engine-assigned run id (the same 8-character hex string Spec Kit prints as `Run ID:` at the end of `workflow run`) as a workflow template variable so YAML authors can reference it from shell `run:`, command `input.args:`, switch `expression:`, and any other field that already evaluates `{{ ... }}` templates. ### Why The run id is the natural join key between a Spec Kit workflow run and downstream artifacts, telemetry, or per-run scratch state. Today the operator sees it in stdout but workflows themselves cannot reference it — there was no way to stamp a log line, name a scratch directory, or tag an artifact with the same id Spec Kit assigned. The three motivating use cases from the issue: 1. Telemetry / observability — stamp logs and events with the run id so external systems can join workflow runs to downstream artifacts. 2. Per-run scratch / isolation — interactive operator commands that need their own state directory under `/tmp/run-<id>/`. 3. Run-id in artifact metadata — stable join key from artifact back to the producing run. ### Implementation `StepContext.run_id` is already populated by `WorkflowEngine` in both `execute()` and `resume()`. The only gap was the template namespace builder. `_build_namespace` (in `workflows/expressions.py`) now adds a `context` key alongside the existing `inputs`, `steps`, `item`, and `fan_in` namespaces: ```python ns["context"] = {"run_id": run_id} ``` The value is always present (even outside a run) and falls back to an empty string when no run is active. Workflows referencing `{{ context.run_id }}` therefore never error — a hard requirement from the issue's acceptance criteria for dry-run, validation, and ad-hoc evaluator usage. ### Default behaviour preserved Workflows that do not reference `{{ context.run_id }}` are byte-equivalent to before this change. The `context` namespace is added unconditionally to keep template resolution branch-free, but its presence has no observable effect when nothing references it. ### Tests `TestExpressions` (unit-level) gains three tests: - `test_context_run_id_resolves` — direct lookup against a `StepContext(run_id=...)`. - `test_context_run_id_defaults_to_empty_when_unset` — graceful default outside a run context. - `test_context_run_id_string_interpolation` — mixed template (e.g. `"RUN_ID={{ context.run_id }}"`). `TestContextRunId` (end-to-end) covers the three step types the acceptance criteria called out: - `test_shell_run_resolves_run_id` — `run:` field substitution, verified via captured stdout. - `test_command_input_args_resolves_run_id` — `input.args:` resolution, captured in step output even when CLI dispatch is unavailable (the artifact-metadata use case). - `test_switch_expression_matches_on_run_id` — switch matches against the resolved value, proving the run id is a first-class value in the expression engine, not just an interpolation token. - `test_workflow_without_context_reference_unchanged` — locks the byte-equivalent default required by the issue. ### Docs `workflows/README.md` gains a "Runtime Context" subsection under "Expressions" documenting the new namespace and the three canonical use patterns (telemetry, per-run scratch, artifact metadata). * test(workflows): drop inline double-quotes in run_id shell tests `test_shell_run_resolves_run_id` and `test_switch_expression_matches_on_run_id` used `run: 'echo "RUN_ID={{ context.run_id }}"'` with inner double-quotes around the echo argument. Bash/sh strips those quotes before invoking echo, but cmd.exe (used on Windows when `shell=True`) treats them as literal characters and emits `"RUN_ID=abc12345"` — failing the exact-match assertion. Linux passed; all three Windows-latest matrix entries failed with `assert '"RUN_ID=abc12345"' == 'RUN_ID=abc12345'`. Resolve by dropping the inner double-quotes (the value has no spaces or shell metacharacters) and wrapping the YAML scalar in plain double-quotes the same way other shell-step tests in this file do (e.g. `run: "echo b-saw-..."`). Behaviour-equivalent on POSIX, portable to cmd.exe.	2026-05-27 13:00:58 -05:00
Huy Bui Minh	66884db85b	fix: resolve __SPECKIT_COMMAND___ refs in preset skill rendering (#2717 ) (#2718 ) fix: resolve __SPECKIT_COMMAND___ refs in preset skill rendering (#2717) The preset skill layer mirrors command templates into SKILL.md files but only ran resolve_skill_placeholders(), leaving command cross-references as raw __SPECKIT_COMMAND_<NAME>__ placeholders instead of rendering them as /speckit-<cmd> the way CommandRegistrar.register_commands() does. As a result, presets that override core commands under the agent skill layer (e.g. Claude --ai-skills) leaked the raw tokens into SKILL.md. Add a shared PresetManager._resolve_skill_command_refs() helper that maps the agent's invoke separator to IntegrationBase.resolve_command_refs(), and call it right after resolve_skill_placeholders() in every preset skill-rendering path: _register_skills() (install), the _reconcile_skills() override-restoration block, and both _unregister_skills() restore paths. This mirrors register_commands() and addresses the path divergence flagged in #1976. Add regression tests covering the install and restore paths. AI assistance: authored with Claude Code (Anthropic) — analysis, patch, and tests. Verified via the existing pytest suite plus a manual CLI install and remove cycle on a Claude --ai-skills project. test: cover reconcile-override and extension restore command-ref paths (#2718 review) Copilot review flagged that the install and core-template restore paths gained regression tests, but the reconcile project-override branch and the extension-backed restore branch were uncovered. Add focused tests for both: - test_reconcile_override_skill_resolves_command_refs: a project override wins after preset removal; _reconcile_skills must render command refs. - test_extension_restore_resolves_command_refs: a skill restored from an extension command body must also render command refs. Both fail on main and pass with the fix in `8dd93c0`.	2026-05-27 12:49:54 -05:00
Manfred Riem	9af5411b4e	Add Workflow Preset to community catalog (#2725 ) * Add Workflow Preset to community catalog Add workflow-preset submitted by @bigsmartben to: - presets/catalog.community.json (alphabetical order) - docs/community/presets.md community presets table Closes #2618 * Fix Requires column: use — for no required extensions The Requires column lists required extensions, not the Spec Kit version. This preset has no extension dependencies.	2026-05-27 09:52:57 -05:00
Manfred Riem	3227b9660e	fix: paths-only skips branch validation, setup-plan preserves existing plan (#2672 ) * fix: paths-only skips branch validation, setup-plan preserves existing plan (#2653) - check-prerequisites.sh/ps1: move branch validation after --paths-only early exit so --paths-only returns paths without requiring a spec branch - setup-plan.sh/ps1: skip template copy when plan.md already exists to prevent overwriting user-authored plans on reruns - setup-plan.sh: send status messages to stderr in --json mode so stdout remains parseable JSON - Add tests for both fixes (bash + PowerShell) * fix: remove trailing whitespace in PowerShell scripts * fix: route PS skip message to stderr in -Json mode, add PS JSON assertions Address review: setup-plan.ps1 Write-Output polluted stdout in -Json mode when plan.md already existed. Use [Console]::Error.WriteLine() when -Json is set. Add json.loads + stderr assertions to the PS rerun test to catch regressions. * fix: use Test-Path -PathType Leaf for plan existence check Bare Test-Path matches directories too, which would silently skip plan creation if a directory existed at the plan.md path.	2026-05-27 07:17:34 -05:00
Jaimin	d116ce2b0a	docs: fix broken pipx homepage URLs to point to pipx.pypa.io (#2670 )	2026-05-27 07:10:38 -05:00
Manfred Riem	eb11dd2d64	Update Architecture Guard extension to v1.8.9 (#2723 ) Update architecture-guard extension submitted by @DyanGalih: - extensions/catalog.community.json (version, download_url, description, tags) - docs/community/extensions.md community extensions table Closes #2696	2026-05-27 06:42:35 -05:00
Manfred Riem	9816f902ca	Re-validate spec quality checklist after clarify updates spec (#2715 ) * Re-validate spec quality checklist after clarify updates spec After clarify modifies spec.md, the existing checklists/requirements.md (generated by specify) can become stale. Items like 'No [NEEDS CLARIFICATION] markers remain' may now pass, and newly added requirements aren't reflected in the checklist evaluation. Add step 8 to the clarify command that re-validates the spec quality checklist against the updated spec after each clarification session: - Check/uncheck items based on current spec state - Report before/after pass counts in the completion report - Skip silently if no checklist exists Fixes #2693 * Address review: scope to checkbox lines, use FEATURE_DIR path - Constrain re-validation to GitHub task-list checkbox lines only (- [ ] / - [x] outside code fences), ignoring headings, notes, and non-checkbox content - Define pass counts as checked/total checkbox items - Use FEATURE_DIR/checklists/requirements.md in Done When for consistency with the rest of the template * Address review: handle regressions in checklist revalidation - Clarify that each checkbox is set based solely on current spec state, regardless of prior marker (checked->unchecked is possible) - Completion report now lists both newly passing items and regressions (checked->unchecked) so users see what became non-compliant * Address review: case-insensitive checkboxes, preserve file verbatim - Accept [x], [X], and leading whitespace for nested task items - Explicitly state only the [ ]/[x] marker is toggled; all other file content (headings, metadata, notes, ordering, whitespace) must remain unchanged to avoid noisy diffs * Address review: track per-item state, preserve marker case - Add explicit before-snapshot step to capture each item's prior marker state before re-evaluation - Compute three lists for the report: newly passing, regressions, and still unchecked - Only toggle markers whose checked/unchecked state actually changes; preserve existing case ([x]/[X]) when state is unchanged to avoid cosmetic diffs	2026-05-27 06:31:27 -05:00
Manfred Riem	3cb7027fab	chore: release 0.8.15, begin 0.8.16.dev0 development (#2722 ) * chore: bump version to 0.8.15 * chore: begin 0.8.16.dev0 development --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>	2026-05-27 06:30:37 -05:00