Merge remote-tracking branch 'origin/main' into add-dotdog-extension-50d2a7dab9bb17c6

Copilot · web-flow · commit df062dda2552 · 2026-07-16T12:50:51.000Z
# Conflicts:
#	docs/community/extensions.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,21 @@
 
 <!-- insert new changelog below this comment -->
 
+## [0.12.17] - 2026-07-16
+
+### Changed
+
+- fix(extensions): resolve __SPECKIT_COMMAND tokens in auto-registered skills (#3544)
+- fix(workflows): fail if/switch steps on non-list branch instead of crashing (#3515)
+- feat(integrations): add Grok Build skills-based integration (#3535)
+- fix(extensions/git): reject negative -Number in create-new-feature-branch.ps1 (#3538)
+- test: cover preset constitution seeding through init CLI (#3297)
+- fix(integration): preserve ai_skills on `use` for skills-mode Copilot (#3550) (#3551)
+- [extension] Add Figma Starter extension to community catalog (#3547)
+- [extension] Add Spec-Kit BDD extension to community catalog (#3548)
+- [extension] Update Quality Gates (Enforcement Layer) extension to v0.3.2 (#3542)
+- chore: release 0.12.16, begin 0.12.17.dev0 development (#3549)
+
 ## [0.12.16] - 2026-07-15
 
 ### Changed
diff --git a/docs/community/extensions.md b/docs/community/extensions.md
@@ -51,7 +51,7 @@ The following community-contributed extensions are available in [`catalog.commun
 | Confluence Extension | Create a doc in Confluence summarizing the specifications and planning files | `integration` | Read+Write | [spec-kit-confluence](https://github.com/aaronrsun/spec-kit-confluence) |
 | Cost Tracker | Track real LLM dollar cost across SDD workflows — per-feature budgets, per-integration comparison, and finance-ready exports | `visibility` | Read+Write | [spec-kit-cost](https://github.com/Quratulain-bilal/spec-kit-cost) |
 | Data Model Diagram | Generates Mermaid ER diagrams from Spec Kit data models after planning | `docs` | Read+Write | [spec-kit-data-model-diagram](https://github.com/benizzio/spec-kit-data-model-diagram) |
-| DocGuard — CDD Enforcement | Doc-integrity engine with MCP server, SARIF output, and zero-LLM core. Validates, scores, and traces documentation against code — 24 validators, stable finding codes, spec-kit hooks. Pure Node.js. | `docs` | Read+Write | [spec-kit-docguard](https://github.com/raccioly/docguard) |
+| DocGuard — CDD Enforcement | The only doc-integrity engine with an MCP server, SARIF/JUnit output, and a deterministic zero-LLM core. Validates, scores, and traces documentation against code — 27 validators, stable finding codes, adoption baseline for legacy repos, compliance-evidence reports, GitHub Action with PR annotations, spec-kit hooks. Pure Node.js, one pinned dep. | `docs` | Read+Write | [spec-kit-docguard](https://github.com/raccioly/docguard) |
 | Dotdog | Import GitHub Spec Kit artifacts into local knowledge graphs for validation, analysis, search, and MCP queries. | `docs` | Read+Write | [dotdog](https://github.com/specdog/dotdog) |
 | EARS Requirements Syntax | Author, lint, and convert requirements using EARS - the five industry-standard sentence patterns for unambiguous, testable requirements | `docs` | Read+Write | [spec-kit-ears](https://github.com/dhruv-15-03/spec-kit-ears) |
 | Extensify | Create and validate extensions and extension catalogs | `process` | Read+Write | [extensify](https://github.com/mnriem/spec-kit-extensions/tree/main/extensify) |
diff --git a/extensions/catalog.community.json b/extensions/catalog.community.json
@@ -1166,10 +1166,10 @@
     "docguard": {
       "name": "DocGuard — CDD Enforcement",
       "id": "docguard",
-      "description": "Doc-integrity engine with MCP server, SARIF output, and zero-LLM core. Validates, scores, and traces documentation against code — 24 validators, stable finding codes, spec-kit hooks. Pure Node.js.",
+      "description": "The only doc-integrity engine with an MCP server, SARIF/JUnit output, and a deterministic zero-LLM core. Validates, scores, and traces documentation against code — 27 validators, stable finding codes, adoption baseline for legacy repos, compliance-evidence reports, GitHub Action with PR annotations, spec-kit hooks. Pure Node.js, one pinned dep.",
       "author": "raccioly",
-      "version": "0.32.0",
-      "download_url": "https://github.com/raccioly/docguard/releases/download/v0.32.0/spec-kit-docguard-v0.32.0.zip",
+      "version": "0.33.0",
+      "download_url": "https://github.com/raccioly/docguard/releases/download/v0.33.0/spec-kit-docguard-v0.33.0.zip",
       "repository": "https://github.com/raccioly/docguard",
       "homepage": "https://www.npmjs.com/package/docguard-cli",
       "documentation": "https://github.com/raccioly/docguard/blob/main/extensions/spec-kit-docguard/README.md",
@@ -1213,7 +1213,7 @@
       "downloads": 0,
       "stars": 0,
       "created_at": "2026-03-13T00:00:00Z",
-      "updated_at": "2026-07-13T00:00:00Z"
+      "updated_at": "2026-07-16T00:00:00Z"
     },
     "doctor": {
       "name": "Project Health Check",
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.12.17.dev0"
+version = "0.12.18.dev0"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 readme = "README.md"
 requires-python = ">=3.11"
diff --git a/src/specify_cli/extensions/__init__.py b/src/specify_cli/extensions/__init__.py
@@ -1004,6 +1004,7 @@ def _register_extension_skills(
         from .. import load_init_options
         from ..agents import CommandRegistrar
         from ..integrations import get_integration
+        from ..integrations.base import IntegrationBase
 
         written: List[str] = []
         opts = load_init_options(self.project_root)
@@ -1015,6 +1016,30 @@ def _register_extension_skills(
         registrar = CommandRegistrar()
         agent_config = registrar.AGENT_CONFIGS.get(selected_ai, {})
         integration = get_integration(selected_ai)
+        ai_skills_enabled = is_ai_skills_enabled(opts)
+
+        def _resolve_command_ref_tokens(body: str) -> str:
+            """Resolve explicit command-ref tokens with the active skill style."""
+
+            def _replacement(match: re.Match[str]) -> str:
+                command_name = "speckit." + match.group(1).lower().replace("_", ".")
+                if is_dollar_skills_agent(selected_ai, ai_skills_enabled):
+                    return "$" + command_name.replace("speckit.", "speckit-").replace(
+                        ".", "-"
+                    )
+                if is_slash_skills_agent(selected_ai, ai_skills_enabled):
+                    return "/" + command_name.replace("speckit.", "speckit-").replace(
+                        ".", "-"
+                    )
+                if integration is not None:
+                    return integration.build_command_invocation(command_name)
+                return IntegrationBase.resolve_command_refs(
+                    match.group(0), agent_config.get("invoke_separator", ".")
+                )
+
+            return re.sub(
+                r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_]*)__", _replacement, body
+            )
 
         for cmd_info in manifest.commands:
             cmd_name = cmd_info["name"]
@@ -1086,6 +1111,7 @@ def _register_extension_skills(
             body = registrar.resolve_skill_placeholders(
                 selected_ai, frontmatter, body, self.project_root, extension_id=manifest.id
             )
+            body = _resolve_command_ref_tokens(body)
 
             original_desc = frontmatter.get("description", "")
             description = original_desc or f"Extension command: {cmd_name}"
diff --git a/src/specify_cli/workflows/steps/if_then/__init__.py b/src/specify_cli/workflows/steps/if_then/__init__.py
@@ -22,10 +22,33 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
         result = evaluate_condition(condition, context)
 
         if result:
+            branch_name = "then"
             branch = config.get("then", [])
         else:
+            branch_name = "else"
             branch = config.get("else", [])
 
+        # The engine does not auto-validate step config (see
+        # ``WorkflowEngine.load_workflow``), and it feeds ``next_steps`` straight
+        # into ``_execute_steps`` which iterates them as step mappings. A
+        # non-list branch (a single mapping or scalar authoring mistake) would
+        # otherwise be iterated element-wise — a dict yields its string keys, a
+        # str its characters — and crash the whole run with AttributeError on
+        # ``.get()``. ``validate`` already rejects a non-list branch; fail this
+        # step loudly on an unvalidated run instead, mirroring the switch/fan-out
+        # steps. A missing ``else`` defaults to ``[]`` and stays valid.
+        if branch is None and branch_name == "else":
+            branch = []
+        elif not isinstance(branch, list):
+            return StepResult(
+                status=StepStatus.FAILED,
+                output={"condition_result": result},
+                error=(
+                    f"If step {config.get('id', '?')!r}: {branch_name!r} must be "
+                    f"a list of steps, got {type(branch).__name__}."
+                ),
+            )
+
         return StepResult(
             status=StepStatus.COMPLETED,
             output={"condition_result": result},
diff --git a/src/specify_cli/workflows/steps/switch/__init__.py b/src/specify_cli/workflows/steps/switch/__init__.py
@@ -42,6 +42,10 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
             )
         for case_key, case_steps in cases.items():
             if str(case_key) == str_value:
+                if not isinstance(case_steps, list):
+                    return self._non_list_branch_failure(
+                        config, f"case {str(case_key)!r}", case_steps, value
+                    )
                 return StepResult(
                     status=StepStatus.COMPLETED,
                     output={"matched_case": str(case_key), "expression_value": value},
@@ -50,12 +54,41 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
 
         # Default fallback
         default_steps = config.get("default", [])
+        if default_steps is None:
+            default_steps = []
+        elif not isinstance(default_steps, list):
+            return self._non_list_branch_failure(
+                config, "'default'", default_steps, value
+            )
         return StepResult(
             status=StepStatus.COMPLETED,
             output={"matched_case": "__default__", "expression_value": value},
             next_steps=default_steps,
         )
 
+    @staticmethod
+    def _non_list_branch_failure(
+        config: dict[str, Any], branch_label: str, branch: Any, value: Any
+    ) -> StepResult:
+        """Fail the step for a non-list branch instead of crashing the run.
+
+        ``validate`` rejects a non-list case/default branch, but the engine does
+        not auto-validate and feeds ``next_steps`` straight into
+        ``_execute_steps``, which iterates them as step mappings. A non-list
+        branch would be iterated element-wise (a dict yields its keys, a str its
+        characters) and crash the whole run with AttributeError on ``.get()``.
+        Fail this step loudly on an unvalidated run instead, mirroring the
+        non-mapping ``cases`` guard above.
+        """
+        return StepResult(
+            status=StepStatus.FAILED,
+            output={"matched_case": None, "expression_value": value},
+            error=(
+                f"Switch step {config.get('id', '?')!r}: {branch_label} must be "
+                f"a list of steps, got {type(branch).__name__}."
+            ),
+        )
+
     def validate(self, config: dict[str, Any]) -> list[str]:
         errors = super().validate(config)
         if "expression" not in config:
diff --git a/tests/test_extension_skills.py b/tests/test_extension_skills.py
@@ -970,6 +970,113 @@ def test_skill_registration_rewrites_extension_subdir_paths(self, project_dir, t
         assert "Read agents/control" not in content
         assert "and knowledge-base/" not in content
 
+    @pytest.mark.parametrize(
+        ("ai", "expected_invocation"),
+        [
+            ("claude", "/speckit-plan"),
+            ("copilot", "/speckit-plan"),
+            ("codex", "$speckit-plan"),
+            ("kimi", "/skill:speckit-plan"),
+            ("zcode", "$speckit-plan"),
+        ],
+    )
+    def test_skill_registration_resolves_command_ref_tokens(
+        self, project_dir, temp_dir, ai, expected_invocation
+    ):
+        """Auto-registered skills should resolve explicit command ref tokens."""
+        _create_init_options(project_dir, ai=ai, ai_skills=True)
+        skills_dir = _create_skills_dir(project_dir, ai=ai)
+
+        ext_dir = temp_dir / "command-ref-ext"
+        ext_dir.mkdir()
+        manifest_data = {
+            "schema_version": "1.0",
+            "extension": {
+                "id": "command-ref-ext",
+                "name": "Command Ref Extension",
+                "version": "1.0.0",
+                "description": "Test",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "commands": [
+                    {
+                        "name": "speckit.command-ref-ext.run",
+                        "file": "commands/run.md",
+                        "description": "Run command",
+                    }
+                ]
+            },
+        }
+        with open(ext_dir / "extension.yml", "w") as f:
+            yaml.safe_dump(manifest_data, f)
+
+        (ext_dir / "commands").mkdir()
+        (ext_dir / "commands" / "run.md").write_text(
+            "---\n"
+            "description: Run command\n"
+            "---\n\n"
+            "Use __SPECKIT_COMMAND_PLAN__ before proceeding.\n"
+        )
+
+        manager = ExtensionManager(project_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        content = (skills_dir / "speckit-command-ref-ext-run" / "SKILL.md").read_text()
+        assert "__SPECKIT_COMMAND_PLAN__" not in content
+        assert expected_invocation in content
+
+    def test_skill_registration_does_not_rewrite_literal_speckit_text(
+        self, project_dir, temp_dir
+    ):
+        """Auto-registered skills should leave literal speckit text untouched."""
+        _create_init_options(project_dir, ai="codex", ai_skills=True)
+        skills_dir = _create_skills_dir(project_dir, ai="codex")
+
+        ext_dir = temp_dir / "literal-ref-ext"
+        ext_dir.mkdir()
+        manifest_data = {
+            "schema_version": "1.0",
+            "extension": {
+                "id": "literal-ref-ext",
+                "name": "Literal Ref Extension",
+                "version": "1.0.0",
+                "description": "Test",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "commands": [
+                    {
+                        "name": "speckit.literal-ref-ext.run",
+                        "file": "commands/run.md",
+                        "description": "Run command",
+                    }
+                ]
+            },
+        }
+        with open(ext_dir / "extension.yml", "w") as f:
+            yaml.safe_dump(manifest_data, f)
+
+        (ext_dir / "commands").mkdir()
+        (ext_dir / "commands" / "run.md").write_text(
+            "---\n"
+            "description: Run command\n"
+            "---\n\n"
+            "Literal slash form: /speckit.foo.bar\n"
+            "Literal skill form: /speckit-plan\n"
+            "Literal bare form: speckit.foo.bar\n"
+        )
+
+        manager = ExtensionManager(project_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        content = (skills_dir / "speckit-literal-ref-ext-run" / "SKILL.md").read_text()
+        assert "/speckit.foo.bar" in content
+        assert "/speckit-plan" in content
+        assert "speckit.foo.bar" in content
+        assert "/speckit-foo-bar" not in content
+        assert "$speckit-plan" not in content
+
     def test_missing_command_file_skipped(self, skills_project, temp_dir):
         """Commands with missing source files should be skipped gracefully."""
         project_dir, skills_dir = skills_project
diff --git a/tests/test_workflows.py b/tests/test_workflows.py
