github / github/spec-kit

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

オープン
#3,451 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る
stale
主要言語
Python
スター
137k
フォーク
12.3k
平均マージ
2日 12時間
マージ済み PR(30日)
159

説明

### 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.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

src/specify_cli/extensions/__init__.py の ExtensionManager._register_extension_skills から始め、次に src/specify_cli/agents.py の _hyphenate_body_refs 周辺にある既存の Cline の処理と、SkillsIntegration の呼び出し動作を比較します。Codex の初期化手順で再現し、生成された SKILL.md を確認します。本文内の参照が対象スキルの呼び出し形式を使用し、EXTENSION-USER-GUIDE.md が移植可能なコマンド参照について説明していれば完了です。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
python
領域
cli, documentation
issue の種類
バグ
難易度
4/5
見積もり時間
3〜5日
活発さ
活発
明瞭さ
明確に書かれている
初心者へのやさしさ
72/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。