docs(upgrade): warn that v2 → v3 needs the compat plugins first (#135) - #136
Merged
Conversation
Claude Code namespaces commands by the plugin manifest name, so pre-v3 versions shipped /elixir-phoenix:* while /phx:init wrote /phx:* into CLAUDE.md. v3.0.0 fixed that by renaming the manifest to phx, and in the same commit declared ecto and lv as dependencies. Adding a dependency turns out to be a breaking change for installed users. claude plugin update does not install dependencies a new version newly declares, and a missing dependency is a hard load failure, so a plain /plugin update leaves the plugin at "failed to load" with all 36 /phx:* commands gone. Verified on Claude Code 2.1.234, so this is not the 2.1.76-2.1.109 band found during #130 - it hits every v2 user on every Claude Code version, and nothing self-heals because auto-update is off by default for non-Anthropic marketplaces. The README's staged upgrade block was already correct but called the failure "a missing-dependency state" and sat below the fold. It now leads with a warning, states the blast radius in commands lost, declares the 2.1.110 floor, adds a recovery path for anyone who already updated in the wrong order, and explains the prefix history. Also: the release skill gains an Iron Law and template for hoisting upgrade warnings to the top of the release body, and make validate now covers all five manifests instead of two - the same gap that let displayName ship in four manifests while CI checked one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Closes #135 once released.
The reported bug
Claude Code namespaces plugin commands by the manifest
name, not the install name. Through v2.14.3 the manifest said"name": "elixir-phoenix", so commands resolved as/elixir-phoenix:workwhile/phx:initwrote/phx:*intoCLAUDE.md. The plugin never shipped acommands/directory, so this was wrong for the whole v1/v2 line.Already fixed in v3.0.0 (
918f809) by renaming the manifest tophx. No code change needed here.The bug that was actually still live
Checking the upgrade path turned up a second defect. v3 declares
ectoandlvas manifestdependencies, andclaude plugin updatedoes not install dependencies that a new version newly declares. Because a missing dependency is a hard load failure, updating in place gives:All 36
/phx:*commands disappear — taken down by the 3 compatibility commands. Reproduced on Claude Code 2.1.234 in an isolatedCLAUDE_CONFIG_DIR, so this is not the 2.1.76–2.1.109 band found during #130; it affects every v2 user on every Claude Code version. Nothing self-heals, since auto-update is off by default for non-Anthropic marketplaces.Also found:
claude plugin install <dependent>resolves only one missing dependency per invocation, so recovery needs two runs here.Changes
README.md— the staged upgrade block was already correct but described the failure as "a missing-dependency state" and sat below the fold. It now leads with a> [!WARNING], states the blast radius in commands lost, declares the 2.1.110 Claude Code floor, adds a recovery path for anyone who already updated in the wrong order, and explains the/phx:vs/elixir-phoenix:history for people searching the old prefix..claude/skills/release/— new Iron Law 9 plus a template: upgrade-breaking releases open with the warning block carrying exact commands, phrased as what the user loses rather than as mechanism. v3.0.0 documented its staged upgrade at ~line 145 of a long changelog dump and users upgraded into a broken install anyway.Makefile—make validatenow covers all five manifests (elixir-phoenix,ecto,lv,catchup, marketplace) instead of two. That gap is howdisplayNameshipped in four manifests while CI checked one.CHANGELOG.md— two Fixed entries, one Changed entry under[Unreleased].Doc-only, so no version bump — this folds into the next release.
Verification
make cigreen: 236 tests, 5 manifests validated, 51 skills / 26 agents (avg 0.990 / 1.000), security scan clean.Upgrade paths verified end-to-end in isolated config dirs on 2.1.234: broken-order repro, staged-order success, and both recovery paths.
🤖 Generated with Claude Code