[Bug]: Extension command references not rewritten for skills-based integrations (Codex), breaking cross-command invocation
- Vorherrschende Sprache
- Python
- Sterne
- 137k
- Forks
- 12.3k
- Ø Merge
- 2 T. 12 Std.
- Gemergte PRs (30 T.)
- 159
Beschreibung
### 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:
```text
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
```text
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 (https://github.com/github/spec-kit/discussions/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.
Beitragsleitfaden
Rechercherichtung
Start in src/specify_cli/extensions/__init__.py at ExtensionManager._register_extension_skills, then compare the existing Cline handling in src/specify_cli/agents.py around _hyphenate_body_refs and the SkillsIntegration invocation behavior. Reproduce with the Codex initialization steps and inspect the generated SKILL.md; done means in-body references use the target skills invocation form and EXTENSION-USER-GUIDE.md explains portable command references.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- python
- Bereich
- cli, documentation
- Issue-Typ
- Bug
- Schwierigkeit
- 4/5
- Geschätzter Aufwand
- 3-5 Tage
- Aktivitätsstatus
- Aktiv
- Klarheit
- Klar beschrieben
- Anfängerfreundlichkeit
- 72/100