[Bug]: Extension command references not rewritten for skills-based integrations (Codex), breaking cross-command invocation

[mnriem]

Bug Description

Extension command markdown is copied verbatim into generated agent skills for skills-based integrations (e.g. Codex CLI), so in-body command references keep their slash-command spelling (/speckit.foo.bar). In Codex skills mode there is no such dispatchable slash command, so the agent fails or falls back to a markdown-only path.

Reported in discussion #3422 with the Codex CLI + spec-kit-memory-hub extension. Example failure the user saw:

Attempted the required memory prep command path (/speckit.memory-md.prepare-context),
but no runnable command was available in this environment, so I followed the
markdown-first fallback (...) before editing.

Root cause (code-confirmed):

• The skills rendering path ExtensionManager._register_extension_skills (src/specify_cli/extensions/__init__.py) copies each command file body into SKILL.md after only:
  • CommandRegistrar.resolve_skill_placeholders — resolves {SCRIPT}, {ARGS}, __AGENT__, project-relative paths only.
  • integration.post_process_skill_content — for SkillsIntegration this only injects a note about hyphenating hook command names; it does not rewrite in-body references.
• The helper that would fix this, CommandRegistrar._hyphenate_body_refs (src/specify_cli/agents.py:94), already exists but is applied only on the Cline extension path (is_cline_ext, agents.py:628-629). The generic skills path never calls it.

Net effect for Codex: the skill directory name and frontmatter hook refs get hyphenated (speckit-memory-md-prepare-context), but body text keeps /speckit.memory-md.prepare-context — wrong separator (.) and a / prefix that maps to nothing in skills mode.

There is also no extension-authoring guidance on command-reference portability: extensions/EXTENSION-USER-GUIDE.md itself uniformly uses /speckit.foo.bar notation and never describes skills-mode rendering.

Steps to Reproduce

1. specify init myproj --integration codex (skills-based integration).
2. Install an extension whose command bodies reference other commands in slash-dot form, e.g. spec-kit-memory-hub:
   specify extension add https://github.com/DyanGalih/spec-kit-memory-hub
3. Inspect a generated skill: cat .agents/skills/speckit-memory-md-prepare-context/SKILL.md
4. Observe the body still contains /speckit.memory-md.prepare-context.
5. Ask Codex to run that skill; it reports the command path is unavailable and falls back.

Expected Behavior

When rendering extension commands into skills, spec-kit should normalize in-body command references to the target integration's invocation form (hyphenated skill name, no bare slash-dot spelling) — the same way it already does for Cline and for frontmatter hook refs. Existing extensions written in slash-dot notation should "just work" for Codex without per-agent templates.

Actual Behavior

Body command references are copied verbatim (/speckit.foo.bar), which is not dispatchable in skills mode, so the agent errors or silently falls back to a markdown path.

Specify CLI Version

Reproduced against current main (source inspection); reporter on discussion #3422 did not pin a version.

AI Agent

Codex CLI

Operating System

Any (logic is OS-independent)

Python Version

Any supported (logic is OS/Python-independent)

Error Logs

Attempted the required memory prep command path (/speckit.memory-md.prepare-context),
but no runnable command was available in this environment, so I followed the
markdown-first fallback (./docs/memory/INDEX.md + feature memory-synthesis.md) before editing.

Additional Context

From discussion #3422 (#3422).

Proposed fix (two parts, ideally both):

1. Code: Apply _hyphenate_body_refs in the skills rendering path (_register_extension_skills), and normalize /speckit.x → the integration's invocation form (reuse SkillsIntegration.build_command_invocation). This makes existing extensions work for Codex without author changes.
2. Docs: Add an extension-authoring portability note — prefer the __SPECKIT_COMMAND_*__ token / neutral wording over hard-coded /speckit.… references so commands render correctly across slash-command and skills-based integrations.