π« Toolkit to help you get started with SDD or any other process!
fix(integrations): preserve native skill invocation prefixes (#3663)
Ben Buttigieg655a3cb8ca33
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.pyindex 1d5a34073..0454b6923 100644--- a/src/specify_cli/__init__.py+++ b/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,)diff --git a/src/specify_cli/_invocation_style.py b/src/specify_cli/_invocation_style.pyindex 2b5f18948..30b42eb08 100644--- a/src/specify_cli/_invocation_style.py+++ b/src/specify_cli/_invocation_style.py@@ -29,6 +29,9 @@ CONDITIONAL_SLASH_AGENTS: frozenset[str] = frozenset(})+# Agents that render /skill:<name> (skill-colon invocation) when in skills mode.+SKILL_COLON_AGENTS: frozenset[str] = frozenset({"kimi"})+def is_dollar_skills_agent(selected_ai: str | None, ai_skills_enabled: bool) -> bool:"""Return ``True`` if *selected_ai* uses ``$speckit-<name>`` invocations.@@ -41,6 +44,21 @@ def is_dollar_skills_agent(selected_ai: str | None, ai_skills_enabled: bool) ->return selected_ai in DOLLAR_SKILLS_AGENTS and ai_skills_enabled+def get_invocation_prefix(selected_ai: str | None, ai_skills_enabled: bool) -> str:+ """Return the native invocation prefix for *selected_ai* in skills mode.++ Returns ``"$"`` for dollar-skills agents (Codex, ZCode),+ ``"/skill:"`` for skill-colon agents (Kimi), and ``"/"`` for all others.+ """+ if not isinstance(selected_ai, str):+ return "/"+ if selected_ai in DOLLAR_SKILLS_AGENTS and ai_skills_enabled:+ return "$"+ if selected_ai in SKILL_COLON_AGENTS and ai_skills_enabled:+ return "/skill:"+ return "/"++def is_slash_skills_agent(selected_ai: str | None, ai_skills_enabled: bool) -> bool:"""Return ``True`` if *selected_ai* uses ``/speckit-<name>`` invocations.diff --git a/src/specify_cli/agents.py b/src/specify_cli/agents.pyindex 41a97cca7..a998f3992 100644--- a/src/specify_cli/agents.py+++ b/src/specify_cli/agents.py@@ -15,6 +15,7 @@ from typing import Any, Dict, Iterable, List, Optionalimport yamlfrom ._init_options import is_ai_skills_enabled, load_init_options+from ._invocation_style import get_invocation_prefixfrom ._toml_string import escape_toml_basic as _escape_toml_basicfrom ._toml_string import has_illegal_toml_control as _has_illegal_toml_controlfrom ._utils import relative_extension_path_violation@@ -659,17 +660,16 @@ class CommandRegistrar:# 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 = get_invocation_prefix(agent_name, registrar_writes_skills)for cmd_info in commands:cmd_name = cmd_info["name"]@@ -772,7 +772,7 @@ class CommandRegistrar:# (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)diff --git a/src/specify_cli/commands/init.py b/src/specify_cli/commands/init.pyindex ccdd7b0a1..0d96e2b6c 100644--- a/src/specify_cli/commands/init.py+++ b/src/specify_cli/commands/init.py@@ -183,6 +183,7 @@ def register(app: typer.Typer) -> None:save_init_options,)from ..integration_runtime import (+ invoke_prefix_for_integration as _invoke_prefix_for_integration,with_integration_setting as _with_integration_setting,)from ..integrations._commands import (@@ -481,6 +482,12 @@ def register(app: typer.Typer) -> None:invoke_separator=resolved_integration.effective_invoke_separator(integration_parsed_options, project_root=project_path),+ invoke_prefix=_invoke_prefix_for_integration(+ resolved_integration,+ resolved_integration.key,+ integration_parsed_options,+ project_path,+ ),)tracker.complete("shared-infra", f"scripts ({selected_script}) + templates"diff --git a/src/specify_cli/integration_runtime.py b/src/specify_cli/integration_runtime.pyindex 98bc6a05b..eef44574c 100644--- a/src/specify_cli/integration_runtime.py+++ b/src/specify_cli/integration_runtime.py@@ -5,6 +5,7 @@ from __future__ import annotationsfrom collections.abc import Callablefrom typing import Any+from ._invocation_style import get_invocation_prefixfrom .integration_state import integration_setting, integration_settings@@ -99,3 +100,14 @@ def invoke_separator_for_integration(return integration.effective_invoke_separator(stored_parsed, project_root)return integration.effective_invoke_separator(None, project_root)+++def invoke_prefix_for_integration(+ integration: Any,+ key: str,+ parsed_options: dict[str, Any] | None = None,+ project_root: Any = None,+) -> str:+ """Resolve the native invocation prefix for an integration's output mode."""+ skills_mode = integration.is_skills_mode(parsed_options, project_root)+ return get_invocation_prefix(key, skills_mode)diff --git a/src/specify_cli/integrations/_helpers.py b/src/specify_cli/integrations/_helpers.pyindex b95830b07..5c16935f1 100644--- a/src/specify_cli/integrations/_helpers.py+++ b/src/specify_cli/integrations/_helpers.py@@ -11,6 +11,7 @@ from rich.markup import escapefrom .._agent_config import SCRIPT_TYPE_CHOICESfrom .._console import consolefrom ..integration_runtime import (+ invoke_prefix_for_integration as _invoke_prefix_for_integration,invoke_separator_for_integration as _invoke_separator_for_integration,resolve_integration_options as _resolve_integration_options_impl,with_integration_setting as _with_integration_setting,@@ -333,6 +334,9 @@ def _set_default_integration(integration, {"integration_settings": settings}, key, parsed_options,project_root=project_root,),+ invoke_prefix=_invoke_prefix_for_integration(+ integration, key, parsed_options, project_root+ ),force=refresh_templates_force,refresh_managed=True,refresh_hint=refresh_hint,diff --git a/src/specify_cli/integrations/_install_commands.py b/src/specify_cli/integrations/_install_commands.pyindex 4d7bb44f9..372a335fd 100644--- a/src/specify_cli/integrations/_install_commands.py+++ b/src/specify_cli/integrations/_install_commands.py@@ -8,6 +8,7 @@ import typerfrom .._console import consolefrom .._utils import _display_project_pathfrom ..integration_runtime import (+ invoke_prefix_for_integration as _invoke_prefix_for_integration,invoke_separator_for_integration as _invoke_separator_for_integration,with_integration_setting as _with_integration_setting,)@@ -130,6 +131,9 @@ def integration_install(infra_integration, current, infra_key, infra_parsed,project_root=project_root,),+ invoke_prefix=_invoke_prefix_for_integration(+ infra_integration, infra_key, infra_parsed, project_root+ ),)if os.name != "nt":from .. import ensure_executable_scriptsdiff --git a/src/specify_cli/integrations/_migrate_commands.py b/src/specify_cli/integrations/_migrate_commands.pyindex f0c622323..0ff617ad2 100644--- a/src/specify_cli/integrations/_migrate_commands.py+++ b/src/specify_cli/integrations/_migrate_commands.py@@ -9,6 +9,7 @@ import typerfrom .._console import consolefrom ..integration_runtime import (+ invoke_prefix_for_integration as _invoke_prefix_for_integration,invoke_separator_for_integration as _invoke_separator_for_integration,with_integration_setting as _with_integration_setting,)@@ -447,6 +448,9 @@ def integration_switch(target_integration, current, target, parsed_options,project_root=project_root,),+ invoke_prefix=_invoke_prefix_for_integration(+ target_integration, target, parsed_options, project_root+ ),refresh_hint=("To overwrite customizations, re-run with ""[cyan]specify integration switch ... --refresh-shared-infra[/cyan]."@@ -747,6 +751,9 @@ def integration_upgrade(infra_integration, current, infra_key, infra_parsed,project_root=project_root,),+ invoke_prefix=_invoke_prefix_for_integration(+ infra_integration, infra_key, infra_parsed, project_root+ ),)if os.name != "nt":from .. import ensure_executable_scripts@@ -782,6 +789,9 @@ def integration_upgrade(integration, {"integration_settings": settings}, key, parsed_options,project_root=project_root,),+ invoke_prefix=_invoke_prefix_for_integration(+ integration, key, parsed_options, project_root+ ),force=force,refresh_managed=True,)diff --git a/src/specify_cli/integrations/base.py b/src/specify_cli/integrations/base.pyindex ccc858770..da255ed86 100644--- a/src/specify_cli/integrations/base.py+++ b/src/specify_cli/integrations/base.py@@ -27,6 +27,7 @@ from typing import TYPE_CHECKING, Anyimport yaml+from .._invocation_style import get_invocation_prefix, is_dollar_skills_agentfrom .._toml_string import escape_toml_basic as _escape_toml_basicfrom .._toml_string import has_illegal_toml_control as _has_illegal_toml_control@@ -34,7 +35,7 @@ if TYPE_CHECKING:from .manifest import IntegrationManifest_HOOK_COMMAND_NOTE = (- "- When constructing slash commands from hook command names, "+ "- When constructing command invocations from hook command names, ""replace dots (`.`) with hyphens (`-`). ""For example, `speckit.git.commit` β `/speckit-git-commit`.\n")@@ -601,7 +602,9 @@ class IntegrationBase(ABC):return created@staticmethod- def resolve_command_refs(content: str, separator: str = ".") -> str:+ def resolve_command_refs(+ content: str, separator: str = ".", prefix: str = "/"+ ) -> str:"""Replace ``__SPECKIT_COMMAND_<NAME>__`` placeholders with invocations.Each placeholder encodes a command name in upper-case with@@ -611,10 +614,16 @@ class IntegrationBase(ABC):* ``separator="."`` β ``/speckit.plan``, ``/speckit.git.commit``* ``separator="-"`` β ``/speckit-plan``, ``/speckit-git-commit``++ *prefix* defaults to ``"/"`` but may be ``"$"`` for agents whose+ native skills invocation uses dollar-prefixed chat commands."""return re.sub(r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_]*)__",- lambda m: "/speckit" + separator + m.group(1).lower().replace("_", separator),+ lambda m: prefix+ + "speckit"+ + separator+ + m.group(1).lower().replace("_", separator),content,)@@ -838,7 +847,12 @@ class IntegrationBase(ABC):content = CommandRegistrar.rewrite_project_relative_paths(content)# 8. Replace __SPECKIT_COMMAND_<NAME>__ with invocation strings- content = IntegrationBase.resolve_command_refs(content, invoke_separator)+ invocation_prefix = get_invocation_prefix(+ agent_name, invoke_separator == "-"+ )+ content = IntegrationBase.resolve_command_refs(+ content, invoke_separator, invocation_prefix+ )return content@@ -1520,18 +1534,21 @@ class SkillsIntegration(IntegrationBase):return project_root / folder / subdirdef build_command_invocation(self, command_name: str, args: str = "") -> str:- """Skills use ``/speckit-<stem>`` (hyphenated directory name)."""+ """Build the agent's native invocation for a hyphenated skill name."""stem = command_nameif stem.startswith("speckit."):stem = stem[len("speckit."):]- invocation = "/speckit-" + stem.replace(".", "-")+ prefix = "$" if is_dollar_skills_agent(self.key, True) else "/"+ invocation = prefix + "speckit-" + stem.replace(".", "-")if args:invocation = f"{invocation} {args}"return invocation@staticmethod- def _inject_hook_command_note(content: str) -> str:+ def _inject_hook_command_note(+ content: str, invocation_prefix: str = "/"+ ) -> str:"""Insert a dot-to-hyphen note before each hook output instruction.Targets the line ``- For each executable hook, output the following``@@ -1540,6 +1557,11 @@ class SkillsIntegration(IntegrationBase):above them."""note = _HOOK_COMMAND_NOTE.rstrip("\n")+ if invocation_prefix != "/":+ note = note.replace(+ "`/speckit-git-commit`",+ f"`{invocation_prefix}speckit-git-commit`",+ )def repl(m: re.Match[str]) -> str:indent = m.group(1)@@ -1573,10 +1595,13 @@ class SkillsIntegration(IntegrationBase):Called by external skill generators (presets, extensions) to letthe integration inject agent-specific frontmatter or bodytransformations. The base implementation injects shared skills- guidance for converting dotted hook command names to hyphenated- slash commands. Subclasses may override β see ``ClaudeIntegration``.+ guidance for converting dotted hook command names to the agent-native+ hyphenated command invocation (e.g. ``/speckit-git-commit`` or+ ``$speckit-git-commit``). Subclasses may override -- see+ ``ClaudeIntegration``."""- return self._inject_hook_command_note(content)+ invocation_prefix = get_invocation_prefix(self.key, True)+ return self._inject_hook_command_note(content, invocation_prefix)def setup(self,diff --git a/src/specify_cli/integrations/kimi/__init__.py b/src/specify_cli/integrations/kimi/__init__.pyindex 3320935a0..2b3d409b6 100644--- a/src/specify_cli/integrations/kimi/__init__.py+++ b/src/specify_cli/integrations/kimi/__init__.py@@ -59,8 +59,7 @@ class KimiIntegration(SkillsIntegration):def post_process_skill_content(self, content: str) -> str:"""Ensure in-skill cross-command references use Kimi's `/skill:` syntax."""- content = super().post_process_skill_content(content)- return content.replace("/speckit-", "/skill:speckit-")+ return super().post_process_skill_content(content)@classmethoddef options(cls) -> list[IntegrationOption]:diff --git a/src/specify_cli/presets/__init__.py b/src/specify_cli/presets/__init__.pyindex b9ca6e6d6..e16a9d325 100644--- a/src/specify_cli/presets/__init__.py+++ b/src/specify_cli/presets/__init__.py@@ -40,6 +40,7 @@ from .._init_options import (load_init_options,resolve_active_agent_for_registration,)+from .._invocation_style import get_invocation_prefixfrom ..integrations.base import IntegrationBasefrom .._utils import dump_frontmatter, version_satisfiesfrom ..shared_infra import (@@ -2424,13 +2425,15 @@ class PresetManager: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()``.+ agent-native invocation -- ``/speckit-<cmd>`` or ``$speckit-<cmd>`` for+ a ``-`` separator, ``/speckit.<cmd>`` for ``.``, or+ ``/skill:speckit-<cmd>`` for skill-colon agents (e.g. Kimi) -- the+ same rendering the command layer applies via+ ``CommandRegistrar.register_commands()``.For dual-layout agents (e.g. Bob) the separator depends on the- project's persisted skills state, so β when *project_root* is provided- β the separator is resolved from the integration via+ project's persisted skills state, so -- when *project_root* is provided+ -- the separator is resolved from the integration via``invoke_separator_for_mode`` rather than the single static``AGENT_CONFIGS`` value."""@@ -2451,7 +2454,8 @@ class PresetManager:separator = registrar.AGENT_CONFIGS.get(selected_ai, {}).get("invoke_separator", ".")- return IntegrationBase.resolve_command_refs(body, separator)+ prefix = get_invocation_prefix(selected_ai, separator == "-")+ return IntegrationBase.resolve_command_refs(body, separator, prefix)def _build_extension_skill_restore_index(self) -> Dict[str, Dict[str, Any]]:"""Index extension-backed skill restore data by skill directory name."""diff --git a/src/specify_cli/shared_infra.py b/src/specify_cli/shared_infra.pyindex d99cca4e8..1c8d727d7 100644--- a/src/specify_cli/shared_infra.py+++ b/src/specify_cli/shared_infra.py@@ -272,27 +272,56 @@ _BASH_FORMAT_COMMAND_RE = re.compile(_POWERSHELL_FORMAT_COMMAND_RE = re.compile(r"Format-SpecKitCommand\s+-CommandName\s+(['\"])([A-Za-z0-9_.-]+)\1(?:\s+-RepoRoot\s+[^\r\n]+)?")+_PYTHON_FORMAT_COMMAND_RETURN_RE = re.compile(+ r'return f"/speckit\{separator\}\{name\}"'+)+_BASH_FORMATTER_RETURN_RE = re.compile(+ r'''printf '/speckit%s%s\\n' "\$separator" "\$command_name"'''+)+_POWERSHELL_FORMATTER_RETURN_RE = re.compile(+ r'return "/speckit\$separator\$name"'+)-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."""+ bash_prefix = r"\$" if prefix == "$" else prefixcontent = _BASH_FORMAT_COMMAND_RE.sub(- lambda match: _format_speckit_command(match.group(2), separator),+ lambda match: _format_speckit_command(+ match.group(2), separator, bash_prefix+ ),+ content,+ )+ content = _POWERSHELL_FORMAT_COMMAND_RE.sub(+ lambda match: f"'{_format_speckit_command(match.group(2), separator, prefix)}'",+ content,+ )+ content = _BASH_FORMATTER_RETURN_RE.sub(+ f'''printf '{prefix}speckit%s%s\\\\n' "$separator" "$command_name"''',content,)- return _POWERSHELL_FORMAT_COMMAND_RE.sub(- lambda match: f"'{_format_speckit_command(match.group(2), separator)}'",+ powershell_prefix = "`$" if prefix == "$" else prefix+ content = _POWERSHELL_FORMATTER_RETURN_RE.sub(+ f'return "{powershell_prefix}speckit$separator$name"',+ content,+ )+ return _PYTHON_FORMAT_COMMAND_RETURN_RE.sub(+ f'return f"{prefix}speckit{{separator}}{{name}}"',content,)@@ -305,6 +334,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 +366,9 @@ def refresh_shared_templates(continuecontent = 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 +395,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,8 +549,12 @@ def install_shared_infra(if not _ensure_or_bucket_dir(dst_path.parent):continuecontent = src_path.read_text(encoding="utf-8")- content = IntegrationBase.resolve_command_refs(content, invoke_separator)- content = _resolve_dynamic_command_refs(content, invoke_separator)+ content = IntegrationBase.resolve_command_refs(+ content, invoke_separator, invoke_prefix+ )+ content = _resolve_dynamic_command_refs(+ content, invoke_separator, invoke_prefix+ )planned_copies.append((dst_path,@@ -566,7 +603,9 @@ def install_shared_infra(continuecontent = 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:diff --git a/tests/integrations/test_base.py b/tests/integrations/test_base.pyindex e78ef2361..5f9996180 100644--- a/tests/integrations/test_base.py+++ b/tests/integrations/test_base.py@@ -204,19 +204,69 @@ class TestBuildCommandInvocation:def test_skills_core_command(self):from specify_cli.integrations import get_integrationi = get_integration("codex")- assert i.build_command_invocation("speckit.plan") == "/speckit-plan"- assert i.build_command_invocation("plan") == "/speckit-plan"+ assert i.build_command_invocation("speckit.plan") == "$speckit-plan"+ assert i.build_command_invocation("plan") == "$speckit-plan"def test_skills_extension_command(self):from specify_cli.integrations import get_integrationi = get_integration("codex")- assert i.build_command_invocation("speckit.git.commit") == "/speckit-git-commit"- assert i.build_command_invocation("git.commit") == "/speckit-git-commit"+ assert i.build_command_invocation("speckit.git.commit") == "$speckit-git-commit"+ assert i.build_command_invocation("git.commit") == "$speckit-git-commit"def test_skills_extension_command_with_args(self):from specify_cli.integrations import get_integrationi = get_integration("codex")- assert i.build_command_invocation("speckit.git.commit", "fix typo") == "/speckit-git-commit fix typo"+ assert i.build_command_invocation("speckit.git.commit", "fix typo") == "$speckit-git-commit fix typo"++ @pytest.mark.parametrize("integration_key", ["codex", "zcode"])+ def test_dollar_skill_post_processing_is_idempotent(self, integration_key):+ from specify_cli.integrations import get_integration++ content = (+ "---\nname: test\n---\n\n"+ "Literal slash invocation: /speckit-plan\n"+ "- For each executable hook, output the following based on its flag:\n"+ )+ integration = get_integration(integration_key)+ once = integration.post_process_skill_content(content)+ twice = integration.post_process_skill_content(once)++ assert twice == once+ assert once.count("replace dots (`.`) with hyphens") == 1+ assert "$speckit-git-commit" in once+ assert "/speckit-plan" in once++ def test_kimi_skill_post_processing_is_idempotent(self):+ """Kimi's post_process_skill_content must be idempotent.++ The hook-command note is injected with the /skill: prefix by the base+ class (via get_invocation_prefix), so the idempotency check matches on+ re-runs without requiring the broad /speckit- -> /skill:speckit- body+ replacement to recognise a duplicate.+ """+ from specify_cli.integrations import get_integration++ content = (+ "---\nname: test\n---\n\n"+ "Literal slash invocation: /speckit-plan\n"+ "- For each executable hook, output the following based on its flag:\n"+ )+ integration = get_integration("kimi")+ once = integration.post_process_skill_content(content)+ twice = integration.post_process_skill_content(once)++ assert twice == once+ assert once.count("replace dots (`.`) with hyphens") == 1+ assert "/skill:speckit-git-commit" in once++ def test_get_invocation_prefix_skill_colon(self):+ """get_invocation_prefix returns '/skill:' for Kimi in skills mode."""+ from specify_cli._invocation_style import get_invocation_prefix++ assert get_invocation_prefix("kimi", True) == "/skill:"+ assert get_invocation_prefix("kimi", False) == "/"+ assert get_invocation_prefix("codex", True) == "$"+ assert get_invocation_prefix("claude", True) == "/"def test_forge_core_command_hyphenated(self):"""Forge installs hyphenated slash-commands (/speckit-<name>), so the@@ -268,6 +318,26 @@ class TestResolveCommandRefs:result = IntegrationBase.resolve_command_refs(text, "-")assert result == "Run `/speckit-plan` to plan."+ def test_dollar_prefix_core_command(self):+ text = "Run `__SPECKIT_COMMAND_PLAN__` to plan."+ result = IntegrationBase.resolve_command_refs(text, "-", "$")+ assert result == "Run `$speckit-plan` to plan."++ def test_skill_colon_prefix_core_command(self):+ text = "Run `__SPECKIT_COMMAND_PLAN__` to plan."+ result = IntegrationBase.resolve_command_refs(text, "-", "/skill:")+ assert result == "Run `/skill:speckit-plan` to plan."++ def test_process_template_kimi_uses_skill_colon_prefix(self):+ """process_template must use /skill: prefix for Kimi without relying on+ post_process_skill_content's broad replacement."""+ text = "---\ndescription: test\n---\nRun `__SPECKIT_COMMAND_PLAN__` to plan."+ result = IntegrationBase.process_template(+ text, "kimi", "sh", invoke_separator="-"+ )+ assert "/skill:speckit-plan" in result+ assert "/speckit-plan" not in result+def test_multiple_placeholders(self):text = "__SPECKIT_COMMAND_SPECIFY__ then __SPECKIT_COMMAND_PLAN__ then __SPECKIT_COMMAND_TASKS__"result = IntegrationBase.resolve_command_refs(text, ".")diff --git a/tests/integrations/test_cli.py b/tests/integrations/test_cli.pyindex 6899a5105..f6c08d0a4 100644--- a/tests/integrations/test_cli.py+++ b/tests/integrations/test_cli.py@@ -3,6 +3,7 @@import ioimport jsonimport os+import runpyimport pytestimport yaml@@ -1180,6 +1181,23 @@ class TestSharedInfraCommandRefs:assert "__SPECKIT_COMMAND_" not in contentassert "/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."""@@ -1220,6 +1238,48 @@ class TestSharedInfraCommandRefs:assert "/speckit.plan" not in contentassert "/speckit.tasks" not in content+ @pytest.mark.parametrize("script_type", ["sh", "ps", "py"])+ 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="$"+ )++ if script_type == "py":+ state = {+ "integration": "codex",+ "integration_settings": {+ "codex": {"invoke_separator": "-"},+ },+ }+ (project / ".specify" / "integration.json").write_text(+ json.dumps(state), encoding="utf-8"+ )+ common = project / ".specify" / "scripts" / "python" / "common.py"+ namespace = runpy.run_path(str(common))+ assert namespace["format_speckit_command"]("plan", project) == (+ "$speckit-plan"+ )+ return++ 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+ if script_type == "sh":+ assert r"\$speckit-specify" in content+ assert r"\$speckit-plan" in content+ assert r"\$speckit-tasks" 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 CliRunnerdiff --git a/tests/integrations/test_integration_base_skills.py b/tests/integrations/test_integration_base_skills.pyindex 79c6d3fb5..25551e1dc 100644--- a/tests/integrations/test_integration_base_skills.py+++ b/tests/integrations/test_integration_base_skills.py@@ -191,7 +191,7 @@ class SkillsIntegrationTests:"---\n""name: test\n""---\n\n"- "- When constructing slash commands from hook command names, "+ "- When constructing command invocations from hook command names, ""replace dots (`.`) with hyphens (`-`). ""For example, `speckit.git.commit` β `/speckit-git-commit`.\n""- For each executable hook, output the following first block:\n"diff --git a/tests/integrations/test_integration_codex.py b/tests/integrations/test_integration_codex.pyindex ac32dd725..9a4dc5442 100644--- a/tests/integrations/test_integration_codex.py+++ b/tests/integrations/test_integration_codex.py@@ -12,7 +12,6 @@ class TestCodexIntegration(SkillsIntegrationTests):COMMANDS_SUBDIR = "skills"REGISTRAR_DIR = ".agents/skills"-class TestCodexInitFlow:"""--integration codex creates expected files."""@@ -98,6 +97,8 @@ class TestCodexHookCommandNote:assert "replace dots" in content, ("speckit-specify should have dot-to-hyphen hook note")+ assert "constructing command invocations" in content+ assert "constructing slash commands" not in contentdef test_hook_note_not_in_skills_without_hooks(self):"""Skills without hook sections should not get the note."""diff --git a/tests/integrations/test_integration_subcommand.py b/tests/integrations/test_integration_subcommand.pyindex ef24c95c2..916c7b83f 100644--- a/tests/integrations/test_integration_subcommand.py+++ b/tests/integrations/test_integration_subcommand.py@@ -1276,6 +1276,24 @@ class TestIntegrationInstall:assert "/speckit-specify" in script_contentassert "/speckit.specify" not in script_content+ def test_install_dollar_skill_into_bare_project_gets_native_shared_refs(+ self, tmp_path+ ):+ """A dollar-style integration supplies its prefix without a default."""+ project = tmp_path / "bare-codex"+ project.mkdir()+ (project / ".specify").mkdir()++ result = _run_in_project(+ project, ["integration", "install", "codex", "--script", "sh"]+ )++ assert result.exit_code == 0, result.output+ plan = project / ".specify" / "templates" / "plan-template.md"+ plan_content = plan.read_text(encoding="utf-8")+ assert "$speckit-plan" in plan_content+ assert "/speckit-plan" not in plan_content+def test_install_defers_extension_commands_until_use(self, tmp_path):"""Installing a second integration does not register enabled extensions.@@ -2725,7 +2743,7 @@ class TestIntegrationSwitch:assert opts["ai"] == "codex"template = project / ".specify" / "templates" / "plan-template.md"- assert "/speckit-plan" in template.read_text(encoding="utf-8")+ assert "$speckit-plan" in template.read_text(encoding="utf-8")def test_failed_switch_rescaffolds_fallback_extensions(self, tmp_path):"""Regression (review 3624184343).diff --git a/tests/integrations/test_integration_zcode.py b/tests/integrations/test_integration_zcode.pyindex f431d3e4a..57abaedff 100644--- a/tests/integrations/test_integration_zcode.py+++ b/tests/integrations/test_integration_zcode.py@@ -9,7 +9,6 @@ class TestZcodeIntegration(SkillsIntegrationTests):COMMANDS_SUBDIR = "skills"REGISTRAR_DIR = ".zcode/skills"-class TestZcodeInvocation:"""ZCode renders $speckit-* chat invocations (like Codex)."""diff --git a/tests/test_extensions.py b/tests/test_extensions.pyindex afff0a2f8..4da73327e 100644--- a/tests/test_extensions.py+++ b/tests/test_extensions.py@@ -2884,6 +2884,29 @@ Real body starts here.assert "source: test-ext:commands/hello.md" in contentassert "<!-- 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 yamldiff --git a/tests/test_presets.py b/tests/test_presets.pyindex 05a1fa9ba..5edd8ac71 100644--- a/tests/test_presets.py+++ b/tests/test_presets.py@@ -4389,6 +4389,35 @@ class TestPresetSkills: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."""+ 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(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).diff --git a/tests/test_setup_tasks.py b/tests/test_setup_tasks.pyindex 6ff8aa23b..26d1c798e 100644--- a/tests/test_setup_tasks.py+++ b/tests/test_setup_tasks.py@@ -466,6 +466,42 @@ def test_bash_command_hint_preserves_hyphens_inside_segments(tasks_repo: Path) -assert result.stdout.strip() == "/speckit.jira.sync-status"+@requires_bash+def test_installed_bash_formatter_uses_dollar_prefix(tmp_path: Path) -> None:+ from specify_cli import _install_shared_infra++ project = tmp_path / "bash-dollar-prefix"+ project.mkdir()+ (project / ".specify").mkdir()+ _install_shared_infra(+ project, "sh", invoke_separator="-", invoke_prefix="$"+ )+ _write_integration_state(project, "codex", "-")++ result = _run_bash_format_command(project, "plan")++ assert result.returncode == 0, result.stderr+ assert result.stdout.strip() == "$speckit-plan"+++@requires_bash+def test_installed_bash_formatter_uses_skill_colon_prefix(tmp_path: Path) -> None:+ from specify_cli import _install_shared_infra++ project = tmp_path / "bash-skill-colon-prefix"+ project.mkdir()+ (project / ".specify").mkdir()+ _install_shared_infra(+ project, "sh", invoke_separator="-", invoke_prefix="/skill:"+ )+ _write_integration_state(project, "kimi", "-")++ result = _run_bash_format_command(project, "plan")++ assert result.returncode == 0, result.stderr+ assert result.stdout.strip() == "/skill:speckit-plan"++def _install_broken_json_tool_stubs(repo: Path) -> Path:"""Create a bin dir with `jq` and `python3` stubs that exist but fail.@@ -779,6 +815,24 @@ def test_powershell_command_hint_normalizes_mixed_separators(assert result.stdout.strip() == "/speckit-git-commit"[email protected](not (HAS_PWSH or _WINDOWS_POWERSHELL), reason="no PowerShell available")+def test_installed_powershell_formatter_uses_dollar_prefix(tmp_path: Path) -> None:+ from specify_cli import _install_shared_infra++ project = tmp_path / "powershell-dollar-prefix"+ project.mkdir()+ (project / ".specify").mkdir()+ _install_shared_infra(+ project, "ps", invoke_separator="-", invoke_prefix="$"+ )+ _write_integration_state(project, "codex", "-")++ result = _run_powershell_format_command(project, "plan")++ assert result.returncode == 0, result.stderr+ assert result.stdout.strip() == "$speckit-plan"++@pytest.mark.skipif(not (HAS_PWSH or _WINDOWS_POWERSHELL), reason="no PowerShell available")def test_powershell_command_hint_preserves_hyphens_inside_segments(tasks_repo: Path,