Skip to content

πŸ’« 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.md
index 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 a
Instead 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 Rewriting
diff --git a/src/specify_cli/extensions/__init__.py b/src/specify_cli/extensions/__init__.py
index 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.py
index 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 whose
native 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"
+ separator
diff --git a/tests/integrations/test_base.py b/tests/integrations/test_base.py
index 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.py
index 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 content
assert 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
):