docs(upgrade): warn that v2 → v3 needs the compat plugins first (#135)

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>

Author: oliver-kriska

.claude/skills/release/SKILL.md

@@ -24,6 +24,7 @@ consistent. **Contributor tooling — not shipped in the plugin.**
 6. **ALWAYS leave a fresh empty `## [Unreleased]`** — one `[Unreleased]` becomes one version heading; re-add an empty one on top.
 7. **NEVER force-push** — `git push --force` is hook-blocked here. If history needs rewriting, the user runs it via `!`.
 8. **EVERY release body links the docs site** — append the `https://phxagents.dev` footer. Releases are this project's one measured promotion lever (v3.0.1: 51 → 120 cloners in a day).
+9. **UPGRADE-BREAKING RELEASES LEAD WITH THE WARNING** — if users must do anything beyond `/plugin update`, the release body opens with a `> [!WARNING]` block carrying the exact commands (see #135).
 
 ## Step 0: Preconditions
 
@@ -117,8 +118,8 @@ gh release create vX.Y.Z --title "vX.Y.Z — <summary>" --notes-file <changelog-
 ```
 
 Use the new CHANGELOG section as release notes (extract it to a temp file or `--notes`),
-then **append the docs footer** before publishing — a release body is read at the
-moment someone decides whether to install:
+then **prepend any upgrade warning** (Iron Law 9) and **append the docs footer** before
+publishing — a release body is read at the moment someone decides whether to install:
 
 ```
 ---

.claude/skills/release/references/templates.md

@@ -57,6 +57,32 @@ printf '\n---\n\nDocs, install guides, and the runtime compatibility matrix: <ht
 gh release create vX.Y.Z --title "vX.Y.Z — <summary>" --notes-file /tmp/relnotes.md
 ```
 
+## Upgrade warning block (Iron Law 9)
+
+When the release requires anything beyond `/plugin update` — a new dependency,
+a renamed manifest, a manual migration — **prepend** this block so it is the
+first thing on the release page, above the changelog body:
+
+```bash
+cat > /tmp/relnotes.md <<'EOF'
+> [!WARNING]
+> **Upgrading from vN.x requires these commands in this order.** <one line on
+> what breaks otherwise, in user-visible terms.>
+>
+> ```bash
+> <exact commands>
+> ```
+
+EOF
+awk '/^## \[X\.Y\.Z\]/{f=1} f&&/^## \[/&&!/X\.Y\.Z/{exit} f' CHANGELOG.md >> /tmp/relnotes.md
+```
+
+State the blast radius in what the user loses, not in mechanism. "The plugin
+fails to load — all 36 `/phx:*` commands disappear" lands; "enters a
+missing-dependency state" does not. v3.0.0 used the second phrasing, buried in
+a `### Changed` bullet, and users still upgraded into a broken install
+(issue #135).
+
 Title format matches history: `vX.Y.Z — <short summary>` (em dash).
 
 **The docs footer is not optional.** A release body is read at the exact moment

CHANGELOG.md

@@ -50,6 +50,16 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   subagents were never affected — their own frontmatter wins — so
   `parallel-reviewer` and `planning-orchestrator` needed no change.
 
+- **The `release` contributor skill hoists upgrade warnings to the top of the
+  release body** — a new Iron Law and template: when a release needs anything
+  beyond `/plugin update`, the body opens with a `> [!WARNING]` block carrying
+  the exact commands, and states the blast radius in what the user loses rather
+  than in mechanism. v3.0.0 documented its staged upgrade correctly but placed
+  it at roughly line 145 of a long changelog dump, phrased as "a temporary
+  missing-dependency state" — and users upgraded into a broken install anyway
+  (#135). A correct instruction nobody reaches is indistinguishable from a
+  missing one.
+
 - **CLAUDE.md model-tier rules describe the actual split** — the guidance said
   "opus for primary workflow orchestrators, sonnet for secondary orchestrators
   (investigation, tracing)", which stopped matching the plugin once
@@ -60,6 +70,35 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **Upgrading from v2.x no longer lands users in a dead install** (reported by
+  @barquesurlocean, #135) — v3.0.0 renamed the plugin manifest to `phx` (which
+  is what makes `/phx:*` correct; pre-v3 versions namespaced their commands as
+  `/elixir-phoenix:*` while `/phx:init` wrote `/phx:*` into `CLAUDE.md`) and in
+  the same commit introduced the `ecto` and `lv` compatibility plugins as
+  manifest `dependencies`. Adding a dependency turns out to be a breaking
+  change for already-installed users: `claude plugin update` does **not**
+  install dependencies a new version newly declares, and a missing dependency
+  is a hard load failure, so the obvious `/plugin update` leaves the plugin at
+  `✘ failed to load` with all 36 `/phx:*` commands gone — taken down by the 3
+  compatibility commands. Verified on Claude Code 2.1.234, so this is not the
+  2.1.76–2.1.109 version band recorded during #130; it affects every v2 user on
+  every Claude Code version. Nothing self-heals either, because auto-update is
+  off by default for non-Anthropic marketplaces. The README's staged upgrade
+  block was already correct but described the failure as "a missing-dependency
+  state"; it now leads with a warning, states the blast radius in commands
+  lost, declares the 2.1.110 version floor, adds a recovery path for anyone who
+  already updated in the wrong order, and explains the `/phx:` vs
+  `/elixir-phoenix:` prefix history. Note during recovery that
+  `claude plugin install elixir-phoenix@oliver-kriska` resolves only **one**
+  missing dependency per invocation.
+
+- **`make validate` covers every plugin manifest** — the target validated
+  `plugins/elixir-phoenix` and the marketplace only, so `plugins/ecto`,
+  `plugins/lv`, and `plugins/catchup` could ship a schema violation that CI
+  never saw. This is exactly how `displayName` reached users: it was present in
+  all four Claude-facing manifests while the gate looked at one of them. All
+  five manifests are validated now.
+
 - **`displayName` removed from all Claude Code manifests** (reported by
   @ndrean, #130) — the field was introduced alongside the v3 plugin split and
   reported as an install blocker one day later. It is undocumented: it appears

Makefile

@@ -59,8 +59,11 @@ test-quick: ## Run pytest (no verbose, fast)
 
 # --- Validate ---
 
-validate: ## Run claude plugin validate on plugin + marketplace manifests
+validate: ## Run claude plugin validate on every plugin + marketplace manifest
 	@claude plugin validate plugins/elixir-phoenix
+	@claude plugin validate plugins/ecto
+	@claude plugin validate plugins/lv
+	@claude plugin validate plugins/catchup
 	@claude plugin validate .
 
 amp-skills: ## Generate Amp skills from the canonical Claude plugin

README.md

@@ -140,18 +140,23 @@ that prevent the mistakes Elixir developers actually make in production.
 /plugin install elixir-phoenix
 ```
 
-The install name stays `elixir-phoenix`, while its public workflow commands
-remain `/phx:*`. Claude Code now derives plugin command names from the plugin
-namespace and each skill's final command name. On a fresh install, it also pulls
-in two small compatibility namespaces for `/ecto:*` and `/lv:*` automatically;
-you do not need to install them separately. Existing v2 installations should
-follow the staged upgrade below. After an update, run `/reload-plugins` before
-trying the commands in an already-open session.
+Requires **Claude Code 2.1.110 or newer**. The install name stays
+`elixir-phoenix`, while its public workflow commands remain `/phx:*` — Claude
+Code namespaces commands by the plugin's manifest name, not its install name.
+A fresh install also pulls in two small compatibility namespaces for `/ecto:*`
+and `/lv:*` automatically; you do not need to install them separately. After an
+update, run `/reload-plugins` before trying the commands in an already-open
+session.
 
 #### Updating from v2.x
 
-Update the marketplace, install the two compatibility namespaces introduced in
-v3, then update the main plugin:
+> [!WARNING]
+> **Do not run `claude plugin update` on its own.** v3 introduced two
+> compatibility plugins (`ecto`, `lv`) that v2 never declared, and
+> `claude plugin update` does not install dependencies a new version newly
+> declares. The updated plugin then fails to load entirely — you lose all 36
+> `/phx:*` commands, not just `/ecto:*` and `/lv:*`. Install the two
+> compatibility plugins **first**, using the exact order below.
 
 ```bash
 claude plugin marketplace update oliver-kriska
@@ -160,11 +165,33 @@ claude plugin install lv@oliver-kriska
 claude plugin update elixir-phoenix@oliver-kriska
 ```
 
-Installing the compatibility plugins first prevents the updated main plugin
-from entering a missing-dependency state. Restart Claude Code afterward. In an
-already-open session, `/reload-plugins` reloads the updated skills, agents, and
-hooks. Confirm that `/phx:help`, `/ecto:n1-check`, and `/lv:assigns` appear
-before continuing work.
+Restart Claude Code afterward. In an already-open session, `/reload-plugins`
+reloads the updated skills, agents, and hooks. Confirm that `/phx:help`,
+`/ecto:n1-check`, and `/lv:assigns` appear before continuing work.
+
+##### Already updated in the wrong order?
+
+If `claude plugin list` reports `✘ failed to load` with
+`Dependency "ecto@oliver-kriska" is not installed`, install the two
+compatibility plugins to recover — nothing is lost, and no reinstall is needed:
+
+```bash
+claude plugin install ecto@oliver-kriska
+claude plugin install lv@oliver-kriska
+```
+
+Note that `claude plugin install elixir-phoenix@oliver-kriska` also repairs the
+state, but resolves only **one** missing dependency per run, so it needs two
+invocations here.
+
+#### Commands are `/phx:*`, not `/elixir-phoenix:*`
+
+Plugin versions before v3.0.0 shipped a manifest named `elixir-phoenix`, so
+their commands resolved as `/elixir-phoenix:work` even though `/phx:init` wrote
+`/phx:*` into `CLAUDE.md`. v3.0.0 renamed the manifest to `phx`, which is what
+makes `/phx:*` correct. If Claude Code reports `/phx:` commands as unknown,
+you are on a pre-v3 version — follow the upgrade steps above, then re-run
+`/phx:init --update`.
 
 #### Claude Code subagent compatibility