openplanr 1.25.3 → 2.0.1

package/lib/host-packages/cursor/openplanr/rules/planr-plan/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-plan/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-plan-review.mdc

@@ -0,0 +1,38 @@
+---
+description: "Review an OpenPlanr plan for product, engineering, design, and developer-experience problems. Use after planning and before implementation to improve the plan."
+alwaysApply: false
+---
+
+# Planr Plan Review
+
+Give the plan a senior, practical review. Read the plan, its repository context,
+and the decisions it depends on. Use only the review lenses relevant to the
+work; do not manufacture a fixed committee.
+
+## Review
+
+- Check that the outcome and user value are clear and measurable.
+- Check scope, sequencing, ownership, architecture, migration, security,
+  operability, testing, and rollback in proportion to the change.
+- Check the first-run and everyday developer experience, including setup,
+  diagnostics, defaults, and recovery.
+- Prefer concrete corrections over abstract criticism. Name the affected plan
+  section and the change that would resolve each material issue.
+- Use subagents or tools when they improve the review, but return one coherent
+  result rather than their raw transcripts.
+
+Ask through the host's native structured question UI only when a missing answer
+would materially change the review. Otherwise state the assumption and continue.
+
+## Output
+
+Lead with one verdict: `ready`, `ready with improvements`, or `needs revision`.
+Then report:
+
+1. Must fix — only issues that would make the implementation wrong or unsafe.
+2. Improvements — worthwhile changes that are not blockers.
+3. Decisions and assumptions — unresolved choices with a recommended default.
+4. Next action — the smallest useful next step.
+
+Return the useful findings directly. Revisit the review when the user asks or
+the plan materially changes.

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

@@ -0,0 +1,105 @@
+---
+description: "Turn a Protocol-compatible specification or product intent into schema-compatible OpenPlanr stories and implementation tasks. Use for planning and decomposition, not implementation."
+alwaysApply: false
+---
+
+# Planr Plan
+
+Turn a decision-complete specification or clear product request into
+implementation-ready stories and tasks. Perform the reasoning in this active
+coding session. Do not delegate semantic planning to a command-line or model
+subprocess. Plan ends with a Ship handoff; it never starts implementation
+automatically.
+
+## Resolve context directly
+
+Read the strongest available inputs:
+
+1. the request and selected specification;
+2. repository instructions (`AGENTS.md`, `CLAUDE.md`, or equivalents), ADRs,
+   planning rules, and active stack files named by the repository;
+3. relevant implementation code, tests, package scripts, and CI configuration;
+4. design inputs and design specifications when a browser surface is involved;
+5. the database schema or persistence code when data behavior is involved.
+
+Use repository-local conventions first. Missing legacy `input/` or `.planr/`
+paths do not block a clear request. State what was unavailable and continue when
+the remaining context is sufficient.
+
+For a completed Design handoff, read `design-document.json`, the selected
+direction, and the authored ten-section `design-spec.md`. The specification lives
+inside `design/` in spec-driven mode and beside `design/` in default feature mode.
+For a studio-backed design, read its `.design/studio-state.json`: the recorded
+`selectedVariant` is authoritative. Verify that the authored document and the
+specification describe that same direction before decomposing UI work. If they
+disagree, synchronize the design handoff using the settled choice or report the
+specific unsynced inputs; do not silently plan the original preview direction.
+Use stable screen IDs, component recipes, responsive frames, and interaction
+flows as UI-task context. Read the current render's verification result and
+unresolved feedback; carry relevant gaps into explicit task checks. Preserve
+`finalized.json` compatibility inputs for older designs. Do not regenerate an
+existing design or re-extract an authored specification from preview images.
+
+When `review-handoff.json` is present beside `design-spec.md`, read its current
+approval and freshness with the bundled
+`node scripts/design.mjs handoff <design-document.json> --action inspect --json`. Use approved, current
+handoff items as additional planning context, retaining revision/comment links and
+unresolved questions. An outdated or unapproved draft is evidence, not agreed scope;
+report the changed inputs and obtain the missing decision only when it affects the
+requested plan. Never silently substitute a newer draft for an approved snapshot.
+A missing review handoff does not block ordinary planning from a clear specification.
+
+For a consequential unresolved choice, use the host's structured question
+interface. Ask at most three short, mutually exclusive questions at once. If the
+host has no structured question interface, ask one concise chat question.
+
+## Apply PO lenses in-session
+
+When the host supports native agents, dispatch the applicable database,
+designer, and specification roles inside this session. Give each role the
+request, repository root, relevant paths, and the precise decision or artifact
+it owns. Parallelize independent lenses. When native agents are unavailable,
+perform the same lenses sequentially in the active agent.
+
+The specification role integrates the results. Database and design roles
+provide grounded inputs; they do not create a second independent plan.
+
+## Author the decomposition
+
+Read [the artifact contract](references/artifact-contract.md) before writing.
+Write stories and tasks directly in the repository's active planning mode.
+
+- Allocate project-global monotonic `US-NNN` and `T-NNN` IDs. Never reuse a
+  deleted ID. The packaged [planning ID helper](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.
+- 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
+  arrays when no signal applies.
+- Set `dependsOn` only when a task consumes another task's output. File overlap,
+  numbering, and prose never create a semantic dependency.
+- Name concrete files and repository-grounded checks. Preserve established
+  repository headings when they carry additional information.
+
+Validate all frontmatter and acceptance coverage before finishing. If a helper
+is unavailable, inspect existing IDs and validate the same invariants directly;
+do not route semantic work to a CLI fallback.
+
+## Return
+
+- **Outcome:** what is implementation-ready.
+- **Mode:** the planning layout used.
+- **Inputs:** repository context and role lenses used.
+- **Artifacts:** every story and task path.
+- **Issues:** only unresolved inputs or material assumptions, or `none`.
+- **Next:** the exact ready task selector and a copy-ready host-native
+  invocation such as `$planr-ship T-NNN` (Codex/ChatGPT) or
+  `/planr-ship T-NNN` (Claude Code).
+
+When the OpenPlanr dashboard is running, the planned graph is browsable at
+`#/board`; open one story at `#/detail/<US-###>`.
+
+Stop after the handoff.

package/lib/host-packages/cursor/openplanr/rules/planr-release/assets/changelog-template.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable user-facing changes to this project are recorded here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning: <scheme, per .release/profile.md>.
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+## [1.0.0] - <DATE>
+
+Initial release.

package/lib/host-packages/cursor/openplanr/rules/planr-release/assets/profile-template.md

@@ -0,0 +1,45 @@
+# Release profile: <PRODUCT NAME>
+
+Written on <DATE>. Update when the product's audience or surface changes,
+not on every release.
+
+## Scheme
+
+**Scheme:** <SemVer | CalVer YYYY.MM.PATCH | other>
+**Why:** <one or two sentences tying the choice to who reads the number and
+what question they are asking>
+
+## Public surface
+
+The list of things a breaking change can happen to. Anything not listed here
+can change in a patch.
+
+- <e.g. documented HTTP endpoints under /api/v1>
+- <e.g. webhook payload shapes>
+- <e.g. the booking flow URLs users bookmark>
+- <e.g. exported types from the package entrypoint>
+
+## Second version line
+
+**Applies:** <yes | no>
+**If yes:** <what it covers, which scheme, where it is declared>
+
+## Cadence
+
+**Regular cut:** <e.g. weekly, Wednesday>
+**Fixes:** <e.g. shipped immediately as patches>
+**Breaking changes:** <e.g. announced 14 days ahead, shipped alone>
+**Freezes:** <e.g. none | client demo weeks | December>
+
+## Tooling
+
+**Version bump:** <e.g. pnpm changeset version | npm version>
+**Tag format:** <e.g. v1.4.0 | 2026.09.1>
+**Changelog:** <path, e.g. CHANGELOG.md, Keep a Changelog format>
+
+## Voice
+
+**Audience:** <who reads the notes>
+**Product vocabulary:** <UI terms that must be used verbatim, and the internal
+names that must never appear>
+**Channels:** <CHANGELOG.md | in-product what's new | email | GitHub releases>

package/lib/host-packages/cursor/openplanr/rules/planr-release/references/cadence.md

@@ -0,0 +1,92 @@
+# Cadence, hotfixes, and recovery
+
+Contents:
+1. Deploys are not releases
+2. The Unreleased section
+3. Picking a rhythm
+4. Hotfixes
+5. When a release goes out wrong
+6. Freezes and quiet periods
+
+---
+
+## 1. Deploys are not releases
+
+A deploy puts code in production. A release is a named, dated, described unit that users and support can refer to. Conflating them is what makes high-frequency shipping incompatible with meaningful versions.
+
+Deploy continuously. Release on a rhythm. The version number then marks a point people can talk about ("this started in 2026.09.2") rather than incrementing invisibly forty times a week.
+
+The one exception is a product whose users genuinely track every deploy, which in practice means developer tooling with a public build feed. Almost nothing else qualifies.
+
+---
+
+## 2. The Unreleased section
+
+This is the mechanism that makes weekly releases cheap.
+
+Keep this at the top of `CHANGELOG.md` at all times:
+
+```markdown
+## [Unreleased]
+
+### Added
+- Entry written when the work merged, while it was still fresh.
+```
+
+Append to it as work merges, in user-facing language, not commit language. Cutting a release then becomes: rename the heading to the version and date, open a fresh empty `## [Unreleased]`, tag.
+
+The reason this is worth the discipline: reconstructing user intent from commit messages a week later is slow and lossy. The person who wrote the feature knows what it does for users on the day they merged it, and nobody knows it as well again.
+
+If the section was not maintained, fall back to collecting from git plus the user's summary. Expect gaps and ask about them explicitly.
+
+---
+
+## 3. Picking a rhythm
+
+**Daily releases.** Suits internal tools and early products with a small user base and fast feedback. CalVer `YYYY.MM.DD` fits naturally. Cost: notes get thin, and users tune out. Mitigate by skipping in-product announcements for most days and batching the announcement weekly even when the versions are daily.
+
+**Weekly.** The default for most products. Cut on a fixed day, ideally Tuesday or Wednesday. Not Friday: nobody wants to discover a bad release on a Saturday, and the person who can fix it is unreachable. Not Monday: it forces weekend work to prepare.
+
+**Twice weekly.** Works when feature flow is steady and fixes are frequent. Practical split: features on the fixed day, fixes whenever ready.
+
+**Monthly or slower.** Only where consumers bear real upgrade cost, typically libraries and on-prem software. For a hosted product, monthly releases usually mean the notes go unread because too much accumulated.
+
+Whatever the rhythm, keep the day fixed. Predictability is most of the value: support knows when to expect change, and users learn when to look.
+
+---
+
+## 4. Hotfixes
+
+A hotfix is a fix that cannot wait for the next scheduled release because users are currently blocked or losing data.
+
+Process:
+
+1. Cut it as a patch off the current release, not off main, if main has unreleased work in it. Shipping unrelated half-finished changes alongside an urgent fix is how a small incident becomes a large one.
+2. One line in the notes, describing the symptom.
+3. Tag it. A hotfix that never gets a version number is invisible to support later, when someone asks whether a given user had the fix.
+
+Do not batch hotfixes. The batching instinct is what turns a fifteen minute fix into a two hour release.
+
+---
+
+## 5. When a release goes out wrong
+
+**Never delete or move a published tag.** Anything that consumed it will silently disagree with anything that consumes it later, and that class of bug is miserable to diagnose.
+
+Instead:
+
+- Roll forward with a new patch version wherever possible. It preserves the history and is faster than a rollback in most deployment setups.
+- If the release must be pulled (a published package, a broken migration), publish a new version and mark the bad one deprecated through the registry's own mechanism. Add a changelog entry saying it was withdrawn and why. Users who already installed it need to know.
+- Correct the changelog by adding a note, not by rewriting history. A changelog that gets quietly edited stops being evidence.
+
+---
+
+## 6. Freezes and quiet periods
+
+Worth declaring in the profile if they apply:
+
+- Around a launch, a demo, or a client-facing event, hold non-urgent releases. Fixes still ship.
+- Around holidays, avoid shipping anything breaking when the people who would field the fallout are away.
+- If the product serves businesses with their own peak periods, avoid their peak. A booking product should not ship a breaking change into a salon's Saturday.
+
+A freeze is a schedule decision, not a code freeze. Work continues and accumulates in `Unreleased`.

package/lib/host-packages/cursor/openplanr/rules/planr-release/references/release-notes.md

@@ -0,0 +1,127 @@
+# Writing user-facing release notes
+
+Contents:
+1. Who is reading
+2. Voice rules
+3. Worked rewrites
+4. Handling breaking changes
+5. Section ordering and grouping
+6. Channel formats
+7. What to leave out
+
+---
+
+## 1. Who is reading
+
+Someone who uses the product, has a limited budget of attention for it, and is scanning for one of three things: did the thing that annoyed me get fixed, can I now do something I could not before, and do I have to change anything.
+
+Everything below follows from that. The reader does not care which service was refactored, and will never read a sentence that opens with "we".
+
+---
+
+## 2. Voice rules
+
+**Lead with the user's new capability, not the implementation.** The subject of the sentence should be the thing they can do or the thing that now works, not the code that was written.
+
+**Use the product's own vocabulary.** If the UI says "Availability", the notes say Availability, not `schedule_slots` and not "the calendar module". A reader who cannot map an entry to something they can see on screen will skip it.
+
+**Describe fixes by symptom.** The reader recognizes the symptom, because they experienced it. They have no way to recognize the cause.
+
+**One line per entry.** If an entry genuinely needs more, write one line and link to a doc. Multi-paragraph entries mean the section is being used as a blog post.
+
+**Second person, present tense.** "You can now export" over "users are now able to export".
+
+**No em dashes.** Use a colon, a comma, or two sentences.
+
+**No filler openers.** Cut "we're excited to announce", "as always", "in this release we've been hard at work". The reader is scanning, and every filler word costs them.
+
+**No hedging on fixes.** "Fixed an issue where some users may have occasionally experienced" is four qualifiers protecting the writer at the reader's expense. It broke, it is fixed, say so.
+
+---
+
+## 3. Worked rewrites
+
+**Feature**
+- Before: `feat(booking): implement recurring slot generation with rrule parsing`
+- After: `Set a session to repeat weekly or monthly instead of creating each one by hand.`
+
+**Feature, buried in implementation**
+- Before: `Migrated the availability resolver to a new interval-tree lookup, improving query performance.`
+- After: `Availability now loads instantly, even on calendars with hundreds of sessions.`
+
+**Fix, described by cause**
+- Before: `Fixed a race condition in the webhook handler's idempotency check.`
+- After: `Payments confirmed twice in quick succession no longer create duplicate bookings.`
+
+**Fix, over-hedged**
+- Before: `Resolved an issue where some users may have intermittently seen incorrect timezone offsets in certain edge cases.`
+- After: `Session times now show in your local timezone after travelling between regions.`
+
+**Improvement, too vague to be worth printing**
+- Before: `Various performance improvements and bug fixes.`
+- After: either name what got faster and what got fixed, or cut the line entirely. This sentence has never informed anyone.
+
+**Breaking change, softened into invisibility**
+- Before: `Updated the booking API response format for consistency.`
+- After: `The booking API now returns `startsAt` instead of `start_time`. Update your integration before 15 October, when the old field is removed.`
+
+**Internal work that should not appear at all**
+- Before: `Upgraded Prisma to 6.2, refactored the seed script, added integration tests for the payout flow.`
+- After: nothing. None of this is observable. Track it in commits.
+
+---
+
+## 4. Handling breaking changes
+
+A breaking change entry needs four things in one or two lines: what changed, what breaks, what to do, and by when.
+
+```
+### Removed
+- The `/v1/sessions/list` endpoint is gone. Use `/v1/sessions` with the `status`
+  filter, which returns the same records. See the migration guide: <link>
+```
+
+Rules:
+
+- Put it first, before Added. The reader who stops after three lines must have seen it.
+- Never bundle it into a list of unrelated improvements. It gets its own section and, where possible, its own release.
+- A changelog entry is not sufficient notice on its own. Anything with an integration cost also needs an in-product notice or a direct message to affected users, because most people do not read changelogs.
+- State the date, not "soon".
+
+---
+
+## 5. Section ordering and grouping
+
+Use Keep a Changelog headings so the format is recognizable and tooling can parse it: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
+
+Order by cost of missing it:
+
+1. `Removed` and breaking items in `Changed`
+2. `Security`
+3. `Added`
+4. `Changed`
+5. `Deprecated`
+6. `Fixed`
+
+Omit any section with nothing in it. Never write "N/A" or "No changes".
+
+If a release has more than about ten entries in one section, group by product area with bold sublabels. Past that length the flat list stops being scannable, which defeats the purpose.
+
+---
+
+## 6. Channel formats
+
+The same release, adapted per channel. Do not paste the changelog everywhere.
+
+- **CHANGELOG.md**: the full record. Every user-visible change, versioned and dated, never edited retroactively except to correct an error.
+- **In-product "what's new"**: the top three entries, plain language, linked to the feature. Skip patch releases entirely; interrupting users for a bug fix trains them to dismiss the panel.
+- **Email or announcement**: only for features worth an interruption, and for breaking changes. One feature per email beats a digest nobody finishes.
+- **Git tag annotation or GitHub release**: the changelog section verbatim, plus the compare link.
+
+---
+
+## 7. What to leave out
+
+Refactors, test coverage, CI changes, dependency bumps without behavior change, formatting, internal renames, infrastructure moves that users cannot detect, and anything gated behind a flag that is still off.
+
+That last one matters at high cadence: code merged behind a disabled flag has not shipped. It belongs in the release where the flag turns on, described from the user's side. Announcing it early produces notes that reference features nobody can find.