[Bug]: Extension command references not rewritten for skills-based integrations (Codex), breaking cross-command invocation
- Ngôn ngữ chính
- Python
- Star
- 137k
- Fork
- 12.3k
- Merge trung bình
- 2 ngày 12 giờ
- Pull request đã merge (30 ngày)
- 159
Mô tả
### 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.
Hướng dẫn đóng góp
Hướng nghiên cứu
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.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- python
- Lĩnh vực
- cli, documentation
- Loại issue
- Lỗi
- Độ khó
- 4/5
- Thời gian dự kiến
- 3-5 ngày
- Mức độ hoạt động
- Sôi nổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 72/100