openplanr 3.4.0 → 3.6.0

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

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-ship",
-  "skillVersion": "1.6.0",
+  "skillVersion": "1.8.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",
@@ -45,18 +45,18 @@
       "executable": false
     },
     {
-      "path": "scripts/discover-verification.mjs",
-      "kind": "script",
+      "path": "references/fail-first.md",
+      "kind": "reference",
       "hosts": [
         "claude-code",
         "codex",
         "chatgpt",
         "cursor"
       ],
-      "executable": true
+      "executable": false
     },
     {
-      "path": "references/fail-first.md",
+      "path": "references/findings.md",
       "kind": "reference",
       "hosts": [
         "claude-code",
@@ -67,7 +67,7 @@
       "executable": false
     },
     {
-      "path": "references/findings.md",
+      "path": "references/backlog-filing.md",
       "kind": "reference",
       "hosts": [
         "claude-code",
@@ -78,15 +78,15 @@
       "executable": false
     },
     {
-      "path": "scripts/backlog-item.mjs",
-      "kind": "script",
+      "path": "references/return-contract.md",
+      "kind": "reference",
       "hosts": [
         "claude-code",
         "codex",
         "chatgpt",
         "cursor"
       ],
-      "executable": true
+      "executable": false
     }
   ]
 }

package/lib/host-packages/openai/openplanr/skills/ship/references/backlog-filing.md

@@ -0,0 +1,102 @@
+# Backlog filing
+
+List and file backlog items with your own file tools. If `openplanr` is already on
+`PATH`, you may instead send each item as one JSON object on stdin to
+`openplanr --project-dir <repository-root> backlog add --data - --json`.
+
+## Where items live
+
+1. Read `.planr/config.json` at the repository root. If it is missing or is not
+   valid JSON, stop and report that the project has no OpenPlanr configuration.
+2. The backlog folder is `<outputPaths.agile>/backlog`, with `outputPaths.agile`
+   defaulting to `.planr`. The ID prefix is `idPrefix.backlog`, default `BL`.
+3. Issued IDs are empty marker files in `<backlog folder>/.issued-ids/`.
+
+## List open items
+
+List the files named `<PREFIX>-NNN-<slug>.md` in the backlog folder and read each
+frontmatter's `id`, `title` and `status`. An item is open unless its `status` is
+`closed` or `done`; a missing `status` counts as open.
+
+## Take an ID
+
+Do this immediately before writing each item, never earlier in the run:
+
+1. List the backlog folder and `.issued-ids/` again; create `.issued-ids/` if it is
+   missing.
+2. Find the highest `<PREFIX>-NNN` number among the file names in both. The new
+   number is that plus 1, or 1 when there is none, padded to at least 3 digits
+   (`BL-007`, `BL-1000`).
+3. Claim it by creating the empty file `.issued-ids/<ID>`. In a POSIX shell use a
+   no-clobber create, `(set -C; : > '<backlog folder>/.issued-ids/<ID>')`, or
+   elsewhere any create that fails when the file already exists, and treat a
+   failure as the ID being taken.
+4. If the marker already existed or any `<ID>-*.md` file exists, take the next
+   number and repeat step 3.
+
+Never overwrite or edit an existing backlog file or marker. A marker outlives its
+item, so the ID of a deleted item is never issued again.
+
+## Write the item
+
+Name the file `<ID>-<slug>.md` in the backlog folder. The slug is the title in
+lowercase with every character other than ASCII letters, digits, `_`, `-` and
+whitespace removed, runs of whitespace, `_` and `-` turned into one `-`, and
+leading or trailing `-` removed. When it is longer than 80 characters, cut it at 80, then back to the last
+`-`.
+
+The frontmatter needs every field below. Scalar values are double-quoted JSON strings;
+arrays use the flow form shown in the example:
+
+- `id`: the claimed ID.
+- `title`: one line.
+- `priority`: `critical`, `high`, `medium` or `low`.
+- `tags`: a list of quoted strings, `[]` when there are none.
+- `status`: `"open"`.
+- `created` and `updated`: today's date as `YYYY-MM-DD`.
+- `when`: `next-unit:<ref>`, `sprint:<SPRINT-NNN or next>`, `trigger:<event>`, or
+  `declined:<reason>`. Use a PR number, task ID, backlog ID, or branch for `<ref>`.
+  Never store `now`; it is a triage outcome. Trigger forms include
+  `date:YYYY-MM-DD`, `closed:<BL-NNN>`, `merged:#<PR>`, `merged:<branch>`, and
+  `release:<pkg>@<semver>`; other non-empty event text is allowed.
+- `files`: a list of quoted repo-relative paths, such as `["src/routes/import.ts"]`.
+  Omit line numbers, absolute paths and `..` segments. Use distinct paths from
+  the evidence, or `[]` when there are none.
+
+Older items may omit `when` and `files`. When listing them, derive files from
+body evidence such as `src/routes/import.ts:41` only if `files` is absent.
+
+The body is `# <ID>: <title>`, then `## Tags` with one `- <tag>` line per tag
+(omitted when there are none), then the description. A description that starts
+with its own `##` sections stands as written; otherwise it goes under
+`## Description`. End with a `---` line and the close line.
+
+```markdown
+---
+id: "BL-007"
+title: "Import endpoint has no rate limit"
+priority: "medium"
+tags: ["security", "api"]
+status: "open"
+created: "2026-11-08"
+updated: "2026-11-08"
+when: "next-unit:#612"
+files: ["src/routes/import.ts"]
+---
+
+# BL-007: Import endpoint has no rate limit
+
+## Tags
+
+- security
+- api
+
+## Problem
+
+`/import` accepts unlimited requests (`src/routes/import.ts:41`).
+
+---
+_Close when done: `openplanr backlog update BL-007 --status closed`_
+```
+
+Report the ID and the repo-relative path of each filed item.

package/lib/host-packages/openai/openplanr/skills/ship/references/findings.md

@@ -31,9 +31,8 @@ Merge duplicates within the run. Sort by severity, highest first, and number fro
 
 ## Check what is already tracked
 
-Before showing findings, list open backlog items with the backlog helper
-linked from SKILL.md, resolved relative to that file: `node <helper> list
---project <repository-root> --open`. A finding about the same problem as an open item,
+Before showing findings, list open backlog items as
+[backlog filing](backlog-filing.md) describes. A finding about the same problem as an open item,
 normally the same evidence file and an equivalent title, is `tracked`. Never file
 it again and never edit the existing item.
 
@@ -52,26 +51,19 @@ rule that applies. File only what it allows.
    example a print or exec mode), another skill or a delegate runner started this
    run, or the user said not to ask. Read `findings.unattended` in
    `.planr/config.json`. Only `file` files every untracked finding. With
-   `report`, or no setting, do not run `add` at all: mark the findings `reported`.
+   `report`, or no setting, do not file at all: mark the findings `reported`.
 
 Never ask per finding, never ask mid-run, and never file or drop a finding
 silently.
 
 ## File
 
-Send each item as one JSON object (`title`, `priority`, `tags`, `description`)
-on stdin. Never pass `acceptanceCriteria`.
+File each item from its `title`, `priority`, `tags` and `description` as
+[backlog filing](backlog-filing.md) describes. Never add acceptance criteria.
+When the `openplanr` command files it and the result says
+`templateOverrideIgnored`, say the default format was used.
 
-- When an `openplanr` CLI resolves (the project's `node_modules/.bin`, then
-  `PATH`; never `npx`): `openplanr --project-dir <repository-root> backlog add
-  --data - --json`.
-- Otherwise: `node <helper> add --project <repository-root> --data -`. Its
-  result can carry `cliHint`; end the result with that line, word for word,
-  once. Install only if the user says yes then, by running exactly the command in
-  the line. If the result says `templateOverrideIgnored`, say the default format
-  was used.
-
-If filing fails, report the command and its error, and leave the finding
+If filing fails, report the step and its error, and leave the finding
 `reported`.
 
 ## Report

package/lib/host-packages/openai/openplanr/skills/ship/references/return-contract.md

@@ -0,0 +1,10 @@
+# Return rules
+
+Shared by Spec, Plan, Plan Review, Ship, Operate and Release. Each skill lists its own fields.
+
+- Lead with the outcome: what is ready, prepared or released, then what is partial or blocked.
+- Link durable artifacts by purpose. Keep inventories, command output and transcripts in their files.
+- Report only checks you ran, with their result. Name each check you could not run and what stays unverified.
+- Omit empty fields. Give each open issue its impact and the smallest recovery action.
+- The summary is a human view, not a schema. Different wording never calls for a rerun or a correction pass.
+- Keep any machine-readable field a skill defines unchanged.

package/lib/host-packages/openai/openplanr/skills/spec/SKILL.md

@@ -12,10 +12,10 @@ another model process.
 
 ## Ground the specification
 
-Read the request, repository instructions, ADRs, product documentation,
-existing planning artifacts, relevant implementation code and tests, stack
-configuration, design inputs, database context, and current behavior. Infer
-facts the repository already answers.
+Read the files the request names, plus `AGENTS.md` and `CLAUDE.md` when tracked,
+in one batch. Expand only for a missing contract, a dependency or a contradiction,
+and stop when each claim has evidence or a named gap. Infer facts the repository
+already answers.
 
 When a missing decision materially changes scope or observable behavior, use
 the host's structured question interface. Ask no more than three short,
@@ -45,9 +45,10 @@ out-of-scope boundaries. Record concrete repository paths and verification
 signals when they are known. Keep unresolved questions out of the saved
 contract when a repository-backed default exists.
 
-Validate the completed artifact before returning. If a helper is unavailable,
-perform the same deterministic checks directly; never fall back to a
-model-backed CLI.
+Validate the completed artifact before returning: run `openplanr spec validate <SPEC-ID>`
+when `command -v openplanr` succeeds, otherwise check the path, frontmatter,
+headings and acceptance IDs against the specification contract directly. Never
+fall back to a model-backed CLI.
 
 ## Return
 
@@ -62,5 +63,4 @@ If the specification is partial or blocked, name the missing decision and its im
   none remains.
 - **Next:** a copy-ready host-native `planr-plan` invocation for the saved spec.
 
-The summary is a human view of the specification, not another schema or a reason
-to rerun a completed operation for different wording.
+Follow [the shared return rules](references/return-contract.md).

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

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-spec",
-  "skillVersion": "1.0.2",
+  "skillVersion": "1.1.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",
@@ -32,6 +32,17 @@
         "cursor"
       ],
       "executable": false
+    },
+    {
+      "path": "references/return-contract.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
     }
   ]
 }

package/lib/host-packages/openai/openplanr/skills/spec/references/return-contract.md

@@ -0,0 +1,10 @@
+# Return rules
+
+Shared by Spec, Plan, Plan Review, Ship, Operate and Release. Each skill lists its own fields.
+
+- Lead with the outcome: what is ready, prepared or released, then what is partial or blocked.
+- Link durable artifacts by purpose. Keep inventories, command output and transcripts in their files.
+- Report only checks you ran, with their result. Name each check you could not run and what stays unverified.
+- Omit empty fields. Give each open issue its impact and the smallest recovery action.
+- The summary is a human view, not a schema. Different wording never calls for a rerun or a correction pass.
+- Keep any machine-readable field a skill defines unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openplanr",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "The openplanr CLI: validates plans in your repo, lists the checks a change needs, renders diagrams, installs 25+ skills into Claude Code, Codex and Cursor, and syncs GitHub Issues and Linear. No model calls.",
   "type": "module",
   "main": "./dist/cli/index.js",
@@ -114,7 +114,7 @@
     "zod": "^4.6.7"
   },
   "optionalDependencies": {
-    "planr-pipeline": "0.62.0"
+    "planr-pipeline": "0.63.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.6.3",

package/lib/host-packages/claude/openplanr/.claude-plugin/icon.svg

@@ -1,11 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 160 160" role="img" aria-labelledby="title desc">
-  <title id="title">OpenPlanr application icon</title>
-  <desc id="desc">The Open Decision mark on a rounded near-black tile.</desc>
-  <rect width="160" height="160" rx="35" fill="#08080C"/>
-  <g transform="translate(24 24) scale(.7)">
-    <g transform="rotate(-45 80 80)">
-      <path d="M125 50A52 52 0 1 0 125 110" fill="none" stroke="#5EEAD4" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
-      <rect x="127" y="71" width="18" height="18" rx="3" fill="#5EEAD4"/>
-    </g>
-  </g>
-</svg>