openplanr 1.25.3 → 2.0.1

package/lib/host-packages/openai/openplanr/skills/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/openai/openplanr/skills/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/openai/openplanr/skills/diagram/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: diagram
+description: Create, inspect, verify, or rerender professional offline diagrams. Use for architecture, process, sequence, data, state, or relationship visuals from intent or source.
+license: MIT
+---
+
+# 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/openai/openplanr/skills/diagram/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Planr Diagram"
+  short_description: "Create, inspect, verify, or rerender professional offline…"
+  default_prompt: "Use $planr:diagram to create, inspect, verify, or rerender professional offline diagrams. Use for architecture, process, sequence, data, state, or relationship visuals from intent or source."
+policy:
+  allow_implicit_invocation: true

package/lib/host-packages/openai/openplanr/skills/diagram/openplanr.skill.json

@@ -0,0 +1,59 @@
+{
+  "kind": "openplanr-skill-package",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.8.0",
+  "skillId": "planr-diagram",
+  "skillVersion": "1.0.0",
+  "entrypoint": "SKILL.md",
+  "hosts": [
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "cursor"
+  ],
+  "execution": "host-agent",
+  "resources": [
+    {
+      "path": "agents/openai.yaml",
+      "kind": "agent-metadata",
+      "hosts": [
+        "codex",
+        "chatgpt"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/diagram-document.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/diagram-fidelity.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/diagram-intent-to-ir.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    }
+  ]
+}

package/lib/host-packages/openai/openplanr/skills/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/openai/openplanr/skills/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/openai/openplanr/skills/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/openai/openplanr/skills/doctor/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: doctor
+description: Diagnose OpenPlanr CLI, pipeline, runtime-adapter, installation, and lock health. Use when setup, discovery, versions, generated assets, or runtime behavior seems wrong.
+license: MIT
+---
+
+# 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/openai/openplanr/skills/doctor/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Planr Doctor"
+  short_description: "Diagnose OpenPlanr CLI, pipeline, runtime-adapter, installation…"
+  default_prompt: "Use $planr:doctor to diagnose OpenPlanr CLI, pipeline, runtime-adapter, installation, and lock health. Use when setup, discovery, versions, generated assets, or runtime behavior seems wrong."
+policy:
+  allow_implicit_invocation: true

package/lib/host-packages/openai/openplanr/skills/doctor/openplanr.skill.json

@@ -0,0 +1,37 @@
+{
+  "kind": "openplanr-skill-package",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.8.0",
+  "skillId": "planr-doctor",
+  "skillVersion": "1.0.0",
+  "entrypoint": "SKILL.md",
+  "hosts": [
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "cursor"
+  ],
+  "execution": "host-agent",
+  "resources": [
+    {
+      "path": "agents/openai.yaml",
+      "kind": "agent-metadata",
+      "hosts": [
+        "codex",
+        "chatgpt"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/upgrade.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    }
+  ]
+}

package/lib/host-packages/openai/openplanr/skills/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/openai/openplanr/skills/investigate/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: investigate
+description: "Diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. Use for root-cause investigation, not planned feature delivery."
+---
+
+# 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.

package/lib/host-packages/openai/openplanr/skills/investigate/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Planr Investigate"
+  short_description: "Diagnose a bug, regression, error, or unexplained behavior and…"
+  default_prompt: "Use $planr:investigate to diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. Use for root-cause investigation, not planned feature delivery."
+policy:
+  allow_implicit_invocation: true

package/lib/host-packages/openai/openplanr/skills/investigate/openplanr.skill.json

@@ -0,0 +1,26 @@
+{
+  "kind": "openplanr-skill-package",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.8.0",
+  "skillId": "planr-investigate",
+  "skillVersion": "2.0.0",
+  "entrypoint": "SKILL.md",
+  "hosts": [
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "cursor"
+  ],
+  "execution": "host-agent",
+  "resources": [
+    {
+      "path": "agents/openai.yaml",
+      "kind": "agent-metadata",
+      "hosts": [
+        "codex",
+        "chatgpt"
+      ],
+      "executable": false
+    }
+  ]
+}