fix(integrations): preserve shared invocation prefix

Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 02f9e138-da58-4a60-93b9-eae659d2aa19

Author: BenBtg

src/specify_cli/__init__.py

@@ -114,6 +114,7 @@ def _refresh_shared_templates(
     project_path: Path,
     *,
     invoke_separator: str,
+    invoke_prefix: str = "/",
     force: bool = False,
 ) -> None:
     """Refresh default-sensitive shared templates without touching scripts."""
@@ -124,6 +125,7 @@ def _refresh_shared_templates(
         repo_root=_repo_root(),
         console=console,
         invoke_separator=invoke_separator,
+        invoke_prefix=invoke_prefix,
         force=force,
     )
 
@@ -134,6 +136,7 @@ def _install_shared_infra(
     tracker: StepTracker | None = None,
     force: bool = False,
     invoke_separator: str = ".",
+    invoke_prefix: str = "/",
     refresh_managed: bool = False,
     refresh_hint: str | None = None,
 ) -> bool:
@@ -177,6 +180,7 @@ def _install_shared_infra(
         console=console,
         force=force,
         invoke_separator=invoke_separator,
+        invoke_prefix=invoke_prefix,
         refresh_managed=refresh_managed,
         refresh_hint=refresh_hint,
     )
@@ -188,6 +192,7 @@ def _install_shared_infra_or_exit(
     tracker: StepTracker | None = None,
     force: bool = False,
     invoke_separator: str = ".",
+    invoke_prefix: str = "/",
     refresh_managed: bool = False,
     refresh_hint: str | None = None,
 ) -> bool:
@@ -198,6 +203,7 @@ def _install_shared_infra_or_exit(
             tracker=tracker,
             force=force,
             invoke_separator=invoke_separator,
+            invoke_prefix=invoke_prefix,
             refresh_managed=refresh_managed,
             refresh_hint=refresh_hint,
         )

src/specify_cli/commands/init.py

@@ -23,6 +23,7 @@
     get_speckit_version,
 )
 from .._console import StepTracker, console, select_with_arrows, show_banner
+from .._invocation_style import is_dollar_skills_agent
 from .._utils import check_tool
 
 
@@ -481,6 +482,16 @@ def init(
                     invoke_separator=resolved_integration.effective_invoke_separator(
                         integration_parsed_options, project_root=project_path
                     ),
+                    invoke_prefix=(
+                        "$"
+                        if is_dollar_skills_agent(
+                            resolved_integration.key,
+                            resolved_integration.is_skills_mode(
+                                integration_parsed_options, project_path
+                            ),
+                        )
+                        else "/"
+                    ),
                 )
                 tracker.complete(
                     "shared-infra", f"scripts ({selected_script}) + templates"

src/specify_cli/integrations/_helpers.py

@@ -9,6 +9,7 @@
 
 from .._agent_config import SCRIPT_TYPE_CHOICES
 from .._console import console
+from .._invocation_style import is_dollar_skills_agent
 from ..integration_runtime import (
     invoke_separator_for_integration as _invoke_separator_for_integration,
     resolve_integration_options as _resolve_integration_options_impl,
@@ -332,6 +333,13 @@ def _set_default_integration(
                     integration, {"integration_settings": settings}, key, parsed_options,
                     project_root=project_root,
                 ),
+                invoke_prefix=(
+                    "$"
+                    if is_dollar_skills_agent(
+                        key, integration.is_skills_mode(parsed_options, project_root)
+                    )
+                    else "/"
+                ),
                 force=refresh_templates_force,
                 refresh_managed=True,
                 refresh_hint=refresh_hint,

src/specify_cli/integrations/_migrate_commands.py

@@ -8,6 +8,7 @@
 import typer
 
 from .._console import console
+from .._invocation_style import is_dollar_skills_agent
 from ..integration_runtime import (
     invoke_separator_for_integration as _invoke_separator_for_integration,
     with_integration_setting as _with_integration_setting,
@@ -327,6 +328,13 @@ def integration_switch(
             target_integration, current, target, parsed_options,
             project_root=project_root,
         ),
+        invoke_prefix=(
+            "$"
+            if is_dollar_skills_agent(
+                target, target_integration.is_skills_mode(parsed_options, project_root)
+            )
+            else "/"
+        ),
         refresh_hint=(
             "To overwrite customizations, re-run with "
             "[cyan]specify integration switch ... --refresh-shared-infra[/cyan]."
@@ -557,6 +565,14 @@ def integration_upgrade(
             infra_integration, current, infra_key, infra_parsed,
             project_root=project_root,
         ),
+        invoke_prefix=(
+            "$"
+            if is_dollar_skills_agent(
+                infra_key,
+                infra_integration.is_skills_mode(infra_parsed, project_root),
+            )
+            else "/"
+        ),
     )
     if os.name != "nt":
         from .. import ensure_executable_scripts
@@ -592,6 +608,13 @@ def integration_upgrade(
                         integration, {"integration_settings": settings}, key, parsed_options,
                         project_root=project_root,
                     ),
+                    invoke_prefix=(
+                        "$"
+                        if is_dollar_skills_agent(
+                            key, integration.is_skills_mode(parsed_options, project_root)
+                        )
+                        else "/"
+                    ),
                     force=force,
                     refresh_managed=True,
                 )

src/specify_cli/shared_infra.py

@@ -305,6 +305,7 @@ def refresh_shared_templates(
     repo_root: Path,
     console: Any,
     invoke_separator: str,
+    invoke_prefix: str = "/",
     force: bool = False,
 ) -> None:
     """Refresh default-sensitive shared templates without touching scripts."""
@@ -336,7 +337,9 @@ def refresh_shared_templates(
                 continue
 
         content = src.read_text(encoding="utf-8")
-        content = IntegrationBase.resolve_command_refs(content, invoke_separator)
+        content = IntegrationBase.resolve_command_refs(
+            content, invoke_separator, invoke_prefix
+        )
         planned_updates.append((dst, rel, content))
 
     for dst, rel, content in planned_updates:
@@ -363,6 +366,7 @@ def install_shared_infra(
     console: Any,
     force: bool = False,
     invoke_separator: str = ".",
+    invoke_prefix: str = "/",
     refresh_managed: bool = False,
     refresh_hint: str | None = None,
 ) -> bool:
@@ -516,7 +520,9 @@ def _ensure_or_bucket_dir(directory: Path) -> bool:
                     if not _ensure_or_bucket_dir(dst_path.parent):
                         continue
                     content = src_path.read_text(encoding="utf-8")
-                    content = IntegrationBase.resolve_command_refs(content, invoke_separator)
+                    content = IntegrationBase.resolve_command_refs(
+                        content, invoke_separator, invoke_prefix
+                    )
                     content = _resolve_dynamic_command_refs(content, invoke_separator)
                     planned_copies.append(
                         (
@@ -566,7 +572,9 @@ def _ensure_or_bucket_dir(directory: Path) -> bool:
                     continue
 
                 content = src.read_text(encoding="utf-8")
-                content = IntegrationBase.resolve_command_refs(content, invoke_separator)
+                content = IntegrationBase.resolve_command_refs(
+                    content, invoke_separator, invoke_prefix
+                )
                 planned_templates.append((dst, rel, content))
 
     for dst_path, rel, content, mode in planned_copies:

tests/integrations/test_cli.py

@@ -1180,6 +1180,23 @@ def test_hyphen_separator_in_page_templates(self, tmp_path):
         assert "__SPECKIT_COMMAND_" not in content
         assert "/speckit-tasks" in content
 
+    def test_dollar_prefix_in_page_templates(self, tmp_path):
+        """Dollar-style skills agents get $speckit-<name> in page templates."""
+        from specify_cli import _install_shared_infra
+
+        project = tmp_path / "dollar-test"
+        project.mkdir()
+        (project / ".specify").mkdir()
+
+        _install_shared_infra(
+            project, "sh", invoke_separator="-", invoke_prefix="$"
+        )
+
+        plan = project / ".specify" / "templates" / "plan-template.md"
+        content = plan.read_text(encoding="utf-8")
+        assert "$speckit-plan" in content
+        assert "/speckit-plan" not in content
+
     @pytest.mark.parametrize("script_type", ["sh", "ps"])
     def test_dot_separator_in_shared_scripts(self, tmp_path, script_type):
         """Markdown agents get /speckit.<name> in shared script hints."""

tests/test_presets.py

@@ -4090,6 +4090,39 @@ def test_restore_skill_resolves_command_refs(self, project_dir, temp_dir):
         assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on restore"
         assert "/speckit-plan" in content
 
+    def test_restore_skill_preserves_dollar_command_refs(self, project_dir, temp_dir):
+        """Dollar-style core refs remain native when a preset skill is removed."""
+        from specify_cli.integrations.base import IntegrationBase
+
+        self._write_init_options(project_dir, ai="zcode")
+        skills_dir = project_dir / ".zcode" / "skills"
+        self._create_skill(skills_dir, "speckit-specify")
+
+        core_cmds = project_dir / ".specify" / "templates" / "commands"
+        core_cmds.mkdir(parents=True, exist_ok=True)
+        raw_core = (
+            "---\ndescription: Core specify\n---\n\n"
+            "Then run `__SPECKIT_COMMAND_PLAN__`.\n"
+        )
+        (core_cmds / "specify.md").write_text(
+            IntegrationBase.resolve_command_refs(raw_core, "-", "$")
+        )
+
+        preset_dir = self._create_command_preset(
+            temp_dir,
+            "dollar-cmdref-restore",
+            "speckit.specify",
+            "Override specify",
+            "Override body\n",
+        )
+        manager = PresetManager(project_dir)
+        manager.install_from_directory(preset_dir, "0.1.5")
+        manager.remove("dollar-cmdref-restore")
+
+        content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()
+        assert "$speckit-plan" in content
+        assert "/speckit-plan" not 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).