Repository navigation
docs: cover every 0.12 behavior change in the migration guide - #51
Merged
Merged
Conversation
The legacy .codex-plugin layout only serves Codex releases older than 0.147.0, the first release that installs Agent Plugins packages and reads their mcp.json (0.146.0 read the root plugin.json only). Until now no doc said how long the option would last, and the ADR's "across v0.146 and v0.147" did not say which release a user needs. A build that sets format: "legacy" on the codex target now prints a warning that names the field, says it is removed in 0.13, and says how to move off it. The README, ADR 0001, the schema comment and the authoring skill state the same policy, and the version claim carries a dated citation to the Codex release notes.
0.12 changes generated output for four targets, and the README's upgrade
note covered only the codex layout. A user upgrading from 0.11 could find
that a cursor build now fails on ${CLAUDE_PLUGIN_DATA} or ${PLUGIN_DATA}
and writes no target at all, or that claude, cursor and copilot MCP
commands and transport labels were rewritten, with nothing explaining why.
MIGRATING_TO_0.12.md covers the codex layout change and format: "legacy",
the per-target MCP rewrites with real 0.11.1 and 0.12 output, the cursor
plugin-data failure and its two fixes, the codex to agent-plugins handoff,
and the frontmatter parser change (validate now rejects ---json blocks and
tab indentation, and leading-zero numbers read as decimal). The README
upgrade section names each change and links the guide. The guide ships in
the npm package, and the pack check requires it.
The 0.12 release adds new build and config errors, output changes, warnings and API type changes beyond the codex, MCP and frontmatter changes the guide covered. Each one was checked against the integrated 0.12 build and against 0.11.1. The guide is now ordered by what a user has to do: fix the errors that stop a build which passed on 0.11.1, review the changed output, read the new warnings, then update API callers. Each entry says what changed, who hits it and the fix. It also explains that the version 2 managed manifest is one-way for 0.11, and corrects the MCP table, since a claude build now rejects cwd instead of rewriting it. The README upgrade section now points to the guide's structure and the manifest change, and drops the claim that claude rewrites cwd.
steve-calvert-glean
added
the
documentation
# ------------------------ >8 ------------------------ # Do not modify or remove the line above. # Everything below it will be ignored. # # Conflicts: # README.md # src/targets/codex.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
0.12 changes behavior for existing 0.11 projects. #38 changed the codex layout and #37 changed MCP output. The fixes going into this release also add new build errors and warnings. "Upgrading from 0.11" covered only the codex layout. It did not mention that a cursor build now fails on
${CLAUDE_PLUGIN_DATA}, or that claude, cursor and copilot MCP output changed. No migration guide existed for 0.12.format: "legacy"had no stated lifetime.Change
MIGRATING_TO_0.12.md, shipped in the package and linked from the README. It is ordered by what a user hits first: build and config errors (each with its fix), then changed output, new warnings, and API and type changes. Each claim was checked with the published 0.11.1 CLI and a build with every 0.12 branch merged.format: "legacy"prints a deprecation warning, and is removed in 0.13. README, ADR 0001 and the schema docs say the same thing. ADR 0001 now names the Codex versions precisely: Agent Plugins packages need 0.147.0 or later.Merge notes
Merge this after #43–#50, because the guide describes their behavior.
Testing
npm run checkpasses. The conformance test asserts that the deprecation warning appears exactly once.