ContextQMD
Back to Openspec

Tasks

openspec/changes/make-codex-skills-only/tasks.md

1.12.05.2 KB
Original Source

1. Command Adapter Surface

  • 1.1 Remove Codex from command adapter registration so CommandAdapterRegistry.get('codex') returns undefined.
  • 1.2 Remove Codex command adapter exports and delete or retire Codex adapter-specific tests.
  • 1.3 Update command-generation types, comments, and examples that describe Codex as a global command target.
  • 1.4 Update registry tests to assert Codex is not included in getAll() or has('codex').

2. Codex Skills-Only Delivery

  • 2.1 Reuse the command-surface capability model for Codex by resolving Codex as skills-invocable; do not add a Codex-only delivery predicate.
  • 2.2 Update openspec init generation so Codex skills are created for both, skills, and commands delivery modes.
  • 2.3 Update openspec init command cleanup so commands delivery does not remove Codex OpenSpec skill directories.
  • 2.4 Update openspec update generation so configured Codex skills are refreshed for both, skills, and commands delivery modes.
  • 2.5 Update openspec update delivery reconciliation so commands delivery does not remove Codex OpenSpec skill directories.
  • 2.6 Keep command generation skipped for Codex whenever command generation would otherwise run.
  • 2.7 If add-tool-command-surface-capabilities has not landed first, stage the smallest shared capability helper needed so Codex and later skills-invocable tools use the same path.

3. Legacy Codex Prompt Cleanup

  • 3.1 Add final Codex prompt cleanup support: allowlisted globally managed Codex legacy prompt filenames plus repo-local .codex/prompts/openspec-*.md compatibility cleanup.
  • 3.2 Resolve the global Codex prompt directory from CODEX_HOME when set and the default user .codex/prompts directory when unset.
  • 3.3 Detect exact allowlisted global Codex prompt files under the resolved prompt directory, infer workflow IDs from those filenames, and leave non-allowlisted prompt files untouched.
  • 3.4 Remove managed global Codex prompt files only after replacement Codex skills exist for the represented workflows.
  • 3.5 Preserve existing project-local .codex/prompts/openspec-*.md cleanup compatibility.
  • 3.6 Update cleanup summaries to identify removed Codex prompt files as replaced by Codex skills.
  • 3.6a Present deferred global prompts cleanup separately from immediate repo-local removals while listing the affected global prompt files.
  • 3.7 Ensure non-interactive openspec init without --force removes only the managed global Codex prompt files whose replacement skills exist and preserves unreplaced prompts.
  • 3.8 Ensure non-interactive openspec update without --force uses the existing legacy-cleanup warning path and leaves legacy files untouched.

4. Documentation and Messaging

  • 4.1 Update docs/supported-tools.md to list Codex as skills-only and remove the $CODEX_HOME/prompts command path.
  • 4.2 Update command and troubleshooting docs so Codex guidance points to .codex/skills/openspec-*.
  • 4.3 Update installation or migration guidance to mention managed Codex prompt cleanup and the breaking change.
  • 4.4 Update CLI success or skipped-command messaging if needed so Codex users understand skills were installed even when commands are skipped.

5. Tests and Validation

  • 5.1 Add openspec init tests for Codex under both, skills, and commands delivery modes, verifying skills exist and global prompt files are not created.
  • 5.2 Add openspec update tests for Codex under both, skills, and commands delivery modes, verifying skills are refreshed and not removed by commands-only delivery.
  • 5.3 Add cleanup tests for allowlisted managed global Codex prompt files under CODEX_HOME/prompts, and verify custom or non-allowlisted prompts remain unmanaged.
  • 5.4 Add cleanup tests proving unmanaged files in the Codex prompt directory are preserved.
  • 5.5 Add non-interactive init cleanup tests proving managed global Codex prompt files are removed only after replacement skills exist.
  • 5.6 Add non-interactive update cleanup tests proving global Codex prompt files are preserved without --force.
  • 5.7 Add cross-platform path tests that construct Codex cleanup paths with path utilities rather than hardcoded separators.
  • 5.8 Update or remove tests that import the removed Codex adapter directly.
  • 5.9 Add command-surface tests proving Codex resolves as skills-invocable and does not require a command adapter.
  • 5.10 Run targeted test suites for command generation, init, update, legacy cleanup, and docs-related snapshots if present.
  • 5.11 Run openspec validate make-codex-skills-only --strict.

6. Review Follow-up

  • 6.1 Add opsx-update.md to the managed global Codex prompt allowlist and map it to the update workflow.
  • 6.2 Simplify managed global Codex prompt detection to exact directory and filename allowlisting so prompts from older template revisions still migrate.
  • 6.3 Defer approved global Codex prompt cleanup until after configured tools refresh, allowing replacement skills and prompt cleanup to complete in one update run.
  • 6.4 Update focused tests and change artifacts for the final allowlist and cleanup ordering behavior.