openplanr 1.25.2 → 2.0.0

package/lib/host-packages/cursor/openplanr/rules/planr-design-loop/scripts/runtime/packages/protocol/schemas/v1.9.0/design-workspace-event.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.9.0/design-workspace-event.schema.json",
+  "x-openplanr-contract": {
+    "id": "design-workspace-event",
+    "version": "1.9.0"
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{22,64}$"
+    },
+    "revisionId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{22,64}$"
+    },
+    "reviewOf": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "epoch": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647
+    },
+    "iv": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 16,
+      "maxLength": 16
+    },
+    "ciphertext": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 22,
+      "maxLength": 6990507
+    },
+    "publicKey": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kty",
+        "crv",
+        "x",
+        "y"
+      ],
+      "properties": {
+        "kty": {
+          "const": "EC"
+        },
+        "crv": {
+          "const": "P-256"
+        },
+        "x": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]+$",
+          "minLength": 43,
+          "maxLength": 43
+        },
+        "y": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]+$",
+          "minLength": 43,
+          "maxLength": 43
+        },
+        "ext": {
+          "type": "boolean"
+        },
+        "key_ops": {
+          "type": "array",
+          "items": {
+            "const": "verify"
+          },
+          "maxItems": 1
+        }
+      }
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 86,
+      "maxLength": 86
+    }
+  },
+  "required": [
+    "id",
+    "revisionId",
+    "reviewOf",
+    "epoch",
+    "iv",
+    "ciphertext",
+    "publicKey",
+    "signature"
+  ]
+}

package/lib/host-packages/cursor/openplanr/rules/planr-design-loop/scripts/runtime/packages/protocol/schemas/v1.9.0/design-workspace-revision.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openplanr.dev/schemas/v1.9.0/design-workspace-revision.schema.json",
+  "x-openplanr-contract": {
+    "id": "design-workspace-revision",
+    "version": "1.9.0"
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{22,64}$"
+    },
+    "epoch": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647
+    },
+    "reviewOf": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "iv": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 16,
+      "maxLength": 16
+    },
+    "ciphertext": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 22,
+      "maxLength": 6990507
+    },
+    "signature": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "minLength": 86,
+      "maxLength": 86
+    }
+  },
+  "required": [
+    "id",
+    "epoch",
+    "reviewOf",
+    "createdAt",
+    "iv",
+    "ciphertext",
+    "signature"
+  ]
+}

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

@@ -0,0 +1,57 @@
+---
+description: "Compare three materially different product design directions in a live review studio, collect pins and ratings, and develop the selected direction. Use for visual alternatives, comparison or a remix."
+alwaysApply: false
+---
+
+# Planr Design Loop
+
+Help the user choose and refine a direction through a real comparison board.
+Generate three alternatives by default; honor an explicit requested count.
+
+1. Read [discovery.md](references/discovery.md) and
+   [design-system.md](references/design-system.md). Inspect the brief, existing
+   product, assets, reference screens, design document and previous preferences.
+   Ask short, consequential unresolved questions through the host's native question
+   surface, with one-question chat fallback. Reuse answers already provided.
+2. Read [generation.md](references/generation.md) and
+   [craft.md](references/craft.md). Define three distinct approaches to layout,
+   hierarchy, typography and brand expression, all addressing the same journey.
+   Keep the [document contract](schemas/design-document.schema.json) shared.
+   Assign one direction per native agent in parallel when supported; otherwise
+   create them sequentially in this active host session. Keep one owner for the
+   shared document and final specification; agents write disjoint variant sources.
+   That owner reads [team-review.md](references/team-review.md) and authors one
+   sibling `review-context.json` before rendering. Ground its welcome purpose and
+   up to three consequential review questions in the supplied brief and the
+   directions' actual tradeoffs, without implying a winner or inventing requirements.
+3. Build the comparison from those sources using
+   [utilities.md](references/utilities.md) and
+   [scripts/design.mjs](scripts/design.mjs), or the public `planr artifact` route
+   when the CLI is present. All variants use the same screen identities and frame
+   coverage. Show failures explicitly without inventing results or discarding
+   completed variants. Canvas, Prototype and Walkthrough share one document and
+   can be switched without regenerating content.
+4. Inspect rendered screenshots and exercise each available direction's primary
+   journey. Record concrete quality evidence; without browser inspection, mark
+   the preview **unverified**. Read [review.md](references/review.md) for ratings,
+   pins, selection and remix. Board feedback is authoritative for pins and ratings;
+   chat may describe a broader remix but cannot impersonate a recorded board vote.
+5. Apply the chosen direction and scoped changes while preserving unrelated
+   screens, anchors, annotations and arrangement. Preserve the previous working
+   revision. Record selected and rejected preferences locally with their reasons.
+6. Use [handoff.md](references/handoff.md) and the
+   [ten-section template](references/design-spec-template.md) to finalize the
+   selected design, editable source, manifest and `design-spec.md`. If selection
+   remains open, report the comparison as awaiting selection rather than implying
+   a winner. Offer the studio's encrypted collaborative review when the user wants
+   company feedback; before a requested share or publish, refresh, render and
+   inspect the welcome context while preserving existing implementation guidance.
+   Selection does not start Plan or Ship or authorize creating
+   or sending a review link or deployment.
+
+The bundled utilities perform deterministic work only. No provider credentials,
+semantic command subprocess, runtime downloads or global CLI are required.
+
+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/cursor/openplanr/rules/planr-design-review/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/cursor/openplanr/rules/planr-design-review/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.

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

@@ -0,0 +1,33 @@
+# Prepare a coherent design system
+
+Reuse the existing app's component patterns, tokens, icon family and typography.
+Before drawing a new shell, inspect its real navigation and a representative dense
+screen. Reuse local fonts and licensed project assets. Do not substitute a generic
+sidebar, color theme or arbitrary spacing rules for established conventions.
+
+If no usable system exists, establish a small project-local system beside the
+design source (or in the project's existing system location):
+
+- `tokens.css`: semantic colors including on-color text, spacing, radii, elevation,
+  type sizes and responsive breakpoints, with required contrast combinations.
+- `brand.md`: purpose, audience, voice, intended visual character, references,
+  chosen and rejected directions, and concrete rationale.
+- `components.md`: recipes for the components this journey needs, including
+  dimensions, variants, keyboard/focus behavior and meaningful state handling.
+
+Link these sources from the design document and use them in authored screens.
+For a system outside the design directory, copy only the resolved tokens/assets
+needed by the portable preview into its local source and record their upstream
+paths in the brief references. Treat that copy as a render snapshot, not a second
+project design system. The document's source paths cannot traverse outside its
+directory. Extract approximated
+values from image references honestly and record uncertainty in Open Questions.
+
+Choose typography for the content: dense data needs legible labels and aligned
+numerals, an editorial page needs deliberate type hierarchy, and a field workflow
+needs readable controls in narrow space. Match visual density to the task.
+Default to one coherent type scale and spacing rhythm; the project's scale wins.
+
+Reusable component changes apply to each affected instance. Keep a short record
+of those instances so review can explain the scope and inspect their screenshots.
+Keep source references editable and local; no fonts or runtimes fetched on launch.

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

@@ -0,0 +1,53 @@
+# Discovery and adaptive consultation
+
+Start from evidence, then ask the smallest set of questions that changes the
+design. A clear brief is usable input; do not force a source/format questionnaire.
+
+## Ground the brief
+
+- Read the requested spec or task and its parent story/feature when present.
+  Find the project root and `.planr/config.json`. Missing planning records do not
+  block an explicit brief. Never choose among multiple matching specs silently.
+- Inspect the app entrypoint and shell, routes, representative working screens,
+  component library, CSS tokens/theme configuration, fonts, logos and images.
+  Inspect available screenshots visually rather than deriving aesthetics from
+  filenames. Record what comes from the project versus inference.
+- Find prior `design-document.json`, `finalized.json`, `design-spec.md`, board
+  feedback and project-local taste. Read source before attempting regeneration.
+  Preserve design/screen/variant/anchor identities and the previous working result.
+- Summarize the actual user, job to be done, primary journey, screen inventory,
+  necessary states and constraints. Include loading, empty, error and success
+  behavior where the journey requires them; do not multiply screens speculatively.
+
+## Ask what remains consequential
+
+Use the host's native structured questions when callable. Otherwise ask one concise
+chat question at a time. Neither a missing question tool nor a thin screen list is
+a technical blocker. Do not ask the user to locate files that exploration can find.
+
+| Missing decision | Useful question | Evidence that settles it |
+| --- | --- | --- |
+| Audience or main job | Who uses this, and what must they finish first? | Explicit role, journey and success criterion in the brief |
+| Conflicting source | Which of the two discovered specs defines this design? | Exact path or identifier provided by the user |
+| Scope from a thin brief | Should this cover the full signup journey or only account creation? | Concrete requirements imply an unambiguous bounded journey |
+| Visual direction | Should this extend the current brand or explore a new identity? | User explicitly requests continuity or a redesign |
+| Responsive use | Is the main context a desktop workspace or a phone in the field? | Product requirements or existing supported breakpoints |
+| Initial presentation | Would you prefer the artboard overview or to click through the journey first? | Explicit canvas/prototype/walkthrough request |
+
+Recommend the option grounded in evidence; explain its effect in one sentence.
+Ask only unresolved axes and honor previous answers. For reversible presentation
+defaults, Canvas suits comparison, Prototype suits a single surface or interaction,
+and Walkthrough suits a guided sequence. All three remain available from one source.
+If assumptions are authorized, state them and record them in the specification.
+
+## Record the useful outcome
+
+Write a short brief/provenance record next to the editable source: audience, main
+journey, screen/state scope, visual direction, declared responsive frames, explicit
+answers, references actually inspected and remaining assumptions. Persist project
+design tokens and brand guidance using [design-system.md](design-system.md).
+
+Normal Design produces one direction. Design Loop explores three by default.
+Existing work evolves by default; replacement keeps a recoverable original. Image
+references may guide authored interfaces or remain static reference boards. Name
+which capability was delivered; an image with pins is not a functional prototype.

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

@@ -0,0 +1,105 @@
+# Author one design, render three views
+
+Keep semantic design and code authoring in the active host agent. Deterministic
+utilities package the authored result; they do not invent screens or call models.
+
+## Editable source and identity
+
+Use a versioned `design-document.json` and the bundled schema exposed by the
+[utility](utilities.md). It names the design, stable screens and variants, authored
+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.
+
+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
+design's brief and current decisions. Keep existing context when evolving the
+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.
+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.
+Use stable `data-planr-id` attributes on meaningful review targets, including
+primary controls and reusable component instances. Avoid anchoring feedback to
+incidental array positions or rendered CSS selectors.
+
+Author real screen content with useful labels, plausible data and complete states.
+Make the primary journey navigable and meaningful controls functional. Use local
+HTML/CSS/JavaScript and assets supported by the bundled utility; do not require a
+build server, package installation, remote modules or a development environment to
+open the studio. Third-party assets retain their license/attribution where needed.
+Use classic browser scripts with local event handlers. If adapting an existing
+module-based component, compile its local preview before packaging; the portable
+utility does not install dependencies or compile modules. Use local image `src`
+with responsive CSS. Forms validate and run local handlers; omit navigation
+actions and targets. Cross-screen actions can use `data-design-navigate` with the
+stable target screen ID.
+
+For a product design, authored screen HTML is the product surface an engineer will
+implement. Keep design rationale, option labels, implementation mappings, cost or
+contract commentary, recommendations, and explanatory guide prose out of the
+artboard. Put a short screen-level explanation in `screen.description`; the studio
+exposes it as a compact note marker and an accordion outside the rendered product.
+Put detailed reasoning and engineering evidence in `design-spec.md`. Use
+Walkthrough for an annotated presentation. Text belongs inside the artboard only
+when an end user of the product would actually see it.
+
+Treat each product screen as development-ready: reuse production components and
+tokens, show realistic content, define primary and secondary actions, include the
+states needed for implementation, and make responsive and keyboard behavior
+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.
+
+## Views
+
+| View | Purpose | Required behavior |
+| --- | --- | --- |
+| Canvas | Compare screens and responsive artboards | Freeform coordinates, background/Space/middle-button pan, cursor-centered zoom, fit/select, persisted arrangement and per-view camera |
+| Prototype | Experience the interface | Real navigation, usable forms/controls, explicit interaction versus annotation mode |
+| Walkthrough | Explain the journey | Ordered screen navigator, screen descriptions and unlimited declared steps |
+
+The same source renders in all views. Switching view or frame does not regenerate,
+reinterpret copy, create new identities or lose feedback. Use explicit declared
+frames. Existing breakpoints win; choose representative narrow and wide frames for
+a responsive web design, and record any product-specific limitation. For a
+greenfield responsive web product without an established viewport, use a
+production-sized `1440 × 1024` desktop artboard, an `834 × 1194` tablet artboard
+when tablet behavior matters, and a `390 × 844` mobile artboard. Treat these as CSS
+viewport dimensions. Do not invent a cramped desktop width merely to make the
+whole canvas fit; the studio's Fit control handles presentation scale.
+
+Canvas tools are exclusive: Interact runs product controls, Annotate places pins,
+Inspect selects elements without activating them, and Pan moves the camera. Drag
+an artboard by its title to arrange it. Use I / C / H to select Interact / Annotate /
+Pan; hold Space for temporary pan and Escape to leave Pan or Inspect. Switching
+tools preserves comment drafts. Focused views start in Interact.
+
+## Parallel alternatives
+
+For Design Loop, define three clear hypotheses, not superficial recolors. Examples
+include dense command workspace, editorial overview and focused guided journey.
+Keep requirements and screen coverage comparable. Use native parallel agents when
+supported, with one direction and separate source paths per agent. The coordinator
+owns the shared document and specification. Sequential execution follows the same
+contract. Completed variants survive another variant failing; record failures and
+never claim an unavailable direction was evaluated.
+
+The document needs an available `selectedVariant` for its initial preview. Use the
+first ready direction until the user chooses; this display default is not a board
+vote. Record a user preference or final winner only after explicit selection.
+
+## Render and recover
+
+Use [utilities.md](utilities.md) to inspect, validate, render and open the document.
+Stage changes before publishing the next revision. Do not edit generated preview
+HTML as the source of truth. Keep the previous working revision until the new one
+is complete; report failed rendering with its cause and retained working preview.
+
+Legacy HTML/canvas/image designs may be reviewed in place. When converting them,
+preserve the original as a local source/reference and declare static image screens
+as static. Existing `finalized.json` and mode-specific specification readers remain
+supported. Use [craft.md](craft.md) for browser checks before finalization and
+[handoff.md](handoff.md) for the complete implementation context.

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

@@ -0,0 +1,47 @@
+# Complete design and handoff to Plan
+
+The active design author owns `design-spec.md` in this run. This includes designs
+based on PNG/SVG mockups: inspect the source visually, document approximations and
+produce the specification now. Do not defer required context to a later Plan run.
+Use the [ten-section template](design-spec-template.md) without dropping sections.
+
+Read the board's persisted `.design/studio-state.json` before finalizing. Its
+`selectedVariant` is authoritative when a selection was recorded. Synchronize
+the authored document's selection and the specification's direction and affected
+sections, then render and verify that result. Keep the handoff incomplete until
+the selected source, document and specification agree; a board click or export
+does not perform this semantic synchronization. Reuse an explicit settled choice
+without asking for permission again.
+
+## Resolve the project location
+
+| Project mode | Design source/studio | Specification |
+| --- | --- | --- |
+| Spec-driven: `.planr/config.json` declares `idPrefix.spec` | `.planr/specs/SPEC-NNN-<slug>/design/` | Same directory's `design-spec.md` |
+| Default feature | `output/feats/feat-<slug>/design/` | `output/feats/feat-<slug>/design-spec.md` |
+| Explicit standalone destination | Requested directory | Same directory's `design-spec.md`; report that Plan needs an explicit association |
+
+Resolve an existing spec's actual identifier; do not invent `SPEC-NNN` or reuse a
+different feature's images. Keep legacy flat specification paths unchanged.
+
+## Deliverable closure
+
+- Editable design document, screen sources, assets and project design-system
+  references suitable for version control.
+- Complete rendered studio, with the selected direction accessible in Canvas,
+  Prototype and Walkthrough. Label static image references clearly.
+- Compatibility `finalized.json` alongside additive document/revision metadata.
+- Ten-section `design-spec.md` covering the chosen design, screen inventory,
+  required component states, responsive behavior and explicit assumptions.
+- Actual verification result and browser evidence, or an explicit unverified
+  status with remaining checks. Keep unresolved feedback visible.
+
+Generated previews and copied runtimes are separate from authored source. Follow
+the project's tracking conventions; never discard editable source or the prior
+working revision merely to clean generated output.
+
+Return concise links to the studio, document/source, specification and quality
+result. State the selected direction and any decisions still open. Plan can read
+the specification and selected sources to create UI tasks; it must not re-extract
+an authored specification from preview pixels. Stop at the handoff. Starting Plan,
+Ship, external sharing, publication or deployment needs that user request.