Fission-AI · satyaborg · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026
@@ -140,6 +140,7 @@ openspec/
 └── config.yaml         # Project configuration
 
 .claude/skills/         # Claude Code skills (if claude selected)
+.agents/skills/         # Codex skills (if codex selected)
 .cursor/skills/         # Cursor skills (if cursor selected)
 .cursor/commands/       # Cursor OPSX commands (if delivery includes commands)
 ... (other tool configs)

@@ -683,7 +683,7 @@ The AI tool doesn't recognize OpenSpec commands.
 **Solutions:**
 - Ensure OpenSpec is initialized: `openspec init`
 - Regenerate skills: `openspec update`
-- Check that `.claude/skills/` directory exists (for Claude Code)
+- Check the selected tool's skill directory from [Supported Tools](supported-tools.md), such as `.claude/skills/` for Claude Code or `.agents/skills/` for Codex
 - Restart your AI tool to pick up new skills
 
 ### Artifacts not generating properly

@@ -29,7 +29,7 @@ You can enable expanded workflows (`new`, `continue`, `ff`, `verify`, `bulk-arch
 | Claude Code (`claude`) | `.claude/skills/openspec-*/SKILL.md` | `.claude/commands/opsx/<id>.md` |
 | Cline (`cline`) | `.cline/skills/openspec-*/SKILL.md` | `.clinerules/workflows/opsx-<id>.md` |
 | CodeBuddy (`codebuddy`) | `.codebuddy/skills/openspec-*/SKILL.md` | `.codebuddy/commands/opsx/<id>.md` |
-| Codex (`codex`) | `.codex/skills/openspec-*/SKILL.md` | `$CODEX_HOME/prompts/opsx-<id>.md`\* |
+| Codex (`codex`) | `.agents/skills/openspec-*/SKILL.md` | `$CODEX_HOME/prompts/opsx-<id>.md`\* |
 | ForgeCode (`forgecode`) | `.forge/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
 | Continue (`continue`) | `.continue/skills/openspec-*/SKILL.md` | `.continue/prompts/opsx-<id>.prompt` |
 | CoStrict (`costrict`) | `.cospec/skills/openspec-*/SKILL.md` | `.cospec/openspec/commands/opsx-<id>.md` |
@@ -54,6 +54,7 @@ You can enable expanded workflows (`new`, `continue`, `ff`, `verify`, `bulk-arch
 | Windsurf (`windsurf`) | `.windsurf/skills/openspec-*/SKILL.md` | `.windsurf/workflows/opsx-<id>.md` |
 
 \* Codex commands are installed in the global Codex home (`$CODEX_HOME/prompts/` if set, otherwise `~/.codex/prompts/`), not your project directory.
+Legacy OpenSpec Codex skills under `.codex/skills/openspec-*` are detected during setup/update and migrated to `.agents/skills`. Non-OpenSpec content under `.codex/skills` is left untouched.
 
 \*\* GitHub Copilot prompt files are recognized as custom slash commands in IDE extensions (VS Code, JetBrains, Visual Studio). Copilot CLI does not currently consume `.github/prompts/*.prompt.md` directly.
 

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-02
@@ -0,0 +1,70 @@
+## Context
+
+The active Codex skills-first PR fixes deprecated prompt generation, but it still keeps Codex skills under `.codex/skills`. Current OpenAI Codex docs use `.agents/skills` for repository skills, so OpenSpec needs a narrow path migration on top of skills-first behavior.
+
+Current OpenSpec path behavior is driven by `AI_TOOLS[].skillsDir`, then init/update append `skills`. Detection can be customized with `detectionPaths`, so the migration can reuse the existing configuration path rather than adding a separate Codex-only scanner.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Write Codex OpenSpec skills to `.agents/skills`.
+- Detect legacy Codex OpenSpec installs under `.codex/skills`.
+- Migrate managed legacy Codex skills by regenerating them under `.agents/skills`.
+- Remove only OpenSpec-managed legacy `.codex/skills/openspec-*` directories after successful regeneration.
+- Apply the same Codex skill migration and managed legacy cleanup to workspace-local Codex skills.
+- Update Codex docs and user output to consistently say `.agents/skills`.
+- Keep path handling cross-platform.
+
+**Non-Goals:**
+
+- Rework Codex custom prompt deprecation beyond what the skills-first PR already covers.
+- Rewrite unsupported Codex runtime tool names beyond existing or parallel Codex-safe transforms.
+- Add a generic `.agents` installer option for every tool.
+- Delete unmanaged `.codex` content.
+
+## Decisions
+
+### 1. Codex Current Skill Root Is `.agents`
+
+Set the Codex tool entry to `skillsDir: '.agents'`. Generated skill paths continue to be built by joining project root, `skillsDir`, `skills`, skill directory, and `SKILL.md`.
+
+Rationale: this keeps the general skill-generation pipeline intact and moves only Codex's configured root.
+
+### 2. Legacy `.codex` Is Detection And Cleanup Metadata
+
+Add explicit legacy metadata for Codex, such as `legacySkillsDirs: ['.codex']` and `detectionPaths: ['.agents/skills', '.codex/skills']`.
+
+Rationale: existing projects should still appear configured for Codex so `openspec update` can migrate them. Detection should not depend on broad globbing.
+
+### 3. Cleanup Is Limited To Managed OpenSpec Skill Directories
+
+After a successful `.agents/skills` write, remove only legacy `.codex/skills/<known-openspec-skill-dir>` directories. This applies to repo-local init/update and workspace-local skill setup/update. The known list should come from existing skill/workflow constants.
+
+Rationale: users may have unrelated Codex files or custom skills under `.codex`. The cleanup must not delete anything that is not a known OpenSpec generated skill directory.
+
+Alternative considered: leave `.codex/skills` untouched and only print a warning. Rejected because users asked for cleanup, and stale OpenSpec skills can keep confusing agents and contributors.
+
+Alternative considered: delete all of `.codex/skills`. Rejected because it can remove user-authored skills.
+
+### 4. Documentation Uses `.agents/skills` For Codex
+
+Codex rows, examples, and setup guidance should describe `.agents/skills`. Any `.codex/skills` mention should be framed only as a legacy migration note.
+
+Rationale: documentation is part of the migration. If docs keep `.codex/skills`, contributors will recreate the drift.
+
+## Risks / Trade-offs
+
+- **Risk: removing user edits inside generated OpenSpec skill directories** - Mitigation: remove only known `openspec-*` legacy directories and only after the replacement is written. This matches the generated artifact contract.
+- **Risk: duplicate skills during failed migration** - Mitigation: perform cleanup after successful `.agents/skills` generation, not before.
+- **Risk: duplicate workspace-local Codex skills** - Mitigation: workspace setup/update should use the same managed legacy cleanup rule as repo-local init/update.
+- **Risk: Windows path regressions** - Mitigation: use `path.join()` or existing file-system helpers and add path tests.
+- **Risk: PR overlap with #1143** - Mitigation: keep this change path-focused and avoid re-solving prompt deprecation.
+
+## Migration Plan
+
+1. Update Codex `AI_TOOLS` metadata to use `.agents`, detect `.agents/skills` and `.codex/skills`, and store legacy skill roots.
+2. Update init/update to remove managed legacy Codex skill directories after successful Codex skill generation.
+3. Update workspace skill setup/update to remove managed legacy Codex skill directories after successful workspace-local Codex skill generation.
+4. Update docs and output to reference `.agents/skills` for Codex.
+5. Add tests for current generation, legacy detection, migration cleanup, unmanaged content preservation, workspace migration cleanup, and cross-platform paths.
@@ -0,0 +1,32 @@
+## Why
+
+OpenAI's current Codex Skills convention discovers repository skills from `.agents/skills`, but OpenSpec's Codex integration and docs still have legacy `.codex/skills` assumptions in places. This creates the exact gap left by the skills-first Codex PR: prompts may be deprecated, but Codex skills still land in the wrong repo-local directory.
+
+## What Changes
+
+- Set Codex skill generation to `.agents/skills/openspec-*/SKILL.md`.
+- Detect legacy Codex OpenSpec skills in `.codex/skills` so existing projects are still recognized as configured for Codex.
+- On init/update refresh, migrate legacy Codex OpenSpec skills by regenerating them under `.agents/skills`.
+- Clean up only OpenSpec-managed legacy `.codex/skills/openspec-*` directories after the `.agents/skills` replacement succeeds.
+- Leave unmanaged or non-OpenSpec `.codex/skills` content untouched.
+- Update Codex-facing docs and success output so Codex skill paths consistently point to `.agents/skills`.
+
+## Capabilities
+
+### New Capabilities
+
+- None.
+
+### Modified Capabilities
+
+- `ai-tool-paths`: Codex uses `.agents` as its current skill root and treats `.codex` as a legacy detection and cleanup path.
+- `cli-init`: Codex setup writes skills to `.agents/skills`, detects legacy `.codex/skills`, and removes managed legacy Codex skill directories after successful regeneration.
+- `cli-update`: Codex refresh migrates existing `.codex/skills` installs to `.agents/skills`, preserves unmanaged legacy content, and reports the migration.
+- `workspace-links`: Codex workspace skills install to `.agents/skills`, migrate managed legacy `.codex/skills/openspec-*` directories, preserve unmanaged legacy content, and report the migration.
+
+## Impact
+
+- Affected code: `src/core/config.ts`, tool detection, init/update skill generation and cleanup, docs, and tests.
+- Affected docs: supported-tools tables and any Codex-specific setup/update guidance.
+- No new dependencies.
+- This is intended as a small follow-up to the active Codex skills-first work; it does not need to re-solve custom prompt deprecation or unsupported runtime tool-name rewrites.
@@ -0,0 +1,54 @@
+## ADDED Requirements
+
+### Requirement: Codex legacy skill path metadata
+The system SHALL keep explicit legacy Codex skill path metadata so existing `.codex/skills` installations can be detected and migrated.
+
+#### Scenario: Detecting current Codex skills
+- **WHEN** tool detection checks a project containing `.agents/skills`
+- **THEN** Codex SHALL be considered configured
+
+#### Scenario: Detecting legacy Codex skills
+- **WHEN** tool detection checks a project containing `.codex/skills`
+- **THEN** Codex SHALL be considered configured
+- **AND** Codex skill generation SHALL still target `.agents/skills`
+
+#### Scenario: Building Codex paths across platforms
+- **WHEN** constructing current or legacy Codex skill paths
+- **THEN** the system SHALL use platform-aware path handling
+
+## MODIFIED Requirements
+
+### Requirement: Path configuration for supported tools
+
+The `AI_TOOLS` array SHALL include `skillsDir` for tools that support the Agent Skills specification.
+
+#### Scenario: Claude Code paths defined
+
+- **WHEN** looking up the `claude` tool
+- **THEN** `skillsDir` SHALL be `.claude`
+
+#### Scenario: Cursor paths defined
+
+- **WHEN** looking up the `cursor` tool
+- **THEN** `skillsDir` SHALL be `.cursor`
+
+#### Scenario: Windsurf paths defined
+
+- **WHEN** looking up the `windsurf` tool
+- **THEN** `skillsDir` SHALL be `.windsurf`
+
+#### Scenario: Kimi CLI paths defined
+
+- **WHEN** looking up the `kimi` tool
+- **THEN** `skillsDir` SHALL be `.kimi`
+
+#### Scenario: Codex paths defined
+
+- **WHEN** looking up the `codex` tool
+- **THEN** `skillsDir` SHALL be `.agents`
+- **AND** legacy Codex skill detection SHALL include `.codex/skills`
+
+#### Scenario: Tools without skillsDir
+
+- **WHEN** a tool has no `skillsDir` defined
+- **THEN** skill generation SHALL error with message indicating the tool is not supported
@@ -0,0 +1,65 @@
+## MODIFIED Requirements
+
+### Requirement: AI Tool Configuration
+
+The command SHALL configure AI coding assistants with skills and slash commands using a searchable multi-select experience.
+
+#### Scenario: Prompting for AI tool selection
+
+- **WHEN** run interactively
+- **THEN** display animated welcome screen with OpenSpec logo
+- **AND** present a searchable multi-select that shows all available tools
+- **AND** mark already configured tools with "(configured ✓)" indicator
+- **AND** pre-select configured tools for easy refresh
+- **AND** sort configured tools to appear first in the list
+- **AND** allow filtering by typing to search
+
+#### Scenario: Selecting tools to configure
+
+- **WHEN** user selects tools and confirms
+- **THEN** generate skills in each selected tool's configured skill path
+- **AND** generate slash commands only for selected tools with a registered command adapter
+- **AND** create `openspec/config.yaml` with default schema setting
+
+#### Scenario: Selecting Codex
+
+- **WHEN** user selects Codex during initialization
+- **THEN** generate Codex OpenSpec skills in `.agents/skills`
+- **AND** treat `.codex/skills` only as a legacy detection and migration path
+- **AND** remove OpenSpec-managed legacy `.codex/skills/openspec-*` directories after the `.agents/skills` replacement succeeds
+
+### Requirement: Skill Generation
+
+The command SHALL generate Agent Skills for selected AI tools.
+
+#### Scenario: Generating skills for a tool
+
+- **WHEN** a tool is selected during initialization
+- **THEN** create 9 skill directories under the selected tool's configured skill path:
+  - `openspec-explore/SKILL.md`
+  - `openspec-new-change/SKILL.md`
+  - `openspec-continue-change/SKILL.md`
+  - `openspec-apply-change/SKILL.md`
+  - `openspec-ff-change/SKILL.md`
+  - `openspec-verify-change/SKILL.md`
+  - `openspec-sync-specs/SKILL.md`
+  - `openspec-archive-change/SKILL.md`
+  - `openspec-bulk-archive-change/SKILL.md`
+- **AND** each SKILL.md SHALL contain YAML frontmatter with name and description
+- **AND** each SKILL.md SHALL contain the skill instructions
+
+#### Scenario: Generating Codex skills
+
+- **WHEN** Codex is selected during initialization
+- **THEN** create Codex skill directories under `.agents/skills`
+- **AND** do not create Codex OpenSpec skills under `.codex/skills`
+
+#### Scenario: Preserving unmanaged legacy Codex content
+
+- **WHEN** Codex initialization encounters `.codex/skills` content outside known OpenSpec-managed skill directories
+- **THEN** the system SHALL leave that content untouched
+
+#### Scenario: Constructing skill paths across platforms
+
+- **WHEN** skill paths are generated for any selected tool
+- **THEN** the system SHALL construct paths using platform-aware path handling
@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: Codex legacy skill migration
+The update command SHALL migrate legacy Codex OpenSpec skills from `.codex/skills` to `.agents/skills`.
+
+#### Scenario: Updating current Codex skills
+- **WHEN** a project has Codex OpenSpec skills under `.agents/skills`
+- **AND** the user runs `openspec update`
+- **THEN** OpenSpec SHALL refresh Codex OpenSpec skills under `.agents/skills`
+
+#### Scenario: Migrating legacy Codex skills
+- **WHEN** a project has Codex OpenSpec skills under `.codex/skills`
+- **AND** the user runs `openspec update`
+- **THEN** OpenSpec SHALL generate refreshed Codex OpenSpec skills under `.agents/skills`
+- **AND** remove OpenSpec-managed legacy `.codex/skills/openspec-*` directories after the replacement succeeds
+- **AND** report that legacy Codex skills were migrated
+
+#### Scenario: Preserving unmanaged legacy Codex skills
+- **WHEN** a project has non-OpenSpec or unmanaged content under `.codex/skills`
+- **AND** the user runs `openspec update`
+- **THEN** OpenSpec SHALL leave that unmanaged content untouched
+
+#### Scenario: Failed Codex migration
+- **WHEN** writing Codex OpenSpec skills to `.agents/skills` fails
+- **THEN** OpenSpec SHALL leave legacy `.codex/skills` content untouched
+- **AND** surface the write failure with the affected path
+
+#### Scenario: Constructing migration paths across platforms
+- **WHEN** the update command migrates Codex OpenSpec skills
+- **THEN** the system SHALL construct `.agents/skills` and `.codex/skills` paths using platform-aware path handling
@@ -0,0 +1,41 @@
+## MODIFIED Requirements
+
+### Requirement: Workspace setup installs agent skills
+OpenSpec SHALL let users install OpenSpec agent skills into a workspace during workspace setup.
+
+#### Scenario: Installing Codex workspace skills
+- **WHEN** workspace setup installs Codex agent skills
+- **THEN** OpenSpec SHALL generate workspace-local Codex OpenSpec skills under `.agents/skills`
+- **AND** it SHALL NOT generate Codex OpenSpec skills under `.codex/skills`
+- **AND** it SHALL treat `.codex/skills` only as a legacy detection and migration path
+
+#### Scenario: Cleaning managed legacy Codex skills during workspace setup
+- **WHEN** workspace setup installs Codex agent skills
+- **AND** the workspace root contains OpenSpec-managed legacy `.codex/skills/openspec-*` directories
+- **THEN** OpenSpec SHALL remove those managed legacy directories only after the `.agents/skills` replacement succeeds
+- **AND** it SHALL leave unmanaged `.codex/skills` content untouched
+
+### Requirement: Workspace update manages agent skills
+OpenSpec SHALL provide a workspace update flow for refreshing agent skills after setup.
+
+#### Scenario: Updating current Codex workspace skills
+- **WHEN** workspace update refreshes Codex agent skills
+- **AND** the workspace has Codex OpenSpec skills under `.agents/skills`
+- **THEN** OpenSpec SHALL refresh Codex OpenSpec skills under `.agents/skills`
+
+#### Scenario: Migrating legacy Codex workspace skills
+- **WHEN** workspace update refreshes Codex agent skills
+- **AND** the workspace root contains OpenSpec-managed legacy `.codex/skills/openspec-*` directories
+- **THEN** OpenSpec SHALL generate refreshed Codex OpenSpec skills under `.agents/skills`
+- **AND** remove OpenSpec-managed legacy `.codex/skills/openspec-*` directories after the replacement succeeds
+- **AND** report that legacy workspace Codex skills were migrated
+
+#### Scenario: Preserving unmanaged legacy Codex workspace skills
+- **WHEN** workspace update refreshes Codex agent skills
+- **AND** the workspace root contains non-OpenSpec or unmanaged content under `.codex/skills`
+- **THEN** OpenSpec SHALL leave that unmanaged content untouched
+
+#### Scenario: Failed workspace Codex migration
+- **WHEN** workspace update fails to write Codex OpenSpec skills to `.agents/skills`
+- **THEN** OpenSpec SHALL leave legacy `.codex/skills` content untouched
+- **AND** surface the write failure with the affected path