From 44927813c28654b12484d0dd5321d3ce39040f68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabor=20K=C3=B6rber?= Date: Sat, 30 May 2026 15:19:18 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Document=20Codex=20marketplace?= =?UTF-8?q?=20support?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...-30-15-codex-plugin-marketplace-support.md | 205 ++++++++++++++++++ 1 file changed, 205 insertions(+) create mode 100644 docs/workpad/reports/2026-05-30-15-codex-plugin-marketplace-support.md diff --git a/docs/workpad/reports/2026-05-30-15-codex-plugin-marketplace-support.md b/docs/workpad/reports/2026-05-30-15-codex-plugin-marketplace-support.md new file mode 100644 index 0000000..f2accbe --- /dev/null +++ b/docs/workpad/reports/2026-05-30-15-codex-plugin-marketplace-support.md @@ -0,0 +1,205 @@ +# Codex Plugin Marketplace Support for Reliquary + +Date: 2026-05-30 + +## Summary + +Reliquary is already a Claude plugin marketplace, and the current Codex installation can consume it today through the existing `.claude-plugin/marketplace.json` layout. In the local Codex CLI 0.135.0-alpha.1 environment, the `reliquary` marketplace is configured from `git@git.g4b.org:dirigence/reliquary.git`, and `g4b_ai`, `gitea`, and `project-uv` are installed and enabled. + +For long-term portability, Reliquary should publish a parallel Codex-native marketplace layout instead of relying on Codex's compatibility with Claude marketplace metadata. The practical target is: + +- keep `.claude-plugin/marketplace.json` for Claude Code +- add `.agents/plugins/marketplace.json` for Codex +- keep each plugin's existing `.claude-plugin/plugin.json` +- add each plugin's `.codex-plugin/plugin.json` +- keep shared skill content under `plugins//skills//SKILL.md` + +The skill directories can remain shared between Claude and Codex. The main work is metadata and install documentation. + +## Current Repository State + +The repo root currently has: + +- `.claude/settings.json`, which configures Claude to know the `reliquary` marketplace and enable selected plugins. +- `.claude-plugin/marketplace.json`, which declares the marketplace and four plugins: `g4b_ai`, `dioxus`, `project-uv`, and `gitea`. +- `plugins//.claude-plugin/plugin.json` for `g4b_ai`, `gitea`, and `project-uv`. +- shared skills under `plugins//skills/.../SKILL.md`. + +The repo-level `CLAUDE.md` already tells Claude users that this repo is a marketplace and that workpad material lives under `docs/workpad/`. + +## Observed Codex Behavior + +Codex is already configured locally with: + +```toml +[marketplaces.reliquary] +source_type = "git" +source = "git@git.g4b.org:dirigence/reliquary.git" + +[plugins."g4b_ai@reliquary"] +enabled = true + +[plugins."gitea@reliquary"] +enabled = true + +[plugins."project-uv@reliquary"] +enabled = true +``` + +Running the local Codex binary's plugin listing showed: + +```text +Marketplace `reliquary` +g4b_ai@reliquary installed, enabled 0.1.0 +dioxus@reliquary not installed +project-uv@reliquary installed, enabled 0.1.0 +gitea@reliquary installed, enabled 0.1.0 +``` + +That proves Codex can currently discover this repo's Claude marketplace file. However, Codex's own plugin creation guidance uses `.codex-plugin/plugin.json` for plugin manifests and `.agents/plugins/marketplace.json` for marketplace files, so Reliquary should add those files explicitly rather than treating Claude metadata as the only source of truth. + +## Codex-Native Marketplace Shape + +OpenAI's Codex plugin creator skill describes Codex plugin scaffolds as containing a required `.codex-plugin/plugin.json`, optional `skills/`, and marketplace entries in `.agents/plugins/marketplace.json`. Its reference schema shows `skills: "./skills/"` in the plugin manifest and Codex marketplace entries with `source`, `policy`, and `category` fields. + +Recommended repo-level Codex marketplace file: + +```text +.agents/plugins/marketplace.json +``` + +Recommended shape: + +```json +{ + "name": "reliquary", + "interface": { + "displayName": "Reliquary" + }, + "plugins": [ + { + "name": "g4b_ai", + "source": { + "source": "local", + "path": "./plugins/g4b_ai" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} +``` + +Each current plugin should get a Codex manifest: + +```text +plugins/g4b_ai/.codex-plugin/plugin.json +plugins/gitea/.codex-plugin/plugin.json +plugins/project-uv/.codex-plugin/plugin.json +plugins/dioxus/.codex-plugin/plugin.json +``` + +Recommended minimal manifest shape: + +```json +{ + "name": "g4b_ai", + "version": "0.1.0", + "description": "Gabor's personal Codex skills: workpad, research-tree, implementation-orchestration, markdown-embedded-svg.", + "author": { + "name": "Gabor Körber", + "email": "gab@g4b.org" + }, + "skills": "./skills/", + "interface": { + "displayName": "g4b_ai", + "shortDescription": "Personal project workflow skills for Codex.", + "longDescription": "Workpad placement, research orchestration, implementation orchestration, and Markdown SVG guidance.", + "developerName": "Gabor Körber", + "category": "Productivity", + "capabilities": ["Skills"] + } +} +``` + +The existing `.claude-plugin/plugin.json` files can stay as-is. The `.codex-plugin` files can point at the same `skills/` folders. + +## How Users Would Install from Codex + +Once the Codex marketplace file exists, a Codex user can add this marketplace from the repo: + +```powershell +codex plugin marketplace add git@git.g4b.org:dirigence/reliquary.git +``` + +Then install the desired plugin: + +```powershell +codex plugin add g4b_ai@reliquary +``` + +For local development from a checked-out repo, Codex also supports local marketplace sources: + +```powershell +codex plugin marketplace add G:\dev\projects\reliquary +codex plugin add g4b_ai@reliquary +``` + +The local Codex help confirms the relevant command forms: + +- `codex plugin marketplace add ` +- `codex plugin marketplace list` +- `codex plugin marketplace upgrade` +- `codex plugin add PLUGIN@MARKETPLACE` +- `codex plugin list` + +## Using Workpad from Codex Projects + +The `workpad` skill should remain inside the `g4b_ai` plugin: + +```text +plugins/g4b_ai/skills/workpad/SKILL.md +``` + +For any Codex project that wants to use it, install and enable `g4b_ai@reliquary`, then add project-level `AGENTS.md` instructions similar to: + +```md +# Project Instructions + +Working documents live in `docs/workpad/`. + +Use the `g4b_ai:workpad` skill for plans, research notes, specs, journals, reports, goals, and brainstorms. +``` + +This gives Codex both pieces it needs: + +- the installed plugin supplies the actual `workpad` skill +- `AGENTS.md` supplies the project-specific workpad location and policy + +For projects that do not already have `docs/workpad/`, the workpad skill can decide placement using its own rules. In this repository, `docs/workpad/` already exists and should remain the canonical location. + +## Recommended Changes to Reliquary + +1. Add `.agents/plugins/marketplace.json`. +2. Add `.codex-plugin/plugin.json` to each plugin directory. +3. Update the root `README.md` with separate Claude and Codex installation sections. +4. Add a short `AGENTS.md` at the repo root for Codex-specific repo instructions, mirroring the important parts of `CLAUDE.md`. +5. Add a validation note or script so marketplace updates keep Claude and Codex plugin lists in sync. + +The Codex marketplace should include all plugins currently listed in `.claude-plugin/marketplace.json`: `g4b_ai`, `dioxus`, `project-uv`, and `gitea`. + +## Compatibility Notes + +Codex can currently consume the Claude marketplace layout in this environment, but that is an implementation detail from the user's perspective. The repo should publish Codex-native metadata so future Codex versions, Codex app UI flows, and third-party tooling can rely on the expected Codex structure. + +Codex plugin cache behavior is version-sensitive. During local plugin development, Codex's own update guidance recommends changing the plugin version with a Codex cachebuster suffix, reinstalling the plugin, and starting a new thread so the new skills and tools are loaded. + +## Sources + +- OpenAI Codex plugin creator skill: https://github.com/openai/codex/blob/main/codex-rs/skills/src/assets/samples/plugin-creator/SKILL.md +- OpenAI Codex plugin and marketplace JSON reference: https://raw.githubusercontent.com/openai/codex/main/codex-rs/skills/src/assets/samples/plugin-creator/references/plugin-json-spec.md +- OpenAI Codex local plugin update reference: https://raw.githubusercontent.com/openai/codex/main/codex-rs/skills/src/assets/samples/plugin-creator/references/installing-and-updating.md +- Local verification in this repo with Codex CLI 0.135.0-alpha.1.