docs: permit a time-boxed parallel packaging evaluation

[kyle-sexton]

Summary

Merge authorised by the repository owner, 2026-08-16 — given out of band,
not as a review on this PR, so it is recorded here rather than inferred from
the timeline. This opened as a proposal, and the merge decision was always the
repository owner's; the owner has now taken it. Superseded, both sentences named rather than silently
dropped: this paragraph previously read "Proposal for maintainer review —
please do not merge on my account. This is drafted as a proposal; the merge
decision is the repository owner's." The first sentence is a standing
instruction that no longer holds. The second remains true and is carried forward
above in the past tense, because the decision was the owner's and that is how it
was taken.

The organization has decided to build a consolidated Agent Plugins v1 package
set in parallel, in a separate evaluation repository, and to retire
nothing. codex-plugins and cursor-plugins each stay the source of truth
for their own host throughout.

One sentence in this repository blocks that evaluation. Section 10 says:

Shared concepts stay conceptual; native packaging and runtime contracts stay
local to their host.

A single package set spanning two hosts is, on its face, shared native
packaging — even when it is hand-built, temporary, and exists only to answer
"is this format worth adopting?". This PR adds a carve-out for exactly that
case and nothing wider.

What this permits

A deliberate, hand-built, time-boxed parallel package set in a separate
evaluation repository, on four conditions: every host repository stays the
source of truth for its host with its own manifests, releases, tests and
adapters; every native marketplace catalog is retained; the set is built by
hand and human-reviewed, never emitted by a tool that reads one repository and
writes another; and the evaluation has a written end date and a named owner.

What stays prohibited

Both standing prohibitions, unchanged and unedited:

• no repository is generated from another at install time
• no automatic synchronization is introduced

The carve-out restates both explicitly and adds the third prohibition that
docs/PLUGIN-PHILOSOPHY.md already carries — no host loads another host's
packages at run time — so the evaluation set cannot be read as exempt from any
of them.

What this does NOT authorize

Retirement is not authorized by this PR. Neither is merging host-specific
content, collapsing plugins that share a skill name across hosts, or dropping a
native catalog. The amendment says so in its own text rather than leaving it to
be inferred.

The retirement gate

Retiring a host repository is a separate, later decision needing its own
amendment, drafted against evidence that does not exist yet:

1. the section 8 twelve-case matrix exercised per skill, comparing outcomes
   and side effects rather than wording, with the evidence published per
   section 9; and
2. every mapped trigger verified by invocation from a clean consumer
   repository — the rule claude-code-plugins/docs/MIGRATION-PLAYBOOK.md
   states directly at line 70.

Section 9 already forbids claiming parity for a component that was dropped,
replaced, or remains untested. The carve-out points at that rule instead of
inventing a new one, because a package that merely loads is not a package at
parity.

Fix

One file, one section, 31 insertions and 0 deletions. The change is purely
additive: docs/MIGRATION-PLAYBOOK.md section 10 keeps its existing paragraph
byte-for-byte and gains a subsection, ### Evaluation carve-out: parallel packaging for assessment.

That the diff deletes nothing is the mechanical guarantee that both
prohibitions survive verbatim — there is no rewording to audit.

Sites evaluated and deliberately NOT amended

The four-site list this work started from was treated as a sample and
re-derived independently against origin/main (1eb67d3). Every candidate
carrier was checked; three were left alone because their text does not block a
parallel evaluation:

Site	Text	Verdict
docs/MIGRATION-PLAYBOOK.md:204-205	"native packaging and runtime contracts stay local to their host"	BLOCKS — amended
docs/PLUGIN-PHILOSOPHY.md:22-25	"Ideas may be ported deliberately in either direction; runtime cross-loading and automatic cross-repository synchronization are prohibited."	Not amended. It already permits deliberate porting, and "Codex-only source of truth" stays true when this repository remains the Codex source of truth. No sentence here contradicts the carve-out.
AGENTS.md:3, AGENTS.md:64-65	"Codex-only source of truth"; "Do not create automatic cross-repository synchronization."	Not amended. A hand-built parallel set performs no automatic synchronization, and this repository keeps its source-of-truth status.
plugins/plugin-ops/skills/migrate-plugin/SKILL.md:28, :54-56	"Never add a second host manifest to the source plugin."; "Do not create automatic cross-repository synchronization. Claude Code, Cursor, and Codex packages remain independent sources of truth."	Not amended. This is a shipped skill body — behavior, not just documentation — so it was held to a strict "amend only if it genuinely blocks" test. It carries no packaging-locality sentence; the evaluation adds no manifest to any source plugin and runs no automatic sync. Leaving it untouched keeps a behavior change out of this PR.
README.md:3, references/component-map.md:9-10	"Codex-only plugin marketplace"; "do not dual-load"	Not amended. Descriptive framing and a runtime cross-loading rule respectively; neither is in scope.

Verification

Gates run locally, on this branch, before pushing

$ node --version
v24.18.0

$ npm test
ℹ tests 35
ℹ pass 35
ℹ fail 0

$ npm run validate
PASS: marketplace <worktree>; 0 error(s), 0 warning(s).

Two gates in tests/documentation-contract.test.mjs bear directly on this
change and both pass:

• line 83 asserts docs/MIGRATION-PLAYBOOK.md still matches
  /automatic synchronization/u. The amendment preserves that exact substring
  in the original sentence and repeats it in the carve-out.
• lines 89-108 assert every relative Markdown link in the doc set resolves.
  The carve-out adds no links, so nothing new to resolve.

A data-freshness defect found and worked around

The evidence documents behind this decision enumerated both repositories
against working trees that were not origin/main — the codex-plugins
checkout was parked on codex/humanize, a merged-and-deleted PR branch,
and cursor-plugins was six commits behind. Their component counts are
therefore not trustworthy as stated.

This PR body deliberately cites no component counts. The argument does not
need them: it rests on the qualitative findings, which the stale-tree defect
does not touch. Figures live in the loss analysis and should be re-derived
against origin/main before anyone quotes them.

Correction, 2026-08-16. Three statements in this section were wrong
when this PR was opened — two in the data-freshness paragraph two above, one
in the findings table below. Each is replaced in place and named here rather
than silently dropped. (A fourth, in the cursor-plugins section further
down, is corrected in its own note there.) Nothing else in this PR changes —
same diff, same branch, same title.

• Superseded: "codex-plugins sat on an unmerged branch." There is no
  unmerged work. codex/humanize's upstream is [gone] — PR feat: add humanize plugin #7 merged on
  2026-08-08 and the branch was deleted — and plugins/humanize/** is present
  in full on origin/main, eleven commits ahead of that checkout. The
  stale-tree defect was real, but its cause was a checkout left on a dead,
  already-merged branch, not codex work awaiting merge.
• Superseded: "cursor-plugins was three commits behind." It was, and
  still is, six behind origin/main, which is still d85ba6a. "Three"
  was itself read off a stale status line — the very defect this paragraph
  describes.
• Superseded: the first row of the findings table below read "No skill and
  no capability is lost". That overstates its own cited source. §6.1
  applies "no skill and no capability" to Codex users; for Cursor it says
  only "They lose no skill", because §4.7 — "The one place v1 breaks a
  working capability" — records that the v1 path-containment rule severs
  sync-local from its repo-root scripts. The loss analysis carries the
  repair as a standing condition, in the corrected executable form at its
  §10.6 (2026-08-16): the relocation is behaviour-affecting, because both
  scripts derive their default source from their own parent directory and
  resolve to the wrong target after the move. An earlier "essentially zero
  cost" framing of
  that repair was superseded by the same §10.6 and is deliberately not
  repeated here. The row is corrected below.

The re-derivation this paragraph asks for has since been completed against
origin/main. No bucket total in the loss analysis moved, because its
counting unit admits only shipped plugin product and every file the canonical
trees add is excluded CI, tests, or agent-harness policy. Twelve support
figures did move, each named at its site. Nothing the argument below rests on
is among them, and this PR body still cites no component counts.

Second pass, same day: a further review caught three defects in the first
version of these corrections and they are fixed above — the sync-local
repair was described using a cost framing its own source document had
superseded; the count sentence read "three statements" without saying it meant
this section; and the sentence below the cursor-plugins table asserted that
every quoted sentence is a prohibition, which the fuller README.md quote
makes visibly untrue. Recorded rather than quietly amended.

The findings this PR does rely on, each traceable to its source document:

Finding	Source
No skill is lost — every skill survives at the v1 floor with its scripts/ and references/ payload. Codex users lose no capability either; Cursor's one capability loss — sync-local severed from its repo-root scripts by the v1 path-containment rule — is repairable, by a relocation that is behaviour-affecting and carries a required default-source fix	retirement-loss-analysis.md §6.1, §4.7, §10.6
v1 defines no catalog or listing format, so both native marketplace catalogs must be kept regardless — consolidation buys one packaging format, not one distribution channel	retirement-loss-analysis.md §4.1, §6.1
No client documents an Agent Plugins §8 client-extension namespace (verdict UNDOCUMENTED, not "none exists")	client-extension-lookup.md §2.4
Codex reads skills/<name>/agents/openai.yaml in place inside a plugin root	client-extension-lookup.md §3.6
allow_implicit_invocation defaults to true	client-extension-lookup.md §6.2, quoting developers.openai.com/codex/llms-full.txt L6031
The organization has 0 inter-plugin dependencies	interview-checklist.md, question 10
Skill names collide across the two repositories and nearly every skill is host-locked by subject, so a naive merge is a hazard in its own right	retirement-loss-analysis.md §4.3

That last row is why the carve-out explicitly refuses to authorize collapsing
plugins that share a skill name.

Live upstream URLs consulted

The vendor documentation underpinning the two client-behavior findings above
was fetched, hashed and quoted in client-extension-lookup.md §5 (retrieved
2026-08-15): developers.openai.com/codex/llms-full.txt,
developers.openai.com/plugins/llms-full.txt,
developers.openai.com/plugins/build/plugins.md, cursor.com/docs/plugins.md,
cursor.com/docs/reference/plugins.md, and agent-plugins.org.

Superseded, 2026-08-16. This paragraph read: "This PR fetched no new
upstream pages, because it changes no host contract. The AGENTS.md
preflight exists to stop us encoding a stale product contract; this diff
encodes an organizational decision about our own repository policy and
asserts nothing about Codex behavior." That reasoning is withdrawn.
AGENTS.md:14-18 requires opening the live official pages for the affected
surface and recording the URLs and verification date in the pull request, and
it grants no exception for a change that asserts no host contract. The
carve-out does rest on a current external-format claim — that a format
defining no catalog or listing format cannot replace a native catalog — so a
day-old capture is not an adequate warrant for it. The sentence is named here
rather than deleted. The live preflight has since been completed and is
recorded immediately below; the 2026-08-15 capture above is retained only as
the prior baseline against which "did upstream move?" was answered, and is no
longer cited as evidence for any claim.

Live documentation preflight (2026-08-16)

Completed live on 2026-08-16, independently of the 2026-08-15 capture, in
response to review thread PRRT_kwDOTuHBl86Zi5Rv. Repository preflight reads
were taken from origin/main (1eb67d3), not a working tree: README.md,
docs/OFFICIAL-DOCS.md, all of docs/PLUGIN-PHILOSOPHY.md, and all of
docs/MIGRATION-PLAYBOOK.md.

Retrieval was by direct HTTP in memory, and every page below was hashed, so the
verdicts are script-computed rather than recalled. Full hashes, line-anchored
quotations, and the sweep methodology are in the planning artifacts; this
section records the URLs, the date, and the verdicts, and links upstream
instead of reproducing upstream prose.

Pages opened live, all retrieved 2026-08-16.

Agent Plugins specification — the complete page set, cross-checked between
https://agent-plugins.org/llms.txt and https://agent-plugins.org/sitemap.xml,
which agree on a thirteen-page site, so the negative claim below rests on a
bounded sweep of the publisher's own corpus rather than on a page list of my
choosing:
https://agent-plugins.org/,
https://agent-plugins.org/llms.txt,
https://agent-plugins.org/sitemap.xml,
https://agent-plugins.org/compatible-clients,
https://agent-plugins.org/specification,
https://agent-plugins.org/schemas,
https://agent-plugins.org/plugin-authors,
https://agent-plugins.org/plugin-authors/manifest,
https://agent-plugins.org/plugin-authors/mcp-servers,
https://agent-plugins.org/plugin-authors/skills,
https://agent-plugins.org/plugin-authors/client-extensions,
https://agent-plugins.org/client-implementers,
https://agent-plugins.org/client-implementers/loading-and-discovery,
https://agent-plugins.org/client-implementers/mcp-runtime,
https://agent-plugins.org/client-implementers/conformance.
That is the complete published set — thirteen pages — and every one was
fetched. One caveat stated rather than glossed: /compatible-clients is a stub
whose client table renders from a dynamic component, so its rendered contents
are not in the text corpus; an independent verifier fetched the rendered page
and found no catalog format there either.

OpenAI and Codex:
https://learn.chatgpt.com/docs/llms-full.txt,
https://developers.openai.com/plugins/llms-full.txt,
https://developers.openai.com/plugins.md,
https://developers.openai.com/plugins/build/plugins,
https://developers.openai.com/plugins/build/skills,
https://developers.openai.com/plugins/concepts/plugins,
https://learn.chatgpt.com/docs/plugins.

Cursor and Claude Code. Named in the source-host rows of
docs/OFFICIAL-DOCS.md: https://cursor.com/docs/plugins,
https://docs.claude.com/en/docs/claude-code/plugins. Not in that index and
fetched because the claims touch it:
https://cursor.com/docs/reference/plugins.

Normative-contract pointer from docs/OFFICIAL-DOCS.md:
https://agentskills.io/specification. The other pointer in that section,
modelcontextprotocol.io/specification/latest, was deliberately not fetched
— no claim here concerns MCP. The scoping rule applied throughout is
AGENTS.md's own: the affected surface, which is cross-host packaging and
distribution policy. Index rows covering MCP servers, ChatGPT UI, connect-and-test,
and submission were scoped out on the same basis. Hashes were computed over the
.md forms of these pages, which is what was retrieved.

Did the upstream spec version move? No. Agent Plugins is still published as
version 1.0.0, status Working Draft, with the same eleven-section
structure and with §8 still "Client extensions" — the section the
supporting evidence assumes. Three independent signals agree: the site's own
sitemap dates the specification page to 2026-07-28, nine days before the
baseline capture, with nothing anywhere on the site modified later than
2026-08-06; no successor version path exists; and of the eight pages hashed on
2026-08-15, seven were re-hashed today — six byte-for-byte identical, the
seventh byte-identical at a redirected URL. The eighth, a release-notes page,
was not re-hashed: the earlier capture had already recorded it as out of scope,
and its substance sits inside the Codex full-text document that was re-hashed
identical. Nothing upstream changed in the intervening day.

Per-claim verdicts, re-tested against bytes fetched 2026-08-16 — not against
the 2026-08-15 capture, whose age is the reviewer's objection:

Claim the argument rests on	Verdict	Basis in today's pages
v1 defines no catalog or listing format, so both native marketplace catalogs must be retained regardless	UPHELD	Not merely absence: the specification site states affirmatively, in its client-implementer scope list and again in its authoring overview and home page, that installation sources, registries, marketplaces, and distribution are outside the portable specification and remain each client's own. A case-insensitive sweep on the patterns catalog, registr, marketplace, listing, distribut (plus directory of and index of in the per-page pass) was run twice — once per page across all thirteen pages, and once across /llms.txt, which is not an index but a full-content concatenation of the entire site. The whole-site pass returns exactly seven lines, every one of them either a scope exclusion or non-normative design rationale. No page defines such a format anywhere. Both hosts corroborate by continuing to define their own: Codex documents its marketplace JSON catalog under .agents/plugins/, Cursor documents its own marketplace manifest and its own distribution channels — in the same page where it describes conforming to the shared format. Consolidation buys one packaging format, not one distribution channel, and today's pages say so directly.
No client documents an Agent Plugins §8 client-extension namespace	UPHELD (still UNDOCUMENTED, not "none exists")	The specification reserves no central registry and publishes only an illustrative placeholder namespace. Neither OpenAI's nor Cursor's nor Claude Code's live plugin documentation declares one. The one plausible false positive was adjudicated explicitly rather than ignored: com.openai.codex does occur in Codex's documentation, but every occurrence is a macOS preference domain, an MDM profile key, or a log directory — platform identifiers, not an Agent Plugins extension namespace. The sweep covers official documentation, not client source, which is why the verdict stays UNDOCUMENTED.
Codex reads skills/<name>/agents/openai.yaml in place inside a plugin root	UPHELD as to the documented path, with one caveat recorded below	OpenAI's plugin documentation states that exact path for a bundled skill's own interface metadata, and its packaging-validator error list enumerates twenty-six distinct skill_agent_* failure codes governing that file, eight of which name its path explicitly — a validator reading it at that path inside the plugin. (Both figures were computed by script over the fetched bytes, not counted by eye.) Cross-checked against the specification, which treats the conventional skill subdirectories as non-exhaustive, so an agents/ subdirectory inside a skill is not prohibited by v1. Caveat, surfaced by an adversarial verifier and confirmed independently: the words "in place" are ours, not upstream's, and one adjacent Codex surface — the app-server skills/list method — documents reading interface and dependency metadata from a SKILL.json when one is present. That is conditional, concerns app-server skill scanning rather than plugin packaging, and does not contradict the documented path; but the honest form of the claim is "the path is documented and validated there", not a proven statement about the read mechanism on every Codex surface. This claim supports a findings row only — the amendment's own text does not rest on it.
allow_implicit_invocation defaults to true	UPHELD, verbatim, at the same line as before	Still stated in Codex's full-text documentation at the same line number cited on 2026-08-15, in a byte-identical document, and corroborated by the plugin validator's constraint on the policy block. Citation corrected: that document's former address, developers.openai.com/codex/llms-full.txt, now returns HTTP 308 to learn.chatgpt.com/docs/llms-full.txt. The bytes and the line are unchanged; only the canonical URL moved.

No claim CHANGED and none became unverifiable, so the diff is unaffected.
The one qualification — the read-mechanism caveat on the third row — narrows a
supporting finding, not the amendment. The claim the amendment itself makes is
the catalog claim, and that one is upheld by affirmative live text.
The 31-line amendment stands exactly as written. The only defects the preflight
found were in this pull-request body — the withdrawn sentence above, and a
citation to a URL that now redirects. The first is withdrawn in place. The
second is corrected here, in this section: the original citation is left
standing where it appears in the 2026-08-15 material above, because that
material is retained as a dated historical record of what was fetched then, and
rewriting it would misrepresent it. The merge decision itself
remains the repository owner's, and is recorded at the top of this body.

codex --help disposition — named, not skipped. AGENTS.md item 4 requires
inspecting the installed CLI help "when CLI behavior is part of the change".
It is not part of this change: the diff touches one documentation file and
ships no command, script, skill body, manifest, or marketplace entry, and
invokes no CLI. The trigger condition is not met. The inspection was run anyway,
because two of the claims above are Codex runtime-contract claims and a silent
skip is indistinguishable from an oversight. Installed release: codex-cli 0.147.0. codex --help, codex plugin --help, and codex plugin marketplace --help were inspected. Bearing on the claims: weakly confirming for the catalog
claim, since marketplace management is a Codex-native CLI surface over a
Codex-defined catalog and the CLI exposes no format-defined catalog; and
silent for the two skill-metadata claims, which are package-format facts
rather than CLI flags. That silence is recorded as no bearing rather than
stretched into support.

One pointer follow-up, deliberately not fixed in this PR.
docs/OFFICIAL-DOCS.md indexes the Agent Skills specification but has no
pointer to the Agent Plugins specification, which is a different document and
is the one the carve-out's external claims rest on. AGENTS.md asks that the
index be updated when a new native surface becomes relevant. That is a change to
a second file and would break this PR's one-file, purely-additive property, so
it is recorded here as a follow-up rather than folded in.

AGENTS.md PR contract — rows that do not apply

AGENTS.md:113-122 lists what a PR must state. Named rather than silently
omitted: user goal and vertical slice, native surfaces selected, ports
and adapters introduced, defaults, configuration and fallbacks, and
migration dispositions are all not applicable — no plugin, skill, manifest,
script or marketplace entry changes here. Only docs/MIGRATION-PLAYBOOK.md
changes. Staging used explicit paths (git add docs/MIGRATION-PLAYBOOK.md).

Related

No linked issue. This PR proposes a policy amendment recorded in the
organization's planning artifacts rather than in a GitHub issue.

Why there is no companion PR against cursor-plugins

The brief for this work stated that cursor-plugins "carries none of" the
independent-host policy, and that if it needed a matching statement for the
policy to be coherent, a second PR should open there.

That premise is false, and the correction is recorded here. A search for
source of truth misses it because cursor-plugins says SSOT. It carries
independent-host policy on origin/main (d85ba6a). These six sites are the
load-bearing ones — a sample of the sites that matter here, not an exhaustive
sweep of the concept:

Site	Text
docs/PLUGIN-PHILOSOPHY.md:26-27	"This repo is the Cursor-only SSOT. Do not dual-read Claude manifests at runtime. Do not auto-export Cursor artifacts into claude-code-plugins."
docs/MIGRATION-PLAYBOOK.md:10-12	"Do not dual-read Claude manifests at runtime. Do not regenerate .cursor-plugin/ from Claude plugins as a continuous export into the Claude repo."
docs/MIGRATION-PLAYBOOK.md:88-95	"Sync policy (how we stay related without dual-host)" — "No automatic export"; "No shared marketplace JSON between hosts."
docs/MIGRATION-PLAYBOOK.md:103-107	"Out of scope here: Changing claude-code-plugins to emit Cursor artifacts again."
README.md:8-9	"Ideas may be inspired by that catalog; manifests and runtime behavior here are Cursor-only."
docs/OFFICIAL-DOCS.md:52	"Manifests and runtime here are Cursor-only."

No second PR is proposed anyway, and the corrected inventory is the reason
rather than an obstacle to it. Every one of those sentences is on the
Cursor ↔ Claude axis, and every one either prohibits runtime cross-loading
or automatic export, or merely scopes this repository to Cursor. None of those
is what the evaluation does. The discriminating
test — is there any sentence in cursor-plugins that at face value forbids a
hand-built v1 package set containing Cursor-derived skills in a third
repository? — returns nothing. The nearest candidate, "No shared marketplace
JSON between hosts", is satisfied: the evaluation keeps both native catalogs
precisely because v1 defines no catalog format.

cursor-plugins also has no packaging-locality sentence at all — the sentence
that blocks here has no counterpart there. Amending a policy to announce that
it does not block would authorize more than is needed and would edit prohibitions
that should stay exactly as written. If a maintainer wants the evaluation
discoverable from cursor-plugins, a pointer note is the right instrument and
is cheap to add later; it is not a policy amendment.

(cursor-plugins gained a root AGENTS.md in the commits this check pulled;
it is Cursor Cloud environment guidance and carries no independent-host
policy.)

Correction, 2026-08-16. The lead sentence above originally read "at six
sites", which asserts an exhaustive sweep that had not been performed; it
now says the table is a sample. A full end-to-end
re-read of every file on d85ba6a found the concept at further sites —
separation framing, inbound Claude→Cursor porting dispositions, a stated goal,
a preference, and several affirmatively permissive sentences — none of
which changes the conclusion, and each of which is adjudicated in the
planning artifacts.
The README.md row is also corrected: its sentence begins on line 8, not 9,
and starts mid-sentence with a lowercase "manifests"; it is now quoted in
full. The six rows are otherwise unchanged and were re-verified verbatim
against d85ba6a. The discriminating test was re-run independently over the
whole ref and returns the same answer: no sentence in cursor-plugins
forbids the evaluation. The supporting inventory is recorded in the
planning artifacts rather than expanded here.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f4d48e247d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".