feat(codex): make Codex skills-only and retire managed custom prompts

[showms]

Summary

This PR removes Codex from OpenSpec's command/prompt-file generation path and makes Codex a skills-only integration.

Specifically, this change:

• stops generating new Codex custom prompt files during openspec init and openspec update
• treats Codex as a skills-invocable surface even when global delivery includes commands
• keeps Codex workflows available through generated OpenSpec skills instead of deprecated prompt files
• detects and cleans up OpenSpec-managed legacy Codex prompt files under CODEX_HOME/prompts or ~/.codex/prompts
• updates docs and tests to reflect the new Codex integration model

Why

This aligns OpenSpec with Codex's current official guidance.

OpenAI's Codex changelog states that custom prompts were deprecated on January 22, 2026, and recommends using skills for reusable instructions and workflows instead. The Codex custom prompts documentation also marks the feature as deprecated and explains that custom prompts are local to the Codex home directory, require explicit invocation, and should be replaced by skills for reusable/shared behavior.

Codex changelog: developers.openai.com/codex/changelog
Codex custom prompts docs: developers.openai.com/codex/custom-prompts

In practice, continuing to generate global Codex prompt files creates a poor fit for OpenSpec:

• it writes outside the repository into a user-global location
• it leaves stale managed artifacts behind
• it keeps OpenSpec advertising a Codex surface that the official docs now discourage
• it makes repository setup appear local while actual Codex behavior depends on global prompt files

OpenSpec already has a skills-based Codex workflow surface, so this PR makes that the supported and explicit path.

Behavior changes

Before

• openspec init / openspec update could generate managed Codex prompt files in CODEX_HOME/prompts or ~/.codex/prompts
• Codex was still represented in the command adapter surface
• legacy managed prompt files could persist in a global location

After

• Codex is no longer a command adapter target
• Codex remains usable through OpenSpec-generated skills only
• commands delivery does not remove Codex skills
• OpenSpec-managed legacy Codex prompt files are detected via managed filename patterns and cleaned up through the normal legacy cleanup flow
• unmanaged user prompt files are preserved

Implementation notes

• removes Codex from command adapter registration and exports
• resolves Codex through the shared skills-invocable command-surface capability path
• separates repo-local legacy slash-command detection from managed global Codex prompt cleanup
• adds/updates tests for:
  • init under both / skills / commands
  • update under both / skills / commands
  • forced and non-forced legacy global prompt cleanup
  • unmanaged prompt preservation
  • command-surface behavior without a Codex adapter

Breaking change

Codex users who previously relied on OpenSpec-generated custom prompt files must use the OpenSpec-generated Codex skills workflow after updating.

Validation

• openspec validate make-codex-skills-only --strict
• targeted Codex/command-generation/init/update/legacy-cleanup tests
• pnpm build

Summary by CodeRabbit

• New Features
  • Codex is now skills-first: it installs/refreshes Codex skills under .codex/skills/openspec-* across delivery modes (both, skills, commands).
• Bug Fixes
  • Codex no longer generates legacy opsx-* prompt/command artifacts; legacy global cleanup is replacement-gated and safer in non-interactive runs (warns unless --force is used).
  • Preserves unmanaged user files during init/update/migration, including legacy prompt handling.
• Documentation
  • Updated command syntax, setup/install, migration, supported tools, and troubleshooting to reflect skills-only Codex behavior.
• Tests
  • Expanded Codex-focused coverage for init/update, legacy detection/cleanup, and command-surface capability decisions.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Codex is moved to a skills-only surface. The Codex adapter is removed, generation and cleanup now use capability-aware logic, managed global Codex prompt files are detected and cleaned up through CODEX_HOME, and the related docs, specs, and tests were updated.

Changes

Codex Skills-Only Migration

Layer / File(s)	Summary
Proposal, specs, and docs openspec/changes/make-codex-skills-only/*, docs/commands.md, docs/how-commands-work.md, docs/migration-guide.md, docs/supported-tools.md, docs/troubleshooting.md, .gitignore	Codex is documented as skills-only, with updated migration, command syntax, supported-tools, troubleshooting, and project metadata guidance.
Capability-aware generation flow src/core/command-generation/adapters/index.ts, src/core/command-generation/registry.ts, src/core/command-generation/types.ts, src/core/command-surface.ts, src/core/init.ts, src/core/update.ts, src/core/profile-sync-drift.ts	Codex is removed from adapter registration, command-surface capability helpers are added, and init/update/drift logic uses them to control skill generation, command generation, reconciliation, and skip reporting.
Managed global prompt cleanup src/core/legacy-cleanup.ts	Legacy cleanup now detects managed global Codex prompt files, removes eligible matches, and formats deferred cleanup output with replacement labels and tool mappings.
Codex coverage and fixtures test/core/command-generation/adapters.test.ts, test/core/command-generation/registry.test.ts, test/core/init.test.ts, test/core/update.test.ts, test/core/legacy-cleanup.test.ts, test/helpers/legacy-codex-prompt.ts	Tests and helpers add Codex skills-only coverage, managed prompt cleanup cases, and command-surface assertions while removing obsolete adapter coverage.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related issues

• The Codex CLI integration continues to generate a deprecated slash-command workflow (/opsx:*). #1129: The PR implements the Codex migration from deprecated prompt files to .codex/skills/openspec-* behavior.

Possibly related PRs

• Fission-AI/OpenSpec#556: Introduced the Codex adapter surface that this PR removes.
• Fission-AI/OpenSpec#565: Also changes init/update and legacy-cleanup flow in the same areas this PR extends for Codex.
• Fission-AI/OpenSpec#622: Changes Codex command-generation path handling that this PR replaces with skills-only behavior.

Suggested reviewers: alfred-openspec, TabishB

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 52.63% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Title clearly summarizes the main Codex shift to skills-only and removal of managed custom prompt generation.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[showms]

One additional note for reviewers: the Windows interactive input bug after legacy cleanup still appears to exist.

I can still reproduce the case where, after running openspec init and accepting legacy cleanup, the subsequent selection prompt stops responding to Up/Down (and effectively only Enter keeps working).

I previously opened #1175 for this issue:
fix(init): fix only Enter working after legacy cleanup on Windows

That PR isolates the problem to the welcome-screen/input lifecycle after cleanup and switches the Enter wait flow to Inquirer-managed input handling. I’m mentioning it here because this Codex PR touches nearby init/update/legacy-cleanup behavior, but this known Windows input bug is a separate issue and may still need to be addressed independently.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

openspec/changes/make-codex-skills-only/specs/ai-tool-paths/spec.md (1)

34-34: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Fix hyphenation: "Codex-managed legacy prompt file names."

"Codex managed" is a compound modifier and should be hyphenated: "Codex-managed legacy prompt file names use prefix-based glob patterns."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openspec/changes/make-codex-skills-only/specs/ai-tool-paths/spec.md` at line
34, The requirement title in the spec uses incorrect hyphenation; update the
text for the Codex-managed legacy prompt file names requirement to use the
compound modifier form. In the relevant spec entry, adjust the wording around
the requirement heading so it reads with a hyphenated “Codex-managed” while
keeping the rest of the phrase about legacy prompt file names and prefix-based
glob patterns unchanged.

src/core/update.ts (1)

238-240: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

No-op else if branch; no skills-invocable messaging parity with init.ts.

This branch only contains a comment and performs no action. init.ts tracks skillsInvocableCommandSkips and emits a Commands skipped for: … (uses skills) line, but the update flow stays silent here. Consider either dropping this empty branch or emitting an equivalent notice so Codex users see that commands were intentionally skipped in favor of skills (task 4.4).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/core/update.ts` around lines 238 - 240, The `update.ts` command-surface
handling has an empty `else if` branch for
`resolveCommandSurfaceCapability(tool.value) === 'skills-invocable'`, so it
silently does nothing while `init.ts` reports skipped commands. Either remove
the no-op branch or add the same skills-skipped tracking/message behavior used
by `init.ts` (for example, the `skillsInvocableCommandSkips`/“Commands skipped
for … (uses skills)” flow) so `update` gives parity and users see the
intentional skip.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/core/legacy-cleanup.ts`:
- Around line 495-504: The unlink loop in cleanupLegacyArtifacts() is deleting
every entry from detection.globalSlashCommandFiles without re-checking that each
path is still a managed global legacy path. Before calling fs.unlink for each
filePath, validate it against getManagedGlobalLegacyPattern() and only proceed
when the entry matches the managed pattern; otherwise record an error and skip
deletion. Keep the change localized to the global slash command cleanup branch
and preserve the existing result.deletedFiles/result.errors behavior.

---

Nitpick comments:
In `@openspec/changes/make-codex-skills-only/specs/ai-tool-paths/spec.md`:
- Line 34: The requirement title in the spec uses incorrect hyphenation; update
the text for the Codex-managed legacy prompt file names requirement to use the
compound modifier form. In the relevant spec entry, adjust the wording around
the requirement heading so it reads with a hyphenated “Codex-managed” while
keeping the rest of the phrase about legacy prompt file names and prefix-based
glob patterns unchanged.

In `@src/core/update.ts`:
- Around line 238-240: The `update.ts` command-surface handling has an empty
`else if` branch for `resolveCommandSurfaceCapability(tool.value) ===
'skills-invocable'`, so it silently does nothing while `init.ts` reports skipped
commands. Either remove the no-op branch or add the same skills-skipped
tracking/message behavior used by `init.ts` (for example, the
`skillsInvocableCommandSkips`/“Commands skipped for … (uses skills)” flow) so
`update` gives parity and users see the intentional skip.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 71241810-dd7a-49e6-be95-4d555b5bcd7a

📥 Commits

Reviewing files that changed from the base of the PR and between 546224e and e821ed7.

📒 Files selected for processing (27)

• docs/commands.md
• docs/how-commands-work.md
• docs/migration-guide.md
• docs/supported-tools.md
• docs/troubleshooting.md
• openspec/changes/make-codex-skills-only/.openspec.yaml
• openspec/changes/make-codex-skills-only/design.md
• openspec/changes/make-codex-skills-only/proposal.md
• openspec/changes/make-codex-skills-only/specs/ai-tool-paths/spec.md
• openspec/changes/make-codex-skills-only/specs/cli-init/spec.md
• openspec/changes/make-codex-skills-only/specs/cli-update/spec.md
• openspec/changes/make-codex-skills-only/specs/command-generation/spec.md
• openspec/changes/make-codex-skills-only/tasks.md
• src/core/command-generation/adapters/codex.ts
• src/core/command-generation/adapters/index.ts
• src/core/command-generation/registry.ts
• src/core/command-generation/types.ts
• src/core/command-surface.ts
• src/core/init.ts
• src/core/legacy-cleanup.ts
• src/core/profile-sync-drift.ts
• src/core/update.ts
• test/core/command-generation/adapters.test.ts
• test/core/command-generation/registry.test.ts
• test/core/init.test.ts
• test/core/legacy-cleanup.test.ts
• test/core/update.test.ts

💤 Files with no reviewable changes (3)

• src/core/command-generation/adapters/codex.ts
• src/core/command-generation/adapters/index.ts
• src/core/command-generation/registry.ts

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

test/core/legacy-cleanup.test.ts (1)

1050-1163: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Add a backslash-path regression for getToolsFromLegacyArtifacts().

This change added Windows-specific normalization in the production matcher, but this section still only feeds POSIX-style slashCommandFiles into the extractor. A case like '.cursor\\commands\\openspec-proposal.md' would catch the exact cross-platform break this code is trying to prevent.

As per coding guidelines, "When touching path behavior, add coverage that would fail on Windows path separators."

🧪 Example test

+    it('should extract cursor from Windows-style legacy artifact paths', () => {
+      const detection = {
+        configFiles: [],
+        configFilesToUpdate: [],
+        slashCommandDirs: [],
+        slashCommandFiles: ['.cursor\\commands\\openspec-proposal.md'],
+        globalSlashCommandFiles: [],
+        hasOpenspecAgents: false,
+        hasProjectMd: false,
+        hasRootAgentsWithMarkers: false,
+        hasLegacyArtifacts: true,
+      };
+
+      expect(getToolsFromLegacyArtifacts(detection)).toContain('cursor');
+    });

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/core/legacy-cleanup.test.ts` around lines 1050 - 1163, Add a
Windows-path regression test for getToolsFromLegacyArtifacts by extending the
existing getToolsFromLegacyArtifacts describe block with a case that passes
backslash-separated legacy paths (for example in slashCommandFiles) and asserts
the same tool is detected. Use the existing getToolsFromLegacyArtifacts helper
and related detection shape, and verify the matcher normalizes separators so the
test would fail without the Windows path fix.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/core/update.test.ts`:
- Around line 1617-1639: The update test is using a prompt name that is not
recognized by detectLegacyArtifacts(), so it never exercises the managed global
prompt preserve path. Change the legacy prompt setup in the
updateCommand.execute test to use an opsx-*.md prompt name, and keep the
assertions verifying both the prompt and SKILL.md remain after the
non-interactive no-force update. This should be fixed in the test case around
updateCommand.execute, detectLegacyArtifacts, and the promptDir/legacyPrompt
setup.

---

Outside diff comments:
In `@test/core/legacy-cleanup.test.ts`:
- Around line 1050-1163: Add a Windows-path regression test for
getToolsFromLegacyArtifacts by extending the existing
getToolsFromLegacyArtifacts describe block with a case that passes
backslash-separated legacy paths (for example in slashCommandFiles) and asserts
the same tool is detected. Use the existing getToolsFromLegacyArtifacts helper
and related detection shape, and verify the matcher normalizes separators so the
test would fail without the Windows path fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3f4eacb2-72a3-4738-9070-0ce5ccd33f44

📥 Commits

Reviewing files that changed from the base of the PR and between e821ed7 and d244ec3.

📒 Files selected for processing (27)

• docs/commands.md
• docs/how-commands-work.md
• docs/migration-guide.md
• docs/supported-tools.md
• docs/troubleshooting.md
• openspec/changes/make-codex-skills-only/.openspec.yaml
• openspec/changes/make-codex-skills-only/design.md
• openspec/changes/make-codex-skills-only/proposal.md
• openspec/changes/make-codex-skills-only/specs/ai-tool-paths/spec.md
• openspec/changes/make-codex-skills-only/specs/cli-init/spec.md
• openspec/changes/make-codex-skills-only/specs/cli-update/spec.md
• openspec/changes/make-codex-skills-only/specs/command-generation/spec.md
• openspec/changes/make-codex-skills-only/tasks.md
• src/core/command-generation/adapters/codex.ts
• src/core/command-generation/adapters/index.ts
• src/core/command-generation/registry.ts
• src/core/command-generation/types.ts
• src/core/command-surface.ts
• src/core/init.ts
• src/core/legacy-cleanup.ts
• src/core/profile-sync-drift.ts
• src/core/update.ts
• test/core/command-generation/adapters.test.ts
• test/core/command-generation/registry.test.ts
• test/core/init.test.ts
• test/core/legacy-cleanup.test.ts
• test/core/update.test.ts

💤 Files with no reviewable changes (3)

• src/core/command-generation/adapters/index.ts
• src/core/command-generation/adapters/codex.ts
• src/core/command-generation/registry.ts

✅ Files skipped from review due to trivial changes (9)

• docs/commands.md
• docs/how-commands-work.md
• openspec/changes/make-codex-skills-only/.openspec.yaml
• src/core/command-generation/types.ts
• docs/supported-tools.md
• docs/migration-guide.md
• openspec/changes/make-codex-skills-only/proposal.md
• docs/troubleshooting.md
• openspec/changes/make-codex-skills-only/tasks.md

🚧 Files skipped from review as they are similar to previous changes (9)

• test/core/command-generation/registry.test.ts
• src/core/command-surface.ts
• openspec/changes/make-codex-skills-only/specs/cli-init/spec.md
• test/core/command-generation/adapters.test.ts
• openspec/changes/make-codex-skills-only/specs/ai-tool-paths/spec.md
• openspec/changes/make-codex-skills-only/specs/command-generation/spec.md
• src/core/init.ts
• src/core/profile-sync-drift.ts
• src/core/update.ts

[TabishB]

Thanks for pushing this forward. The direction makes sense: Codex should move to skills and stop generating global prompt files. I think we need to tighten the migration safety before merging, mostly so we do not accidentally delete user prompts or leave older Codex users without a replacement. I left the specific spots inline.

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

src/core/legacy-cleanup.ts (1)

650-666: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Re-validate managed global prompt paths before unlinking (still unaddressed).

cleanupLegacyArtifacts() is exported and this loop unlinks every entry in detection.globalSlashCommandFiles unconditionally; the validated globalPromptMatchesByPath map is only consulted for replacement labels, not to gate deletion. A stale/malformed detection object could still delete arbitrary absolute paths. Guard each filePath with getManagedGlobalLegacyPromptMetadata(filePath) before fs.unlink.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/core/legacy-cleanup.ts` around lines 650 - 666, The managed global slash
command cleanup loop in cleanupLegacyArtifacts currently deletes every entry in
detection.globalSlashCommandFiles without re-checking that each path is still a
valid managed global prompt. Update this loop to validate each filePath with
getManagedGlobalLegacyPromptMetadata(filePath) before calling fs.unlink, and
only delete when the metadata confirms it is a managed global legacy prompt;
keep the existing globalPromptMatchesByPath logic only for replacement labels.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@openspec/changes/make-codex-skills-only/design.md`:
- Line 47: Use openspec-* consistently in this section instead of opsx-* to
match the rest of the design and the .codex/prompts/openspec-*.md naming. Update
the wording in the global cleanup/allowlist explanation so the referenced prompt
filenames and examples use the openspec prefix everywhere, including any
mentions tied to workflow ID inference or unmanaged user-authored files.

---

Duplicate comments:
In `@src/core/legacy-cleanup.ts`:
- Around line 650-666: The managed global slash command cleanup loop in
cleanupLegacyArtifacts currently deletes every entry in
detection.globalSlashCommandFiles without re-checking that each path is still a
valid managed global prompt. Update this loop to validate each filePath with
getManagedGlobalLegacyPromptMetadata(filePath) before calling fs.unlink, and
only delete when the metadata confirms it is a managed global legacy prompt;
keep the existing globalPromptMatchesByPath logic only for replacement labels.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 01e50aea-e1e5-4b79-86ff-e78ba840ff8c

📥 Commits

Reviewing files that changed from the base of the PR and between 8847835 and a29c458.

📒 Files selected for processing (16)

• .gitignore
• docs/migration-guide.md
• docs/troubleshooting.md
• openspec/changes/make-codex-skills-only/design.md
• openspec/changes/make-codex-skills-only/proposal.md
• openspec/changes/make-codex-skills-only/specs/ai-tool-paths/spec.md
• openspec/changes/make-codex-skills-only/specs/cli-init/spec.md
• openspec/changes/make-codex-skills-only/specs/cli-update/spec.md
• openspec/changes/make-codex-skills-only/tasks.md
• src/core/init.ts
• src/core/legacy-cleanup.ts
• src/core/update.ts
• test/core/init.test.ts
• test/core/legacy-cleanup.test.ts
• test/core/update.test.ts
• test/helpers/legacy-codex-prompt.ts

✅ Files skipped from review due to trivial changes (6)

• test/helpers/legacy-codex-prompt.ts
• .gitignore
• docs/migration-guide.md
• docs/troubleshooting.md
• openspec/changes/make-codex-skills-only/tasks.md
• openspec/changes/make-codex-skills-only/specs/ai-tool-paths/spec.md

🚧 Files skipped from review as they are similar to previous changes (3)

• openspec/changes/make-codex-skills-only/proposal.md
• openspec/changes/make-codex-skills-only/specs/cli-init/spec.md
• openspec/changes/make-codex-skills-only/specs/cli-update/spec.md

[showms]

Thanks for the careful review. I addressed the migration-safety issues in the latest update and added targeted tests for the new global prompt detection, deferred cleanup, and legacy workflow inference paths. @TabishB

[TabishB]

A few small cleanup changes would make this migration simpler and ensure it completes in one update run.

Requested changes were addressed in subsequent commits; all review threads are resolved and the current head has been revalidated.

[alfred-openspec]

Validated the current head after the latest rebase. The requested Codex migration changes are addressed, all review threads are resolved, and local build, strict change validation, lint, and the full 1,987-test suite pass.