The Codex CLI integration continues to generate a deprecated slash-command workflow (/opsx:*).

[baiyeidk]

Description

OpenSpec’s Codex integration still relies on the legacy prompt / slash-command workflow (/opsx:*). However, in recent versions of Codex CLI, user-defined slash commands are no longer reliably supported or automatically registered.

Even after running:

openspec init --tools codex
openspec update --force

the generated assets still include:

~/.codex/prompts/

containing files such as:

opsx-apply.md
opsx-propose.md
opsx-archive.md

However, these prompt files are not registered as executable slash commands in Codex CLI.

Inside Codex:

/opsx

returns:

Unrecognized command '/opsx'

This indicates that the generated integration is not compatible with the current Codex runtime behavior.

---

Environment

• OpenSpec version: 1.3.1
• Codex CLI version: 0.133.0
• Node.js: v22.16.0
• OS: macOS
• Tool target: codex-cli

---

Reproduction Steps

Install OpenSpec:

npm install -g @fission-ai/openspec@latest

Initialize Codex integration:

openspec init --tools codex
openspec update --force

Inspect generated prompts:

ls ~/.codex/prompts

Start Codex:

codex

Try invoking:

/opsx

---

Actual Behavior

Codex reports:

Unrecognized command '/opsx'

despite the presence of generated prompt files.

---

Expected Behavior

OpenSpec should:

1. Stop generating deprecated Codex slash-command integration (/opsx:*)
2. Fully migrate to the Skills-based workflow ($openspec-*)
3. Update documentation, examples, and quickstart guides to remove or deprecate /opsx:* usage
4. Provide clear warnings or compatibility checks for unsupported Codex CLI versions

---

Documentation Issue (Important)

There is also a documentation-level inconsistency:

• Current documentation still describes /opsx:* as a valid invocation mechanism
• However, Codex CLI no longer supports user-defined slash commands in a reliable or consistent way
• The Skills mechanism ($openspec-*) appears to be the only stable supported approach

This leads to a misleading user experience where:

• Installation succeeds
• Files are generated correctly
• But commands cannot be executed in Codex

---

Related Issues

• /prompt invocation broken in Codex while $skill works #723 (/prompt invocation broken in Codex while $skill works)
• [Regression] /opsx:* commands not recognized in codex-cli v0.117.0 interactive dialog #890 (/opsx:* regression)
• Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools #1103 (generated Codex assets reference unsupported runtime tools)

---

Summary

This issue is not only an implementation incompatibility, but also a documentation drift problem. The documentation and generated assets no longer match the actual Codex CLI runtime behavior.

Therefore, I suggest:

• Updating documentation to explicitly deprecate /opsx:*
• Aligning all examples with the Skills-based model ($openspec-*)
• Preventing new users from being misled into using unsupported slash-command workflows

References (Official Deprecation Evidence)

There is official confirmation that Codex has deprecated the custom slash-command / prompt-based workflow.

1. Custom Prompts (Deprecated)

OpenAI Codex documentation explicitly states that custom prompts are deprecated:

https://developers.openai.com/codex/custom-prompts

Custom prompts are deprecated.

This feature previously allowed Markdown files to be exposed as slash commands (e.g. /xxx), but is now marked as deprecated in favor of Skills.

---

2. Skills as Replacement Mechanism

The official Skills documentation indicates that Skills are the replacement for reusable prompt workflows:

https://developers.openai.com/codex/skills

Skills are positioned as the modern mechanism replacing:

• reusable prompts
• slash-command-style workflows

---

3. CLI Slash Commands Documentation

The Codex CLI documentation for slash commands only lists built-in commands:

https://developers.openai.com/codex/cli/slash-commands

There is no longer any supported mechanism for user-defined slash command registration via ~/.codex/prompts.

---

4. GitHub Discussion / Version Changes

Codex CLI versions ≥ 0.117.0 reportedly removed or broke support for custom prompt-based slash commands:

openai/codex#15941

This aligns with observed behavior where:

• ~/.codex/prompts/*.md files are no longer registered as commands
• Custom /opsx:* style invocations are unrecognized

---

Conclusion

These sources collectively indicate that:

• The slash-command prompt system is deprecated or removed
• Skills ($skill-name) are the current supported mechanism
• OpenSpec Codex integration relying on /opsx:* is therefore incompatible with modern Codex CLI behavior