create-yss-spec 1.1.2 → 1.1.3

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

@@ -0,0 +1,92 @@
+---
+name: research
+description: "Run fast, source-grounded UX research on the highest-signal problems users are experiencing with a user-specified digital product. Use when the user asks to research user pain, UX friction, onboarding issues, docs/help problems, developer experience friction, support pain, product workflow issues, or current user complaints for a named product."
+---
+
+# Research
+
+Run a fresh UX research scan for the product the user specifies.
+
+Focus on current, evidence-backed user problems. Prioritize logged-in product experience, self-serve flows, onboarding, docs/help, developer experience, support friction, and product workflows.
+
+## 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.
+
+## Contract
+
+- Restate the product, audience, time horizon, and research scope before scanning.
+- Use public sources by default. Use internal sources when the connectors are available and the user request allows it.
+- Cite sources wherever available.
+- Separate observed evidence from inference.
+- Do not overclaim from anecdotes.
+- Do not return a dump of complaints. Tell a clear product story.
+- Say clearly when source access is missing or weak.
+
+## Workflow
+
+1. Restate the research scope.
+
+2. Search public sources:
+
+- Reddit
+- X/Twitter
+- Hacker News
+- Stack Overflow
+- GitHub issues/discussions
+- forums, blogs, reviews, YouTube comments, and developer communities where relevant
+
+3. Search internal sources when available:
+
+- Slack
+- Gong
+- Notion
+- Google Drive/docs
+- Linear/Jira/GitHub
+- support or CRM notes if available
+
+4. Cluster evidence into the highest-signal UX problems.
+
+5. Separate:
+
+- product UI/workflow friction
+- docs/help friction
+- onboarding friction
+- account, billing, permissions, or setup friction
+- developer/API/SDK friction
+- reliability/performance issues
+- feature requests
+
+6. Rank problems by severity, frequency, confidence, and product leverage.
+
+7. Tell a clear product story.
+
+## Output
+
+Default to an in-chat research brief unless the user asks for another format.
+
+Include:
+
+- Executive read: the core story in 5-7 sentences.
+- Ranked UX problems: for each problem, include the problem, user goal, surface, what breaks, evidence, severity, frequency signal, confidence, and recommended product move.
+- Source map: what was searched, what each source contributed, and where signal was weak.
+- Opportunity map: group recommendations into fix this week, fix this quarter, and needs deeper research.
+
+## Rules
+
+- Use citations wherever available.
+- Do not overclaim from anecdotes.
+- Separate loud complaints from frequent problems.
+- Separate UX friction from missing features.
+- Separate reliability/performance issues from UX workflow issues.
+- Mark internal-only evidence separately from public evidence.
+- Keep the brief sharp, specific, and easy to consume.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Research"
+  short_description: "Research UX pain and workflow friction for a digital product"
+  default_prompt: "Research user pain and workflow friction for this product."
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,41 @@
+---
+name: share
+description: "Share a runnable prototype using the user's preferred deployment tool."
+---
+
+# Share
+
+Deploy the user's runnable prototype so they can share it with others.
+
+## 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
+
+1. Confirm the prototype directory and the user's preferred deployment target.
+2. If the user invokes Product Design with @Sites, @Vercel, or another deployment tool, treat that as the selected hosting target.
+3. If the user did not choose a target, ask one question:
+
+> Where should I deploy this: @Sites, @Vercel, or another target?
+
+4. Use the selected deployment tool when it is available.
+5. If the selected tool is not available, say that clearly and ask whether to use another target.
+6. Run the deployment when possible. Do not give setup instructions if you can complete the deployment directly.
+7. Return the shareable URL.
+8. State any misses or manual follow-up the user still needs to do.
+
+## Rules
+
+- Do not deploy before the user chooses or confirms the target.
+- Do not claim the prototype is shared until you have a working URL.
+- If the selected tool is not available, say that clearly and ask whether to use another target.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Share"
+  short_description: "Deploy a runnable prototype and return a shareable URL"
+  default_prompt: "Share my runnable prototype."
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,124 @@
+---
+name: url-to-code
+description: "Clone a live URL as a runnable frontend-only local app using Browser/Chrome source evidence after Product Design get-context has confirmed the design brief."
+---
+
+# URL To Code
+
+Clone `<target-url>` as a real interactive, frontend-only local app or website. The clone should look and interact like the source.
+
+## 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
+
+0. Do not start unless `$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.
+
+1. CRITICAL STEP: Warn the user that they must follow the target website's terms before proceeding. This workflow is only for apps and websites the user owns, or has permission to recreate.
+
+2. Open the source URL using [browser-order](../../references/browser-order.md).
+
+3. Check that the page is correct.
+
+- Do not continue if it shows the wrong page, a blocked page, a login page, a promo page, a loading screen, an error page, an app-install page, or an unrelated redirect.
+- If the page is wrong, try again with another available browser.
+- If every browser shows the wrong page, stop and tell the user what you can see.
+
+4. Capture the source page carefully.
+
+- Start at the top of the page.
+- Scroll down in small steps.
+- At each step, capture what is visible.
+- Note any new sections, controls, sticky elements, animations, or lazy-loaded assets.
+- Continue until the full page has been seen.
+- Scroll back to the top and check whether anything changed.
+- Repeat on mobile at `390 x 844`.
+
+5. Use the browser DOM tools to gather everything needed to recreate the source.
+
+- Elements
+- Components
+- Text
+- Links
+- Buttons and controls
+- States
+- Images
+- Icons
+- Fonts
+- Videos
+- SVGs
+- Style sheets
+- Colors
+- Spacing
+- Layout sizes
+- Responsive behavior
+
+6. Find and test the page interactions.
+
+- Use the screenshots and browser DOM tools to find visible controls.
+- Include navigation, buttons, links, inputs, menus, drawers, modals, tabs, carousels, hover states, sticky elements, and anything else the user can interact with.
+- Test one control at a time.
+- Return to the starting state before testing the next control.
+- Save the result when the page visibly changes or the browser tools show a state change.
+
+7. Copy the real assets from the source page.
+
+- If the page loads the asset, treat it as available unless the browser cannot access or save it.
+- If an image, logo, icon, font, video, SVG, sprite, mask, cursor, or background image is used by the page, copy it locally.
+- If an image asset cannot be copied, generate a replacement with ImageGen using a screenshot of the original.
+- If a font file cannot be copied, use the closest open source font match.
+- If an icon or glyph cannot be copied, use the closest matching open source icon set. Do not default to Lucide unless it is the closest match.
+- Briefly note any asset, font, or icon you replaced and why.
+
+8. Create the local app with [local-prototype-preflight](../../references/local-prototype-preflight.md).
+
+9. Build only from what you captured, copied, or gathered from the source.
+
+- Do not add new visual ideas.
+- Do not use hotlinked source assets.
+- Do not guess when source proof is available.
+
+10. Run the local app.
+
+11. Compare the local app against the original.
+
+- Check desktop.
+- Check mobile.
+- Check every interaction you captured.
+- Fix any obvious mismatch before running final QA.
+
+12. Run [design-qa](../design-qa/SKILL.md) as the blocking build gate.
+
+- 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`.
+
+13. 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).
+
+## Hard Rules
+
+- Capture source evidence first. Do not scaffold, write app code, start a server, or create the local prototype until desktop capture, mobile capture, key states, and every required asset, icon, control mark, and font is captured or replaced.
+- Do not hand off until every single interaction and state is captured from the target.
+- Do not build from memory, screenshots alone, guessed CSS, generic assets, or prior chats.
+- Do not implement a saved state without source screenshot plus the available DOM/style/layout evidence for that state.
+- Do not use hotlinked source assets in the final app.
+- Do not create temporary CSS icons, text glyphs, emoji marks, placeholder blocks, or handmade SVGs while "waiting" to resolve assets. Resolve assets first, then build.
+- If Browser and Chrome fail, ask before using Playwright. If no approved tool can capture valid source and prototype evidence, stop and report the design-qa blocker.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "URL To Code"
+  short_description: "Clone a live URL into a runnable frontend prototype after brief confirmation"
+  default_prompt: "Confirm the design brief, then clone this URL as a runnable frontend prototype."
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,147 @@
+---
+name: user-context
+description: Load or manage Product Design's saved user context. Use when the user asks to set up Product Design, get started, onboard, save product or design sources, see what Product Design remembers, update saved context, or remember Product Design preferences. Examples include product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, and general product/design notes.
+---
+
+# User Context
+
+User Context stores the product and design references a designer uses often, so future Product Design work starts from the right sources.
+
+Use this skill 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
+
+## Critical Overrides
+
+- Refer to the Plugin router [$index](../index/SKILL.md) before proceeding.
+- Follow [$critical-overrides](../../references/critical-overrides.md).
+
+## Saved User Context
+
+If `user-context.md` exists, use it by default.
+
+Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets to ground Product Design work.
+
+Ideation, prototypes, audits, clones, and critiques should match the saved product context unless the user asks for something different.
+
+When a workflow needs visual grounding, attach or include relevant saved screenshots, reference images, tokens, design language, and component references in ImageGen, ideation, prototype, audit, and critique work.
+
+## State File
+
+Saved context lives here:
+
+```text
+$CODEX_HOME/state/plugins/product-design/user-context.md
+```
+
+Saved screenshots and reference images live next to it:
+
+```text
+$CODEX_HOME/state/plugins/product-design/assets/
+```
+
+If the file does not exist, continue normally unless the user asks to set up Product Design, save context, or the current task is blocked by missing product/design context.
+
+## Preflight
+
+When any Product Design workflow needs saved context, run:
+
+```bash
+python3 scripts/user_context_preflight.py
+```
+
+Use the returned saved entries as the starting context for the task.
+
+If the script reports that no saved context exists, continue from the current user prompt unless setup context is required.
+
+Do not browse, open, or inspect every saved reference during preflight. Inspect only the saved references needed for the current task.
+
+## Setup
+
+Use [references/onboarding.md](references/onboarding.md) when the user asks to set up Product Design, asks what Product Design can remember, asks what Product Design knows about their product, or provides product/design references to save.
+
+For setup-only requests, explain what Product Design can remember and ask for useful sources.
+
+Adjust the context-gathering request to match the user's request. First-time setup differs from updating existing context.
+
+Do not inspect the workspace, install dependencies, scaffold a prototype, generate images, run audits, or start implementation during setup.
+
+After the user provides references to save, run:
+
+```bash
+python3 scripts/init_user_context.py
+```
+
+Then add the references to the created `user-context.md`.
+
+## Save
+
+Save useful, durable Product Design context:
+
+- Product URLs
+- Figma files
+- Screenshots and reference images
+- Codebase paths
+- Storybook and component docs
+- Design tokens and theme sources
+- Brand, logo, icon, illustration, image, and asset sources
+- Preferred browser, capture tools, and share targets
+- Team conventions that make future Product Design work more accurate
+
+When the user provides screenshots or reference images to save, copy them into `assets/` next to `user-context.md` and link them from the saved entry.
+
+Give each saved image a clear, descriptive filename that says what the image shows. Use names future Product Design runs can understand without opening the file.
+
+Good image names:
+
+```text
+assets/chatgpt-settings-modal-dark-mode.png
+assets/payment-sheet-mobile-error-state.png
+assets/product-dashboard-sidebar-navigation.png
+assets/storybook-primary-button-states.png
+assets/brand-logo-lockup-purple-gradient.png
+assets/onboarding-flow-welcome-step.png
+assets/checkout-confirmation-screen.png
+assets/account-menu-open-state.png
+```
+
+Do not save secrets, credentials, API keys, private tokens, copied customer data, or anything that should not persist.
+
+Use this structure:
+
+```md
+# {Category}
+
+- Description: {what this category is and when future Product Design runs should use it}
+
+## Saved Links And Context
+
+{Saved reference or fact}
+- Date Added: YYYY-MM-DD.
+- File: assets/{clear-descriptive-name}.png
+- Useful Context: {what this reference represents}
+- Future Use: {how future Product Design work should use it}
+```
+
+Include `File:` only when the saved entry has a local image file.
+
+When a category has no saved references yet, use exactly:
+
+```md
+status: not provided
+```
+
+Keep saved context curated. Prefer a few high-value references over a dump of every possible URL or file.
+
+## Read
+
+- Do not treat `status: not provided` as a fact.
+- Read through `scripts/user_context_preflight.py` when local shell access is available.
+- Use saved context as default grounding, then inspect only what the current task needs.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "User Context"
+  short_description: "Save and read Product Design user context"
+  default_prompt: "Set up Product Design with my product URLs, Figma files, screenshots, codebase paths, Storybook, tokens, and brand assets."
+policy:
+  allow_implicit_invocation: false

package/template/.codex/skills/product-design/skills/user-context/plugin-author-config/user-context-template.md

@@ -0,0 +1,63 @@
+# Product URLs
+
+- Description: Production, staging, local app, docs, admin, or key flow URLs Product Design can use as likely source surfaces.
+
+## Saved Links And Context
+
+status: not provided
+
+# Figma Sources
+
+- Description: Product files, design-system files, component libraries, prototypes, FigJam boards, or other Figma sources.
+
+## Saved Links And Context
+
+status: not provided
+
+# Screenshots And Reference Images
+
+- Description: Local screenshots and reference images saved under `assets/` next to `user-context.md`.
+
+## Saved Links And Context
+
+status: not provided
+
+# Codebase References
+
+- Description: Repo roots, app packages, component folders, token files, theme files, CSS entrypoints, or implementation notes.
+
+## Saved Links And Context
+
+status: not provided
+
+# Storybook And Component Docs
+
+- Description: Storybook URLs, component docs, design-system docs, UI kit docs, or local component preview commands.
+
+## Saved Links And Context
+
+status: not provided
+
+# Design Tokens And Theme Sources
+
+- Description: Tokens, typography, spacing, color, radius, icon, motion, CSS variable, Tailwind, or theme sources.
+
+## Saved Links And Context
+
+status: not provided
+
+# Brand And Asset Sources
+
+- Description: Logos, app icons, illustration libraries, product imagery, icon sets, image libraries, and brand guidelines.
+
+## Saved Links And Context
+
+status: not provided
+
+# Tool And Sharing Preferences
+
+- Description: Preferred browser, capture tool, Figma usage, share target, deployment target, and team workflow preferences.
+
+## Saved Links And Context
+
+status: not provided

package/template/.codex/skills/product-design/skills/user-context/references/onboarding.md

@@ -0,0 +1,66 @@
+# Product Design Setup
+
+Use this reference when saved user context is missing, when the user asks what Product Design can remember, when the user asks to set up Product Design, or when the user provides product/design references to save.
+
+Setup is short. It is not a questionnaire and not a formal onboarding state machine.
+
+## Step 1: Orientation
+
+Render this first. Do not write files, inspect tools, browse URLs, open Figma, create prototypes, generate images, or run audits before this message.
+
+```md
+Product Design can remember the product surfaces and design sources you use most, so future work starts from the right place.
+
+Useful things to save:
+1. Product URLs
+2. Figma files
+3. Screenshots or reference images
+4. Codebase paths
+5. Storybook or component docs
+6. Design-system refs
+7. Brand and asset sources
+8. Preferred tools and share targets
+
+Send any of those now, or say `skip` and I'll work from each task's source.
+```
+
+## Step 2: Save Context
+
+When the user provides references, save them to:
+
+```text
+$CODEX_HOME/state/plugins/product-design/user-context.md
+```
+
+Create the file first if needed:
+
+```bash
+python3 scripts/init_user_context.py
+```
+
+Use the category structure from `../SKILL.md`.
+
+If the user provides screenshots or reference images, copy them into:
+
+```text
+$CODEX_HOME/state/plugins/product-design/assets/
+```
+
+Give saved images clear names that say what they show, such as `assets/payment-sheet-mobile-error-state.png` or `assets/account-menu-open-state.png`.
+
+Do not save secrets, API keys, credentials, private tokens, or unsupported claims.
+
+Use this save recap:
+
+```md
+Saved Product Design context:
+- {Category}: {what was saved}
+
+I'll use this as a starting map for future Product Design work. The source you provide in a task still wins.
+```
+
+## Step 3: Read Context
+
+When the user asks what Product Design knows, read `user-context.md` and summarize only saved entries.
+
+If no saved context exists, say that plainly and offer the Step 1 setup prompt.

package/template/.codex/skills/product-design/skills/user-context/scripts/init_user_context.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Create the local Product Design context file."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+TEMPLATE_PATH = SKILL_ROOT / "plugin-author-config/user-context-template.md"
+PLUGIN_STATE_DIR = Path("state/plugins/product-design")
+
+CONTEXT_NOTE = """<!--
+Product Design context. This file is user-editable.
+Unresolved `status: not provided` entries are setup prompts, not saved facts.
+Saved references should include Date Added, Useful Context, and Future Use when available.
+-->
+
+"""
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Create $CODEX_HOME/state/plugins/product-design/user-context.md "
+            "from the bundled Product Design template."
+        )
+    )
+    parser.add_argument(
+        "--codex-home",
+        type=Path,
+        default=None,
+        help="Codex home directory. Defaults to $CODEX_HOME or ~/.codex.",
+    )
+    parser.add_argument(
+        "--state-dir",
+        type=Path,
+        default=None,
+        help="Override the Product Design state directory.",
+    )
+    parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="Overwrite an existing user-context.md file.",
+    )
+    return parser.parse_args()
+
+
+def resolve_state_dir(codex_home: Path | None, state_dir: Path | None) -> Path:
+    if state_dir is not None:
+        return state_dir.expanduser().resolve()
+    home = codex_home or Path(os.environ.get("CODEX_HOME", "~/.codex"))
+    return (home.expanduser() / PLUGIN_STATE_DIR).resolve()
+
+
+def main() -> int:
+    args = parse_args()
+    state_dir = resolve_state_dir(args.codex_home, args.state_dir)
+    context_path = state_dir / "user-context.md"
+
+    if not TEMPLATE_PATH.exists():
+        print("Missing Product Design context template.", file=sys.stderr)
+        print(f"- {TEMPLATE_PATH.relative_to(SKILL_ROOT)}", file=sys.stderr)
+        return 1
+
+    state_dir.mkdir(parents=True, exist_ok=True)
+    (state_dir / "assets").mkdir(parents=True, exist_ok=True)
+
+    existed = context_path.exists()
+    if existed and not args.overwrite:
+        result = "preserved"
+    else:
+        context_path.write_text(
+            CONTEXT_NOTE + TEMPLATE_PATH.read_text(encoding="utf-8"), encoding="utf-8"
+        )
+        result = "overwritten" if existed else "created"
+
+    print(f"Product Design state directory: {state_dir}")
+    print(f"user-context.md: {result}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())