/prompt invocation broken in Codex while $skill works

[alfred-openspec]

Bug Report

Reported by: vim_commando (Discord)

Description

/prompt invocation is broken in Codex, but $skill invocation works correctly. This is a positive signal that skills are working, but the legacy /prompt path has regressed.

Context

Related issues:

• codex Custom Prompts Deprecated. Use skills for reusable prompts #589 — Codex custom prompts deprecated, recommends migration to skills
• Codex prompts generated by OpenSpec do not inject arguments ($ARGUMENTS missing) #649 — Codex prompts missing $ARGUMENTS injection

This may be a consequence of the prompt → skill migration (#589), where /prompt stopped working but the newer $skill path is functional. If /prompt is intentionally deprecated, we should surface a clear error/migration message rather than silently breaking.

Expected Behavior

Either:

1. /prompt works as before (backward compat), OR
2. /prompt shows a clear deprecation message pointing users to $skill

Steps to Reproduce

1. Set up OpenSpec with Codex integration
2. Try /prompt invocation → broken
3. Try $skill invocation → works

Priority

User-reported, blocking workflow for at least one active community member.

---

Filed by Alfred via community triage

[21st-connector]

Task completed.

The enrichment comment has been posted on issue #723. Here's a summary of what was found and commented:

Two root causes identified:

1. Missing $ARGUMENTS injection in the Codex command adapter (src/core/command-generation/adapters/codex.ts:35-42). The formatFile() method outputs content.body directly without a $ARGUMENTS placeholder, so user-provided arguments are silently dropped when invoking via /prompt. This is a regression from pre-1.0 behavior and directly related to Codex prompts generated by OpenSpec do not inject arguments ($ARGUMENTS missing) #649.

2. Path mismatch between the global prompt location (~/.codex/prompts/) where the adapter writes files and the project-local path (.codex/prompts/) used in legacy cleanup detection (src/core/legacy-cleanup.ts:57).

Three fix approaches were suggested: restoring $ARGUMENTS for backward compat, explicitly deprecating /prompt in favor of $skill, or both (recommended).

The comment links to all relevant code locations with line numbers and clarifies the relationship between issues #589, #649, and #723.

---

View full conversation

Powered by 1Code

[21st-connector]

Issue Triage: Codebase Analysis

Root Cause Identification

This issue sits at the intersection of two systems that OpenSpec maintains for Codex:

1. Skills (new, working) — installed to .codex/skills/ as SKILL.md files following the Agent Skills spec. Invoked via $skill in Codex.
2. Commands / Prompts (legacy, broken) — installed to ~/.codex/prompts/opsx-*.md as global prompt files. Invoked via /prompt (slash commands) in Codex.

The dual-system architecture is visible in src/core/init.ts:426-463 — skills are generated first (lines 438-450), then commands are generated via the adapter system (lines 453-463).

Key Code Locations

File	Lines	Role
src/core/command-generation/adapters/codex.ts	28-44	Codex command adapter — formats prompt files for ~/.codex/prompts/
src/core/init.ts	426-463	Init flow — generates both skills AND commands per tool
src/core/command-generation/types.ts	12-25	CommandContent interface (defines body field)
src/core/shared/skill-generation.ts	87-97	getCommandContents() — maps templates to command content
src/core/legacy-cleanup.ts	32-58	Legacy artifact detection — note the naming mismatch (see below)
docs/supported-tools.md	22	Documents dual install: .codex/skills/ + ~/.codex/prompts/

Two Specific Problems Found

1. Missing $ARGUMENTS injection (directly related to #649)

The Codex adapter at src/core/command-generation/adapters/codex.ts:35-42 outputs content.body directly without injecting a $ARGUMENTS placeholder:

formatFile(content: CommandContent): string {
    return `---
description: ${content.description}
argument-hint: command arguments
---

${content.body}
`;
}

While the frontmatter includes argument-hint: command arguments, the body itself has no $ARGUMENTS (or $1..$9) variable for Codex to substitute user-provided arguments into. This means when a user runs /opsx-ff add-user-auth, the argument add-user-auth is silently dropped.

This is a regression — pre-1.0 versions included $ARGUMENTS in prompt templates (confirmed in the proposal at openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md).

2. Legacy cleanup may be removing prompt files

In src/core/legacy-cleanup.ts:57, the legacy pattern for Codex is:

'codex': { type: 'files', pattern: '.codex/prompts/openspec-*.md' }

But the current adapter generates files as opsx-*.md (not openspec-*.md). This means:

• Old openspec-*.md files get cleaned up correctly
• New opsx-*.md files in ~/.codex/prompts/ are NOT cleaned up by legacy detection
• However, the prompts are generated at the global path (~/.codex/prompts/) while legacy detection scans the project directory (.codex/prompts/)

This path mismatch (global vs project-local) means that even if prompt files are generated correctly, the legacy cleanup won't find or touch them — but it also means no accidental deletion.

Relationship to Other Issues

These three issues form a chain:

• codex Custom Prompts Deprecated. Use skills for reusable prompts #589 — Codex deprecated custom prompts, recommends skills → triggered the migration
• Codex prompts generated by OpenSpec do not inject arguments ($ARGUMENTS missing) #649 — $ARGUMENTS missing from generated Codex prompts → body-level regression
• /prompt invocation broken in Codex while $skill works #723 (this issue) — /prompt invocation fully broken while $skill works → end-user-facing symptom

Suggested Fix Approaches

Option A: Fix the /prompt path (backward compat)

1. Add $ARGUMENTS injection to the Codex adapter body in src/core/command-generation/adapters/codex.ts:41:

   formatFile(content: CommandContent): string {
       return `---
   description: ${content.description}
   argument-hint: command arguments
   ---
   
   $ARGUMENTS
   
   ${content.body}
   `;
   }

2. This would resolve both Codex prompts generated by OpenSpec do not inject arguments ($ARGUMENTS missing) #649 and this issue for users who rely on /prompt.

Option B: Deprecate /prompt explicitly

1. If Codex has officially deprecated custom prompts (per codex Custom Prompts Deprecated. Use skills for reusable prompts #589), stop generating prompt files in the Codex adapter entirely.
2. Surface a deprecation message during openspec init when Codex is selected, informing users that /prompt is no longer supported and to use $skill instead.
3. This would mean removing the codex adapter from src/core/command-generation/adapters/ and updating docs/supported-tools.md.

Option C: Both (recommended)

1. Add $ARGUMENTS to restore /prompt functionality short-term.
2. Add a deprecation notice in docs and CLI output.
3. Plan removal of the Codex command adapter in a future major version.

Duplicate Check

This is not a duplicate — it describes the user-facing symptom of the underlying $ARGUMENTS regression in #649. However, fixing #649 would likely resolve this issue as well, so they should be worked together.

[clay-good]

Closing as resolved by #1283, which made the Codex integration skills-only and retired the managed custom prompts entirely. There is no /prompt surface left to regress: openspec init --tools codex now generates skills under .codex/skills/ and no prompt files at all (verified on current main). The $skill path that was working is now the one supported path, and openspec update cleans up legacy prompt files.

The fix is on main and ships with the next release.