fix(integrations): preserve dollar refs everywhere

Use agent-native invocation prefixes in extension command registration and dynamic shared-script command hints.

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/agents.py

@@ -15,6 +15,7 @@
 import yaml
 
 from ._init_options import is_ai_skills_enabled, load_init_options
+from ._invocation_style import is_dollar_skills_agent
 from ._toml_string import escape_toml_basic as _escape_toml_basic
 from ._toml_string import has_illegal_toml_control as _has_illegal_toml_control
 from ._utils import relative_extension_path_violation
@@ -659,17 +660,20 @@ def register_commands(
         # correct when a stale ``.bob/skills`` directory coexists with
         # ``.bob/commands``.
         _sep = agent_config.get("invoke_separator", ".")
+        registrar_writes_skills = agent_config.get("extension") == "/SKILL.md"
         try:
             from specify_cli.integrations import get_integration  # noqa: PLC0415
 
             _integ = get_integration(agent_name)
             if _integ is not None:
-                registrar_writes_skills = (
-                    agent_config.get("extension") == "/SKILL.md"
-                )
                 _sep = _integ.invoke_separator_for_mode(registrar_writes_skills)
         except Exception:
             pass
+        _prefix = (
+            "$"
+            if is_dollar_skills_agent(agent_name, registrar_writes_skills)
+            else "/"
+        )
 
         for cmd_info in commands:
             cmd_name = cmd_info["name"]
@@ -755,7 +759,7 @@ def register_commands(
             # (base.py itself imports CommandRegistrar lazily).
             from specify_cli.integrations.base import IntegrationBase  # noqa: PLC0415
 
-            body = IntegrationBase.resolve_command_refs(body, _sep)
+            body = IntegrationBase.resolve_command_refs(body, _sep, _prefix)
 
             output_name = self._compute_output_name(agent_name, cmd_name, agent_config)
 

src/specify_cli/shared_infra.py

@@ -274,25 +274,29 @@ def _write_shared_bytes(
 )
 
 
-def _format_speckit_command(command_name: str, separator: str) -> str:
+def _format_speckit_command(
+    command_name: str, separator: str, prefix: str = "/"
+) -> str:
     name = command_name.strip().lstrip("/")
     if name.startswith("speckit."):
         name = name[len("speckit.") :]
     elif name.startswith("speckit-"):
         name = name[len("speckit-") :]
     name = name.replace(".", separator)
-    return f"/speckit{separator}{name}"
+    return f"{prefix}speckit{separator}{name}"
 
 
-def _resolve_dynamic_command_refs(content: str, separator: str) -> str:
+def _resolve_dynamic_command_refs(
+    content: str, separator: str, prefix: str = "/"
+) -> str:
     """Render script runtime command helpers for managed shared infra copies."""
 
     content = _BASH_FORMAT_COMMAND_RE.sub(
-        lambda match: _format_speckit_command(match.group(2), separator),
+        lambda match: _format_speckit_command(match.group(2), separator, prefix),
         content,
     )
     return _POWERSHELL_FORMAT_COMMAND_RE.sub(
-        lambda match: f"'{_format_speckit_command(match.group(2), separator)}'",
+        lambda match: f"'{_format_speckit_command(match.group(2), separator, prefix)}'",
         content,
     )
 
@@ -523,7 +527,9 @@ def _ensure_or_bucket_dir(directory: Path) -> bool:
                     content = IntegrationBase.resolve_command_refs(
                         content, invoke_separator, invoke_prefix
                     )
-                    content = _resolve_dynamic_command_refs(content, invoke_separator)
+                    content = _resolve_dynamic_command_refs(
+                        content, invoke_separator, invoke_prefix
+                    )
                     planned_copies.append(
                         (
                             dst_path,

tests/integrations/test_cli.py

@@ -1237,6 +1237,27 @@ def test_hyphen_separator_in_shared_scripts(self, tmp_path, script_type):
         assert "/speckit.plan" not in content
         assert "/speckit.tasks" not in content
 
+    @pytest.mark.parametrize("script_type", ["sh", "ps"])
+    def test_dollar_prefix_in_shared_scripts(self, tmp_path, script_type):
+        """Dollar-style skills agents get native prefixes in shared script hints."""
+        from specify_cli import _install_shared_infra
+
+        project = tmp_path / f"dollar-script-{script_type}"
+        project.mkdir()
+        (project / ".specify").mkdir()
+
+        _install_shared_infra(
+            project, script_type, invoke_separator="-", invoke_prefix="$"
+        )
+
+        content = self._combined_script_content(project, script_type)
+        assert "$speckit-specify" in content
+        assert "$speckit-plan" in content
+        assert "$speckit-tasks" in content
+        assert "/speckit-specify" not in content
+        assert "/speckit-plan" not in content
+        assert "/speckit-tasks" not in content
+
     def test_full_init_claude_resolves_page_templates(self, tmp_path):
         """Full CLI init with Claude (skills agent) produces hyphen refs in page templates."""
         from typer.testing import CliRunner

tests/test_extensions.py

@@ -2812,6 +2812,29 @@ def test_codex_skill_registration_writes_skill_frontmatter(self, extension_dir,
         assert "source: test-ext:commands/hello.md" in content
         assert "<!-- Extension:" not in content
 
+    def test_codex_skill_registration_uses_dollar_command_refs(
+        self, extension_dir, project_dir
+    ):
+        """Codex extension skills use the native dollar invocation prefix."""
+        skills_dir = project_dir / ".agents" / "skills"
+        skills_dir.mkdir(parents=True)
+        command = extension_dir / "commands" / "hello.md"
+        command.write_text(
+            "---\ndescription: Test hello command\n---\n\nRun __SPECKIT_COMMAND_PLAN__.",
+            encoding="utf-8",
+        )
+
+        manifest = ExtensionManifest(extension_dir / "extension.yml")
+        registrar = CommandRegistrar()
+        registrar.register_commands_for_agent(
+            "codex", manifest, extension_dir, project_dir
+        )
+
+        skill_file = skills_dir / "speckit-test-ext-hello" / "SKILL.md"
+        content = skill_file.read_text(encoding="utf-8")
+        assert "$speckit-plan" in content
+        assert "/speckit-plan" not in content
+
     def test_codex_skill_registration_resolves_script_placeholders(self, project_dir, temp_dir):
         """Codex SKILL.md overrides should resolve script placeholders."""
         import yaml