π« Toolkit to help you get started with SDD or any other process!
allow hyphen in command ref token names (#4356)
Huzaifa Iftikhar34f194d571dc
diff --git a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md b/extensions/EXTENSION-DEVELOPMENT-GUIDE.mdindex ac78029f2..ff0e90c23 100644--- a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md+++ b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md@@ -296,15 +296,16 @@ A command body is a *template* that Spec Kit renders once per agent. Different aInstead use the agent-neutral token `__SPECKIT_COMMAND_<NAME>__`. Spec Kit resolves it to a `/speckit<separator>...` invocation using the active integration's `invoke_separator` (and integrations may post-process that further in skills output).-Encode the command name in upper case, dropping the `speckit.` prefix and turning each dotted segment separator into an underscore:+Encode the command name in upper case, dropping the `speckit.` prefix and turning each dotted segment separator into an underscore. A hyphen inside a segment is kept as a hyphen:| Command file | Token || --- | --- || `speckit.plan.md` | `__SPECKIT_COMMAND_PLAN__` || `speckit.bug.fix.md` | `__SPECKIT_COMMAND_BUG_FIX__` || `speckit.git.commit.md` | `__SPECKIT_COMMAND_GIT_COMMIT__` |+| `speckit.agent-context.update.md` | `__SPECKIT_COMMAND_AGENT-CONTEXT_UPDATE__` |-The resolver maps each underscore back to the active agent's separator, so use tokens to reference commands whose name segments are single words. (Command names are dotted segments like `git.commit`; the token scheme rebuilds those dots and does not carry hyphens within a segment.)+The resolver maps each underscore back to the active agent's separator. An underscore separates segments and a hyphen belongs to the segment it sits in, so `AGENT-CONTEXT_UPDATE` is the two segments `agent-context` and `update` rather than three.**Example** β a command body that points the user at the next step:@@ -314,15 +315,19 @@ Once the assessment exists, the next step is `__SPECKIT_COMMAND_BUG_FIX__ slug=<This renders as `/speckit.bug.fix slug=<slug>` for a slash-based agent, `/speckit-bug-fix slug=<slug>` for a skills-based agent, and so on β the author writes it once and it stays portable. The first-party `bug` and `git` extensions use this token exclusively; see `extensions/bug/commands/` for working examples.-> **Current limitation β skills mode.** Token resolution runs in the-> command-rendering path (`CommandRegistrar`), so it applies when an extension-> installs *command files*. It does **not** yet run when an extension is-> registered as *skills* for a skills-based agent: `_register_extension_skills`-> resolves placeholders and post-processes content but never calls-> `resolve_command_refs`, so a `__SPECKIT_COMMAND_<NAME>__` token reaches-> agents such as Codex, ZCode, and Kimi verbatim in that mode. Until that-> rendering step lands, prefer the token for command-file extensions and avoid-> relying on it inside skill bodies destined for skills-based agents.+> **Skills mode.** Token resolution runs in both paths, so the token is safe to+> use either way. Command files go through the command-rendering path+> (`CommandRegistrar`). Skill bodies go through `_resolve_command_ref_tokens` in+> `_register_extension_skills`, which resolves the same token shape against the+> active skill style, so `__SPECKIT_COMMAND_BUG_FIX__` renders as:+>+> | Agent | Rendered |+> | --- | --- |+> | Codex, ZCode, Command Code | `$speckit-bug-fix` |+> | Claude, Copilot, Cursor, Devin, Droid, Grok and the other slash agents | `/speckit-bug-fix` |+> | Kimi | `/skill:speckit-bug-fix` |+>+> Anything else falls through to the integration's own `build_command_invocation`.### Script Path Rewritingdiff --git a/src/specify_cli/extensions/__init__.py b/src/specify_cli/extensions/__init__.pyindex 3968e4fcb..a440b6da9 100644--- a/src/specify_cli/extensions/__init__.py+++ b/src/specify_cli/extensions/__init__.py@@ -1596,7 +1596,7 @@ class ExtensionManager:)return re.sub(- r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_]*)__", _replacement, body+ r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_-]*)__", _replacement, body)for cmd_info in manifest.commands:diff --git a/src/specify_cli/integrations/base.py b/src/specify_cli/integrations/base.pyindex 27c43582b..e58d231d3 100644--- a/src/specify_cli/integrations/base.py+++ b/src/specify_cli/integrations/base.py@@ -636,11 +636,15 @@ class IntegrationBase(ABC):* ``separator="."`` β ``/speckit.plan``, ``/speckit.git.commit``* ``separator="-"`` β ``/speckit-plan``, ``/speckit-git-commit``+ A hyphen belongs to the segment it sits in rather than separating+ segments, so ``__SPECKIT_COMMAND_AGENT-CONTEXT_UPDATE__`` resolves to+ ``/speckit.agent-context.update``.+*prefix* defaults to ``"/"`` but may be ``"$"`` for agents whosenative skills invocation uses dollar-prefixed chat commands."""return re.sub(- r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_]*)__",+ r"__SPECKIT_COMMAND_([A-Z][A-Z0-9_-]*)__",lambda m: prefix+ "speckit"+ separatordiff --git a/tests/integrations/test_base.py b/tests/integrations/test_base.pyindex 5f9996180..713cf7552 100644--- a/tests/integrations/test_base.py+++ b/tests/integrations/test_base.py@@ -353,6 +353,16 @@ class TestResolveCommandRefs:result = IntegrationBase.resolve_command_refs(text, "-")assert result == "Run /speckit-git-commit to commit."+ def test_hyphenated_command_dot(self):+ text = "Run __SPECKIT_COMMAND_AGENT-CONTEXT_UPDATE__ to refresh."+ result = IntegrationBase.resolve_command_refs(text, ".")+ assert result == "Run /speckit.agent-context.update to refresh."++ def test_hyphenated_command_hyphen(self):+ text = "Run __SPECKIT_COMMAND_AGENT-CONTEXT_UPDATE__ to refresh."+ result = IntegrationBase.resolve_command_refs(text, "-")+ assert result == "Run /speckit-agent-context-update to refresh."+def test_no_placeholders_unchanged(self):text = "No placeholders here."assert IntegrationBase.resolve_command_refs(text, ".") == text@@ -400,6 +410,10 @@ class TestResolveCommandRefs:text = "Run __SPECKIT_COMMAND_plan__ to plan."assert IntegrationBase.resolve_command_refs(text, ".") == text+ def test_leading_hyphen_not_matched(self):+ text = "Run __SPECKIT_COMMAND_-PLAN__ to plan."+ assert IntegrationBase.resolve_command_refs(text, ".") == text+def test_placeholder_adjacent_to_text(self):text = "foo__SPECKIT_COMMAND_PLAN__bar"result = IntegrationBase.resolve_command_refs(text, ".")diff --git a/tests/test_extension_skills.py b/tests/test_extension_skills.pyindex 6eec5e7b4..a0a32f4d2 100644--- a/tests/test_extension_skills.py+++ b/tests/test_extension_skills.py@@ -1166,6 +1166,52 @@ class TestExtensionSkillRegistration:assert "__SPECKIT_COMMAND_PLAN__" not in contentassert expected_invocation in content+ def test_skill_registration_resolves_hyphenated_command_ref_tokens(+ self, project_dir, temp_dir+ ):+ """Command names containing a hyphen resolve like any other name."""+ _create_init_options(project_dir, ai="claude", ai_skills=True)+ skills_dir = _create_skills_dir(project_dir, ai="claude")++ ext_dir = temp_dir / "hyphen-ref-ext"+ ext_dir.mkdir()+ manifest_data = {+ "schema_version": "1.0",+ "extension": {+ "id": "hyphen-ref-ext",+ "name": "Hyphen Ref Extension",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "commands": [+ {+ "name": "speckit.hyphen-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_AGENT-CONTEXT_UPDATE__ before proceeding.\n"+ )++ manager = ExtensionManager(project_dir)+ manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)++ content = (skills_dir / "speckit-hyphen-ref-ext-run" / "SKILL.md").read_text()+ assert "__SPECKIT_COMMAND_AGENT-CONTEXT_UPDATE__" not in content+ assert "/speckit-agent-context-update" in content+def test_skill_registration_does_not_rewrite_literal_speckit_text(self, project_dir, temp_dir):