openplanr 2.2641.0 → 2.2641.2

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

@@ -1,9 +1,9 @@
 # Driving an OpenPlanr upgrade
 
-`planr doctor` diagnoses; this reference is how to *act* once the tuple has
-drifted. An OpenPlanr install has two parts: the npm CLI, and what `planr setup`
+`openplanr doctor` diagnoses; this reference is how to *act* once the tuple has
+drifted. An OpenPlanr install has two parts: the npm CLI, and what `openplanr 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
+Claude Code plugin, Codex skills, Cursor rules. `openplanr 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.
 
@@ -11,15 +11,15 @@ The cardinal rule: **name the actions, let the engine own the list.** Every
 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
+`openplanr runtime update` and `openplanr 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
+through the `openplanr setup … --replace-managed` command the list carries; an
 instruction to install one did not come from the CLI.
 
 ## 1. Decide whether to act
 
 ```bash
-planr upgrade status --json
+openplanr upgrade status --json
 ```
 
 Shape (the fields this skill reads):
@@ -41,7 +41,7 @@ Shape (the fields this skill reads):
 ```
 
 - `installed.skills` is the installed version of `planr@openplanr-local`; `null`
-  means Claude Code was not detected or `planr setup` has not installed the
+  means Claude Code was not detected or `openplanr setup` has not installed the
   plugin. `installed.pipeline` is always `null` — the pipeline ships inside the
   CLI, and `bundledPipeline` reports it.
 - `nextSteps` lists what each coding agent needs to match the installed CLI,
@@ -58,7 +58,7 @@ Shape (the fields this skill reads):
 Confirm with the user first (this upgrades the npm CLI), then:
 
 ```bash
-planr upgrade apply --yes --json
+openplanr upgrade apply --yes --json
 ```
 
 On success the output carries `nextSteps`, planned by the newly installed CLI:
@@ -74,7 +74,7 @@ On success the output carries `nextSteps`, planned by the newly installed CLI:
     {
       "runtime": "claude-code",
       "host": "Claude Code",
-      "command": "<one planr command>",
+      "command": "<one openplanr command>",
       "detail": "<what it changes>"
     }
   ]
@@ -87,9 +87,9 @@ 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`.
+  `openplanr upgrade status --json` and use its `nextSteps`.
+- An `openplanr doctor` command: planning that agent's update failed, and `detail`
+  says why. Relay it and run `openplanr doctor --json`.
 
 `pluginHalfCommands` repeats the commands for older readers; read `nextSteps`.
 
@@ -111,8 +111,8 @@ keeps the old plugin and skills until it restarts.
 ## 4. Verify, then report what actually changed
 
 ```bash
-planr upgrade status --json
-planr doctor --json
+openplanr upgrade status --json
+openplanr doctor --json
 ```
 
 Compare the new `installed` block against the before state you recorded, and
@@ -123,12 +123,14 @@ CLI                     2.2638.0 → 2.2639.1   moved
 planr@openplanr-local   2.2638.0 → 2.2639.1   moved
 ```
 
-`nextSteps` should now be empty. `planr doctor` adds what `upgrade status` does
+`nextSteps` should now be empty. `openplanr 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.
+when the user asks — nothing removes a duplicate automatically. An
+`installed-skill-commands` warning means installed skills still use the old
+command name; relay its `fix`, which names the setup command that refreshes them.
 
 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

package/lib/host-packages/cursor/openplanr/rules/planr-doctor.mdc

@@ -5,7 +5,7 @@ alwaysApply: false
 
 # OpenPlanr Doctor
 
-Run `planr doctor` with the requested flags. Prefer `--json` for diagnosis.
+Run `openplanr doctor` with the requested flags. Prefer `--json` for diagnosis.
 Preview every repair; package installation, version changes, provenance recovery,
 and deletion always require explicit confirmation.
 
@@ -20,38 +20,38 @@ share custody under `~/.openplanr/design-shares` is read and safely moved only w
 its canonical destination is absent. Existing destinations are never overwritten.
 When state seems missing, check which variable is set.
 
-Doctor also reports healthy owned local services. Use `planr server list --json`
-to inspect their instance IDs, project and runtime. `planr server stop <instance>`
+Doctor also reports healthy owned local services. Use `openplanr server list --json`
+to inspect their instance IDs, project and runtime. `openplanr server stop <instance>`
 authenticates that exact service, drains pending saves and requests shutdown.
 A port or process ID is never shutdown authority; legacy unowned services remain
 untouched.
 
 ## Driving an upgrade
 
-`planr upgrade` moves only half of an OpenPlanr upgrade — the npm CLI. The other
-half is the Claude Code plugin that `planr setup` installs from the bundled
+`openplanr upgrade` moves only half of an OpenPlanr upgrade — the npm CLI. The other
+half is the Claude Code plugin that `openplanr setup` installs from the bundled
 `openplanr-local` marketplace, and the upgrade never changes that plugin itself:
 it hands back the exact commands. Driving them with host shell access is this
 skill's job, then reporting what actually changed — never what was merely
 attempted.
 
-1. **Decide.** Run `planr upgrade status --json` and read `status`. If it is
+1. **Decide.** Run `openplanr upgrade status --json` and read `status`. If it is
    `aligned` or `unknown`, there is nothing to drive — report it and stop.
    Record the reported `installed` versions; that is the before state.
 2. **Own half, prescribe half.** If `status` is `upgrade-available` or
    `incompatible`, confirm with the user (this upgrades the npm CLI), then run
-   `planr upgrade apply --yes --json`. The CLI performs the npm half itself and
+   `openplanr upgrade apply --yes --json`. The CLI performs the npm half itself and
    returns the plugin half as an ordered `pluginHalfCommands` array — the exact
    argv it would run, so the list can never drift from the engine. Take the
    commands from there; never write a plugin command of your own.
 3. **Refresh first, then execute in order.** Run every entry of
    `pluginHalfCommands` verbatim, in the array's given order, with your shell.
    The first entry is either the `openplanr-local` marketplace refresh or a
-   single `planr setup …` command (when that marketplace was never registered);
+   single `openplanr setup …` command (when that marketplace was never registered);
    it must run first: skip the refresh and the installer reinstalls the cached,
    stale version while the user believes they upgraded. Do not reorder, drop, or
    substitute an entry.
-4. **Verify and report the real diff.** Re-run `planr upgrade status --json` and
+4. **Verify and report the real diff.** Re-run `openplanr upgrade status --json` and
    compare its `installed` versions against the before state. Report only what
    actually moved and to what. If a component did not move, say so — never claim
    "upgraded" for a version that did not change.

package/lib/host-packages/cursor/openplanr/rules/planr-land.mdc

@@ -10,8 +10,8 @@ user wants to assess readiness or prepare a clear landing sequence.
 
 1. Read the current branch, worktree status, requested target, completed checks,
    and release constraints already available in the repository or conversation.
-2. Inspect the installed CLI help, then use `planr land prepare`, `planr land
-   show`, or `planr land status` only when that command adds useful local state.
+2. Inspect the installed CLI help, then use `openplanr land prepare`, `openplanr land
+   show`, or `openplanr land status` only when that command adds useful local state.
 3. Identify blockers, missing checks, ordering constraints, recovery options,
    and the exact merge, publication, or deployment commands the user would run.
 4. If a real release choice is missing, use the host's native structured question

package/lib/host-packages/cursor/openplanr/rules/planr-operate.mdc

@@ -46,9 +46,11 @@ matches. Never overwrite a prior cycle implicitly.
 ```
 
 `cycle.md` records the effective scope, roster, repository revision when relevant, and the outcome
-of each lens. If the directory is ignored by Git, continue locally and mention that in the report;
-do not ask the user to change ignore rules. Report an exact filesystem error only when the cycle
-workspace cannot be created or written.
+of each lens. An advisor lens run on its own creates the same layout with a one-lens roster and an
+unsynthesized `board-report.md`, so every review the dashboard lists has one shape.
+If the directory is ignored by Git, continue locally and mention that in the report; do not ask the
+user to change ignore rules. Report an exact filesystem error only when the cycle workspace cannot be
+created or written.
 
 ## Build shared context once
 

package/lib/host-packages/cursor/openplanr/rules/planr-plan/references/artifact-contract.md

@@ -10,6 +10,11 @@
   tasks/T-NNN-{slug}.md
 ```
 
+Before writing under `.planr/`, confirm OpenPlanr created it. When it has no
+`config.json` but holds `planr.config.json`, `board.html`, or `*-goal.md` files in
+`tasks/` or `plans/`, OpenPlanr didn't create it: write nothing there, tell the user
+what you found, and ask them to move or rename that folder.
+
 Use Protocol `1.7.0` frontmatter for stories and tasks. Story frontmatter has
 `id`, `title`, `specId`, `slug`, `schemaVersion`, `status`, dates, and
 `acceptanceCriteria` entries with stable `AC-NNN` IDs. Task frontmatter has

package/lib/host-packages/cursor/openplanr/rules/planr-plan.mdc

@@ -78,8 +78,14 @@ Write stories and tasks directly in the repository's active planning mode.
   deleted ID. The packaged [planning ID helper](planr-plan/scripts/planning-ids.mjs) may
   inspect or reserve IDs; it never generates content.
 - Give each story stable acceptance IDs starting at `AC-001`.
-- Create one Tech task when no design surface applies; create one UI and one
-  Tech task when it does. Never exceed two tasks for one story.
+- Split each story into tasks that are coherent and independently verifiable.
+  Separate by ownership first: UI work is a `UI` task for the frontend role and
+  server, data, or integration work is a `Tech` task for the backend role.
+  Within one owner, split further only for a real output dependency, a distinct
+  verification surface, or reviewable size. Most stories need one Tech task,
+  plus one UI task when a design surface applies; never fragment one coherent
+  change into tasks that cannot be verified alone, and never fold unrelated work
+  into one task.
 - Map every acceptance ID through `acceptanceRefs` and name it with a concrete
   verification statement under `## Test Requirements`.
 - Set `reviewRisks` and `browserSurfaces` from repository evidence; use empty

package/lib/host-packages/cursor/openplanr/rules/planr-spec/references/specification-contract.md

@@ -6,6 +6,11 @@ frontmatter: `id`, `title`, `slug`, `schemaVersion`, `status`, `priority`,
 `created`, `updated`, `ui_files`, and `tech_dependencies`. Preserve supported
 optional fields used by the repository.
 
+Before writing under `.planr/`, confirm OpenPlanr created it. When it has no
+`config.json` but holds `planr.config.json`, `board.html`, or `*-goal.md` files in
+`tasks/` or `plans/`, OpenPlanr didn't create it: write nothing there, tell the user
+what you found, and ask them to move or rename that folder.
+
 Use these body sections, in this order, when the repository has no stronger
 template:
 

package/lib/host-packages/cursor/openplanr/rules/planr-sprint/references/refinement-contract.md

@@ -2,10 +2,10 @@
 
 The refinement document is the durable record of one run: what was read, how
 each item was judged, what was selected and what the refuters changed. The CLI
-validates it (`planr sprint refinement <id> --data`), stores it as
+validates it (`openplanr sprint refinement <id> --data`), stores it as
 `.planr/sprints/SPRINT-NNN/refinement.json`, renders `refinement.md` from it
-and fills the sprint body from its batches. `planr sprint diff`, `planr sprint
-close` and `planr sprint apply` read it back.
+and fills the sprint body from its batches. `openplanr sprint diff`, `openplanr sprint
+close` and `openplanr sprint apply` read it back.
 
 ## Item record
 
@@ -26,7 +26,7 @@ One entry per open item, whether or not it is selected.
 | `bucket` | `inProgress`, `planNext`, `blocked` or `closeOrDemote`. |
 | `reason` | One clause: why the item sits in that bucket. |
 | `evidence` | For close-or-demote rows: `file:line`, PR number or date. |
-| `targetStatus` / `targetPriority` | What `planr sprint apply` writes, in the repository's own vocabulary (`planr update --help`). Priority applies to backlog items only. |
+| `targetStatus` / `targetPriority` | What `openplanr sprint apply` writes, in the repository's own vocabulary (`openplanr update --help`). Priority applies to backlog items only. |
 
 ## Scoring
 
@@ -149,6 +149,6 @@ A pick that fails a lens moves or drops, and the correction is recorded in
 
 `inputs.sources` names what was read; `inputs.defaulted` names every value
 taken from a default instead of the repository or the user. The CLI adds
-`leftovers[]` on `planr sprint close` and `applied` on `planr sprint apply`;
+`leftovers[]` on `openplanr sprint close` and `applied` on `openplanr sprint apply`;
 never write those yourself. Unknown fields are rejected, so keep notes in
 `inputs.notes` or in the item's `reason`.

package/lib/host-packages/cursor/openplanr/rules/planr-sprint/references/sprint-formats.md

@@ -3,7 +3,7 @@
 Three durable outputs and one chat return. The CLI writes the first three from
 the two JSON inputs below; when it is unavailable, write the same files by hand.
 
-## `sprint.json` (input to `planr sprint create --data`)
+## `sprint.json` (input to `openplanr sprint create --data`)
 
 ```json
 {
@@ -17,7 +17,7 @@ the two JSON inputs below; when it is unavailable, write the same files by hand.
 
 `endDate` defaults to `releaseCut`, or to `startDate` plus the duration when no
 cut is known. `status` may be `planned` or `active` (default). Omit `taskIds`
-and `batches`; `planr sprint refinement` fills them from the refinement
+and `batches`; `openplanr sprint refinement` fills them from the refinement
 document.
 
 ## Sprint artifact
@@ -64,11 +64,11 @@ refinedAt: "2026-09-17"
 - [ ] **QT-194** Release cut 25 Sep · hours · [view](../quick/QT-194-release-cut-25-sep.md)
 
 ## Retrospective
-_Complete this section when closing the sprint with `planr sprint close SPRINT-004`._
+_Complete this section when closing the sprint with `openplanr sprint close SPRINT-004`._
 ```
 
 Each task line is `- [ ] **ID** title · effort · [view](relative path)`.
-`planr status`, `planr sprint close` and the dashboard read these lines; tick a
+`openplanr status`, `openplanr sprint close` and the dashboard read these lines; tick a
 box when the item ships. `releaseCut` is absent when no release profile exists;
 `capacityDays` and `refinedAt` are absent until a refinement is recorded.
 
@@ -84,20 +84,20 @@ run can diff against it:
 - **Refuter verdicts**: every correction verbatim, with its lens.
 - **In progress** by batch, then **Plan next**, **Blocked** and **Close or
   demote** in full, since only In progress goes into the sprint.
-- **Leftovers** (after `planr sprint close`) and **Applied** (after
-  `planr sprint apply`).
+- **Leftovers** (after `openplanr sprint close`) and **Applied** (after
+  `openplanr sprint apply`).
 
 ## Machine-readable copy
 
 `.planr/sprints/SPRINT-NNN/refinement.json`: the document described in
 [the refinement contract](refinement-contract.md), validated against the JSON
 Schema packaged as `schemas/refinement.schema.json` (linked from the skill
-entrypoint). The dashboard, `planr sprint diff` and `planr sprint apply` consume
+entrypoint). The dashboard, `openplanr sprint diff` and `openplanr sprint apply` consume
 it.
 
 ## Status write-back
 
-Only on approval through the structured question. `planr sprint apply
+Only on approval through the structured question. `openplanr sprint apply
 SPRINT-NNN --yes --commit` writes each close, demote or blocked row's
 `targetStatus`, `targetPriority` and `blockedBy` to the artifacts and commits the
 sprint, the note, the JSON and the changed artifacts as one commit:

package/lib/host-packages/cursor/openplanr/rules/planr-sprint/references/tracker-connections.md

@@ -0,0 +1,70 @@
+# GitHub and Linear connections
+
+These skills store and read no GitHub or Linear credentials. Remote steps run through a
+connection the host already has; the planning files stay the source of truth.
+
+## Use the host's connection
+
+- **Linear:** the host's Linear connection, whose tools read, create and update issues.
+- **GitHub:** the host's GitHub connection, or the GitHub CLI when
+  `gh auth status --hostname github.com` succeeds.
+
+Never ask the user for a token, read one from the environment or a file, or put one in a
+command, URL or file.
+
+## When a connection is missing
+
+Finish the local work first. Then report the remote step as not run and give the one
+line for the current host:
+
+| Host | Linear | GitHub |
+| --- | --- | --- |
+| Claude Code | Run `/plugin install linear@claude-plugins-official`, then sign in to Linear from `/mcp`. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
+| Codex | Run `codex mcp add linear --url https://mcp.linear.app/mcp`, then `codex mcp login linear`. | Install the GitHub plugin from `/plugins`, or run `gh auth login`. |
+| Cursor | Add Linear from the Cursor Marketplace and sign in to Linear. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
+
+Ask the user to try again once connected; never retry the remote step on your own.
+
+## Status mapping
+
+| Local status | Linear workflow state | GitHub issue |
+| --- | --- | --- |
+| `planning`, `pending` | Unstarted (for example Todo) | open |
+| `in-progress` | Started (for example In Progress) | open |
+| `done` | Completed (for example Done) | closed |
+| Backlog `open` | Backlog, else Unstarted | open |
+| Backlog `closed` | Completed | closed |
+| Backlog `promoted` | Leave as it is | Leave as it is |
+
+When reading state back, write only a status the item's type allows. A backlog item takes
+`open` or `closed` and keeps `promoted`.
+
+- Linear Completed or Canceled sets `done`, or `closed` for a backlog item. Started sets
+  `in-progress`, and Triage, Backlog or Unstarted sets `planning` for features and stories
+  and `pending` for quick tasks; a backlog item takes `open` from any of these. Epics and
+  task files keep their status.
+- A closed GitHub issue sets `done`, or `closed` for a backlog item. An open issue sets
+  `in-progress` for a `done` item and `open` for a `closed` backlog item; other statuses
+  stay as they are.
+
+## Links
+
+A linked item records its tracker identity in frontmatter. Update a linked item through
+that identity instead of creating another, and record the identity of everything you
+create.
+
+- **GitHub:** each item is one issue, recorded as `githubIssue`.
+- **Linear:** use the shapes the OpenPlanr CLI uses, so its later pushes reuse what you
+  create:
+  - An epic is a Linear project (`linearProjectId`, `linearProjectIdentifier`,
+    `linearProjectUrl`). When its `linearMappingStrategy` is `milestone-of` or `label-on`,
+    it is a milestone in an existing project (`linearMilestoneId`) or a team label
+    (`linearLabelId`) instead, and every issue under it carries that milestone
+    (`linearProjectMilestoneId`) or label (`linearLabelIds`).
+  - A feature, quick task or backlog item is one issue (`linearIssueId`,
+    `linearIssueIdentifier`, `linearIssueUrl`). A story is a sub-issue of its feature's
+    issue (`linearParentIssueId`).
+  - All task files of one feature share one task-list issue: a sub-issue of the feature's
+    issue whose checklist merges every task file, recorded in each task file. Its state is
+    Completed when every task file is `done`, Unstarted when every one is `pending`, and
+    Started otherwise.

package/lib/host-packages/cursor/openplanr/rules/planr-sprint/schemas/refinement.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openplanr.dev/schemas/skills/planr-sprint/refinement.schema.json",
   "title": "OpenPlanr sprint refinement document",
-  "description": "One backlog refinement run: inputs, every open item's judgement, the four buckets, the in-progress batches and the refuter corrections. Written by the planr-sprint skill and validated by planr sprint refinement.",
+  "description": "One backlog refinement run: inputs, every open item's judgement, the four buckets, the in-progress batches and the refuter corrections. Written by the planr-sprint skill and validated by openplanr sprint refinement.",
   "type": "object",
   "additionalProperties": false,
   "required": ["schemaVersion", "sprintId", "refinedAt", "inputs", "items", "buckets"],
@@ -102,7 +102,7 @@
       }
     },
     "leftovers": {
-      "description": "Written by planr sprint close.",
+      "description": "Written by openplanr sprint close.",
       "type": "array",
       "items": {
         "type": "object",
@@ -115,7 +115,7 @@
       }
     },
     "applied": {
-      "description": "Written by planr sprint apply.",
+      "description": "Written by openplanr sprint apply.",
       "type": "object",
       "additionalProperties": false,
       "required": ["at", "updates"],

package/lib/host-packages/cursor/openplanr/rules/planr-sprint.mdc

@@ -10,7 +10,7 @@ item in full and judges it against the default branch and the calendar.
 **Select** fits the surviving items to the stated capacity and the next release
 cut, refutes the picks with three independent lenses, and writes the sprint.
 Perform the reasoning in this session; never delegate it to a model subprocess.
-The CLI (`planr sprint …`) stores what this skill decides. It is optional: when
+The CLI (`openplanr sprint …`) stores what this skill decides. It is optional: when
 it is unavailable, write the same files by hand in the shapes given in
 [sprint formats](planr-sprint/references/sprint-formats.md).
 
@@ -33,9 +33,9 @@ capability; it never blocks the run. Name every degraded input in `Issues`.
 | Git history and the code paths items cite | Evidence lens: stale, already fixed, premise false | Buckets rest on the items' own dates; say "not verified against code" |
 | Release profile (`.release/profile.md`: cut date, cadence, freezes) | Size the In-progress bucket to the cut; the sprint gets `releaseCut` | Ask once for a horizon; default to a two-week sprint from today |
 | Capacity (engineers × working days) | Fit the list and name the overflow | Ask once; default 1 engineer × 10 days, stated in the return |
-| Previous sprint or refinement note (`.planr/sprints/SPRINT-NNN/refinement.json`) | Carry `leftovers`; `planr sprint diff` is possible | First run, no diff |
+| Previous sprint or refinement note (`.planr/sprints/SPRINT-NNN/refinement.json`) | Carry `leftovers`; `openplanr sprint diff` is possible | First run, no diff |
 | Last Operate cycle | Rank its unfinished actions alongside | Skipped silently |
-| Linear or GitHub connector | Push statuses on approval, read PR state | Local files only; report the external step as not run |
+| Linear or GitHub connection ([tracker connections](planr-sprint/references/tracker-connections.md)) | Update linked issues on approval, read PR state | Local files only; report the external step as not run and name the connection to add |
 
 ## Step 0: Frame the run
 
@@ -89,7 +89,7 @@ the cheapest refutations.
 
 Carry the previous Operate cycle's unfinished actions explicitly. Include the
 release cut itself as work; when it has no artifact yet, file it with
-`planr quick create "Release cut <date>"` so the sprint contains only artifact
+`openplanr quick create "Release cut <date>"` so the sprint contains only artifact
 ids.
 
 ## Step 4: Refute the In-progress bucket
@@ -113,9 +113,9 @@ Write the three durable outputs (formats in
 them.
 
 ```bash
-planr sprint create --data sprint.json --json                  # name, releaseCut, capacityDays, startDate
-planr sprint refinement SPRINT-NNN --data refinement.json --json # validates, stores the note and JSON, fills the sprint body
-planr sprint diff SPRINT-MMM SPRINT-NNN                          # when a previous run exists
+openplanr sprint create --data sprint.json --json                  # name, releaseCut, capacityDays, startDate
+openplanr sprint refinement SPRINT-NNN --data refinement.json --json # validates, stores the note and JSON, fills the sprint body
+openplanr sprint diff SPRINT-MMM SPRINT-NNN                          # when a previous run exists
 ```
 
 `refinement.json` must satisfy [the schema](planr-sprint/schemas/refinement.schema.json); the
@@ -130,16 +130,17 @@ write-back, or leave the proposal as written.
 ## Step 6: On approval, apply
 
 ```bash
-planr sprint apply SPRINT-NNN --dry-run          # show the status and priority changes
-planr sprint apply SPRINT-NNN --yes --commit     # one commit: chore(planr): refine backlog for SPRINT-NNN
+openplanr sprint apply SPRINT-NNN --dry-run          # show the status and priority changes
+openplanr sprint apply SPRINT-NNN --yes --commit     # one commit: chore(planr): refine backlog for SPRINT-NNN
 ```
 
-Where a connector is configured, push each changed item afterwards
-(`planr linear push <id>`, `planr github push <id>`) and report the ones that
-were not pushed. When the CLI is unavailable, apply the same status changes with
+Then update the issue linked to each changed item through the host's Linear or
+GitHub connection, with the status mapping in
+[tracker connections](planr-sprint/references/tracker-connections.md), and report the items that
+were not updated. When the CLI is unavailable, apply the same status changes with
 the repository's own vocabulary and commit them with the same message.
 
-Close a finished sprint with `planr sprint close SPRINT-NNN`; it records the
+Close a finished sprint with `openplanr sprint close SPRINT-NNN`; it records the
 leftovers the next run carries.
 
 ## Rules from production use
@@ -151,7 +152,7 @@ leftovers the next run carries.
   the question that unblocks them.
 - The list must fit the stated capacity; if it does not, say what was cut.
 - No new migration in a hand deploy unless the sprint says so explicitly.
-- Use the repository's own status vocabulary (`planr update --help` lists it);
+- Use the repository's own status vocabulary (`openplanr update --help` lists it);
   never introduce a second one.
 - The note and the JSON are the durable output; the chat return is a view of
   them. That is what keeps the third run from re-arguing the first two.
@@ -178,7 +179,7 @@ and identify incomplete evidence or blocked inputs with their recovery action.
 The note and JSON remain complete and unchanged in shape. Omit empty chat sections;
 different summary wording never causes another sprint creation or write-back.
 
-`planr status` shows the active sprint with its cut and progress; the dashboard
+`openplanr status` shows the active sprint with its cut and progress; the dashboard
 (`planr-dashboard`) renders the sprint from the same frontmatter and checkboxes.
 
 ## Reference files

package/lib/host-packages/cursor/openplanr/rules/planr-status/references/tracker-connections.md

@@ -0,0 +1,70 @@
+# GitHub and Linear connections
+
+These skills store and read no GitHub or Linear credentials. Remote steps run through a
+connection the host already has; the planning files stay the source of truth.
+
+## Use the host's connection
+
+- **Linear:** the host's Linear connection, whose tools read, create and update issues.
+- **GitHub:** the host's GitHub connection, or the GitHub CLI when
+  `gh auth status --hostname github.com` succeeds.
+
+Never ask the user for a token, read one from the environment or a file, or put one in a
+command, URL or file.
+
+## When a connection is missing
+
+Finish the local work first. Then report the remote step as not run and give the one
+line for the current host:
+
+| Host | Linear | GitHub |
+| --- | --- | --- |
+| Claude Code | Run `/plugin install linear@claude-plugins-official`, then sign in to Linear from `/mcp`. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
+| Codex | Run `codex mcp add linear --url https://mcp.linear.app/mcp`, then `codex mcp login linear`. | Install the GitHub plugin from `/plugins`, or run `gh auth login`. |
+| Cursor | Add Linear from the Cursor Marketplace and sign in to Linear. | Install the GitHub CLI (cli.github.com) and run `gh auth login`. |
+
+Ask the user to try again once connected; never retry the remote step on your own.
+
+## Status mapping
+
+| Local status | Linear workflow state | GitHub issue |
+| --- | --- | --- |
+| `planning`, `pending` | Unstarted (for example Todo) | open |
+| `in-progress` | Started (for example In Progress) | open |
+| `done` | Completed (for example Done) | closed |
+| Backlog `open` | Backlog, else Unstarted | open |
+| Backlog `closed` | Completed | closed |
+| Backlog `promoted` | Leave as it is | Leave as it is |
+
+When reading state back, write only a status the item's type allows. A backlog item takes
+`open` or `closed` and keeps `promoted`.
+
+- Linear Completed or Canceled sets `done`, or `closed` for a backlog item. Started sets
+  `in-progress`, and Triage, Backlog or Unstarted sets `planning` for features and stories
+  and `pending` for quick tasks; a backlog item takes `open` from any of these. Epics and
+  task files keep their status.
+- A closed GitHub issue sets `done`, or `closed` for a backlog item. An open issue sets
+  `in-progress` for a `done` item and `open` for a `closed` backlog item; other statuses
+  stay as they are.
+
+## Links
+
+A linked item records its tracker identity in frontmatter. Update a linked item through
+that identity instead of creating another, and record the identity of everything you
+create.
+
+- **GitHub:** each item is one issue, recorded as `githubIssue`.
+- **Linear:** use the shapes the OpenPlanr CLI uses, so its later pushes reuse what you
+  create:
+  - An epic is a Linear project (`linearProjectId`, `linearProjectIdentifier`,
+    `linearProjectUrl`). When its `linearMappingStrategy` is `milestone-of` or `label-on`,
+    it is a milestone in an existing project (`linearMilestoneId`) or a team label
+    (`linearLabelId`) instead, and every issue under it carries that milestone
+    (`linearProjectMilestoneId`) or label (`linearLabelIds`).
+  - A feature, quick task or backlog item is one issue (`linearIssueId`,
+    `linearIssueIdentifier`, `linearIssueUrl`). A story is a sub-issue of its feature's
+    issue (`linearParentIssueId`).
+  - All task files of one feature share one task-list issue: a sub-issue of the feature's
+    issue whose checklist merges every task file, recorded in each task file. Its state is
+    Completed when every task file is `done`, Unstarted when every one is `pending`, and
+    Started otherwise.

package/lib/host-packages/cursor/openplanr/rules/planr-status.mdc

@@ -7,12 +7,13 @@ alwaysApply: false
 
 Inspect delivery state read-only in the active session. Read the repository's
 planning artifacts, task statuses, dependency graph, current branch, and relevant
-runtime markers directly. Use the optional deterministic `planr status --json`
+runtime markers directly. Use the optional deterministic `openplanr status --json`
 utility when available, but do not require it or a semantic subprocess.
 
-Add GitHub or Linear lookups only when the user requests live remote state. Keep
-local results useful when credentials or connectors are unavailable. Report
-counts, ready and blocked work, dependency problems, and the most useful next
+Add GitHub or Linear lookups only when the user requests live remote state, through
+the host's connections as described in [tracker connections](planr-status/references/tracker-connections.md).
+Keep local results useful when a connection is unavailable, and name the one to add.
+Report counts, ready and blocked work, dependency problems, and the most useful next
 action. Do not repair artifacts, start Plan or Ship, or change lifecycle state.
 
 When the OpenPlanr dashboard is running (`planr-dashboard`), the same delivery