fix(extensions): hyphenate in-body command refs when rendering skills

[Quratulain-bilal]

fixes #3451

extension command bodies were copied verbatim into generated SKILL.md files for skills-based integrations (codex, claude, etc.), so an in-body reference like /speckit.foo.bar kept its slash-dot spelling. skills agents dispatch speckit-foo-bar skills, not /speckit.foo.bar slash commands, so the reference was not runnable and the agent fell back to a markdown-only path (as reported in discussion #3422 with codex + spec-kit-memory-hub).

root cause (matches the issue): _register_extension_skills only ran resolve_skill_placeholders (script/args/__AGENT__/project-relative paths) and post_process_skill_content (which for SkillsIntegration only injects a hook-note), never a body-ref rewrite. the skill dir name and frontmatter hook refs were already hyphenated elsewhere; the body was the missing piece.

fix: apply the existing CommandRegistrar._hyphenate_body_refs helper in the skills render path, right after resolve_skill_placeholders. that helper is already used on the cline extension path (agents.py); this reuses it. skills integrations always dispatch hyphenated skills, so the rewrite is unconditionally correct there.

added a regression test: it installs an extension whose command body references a sibling command (/speckit.test-ext.world) and asserts the generated skill body has the dotted ref rewritten to speckit-test-ext-world. i confirmed it fails on the pre-fix code (the verbatim speckit.test-ext.world leaks into the body); the full extension-skills suite (58 tests) passes with the fix.

this covers part 1 (code) of the issue's proposed fix. i left the docs-portability note (part 2) out of this PR to keep it focused; happy to follow up if you'd like it here.

[Copilot]

Pull request overview

Rewrites dotted extension command references when generating skills.

Changes:

• Hyphenates in-body speckit.* references.
• Adds regression coverage for generated skill content.

Show a summary per file

File	Description
src/specify_cli/extensions/__init__.py	Rewrites command references during skill rendering.
tests/test_extension_skills.py	Adds a cross-command reference regression test.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Medium

[mnriem]

Please read comments to #3474 as we cannot take this PR as-is

[Quratulain-bilal]

thanks @mnriem, read through your writeup on #3474 and you're right — the root cause isn't verbatim copy, it's that spec-kit-memory-hub hard-coded a literal /speckit.... invocation instead of the neutral __SPECKIT_COMMAND_*__ token that the renderer already resolves. teaching the renderer to guess which slash-dot literals are command refs (vs urls, paths, links, code spans) is exactly the heuristic trap you point out, so hyphenating the body was treating the symptom.

i confirmed the mechanism in code before agreeing: resolve_command_refs() lives at integrations/base.py:524 and the first-party extensions use the token exclusively (e.g. extensions/bug/commands/*.md reference __SPECKIT_COMMAND_BUG_FIX__ etc.), and EXTENSION-USER-GUIDE.md never mentions the token while its own examples use /speckit.* throughout — so the discoverability gap in your phase 1 is real.

closing this in favor of your phased plan. i'd like to pick up phase 1 (documenting __SPECKIT_COMMAND_*__ as the required way to write cross-command refs, and fixing the guide examples) since it's independent and shippable on its own — will open a focused PR for it. thanks for the detailed reframe.

note: i used an ai assistant to help investigate and write this up.