create-yss-spec 1.1.1 → 1.1.3

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())

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

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Read local Product Design context and print compact JSON."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+PLUGIN_STATE_DIR = Path("state/plugins/product-design")
+DEFAULT_MAX_CONTEXT_BYTES = 2_000_000
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Read Product Design user-context.md and return saved context as JSON."
+    )
+    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(
+        "--max-context-bytes",
+        type=int,
+        default=DEFAULT_MAX_CONTEXT_BYTES,
+        help="Maximum user-context.md size to read.",
+    )
+    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 file_mtime(path: Path) -> str | None:
+    try:
+        return datetime.fromtimestamp(path.stat().st_mtime, tz=timezone.utc).isoformat()
+    except OSError:
+        return None
+
+
+def sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def parse_resource_name(line: str) -> dict[str, str]:
+    link_match = re.match(r"^\[(.+?)\]\((.+?)\)\s*$", line)
+    if link_match:
+        return {"name": link_match.group(1).strip(), "url": link_match.group(2).strip()}
+    url_match = re.match(r"^(https?://\S+)\s*$", line)
+    if url_match:
+        return {"name": url_match.group(1).strip(), "url": url_match.group(1).strip()}
+    return {"name": line.strip()}
+
+
+def summarize_user_context(markdown: str) -> dict[str, Any]:
+    entries: list[dict[str, Any]] = []
+    unresolved_categories: list[str] = []
+    category: str | None = None
+    in_saved_context = False
+    current_entry: dict[str, Any] | None = None
+
+    def flush_entry() -> None:
+        nonlocal current_entry
+        if current_entry:
+            entries.append(current_entry)
+            current_entry = None
+
+    for raw_line in markdown.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith(("<!--", "-->")):
+            continue
+
+        category_match = re.match(r"^# ([^#].*?)\s*$", line)
+        if category_match:
+            flush_entry()
+            category = category_match.group(1).strip()
+            in_saved_context = False
+            continue
+
+        if line == "## Saved Links And Context":
+            flush_entry()
+            in_saved_context = True
+            continue
+
+        if not category or not in_saved_context:
+            continue
+
+        if line.casefold() == "status: not provided" or line.casefold() == "status: not provided.":
+            flush_entry()
+            unresolved_categories.append(category)
+            continue
+
+        if not line.startswith("- "):
+            flush_entry()
+            current_entry = {"category": category, **parse_resource_name(line)}
+            continue
+
+        if not current_entry:
+            continue
+
+        bullet = line[2:].strip()
+        for prefix, key in (
+            ("Date Added:", "date_added"),
+            ("File:", "file"),
+            ("Useful Context:", "useful_context"),
+            ("Future Use:", "future_use"),
+        ):
+            if bullet.startswith(prefix):
+                current_entry[key] = bullet[len(prefix) :].strip().rstrip(".")
+                break
+        else:
+            current_entry.setdefault("notes", []).append(bullet)
+
+    flush_entry()
+    return {"entries": entries, "unresolved_categories": unresolved_categories}
+
+
+def missing_payload(state_dir: Path, context_path: Path) -> dict[str, Any]:
+    return {
+        "plugin": "product-design",
+        "state_dir": str(state_dir),
+        "user_context": {
+            "path": str(context_path),
+            "exists": False,
+            "status": "missing",
+            "entries": [],
+            "unresolved_categories": [],
+        },
+    }
+
+
+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 context_path.exists():
+        print(json.dumps(missing_payload(state_dir, context_path), indent=2))
+        return 0
+
+    size = context_path.stat().st_size
+    if size > args.max_context_bytes:
+        print(
+            json.dumps(
+                {
+                    "plugin": "product-design",
+                    "state_dir": str(state_dir),
+                    "user_context": {
+                        "path": str(context_path),
+                        "exists": True,
+                        "status": "too_large",
+                        "size_bytes": size,
+                        "max_context_bytes": args.max_context_bytes,
+                        "entries": [],
+                        "unresolved_categories": [],
+                    },
+                },
+                indent=2,
+            )
+        )
+        return 0
+
+    markdown = context_path.read_text(encoding="utf-8")
+    summary = summarize_user_context(markdown)
+    print(
+        json.dumps(
+            {
+                "plugin": "product-design",
+                "state_dir": str(state_dir),
+                "user_context": {
+                    "path": str(context_path),
+                    "exists": True,
+                    "status": "present",
+                    "sha256": sha256_text(markdown),
+                    "modified_at": file_mtime(context_path),
+                    **summary,
+                },
+            },
+            indent=2,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/template/.codex/skills/product-design/templates/prototype/AGENTS.md

@@ -0,0 +1,7 @@
+# Prototype Instructions
+
+Run the local server yourself and open the preview in the in-app browser. Do not give the user server-start instructions when you can run it.
+
+Before making substantial visual changes, use the Product Design plugin's `get-context` skill when the visual source is unclear or no longer matches the current goal. When the user gives durable prototype-specific design feedback, preferences, or decisions, record them in `AGENTS.md`.
+
+When implementing from a selected generated mock, treat that image as the source of truth for layout, component anatomy, density, spacing, color, typography, visible content, and hierarchy.

package/template/.codex/skills/product-design/templates/prototype/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Prototype</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/template/.codex/skills/product-design/templates/prototype/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "design-prototype",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "vite build",
+    "preview": "vite preview --host 127.0.0.1"
+  },
+  "dependencies": {
+    "@vitejs/plugin-react": "5.0.4",
+    "vite": "6.4.2",
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
+  },
+  "devDependencies": {}
+}

package/template/.codex/skills/product-design/templates/prototype/src/App.jsx

@@ -0,0 +1,5 @@
+export function App() {
+  return (
+    <main></main>
+  );
+}

package/template/.codex/skills/product-design/templates/prototype/src/main.jsx

@@ -0,0 +1,10 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App.jsx";
+import "./styles.css";
+
+createRoot(document.getElementById("root")).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/template/.codex/skills/product-design/templates/prototype/src/styles.css

@@ -0,0 +1,13 @@
+:root {
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+  min-height: 100vh;
+  -webkit-font-smoothing: antialiased;
+}

package/template/.codex/skills/product-design/templates/prototype/vite.config.mjs

@@ -0,0 +1,14 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  optimizeDeps: {
+    include: ["react", "react-dom/client"],
+  },
+  server: {
+    warmup: {
+      clientFiles: ["./src/main.jsx"],
+    },
+  },
+  plugins: [react()],
+});

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

@@ -25,7 +25,7 @@ If no PRD baseline exists, route back to `yss-product-lifecycle` / `grill-with-d
 5. Write the OpenAPI implication list: fields, filters, actions, errors, permissions, pagination, optimistic/concurrency states, and audit/version data.
 6. For every primary page action, add an action-to-contract row: page/component, action label, `actionKey`, endpoint or explicit non-goal, request fields, response shape, permission behavior, state transition, idempotency/concurrency rule, and error codes.
 7. For every P0 requirement containing verbs such as manage, maintain, configure, create, update, archive, retry, cancel, publish, export, or create draft, confirm the interaction spec either names the API implication or records that the capability is intentionally out of scope.
-8. Hand off to `prototype-review`. Do not freeze/calibrate the PRD or enter OpenAPI Draft for UI work until prototype review has no blocking findings.
+8. Hand off to `prototype-review`. After low-fidelity review is approved, hand off to `high-fidelity-html-prototype`. Do not freeze/calibrate the PRD or enter OpenAPI Draft for UI work until the Ant Design v6 high-fidelity HTML prototype exists and has no blocking findings.
 
 ## Tool Routing
 
@@ -33,8 +33,6 @@ If no PRD baseline exists, route back to `yss-product-lifecycle` / `grill-with-d
 |---|---|
 | Low-fidelity page or flow sketch | `wireframe-prototype` |
 | Figma work or existing Figma file | `figma` / `figma-use` |
-| Engineering state prototype | `component-story-prototype` |
-| API not frozen but interactions need data | `mock-api-prototype` |
 | YSS implementation constraints | `yss-router`, then `yss-ui`, `yss-formily`, `yss-page-module-development` as needed |
 
 ## Output Contract
@@ -67,7 +65,7 @@ Product design / prototype / interaction design
 - <yes/no; include whether PRD calibration is needed first>
 
 ### 下一步
-- <prototype-review or routing back to PRD/design>
+- <prototype-review / high-fidelity-html-prototype / routing back to PRD/design>
 ```
 
 ## Data Modeling Example

package/template/.codex/skills/prototype-review/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: prototype-review
-description: Use when reviewing UI design, wireframes, prototype links, interaction specs, or state matrices before PRD calibration, OpenAPI Draft, vertical slicing, or implementation.
+description: Use when reviewing low-fidelity UI design, wireframes, prototype links, interaction specs, or state matrices before high-fidelity HTML prototype work, PRD calibration, OpenAPI Draft, vertical slicing, or implementation.
 ---
 
 # Prototype Review
 
-Use this skill as the gate between product design/prototype work and PRD calibration / OpenAPI Draft. The review is fail-closed: if the design cannot drive calibrated requirements, API, frontend acceptance, and slices, send it back to product design.
+Use this skill as the low-fidelity gate between product design/prototype work and high-fidelity HTML prototype work. The review is fail-closed: if the design cannot drive calibrated requirements, API, frontend acceptance, and slices, send it back to product design.
 
 ## Required Inputs
 
@@ -27,13 +27,13 @@ Use this skill as the gate between product design/prototype work and PRD calibra
 | Action contract coverage | Every primary page action has an `actionKey`, endpoint or explicit non-goal, permission behavior, state transition, idempotency/concurrency rule, and error codes |
 | P0 contract coverage | Every P0 requirement with manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft semantics is mapped to an API implication or an explicit non-goal |
 | Rule/source coverage | Validation, approval, coverage, and publish gates state where rules come from, who can configure them, whether they are fixed, and how blocker/warning decisions are represented |
-| Frontend acceptance | A frontend engineer can tell which components, stories, mock data, and E2E paths are needed |
+| Frontend acceptance | A frontend engineer can tell which components, visible states, data dependencies, and E2E paths are needed |
 
 ## Decision Rules
 
-- If a feature has UI impact and lacks page map, user flow, prototype/wireframe, or state matrix, block PRD calibration and OpenAPI Draft.
+- If a feature has UI impact and lacks page map, user flow, prototype/wireframe, or state matrix, block high-fidelity HTML prototype work, PRD calibration, and OpenAPI Draft.
 - If the prototype hides business rules behind generic text such as "校验失败", require field-level errors and recovery behavior.
-- If a page shows a user action but the OpenAPI implication list lacks endpoint/non-goal mapping, block PRD calibration or OpenAPI Draft.
+- If a page shows a user action but the OpenAPI implication list lacks endpoint/non-goal mapping, block high-fidelity HTML prototype work, PRD calibration, or OpenAPI Draft.
 - If PRD P0 scope says a user can manage or configure an object but the design only shows read-only data, block until the write path or scope downgrade is explicit.
 - If a state is intentionally out of scope, record why and who owns the decision.
 - If implementation dependencies are unclear, route to `yss-router` only after the prototype passes this review.
@@ -57,10 +57,10 @@ Use this skill as the gate between product design/prototype work and PRD calibra
 - <requirements gaps, acceptance criteria updates, non-goals, pending decisions>
 
 ### Frontend Prototype Readiness
-- <storybook/histoire stories, mock data, component states>
+- <component states, data dependencies, frontend acceptance notes>
 
 ### Next Action
-- <PRD calibration / OpenAPI Draft / return to product-design-prototype / component-story-prototype / mock-api-prototype>
+- <high-fidelity-html-prototype / return to product-design-prototype>
 ```
 
 Use `docs/design/templates/prototype-review-checklist.md` when writing a persistent review artifact.

package/template/.codex/skills/yss-design-system/SKILL.md

@@ -70,12 +70,14 @@ description: YSS 产品设计系统与 Ant Design 企业级 UI 风格基线。
 | 场景 | 配合技能 |
 | --- | --- |
 | PRD 后做页面 / 原型 / 交互说明 | `product-design-prototype` |
-| 原型进入 PRD 校准 / OpenAPI Draft 前评审 | `prototype-review` |
+| 低保真原型进入高保真前评审 | `prototype-review` |
+| 低保真评审通过后的高保真 HTML 原型 | `high-fidelity-html-prototype` |
 | 低保真线框或流程图 | `wireframe-prototype` / `excalidraw-diagram-generator` |
 | 前端页面实现 | `yss-ui` / `yss-page-module-development` |
 | 表单 schema | `yss-formily` |
 | YTable / YTree / 高度自适应 | `yss-components` / `yss-use-table-height` / `yss-use-tree-height` |
-| API / Mock 联调 | `api-integration` / `mock-api-prototype` |
+| Ant Design v6 组件 / token / demo 查询 | 官方 `@ant-design/cli` / `https://ant.design/docs/react/for-agents` |
+| API 契约 / 接入 | `api-integration` / `yss-openapi` |
 
 ## 更新设计系统
 

package/template/.codex/skills/yss-product-lifecycle/SKILL.md

@@ -63,7 +63,7 @@ Architecture artifacts are produced progressively. Do not try to finish every ar
 | Artifact | Lifecycle timing | Primary question | Typical outputs | Diagram support |
 |---|---|---|---|---|
 | Business architecture | Opportunity exploration / Discovery / product definition | Who gets value, in which workflow, and where the product boundary sits | user journey, value stream, role/ecosystem model, capability map | journey map, swimlane, capability map |
-| Product overview design / Functional architecture | PRD baseline / product design / PRD calibration | Which product capabilities, user flows, modules, pages, APIs, and data impacts support the MVP boundary | product overview, module map, feature list, priority, dependencies, state flow, open questions, PRD gaps | feature/module map, dependency graph, user flow, page map |
+| Product overview design / Functional architecture | PRD baseline / product design / PRD calibration | Which product capabilities, user flows, modules, pages, low-fidelity prototypes, APIs, and data impacts support the MVP boundary | product overview, module map, feature list, priority, dependencies, low-fidelity wireframe, state flow, open questions, PRD gaps | feature/module map, dependency graph, user flow, page map, low-fidelity wireframe |
 | System overview design / System architecture | Engineering baseline / architecture review | How the product is built, deployed, integrated, operated, and safely evolved | C4/container view, service boundary, integration, deployment, NFR decisions, rollout/rollback decisions | system architecture, sequence, deployment, DFD |
 | Data architecture | Detailed design before persistence and repository work | How domain data, metadata, versions, lineage, and queries are modeled and stored | conceptual/logical/physical model, meta-model, versioning strategy, lineage/query/index strategy | ER, class, lineage graph, DFD |
 
@@ -90,7 +90,9 @@ Use `excalidraw-diagram-generator` when diagrams will make boundaries, flows, da
    - service boundary, state machine, integration, NFR, rollout, or rollback -> system / data architecture, engineering contract, and Design Review downstream gates;
    - persistence, metadata, versioning, lineage, query, or index -> system / data architecture, engineering contract, and Design Review downstream gates.
 4. Check whether required upstream artifacts exist.
-   - Before formal vertical slicing, verify PRD, OpenAPI Freeze or no-API-impact record, architecture review as needed, and a clear issue destination.
+   - Before PRD calibration, product design, API impact analysis, OpenAPI Draft, requirement freeze, or formal vertical slicing, verify PRD baseline and product overview design / functional architecture exist. If the task does not enter the PRD lifecycle, record the not-applicable reason in the impact assessment.
+   - For UI work, before PRD calibration, API impact analysis, OpenAPI Draft, or requirement freeze, verify low-fidelity `prototype-review` is approved, `docs/design/prototypes/<feature>/index.html` exists as an Ant Design v6 high-fidelity HTML prototype, AntD v6 CLI validation evidence is recorded, and user confirmation is recorded after the prototype is produced. This prototype is a required lifecycle artifact and may be generated automatically by the system / Agent after low-fidelity prototype review; it does not have to be manually supplied by the user.
+   - Before formal vertical slicing, verify PRD, product overview design / functional architecture, OpenAPI Freeze or no-API-impact record, architecture review as needed, and a clear issue destination.
    - For medium/high-risk API, permission, state-machine, data-model, cross-client, new-module, or safety-sensitive changes, verify an OpenSpec-style Spec Delta exists or record why it is not needed.
    - Before frontend/backend implementation, verify vertical slice scope, implementation repo/location, whether the impacted frontend/backend runtime projects already exist and are reusable, YSS skill routing, Build Architecture Checklist, test command, and review strategy.
 5. Output the next action:
@@ -139,10 +141,11 @@ Default routing:
 
 | Intent | Next skill / workflow |
 |---|---|
-| Start a new business product/module | intake -> opportunity and Discovery -> `competitive-intelligence` when market / competitor facts are needed -> `grill-with-docs` -> `to-prd` -> business / PRD / functional architecture -> product design and requirement freeze when UI exists |
+| Start a new business product/module | intake -> opportunity and Discovery -> `competitive-intelligence` when market / competitor facts are needed -> `grill-with-docs` -> `to-prd` -> product overview design / functional architecture -> product design and requirement freeze when UI exists |
 | Analyze competitors, substitute workflows, pricing, positioning, or market facts | `competitive-intelligence`; then feed stable findings into `grill-with-docs` and `to-prd` |
-| Design UI flow after PRD baseline | `product-design-prototype`; add `wireframe-prototype`, `component-story-prototype`, or `mock-api-prototype` only when needed |
-| Review prototype before PRD calibration | `prototype-review` |
+| Design UI flow after PRD baseline | Verify product overview design / functional architecture first, then use `product-design:index` as the primary Product Design router; follow its focused routing such as `$get-context`, `$ideate`, `$prototype`, `$image-to-code`, or `$url-to-code` |
+| Review low-fidelity prototype before high-fidelity design | `prototype-review` |
+| Build high-fidelity interactive HTML prototype | Use `product-design:index` as the primary entrypoint and route to the appropriate Product Design focused workflow for prototype/code output; query AntD v6 design/component/demo/token/semantic facts with `antd` CLI before output; the required stage output must be Ant Design v6 HTML at `docs/design/prototypes/<feature>/index.html`, may be system / Agent generated, must record AntD CLI validation evidence, and must be confirmed by the user before downstream gates |
 | Review contract draft / OpenAPI Draft inside architecture/design review | `yss-openapi-draft-review` |
 | Record behavior deltas for medium/high-risk changes | OpenSpec-style Spec Delta at `docs/specs/<feature>-spec-delta.md` using `docs/templates/spec-delta-template.md` |
 | Clarify architecture artifact timing or gaps | this skill plus `docs/process/lifecycle-artifact-map.md` and `references/artifact-checklist.md` |
@@ -202,10 +205,10 @@ When the user explicitly asks for a full delivery plan, include stage-by-stage t
 
 - Do not skip opportunity exploration for new product/module work; use `competitive-intelligence` when market/competitor facts are needed, or record why it is not needed.
 - Do not treat Discovery outputs as frozen downstream design. Discovery can provide product capability guidance and downstream impact signals, but PRD, functional architecture, OpenAPI, system architecture, and data architecture still require their own gates.
-- Do not start implementation before PRD is calibrated, required architecture artifacts are explicit, product design / prototype / interaction design exists and passes `prototype-review` when UI exists, OpenAPI Freeze decision, engineering baseline, design review, and vertical slice are clear.
+- Do not start implementation before PRD is calibrated, product overview design / functional architecture exists, required architecture artifacts are explicit, product design / prototype / interaction design exists, low-fidelity `prototype-review` passes, high-fidelity Ant Design v6 HTML prototype exists when UI exists, OpenAPI Freeze decision, engineering baseline, design review, and vertical slice are clear.
 - Do not start implementation before deciding whether the impacted frontend/backend runtime projects already exist and can be reused. Missing or conflicting runtime projects must route back to implementation routing and scaffold initialization first.
 - Do not skip business architecture for new products unless the product boundary, users, ecosystem, and value stream are already captured elsewhere.
-- Do not skip functional architecture before PRD calibration when module boundaries, MVP priority, or cross-module dependencies are still unclear.
+- Do not skip product overview design / functional architecture after PRD baseline. It is a required artifact before PRD calibration, product design / prototype / interaction design, API impact analysis, OpenAPI Draft, requirement freeze, or implementation. Only tasks that do not enter the PRD lifecycle may record a not-applicable reason in the impact assessment.
 - Do not skip system architecture when services, deployment, integrations, performance, security, reliability, or operations are affected.
 - Do not skip data architecture before persistence / repository work. For data modeling, metadata, versioning, or lineage products, treat it as mandatory before Design Review and OpenAPI Freeze.
 - Do not let Excalidraw diagrams invent requirements or architecture decisions; diagrams must point back to source artifacts and any findings must be written back to PRD, OpenAPI, ADR, or issues.

package/template/.codex/skills/yss-product-lifecycle/references/artifact-checklist.md

@@ -14,6 +14,7 @@ Use this checklist to decide whether the current request can move forward or mus
 | Functional architecture | `docs/architecture/<feature>-functional-architecture.md` or PRD/design section | Product capabilities, module boundaries, priority, dependencies, and MVP scope are clear |
 | Product overview design | `docs/design/<feature>-product-overview-design.md` | Pages, flows, states, permissions, API candidates, and PRD gaps are clear |
 | Prototype / interaction review | `docs/design/<feature>-prototype-review.md` or issue comment | UI paths, empty/error/loading states, permission states, and API backflow list are reviewed |
+| High-fidelity HTML prototype | `docs/design/prototypes/<feature>/index.html` | Ant Design v6 interactive HTML prototype exists after low-fidelity review and before PRD calibration / API Draft |
 | API impact / OpenAPI Draft | `docs/api/specs/<feature>.yaml`, issue note, or API impact record | Request/response, wrappers, errors, pagination, permissions, concurrency, and contract test seams are reviewable |
 | OpenAPI Freeze | `docs/api/<feature>-openapi-freeze.md` or issue comment | Draft has been reviewed and marked stable for frontend/backend implementation |
 | Engineering baseline | `docs/architecture/<feature>-engineering-baseline-review.md` | YSS DDD module boundary, dependency direction, DTO/VO/CMD/Query conventions, and scaffold constraints are reviewed |

package/template/.codex/skills/yss-product-lifecycle/references/stage-routing.md

@@ -9,7 +9,7 @@ Use this reference after reading current repo context. It maps request shape to
 | 1. Intake / lifecycle triage | 新需求、继续需求、Bug、小调整、流程不清、缺失资产判断 | User request, `CONTEXT.md`, docs, issues, git state | stage decision, nearest trustworthy artifact, minimal skill list | route to earliest impacted stage |
 | 2. Opportunity and Discovery | 模糊想法、竞品/市场输入、用户痛点尚不清楚 | discovery docs, market/user facts, stakeholder notes | user, pain, why now, MVP, non-goals, success criteria, downstream impact | `competitive-intelligence` when market / competitor facts are needed, then `grill-with-docs` / PRD |
 | 3. Business / PRD / functional architecture | 需要明确用户故事、验收标准、功能边界、模块依赖 | discovery, `CONTEXT.md`, ADRs, existing PRD | PRD, business architecture, functional architecture, PRD review notes | product design or contract design |
-| 4. Product design and requirement freeze | 有 UI、页面、交互、状态矩阵、权限状态、空/错/加载态 | PRD, design system, existing UI, component docs | product overview design, interaction spec, state matrix, prototype review, requirement freeze | contract and architecture review |
+| 4. Product design and requirement freeze | 有 UI、页面、交互、状态矩阵、权限状态、空/错/加载态、高保真体验 | PRD, design system, existing UI, component docs | product overview design, interaction spec, state matrix, prototype review, Ant Design v6 high-fidelity HTML prototype, requirement freeze | contract and architecture review |
 | 5. System / data architecture, engineering contract, and Design Review | 接口、DTO、错误结构、后端新服务、新模块、DDD 分层、服务边界、部署、集成、状态机、权限、NFR、持久化、元模型、版本、血缘 | calibrated requirements, design inputs, API impact decision, engineering impact decision | API impact record; contract sketch or reviewable OpenAPI Draft marked draft-for-review; OpenAPI Draft Review; engineering baseline review; system overview; data architecture when required; ADR candidates; Design Review result | contract freeze and Issue formalization |
 | 6. Contract freeze and Issue formalization | OpenAPI Freeze、无 API 影响记录、正式拆分垂直切片 | Design Review approval, contract draft / OpenAPI Draft, PRD/design/architecture artifacts | OpenAPI Freeze or no API impact record; GitHub/GitLab/local vertical slice Issues | vertical slices and TDD implementation |
 | 7. Vertical slices and TDD implementation | issue、切片、实现、review、清理简化 | frozen contract / no API impact, approved slice, implementation repo/location | implementation routing, YSS skill routing, tests, review, verification evidence | verification, release, and retrospective |

package/template/.codex/skills/yss-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "yss-ui"
-description: "YSS UI 页面开发组件技能。涉及 YTable、YTree、YssFormily、useTableHeight、useTreeHeight、页面布局、Hook 抽离、API/Mock 联调、路由菜单约定时必须使用。组件技能可以参考 yss-components 与 yss-hooks 技能规范。"
+description: "YSS UI 页面开发组件技能。涉及 YTable、YTree、YssFormily、useTableHeight、useTreeHeight、页面布局、Hook 抽离、API 契约接入、路由菜单约定时必须使用。组件技能可以参考 yss-components 与 yss-hooks 技能规范。"
 ---
 
 # YSS UI 页面与 Hook 一体化标准
@@ -197,19 +197,13 @@ const { loading, run: runPage } = useRequest(pageApi, {
 - 翻页仅更新 `page/pageSize`，保留筛选项
 - 导出、刷新等动作复用 `currentParams`
 
-## 11. API 与 Mock 联调标准
-
-API 层：
+## 11. API 契约接入标准
 
 - 接口写在 `packages/src/api/*`
 - 复用 `mutator.ts`
 - 避免重复拼接 `/api`
-
-Mock 层：
-
-- 路由放 `packages/mock/api.ts`
-- 支持筛选和分页切片
-- 返回结构统一：`{ code, message, data: { list, total, page, pageSize } }`
+- 请求 / 响应字段以冻结后的 OpenAPI 或明确的契约草案为准
+- 未冻结契约不得作为稳定生成客户端或实现依据
 
 ## 12. 路由菜单标准