create-yss-spec 1.1.1 → 1.1.3

package/template/.codex/skills/product-design/skills/design-qa/references/qa-rubric.md

@@ -0,0 +1,61 @@
+# QA Rubric
+
+Use this rubric for comprehensive design-to-implementation QA.
+
+## Fidelity
+
+- Layout: frame size, grid, alignment, content order, spatial grouping, card radius, elevation, borders.
+- Spacing: page margins, section gaps, item gaps, padding, tap-target spacing, vertical rhythm, cramped text, collapsed sections, and density drift.
+- Typography: font family, weight, size, line height, letter spacing, wrapping, truncation, hierarchy, text density, optical balance, and mismatched display/body treatment.
+- Color: token mapping, contrast, brand palette, state colors, gradients, opacity, shadows.
+- Imagery: all target image assets are accounted for and match subject accuracy, crop, aspect ratio, generated/real image quality, background treatment.
+- Icons: all icons are accounted for and match stroke weight, size, style family, alignment, optical balance, state changes.
+- Shape and surfaces: rounded cards, borders, dividers, shadows, fills, and container treatments match the target rather than generic component defaults.
+- Responsiveness: elements do not overlap, collapse into adjacent sections, clip, wrap awkwardly, or break hierarchy across desktop, tablet, and mobile viewports.
+- Implementation shortcuts: custom CSS art, inline SVG substitutes, placeholder avatars, decorative blobs, and fake product imagery are flagged when they drift from the target design.
+
+## Mandatory Comparison Passes
+
+Do not rely on generic "looks close" judgment. For each design QA pass, inspect and report on these areas:
+
+### Core design and functionality
+
+- Fonts and typography: identify mismatched font family/fallback, weight, scale, line height, letter spacing, antialiasing, text hierarchy, wrapping, truncation, display-vs-body optical treatment, cramped text, and places where text spacing makes the UI feel broken or harder to scan.
+- Spacing and layout: compare frame/crop, alignment, margins, padding, gaps, component sizes, radii, elevation, borders, and vertical rhythm. Cite where spacing drift changes hierarchy, density, readability, or causes elements to collide.
+- Viewport resilience: check desktop, tablet, and mobile widths for overlapping elements, clipped content, collapsing sections, broken grids, awkward wrapping, and controls that become unusable.
+- Colors and tokens: compare palette, gradients, opacity, shadows, contrast, semantic status colors, disabled/active states, and whether implementation tokens map to design intent.
+- Image quality and asset fidelity: check subject match, crop, scale, aspect ratio, sharpness, compression, transparency/masking artifacts, halos, background integration, and raster-vs-vector suitability. Div/CSS art or custom SVG art that replace images in the target design are banned.
+- Copy and content: for any copy that is part of the app, not dynamic content, check that it is coherent, makes sense in the standalone context of the app, and is visually appealing.
+- Icons: zoom in and analyze all visible icons and icons hidden behind controls/interactions to ensure they are fully implemented, aligned, and visually consistent.
+- States and interactions: expand/collapse sidebars, tooltips, forms, hover, focus, active, selected, disabled, loading, success, error, empty states, and any interactive controls needed for a functional frontend.
+- AI shortcut artifacts: flag generic rounded cards, unnecessary borders, decorative CSS blobs, fake SVG illustrations, half-built avatars, mismatched hero art, and custom CSS/SVG replacements where the target called for real imagery, real icons, or a different surface treatment.
+
+### Accessibility
+
+- Contrast, focus indicators, keyboard reachability, semantic controls, labels, alt text, reduced motion.
+- Text scaling and zoom resilience.
+- Tap targets at practical mobile sizes.
+- Layout stability when text wraps, scales, or appears in longer real-world strings.
+
+## Finding Quality
+
+A useful finding includes:
+
+- One specific mismatch or flaw.
+- Design evidence and implementation evidence.
+- User or fidelity impact.
+- Concrete fix, ideally with file/component/token/CSS guidance.
+- Severity based on user impact, not personal taste.
+- The affected fidelity surface when relevant: fonts, spacing, colors, image quality, layout, behavior, accessibility, content, icons, or responsiveness.
+- Crammed text, broken wrapping, mismatched font weights, bad line height, or awkward letter spacing when they affect readability or hierarchy.
+- Elements that overlap, clip, collapse into nearby sections, or break at alternate viewport sizes.
+- Rounded cards, borders, shadows, or container treatments that appear in the implementation but are not present in the target.
+- Borked icons, custom SVGs, half-assed attempts at avatars, hero art mismatches, custom CSS art, and placeholder-looking generated assets.
+- Overflowing text, cramped text, broken layout, missing states, and incomplete interactions.
+
+Avoid:
+
+- Vague statements such as "make it more polished."
+- Criticizing known placeholder content unless it affects the design goal.
+- Treating every pixel difference as a bug when the design intent is preserved.
+- Mixing multiple unrelated flaws into one finding.

package/template/.codex/skills/product-design/skills/get-context/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: get-context
+description: "Mandatory design-brief gate for Product Design build and design workflows. Use before ideation, prototyping, image-to-code builds, redesigns, or product UI work to clarify missing product, visual, and interactivity context or play back the supplied brief before proceeding."
+---
+
+# Get Context
+
+Gather only the context needed for the next design action. This skill resolves or confirms the design brief; it does not implement UI or create durable design artifacts.
+
+Run this skill at the start of Product Design requests that ask to design, build, prototype, clone, redesign, extend, or generate product UI directions.
+
+Use question mode when any of the following are unclear:
+
+- what product, site, feature, workflow, component, or screen is being designed
+- what visual source should determine how it looks
+- what concrete preferences or avoidances should shape visual exploration when no source exists
+- what level of interactivity the user expects
+
+Use playback mode when the user already provided the needed details. In playback mode, do not re-ask answered questions; play back the brief in a pithy format and name the next workflow.
+
+Hard boundary: do not implement UI, scaffold a prototype, start a server, or create files while context is still missing.
+
+## Critical Overrides
+
+- Refer to the Plugin router [$index](../index/SKILL.md) before proceeding.
+- Follow [$critical-overrides](../../references/critical-overrides.md).
+
+## User Context
+
+Before starting, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+
+Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets as grounding material when relevant.
+
+Do not inspect every saved reference. Inspect only what the current task needs.
+
+## Get Context Script
+
+The following three questions should be answered by the user. Adapt the questions based on what the user has provided so far in the conversation. If some or all fields are already known, skip the questions and summarize the design brief in your own words.
+
+The questions to answer are:
+
+> What do you want the thing to do?
+
+> What existing product, design system, Figma file, screenshot, URL, image, or other visual source should it match? If none, what look are you going for? Mention existing design systems already in user-context if they exist.
+
+> What level of interactivity should the thing have?
+
+One of:
+
+- Full interactivity: all controls and states are completely functional and implemented.
+- Static: controls and states are minimally interactive, preferring speed.
+
+After the questions, reply with a pithy design brief that summarizes what you're about to explore. Avoid walls of text at all costs. Be clear and concise.
+
+Example script to follow:
+
+```
+Before I build, the Product Design workflow needs a quick design brief.
+
+What should the login page do? Email/password only, magic link, SSO, sign-up link, forgot password?
+Do you have an existing design system, app, Figma, or screenshot to match?
+If not, what look are you going for?
+Interactivity level: full working form states, or a faster mostly-static mock?
+
+```
+
+## Final message
+
+1. Before proceeding to `$ideate`, `$prototype`, `$url-to-code`, or `$image-to-code`, confirm the design brief by explaining it back to the user in a pithy format as a `final` message.
+
+2. Proceed only after the user confirms the design brief, unless the current thread already contains confirmation of that exact brief. If the user provides feedback, continue to refine the design brief with them.
+
+3. After the user confirms the design brief, send one short expectation-setting note before starting an involved app, prototype, clone, redesign, or build. Example confirmation message with expectations setting:
+
+```text
+Lovely, brief locked. This kind of build usually takes about 10-15 minutes, and ambitious ones can take longer. Good moment to grab coffee or tend to something else; I'll keep moving and bring the prototype back when it is ready.
+```
+
+Do not send this note for tiny static changes, quick audits, simple research, setup-only, or share-only requests.
+
+Done means the user has confirmed the design brief.

package/template/.codex/skills/product-design/skills/get-context/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Get Context"
+  short_description: "Confirm the Product Design brief before design or build work"
+  default_prompt: "Confirm the design brief for this Product Design task before the next workflow starts."
+policy:
+  allow_implicit_invocation: true

package/template/.codex/skills/product-design/skills/ideate/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: ideate
+description: "Generate image-based visual alternatives, remixes, or concept directions after Product Design get-context has confirmed the design brief. Use when the user asks for design variants, visual exploration, remixes, or image-generated approaches from provided context."
+---
+
+# Ideate
+
+You're tasked with generating design concepts for a user's idea.
+
+Follow the shared Product Design routing guidance in [$index](../index/SKILL.md).
+
+## Critical Overrides
+
+- Refer to the Plugin router [$index](../index/SKILL.md) before proceeding.
+- Follow [$critical-overrides](../../references/critical-overrides.md).
+
+## User Context
+
+Before starting, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+
+Attach provided product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets to the Image Gen generations to align them to the design brief.
+
+Do not inspect every saved reference. Inspect only what the current task needs.
+
+## Workflow
+
+Do not generate images until `$get-context` has played back and confirmed the design brief for this exact request. If this skill was invoked directly and the current thread does not already contain that confirmed brief, route to [$get-context](../get-context/SKILL.md) first.
+
+Before generating images:
+
+1. Understand the brief.
+
+- Identify the target: component, screen, feature/workflow, or broad product idea.
+- Identify the intended user, product surface, and goal.
+- Preserve hard constraints from the user.
+- Run `get-context` if the brief has not already been played back and confirmed.
+
+2. Resolve context.
+
+- Use provided files, screenshots, links, and visible references.
+- In a local workspace, look for nearby design documentation and other local visual context.
+- Check likely design context folders such as `user-context`, `storybook/`, `.storybook/`, `design-system/`, `design-systems/`, `tokens/`, `components/`, `app/`, and generated prototype roots.
+- In an existing project, look for existing product screenshots, similar flows, Storybook captures, design tokens, and component references before generating. Ask if the user can provide example screens similar to the one they are building if the existing app isn't accessible. Ensure you add design language and tokens to the Image Gen prompt.
+
+3. Inspect references directly.
+
+- Look at screenshots, images, Figma frames, app surfaces, or other visual references before generating.
+- Do not infer from filenames alone.
+- If a named local path or reference is not visible, stop and ask the user to confirm the path, upload the file, start the local app, or point to the correct workspace.
+
+4. Decide the variation mode.
+
+- If useful local design context exists and the user has not asked for a new style, stay within that existing direction.
+- If no useful design context exists, or the user asks for broad exploration, vary both concept and visual system.
+- For a specific component or existing surface, vary structure, interaction, hierarchy, and emphasis before varying brand style.
+- For a broad product idea, explore three meaningfully different product directions.
+
+5. Choose target dimensions before Image Gen.
+
+- Pick the dimensions that best match the user's request and any provided visual reference.
+- Mobile app: `390 x 844`.
+- Tablet app: `834 x 1194`.
+- Desktop app, dashboard, admin, or SaaS: `1440 x 1024`.
+- Landing or marketing page: `1440` wide and scrollable.
+- Modal, panel, widget, or component: natural container size.
+- Provided screenshot, Figma frame, mockup, or reference image: match its dimensions and aspect ratio when the user wants to continue from that visual.
+- Avoid crowding. Make the design fit the chosen dimensions cleanly, with realistic spacing, readable type, and no clipped content.
+- Include the chosen dimensions in every Image Gen prompt.
+
+6. Check for access gaps.
+
+- If a connector, reference, or file cannot be accessed because of auth, permissions, expired login, missing scope, suspiciously empty results, or unavailable local state, stop.
+- Name the gap clearly and ask whether to troubleshoot access or continue without that source.
+- Do not generate images while silently ignoring a named reference.
+
+7. Ask only if context is too thin.
+
+- Ask one targeted question only when available context is insufficient to generate useful directions.
+- Prefer asking about style direction, target audience, or the reference surface.
+
+8. Attach images and mocks provided by the user to the Image Gen call along with your design brief.
+
+9. Generate 3 independent options that have distinct information hierarchy, layout strategy, interaction model, or product framing.
+
+Rules you must follow:
+
+- Use the Image Gen prompt below.
+- Use the built-in Image Gen tool.
+- Generate exactly three independent images unless the user overrides the count.
+- Generate options in parallel when possible.
+- Each option must be its own Image Gen result. Do not put multiple ideas in one image.
+- Attach provided screenshots, files, app captures, Figma references, and visual source material as moodboard inspiration when available.
+- Attach existing product screenshots, similar flows, Storybook captures, design tokens, and component references as grounding material when available.
+- If a screenshot, image, or visual file is available, attach the actual image to the Image Gen call. Do not rely on text descriptions of it.
+- Only claim a visual reference was attached if the Image Gen call actually received that image or a readable local image path.
+- If you cannot attach the image, say that clearly and ask whether to continue with text-only direction.
+- Preserve hard constraints from the brief in every image.
+- After generating options, stop for the user's selection before any build work begins.
+- The selected option is the visual target for `$image-to-code`.
+
+## Feedback Loop
+
+If the user gives feedback after seeing options, generate revised options with that feedback.
+
+If the user selects an option and gives feedback, generate a revised option with that feedback before build.
+
+If the user likes parts of more than one option, combine those choices into a new Image Gen design and show it before build.
+
+## Image Gen Prompt
+
+Adapt this prompt to the confirmed design brief, attach any available image references, and send it to Image Gen:
+
+```text
+Create realistic, production-quality UI designs with clear hierarchy, strong typography, intentional imagery, and purposeful spacing.
+
+Keep the design simple. Avoid busy interfaces. Every section should have a clear purpose, and every element should earn its place.
+
+Prioritize clarity, whitespace, and usability over decorative complexity.
+
+### Target Dimensions
+
+Pick the dimensions that best match the user's request and any provided visual reference.
+
+ - Mobile app: `390 x 844`
+ - Tablet app: `834 x 1194`
+ - Desktop app, dashboard, admin, or SaaS: `1440 x 1024`
+ - Landing or marketing page: `1440` wide and scrollable
+ - Modal, panel, widget, or component: natural container size
+ - Provided screenshot, Figma frame, mockup, or reference image: match its dimensions and aspect ratio when the user wants to continue from that visual
+
+Avoid crowding. Make the design fit the chosen dimensions cleanly, with realistic spacing, readable type, and no clipped content.
+
+### Layout
+
+When deciding how to lay elements out on the page, this should be your priority order for tools to differentiate sections:
+
+1. Use spacing, grouping, alignment, typography, and hierarchy on the same product surface.
+2. Use simple dividers or row separators.
+3. Use a subtle surface tint only when the base surface is not enough.
+4. Use borders only when separation still is not clear.
+5. Use shadows/elevation last, and sparingly.
+
+Don'ts:
+ - Do not default to a centered "app card" (the whole UI is in a card on the page) on top of a contrasting page background. Use the base page surface first unless the source product or user explicitly asks for a contained app panel.
+ - Do not put cards inside cards. Do not make every major section a card. Do not make each list item its own card unless each item is truly a standalone object. A normal list should usually read as one grouped surface with lightweight row separation.
+ - Do not make up extraneous features. Add only the things essential to accomplish what the prototype's goal is. Don't make up more features just to fill out a UI.
+
+### Typography
+
+ - Anchor UI typography to readable product sizes. Body text should usually sit between 14px and 16px, with the rest of the type scale built around that baseline.
+ - Keep long-form text to a comfortable line length, generally no more than 65 characters per line.
+ - Use no more than 2 fonts in a UI. You can use any font available in the project, or fonts provided free on Google Fonts. Pick the font that is best for the goal of the product and that matches with its intended look and feel.
+
+### Presentation
+
+ - Do not add browser or device chrome around the mockup.
+ - Do not put multiple ideas into a single image generation.
+ - Vary each idea as much as possible while adhering to the constraints given entirely.
+```
+
+## Output
+
+After generation, provide
+
+1. A short, memorable name for each concept that distills its choices down.
+
+2. A short closing question that asks whether the user wants to keep exploring or choose one direction to continue.
+
+If the image tool already displayed the generated images in the thread, do not embed the same images again in the final message.
+
+If the image tool did not display the generated images, include one image per option.
+
+Do not show the same generated image twice.
+
+Example closing question:
+
+> Want to explore more directions, or should I build one of these? If one works, tell me 1, 2, or 3.
+
+Done means the requested number of independent images was generated and the user has been asked to select one.

package/template/.codex/skills/product-design/skills/ideate/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Ideate"
+  short_description: "Generate visual directions after brief confirmation"
+  default_prompt: "Confirm the design brief, then create visual design directions for this product idea."
+policy:
+  allow_implicit_invocation: true

package/template/.codex/skills/product-design/skills/image-to-code/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: image-to-code
+description: "Implement a selected image, screenshot, mockup, or Image Gen reference as a faithful responsive frontend after Product Design get-context has confirmed the design brief."
+---
+
+# Image to Code
+
+You're tasked with translating the visual target image into a high-quality, interactive website or web app.
+
+## Critical Overrides
+
+- Refer to the Plugin router [$index](../index/SKILL.md) before proceeding.
+- Follow [$critical-overrides](../../references/critical-overrides.md).
+
+## User Context
+
+Before starting, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+
+Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets as grounding material when relevant.
+
+Do not inspect every saved reference. Inspect only what the current task needs.
+
+## Workflow
+
+CRITICAL: THIS IS NOT GUIDANCE. THIS IS A CHECKLIST TO COMPLETE.
+
+0. Do not start unless `$get-context` has played back and confirmed the design brief for this exact request. If this skill was directly at-mentioned without a clear visual target or the current thread does not already contain a confirmed brief, route to [$get-context](../get-context/SKILL.md) first.
+
+1. Do not start unless you have a selected image, screenshot, mockup, or Image Gen result to recreate. A written brief is not enough.
+
+2. Treat the provided image as the design to recreate.
+
+3. If the provided design is a mobile viewport, build a mobile app. If it's unclear, default to desktop.
+
+4. Review the reference design, catalog every image asset in the design, and use the Image Gen tool to create individual images for each one. Zoom in so you can catch every asset that needs to be generated.
+
+    Examples include:
+
+    - Hero images including full bleed image backgrounds
+    - Featured article imagery
+    - Thumbnails
+    - Decorative illustrations
+    - Textures and background motifs
+    - Logos
+    - Product images
+    - Avatars
+
+    Rules:
+
+    - CRITICAL RULE: Do not create custom div art, CSS art, inline SVGs, handcrafted SVGs, HTML element drawings, div/span shapes, CSS drawings, gradients, emoji, or text glyphs instead of real icons and image assets ever. Use the built-in Image Gen tool for images and the closest matching icon library for icons.
+    - If text is part of an image asset, keep it in the image asset. Examples include full bleed hero images, signs, posters, packaging, storefronts, article art, and illustrations where the type belongs to the visual itself. Do not crop the background image and recreate that text with transparent text boxes, HTML, CSS, or separate overlay layers unless the source clearly shows editable UI text sitting on top of the image.
+    - Do not use generic placeholders where the reference implies custom visual content.
+    - Generated assets must share the same art direction, palette, rendering style, and design language as the reference mockup.
+    - The built-in Image Gen tool does not support transparent images; post-process generated assets when transparency is required.
+
+5. Define all sections of the page. For each section, meticulously measure the layout, spacing between elements, and the size and space of the elements themselves.
+
+6. Find freely available fonts that match the target design.
+
+7. Find a freely available icon library that matches the target design. Do not default to Lucide icons. Search for the best match.
+
+    Rules:
+
+    - CRITICAL RULE: Do not create custom inline SVGs, handcrafted SVGs, HTML element drawings, div/span shapes, CSS drawings, gradients, emoji, or text glyphs. Use the built-in Image Gen tool to generate assets and use the closest matching icon library for icons.
+
+8. Build the app starting with [local-prototype-preflight](../../references/local-prototype-preflight.md). Build all interactions, ensuring the app is complete, functional, and interactive: all controls and states activated and functional.
+
+    Examples include:
+
+    - Header, sidebar, tooltip, and modal interactions
+    - Hover and focus states
+    - Responsive navigation
+    - Clickable cards and buttons
+    - Animated affordances if implied by the design
+    - Newsletter forms, tags, filters, or navigation elements shown in the mockup
+    - Bring the thing to life. Do not deliver a static site; the less you do, the more the designer has to add.
+
+    Rules:
+
+    - Place every image asset you generated into its position before proceeding. I repeat, replace all placeholders, including CSS/SVG placeholders, before proceeding.
+    - Do not leave visible controls as static chrome. Do not create new pages or routes unless the user asks for them.
+
+9. Run the local app.
+
+10. Capture the local app using [browser-order](../../references/browser-order.md).
+
+11. Run [design-qa](../design-qa/SKILL.md) as the blocking build gate.
+
+    Steps:
+
+    - Open the reference image and the latest prototype screenshot before writing the QA report.
+    - Compare the same viewport and the same interaction state. If they do not match, capture the missing view first.
+    - Save the QA report as `design-qa.md` in the project root.
+    - Fix P0/P1/P2 issues, capture the app again, and repeat until the QA report says `final result: passed`.
+    - Do not keep looping on P3 polish. Include any remaining P3s as follow-up iteration notes.
+    - If source capture, prototype capture, or visual comparison is blocked, stop. `design-qa.md` must say `final result: blocked`.
+    - Do not hand off unless `design-qa.md` exists and says `final result: passed`.
+
+12. Handoff the app or website.
+
+    - Only hand off after [design-qa](../design-qa/SKILL.md) passes.
+    - Keep the prototype running locally.
+    - Provide the clickable local URL.
+    - Briefly describe the work as a designer would.
+    - Include the post-build iteration and share nudge from [critical-overrides](../../references/critical-overrides.md#build-handoff).

package/template/.codex/skills/product-design/skills/image-to-code/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Image To Code"
+  short_description: "Build a responsive frontend from a selected visual target after brief confirmation"
+  default_prompt: "Confirm the design brief, then build this selected design as an interactive frontend."
+policy:
+  allow_implicit_invocation: true

package/template/.codex/skills/product-design/skills/index/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: index
+description: "Use to discover specific skills for the Product Design plugin, when it is at-mentioned directly, or for any mentions of potentially relevant work, including: UX research; product, screen, or flow audits; visual ideation; app or interface design, redesign, cloning, prototyping, or implementation from ideas, URLs, images, Figma, or code; design QA; and prototype sharing or deployment."
+---
+
+# Skill Purpose
+
+Route Product Design requests to the right Product Design skill. Treat an `@Product Design` mention, direct Product Design invocation, or broad request like "design this app", "build a prototype", "audit this flow", "research this product", or "share this prototype" as intent to use this plugin.
+
+# Plugin Purpose
+
+The Product Design plugin helps designers and other non-coders close the gap between product ideas and working software.
+
+The Product Design plugin equips you with the following set of skills to:
+
+- Research ideas and pain points related to your product.
+- Conduct product-flow audits.
+- Generate distinctly new ideas for your product with ImageGen.
+- Clone existing product apps into lightweight prototypes.
+- Build lightweight or interactive prototypes to share with your team.
+
+## Communication Style
+
+Speak to the user in a warm, fun, and collaborative way, prioritizing pithy explanations over long walls of text and numerous bullet points. Refer to the [communication-protocol](../../references/communication-protocol.md) for relaying Product Design plugin progress updates and handoff.
+
+## Critical Overrides
+
+- Follow [$critical-overrides](../../references/critical-overrides.md).
+
+## Router Only
+
+This index routes Product Design requests; it does not satisfy focused workflows itself.
+
+When a request matches `$user-context`, `$get-context`, `$research`, `$ideate`, `$prototype`, `$image-to-code`, `$url-to-code`, `$audit`, `$design-qa`, or `$share`, load the focused skill and follow it.
+
+For visual ideation requests, load `$get-context` first, then `$ideate`.
+
+## No Visual Target, No Build
+
+For new app, prototype, redesign, or UI build requests without a URL, screenshot, Figma frame, mockup, source image, or existing code target:
+
+- Run `$get-context`.
+- After the brief is approved, route to `$ideate`.
+- Show exactly three visual options and wait for the user to choose one.
+- Do not scaffold, edit files, or start a server before a visual option is selected.
+
+`Full working version`, `no refs`, `go for it`, `make an assumption`, or a confirmed brief do not waive this.
+
+## User Context
+
+Use [$user-context](../user-context/SKILL.md) when the user asks to:
+
+- Set up Product Design
+- Get started with Product Design
+- Onboard with Product Design
+- Save product or design sources
+- See what Product Design remembers
+- Update saved product or design context
+- Remember a Product Design preference
+- Setup my plugin
+
+Adjust the context-gathering request to match the user's request. First-time setup differs from updating existing context.
+
+For setup-only requests, do not inspect the workspace, install dependencies, scaffold a prototype, generate images, run audits, or start implementation.
+
+When answering "what can you do?", "how do I get started?", or similar broad Product Design questions, end by asking whether the user wants to set up saved context.
+
+Use this close:
+
+```text
+Want to onboard Product Design with your context? Send product URLs, Figma files, screenshots, codebase paths, Storybook links, tokens, brand assets, or preferred share targets, and I'll save them for future work.
+```
+
+Before routing to Product Design workflows, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+
+## Browser Annotation Updates
+
+Treat annotations as scoped edits to the current prototype.
+
+Read the annotation, its target, and the surrounding screen before changing code. Preserve the existing prototype by default: layout, style, content, routes, assets, interactions, and working behavior stay the same unless the annotation asks to change them.
+
+Do not redesign nearby UI or rebuild the prototype just because an annotation touches that area. If the annotation is ambiguous and the choice would materially change the prototype, ask first.
+
+## Skills
+
+Use this as the root routing guidance for Product Design plugin work. If several focused skills apply, sequence them in the order that creates the most useful design workflow. Keep this index as a router; do not perform focused workflow logic here.
+
+### $user-context
+
+Preflight, save, or answer from Product Design setup context. Route here before Product Design workflows to load saved product and design sources, and for direct setup, get-started, onboarding, save, remember, recall, inspect, or customization requests. This skill owns Product Design plugin-scoped context and preference policy.
+
+### $get-context
+
+Route here first for design, build, prototype, redesign, extend, or UI exploration work. If details are missing, ask only for the missing product, visual, or interactivity context; if details are already present, play back the brief before proceeding. Confirm the design brief back to the user before Product Design ideation or implementation.
+
+### $research
+
+Run fast, source-grounded UX research on current user problems for a named digital product. Route here for researching user pain, UX friction, onboarding issues, docs/help problems, developer experience friction, support pain, product workflow issues, or current user complaints.
+
+### $audit
+
+Capture and review a product flow, journey, screen, or multi-step product experience from screenshots. Route here for user-facing audit, critique, review, inspect, assess, or UI evaluation requests. It reports UX, design, and accessibility findings tied to captured evidence; do not use `design-qa` for user-facing audits.
+
+### $ideate
+
+Generate image-based visual alternatives, remixes, or concept directions for a component, screen, feature, workflow, or product idea. Route here after `get-context` has confirmed the design brief and the user needs visual exploration, design variants, alternatives to an existing design, or idea discovery before choosing a visual target. Prefer this over prose-only ideation unless the user asks for prose.
+
+### $prototype
+
+Route coded prototype, redesign, clone, and UI build requests to the right Product Design workflow. Route here after `get-context` has confirmed the design brief and the user asks to build from a URL, image, mockup, Figma source, existing codebase, or product idea.
+
+### $url-to-code
+
+Clone a live URL as a runnable frontend-only local app using Browser or Chrome source evidence. Route here after `get-context` has confirmed the brief and the user provides a production URL for a faithful local prototype or clone. It should not modify production code; use `prototype` first when source selection is still unclear.
+
+### $image-to-code
+
+Implement a selected visual target as a faithful, responsive, interactive frontend. Route here after `get-context` has confirmed the brief and the user has chosen an ImageGen mock, screenshot, Figma frame, mockup, reference image, or other visual source. Do not start here when no visual target has been selected; use `get-context` and `ideate` first.
+
+### $share
+
+Deploy a runnable prototype and return a shareable URL using the user's preferred target when available. Route here when the user asks to share, deploy, publish, host, create a link, or make a prototype shareable with `@Sites`, `@Vercel`, or another deployment tool.
+
+### $design-qa
+
+Compare a coded Product Design prototype against its source visual target before handoff. Route here only as an internal helper after a prototype, URL-to-code build, or image-to-code build has both a source visual and rendered implementation. Do not route broad UX critiques, audits, or product-flow reviews here; use `audit` instead.

package/template/.codex/skills/product-design/skills/index/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Product Design"
+  short_description: "Primary entrypoint for Product Design setup, brief confirmation, research, audits, ideation, prototypes, URL clones, image-to-code builds, QA, and sharing."
+  default_prompt: "What can Product Design do?"
+policy:
+  allow_implicit_invocation: true