openplanr 3.2.0 → 3.4.0

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,10 @@
 
 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 provider credentials. Local design work needs no global
+CLI. Sharing a design for company review runs in the `openplanr` CLI, which holds the
+owner keys. 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 +18,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
@@ -98,12 +110,16 @@ The design remains accessible when the local machine is offline. Owner authority
 saves automatically in a protected user-level file outside the project; recovery
 export is optional. Only copy the reviewer token through the explicit Share controls.
 
-The bundled utility supports `share`, `publish`, and `sync` with the same design
-document argument. `share` creates or retries a review, `publish` sends an explicitly
-requested new revision to the existing URL, and `sync` retrieves authenticated
-feedback. Run `--help` for access-management and recovery options. The public CLI
-equivalents are `openplanr artifact share`, `openplanr artifact publish`, and
-`openplanr artifact sync`. No global CLI is required for the bundled helper.
+Sharing needs the OpenPlanr CLI (`npm install -g openplanr`). The bundled utility's
+`share`, `publish`, `sync` and `manage` commands, the studio's Share dialog, and handoff
+decisions on a shared design all run `openplanr artifact` for the network step, so the
+helper itself reads no owner keys. `share` creates or retries a review, `publish` sends
+an explicitly requested new revision to the existing URL, and `sync` retrieves
+authenticated feedback. You can also run the CLI directly: `openplanr artifact share`,
+`publish`, `sync`, `status`, `manage`, `feedback` and `handoff`. Without the CLI,
+sharing commands stop with `E_DESIGN_SHARE_CLI_REQUIRED`, and feedback inspection
+still works but reports that sync was skipped. A helper and CLI with different sharing
+formats refuse with `E_DESIGN_SHARE_RUNTIME_MISMATCH`; update whichever is older.
 
 Retention is until the owner revokes or deletes the review, while the service is
 maintained. The owner can pause comments and rotate access tokens. Rotation blocks

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
@@ -22,6 +22,7 @@ the requested outcome.
 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.
+Prove the regression test with [fail-first](references/fail-first.md).
 
 ## Findings outside the cause
 

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.3.0",
   "entrypoint": "SKILL.md",
   "hosts": [
     "claude-code",
@@ -22,6 +22,17 @@
       ],
       "executable": false
     },
+    {
+      "path": "references/fail-first.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
     {
       "path": "references/findings.md",
       "kind": "reference",

package/lib/host-packages/openai/openplanr/skills/investigate/references/fail-first.md

@@ -0,0 +1,40 @@
+# Fail-first
+
+A check proves an acceptance criterion only if it fails without the change.
+
+## Applies to
+
+A check mapped to an acceptance ID, or a test written for this task. For
+Investigate, the regression test for the fix.
+
+## Fail-first
+
+- Write or run the check before the implementation. It counts only when the
+  runner reports at least one failed assertion or test.
+- A load error does not count: a missing module, a syntax or compile error, "no
+  tests found", or a collection error. Report it as "fails only on load".
+- If the runner output is unclear, say so instead of guessing.
+- A test written after the code is `not-run` for fail-first. Never revert the
+  implementation to prove it.
+
+A check that already passes before the change: report "passes before the change;
+proves nothing", then narrow or strengthen the check yourself and record that in
+`checks`.
+
+## Seeded fault
+
+Off by default. Offer it only when an acceptance check is new code or fail-first
+failed only on load; the question's default is skip.
+
+1. Record `git status --porcelain` and confirm nothing staged (`git diff --cached --quiet`).
+2. Copy the target file outside the repository.
+3. Make one small edit that breaks behaviour the criterion names.
+4. Rebuild if the tests run built output.
+5. Run the check. It must fail on an assertion.
+6. Restore from the copy, and rebuild if step 4 did; never `git checkout`, which
+   also discards the uncommitted implementation.
+7. Confirm `cmp` against the copy, an identical `--porcelain` output, and nothing staged.
+
+A seed that survives goes in `checks` with a question whose default is "add a
+test for it". Report all of this in the existing `checks` result text: no new
+field, no new stop, no record file.

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",

package/lib/host-packages/openai/openplanr/skills/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"
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
 }