openplanr 3.2.0 → 3.3.0

package/lib/host-packages/openai/openplanr/skills/design-loop/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/openai/openplanr/skills/design-review/references/design-system.md

@@ -54,8 +54,23 @@ while authoring:
 - at most two families and three weights each; one variable file can cover a
   family's weights.
 
-Snapshotting needs network access while authoring. When it is unavailable, or a
-license is unclear, use the role's system stack and name that fallback in the return:
+Snapshot with the bundled helper, run from the skill directory (see
+[utilities.md](utilities.md)):
+
+```sh
+node scripts/design.mjs fonts fetch --family "Inter:400,600" --family "Source Serif 4:400" --dest <design>/source/assets/fonts
+```
+
+It is the one command to ask approval for. A host that allowlists network access by
+domain needs `raw.githubusercontent.com`, `fonts.googleapis.com` and
+`fonts.gstatic.com`. It enforces the rules above, verifies each
+license from the Google Fonts catalog, writes `fonts.css`, and prints the files and
+total bytes. Start the design stylesheet with `@import "assets/fonts/fonts.css";`
+(relative to that stylesheet), then use the families by name. Nothing is fetched when
+a design opens.
+
+When the host denies network access, the command fails, or it refuses a license, use
+the role's system stack and name that fallback in the return:
 
 | Role | System stack |
 | --- | --- |

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

@@ -1,6 +1,6 @@
 ---
 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."
+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."
 ---
 
 # OpenPlanr Investigate

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

@@ -1,6 +1,6 @@
 interface:
   display_name: "OpenPlanr 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."
+  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, including before any fix, not planned feature delivery."
 policy:
   allow_implicit_invocation: true

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

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-investigate",
-  "skillVersion": "2.0.1",
+  "skillVersion": "2.1.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",

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

@@ -7,9 +7,9 @@ license: MIT
 # 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
@@ -64,14 +64,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/openai/openplanr/skills/plan/openplanr.skill.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0.0",
   "protocolVersion": "1.8.0",
   "skillId": "planr-plan",
-  "skillVersion": "1.2.1",
+  "skillVersion": "1.3.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",