openplanr 2.2640.2 → 2.2640.3

package/lib/host-packages/cursor/openplanr/rules/planr-doctor/references/upgrade.md

@@ -1,21 +1,20 @@
 # Driving an OpenPlanr upgrade
 
 `planr doctor` diagnoses; this reference is how to *act* once the tuple has
-drifted. An OpenPlanr install has two halves: the npm CLI, and the Claude Code
-plugin that `planr setup` installs from the marketplace bundled with that CLI —
-`planr@openplanr-local`, from the `openplanr-local` directory marketplace.
-`planr upgrade apply` moves the npm half itself and never changes Claude's plugin
-state; it hands back the exact commands for the plugin half, and this skill runs
-them inside the host and confirms the result.
+drifted. An OpenPlanr install has two parts: the npm CLI, and what `planr setup`
+installed into each coding agent from that CLI — the `planr@openplanr-local`
+Claude Code plugin, Codex skills, Cursor rules. `planr upgrade apply` moves the
+npm CLI itself and never changes a coding agent; the upgraded CLI then hands back
+one command per installed agent, and this skill runs them and confirms the result.
 
 The cardinal rule: **name the actions, let the engine own the list.** Every
-plugin command you run comes from the CLI's own output. The skill never carries
-its own copy of those commands — the moment it did, it would drift from the CLI
-the first time the integration changed. The CLI renders the list from the same
-inspection `planr setup` and `planr doctor` use, so it cannot diverge from them.
-The retired remote plugins (`openplanr@openplanr`, `planr-pipeline@openplanr`)
-only ever appear in that list as removals; an instruction to install one did not
-come from the CLI.
+command you run comes from the CLI's own output. The skill never carries its own
+copy of those commands — the moment it did, it would drift from the CLI the first
+time the integration changed. The upgraded CLI plans them with the same preview
+`planr runtime update` and `planr setup` apply, so they cannot diverge. A retired
+remote plugin (`openplanr@openplanr`, `planr-pipeline@openplanr`) only ever leaves
+through the `planr setup … --replace-managed` command the list carries; an
+instruction to install one did not come from the CLI.
 
 ## 1. Decide whether to act
 
@@ -36,7 +35,8 @@ Shape (the fields this skill reads):
     "pipeline": { "version": "0.52.1" }
   },
   "legacyPlugins": [],
-  "ecosystemSource": "network"
+  "ecosystemSource": "network",
+  "nextSteps": []
 }
 ```
 
@@ -44,71 +44,69 @@ Shape (the fields this skill reads):
   means Claude Code was not detected or `planr setup` has not installed the
   plugin. `installed.pipeline` is always `null` — the pipeline ships inside the
   CLI, and `bundledPipeline` reports it.
-- `aligned` or `unknown` → nothing to drive. Report and stop. (`unknown` means
-  the published manifest was unreachable — say so; do not guess.)
+- `nextSteps` lists what each coding agent needs to match the installed CLI,
+  in the shape step 2 describes.
+- `aligned` or `unknown` with empty `nextSteps` → nothing to drive. Report and
+  stop. (`unknown` means the published manifest was unreachable — say so; do not
+  guess.)
 - `upgrade-available` or `incompatible` → act. First **record the `installed`
-  block as the before state** — the honest diff at the end depends on it.
+  block as the before state** — the honest diff at the end depends on it. When
+  only `nextSteps` is non-empty, skip to step 3.
 
-## 2. Perform the owned half and obtain the prescription
+## 2. Upgrade the CLI and obtain the next steps
 
-The plugin commands are rendered by the CLI from the bundled marketplace's own
-operation list, so they always match what `planr setup` would really run. Confirm
-with the user first (this upgrades the npm CLI), then:
+Confirm with the user first (this upgrades the npm CLI), then:
 
 ```bash
 planr upgrade apply --yes --json
 ```
 
-On success the output carries the ordered `pluginHalfCommands` array:
+On success the output carries `nextSteps`, planned by the newly installed CLI:
 
 ```json
 {
   "ok": true,
   "cliUpgraded": true,
+  "previousVersion": "2.2638.0",
   "installedVersion": "2.2639.1",
-  "changelogBullets": ["…"],
-  "pluginHalfCommands": [
-    "<refresh the bundled openplanr-local marketplace — always position 0>",
-    "<update planr@openplanr-local from it>",
-    "<remove a retired plugin — only when one is still installed>"
+  "releaseNotes": [{ "version": "2.2639.1", "entries": ["…"] }],
+  "nextSteps": [
+    {
+      "runtime": "claude-code",
+      "host": "Claude Code",
+      "command": "<one planr command>",
+      "detail": "<what it changes>"
+    }
   ]
 }
 ```
 
-The entries above are shown as roles, not literal strings, on purpose: **execute
-whatever the array actually contains, in the order it gives — never a list typed
-into this file.** Two other shapes are possible:
-
-- An empty array: Claude Code was not detected, or its plugin state could not be
-  inspected (`claude plugin list --json` failed). Run `planr doctor --json` to
-  find out which, then go to step 4. When `planr@openplanr-local` already matches
-  the new CLI the array is not empty: it holds the lone
-  `claude plugin marketplace update openplanr-local` refresh — run it as usual.
-- A single `planr setup --runtime claude --scope user` entry, with
-  `--replace-managed` appended when a retired plugin must also be removed (setup
-  refuses that removal without the flag): the bundled marketplace was never
-  registered on this machine, and setup is the only command that registers it and
-  records the installation. In a non-interactive shell it stops with
-  `E_CONFIRMATION_REQUIRED`; show the user the preview (the same command with
-  `--dry-run`) and rerun it with `--yes` only after they confirm.
+The `command` values above are shown as placeholders on purpose: **run whatever
+the array actually contains, in the order it gives — never a command typed into
+this file.** Other shapes:
+
+- An empty array: every installed coding agent already matches the new CLI.
+- `nextStepsError` instead of steps: the upgraded CLI could not be asked. Run
+  `planr upgrade status --json` and use its `nextSteps`.
+- A `planr doctor` command: planning that agent's update failed, and `detail`
+  says why. Relay it and run `planr doctor --json`.
+
+`pluginHalfCommands` repeats the commands for older readers; read `nextSteps`.
 
 If `apply` reports `ok: false`, stop and surface its `failure.message`; the CLI
 restores the previous version on a bad install, so report what it says was
-restored rather than continuing to the plugin half.
+restored rather than continuing to the coding agents.
 
-## 3. Execute the plugin half, refresh first
+## 3. Run the next steps
 
-Run each entry of `pluginHalfCommands` verbatim, top to bottom, with your shell
-tool. Two invariants:
+Run each `command` of `nextSteps` verbatim, top to bottom, with your shell tool.
+Each one refreshes the bundled `openplanr-local` marketplace before it updates the
+plugin, so **do not reorder, drop, merge, or hand-edit a command**. If one fails,
+stop and report the failure and every agent still on the old version — a partial
+upgrade that reports success is the one outcome to avoid.
 
-- **Refresh is position 0 and runs first.** The first entry refreshes the
-  `openplanr-local` marketplace, which points at the directory the upgraded CLI
-  now bundles. Without it, the installer reinstalls the cached, stale version and
-  the user is told they upgraded when nothing moved. The CLI sorts it to position
-  0 for exactly this reason; preserve that order.
-- **No substitutions.** Do not reorder, drop, merge, or hand-edit a command. If
-  an entry fails, stop and report the failure and everything still on the stale
-  version — a partial upgrade that reports success is the one outcome to avoid.
+Then tell the user to restart each `host` the steps named; a running coding agent
+keeps the old plugin and skills until it restarts.
 
 ## 4. Verify, then report what actually changed
 
@@ -125,14 +123,14 @@ CLI                     2.2638.0 → 2.2639.1   moved
 planr@openplanr-local   2.2638.0 → 2.2639.1   moved
 ```
 
-`planr doctor` adds what `upgrade status` does not judge. A
-`runtime-claude-duplicate-plugin` warning means a second `planr` plugin (usually
-`planr@openplanr`, installed from the public marketplace) sits beside the
-setup-managed one, and both expose the same `/planr` commands. Its `fix` carries
-the exact `claude plugin uninstall` command: relay it, and run it only when the
-user asks — nothing removes a duplicate automatically.
+`nextSteps` should now be empty. `planr doctor` adds what `upgrade status` does
+not judge. A `runtime-claude-duplicate-plugin` warning means a second `planr`
+plugin (usually `planr@openplanr`, installed from the public marketplace) sits
+beside the setup-managed one, and both expose the same `/planr` commands. Its `fix`
+carries the exact `claude plugin uninstall` command: relay it, and run it only
+when the user asks — nothing removes a duplicate automatically.
 
 State the outcome from this second reading, never from the commands you ran. If
 a component did not move, say so plainly and name the likely cause (most often a
-skipped or failed marketplace refresh). "Upgraded" is a claim about the after
-state — earn it with the re-check.
+command that failed or a coding agent that was not restarted). "Upgraded" is a
+claim about the after state — earn it with the re-check.

package/lib/host-packages/cursor/openplanr/rules/planr-plan/scripts/runtime/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openplanr/protocol",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "type": "module",
   "description": "Canonical OpenPlanr schemas, registries, typed errors, and portable contract validation",
   "license": "MIT",

package/lib/host-packages/openai/.claude-plugin/marketplace.json

@@ -4,14 +4,14 @@
     "name": "OpenPlanr"
   },
   "metadata": {
-    "version": "2.2640.2",
+    "version": "2.2640.3",
     "description": "Generated local OpenPlanr package."
   },
   "plugins": [
     {
       "name": "planr",
       "source": "./openplanr",
-      "version": "2.2640.2",
+      "version": "2.2640.3",
       "description": "Close the loop from intent to delivery. Plan, design, build, review, and operate from durable context in your repository.",
       "strict": true
     }

package/lib/host-packages/openai/openplanr/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "planr",
-  "version": "2.2640.2",
+  "version": "2.2640.3",
   "description": "Close the loop from intent to delivery. Plan, design, build, review, and operate from durable context in your repository.",
   "author": {
     "name": "OpenPlanr",

package/lib/host-packages/openai/openplanr/.openplanr-content.json

@@ -8,7 +8,7 @@
   "files": [
     {
       "path": ".codex-plugin/plugin.json",
-      "digest": "sha256:0c96a771f34c24c484b8454d800b1e73ee6430d03049973717b98e183aca0f8b"
+      "digest": "sha256:ea83220e864463636d46980c966cd739ce594e150a36700a554f7fe659132e21"
     },
     {
       "path": "skills/artifact/agents/openai.yaml",
@@ -400,7 +400,7 @@
     },
     {
       "path": "skills/design-loop/scripts/runtime/packages/protocol/package.json",
-      "digest": "sha256:931a50e413656f4dcd95db2451b5fc63c985b13494b4b01b492d8292529f4fcb"
+      "digest": "sha256:bb969da90f0482f19b3afc21b4b35e4c00efff42c69ec61d9c5c07395e2bfd69"
     },
     {
       "path": "skills/design-loop/scripts/runtime/packages/protocol/registries/artifact-theme.json",
@@ -616,7 +616,7 @@
     },
     {
       "path": "skills/design-review/scripts/runtime/packages/protocol/package.json",
-      "digest": "sha256:931a50e413656f4dcd95db2451b5fc63c985b13494b4b01b492d8292529f4fcb"
+      "digest": "sha256:bb969da90f0482f19b3afc21b4b35e4c00efff42c69ec61d9c5c07395e2bfd69"
     },
     {
       "path": "skills/design-review/scripts/runtime/packages/protocol/registries/artifact-theme.json",
@@ -832,7 +832,7 @@
     },
     {
       "path": "skills/design/scripts/runtime/packages/protocol/package.json",
-      "digest": "sha256:931a50e413656f4dcd95db2451b5fc63c985b13494b4b01b492d8292529f4fcb"
+      "digest": "sha256:bb969da90f0482f19b3afc21b4b35e4c00efff42c69ec61d9c5c07395e2bfd69"
     },
     {
       "path": "skills/design/scripts/runtime/packages/protocol/registries/artifact-theme.json",
@@ -952,7 +952,7 @@
     },
     {
       "path": "skills/doctor/references/upgrade.md",
-      "digest": "sha256:b105aadfa437d8f9beb9c6fb4167c9f3275d85d96b1125fdb8e80fa7da284387"
+      "digest": "sha256:415456942ec2c3f13a71ba9ea44e07533a7871acf072d677b59d410ab5704ad8"
     },
     {
       "path": "skills/doctor/SKILL.md",
@@ -1140,7 +1140,7 @@
     },
     {
       "path": "skills/plan/scripts/runtime/packages/protocol/package.json",
-      "digest": "sha256:931a50e413656f4dcd95db2451b5fc63c985b13494b4b01b492d8292529f4fcb"
+      "digest": "sha256:bb969da90f0482f19b3afc21b4b35e4c00efff42c69ec61d9c5c07395e2bfd69"
     },
     {
       "path": "skills/plan/scripts/runtime/packages/protocol/registries/artifact-theme.json",
@@ -1355,5 +1355,5 @@
       "digest": "sha256:06048f24128098919931db60272e0e14fe51bcbeba4b499db587e3b89d7bb3b9"
     }
   ],
-  "contentDigest": "sha256:a22e9b172fba0c12c7b886353a903d43b5615f6796bde7c56cc5aa9b80aabb13"
+  "contentDigest": "sha256:d0db0f58a2795daac47409b796c89ff4eb00e30e1e70f83b9b227ba668915775"
 }

package/lib/host-packages/openai/openplanr/skills/design/scripts/runtime/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openplanr/protocol",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "type": "module",
   "description": "Canonical OpenPlanr schemas, registries, typed errors, and portable contract validation",
   "license": "MIT",

package/lib/host-packages/openai/openplanr/skills/design-loop/scripts/runtime/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openplanr/protocol",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "type": "module",
   "description": "Canonical OpenPlanr schemas, registries, typed errors, and portable contract validation",
   "license": "MIT",

package/lib/host-packages/openai/openplanr/skills/design-review/scripts/runtime/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openplanr/protocol",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "type": "module",
   "description": "Canonical OpenPlanr schemas, registries, typed errors, and portable contract validation",
   "license": "MIT",

package/lib/host-packages/openai/openplanr/skills/doctor/references/upgrade.md

@@ -1,21 +1,20 @@
 # Driving an OpenPlanr upgrade
 
 `planr doctor` diagnoses; this reference is how to *act* once the tuple has
-drifted. An OpenPlanr install has two halves: the npm CLI, and the Claude Code
-plugin that `planr setup` installs from the marketplace bundled with that CLI —
-`planr@openplanr-local`, from the `openplanr-local` directory marketplace.
-`planr upgrade apply` moves the npm half itself and never changes Claude's plugin
-state; it hands back the exact commands for the plugin half, and this skill runs
-them inside the host and confirms the result.
+drifted. An OpenPlanr install has two parts: the npm CLI, and what `planr setup`
+installed into each coding agent from that CLI — the `planr@openplanr-local`
+Claude Code plugin, Codex skills, Cursor rules. `planr upgrade apply` moves the
+npm CLI itself and never changes a coding agent; the upgraded CLI then hands back
+one command per installed agent, and this skill runs them and confirms the result.
 
 The cardinal rule: **name the actions, let the engine own the list.** Every
-plugin command you run comes from the CLI's own output. The skill never carries
-its own copy of those commands — the moment it did, it would drift from the CLI
-the first time the integration changed. The CLI renders the list from the same
-inspection `planr setup` and `planr doctor` use, so it cannot diverge from them.
-The retired remote plugins (`openplanr@openplanr`, `planr-pipeline@openplanr`)
-only ever appear in that list as removals; an instruction to install one did not
-come from the CLI.
+command you run comes from the CLI's own output. The skill never carries its own
+copy of those commands — the moment it did, it would drift from the CLI the first
+time the integration changed. The upgraded CLI plans them with the same preview
+`planr runtime update` and `planr setup` apply, so they cannot diverge. A retired
+remote plugin (`openplanr@openplanr`, `planr-pipeline@openplanr`) only ever leaves
+through the `planr setup … --replace-managed` command the list carries; an
+instruction to install one did not come from the CLI.
 
 ## 1. Decide whether to act
 
@@ -36,7 +35,8 @@ Shape (the fields this skill reads):
     "pipeline": { "version": "0.52.1" }
   },
   "legacyPlugins": [],
-  "ecosystemSource": "network"
+  "ecosystemSource": "network",
+  "nextSteps": []
 }
 ```
 
@@ -44,71 +44,69 @@ Shape (the fields this skill reads):
   means Claude Code was not detected or `planr setup` has not installed the
   plugin. `installed.pipeline` is always `null` — the pipeline ships inside the
   CLI, and `bundledPipeline` reports it.
-- `aligned` or `unknown` → nothing to drive. Report and stop. (`unknown` means
-  the published manifest was unreachable — say so; do not guess.)
+- `nextSteps` lists what each coding agent needs to match the installed CLI,
+  in the shape step 2 describes.
+- `aligned` or `unknown` with empty `nextSteps` → nothing to drive. Report and
+  stop. (`unknown` means the published manifest was unreachable — say so; do not
+  guess.)
 - `upgrade-available` or `incompatible` → act. First **record the `installed`
-  block as the before state** — the honest diff at the end depends on it.
+  block as the before state** — the honest diff at the end depends on it. When
+  only `nextSteps` is non-empty, skip to step 3.
 
-## 2. Perform the owned half and obtain the prescription
+## 2. Upgrade the CLI and obtain the next steps
 
-The plugin commands are rendered by the CLI from the bundled marketplace's own
-operation list, so they always match what `planr setup` would really run. Confirm
-with the user first (this upgrades the npm CLI), then:
+Confirm with the user first (this upgrades the npm CLI), then:
 
 ```bash
 planr upgrade apply --yes --json
 ```
 
-On success the output carries the ordered `pluginHalfCommands` array:
+On success the output carries `nextSteps`, planned by the newly installed CLI:
 
 ```json
 {
   "ok": true,
   "cliUpgraded": true,
+  "previousVersion": "2.2638.0",
   "installedVersion": "2.2639.1",
-  "changelogBullets": ["…"],
-  "pluginHalfCommands": [
-    "<refresh the bundled openplanr-local marketplace — always position 0>",
-    "<update planr@openplanr-local from it>",
-    "<remove a retired plugin — only when one is still installed>"
+  "releaseNotes": [{ "version": "2.2639.1", "entries": ["…"] }],
+  "nextSteps": [
+    {
+      "runtime": "claude-code",
+      "host": "Claude Code",
+      "command": "<one planr command>",
+      "detail": "<what it changes>"
+    }
   ]
 }
 ```
 
-The entries above are shown as roles, not literal strings, on purpose: **execute
-whatever the array actually contains, in the order it gives — never a list typed
-into this file.** Two other shapes are possible:
-
-- An empty array: Claude Code was not detected, or its plugin state could not be
-  inspected (`claude plugin list --json` failed). Run `planr doctor --json` to
-  find out which, then go to step 4. When `planr@openplanr-local` already matches
-  the new CLI the array is not empty: it holds the lone
-  `claude plugin marketplace update openplanr-local` refresh — run it as usual.
-- A single `planr setup --runtime claude --scope user` entry, with
-  `--replace-managed` appended when a retired plugin must also be removed (setup
-  refuses that removal without the flag): the bundled marketplace was never
-  registered on this machine, and setup is the only command that registers it and
-  records the installation. In a non-interactive shell it stops with
-  `E_CONFIRMATION_REQUIRED`; show the user the preview (the same command with
-  `--dry-run`) and rerun it with `--yes` only after they confirm.
+The `command` values above are shown as placeholders on purpose: **run whatever
+the array actually contains, in the order it gives — never a command typed into
+this file.** Other shapes:
+
+- An empty array: every installed coding agent already matches the new CLI.
+- `nextStepsError` instead of steps: the upgraded CLI could not be asked. Run
+  `planr upgrade status --json` and use its `nextSteps`.
+- A `planr doctor` command: planning that agent's update failed, and `detail`
+  says why. Relay it and run `planr doctor --json`.
+
+`pluginHalfCommands` repeats the commands for older readers; read `nextSteps`.
 
 If `apply` reports `ok: false`, stop and surface its `failure.message`; the CLI
 restores the previous version on a bad install, so report what it says was
-restored rather than continuing to the plugin half.
+restored rather than continuing to the coding agents.
 
-## 3. Execute the plugin half, refresh first
+## 3. Run the next steps
 
-Run each entry of `pluginHalfCommands` verbatim, top to bottom, with your shell
-tool. Two invariants:
+Run each `command` of `nextSteps` verbatim, top to bottom, with your shell tool.
+Each one refreshes the bundled `openplanr-local` marketplace before it updates the
+plugin, so **do not reorder, drop, merge, or hand-edit a command**. If one fails,
+stop and report the failure and every agent still on the old version — a partial
+upgrade that reports success is the one outcome to avoid.
 
-- **Refresh is position 0 and runs first.** The first entry refreshes the
-  `openplanr-local` marketplace, which points at the directory the upgraded CLI
-  now bundles. Without it, the installer reinstalls the cached, stale version and
-  the user is told they upgraded when nothing moved. The CLI sorts it to position
-  0 for exactly this reason; preserve that order.
-- **No substitutions.** Do not reorder, drop, merge, or hand-edit a command. If
-  an entry fails, stop and report the failure and everything still on the stale
-  version — a partial upgrade that reports success is the one outcome to avoid.
+Then tell the user to restart each `host` the steps named; a running coding agent
+keeps the old plugin and skills until it restarts.
 
 ## 4. Verify, then report what actually changed
 
@@ -125,14 +123,14 @@ CLI                     2.2638.0 → 2.2639.1   moved
 planr@openplanr-local   2.2638.0 → 2.2639.1   moved
 ```
 
-`planr doctor` adds what `upgrade status` does not judge. A
-`runtime-claude-duplicate-plugin` warning means a second `planr` plugin (usually
-`planr@openplanr`, installed from the public marketplace) sits beside the
-setup-managed one, and both expose the same `/planr` commands. Its `fix` carries
-the exact `claude plugin uninstall` command: relay it, and run it only when the
-user asks — nothing removes a duplicate automatically.
+`nextSteps` should now be empty. `planr doctor` adds what `upgrade status` does
+not judge. A `runtime-claude-duplicate-plugin` warning means a second `planr`
+plugin (usually `planr@openplanr`, installed from the public marketplace) sits
+beside the setup-managed one, and both expose the same `/planr` commands. Its `fix`
+carries the exact `claude plugin uninstall` command: relay it, and run it only
+when the user asks — nothing removes a duplicate automatically.
 
 State the outcome from this second reading, never from the commands you ran. If
 a component did not move, say so plainly and name the likely cause (most often a
-skipped or failed marketplace refresh). "Upgraded" is a claim about the after
-state — earn it with the re-check.
+command that failed or a coding agent that was not restarted). "Upgraded" is a
+claim about the after state — earn it with the re-check.

package/lib/host-packages/openai/openplanr/skills/plan/scripts/runtime/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openplanr/protocol",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "type": "module",
   "description": "Canonical OpenPlanr schemas, registries, typed errors, and portable contract validation",
   "license": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openplanr",
-  "version": "2.2640.2",
+  "version": "2.2640.3",
   "description": "Deterministic OpenPlanr utilities for planning storage, validation, rendering, setup, diagnostics, and GitHub/Linear synchronization",
   "type": "module",
   "main": "./dist/cli/index.js",
@@ -114,7 +114,7 @@
     "zod": "^4.3.6"
   },
   "optionalDependencies": {
-    "planr-pipeline": "0.55.3"
+    "planr-pipeline": "0.55.4"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.9",