openplanr 1.25.3 → 2.0.1

package/lib/host-packages/claude/openplanr/skills/design/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: design
+description: Design a polished product interface through adaptive consultation, a shared canvas/prototype/walkthrough studio, and an implementation-ready specification. Use for a new design or an existing interface that needs a coherent direction.
+license: MIT
+---
+
+# Planr Design
+
+Develop one strong direction in the active host session, grounded in the product
+and its visual language. Deliver editable local source, a working review studio,
+and a ten-section design specification ready for Plan.
+
+## Consult and establish direction
+
+Read [discovery.md](references/discovery.md) before generating. Inspect the brief,
+app shell, components, tokens, assets, reference screens, prior design and project
+taste. Ask only consequential unresolved questions using the host's native
+structured question surface, or one concise chat question when unavailable.
+Honor previous answers and presentation choices. Evolve existing designs by
+default; replacement retains a recoverable prior revision.
+
+Use [design-system.md](references/design-system.md) to reuse the app's system or
+establish a deliberate greenfield system. Existing project conventions take
+precedence over generic spacing, typography and frame defaults.
+
+## Author and inspect
+
+Read [generation.md](references/generation.md) and [craft.md](references/craft.md).
+Use the [document contract](schemas/design-document.schema.json) to create one
+design document with stable screens and authored local sources. Canvas,
+Prototype and Walkthrough are views of that document; view changes never start
+generation. Use a native designer agent when available, otherwise perform the
+work directly. Semantic design work stays in this active host session.
+
+Read [team-review.md](references/team-review.md) and author `review-context.json`
+beside the design document before rendering every new design. Write its welcome
+purpose and up to three consequential review questions from this project's brief
+and settled answers. Preserve existing guidance; never invent requirements or
+reuse another project's welcome copy.
+
+Use [utilities.md](references/utilities.md) for the bundled deterministic helper
+at [scripts/design.mjs](scripts/design.mjs). It inspects, validates, renders, opens,
+exports and records feedback without a separate CLI installation. When available,
+use the public `planr artifact` route to open the design document.
+
+Inspect browser screenshots and exercise the primary journey and keyboard behavior
+at declared frames. Correct observed failures, then record evidence. Static lint
+alone cannot establish visual verification. When browser inspection is unavailable,
+return the artifact as **unverified**.
+
+The studio can create an encrypted collaborative review for a company team. When
+the user asks to share, refresh and render the welcome context, inspect it in the
+studio, then open Share. Explain the stable review link, separately entered access
+token and private owner controls; never create or send a link without that
+explicit request.
+
+## Review and hand off
+
+Read [review.md](references/review.md) when feedback arrives. Pins and ratings come
+from the board; chat may request broader changes. Preserve unrelated screens,
+stable anchors and board arrangement during scoped revisions.
+
+Finish with [handoff.md](references/handoff.md) and its
+[ten-section template](references/design-spec-template.md). The design author
+writes `design-spec.md` in this run, including image-based inputs. Return the
+studio/source/specification paths, chosen direction, verification result and any
+remaining questions. Stop here: Plan, Ship, creating a share link and deployment
+are separate user actions. Use Design Loop when the user requests alternatives, and Design
+Review for focused iteration on an existing direction.
+
+For company reviews and implementation handoff, follow
+[team-review.md](references/team-review.md). Keep review guidance outside product
+screens, preserve reviewer intent, and let the owner approve the refined handoff.

package/lib/host-packages/claude/openplanr/skills/design/openplanr.skill.json

@@ -0,0 +1,466 @@
+{
+  "kind": "openplanr-skill-package",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.8.0",
+  "skillId": "planr-design",
+  "skillVersion": "2.0.0",
+  "entrypoint": "SKILL.md",
+  "hosts": [
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "cursor"
+  ],
+  "execution": "host-agent",
+  "resources": [
+    {
+      "path": "agents/openai.yaml",
+      "kind": "agent-metadata",
+      "hosts": [
+        "codex",
+        "chatgpt"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/craft.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/design-spec-template.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/design-system.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/discovery.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/generation.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/handoff.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/review.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/utilities.md",
+      "kind": "reference",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": false
+    },
+    {
+      "path": "references/team-review.md",
+      "kind": "reference",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/design.mjs",
+      "kind": "script",
+      "executable": true,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "schemas/design-document.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "schemas/design-review-context.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "schemas/design-review-handoff.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/artifact/templates/artifact-review-stage.js",
+      "kind": "asset",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/design/templates/studio/enhancements.css",
+      "kind": "asset",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/design/templates/studio/enhancements.js",
+      "kind": "asset",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/design/templates/studio/share.css",
+      "kind": "asset",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/design/templates/studio/share.js",
+      "kind": "asset",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/design/templates/studio/studio.css",
+      "kind": "asset",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/design/templates/studio/studio.js",
+      "kind": "asset",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/package.json",
+      "kind": "asset",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/registry/artifact-theme.json",
+      "kind": "asset",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.0.0/design-manifest.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.1.0/artifact-envelope.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.1.0/artifact-paste.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.1.0/artifact-review.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.1.0/artifact-theme.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.10.0/design-review-bundle.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.10.0/design-review-context.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.10.0/design-review-handoff.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.10.0/design-review-metadata-payload.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.11.0/design-review-metadata-payload.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.9.0/design-document.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.9.0/design-review-bundle.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.9.0/design-review-workspace.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.9.0/design-workspace-create.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.9.0/design-workspace-event.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/packages/protocol/schemas/v1.9.0/design-workspace-revision.schema.json",
+      "kind": "schema",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/notices/entities.txt",
+      "kind": "asset",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    },
+    {
+      "path": "scripts/runtime/notices/parse5.txt",
+      "kind": "asset",
+      "executable": false,
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ]
+    }
+  ]
+}

package/lib/host-packages/claude/openplanr/skills/design/references/craft.md

@@ -0,0 +1,68 @@
+# Design craft and browser verification
+
+Aim for a deliberate interface that fits the actual product. Project tokens and
+components are authoritative. Static rules help catch accidents; screenshots and
+interaction checks establish whether the design works.
+
+## Review while authoring
+
+| Dimension | What to inspect |
+| --- | --- |
+| Hierarchy | A clear main job and primary action; scanning order matches user priority |
+| Typography | Deliberate scale, appropriate density, readable line lengths and labels; aligned data numerals |
+| Spacing | Consistent project rhythm, aligned baselines, related items grouped and sections distinguished |
+| Components | Consistent control sizes and states; long labels wrap without clipping; repeated badges have coherent dimensions |
+| Color | Semantic roles remain consistent; computed text contrast at least 4.5:1 or 3:1 for large text |
+| Content | Concrete copy and plausible data; honest loading/empty/error states; no lorem ipsum or misleading product claims |
+| Responsiveness | Content reflows at declared frames, controls remain reachable, no accidental horizontal overflow |
+| Accessibility | Semantic controls, accessible names, visible focus, logical keyboard order, reduced-motion support |
+
+Use the project's visual vocabulary. Avoid ornamental gradients, repeated generic
+cards or decorative imagery that does not serve the content; do not ban treatments
+the brand explicitly uses. Use the project icon set and appropriate real assets.
+Dense tools and branded pages need different hierarchy and density. A polished
+canvas shell does not compensate for a weak interface inside its artboards.
+
+## Keep product and explanation separate
+
+A product artboard must look and behave like the interface the team can build and
+ship. Do not turn it into a requirements document, comparison slide, annotated
+wireframe, or architecture memo. Move author commentary, tradeoffs, field mappings,
+recommendations, citations, and implementation notes into the studio's external
+Notes accordion, Walkthrough narrative, or `design-spec.md`. Use short tooltips for
+one concise screen note and collapsed accordion entries when several screens carry
+guidance. Review the artboard once with all studio notes closed; it should still be
+a coherent, production-like product screen.
+
+Check development readiness explicitly: components map to a consistent recipe,
+spacing and typography use declared tokens, content is realistic, interaction and
+validation states are present, responsive changes are intentional, and keyboard
+focus follows the user journey. A detailed explanation of missing behavior does not
+substitute for demonstrating that behavior in Prototype.
+
+## Inspect the rendered result
+
+Run static validation first, fixing its concrete errors in source. Project scales
+and declared frames take precedence over generic linter defaults. Then use the
+available browser tool to open the actual studio URL and:
+
+1. Verify the loaded design/revision and wait for fonts, images and frames to load.
+   Capture and visually inspect each selected screen at narrow and wide declared
+   frames; inspect all available variants when comparing alternatives.
+2. Check computed foreground/background colors, including CSS variables and parent
+   surfaces. Detect clipping and overflow, missing assets, overlapping controls and
+   unreadable text. Review console/network errors that affect this design.
+3. Exercise the primary journey, changed controls, form validation and back/next
+   navigation. Use keyboard navigation and visible focus. Test annotation mode
+   separately so a pin cannot accidentally trigger a product action.
+4. Switch Canvas, Prototype and Walkthrough; verify that source content, responsive
+   frame choices and existing feedback stay consistent. Check long walkthroughs
+   through their final step rather than assuming the first eight prove the rest.
+5. Record actual screenshots, tested frames/actions, findings and fixes. Re-render
+   and recheck affected screens after changes. Submit the resulting browser report
+   through the verification utility as documented in [utilities.md](utilities.md).
+
+Do not fabricate measurements or pass a report based only on static markup.
+When a browser, screenshot capability or required asset is unavailable, deliver
+the source and preview with **unverified** status and the missing check. Failed
+checks remain visible until corrected; server health alone is not visual verification.

package/lib/host-packages/claude/openplanr/skills/design/references/design-spec-template.md

@@ -0,0 +1,88 @@
+# Shared: the `design-spec.md` ten-section template
+
+The active design author writes this specification once per run from the brief,
+existing design system and inspected references, including image-based inputs.
+A delegated designer may be that single author; the coordinator must not start a
+second writer. Plan consumes an existing specification rather than re-extracting
+its preview pixels. If Plan receives only previously unattached mockups, its
+native designer can author a missing specification using this same contract.
+
+Write one Markdown file to the mode-specific path. Include all ten sections in
+order; use “Not applicable” with a reason when a section genuinely does not apply.
+Record exact authored values and identify approximations from image references.
+Identify the selected direction above the sections, for example
+`> Selected direction: editorial — Editorial workspace`, and keep it aligned
+with the authored document and the board's recorded selection at handoff.
+
+## 1. Color Palette
+
+| Role | Hex | Usage |
+|------|-----|-------|
+| Primary | `#______` | … |
+| Accent | `#______` | … |
+| Background | `#______` | … |
+| Surface | `#______` | … |
+| Text / Ink | `#______` | … |
+| Muted | `#______` | … |
+| Success / Warn / Danger | `#______` | … |
+
+State exact hex values. For dark mode, add a parallel column or note.
+
+## 2. Typography
+
+| Role | Family | Weight | Size / Line-height |
+|------|--------|--------|--------------------|
+| Display / H1 | … | … | … |
+| Heading | … | … | … |
+| Body | … | … | … |
+| Caption / Label | … | … | … |
+| Mono (if any) | … | … | … |
+
+Name the font families and the weights actually used.
+
+## 3. Spacing & Layout
+
+Spacing scale (e.g. 4 / 8 / 12 / 16 / 24 / 32), grid columns, gutters, max content
+width, the project’s actual breakpoints and declared responsive frames, and the
+corner-radius scale. Reuse the project scale; the numbers above are examples.
+
+## 4. Components Inventory
+
+Exhaustive list of components with their variants and states (default / hover /
+focus / active / disabled / loading / empty / error). One subsection per component.
+
+## 5. Navigation & Layout Patterns
+
+Global chrome (top bar, sidebar, tabs), the navigation model, and how primary
+regions are arranged. Note sticky/scroll behaviors.
+
+## 6. Iconography
+
+Icon style (line/solid), nominal size(s), and the set/source if identifiable.
+
+## 7. Motion & Interaction Hints
+
+Transitions, durations/easings, hover/press feedback, and `prefers-reduced-motion`
+intent. Keep it implementable, not aspirational.
+
+## 8. Component Overrides
+
+Any deviations from the project component library (`input/tech/stack.md`
+`ComponentLibrary`) — per-component, with the reason.
+
+## 9. Screen Inventory
+
+| Screen | Purpose | Key components | States to handle |
+|--------|---------|----------------|------------------|
+| … | … | … | loading / empty / error / success |
+
+One row per screen. This drives the downstream UI tasks.
+
+## 10. Open Questions
+
+Record material ambiguities, the recommended default, and any assumption used to
+keep the work moving. When authoring directly from a thin brief, put
+inferred-not-specified decisions here rather than asserting them as fact
+(`content_provenance: inferred`). Do not block ordinary implementation when the
+repository or a safe reversible default resolves the question; ask the user only
+when the choice materially changes product behavior, architecture, or risk.