github / github/spec-kit

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

Đang mở
#3,451 1 bình luận 0 reaction 0 người được giao Xem trên GitHub
stale
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

Mở 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

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.