From c93103300ec3254009ff3579f1bc1c40007d62dc Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 14 Nov 2026 12:54:12 -0500 Subject: [PATCH 1/2] docs: reconcile instruction files that disagreed with each other The preflight said to read all of two docs and then only the relevant sections; the second sentence now scopes the live upstream pages. AGENTS.md and the migration playbook restated the $plugin-creator removal as a version history note. They now state the current rule and point at the cheat sheet, the dated record, whose guide claim is brought up to the wording the packaging guide uses today. AGENTS.md listed five behavioral test cases where the release gates list seven; it now cites the release gates and the playbook matrix. migrate-plugin told an installed copy to act "in this marketplace", which it cannot detect; the step now applies when the active repository has the named files. plugin-ops 0.2.5. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015XWwmeQBXsRaYpmqMJbwsf --- AGENTS.md | 22 ++++++++++--------- docs/codex-capability-cheat-sheet.md | 4 ++-- docs/migration-playbook.md | 10 ++++----- plugins/plugin-ops/.codex-plugin/plugin.json | 2 +- .../plugin-ops/skills/migrate-plugin/SKILL.md | 8 +++---- tests/plugin-ops-plugin.test.mjs | 2 +- 6 files changed, 25 insertions(+), 23 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6b6e1df..9f05208 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,8 @@ installs, or publishes a plugin component: 5. Record the consulted URLs and verification date in the pull request. Link to upstream material; do not copy its prose or examples into this repository. -Read only the sections relevant to the action, but do not skip the preflight. +Within the live upstream pages, read only the sections relevant to the action, +but do not skip the preflight. When live official documentation and verified product behavior disagree, stop contract-changing work, record the discrepancy, and prefer the narrower behavior until it is resolved. Update `docs/official-docs.md` when a pointer @@ -82,10 +83,9 @@ paths, tool installation, subscription, or credentials as a consumer default. - Scaffold or update plugins by hand from the [plugin packaging guide](https://developers.openai.com/plugins/build/plugins), - and skills with `$skill-creator`. Codex CLI 0.159.0 removed `$plugin-creator`; - the guide still offers `@plugin-creator` in ChatGPT Work mode and - `$plugin-creator` on other Codex surfaces, so check the page before relying - on either. + and skills with `$skill-creator`. The Codex CLI ships no `$plugin-creator`; + the [cheat sheet](docs/codex-capability-cheat-sheet.md#built-in-system-skills) + records the version and what the guide offers on other surfaces. - Keep every skill focused on one recognizable goal. Put essential procedure in `SKILL.md` and detailed variants in directly linked `references/` files. - Keep `agents/openai.yaml` aligned with its skill. It is the harness-facing @@ -114,11 +114,13 @@ npm test npm run validate ``` -`npm run validate` is the plugin and catalog validator; Codex CLI 0.159.0 -removed the built-in one. Also run the `$skill-creator` quick validator for every -changed skill, and behavioral tests for direct, indirect, negative, missing -dependency, and repository-context cases. Migration validation must use a new -Codex task with the source marketplace and sibling plugins disabled. +`npm run validate` is the plugin and catalog validator; the Codex CLI ships +none. Also run the `$skill-creator` quick validator for every changed skill, +and behavioral tests for every case the +[release gates](docs/plugin-philosophy.md#release-gates) name. Migration +validation must use a new Codex task with the source marketplace and sibling +plugins disabled, and exercises the +[playbook matrix](docs/migration-playbook.md#8-validate-the-target-in-isolation). The pull request must state: diff --git a/docs/codex-capability-cheat-sheet.md b/docs/codex-capability-cheat-sheet.md index 49a4ad1..56a7cb8 100644 --- a/docs/codex-capability-cheat-sheet.md +++ b/docs/codex-capability-cheat-sheet.md @@ -68,8 +68,8 @@ Codex CLI 0.159.0 removed the bundled `plugin-creator` skill ([#48604](https://github.com/openai/codex/pull/48604)), so `$plugin-creator` no longer resolves from the CLI binary. The [plugin packaging guide](https://developers.openai.com/plugins/build/plugins) -still names `@plugin-creator` as a built-in in ChatGPT; check that page before -relying on it. +still offers `@plugin-creator` in ChatGPT Work mode and `$plugin-creator` on +other Codex surfaces; check that page before relying on either. ## Plugin-author changes since 0.143.0 diff --git a/docs/migration-playbook.md b/docs/migration-playbook.md index 3765096..fe50295 100644 --- a/docs/migration-playbook.md +++ b/docs/migration-playbook.md @@ -121,9 +121,9 @@ to preserve the source file shape. Write the target package's manifest and marketplace entry by hand from the [plugin packaging guide](https://developers.openai.com/plugins/build/plugins); -Codex CLI 0.159.0 removed the bundled `$plugin-creator` skill. The guide still -offers `@plugin-creator` in ChatGPT Work mode and `$plugin-creator` on other -Codex surfaces; check the page before relying on either. Use `$skill-creator` for each +the Codex CLI ships no `$plugin-creator` skill (see the +[cheat sheet](codex-capability-cheat-sheet.md#built-in-system-skills)). +Use `$skill-creator` for each skill; it is a built-in system skill, so it takes the bare `$name` form. Use the installed `$plugin-ops:migrate-plugin` component map as a checklist, then override it when current official documentation differs. Skills that ship inside @@ -160,8 +160,8 @@ write to a broader scope, or change the user goal. ## 8. Validate the target in isolation -Run the repository validator (`validate-marketplace.mjs`, which replaces the -built-in plugin validator Codex CLI 0.159.0 removed) and the `$skill-creator` +Run the repository validator (`validate-marketplace.mjs`; the Codex CLI ships +no plugin validator) and the `$skill-creator` quick validator. Then install the target from a local marketplace and start a new Codex task with the source marketplace and sibling plugins disabled. diff --git a/plugins/plugin-ops/.codex-plugin/plugin.json b/plugins/plugin-ops/.codex-plugin/plugin.json index e34cb42..ffb92b7 100644 --- a/plugins/plugin-ops/.codex-plugin/plugin.json +++ b/plugins/plugin-ops/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-ops", - "version": "0.2.4", + "version": "0.2.5", "description": "Install, update, migrate, and validate Codex plugins and marketplace catalogs.", "author": { "name": "Melodic Software", diff --git a/plugins/plugin-ops/skills/migrate-plugin/SKILL.md b/plugins/plugin-ops/skills/migrate-plugin/SKILL.md index 925a6f5..8a8b8ed 100644 --- a/plugins/plugin-ops/skills/migrate-plugin/SKILL.md +++ b/plugins/plugin-ops/skills/migrate-plugin/SKILL.md @@ -12,10 +12,10 @@ assumptions. 1. Record the source repository, exact commit, version, and target base commit. Read every source component and its tests before editing. -2. Fetch current official documentation for both the source host and Codex. In - this marketplace, complete the root `AGENTS.md` preflight and read - `docs/plugin-philosophy.md` plus `docs/migration-playbook.md`. Record live - URLs and the date checked; copy no upstream prose. +2. Fetch current official documentation for both the source host and Codex. + When the active repository has them, complete the root `AGENTS.md` preflight + and read `docs/plugin-philosophy.md` plus `docs/migration-playbook.md`. + Record live URLs and the date checked; copy no upstream prose. 3. Define the user-goal vertical slice: inputs, repository context, output, side effects, boundaries, platform variants, and acceptance evidence. 4. Read [references/component-map.md](references/component-map.md), then create diff --git a/tests/plugin-ops-plugin.test.mjs b/tests/plugin-ops-plugin.test.mjs index 599c1ea..3a8fb76 100644 --- a/tests/plugin-ops-plugin.test.mjs +++ b/tests/plugin-ops-plugin.test.mjs @@ -12,7 +12,7 @@ const paths = skillPaths("plugin-ops"); test("the marketplace exposes the Plugin Ops plugin", async () => { await assertMarketplacePlugin({ name: "plugin-ops", - version: "0.2.4", + version: "0.2.5", category: "Developer Tools", }); }); From 3258dbc603d4774b01cc8fed9ad9ba4c5c4405c6 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 14 Nov 2026 12:56:12 -0500 Subject: [PATCH 2/2] docs: date the packaging-guide claim in the cheat sheet Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015XWwmeQBXsRaYpmqMJbwsf --- docs/codex-capability-cheat-sheet.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/codex-capability-cheat-sheet.md b/docs/codex-capability-cheat-sheet.md index 56a7cb8..f195924 100644 --- a/docs/codex-capability-cheat-sheet.md +++ b/docs/codex-capability-cheat-sheet.md @@ -69,7 +69,8 @@ Codex CLI 0.159.0 removed the bundled `plugin-creator` skill no longer resolves from the CLI binary. The [plugin packaging guide](https://developers.openai.com/plugins/build/plugins) still offers `@plugin-creator` in ChatGPT Work mode and `$plugin-creator` on -other Codex surfaces; check that page before relying on either. +other Codex surfaces (read 2026-11-14); check that page before relying on +either. ## Plugin-author changes since 0.143.0