π« Toolkit to help you get started with SDD or any other process!
docs: document __SPECKIT_COMMAND_ token for portable cross-command references (#3503)
Quratulain-bilal840fb8d786ba
diff --git a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md b/extensions/EXTENSION-DEVELOPMENT-GUIDE.mdindex 77e79bd33..5da95c9d5 100644--- a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md+++ b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md@@ -252,6 +252,7 @@ Use standard Markdown with special placeholders:- `$ARGUMENTS`: User-provided arguments- `{SCRIPT}`: Replaced with script path during registration+- `__SPECKIT_COMMAND_<NAME>__`: Replaced with the invocation of another command, rendered using the active integration's separator (see [Referencing other commands](#referencing-other-commands))**Example**:@@ -267,6 +268,40 @@ echo "Running with args: $args"```````+### Referencing other commands++A command body is a *template* that Spec Kit renders once per agent. Different agents invoke commands with different surface syntax β for example `/speckit.plan` (dot separator) or `/speckit-plan` (hyphen separator). Some agents also use different prefixes in skills mode (e.g. Kimi `/skill:speckit-plan`, Codex/ZCode `$speckit-plan`). So when you reference a sibling command from a body, **do not hard-code a literal invocation** like `/speckit.my-ext.prepare`. A literal is correct for exactly one agent and breaks on the rest.++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:++| 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__` |++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.)++**Example** β a command body that points the user at the next step:++```markdown+Once the assessment exists, the next step is `__SPECKIT_COMMAND_BUG_FIX__ slug=<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.+### Script Path RewritingExtension commands use relative paths that get rewritten during registration: