@every-env/compound-plugin 2.40.1 → 2.40.3

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
   "plugins": [
     {
       "name": "compound-engineering",
-      "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 28 specialized agents and 46 skills.",
+      "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 28 specialized agents and 41 skills.",
       "version": "2.40.0",
       "author": {
         "name": "Kieran Klaassen",

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Release numbering now follows the repository `v*` tag line. Starting at `v2.34.0`, the root CLI package and this changelog stay on that shared version stream. Older entries below retain the previous `0.x` CLI numbering.
 
+## [2.40.3](https://github.com/EveryInc/compound-engineering-plugin/compare/v2.40.2...v2.40.3) (2026-03-17)
+
+
+### Bug Fixes
+
+* research agents prefer native tools over shell for repo exploration ([b290690](https://github.com/EveryInc/compound-engineering-plugin/commit/b2906906555810fca176fa4e0153bf080446c486))
+
+## [2.40.2](https://github.com/EveryInc/compound-engineering-plugin/compare/v2.40.1...v2.40.2) (2026-03-17)
+
+
+### Bug Fixes
+
+* harden codex copied skill rewriting ([#285](https://github.com/EveryInc/compound-engineering-plugin/issues/285)) ([6f561f9](https://github.com/EveryInc/compound-engineering-plugin/commit/6f561f94b4397ca6df2ab163e6f1253817bd7cea))
+
 ## [2.40.1](https://github.com/EveryInc/compound-engineering-plugin/compare/v2.40.0...v2.40.1) (2026-03-17)
 
 

package/README.md

@@ -82,7 +82,7 @@ Then run `claude-dev-ce` instead of `claude` to test your changes. Your producti
 **Codex** — point the install command at your local path:
 
 ```bash
-bunx @every-env/compound-plugin install ./plugins/compound-engineering --to codex
+bun run src/index.ts install ./plugins/compound-engineering --to codex
 ```
 
 **Other targets** — same pattern, swap the target:
@@ -97,7 +97,7 @@ bun run src/index.ts install ./plugins/compound-engineering --to opencode
 | Target | Output path | Notes |
 |--------|------------|-------|
 | `opencode` | `~/.config/opencode/` | Commands as `.md` files; `opencode.json` MCP config deep-merged; backups made before overwriting |
-| `codex` | `~/.codex/prompts` + `~/.codex/skills` | Each command becomes a prompt + skill pair; descriptions truncated to 1024 chars |
+| `codex` | `~/.codex/prompts` + `~/.codex/skills` | Claude commands become prompt + skill pairs; canonical `ce:*` workflow skills also get prompt wrappers; deprecated `workflows:*` aliases are omitted |
 | `droid` | `~/.factory/` | Tool names mapped (`Bash`→`Execute`, `Write`→`Create`); namespace prefixes stripped |
 | `pi` | `~/.pi/agent/` | Prompts, skills, extensions, and `mcporter.json` for MCPorter interoperability |
 | `gemini` | `.gemini/` | Skills from agents; commands as `.toml`; namespaced commands become directories (`workflows:plan` → `commands/workflows/plan.toml`) |

package/docs/solutions/codex-skill-prompt-entrypoints.md

@@ -0,0 +1,152 @@
+---
+title: Codex Conversion Skills, Prompts, and Canonical Entry Points
+category: architecture
+tags: [codex, converter, skills, prompts, workflows, deprecation]
+created: 2026-03-15
+severity: medium
+component: codex-target
+problem_type: best_practice
+root_cause: outdated_target_model
+---
+
+# Codex Conversion Skills, Prompts, and Canonical Entry Points
+
+## Problem
+
+The Codex target had two conflicting assumptions:
+
+1. Compound workflow entrypoints like `ce:brainstorm` and `ce:plan` were treated in docs as slash-command-style surfaces.
+2. The Codex converter installed those entries as copied skills, not as generated prompts.
+
+That created an inconsistent runtime for cross-workflow handoffs. Copied skill content still contained Claude-style references like `/ce:plan`, but no Codex-native translation was applied to copied `SKILL.md` files, and there was no clear canonical Codex entrypoint model for those workflow skills.
+
+## What We Learned
+
+### 1. Codex supports both skills and prompts, and they are different surfaces
+
+- Skills are loaded from skill roots such as `~/.codex/skills`, and newer Codex code also supports `.agents/skills`.
+- Prompts are a separate explicit entrypoint surface under `.codex/prompts`.
+- A skill is not automatically a prompt, and a prompt is not automatically a skill.
+
+For this repo, that means a copied skill like `ce:plan` is only a skill unless the converter also generates a prompt wrapper for it.
+
+### 2. Codex skill names come from the directory name
+
+Codex derives the skill name from the skill directory basename, not from our normalized hyphenated converter name.
+
+Implication:
+
+- `~/.codex/skills/ce:plan` loads as the skill `ce:plan`
+- Rewriting that to `ce-plan` is wrong for skill-to-skill references
+
+### 3. The original bug was structural, not just wording
+
+The issue was not that `ce:brainstorm` needed slightly different prose. The real problem was:
+
+- copied skills bypassed Codex-specific transformation
+- workflow handoffs referenced a surface that was not clearly represented in installed Codex artifacts
+
+### 4. Deprecated `workflows:*` aliases add noise in Codex
+
+The `workflows:*` names exist only for backward compatibility in Claude.
+
+Copying them into Codex would:
+
+- duplicate user-facing entrypoints
+- complicate handoff rewriting
+- increase ambiguity around which name is canonical
+
+For Codex, the simpler model is to treat `ce:*` as the only canonical workflow namespace and omit `workflows:*` aliases from installed output.
+
+## Recommended Codex Model
+
+Use a two-layer mapping for workflow entrypoints:
+
+1. **Skills remain the implementation units**
+   - Copy the canonical workflow skills using their exact names, such as `ce:plan`
+   - Preserve exact skill names for any Codex skill references
+
+2. **Prompts are the explicit entrypoint layer**
+   - Generate prompt wrappers for canonical user-facing workflow entrypoints
+   - Use Codex-safe prompt slugs such as `ce-plan`, `ce-work`, `ce-review`
+   - Prompt wrappers delegate to the exact underlying skill name, such as `ce:plan`
+
+This gives Codex one clear manual invocation surface while preserving the real loaded skill names internally.
+
+## Rewrite Rules
+
+When converting copied `SKILL.md` content for Codex:
+
+- References to canonical workflow entrypoints should point to generated prompt wrappers
+  - `/ce:plan` -> `/prompts:ce-plan`
+  - `/ce:work` -> `/prompts:ce-work`
+- References to deprecated aliases should canonicalize to the modern `ce:*` prompt
+  - `/workflows:plan` -> `/prompts:ce-plan`
+- References to non-entrypoint skills should use the exact skill name, not a normalized alias
+- Actual Claude commands that are converted to Codex prompts can continue using `/prompts:...`
+
+### Regression hardening
+
+When rewriting copied `SKILL.md` files, only known workflow and command references should be rewritten.
+
+Do not rewrite arbitrary slash-shaped text such as:
+
+- application routes like `/users` or `/settings`
+- API path segments like `/state` or `/ops`
+- URLs such as `https://www.proofeditor.ai/...`
+
+Unknown slash references should remain unchanged in copied skill content. Otherwise Codex installs silently corrupt unrelated skills while trying to canonicalize workflow handoffs.
+
+Personal skills loaded from `~/.claude/skills` also need tolerant metadata parsing:
+
+- malformed YAML frontmatter should not cause the entire skill to disappear
+- keep the directory name as the stable skill name
+- treat frontmatter metadata as best-effort only
+
+## Future Entry Points
+
+Do not hard-code an allowlist of workflow names in the converter.
+
+Instead, use a stable rule:
+
+- `ce:*` = canonical workflow entrypoint
+  - auto-generate a prompt wrapper
+- `workflows:*` = deprecated alias
+  - omit from Codex output
+  - rewrite references to the canonical `ce:*` target
+- non-`ce:*` skills = skill-only by default
+  - if a non-`ce:*` skill should also be a prompt entrypoint, mark it explicitly with Codex-specific metadata
+
+This means future skills like `ce:ideate` should work without manual converter changes.
+
+## Implementation Guidance
+
+For the Codex target:
+
+1. Parse enough skill frontmatter to distinguish command-like entrypoint skills from background skills
+2. Filter deprecated `workflows:*` alias skills out of Codex installation
+3. Generate prompt wrappers for canonical `ce:*` workflow skills
+4. Apply Codex-specific transformation to copied `SKILL.md` files
+5. Preserve exact Codex skill names internally
+6. Update README language so Codex entrypoints are documented as Codex-native surfaces, not assumed to be identical to Claude slash commands
+
+## Prevention
+
+Before changing the Codex converter again:
+
+1. Verify whether the target surface is a skill, a prompt, or both
+2. Check how Codex derives names from installed artifacts
+3. Decide which names are canonical before copying deprecated aliases
+4. Add tests for copied skill content, not just generated prompt content
+
+## Related Files
+
+- `src/converters/claude-to-codex.ts`
+- `src/targets/codex.ts`
+- `src/types/codex.ts`
+- `tests/codex-converter.test.ts`
+- `tests/codex-writer.test.ts`
+- `README.md`
+- `plugins/compound-engineering/skills/ce-brainstorm/SKILL.md`
+- `plugins/compound-engineering/skills/ce-plan/SKILL.md`
+- `docs/solutions/adding-converter-target-providers.md`

package/docs/specs/codex.md

@@ -48,7 +48,9 @@ https://developers.openai.com/codex/mcp
 - `SKILL.md` uses YAML front matter and requires `name` and `description`. citeturn3view3turn3view4
 - Required fields are single-line with length limits (name ≤ 100 chars, description ≤ 500 chars). citeturn3view4
 - At startup, Codex loads only each skill’s name/description; full content is injected when invoked. citeturn3view3turn3view4
-- Skills can be repo-scoped in `.codex/skills/` or user-scoped in `~/.codex/skills/`. citeturn3view4
+- Skills can be repo-scoped in `.agents/skills/` and are discovered from the current working directory up to the repository root. User-scoped skills live in `~/.agents/skills/`. citeturn1view1turn1view4
+- Inference: some existing tooling and user setups still use `.codex/skills/` and `~/.codex/skills/` as legacy compatibility paths, but those locations are not documented in the current OpenAI Codex skills docs linked above.
+- Codex also supports admin-scoped skills in `/etc/codex/skills` plus built-in system skills bundled with Codex. citeturn1view4
 - Skills can be invoked explicitly using `/skills` or `$skill-name`. citeturn3view3
 
 ## MCP (Model Context Protocol)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@every-env/compound-plugin",
-  "version": "2.40.1",
+  "version": "2.40.3",
   "type": "module",
   "private": false,
   "bin": {

package/plugins/compound-engineering/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "compound-engineering",
   "version": "2.40.0",
-  "description": "AI-powered development tools. 28 agents, 46 skills, 1 MCP server for code review, research, design, and workflow automation.",
+  "description": "AI-powered development tools. 28 agents, 41 skills, 1 MCP server for code review, research, design, and workflow automation.",
   "author": {
     "name": "Kieran Klaassen",
     "email": "kieran@every.to",

package/plugins/compound-engineering/AGENTS.md

@@ -40,7 +40,6 @@ agents/
 
 skills/
 ├── ce-*/          # Core workflow skills (ce:plan, ce:review, etc.)
-├── workflows-*/   # Deprecated aliases for ce:* skills
 └── */             # All other skills
 ```
 
@@ -57,7 +56,7 @@ skills/
 - `/ce:work` - Execute work items systematically
 - `/ce:compound` - Document solved problems
 
-**Why `ce:`?** Claude Code has built-in `/plan` and `/review` commands. The `ce:` namespace (short for compound-engineering) makes it immediately clear these commands belong to this plugin. The legacy `workflows:` prefix is still supported as deprecated aliases that forward to the `ce:*` equivalents.
+**Why `ce:`?** Claude Code has built-in `/plan` and `/review` commands. The `ce:` namespace (short for compound-engineering) makes it immediately clear these commands belong to this plugin.
 
 ## Skill Compliance Checklist
 
@@ -94,6 +93,18 @@ This plugin is authored once, then converted for other agent platforms. Commands
 - [ ] When one skill refers to another skill, prefer semantic wording such as "load the `document-review` skill" rather than slash syntax.
 - [ ] Use slash syntax only when referring to an actual published command or workflow such as `/ce:work` or `/deepen-plan`.
 
+### Tool Selection in Agents and Skills
+
+Agents and skills that explore codebases must prefer native tools over shell commands.
+
+Why: shell-heavy exploration causes avoidable permission prompts in sub-agent workflows; native file-search, content-search, and file-read tools avoid that.
+
+- [ ] Never instruct agents to use `find`, `ls`, `cat`, `head`, `tail`, `grep`, `rg`, `wc`, or `tree` through a shell for routine file discovery, content search, or file reading
+- [ ] Describe tools by capability class with platform hints — e.g., "Use the native file-search/glob tool (e.g., Glob in Claude Code)" — not by Claude Code-specific tool names alone
+- [ ] When shell is the only option (e.g., `ast-grep`, `bundle show`, git commands), instruct one simple command at a time — no chaining (`&&`, `||`, `;`), pipes, or redirects
+- [ ] Do not encode shell recipes for routine exploration when native tools can do the job; encode intent and preferred tool classes instead
+- [ ] For shell-only workflows (e.g., `gh`, `git`, `bundle show`, project CLIs), explicit command examples are acceptable when they are simple, task-scoped, and not chained together
+
 ### Quick Validation Command
 
 ```bash

package/plugins/compound-engineering/README.md

@@ -83,8 +83,6 @@ Core workflow commands use `ce:` prefix to unambiguously identify them as compou
 | `/ce:compound` | Document solved problems to compound team knowledge |
 | `/ce:compound-refresh` | Refresh stale or drifting learnings and decide whether to keep, update, replace, or archive them |
 
-> **Deprecated aliases:** `/workflows:plan`, `/workflows:work`, `/workflows:review`, `/workflows:brainstorm`, `/workflows:compound` still work but show a deprecation warning. Use `ce:*` equivalents.
-
 ### Utility Commands
 
 | Command | Description |

package/plugins/compound-engineering/agents/research/best-practices-researcher.md

@@ -30,9 +30,12 @@ You are an expert technology researcher specializing in discovering, analyzing,
 Before going online, check if curated knowledge already exists in skills:
 
 1. **Discover Available Skills**:
-   - Use Glob to find all SKILL.md files: `**/**/SKILL.md` and `~/.claude/skills/**/SKILL.md`
-   - Also check project-level skills: `.claude/skills/**/SKILL.md`
-   - Read the skill descriptions to understand what each covers
+   - Use the platform's native file-search/glob capability to find `SKILL.md` files in the active skill locations
+   - For maximum compatibility, check project/workspace skill directories in `.claude/skills/**/SKILL.md`, `.codex/skills/**/SKILL.md`, and `.agents/skills/**/SKILL.md`
+   - Also check user/home skill directories in `~/.claude/skills/**/SKILL.md`, `~/.codex/skills/**/SKILL.md`, and `~/.agents/skills/**/SKILL.md`
+   - In Codex environments, `.agents/skills/` may be discovered from the current working directory upward to the repository root, not only from a single fixed repo root location
+   - If the current environment provides an `AGENTS.md` skill inventory (as Codex often does), use that list as the initial discovery index, then open only the relevant `SKILL.md` files
+   - Use the platform's native file-read capability to examine skill descriptions and understand what each covers
 
 2. **Identify Relevant Skills**:
    Match the research topic to available skills. Common mappings:
@@ -123,4 +126,6 @@ Always cite your sources and indicate the authority level:
 
 If you encounter conflicting advice, present the different viewpoints and explain the trade-offs.
 
+**Tool Selection:** Use native file-search/glob (e.g., `Glob`), content-search (e.g., `Grep`), and file-read (e.g., `Read`) tools for repository exploration. Only use shell for commands with no native equivalent (e.g., `bundle show`), one command at a time.
+
 Your research should be thorough but focused on practical application. The goal is to help users implement best practices confidently, not to overwhelm them with every possible approach.

package/plugins/compound-engineering/agents/research/framework-docs-researcher.md

@@ -103,4 +103,6 @@ Structure your findings as:
 6. **Common Issues**: Known problems and their solutions
 7. **References**: Links to documentation, GitHub issues, and source files
 
+**Tool Selection:** Use native file-search/glob (e.g., `Glob`), content-search (e.g., `Grep`), and file-read (e.g., `Read`) tools for repository exploration. Only use shell for commands with no native equivalent (e.g., `bundle show`), one command at a time.
+
 Remember: You are the bridge between complex documentation and practical implementation. Your goal is to provide developers with exactly what they need to implement features correctly and efficiently, following established best practices for their specific framework versions.

package/plugins/compound-engineering/agents/research/git-history-analyzer.md

@@ -23,17 +23,19 @@ assistant: "Let me use the git-history-analyzer agent to investigate the histori
 
 You are a Git History Analyzer, an expert in archaeological analysis of code repositories. Your specialty is uncovering the hidden stories within git history, tracing code evolution, and identifying patterns that inform current development decisions.
 
+**Tool Selection:** Use native file-search/glob (e.g., `Glob`), content-search (e.g., `Grep`), and file-read (e.g., `Read`) tools for all non-git exploration. Use shell only for git commands, one command per call.
+
 Your core responsibilities:
 
-1. **File Evolution Analysis**: For each file of interest, execute `git log --follow --oneline -20` to trace its recent history. Identify major refactorings, renames, and significant changes.
+1. **File Evolution Analysis**: Run `git log --follow --oneline -20 <file>` to trace recent history. Identify major refactorings, renames, and significant changes.
 
-2. **Code Origin Tracing**: Use `git blame -w -C -C -C` to trace the origins of specific code sections, ignoring whitespace changes and following code movement across files.
+2. **Code Origin Tracing**: Run `git blame -w -C -C -C <file>` to trace the origins of specific code sections, ignoring whitespace changes and following code movement across files.
 
-3. **Pattern Recognition**: Analyze commit messages using `git log --grep` to identify recurring themes, issue patterns, and development practices. Look for keywords like 'fix', 'bug', 'refactor', 'performance', etc.
+3. **Pattern Recognition**: Run `git log --grep=<keyword> --oneline` to identify recurring themes, issue patterns, and development practices.
 
-4. **Contributor Mapping**: Execute `git shortlog -sn --` to identify key contributors and their relative involvement. Cross-reference with specific file changes to map expertise domains.
+4. **Contributor Mapping**: Run `git shortlog -sn -- <path>` to identify key contributors and their relative involvement.
 
-5. **Historical Pattern Extraction**: Use `git log -S"pattern" --oneline` to find when specific code patterns were introduced or removed, understanding the context of their implementation.
+5. **Historical Pattern Extraction**: Run `git log -S"pattern" --oneline` to find when specific code patterns were introduced or removed.
 
 Your analysis methodology:
 - Start with a broad view of file history before diving into specifics

package/plugins/compound-engineering/agents/research/repo-research-analyst.md

@@ -56,8 +56,10 @@ You are an expert repository research analyst specializing in understanding code
    - Analyze template structure and required fields
 
 5. **Codebase Pattern Search**
-   - Use `ast-grep` for syntax-aware pattern matching when available
-   - Fall back to `rg` for text-based searches when appropriate
+   - Use the native content-search tool for text and regex pattern searches
+   - Use the native file-search/glob tool to discover files by name or extension
+   - Use the native file-read tool to examine file contents
+   - Use `ast-grep` via shell when syntax-aware pattern matching is needed
    - Identify common implementation patterns
    - Document naming conventions and code organization
 
@@ -115,14 +117,7 @@ Structure your findings as:
 - Flag any contradictions or outdated information
 - Provide specific file paths and examples to support findings
 
-**Search Strategies:**
-
-Use the built-in tools for efficient searching:
-- **Grep tool**: For text/code pattern searches with regex support (uses ripgrep under the hood)
-- **Glob tool**: For file discovery by pattern (e.g., `**/*.md`, `**/CLAUDE.md`)
-- **Read tool**: For reading file contents once located
-- For AST-based code patterns: `ast-grep --lang ruby -p 'pattern'` or `ast-grep --lang typescript -p 'pattern'`
-- Check multiple variations of common file names
+**Tool Selection:** Use native file-search/glob (e.g., `Glob`), content-search (e.g., `Grep`), and file-read (e.g., `Read`) tools for repository exploration. Only use shell for commands with no native equivalent (e.g., `ast-grep`), one command at a time.
 
 **Important Considerations:**
 

package/src/converters/claude-to-codex.ts

@@ -1,7 +1,12 @@
 import { formatFrontmatter } from "../utils/frontmatter"
-import type { ClaudeAgent, ClaudeCommand, ClaudePlugin } from "../types/claude"
+import type { ClaudeAgent, ClaudeCommand, ClaudePlugin, ClaudeSkill } from "../types/claude"
 import type { CodexBundle, CodexGeneratedSkill } from "../types/codex"
 import type { ClaudeToOpenCodeOptions } from "./claude-to-opencode"
+import {
+  normalizeCodexName,
+  transformContentForCodex,
+  type CodexInvocationTargets,
+} from "../utils/codex-content"
 
 export type ClaudeToCodexOptions = ClaudeToOpenCodeOptions
 
@@ -11,42 +16,102 @@ export function convertClaudeToCodex(
   plugin: ClaudePlugin,
   _options: ClaudeToCodexOptions,
 ): CodexBundle {
-  const promptNames = new Set<string>()
-  const skillDirs = plugin.skills.map((skill) => ({
+  const invocableCommands = plugin.commands.filter((command) => !command.disableModelInvocation)
+  const applyCompoundWorkflowModel = shouldApplyCompoundWorkflowModel(plugin)
+  const canonicalWorkflowSkills = applyCompoundWorkflowModel
+    ? plugin.skills.filter((skill) => isCanonicalCodexWorkflowSkill(skill.name))
+    : []
+  const deprecatedWorkflowAliases = applyCompoundWorkflowModel
+    ? plugin.skills.filter((skill) => isDeprecatedCodexWorkflowAlias(skill.name))
+    : []
+  const copiedSkills = applyCompoundWorkflowModel
+    ? plugin.skills.filter((skill) => !isDeprecatedCodexWorkflowAlias(skill.name))
+    : plugin.skills
+  const skillDirs = copiedSkills.map((skill) => ({
     name: skill.name,
     sourceDir: skill.sourceDir,
   }))
+  const promptNames = new Set<string>()
+  const usedSkillNames = new Set<string>(skillDirs.map((skill) => normalizeCodexName(skill.name)))
+
+  const commandPromptNames = new Map<string, string>()
+  for (const command of invocableCommands) {
+    commandPromptNames.set(
+      command.name,
+      uniqueName(normalizeCodexName(command.name), promptNames),
+    )
+  }
+
+  const workflowPromptNames = new Map<string, string>()
+  for (const skill of canonicalWorkflowSkills) {
+    workflowPromptNames.set(
+      skill.name,
+      uniqueName(normalizeCodexName(skill.name), promptNames),
+    )
+  }
+
+  const promptTargets: Record<string, string> = {}
+  for (const [commandName, promptName] of commandPromptNames) {
+    promptTargets[normalizeCodexName(commandName)] = promptName
+  }
+  for (const [skillName, promptName] of workflowPromptNames) {
+    promptTargets[normalizeCodexName(skillName)] = promptName
+  }
+  for (const alias of deprecatedWorkflowAliases) {
+    const canonicalName = toCanonicalWorkflowSkillName(alias.name)
+    const promptName = canonicalName ? workflowPromptNames.get(canonicalName) : undefined
+    if (promptName) {
+      promptTargets[normalizeCodexName(alias.name)] = promptName
+    }
+  }
+
+  const skillTargets: Record<string, string> = {}
+  for (const skill of copiedSkills) {
+    if (applyCompoundWorkflowModel && isCanonicalCodexWorkflowSkill(skill.name)) continue
+    skillTargets[normalizeCodexName(skill.name)] = skill.name
+  }
+
+  const invocationTargets: CodexInvocationTargets = { promptTargets, skillTargets }
 
-  const usedSkillNames = new Set<string>(skillDirs.map((skill) => normalizeName(skill.name)))
   const commandSkills: CodexGeneratedSkill[] = []
-  const invocableCommands = plugin.commands.filter((command) => !command.disableModelInvocation)
   const prompts = invocableCommands.map((command) => {
-    const promptName = uniqueName(normalizeName(command.name), promptNames)
-    const commandSkill = convertCommandSkill(command, usedSkillNames)
+    const promptName = commandPromptNames.get(command.name)!
+    const commandSkill = convertCommandSkill(command, usedSkillNames, invocationTargets)
     commandSkills.push(commandSkill)
-    const content = renderPrompt(command, commandSkill.name)
+    const content = renderPrompt(command, commandSkill.name, invocationTargets)
     return { name: promptName, content }
   })
+  const workflowPrompts = canonicalWorkflowSkills.map((skill) => ({
+    name: workflowPromptNames.get(skill.name)!,
+    content: renderWorkflowPrompt(skill),
+  }))
 
-  const agentSkills = plugin.agents.map((agent) => convertAgent(agent, usedSkillNames))
+  const agentSkills = plugin.agents.map((agent) =>
+    convertAgent(agent, usedSkillNames, invocationTargets),
+  )
   const generatedSkills = [...commandSkills, ...agentSkills]
 
   return {
-    prompts,
+    prompts: [...prompts, ...workflowPrompts],
     skillDirs,
     generatedSkills,
+    invocationTargets,
     mcpServers: plugin.mcpServers,
   }
 }
 
-function convertAgent(agent: ClaudeAgent, usedNames: Set<string>): CodexGeneratedSkill {
-  const name = uniqueName(normalizeName(agent.name), usedNames)
+function convertAgent(
+  agent: ClaudeAgent,
+  usedNames: Set<string>,
+  invocationTargets: CodexInvocationTargets,
+): CodexGeneratedSkill {
+  const name = uniqueName(normalizeCodexName(agent.name), usedNames)
   const description = sanitizeDescription(
     agent.description ?? `Converted from Claude agent ${agent.name}`,
   )
   const frontmatter: Record<string, unknown> = { name, description }
 
-  let body = transformContentForCodex(agent.body.trim())
+  let body = transformContentForCodex(agent.body.trim(), invocationTargets)
   if (agent.capabilities && agent.capabilities.length > 0) {
     const capabilities = agent.capabilities.map((capability) => `- ${capability}`).join("\n")
     body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
@@ -59,8 +124,12 @@ function convertAgent(agent: ClaudeAgent, usedNames: Set<string>): CodexGenerate
   return { name, content }
 }
 
-function convertCommandSkill(command: ClaudeCommand, usedNames: Set<string>): CodexGeneratedSkill {
-  const name = uniqueName(normalizeName(command.name), usedNames)
+function convertCommandSkill(
+  command: ClaudeCommand,
+  usedNames: Set<string>,
+  invocationTargets: CodexInvocationTargets,
+): CodexGeneratedSkill {
+  const name = uniqueName(normalizeCodexName(command.name), usedNames)
   const frontmatter: Record<string, unknown> = {
     name,
     description: sanitizeDescription(
@@ -74,95 +143,55 @@ function convertCommandSkill(command: ClaudeCommand, usedNames: Set<string>): Co
   if (command.allowedTools && command.allowedTools.length > 0) {
     sections.push(`## Allowed tools\n${command.allowedTools.map((tool) => `- ${tool}`).join("\n")}`)
   }
-  // Transform Task agent calls to Codex skill references
-  const transformedBody = transformTaskCalls(command.body.trim())
+  const transformedBody = transformContentForCodex(command.body.trim(), invocationTargets)
   sections.push(transformedBody)
   const body = sections.filter(Boolean).join("\n\n").trim()
   const content = formatFrontmatter(frontmatter, body.length > 0 ? body : command.body)
   return { name, content }
 }
 
-/**
- * Transform Claude Code content to Codex-compatible content.
- *
- * Handles multiple syntax differences:
- * 1. Task agent calls: Task agent-name(args) → Use the $agent-name skill to: args
- * 2. Slash commands: /command-name → /prompts:command-name
- * 3. Agent references: @agent-name → $agent-name skill
- *
- * This bridges the gap since Claude Code and Codex have different syntax
- * for invoking commands, agents, and skills.
- */
-function transformContentForCodex(body: string): string {
-  let result = body
-
-  // 1. Transform Task agent calls
-  // Match: Task repo-research-analyst(feature_description)
-  // Match: - Task learnings-researcher(args)
-  const taskPattern = /^(\s*-?\s*)Task\s+([a-z][a-z0-9-]*)\(([^)]+)\)/gm
-  result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
-    const skillName = normalizeName(agentName)
-    const trimmedArgs = args.trim()
-    return `${prefix}Use the $${skillName} skill to: ${trimmedArgs}`
-  })
-
-  // 2. Transform slash command references
-  // Match: /command-name or /workflows:command but NOT /path/to/file or URLs
-  // Look for slash commands in contexts like "Run /command", "use /command", etc.
-  // Avoid matching file paths (contain multiple slashes) or URLs (contain ://)
-  const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
-  result = result.replace(slashCommandPattern, (match, commandName: string) => {
-    // Skip if it looks like a file path (contains /)
-    if (commandName.includes('/')) return match
-    // Skip common non-command patterns
-    if (['dev', 'tmp', 'etc', 'usr', 'var', 'bin', 'home'].includes(commandName)) return match
-    // Transform to Codex prompt syntax
-    const normalizedName = normalizeName(commandName)
-    return `/prompts:${normalizedName}`
-  })
-
-  // 3. Rewrite .claude/ paths to .codex/
-  result = result
-    .replace(/~\/\.claude\//g, "~/.codex/")
-    .replace(/\.claude\//g, ".codex/")
-
-  // 4. Transform @agent-name references
-  // Match: @agent-name in text (not emails)
-  const agentRefPattern = /@([a-z][a-z0-9-]*-(?:agent|reviewer|researcher|analyst|specialist|oracle|sentinel|guardian|strategist))/gi
-  result = result.replace(agentRefPattern, (_match, agentName: string) => {
-    const skillName = normalizeName(agentName)
-    return `$${skillName} skill`
-  })
-
-  return result
-}
-
-// Alias for backward compatibility
-const transformTaskCalls = transformContentForCodex
-
-function renderPrompt(command: ClaudeCommand, skillName: string): string {
+function renderPrompt(
+  command: ClaudeCommand,
+  skillName: string,
+  invocationTargets: CodexInvocationTargets,
+): string {
   const frontmatter: Record<string, unknown> = {
     description: command.description,
     "argument-hint": command.argumentHint,
   }
   const instructions = `Use the $${skillName} skill for this command and follow its instructions.`
-  // Transform Task calls in prompt body too (not just skill body)
-  const transformedBody = transformTaskCalls(command.body)
+  const transformedBody = transformContentForCodex(command.body, invocationTargets)
   const body = [instructions, "", transformedBody].join("\n").trim()
   return formatFrontmatter(frontmatter, body)
 }
 
-function normalizeName(value: string): string {
-  const trimmed = value.trim()
-  if (!trimmed) return "item"
-  const normalized = trimmed
-    .toLowerCase()
-    .replace(/[\\/]+/g, "-")
-    .replace(/[:\s]+/g, "-")
-    .replace(/[^a-z0-9_-]+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-+|-+$/g, "")
-  return normalized || "item"
+function renderWorkflowPrompt(skill: ClaudeSkill): string {
+  const frontmatter: Record<string, unknown> = {
+    description: skill.description,
+    "argument-hint": skill.argumentHint,
+  }
+  const body = [
+    `Use the ${skill.name} skill for this workflow and follow its instructions exactly.`,
+    "Treat any text after the prompt name as the workflow context to pass through.",
+  ].join("\n\n")
+  return formatFrontmatter(frontmatter, body)
+}
+
+function isCanonicalCodexWorkflowSkill(name: string): boolean {
+  return name.startsWith("ce:")
+}
+
+function isDeprecatedCodexWorkflowAlias(name: string): boolean {
+  return name.startsWith("workflows:")
+}
+
+function toCanonicalWorkflowSkillName(name: string): string | null {
+  if (!isDeprecatedCodexWorkflowAlias(name)) return null
+  return `ce:${name.slice("workflows:".length)}`
+}
+
+function shouldApplyCompoundWorkflowModel(plugin: ClaudePlugin): boolean {
+  return plugin.manifest.name === "compound-engineering"
 }
 
 function sanitizeDescription(value: string, maxLength = CODEX_DESCRIPTION_MAX_LENGTH): string {