[FEATURE] Compile "prompts" primitive to Codex's native ~/.codex/prompts/ format (mirroring how "agents" already targets .codex/agents/*.toml)

[Ives7]

Is your feature request related to a problem? Please describe.

The prompts primitive (.apm/prompts/*.prompt.md) compiles to Claude (.claude/commands/<name>.md), Copilot (.github/prompts/<name>.prompt.md), Cursor (.cursor/commands/<name>.md), Gemini (.gemini/commands/<name>.toml), and Windsurf (.windsurf/workflows/<name>.md) — but explicitly emits nothing for Codex. The docs confirm this is intentional today: "Codex receives nothing. Do not assume a prompt is universal," with the suggested workaround being to ship the functionality as a skill instead.

This is inconsistent with the agents primitive (.apm/agents/*.agent.md), which does compile to Codex correctly today: .codex/agents/<name>.toml, with the markdown body mapped to the developer_instructions field (per the "What compiles where" table in the instructions-and-agents docs). So apm already has precedent for faithfully materializing a primitive into a Codex-native format — it just hasn't been done for prompts yet.

Note this is a different ask from #1781, which was declined. #1781 proposed generating a skill from each prompt entry on Codex — i.e., translating one primitive type into another, which the maintainer correctly identified as a semantic-translation shim outside apm's install-and-integrity scope ("materializing the primitive faithfully is ours" vs. translating between primitive types). This issue instead asks apm to materialize the same prompt primitive onto Codex's own native prompts mechanism, not convert it into a different primitive — the same category of work already being done for agents -> .codex/agents/*.toml.

Concretely, Codex CLI already has its own native custom-prompts mechanism: files under ~/.codex/prompts/*.md, where the filename becomes the invocable command name (e.g. /prompt-name). So Codex can support project-authored custom commands in principle — it's specifically apm's prompts compiler that doesn't target it yet.

Without this, any apm package that ships a prompt is unusable as a slash-command on Codex, and a developer who wants that command available in Codex has to hand-author and hand-maintain a separate file under ~/.codex/prompts/ outside of apm's install/lock/verify lifecycle, per machine, instead of getting it compiled and kept in sync automatically the way Claude/Copilot/Cursor/Gemini/Windsurf users already do.

Describe the solution you'd like

Extend the prompts compiler to also emit to Codex's native prompts format when Codex is a target, mirroring the existing agents -> .codex/agents/<name>.toml mapping:

• Output: <name>.md (body content, since Codex's native prompt files are plain markdown, not TOML)
• Location: Codex's native prompts directory (~/.codex/prompts/)

One open question worth surfacing: Codex's native prompts directory is user-global (~/.codex/prompts/), unlike apm's other prompt targets which are all project-local (.claude/commands/, .cursor/commands/, etc.). If apm's install model assumes all materialized output lives inside the project tree, targeting a user-global path may need either (a) a documented exception for this target, or (b) treating it as out of scope for apm install and only relevant to apm install -g. Flagging this rather than assuming it's a simple addition.

Describe alternatives you've considered

• Keep the current behavior (Codex gets nothing for prompts, author ships a skill instead). Works, but means prompt-based packages are simply unreachable as slash-commands on Codex, and there's no compiled/shared path — every developer maintains their own ~/.codex/prompts/ file by hand.
• Generate a skill from prompt entries on Codex ([FEATURE] Generate a skill for prompt entries when targeting Codex #1781) — already proposed and declined as an out-of-scope semantic translation between primitive types.

Additional context

This was noticed while comparing how the agents and prompts primitives each target Codex — agents has full, correct Codex support today (verified empirically via apm install), while prompts has none, despite Codex having its own equivalent native mechanism that would make this a faithful materialization rather than a translation shim.

[Ives7]

For reference, this same problem has already been solved elsewhere: OpenSpec ships its own workflow slash-commands (/opsx:propose, /opsx:apply, etc.) to multiple AI coding tools, including both Claude Code and Codex.

For Claude Code, its installer deploys these as project-scoped command files (.claude/commands/opsx/*.md). For Codex — since Codex's custom-prompts mechanism has no project-scoped option — its installer deliberately targets the user-global path instead: $CODEX_HOME/prompts/opsx-*.md (defaulting to ~/.codex/prompts/), and documents this as expected, working behavior for Codex users (see OpenSpec's supported-tools.md: "Codex commands are installed in the global Codex home").

This confirms targeting Codex's global prompts directory is a workable, already-shipped pattern for materializing project-authored slash commands there — not just a hypothetical fallback. It's a real precedent for the open design question raised above about whether apm's prompts primitive could/should do the same for its Codex target.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/multi-target
area/package-authoring
area/docs-site
type/feature
status/needs-design

Milestone

null -- status/needs-design issues do not receive a milestone until the design is settled.

Suggested next action

Decide whether the Codex prompts output path (~/.codex/prompts/) should be handled by apm install -g only, by project-install as well, or documented as out of scope pending an install-model extension for user-global outputs.

Suggested issue comment

Thanks for this carefully researched request and for clearly distinguishing it from #1781 -- you are right that materializing the `prompts` primitive faithfully onto Codex's native format is a different category of work from the semantic translation #1781 proposed.

The gap is real and the implementation would be small, but there is one design question that needs to be resolved before code can land safely: Codex's native prompts directory (`~/.codex/prompts/`) is user-global, unlike every other APM prompt target which is project-local. APM's current install model assumes all compiled outputs live inside the project tree (git-trackable, deterministic per checkout). Writing to a user-global path from a project install would be a new policy.

The options on the table:
- Support this only via `apm install -g` (keeps the install model clean, but limits usefulness to global packages).
- Support it for project installs too, accepting user-global writes as an explicit exception for this target (new policy, needs documentation and audit of the security model for user-global prompt installation).
- Defer until the install model is extended with a first-class concept of user-global output paths.

If you have a strong preference or additional context on how Codex users expect this to work, please share it in a comment. A brief design note (or comment here) settling the install-scope question would unblock implementation quickly.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request is well-grounded and the gap is real. The agents primitive already materializes to .codex/agents/*.toml, so this is a consistent extension request. The UX problem is concrete: prompt-based packages are simply unreachable as slash-commands on Codex, with no compiled path. However, the user-global vs project-local boundary is a genuine design question that must be answered before implementation.

Supply Chain Security Expert -- Risk-Surface Reviewer

Writing to ~/.codex/prompts/ from a project-scoped install is a supply-chain concern: package-authored content would persist globally across projects and survives package uninstall from the project. The security model for user-global prompt installation needs explicit documentation. Theme: theme/portability (multi-target coverage). No immediate vulnerability, but the new policy warrants deliberate design.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author Ives7 has author_association: NONE. The report is thorough and shows careful research (citing #1781, distinguishing the trust boundary, verifying agents already targets Codex). Tone should be warm and acknowledge the quality of the analysis. The reply must be specific about what design question needs answering so the author knows exactly what is blocking acceptance.

Python Architect -- Architecture Reviewer

The implementation is small (add a Codex branch to the prompts compiler, similar to the existing agents -> .codex/agents/*.toml path). The design blocker is the install-scope question. If the decision is apm install -g only, the implementation is clean and bounded. If project installs are included, the install model needs an explicit concept of user-global output paths, which is a broader change. Recommend status/needs-design with the named decision: install-scope policy for user-global Codex paths.

Doc Writer -- Documentation Reviewer

If accepted, the "What compiles where" table in the instructions-and-agents docs needs a new Codex row for prompts, and the package-authoring docs need a note on install scope. area/docs-site rides alongside because an implementing PR will need new documentation. This is within the 6-label cap for this issue.

APM CEO -- Triage Arbiter

Direction is sound. The author has correctly identified a real gap and a legitimate implementation path. The user-global output path question is the only blocker. Routing to needs-design with the install-scope decision named. Once a maintainer settles that question (in a comment or design note), implementation is straightforward.

{
  "decision": "needs-design",
  "decision_detail": "Must decide: should the Codex prompts output (user-global ~/.codex/prompts/) be scoped to apm install -g only, or also to project installs? This is a new install-model policy for user-global output paths.",
  "theme": "theme/portability",
  "areas": ["area/multi-target", "area/package-authoring", "area/docs-site"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Decide install-scope policy for user-global Codex output paths (apm install -g only vs. project installs) before implementing the prompts compiler extension.",
  "comment_markdown": "Thanks for this carefully researched request and for clearly distinguishing it from #1781 -- you are right that materializing the `prompts` primitive faithfully onto Codex's native format is a different category of work from the semantic translation #1781 proposed.\n\nThe gap is real and the implementation would be small, but there is one design question that needs to be resolved before code can land safely: Codex's native prompts directory (`~/.codex/prompts/`) is user-global, unlike every other APM prompt target which is project-local. APM's current install model assumes all compiled outputs live inside the project tree (git-trackable, deterministic per checkout). Writing to a user-global path from a project install would be a new policy.\n\nThe options on the table:\n- Support this only via `apm install -g` (keeps the install model clean, but limits usefulness to global packages).\n- Support it for project installs too, accepting user-global writes as an explicit exception for this target (new policy, needs documentation and audit of the security model for user-global prompt installation).\n- Defer until the install model is extended with a first-class concept of user-global output paths.\n\nIf you have a strong preference or additional context on how Codex users expect this to work, please share it in a comment. A brief design note (or comment here) settling the install-scope question would unblock implementation quickly."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · 184.7 AIC · ⌖ 18.6 AIC · ⊞ 9.2K · ◷