github / github/spec-kit

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

Ouverte
#3,451 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub
stale
Langage dominant
Python
Étoiles
137k
Forks
12.3k
Merge moyen
2 j 12 h
PR mergées (30 j)
159

Description

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

Guide de contribution

Ouvrir le guide de contribution

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
python
Domaine
cli, documentation
Type d'issue
Bug
Difficulté
4/5
Temps estimé
3-5 jours
Activité
Active
Clarté
Clairement spécifiée
Accessibilité débutants
72/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.