openplanr 3.2.0 → 3.3.0

package/lib/host-packages/cursor/openplanr/rules/planr-design-review/references/generation.md

@@ -10,7 +10,8 @@ Use a versioned `design-document.json` and the bundled schema exposed by the
 local HTML/CSS/JavaScript, assets, screen order, responsive frames, interaction
 flows, selected direction, brief provenance and design-system references. Inspect
 the schema before creating the document; validate it before rendering. Use
-`schemaVersion: "1.0.0"` when authoring, revising, migrating or arranging documents.
+`schemaVersion: "1.1.0"` for documents with screen or variant props. Documents without
+props may keep `schemaVersion: "1.0.0"`.
 
 Read [team-review.md](team-review.md) and author a sibling `review-context.json`
 for every new design. Its welcome purpose and review questions belong to this
@@ -19,7 +20,9 @@ design, updating only what changed. Render it with the same revision as the
 screens so the shared welcome and implementation guidance describe that revision.
 
 Place source in a sibling `source/` directory. Shared CSS and components belong in
-shared source; variants write disjoint directories. Preserve IDs during evolution.
+shared source. Distinct design directions may use disjoint directories; theme,
+partial and state instances share a screen source through typed props. Preserve
+IDs during evolution.
 All document source paths are local and relative to its directory; import the
 required asset snapshots rather than referring outside it or to remote resources.
 Fonts are asset snapshots too; follow [design-system.md](design-system.md).
@@ -57,6 +60,61 @@ observable. If the requested deliverable is an architecture or decision diagram
 rather than a product interface, route that content to the diagram workflow instead
 of styling documentation as a product screen.
 
+## Typed screen props
+
+Declare reusable screen state in `screens[].props`. An enum declaration requires
+`type: "enum"`, nonempty unique string `options`, and a `default` from those options.
+A boolean declaration requires `type: "boolean"` and a boolean `default`. Prop names,
+enum options and enum defaults must be lowercase tokens matching
+`^[a-z][a-z0-9-]*$`, with at most 128 characters. Use `is-dark` and `dark-mode`,
+for example; uppercase letters, spaces and underscores are invalid. Use props for
+theme, partial content and state variants instead of copying HTML sources.
+
+Set instance values in `variants[].props`, keyed first by screen ID and then prop
+name. Omitted values use the screen defaults. For example:
+
+```json
+{
+  "schemaVersion": "1.1.0",
+  "screens": [
+    {
+      "id": "overview",
+      "title": "Overview",
+      "source": { "html": "source/overview.html" },
+      "props": {
+        "theme": { "type": "enum", "options": ["light", "dark"], "default": "light" },
+        "partial": { "type": "boolean", "default": false }
+      }
+    }
+  ],
+  "variants": [
+    { "id": "light", "label": "Light", "status": "ready" },
+    {
+      "id": "dark",
+      "label": "Dark",
+      "status": "ready",
+      "props": { "overview": { "theme": "dark", "partial": true } }
+    }
+  ]
+}
+```
+
+Each source with props needs exactly one explicit `<body>` screen root. The
+renderer writes effective values onto that body as `data-prop-theme="dark"`,
+`data-prop-partial="true"`, `prop-theme-dark` and `prop-partial-true`; false booleans
+also receive an attribute and class. Names and values are written unchanged,
+without case conversion or encoding. A prop named `is-dark` becomes
+`data-prop-is-dark="true"` and `prop-is-dark-true`; scripts read it as
+`document.body.dataset.propIsDark`. Branch CSS and local scripts on these values.
+A `variants[].sources[screenId]` override still selects the source; props
+apply to that selected source, otherwise to `screens[].source`. Board keys,
+screen order, responsive frames and existing source overrides retain their roles.
+
+Lint warns about copied screens only when their source files are byte-identical
+after removing body `data-theme="light"` or `data-theme="dark"` attributes and
+`theme-light` or `theme-dark` body classes. Other markup, styles, scripts and assets
+must match. Use a shared source with a theme prop for those instances.
+
 ## Views
 
 | View | Purpose | Required behavior |

package/lib/host-packages/cursor/openplanr/rules/planr-design-review/references/utilities.md

@@ -2,7 +2,8 @@
 
 Run the linked design helper from the skill entrypoint relative to the skill's
 directory. It contains deterministic operations and all required assets. It needs
-Node.js 22.13 or later, with no global CLI, provider credentials or runtime downloads.
+Node.js 22.13 or later, with no global CLI or provider credentials. Only `fonts fetch`
+downloads anything, and only when run; nothing is fetched when a design opens.
 Use `--help` to inspect the installed command interface before writing documents
 or invoking operations; the installed contract is authoritative.
 
@@ -15,8 +16,17 @@ node scripts/design.mjs feedback <design-document.json> --action inspect --json
 node scripts/design.mjs view-context <design-document.json> --json
 node scripts/design.mjs studio <design-document.json> --action status --json
 node scripts/design.mjs studio <design-document.json> --action stop --json
+node scripts/design.mjs fonts fetch --family "<Name>:<weights>" [--family ...] --dest <design>/source/assets/fonts --json
 ```
 
+`fonts fetch` snapshots at most two OFL or Apache families, three weights each, as
+Latin `woff2` files with their license files and a local `fonts.css`. It needs network
+access; ask the user to approve that one command. A host that allowlists domains needs
+`raw.githubusercontent.com` (license check), `fonts.googleapis.com` (font CSS) and
+`fonts.gstatic.com` (font files). It refuses an existing non-empty
+`--dest` and leaves nothing behind when any request fails. See
+[design-system.md](design-system.md) for the fallback.
+
 Use `--view prototype` or `--view walkthrough` to select the initial presentation.
 When an `openplanr` CLI is available, prefer its public `openplanr artifact` route for
 opening the document; otherwise use this bundled script. Both compose the same

package/lib/host-packages/cursor/openplanr/rules/planr-design-review/schemas/design-document.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://openplanr.dev/schemas/v1.20.0/design-document.schema.json",
+  "$id": "https://openplanr.dev/schemas/v1.22.0/design-document.schema.json",
   "x-openplanr-contract": {
     "id": "design-document",
-    "version": "1.20.0"
+    "version": "1.22.0"
   },
   "title": "OpenPlanr authored design document",
   "type": "object",
@@ -26,7 +26,10 @@
       "const": "openplanr-design-document"
     },
     "schemaVersion": {
-      "const": "1.0.0"
+      "enum": [
+        "1.0.0",
+        "1.1.0"
+      ]
     },
     "id": {
       "$ref": "#/$defs/id"
@@ -158,6 +161,66 @@
           },
           "anchors": {
             "$ref": "#/$defs/ids"
+          },
+          "props": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128,
+              "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+            },
+            "additionalProperties": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "type",
+                    "options",
+                    "default"
+                  ],
+                  "properties": {
+                    "type": {
+                      "const": "enum"
+                    },
+                    "options": {
+                      "type": "array",
+                      "minItems": 1,
+                      "uniqueItems": true,
+                      "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 128,
+                        "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+                      }
+                    },
+                    "default": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 128,
+                      "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "type",
+                    "default"
+                  ],
+                  "properties": {
+                    "type": {
+                      "const": "boolean"
+                    },
+                    "default": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              ]
+            }
           }
         }
       }
@@ -232,6 +295,34 @@
             "additionalProperties": {
               "$ref": "#/$defs/source"
             }
+          },
+          "props": {
+            "type": "object",
+            "propertyNames": {
+              "$ref": "#/$defs/id"
+            },
+            "additionalProperties": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+              },
+              "additionalProperties": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128,
+                    "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+                  },
+                  {
+                    "type": "boolean"
+                  }
+                ]
+              }
+            }
           }
         },
         "if": {
@@ -375,5 +466,41 @@
       "minimum": -10000000,
       "maximum": 10000000
     }
-  }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "schemaVersion": {
+            "const": "1.1.0"
+          }
+        },
+        "required": [
+          "schemaVersion"
+        ]
+      },
+      "else": {
+        "properties": {
+          "screens": {
+            "items": {
+              "not": {
+                "required": [
+                  "props"
+                ]
+              }
+            }
+          },
+          "variants": {
+            "items": {
+              "not": {
+                "required": [
+                  "props"
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
 }

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

@@ -1,5 +1,5 @@
 ---
-description: "Diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. Use for root-cause investigation, not planned feature delivery."
+description: "Diagnose a bug, regression, error, or unexplained behavior and optionally implement a bounded fix. Use for root-cause investigation, including before any fix, not planned feature delivery."
 alwaysApply: false
 ---
 

package/lib/host-packages/cursor/openplanr/rules/planr-plan/schemas/design-document.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://openplanr.dev/schemas/v1.20.0/design-document.schema.json",
+  "$id": "https://openplanr.dev/schemas/v1.22.0/design-document.schema.json",
   "x-openplanr-contract": {
     "id": "design-document",
-    "version": "1.20.0"
+    "version": "1.22.0"
   },
   "title": "OpenPlanr authored design document",
   "type": "object",
@@ -26,7 +26,10 @@
       "const": "openplanr-design-document"
     },
     "schemaVersion": {
-      "const": "1.0.0"
+      "enum": [
+        "1.0.0",
+        "1.1.0"
+      ]
     },
     "id": {
       "$ref": "#/$defs/id"
@@ -158,6 +161,66 @@
           },
           "anchors": {
             "$ref": "#/$defs/ids"
+          },
+          "props": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128,
+              "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+            },
+            "additionalProperties": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "type",
+                    "options",
+                    "default"
+                  ],
+                  "properties": {
+                    "type": {
+                      "const": "enum"
+                    },
+                    "options": {
+                      "type": "array",
+                      "minItems": 1,
+                      "uniqueItems": true,
+                      "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 128,
+                        "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+                      }
+                    },
+                    "default": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 128,
+                      "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "type",
+                    "default"
+                  ],
+                  "properties": {
+                    "type": {
+                      "const": "boolean"
+                    },
+                    "default": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              ]
+            }
           }
         }
       }
@@ -232,6 +295,34 @@
             "additionalProperties": {
               "$ref": "#/$defs/source"
             }
+          },
+          "props": {
+            "type": "object",
+            "propertyNames": {
+              "$ref": "#/$defs/id"
+            },
+            "additionalProperties": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+              },
+              "additionalProperties": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128,
+                    "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+                  },
+                  {
+                    "type": "boolean"
+                  }
+                ]
+              }
+            }
           }
         },
         "if": {
@@ -375,5 +466,41 @@
       "minimum": -10000000,
       "maximum": 10000000
     }
-  }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "schemaVersion": {
+            "const": "1.1.0"
+          }
+        },
+        "required": [
+          "schemaVersion"
+        ]
+      },
+      "else": {
+        "properties": {
+          "screens": {
+            "items": {
+              "not": {
+                "required": [
+                  "props"
+                ]
+              }
+            }
+          },
+          "variants": {
+            "items": {
+              "not": {
+                "required": [
+                  "props"
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
 }

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

@@ -6,9 +6,9 @@ alwaysApply: false
 # OpenPlanr 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
+implementation-ready stories and tasks 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
@@ -63,14 +63,24 @@ 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.
+The main session owns the plan, decisions, and integration. Keep small coherent
+planning work in this session. Delegate only a self-contained outcome that
+benefits from context isolation, a distinct capability boundary, or independent
+parallel work; agent availability alone is not a reason to dispatch.
+
+Use specification for a distinct planning assignment or completeness review,
+designer for a separate design deliverable or critique, and database only for
+authorized read-only live introspection when repository schemas are insufficient.
+Do not have two planners decompose the same request. Entity scaffolding remains
+manual, on explicit request.
+
+Select the exact registered identity from the host's roster; Claude plugin
+agents use names such as `planr:planr-specification`. Give each worker its outcome,
+authoritative paths, relevant decisions, file ownership, verification requirements,
+and concise return expectations. Parallel workers need disjoint writes or an
+agreed interface. Explain the delegation's purpose briefly in commentary.
+When the host lacks the native role, perform the work sequentially in this session
+and disclose capability limitations; never claim an unavailable specialist ran.
 
 ## Author the decomposition
 

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

@@ -1,12 +1,12 @@
 ---
-description: "Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work."
+description: "Implement an OpenPlanr plan, specification, task, or clearly stated request end to end in the current repository. Use when the user asks to build, implement, fix, finish, or ship local work, or to plan and implement an accepted change. Invoke before editing files for the requested change. Not for planning only, landing, release, or work handed to another coding agent."
 alwaysApply: false
 ---
 
 # OpenPlanr Ship
 
-Produce an implementation-complete local repository in this active coding
-session. Landing and release preparation belong to `planr-land`. Ordinary
+Produce an implementation-complete local repository in this active coding session.
+Landing and release preparation belong to `planr-land`. Ordinary
 Ship stays host-native. Do not delegate implementation to a command-line or model subprocess. If the user explicitly asks another coding agent to implement,
 hand off to `planr-delegate` before implementation. That separate opt-in workflow
 previews the selected context, writable repository, profile, and destination;
@@ -39,13 +39,34 @@ context is sufficient; missing planning files do not create a gate.
 
 ## Implement with native roles
 
-Use the host's read, edit, shell, browser, and test capabilities. When native
-agents are available, dispatch only the applicable frontend, backend, database,
-QA, DevOps, and documentation roles inside this session. Give each role its
-owned outcome, relevant context paths, and explicit file coordination boundary.
-Run independent work in parallel. Host-native role agents remain part of this
-Ship session and do not invoke the separate `planr-delegate` helper. When native
-agents are unavailable, perform the same lenses sequentially in the active agent.
+The main session owns scope, decisions, integration, and final verification.
+Use the host's read, edit, shell, browser, and test capabilities inside this session.
+Keep small coherent changes in this session. Delegate only a self-contained
+outcome that benefits from context isolation, a distinct capability boundary,
+or independent parallel work; agent availability alone is not a reason to dispatch.
+
+Frontend and backend own substantial bounded implementation assignments.
+Persistence implementation, including a task carrying the legacy `db-agent`
+identity, belongs to backend with the relevant database guidance; preserve the
+task's recorded identity. Database is optional read-only introspection when
+repository schemas are insufficient, never migration implementation. Keep small
+documentation updates with their implementation; delegate substantial documentation
+or requested configuration work separately. DevOps never deploys. Entity
+scaffolding remains manual, on explicit request.
+
+Use a separate QA reviewer for authorization, credentials, data-loss risk,
+migrations, public contracts, release behavior, or substantial delegated
+implementation. Small low-risk edits use focused verification in the main session.
+QA retains verification tools, subject to role policy and session permissions.
+
+Select the exact registered identity from the host's roster; Claude plugin
+agents use names such as `planr:planr-backend` and `planr:planr-qa`. Give each worker
+its outcome, authoritative paths, relevant decisions, file ownership, verification
+requirements, and concise return expectations. Parallel workers need disjoint
+writes or an agreed interface. Explain the delegation's purpose briefly in
+commentary. Host-native workers do not invoke the separate `planr-delegate` helper.
+When the host lacks the native role, perform the work sequentially in this session
+and disclose capability limitations; never claim an unavailable specialist ran.
 
 Integrate the complete change, then verify behavior. `reviewRisks` and
 `browserSurfaces` select useful checks; empty arrays are normal and neither field

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

@@ -30,7 +30,9 @@ template:
 
 Keep evidence and rollback as useful planning context, not approval gates or
 receipt requirements. A risk-specialist section may be empty when no specialist
-lens applies.
+lens applies. Under `## Notes for Decomposition`, list each decision made without
+an answer as a bullet starting `Assumption:` that names the decision and the
+alternative not taken.
 
 For a repository intentionally using default mode, write
 `input/specs/spec-{slug}.md` and preserve its active schema. Do not create a

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

@@ -22,6 +22,12 @@ mutually exclusive questions at once and put the recommended option first. If
 the host lacks that interface, ask one concise chat question. Do not present a
 long prose questionnaire.
 
+If no one can answer, as in a headless run, do not ask: choose the
+repository-backed default, or the recommended one when the repository does not
+settle it, and record each such choice as a bullet starting `Assumption:` under
+`## Notes for Decomposition`, naming the decision and the alternative not taken.
+Record a decision you settle inside a functional requirement the same way.
+
 When native agents are available, use the specification role to consolidate the
 contract and dispatch database or designer roles only when their lens affects
 the decision. Otherwise perform those lenses sequentially in the active agent.