openplanr 1.25.3 → 2.0.0

package/lib/host-packages/cursor/openplanr/rules/planr-design-review/scripts/runtime/packages/protocol/schemas/v1.9.0/design-workspace-event.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.9.0/design-workspace-event.schema.json",
+  "x-openplanr-contract": {
+    "id": "design-workspace-event",
+    "version": "1.9.0"
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{22,64}$"
+    },
+    "revisionId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{22,64}$"
+    },
+    "reviewOf": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "epoch": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647
+    },
+    "iv": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 16,
+      "maxLength": 16
+    },
+    "ciphertext": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 22,
+      "maxLength": 6990507
+    },
+    "publicKey": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kty",
+        "crv",
+        "x",
+        "y"
+      ],
+      "properties": {
+        "kty": {
+          "const": "EC"
+        },
+        "crv": {
+          "const": "P-256"
+        },
+        "x": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]+$",
+          "minLength": 43,
+          "maxLength": 43
+        },
+        "y": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]+$",
+          "minLength": 43,
+          "maxLength": 43
+        },
+        "ext": {
+          "type": "boolean"
+        },
+        "key_ops": {
+          "type": "array",
+          "items": {
+            "const": "verify"
+          },
+          "maxItems": 1
+        }
+      }
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 86,
+      "maxLength": 86
+    }
+  },
+  "required": [
+    "id",
+    "revisionId",
+    "reviewOf",
+    "epoch",
+    "iv",
+    "ciphertext",
+    "publicKey",
+    "signature"
+  ]
+}

package/lib/host-packages/cursor/openplanr/rules/planr-design-review/scripts/runtime/packages/protocol/schemas/v1.9.0/design-workspace-revision.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.9.0/design-workspace-revision.schema.json",
+  "x-openplanr-contract": {
+    "id": "design-workspace-revision",
+    "version": "1.9.0"
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{22,64}$"
+    },
+    "epoch": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647
+    },
+    "reviewOf": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "iv": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 16,
+      "maxLength": 16
+    },
+    "ciphertext": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 22,
+      "maxLength": 6990507
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 86,
+      "maxLength": 86
+    }
+  },
+  "required": [
+    "id",
+    "epoch",
+    "reviewOf",
+    "createdAt",
+    "iv",
+    "ciphertext",
+    "signature"
+  ]
+}

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

@@ -0,0 +1,53 @@
+---
+description: "Review and revise an existing product design using stable board pins and scoped browser-verified changes. Use for focused improvements while preserving unrelated screens and feedback."
+alwaysApply: false
+---
+
+# Planr Design Review
+
+Improve the existing design in this active host session, retaining the user's
+intent and recorded feedback.
+
+1. Read [review.md](references/review.md), then inspect the existing design
+   document, authored sources, specification, manifest, prior revision and board
+   feedback using [utilities.md](references/utilities.md) and
+   [scripts/design.mjs](scripts/design.mjs). Legacy HTML, canvas and image artifacts
+   remain reviewable; preserve originals and distinguish static images from
+   working interaction. Preserve the [document contract](schemas/design-document.schema.json).
+   Use the public `planr artifact` route when available.
+2. Consult [discovery.md](references/discovery.md) only for missing context or
+   consequential ambiguity. Read the project's components and tokens using
+   [design-system.md](references/design-system.md). Ask through native structured
+   questions with concise chat fallback; do not ask again for settled decisions.
+3. Map pins to stable screens and anchors. Report missing or stale targets as
+   unresolved rather than attaching them elsewhere. Chat may request broad
+   changes; board state remains the pin/rating authority. State shared-component
+   scope before updating every affected instance.
+4. Apply changes only to the targeted source or component, following
+   [generation.md](references/generation.md) and [craft.md](references/craft.md).
+   Keep unrelated screens, identities, feedback and arrangement intact. Stage a
+   complete revision; a failed revision preserves the last working studio.
+   Read [team-review.md](references/team-review.md) and update the sibling
+   `review-context.json` for the changed journey and unresolved review questions.
+   Create it when missing. Ground the welcome purpose and up to three consequential
+   questions in the supplied brief and recorded feedback; preserve still-relevant
+   wording and implementation guidance, and never invent requirements.
+5. Inspect revised screenshots at affected responsive frames, exercise the
+   changed journey and keyboard focus, and record evidence. Resolve pins only
+   after the relevant change is rendered and checked. A static lint pass does not
+   establish visual verification; absent browser inspection means **unverified**.
+6. Synchronize the specification, document and compatibility manifest using
+   [handoff.md](references/handoff.md) and the
+   [ten-section template](references/design-spec-template.md). Update only affected
+   specification sections. Record retained and rejected project preferences.
+
+Return applied feedback and affected screens, remaining/stale pins, source and
+studio paths, and verification results. Plan is an optional next invocation.
+Opening, revising or selecting a design never auto-starts Plan, Ship, publication,
+deployment, review-link creation or review-URL import. When company review is
+requested, validate, render and inspect the current welcome context before using
+the studio's encrypted Share flow. Preserve reviewer attribution.
+
+For company reviews and implementation handoff, follow
+[team-review.md](references/team-review.md). Keep review guidance outside product
+screens, preserve reviewer intent, and let the owner approve the refined handoff.

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

@@ -0,0 +1,72 @@
+---
+description: "Design a polished product interface through adaptive consultation, a shared canvas/prototype/walkthrough studio, and an implementation-ready specification. Use for a new design or an existing interface that needs a coherent direction."
+alwaysApply: false
+---
+
+# Planr Design
+
+Develop one strong direction in the active host session, grounded in the product
+and its visual language. Deliver editable local source, a working review studio,
+and a ten-section design specification ready for Plan.
+
+## Consult and establish direction
+
+Read [discovery.md](references/discovery.md) before generating. Inspect the brief,
+app shell, components, tokens, assets, reference screens, prior design and project
+taste. Ask only consequential unresolved questions using the host's native
+structured question surface, or one concise chat question when unavailable.
+Honor previous answers and presentation choices. Evolve existing designs by
+default; replacement retains a recoverable prior revision.
+
+Use [design-system.md](references/design-system.md) to reuse the app's system or
+establish a deliberate greenfield system. Existing project conventions take
+precedence over generic spacing, typography and frame defaults.
+
+## Author and inspect
+
+Read [generation.md](references/generation.md) and [craft.md](references/craft.md).
+Use the [document contract](schemas/design-document.schema.json) to create one
+design document with stable screens and authored local sources. Canvas,
+Prototype and Walkthrough are views of that document; view changes never start
+generation. Use a native designer agent when available, otherwise perform the
+work directly. Semantic design work stays in this active host session.
+
+Read [team-review.md](references/team-review.md) and author `review-context.json`
+beside the design document before rendering every new design. Write its welcome
+purpose and up to three consequential review questions from this project's brief
+and settled answers. Preserve existing guidance; never invent requirements or
+reuse another project's welcome copy.
+
+Use [utilities.md](references/utilities.md) for the bundled deterministic helper
+at [scripts/design.mjs](scripts/design.mjs). It inspects, validates, renders, opens,
+exports and records feedback without a separate CLI installation. When available,
+use the public `planr artifact` route to open the design document.
+
+Inspect browser screenshots and exercise the primary journey and keyboard behavior
+at declared frames. Correct observed failures, then record evidence. Static lint
+alone cannot establish visual verification. When browser inspection is unavailable,
+return the artifact as **unverified**.
+
+The studio can create an encrypted collaborative review for a company team. When
+the user asks to share, refresh and render the welcome context, inspect it in the
+studio, then open Share. Explain the stable review link, separately entered access
+token and private owner controls; never create or send a link without that
+explicit request.
+
+## Review and hand off
+
+Read [review.md](references/review.md) when feedback arrives. Pins and ratings come
+from the board; chat may request broader changes. Preserve unrelated screens,
+stable anchors and board arrangement during scoped revisions.
+
+Finish with [handoff.md](references/handoff.md) and its
+[ten-section template](references/design-spec-template.md). The design author
+writes `design-spec.md` in this run, including image-based inputs. Return the
+studio/source/specification paths, chosen direction, verification result and any
+remaining questions. Stop here: Plan, Ship, creating a share link and deployment
+are separate user actions. Use Design Loop when the user requests alternatives, and Design
+Review for focused iteration on an existing direction.
+
+For company reviews and implementation handoff, follow
+[team-review.md](references/team-review.md). Keep review guidance outside product
+screens, preserve reviewer intent, and let the owner approve the refined handoff.

package/lib/host-packages/cursor/openplanr/rules/planr-diagram/references/diagram-document.md

@@ -0,0 +1,86 @@
+# Diagram document authoring contract
+
+Use this self-contained contract to author a diagram from English intent. Do not
+inspect the OpenPlanr installation, `node_modules`, pipeline source, schemas, or
+fixtures. The public CLI accepts this digestless draft and adds the canonical
+RFC 8785 digest before rendering.
+
+Start from this shape:
+
+```json
+{
+  "diagramId": "request-flow",
+  "title": "Request flow",
+  "summary": "How a request moves from intake to completion.",
+  "audience": "mixed",
+  "grammar": { "id": "sequence", "version": "1.0.0" },
+  "layout": { "direction": "left-right", "detailTier": "balanced" },
+  "theme": { "themeId": "openplanr-default", "mode": "auto" },
+  "source": { "format": "english", "path": null, "digest": null },
+  "nodes": [
+    {
+      "id": "request",
+      "label": "Request",
+      "kind": "primary-item",
+      "description": "A new request enters the system.",
+      "semanticPosition": null
+    },
+    {
+      "id": "completion",
+      "label": "Completion",
+      "kind": "secondary-item",
+      "description": "The verified result is returned.",
+      "semanticPosition": null
+    }
+  ],
+  "relations": [
+    {
+      "id": "request-to-completion",
+      "from": "request",
+      "to": "completion",
+      "kind": "flow",
+      "label": "produces",
+      "weight": null
+    }
+  ],
+  "events": [
+    { "id": "start", "label": "Start", "order": 0, "at": null },
+    { "id": "finish", "label": "Finish", "order": 1, "at": null }
+  ],
+  "emphasis": [
+    { "targetId": "completion", "level": "primary" }
+  ],
+  "accessibility": {
+    "title": "Request flow",
+    "description": "A request moves from intake to a verified completion.",
+    "readingOrder": ["request", "completion", "start", "request-to-completion", "finish"]
+  }
+}
+```
+
+The CLI supplies `kind`, schema and protocol versions, digest settings, the
+document digest, and any omitted semantic collections. Include only primitives
+allowed by the selected grammar. Every relation endpoint, collection member,
+emphasis target, and accessibility reading-order entry must reference an item
+ID in the document. IDs use lowercase letters, numbers, and hyphens. Express
+meaning only; never add renderer coordinates.
+
+Use the `emphasis` collection when an item needs primary or secondary visual
+priority. `highlight` is not a diagram-document field. The renderer must either
+represent every declared semantic primitive or mark the quality report invalid;
+never remove groups, lanes, axes, annotations, or emphasis while reporting a
+presentable result.
+
+For a sequence diagram, use nodes as participants, relations as time-ordered
+messages, and events as named phases. After participant IDs, interleave phase
+event IDs and message relation IDs in `accessibility.readingOrder`. That order
+is the canonical timeline used by the renderer and editable projections.
+
+Write the draft to `<slug>.planr-diagram.json`, then run:
+
+```sh
+planr diagram render <slug>.planr-diagram.json --json
+```
+
+If validation fails, use the returned diagnostics to correct the draft. Do not
+open internal package code to interpret a public validation error.

package/lib/host-packages/cursor/openplanr/rules/planr-diagram/references/diagram-fidelity.md

@@ -0,0 +1,19 @@
+# Diagram fidelity and editable sources
+
+Use this reference when the user requests Mermaid or Excalidraw editing, imports
+an existing source, or asks why a projection was omitted.
+
+- Canonical `.planr-diagram.json` is the semantic source and is always editable.
+- Mermaid is emitted only when the selected grammar has a certified projection.
+  `editable`, `partial`, and `unsupported` are honest compatibility levels, not
+  success or failure labels.
+- Excalidraw is emitted only for grammars with a certified native scene
+  projection. Free-form scene edits become scene-owned pixels and do not imply
+  semantic round-trip equivalence.
+- SVG, PNG, and HTML are render outputs. They are not canonical sources.
+- When multiple source branches changed, show the runtime's choices and let the
+  user select `ir`, `mermaid`, `excalidraw`, or a new slug.
+
+Use the command envelope's fidelity and omission reasons verbatim enough to
+preserve their meaning; do not promise lossless conversion that the registry
+does not certify.

package/lib/host-packages/cursor/openplanr/rules/planr-diagram/references/diagram-intent-to-ir.md

@@ -0,0 +1,22 @@
+# English intent to canonical diagram IR
+
+Use this reference only when turning natural-language intent into a Protocol 1.6
+`planr-diagram` document.
+
+1. Identify the audience, the question the visual must answer, and the semantic
+   relationships that must remain visible.
+2. Use `planr diagram gallery --json` to select the narrowest grammar that
+   represents those relationships. Prefer an explicit user choice over an
+   inferred one.
+3. Choose `simplified`, `balanced`, or `faithful` detail from the requested use:
+   quick explanation, normal engineering communication, or complete source
+   coverage. Split the diagram when the runtime quality result requires it.
+4. Express meaning with semantic nodes, relations, groups, lanes, events,
+   series, axes, sets, annotations, and emphasis. Never invent renderer
+   coordinates; the runtime owns geometry.
+5. Provide a useful accessible title, description, and semantic reading order.
+   Keep labels concise enough to scan at the target size.
+
+Ask a question only if selecting a different answer would change the grammar,
+meaning, or audience. Infer presentation details from context and let the
+runtime validate them.

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

@@ -0,0 +1,64 @@
+---
+description: "Create, inspect, verify, or rerender professional offline diagrams. Use for architecture, process, sequence, data, state, or relationship visuals from intent or source."
+alwaysApply: false
+---
+
+# Planr Diagram
+
+Use the public `planr diagram` surface for deterministic validation, rendering,
+fidelity reporting, and source custody. Do not reproduce renderer or manifest
+logic in the prompt.
+
+Treat a successful `planr diagram gallery --json` call as proof that the runtime
+is ready. Never locate or import `planr-pipeline`, inspect `node_modules`, search
+the filesystem for schemas or examples, or call internal runtime modules. The
+CLI and this skill's bundled references are the complete supported boundary.
+
+## Create from intent
+
+When the input is an English description, read the
+[intent-to-IR guide](references/diagram-intent-to-ir.md) and the
+[diagram document contract](references/diagram-document.md).
+Choose the grammar and detail tier from the available project context. Use
+`planr diagram gallery --type <type> --json` only when grammar metadata is
+needed. Ask only
+when an unresolved choice would materially change the meaning; ask no more than
+three short decision-changing questions at once and prefer the host's native
+question UI. Write one digestless Protocol 1.6 diagram draft from the bundled
+contract, then run the command below. The CLI validates it and adds the
+canonical digest; the skill must not calculate that digest itself.
+
+```sh
+planr diagram render <file>.planr-diagram.json --json
+```
+
+For Mermaid input, pass the `.mmd` file directly. An edited Excalidraw scene is
+a source branch of an existing generated set; rerender its manifest with
+`--accept excalidraw` when the user chooses that branch.
+
+## Inspect and revise
+
+- `planr diagram inspect <input-or-manifest> --json` explains the current source,
+  outputs, editability, fidelity, and drift without changing files.
+- `planr diagram check <input-or-manifest> --json` verifies schema and manifest
+  custody.
+- `planr diagram rerender <manifest> --accept ir|mermaid|excalidraw --json`
+  regenerates from the selected source branch.
+- `planr diagram gallery [--type <type>] --json` lists grammars, aliases,
+  primitives, and layout families. Read the
+  [fidelity guide](references/diagram-fidelity.md) when choosing an editable
+  projection or explaining an omitted one.
+
+After a successful render or rerender, run the returned `nextAction` to start
+the native diagram studio (one SVG canvas, outline, pan/zoom, comments, and
+exports). Keep that process alive, wait for its startup
+JSON, open the returned URL with the host's native preview, and return the URL
+to the user. Skip this only when the user explicitly requests files without a
+preview or the host cannot open local URLs; in that case return the exact
+self-contained HTML and manifest paths. The manifest is the studio input so
+review pins remain bound to the verified diagram set. Treat an omitted Mermaid
+or Excalidraw projection as a supported fidelity outcome only when the command
+result explains why.
+
+Report the selected grammar, manifest path, emitted files, validation status,
+editable source, fidelity or omissions, and the clearest next action.

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

@@ -0,0 +1,106 @@
+# Driving an OpenPlanr upgrade
+
+`planr doctor` diagnoses; this reference is how to *act* once the tuple has
+drifted. An OpenPlanr install is several moving parts across two package
+managers — the npm CLI and the host plugins. `planr` can upgrade the npm half
+itself, but a CLI cannot install a host plugin. So the CLI does the half it owns
+and hands back the exact commands for the half it cannot; this skill runs them
+inside the host 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. This is the same staleness a generated
+mirror suffers, applied to a command contract; the CLI renders the list from the
+plugin integration's own operation set precisely so it cannot diverge.
+
+## 1. Decide whether to act
+
+```bash
+planr upgrade status --json
+```
+
+Shape (the fields this skill reads):
+
+```json
+{
+  "status": "upgrade-available",
+  "installed": { "cli": "1.22.0", "skills": "1.22.0", "pipeline": "0.38.0" },
+  "published": {
+    "cli": { "version": "1.23.0" },
+    "skills": { "version": "1.23.0" },
+    "pipeline": { "version": "0.39.0" }
+  },
+  "ecosystemSource": "network"
+}
+```
+
+- `aligned` or `unknown` → 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.
+
+## 2. Perform the owned half and obtain the prescription
+
+The plugin commands are rendered by the CLI, from the plugin integration's own
+operation list, so they always match what an install would really run. 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:
+
+```json
+{
+  "ok": true,
+  "cliUpgraded": true,
+  "installedVersion": "1.23.0",
+  "changelogBullets": ["…"],
+  "pluginHalfCommands": [
+    "<marketplace-refresh — always position 0>",
+    "<update the OpenPlanr skill plugin>",
+    "<update the planr-pipeline plugin>"
+  ]
+}
+```
+
+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.** 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.
+
+## 3. Execute the plugin half, refresh first
+
+Run each entry of `pluginHalfCommands` verbatim, top to bottom, with your shell
+tool. Two invariants:
+
+- **Refresh is position 0 and runs first.** The first entry refreshes the plugin
+  marketplace metadata. 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.
+
+## 4. Verify, then report what actually changed
+
+```bash
+planr upgrade status --json
+```
+
+Compare the new `installed` block against the before state you recorded, and
+report the real difference — per component, old → new:
+
+```
+CLI       1.22.0 → 1.23.0   moved
+skills    1.22.0 → 1.23.0   moved
+pipeline  0.38.0 → 0.38.0   unchanged — still stale
+```
+
+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.

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

@@ -0,0 +1,39 @@
+---
+description: "Diagnose OpenPlanr CLI, pipeline, runtime-adapter, installation, and lock health. Use when setup, discovery, versions, generated assets, or runtime behavior seems wrong."
+alwaysApply: false
+---
+
+# Planr Doctor
+
+Run `planr doctor` with the requested flags. Prefer `--json` for diagnosis.
+Preview every repair; package installation, version changes, provenance recovery,
+and deletion always require explicit confirmation.
+
+## Driving an upgrade
+
+`planr` owns only half of an OpenPlanr upgrade — the npm CLI. The other half, the
+host plugins, cannot be installed by a CLI; it needs a tool with host shell
+access. That is this skill's job: drive the plugin half, then report what
+actually changed — never what was merely attempted.
+
+1. **Decide.** Run `planr 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
+   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 a marketplace refresh and must run first: skip it 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
+   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.
+
+For the longer walkthrough, JSON output shape, and reporting format, read the
+[upgrade guide](references/upgrade.md).

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

@@ -0,0 +1,31 @@
+---
+description: "Diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. Use for root-cause investigation, not planned feature delivery."
+alwaysApply: false
+---
+
+# Planr Investigate
+
+Find the cause before proposing a fix. Use the request, repository, runtime output, and focused
+experiments as context. Keep the investigation lightweight and make every diagnostic useful to
+the requested outcome.
+
+## Investigate
+
+1. Restate the observed failure and the smallest reproducible case.
+2. Trace the relevant call path, state, configuration, and recent changes.
+3. Form competing hypotheses and run the cheapest discriminating checks first.
+4. Identify the root cause only when the observations distinguish it from plausible alternatives.
+5. Report exact errors and unavailable tools without prescribing a workflow ceremony.
+
+## Fix when requested
+
+When the user asked for a fix, implement the smallest coherent correction within the requested
+repository and run focused regression checks. Preserve unrelated work. Ask only when a missing
+product decision or an irreversible external action genuinely blocks progress.
+
+## Return
+
+- **Cause:** established root cause, or the strongest remaining hypotheses.
+- **Change:** files and behavior changed, or none for diagnosis-only work.
+- **Checks:** commands and results.
+- **Issues:** unresolved uncertainty or blocker, or none.