create-yss-spec 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Initialize a YSS spec project template repository",
   "files": [
     "bin",

package/template/.agents/skills/high-fidelity-html-prototype/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: high-fidelity-html-prototype
+description: Use after low-fidelity prototype review is approved and before PRD calibration, requirement freeze, OpenAPI Draft, or UI implementation when a user-facing YSS feature needs a high-fidelity interactive HTML prototype using Ant Design v6.
+---
+
+# High Fidelity HTML Prototype
+
+Use this skill only after `prototype-review` approves the low-fidelity prototype / interaction design. It turns reviewed product design into a high-fidelity, browser-runnable HTML artifact for business, UX, frontend, and API review.
+
+## Required Inputs
+
+- PRD baseline: `docs/requirements/<feature>-prd.md`.
+- Product overview design / functional architecture: `docs/design/<feature>-product-overview-design.md`.
+- Interaction spec: `docs/design/<feature>-interaction-spec.md`.
+- State matrix: `docs/design/<feature>-state-matrix.md`.
+- Approved low-fidelity prototype review: `docs/design/<feature>-prototype-review.md` or equivalent issue comment.
+- Project design system: `docs/design/design.md` and `docs/design/tokens/*`.
+
+If low-fidelity `prototype-review` is blocked or missing, stop and return to `product-design-prototype` / `prototype-review`.
+
+## Ant Design Official Agent Baseline
+
+Use the official Ant Design agent guidance as the implementation baseline:
+
+- Read or reference `https://ant.design/docs/react/for-agents` when the task starts.
+- Use `@ant-design/cli` before choosing unfamiliar components, props, tokens, or migration-sensitive APIs.
+- Prefer direct CLI subcommands because `--help` may fail in some Node environments while subcommands still work.
+
+Recommended commands:
+
+```bash
+npm view antd version
+npm view @ant-design/cli version
+npx -y @ant-design/cli@6.5.0 info Button
+npx -y @ant-design/cli@6.5.0 token Button
+npx -y @ant-design/cli@6.5.0 demo Select basic
+npx -y @ant-design/cli@6.5.0 changelog 5.0.0 6.5.0 Table
+```
+
+Use the latest verified v6.x version instead of `6.5.0` when npm reports a newer v6 release. Record the exact version and any queried components in the output.
+
+## Core Rules
+
+- Output is HTML: `docs/design/prototypes/<feature>/index.html`.
+- The prototype must use Ant Design v6. Before generating or updating code, verify the current v6 package with `npm view antd version` and `npm view @ant-design/cli version`. If the latest version is not v6.x, pin the newest available v6.x version and record the choice.
+- Use React >= 18, `antd@6.x`, and `@ant-design/icons@6.x` for interactive prototypes.
+- Prefer Ant Design components and tokens over hand-built controls: `Layout`, `Menu`, `Breadcrumb`, `Button`, `Input`, `Select`, `Table`, `Form`, `Tabs`, `Steps`, `Drawer`, `Modal`, `Alert`, `Tooltip`, `Tag`, `Badge`, `DatePicker`, `Upload`, `Pagination`, `Empty`, `Spin`, `Result`.
+- Do not create extra data-service or fixture artifacts. Use embedded sample data inside the HTML/JS for visual and interaction demonstration only.
+- Mark the file clearly as `PROTOTYPE ONLY - NOT PRODUCTION CODE`.
+- Do not treat the HTML prototype as a stable frontend implementation, generated-client contract, or OpenAPI source of truth. It informs PRD calibration and OpenAPI Draft.
+
+## Interaction Coverage
+
+The HTML prototype must cover, or explicitly mark not applicable:
+
+- Primary page navigation and page-to-page return path.
+- Main task completion flow.
+- Search / filter / sort / pagination behavior.
+- Form input, validation, submit, cancel, dirty-form leave prompt.
+- Drawer / modal / confirmation interactions.
+- loading, empty, error, readonly, disabled, no-permission, conflict, success states.
+- Permission behavior: hidden vs disabled vs rejected action.
+- Field-level and page-level error placement.
+- Responsive behavior for at least desktop, tablet, and narrow mobile viewport.
+
+## Verification
+
+Run a local browser verification before calling the artifact ready:
+
+- Open `docs/design/prototypes/<feature>/index.html` or run the dev server if the prototype needs one.
+- Check that the page renders nonblank.
+- Exercise the main flow and at least one failure / permission / conflict state.
+- Check at least one desktop and one mobile viewport.
+- Record verification evidence in the response or in the related review / issue.
+
+## Output Contract
+
+```markdown
+### 当前阶段
+High-fidelity HTML prototype
+
+### 输入资产
+- <PRD / product overview / interaction spec / state matrix / prototype review>
+
+### 高保真产物
+- `docs/design/prototypes/<feature>/index.html`
+
+### Ant Design v6 依据
+- <antd version, @ant-design/cli version, official docs checked, CLI component/token/demo queries>
+
+### 覆盖范围
+- <pages, flows, states, permissions, data dependencies>
+
+### 验证证据
+- <render command or file open path, viewport checks, interaction checks>
+
+### 是否可进入 PRD 校准 / API 影响分析
+- <yes/no; list blocking gaps>
+
+### 下一步
+- <PRD calibration / return to high-fidelity prototype / return to product-design-prototype>
+```

package/template/.codex/skills/high-fidelity-html-prototype/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: high-fidelity-html-prototype
+description: Use after low-fidelity prototype review is approved and before PRD calibration, requirement freeze, OpenAPI Draft, or UI implementation when a user-facing YSS feature needs a high-fidelity interactive HTML prototype using Ant Design v6.
+---
+
+# High Fidelity HTML Prototype
+
+Use this skill only after `prototype-review` approves the low-fidelity prototype / interaction design. It turns reviewed product design into a high-fidelity, browser-runnable HTML artifact for business, UX, frontend, and API review.
+
+## Required Inputs
+
+- PRD baseline: `docs/requirements/<feature>-prd.md`.
+- Product overview design / functional architecture: `docs/design/<feature>-product-overview-design.md`.
+- Interaction spec: `docs/design/<feature>-interaction-spec.md`.
+- State matrix: `docs/design/<feature>-state-matrix.md`.
+- Approved low-fidelity prototype review: `docs/design/<feature>-prototype-review.md` or equivalent issue comment.
+- Project design system: `docs/design/design.md` and `docs/design/tokens/*`.
+
+If low-fidelity `prototype-review` is blocked or missing, stop and return to `product-design-prototype` / `prototype-review`.
+
+## Ant Design Official Agent Baseline
+
+Use the official Ant Design agent guidance as the implementation baseline:
+
+- Read or reference `https://ant.design/docs/react/for-agents` when the task starts.
+- Use `@ant-design/cli` before choosing unfamiliar components, props, tokens, or migration-sensitive APIs.
+- Prefer direct CLI subcommands because `--help` may fail in some Node environments while subcommands still work.
+
+Recommended commands:
+
+```bash
+npm view antd version
+npm view @ant-design/cli version
+npx -y @ant-design/cli@6.5.0 info Button
+npx -y @ant-design/cli@6.5.0 token Button
+npx -y @ant-design/cli@6.5.0 demo Select basic
+npx -y @ant-design/cli@6.5.0 changelog 5.0.0 6.5.0 Table
+```
+
+Use the latest verified v6.x version instead of `6.5.0` when npm reports a newer v6 release. Record the exact version and any queried components in the output.
+
+## Core Rules
+
+- Output is HTML: `docs/design/prototypes/<feature>/index.html`.
+- The prototype must use Ant Design v6. Before generating or updating code, verify the current v6 package with `npm view antd version` and `npm view @ant-design/cli version`. If the latest version is not v6.x, pin the newest available v6.x version and record the choice.
+- Use React >= 18, `antd@6.x`, and `@ant-design/icons@6.x` for interactive prototypes.
+- Prefer Ant Design components and tokens over hand-built controls: `Layout`, `Menu`, `Breadcrumb`, `Button`, `Input`, `Select`, `Table`, `Form`, `Tabs`, `Steps`, `Drawer`, `Modal`, `Alert`, `Tooltip`, `Tag`, `Badge`, `DatePicker`, `Upload`, `Pagination`, `Empty`, `Spin`, `Result`.
+- Do not create extra data-service or fixture artifacts. Use embedded sample data inside the HTML/JS for visual and interaction demonstration only.
+- Mark the file clearly as `PROTOTYPE ONLY - NOT PRODUCTION CODE`.
+- Do not treat the HTML prototype as a stable frontend implementation, generated-client contract, or OpenAPI source of truth. It informs PRD calibration and OpenAPI Draft.
+
+## Interaction Coverage
+
+The HTML prototype must cover, or explicitly mark not applicable:
+
+- Primary page navigation and page-to-page return path.
+- Main task completion flow.
+- Search / filter / sort / pagination behavior.
+- Form input, validation, submit, cancel, dirty-form leave prompt.
+- Drawer / modal / confirmation interactions.
+- loading, empty, error, readonly, disabled, no-permission, conflict, success states.
+- Permission behavior: hidden vs disabled vs rejected action.
+- Field-level and page-level error placement.
+- Responsive behavior for at least desktop, tablet, and narrow mobile viewport.
+
+## Verification
+
+Run a local browser verification before calling the artifact ready:
+
+- Open `docs/design/prototypes/<feature>/index.html` or run the dev server if the prototype needs one.
+- Check that the page renders nonblank.
+- Exercise the main flow and at least one failure / permission / conflict state.
+- Check at least one desktop and one mobile viewport.
+- Record verification evidence in the response or in the related review / issue.
+
+## Output Contract
+
+```markdown
+### 当前阶段
+High-fidelity HTML prototype
+
+### 输入资产
+- <PRD / product overview / interaction spec / state matrix / prototype review>
+
+### 高保真产物
+- `docs/design/prototypes/<feature>/index.html`
+
+### Ant Design v6 依据
+- <antd version, @ant-design/cli version, official docs checked, CLI component/token/demo queries>
+
+### 覆盖范围
+- <pages, flows, states, permissions, data dependencies>
+
+### 验证证据
+- <render command or file open path, viewport checks, interaction checks>
+
+### 是否可进入 PRD 校准 / API 影响分析
+- <yes/no; list blocking gaps>
+
+### 下一步
+- <PRD calibration / return to high-fidelity prototype / return to product-design-prototype>
+```

package/template/.codex/skills/high-fidelity-html-prototype/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "High Fidelity HTML Prototype"
+  short_description: "Ant Design v6 interactive HTML prototype gate"
+  default_prompt: "Use $high-fidelity-html-prototype to create an Ant Design v6 high-fidelity interactive HTML prototype after low-fidelity prototype review."

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 and `docs/design/prototypes/<feature>/index.html` exists as an Ant Design v6 high-fidelity HTML prototype.
+   - 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-prototype`; add `wireframe-prototype` only when a low-fidelity page or flow sketch is needed |
+| Review low-fidelity prototype before high-fidelity design | `prototype-review` |
+| Build high-fidelity interactive HTML prototype | `high-fidelity-html-prototype` with Ant Design v6 after low-fidelity prototype review is approved |
 | 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. 路由菜单标准
 

package/template/.codex/skills/yss-ui/references/quick-recipes.md

@@ -152,7 +152,7 @@ const nodeColumns = reactive<YTableColumn[]>([
 
 ---
 
-## 模板 4：列表请求 + Mock 联调
+## 模板 4：列表请求 + API 接入
 
 ```ts
 const fetchData = async () => {

package/template/AGENTS.md

@@ -67,6 +67,10 @@ yss-product-lifecycle
 -> competitive-intelligence (需要竞品 / 市场事实时)
 -> grill-with-docs
 -> to-prd
+-> product overview design / functional architecture
+-> product-design-prototype
+-> prototype-review
+-> high-fidelity-html-prototype
 -> OpenAPI Draft
 -> OpenSpec-style Spec Delta (中高风险行为变化时)
 -> OpenAPI Freeze
@@ -126,9 +130,10 @@ Matt skills 与 YSS skills 产物正文默认使用中文，包括澄清记录
 - 任务开始前必须先参考 `docs/process/harness-process-tailoring.md` 判断小改动 / 中等变更 / 新模块或高风险变更；裁剪只能减少不相关产物，不能裁剪安全人审、Issue 追踪、Git checkpoint 和 fresh verification。
 - 新功能或较大改动必须先用 `grill-with-docs` 澄清需求，再用 `to-prd` 形成 PRD，并在 PRD、实施计划或 Issue 中引用澄清记录。
 - PRD 基线阶段必须同步明确功能架构：功能域、模块边界、优先级、MVP / 非目标范围和模块依赖；不清晰时不得进入 PRD 校准。
+- 只要进入 PRD 初稿 / 需求基线流程，产品总体设计 / 功能架构就是必要产物，默认路径为 `docs/design/<feature>-product-overview-design.md`，且必须包含低保真原型 / 页面草图。不得直接从 PRD 初稿进入页面 / 原型 / 交互设计、OpenAPI Draft、PRD 校准、需求冻结或实现；不进入 PRD 生命周期的小文案、低风险 Bug 或局部配置变更，必须在影响面评估中说明不适用原因。
 - 涉及页面设计、原型评审、UI 实现、组件选型、主题 token、颜色排版间距或 Ant Design / YSS UI 风格一致性的任务，必须先用 `yss-design-system` 作为设计系统基线；详细规范引用 `docs/design/design-system.md`。
-- 有用户界面的功能在 PRD 初稿后必须先引用 `yss-design-system`，再用 `product-design-prototype` 产出页面、原型、交互状态、PRD 回填项和 OpenAPI 反推清单，并通过 `prototype-review` 后才能进入 PRD 校准 / 需求冻结和 UI 驱动的 OpenAPI Draft。
-- 任何 API 契约变更必须先在 `docs/api/specs/*.yaml` 形成 Draft；有 UI 的功能不得只基于 PRD 反推 OpenAPI，必须结合产品总体设计、页面/原型/交互说明、状态矩阵和 `prototype-review` 结论，经工程基线（如适用）、系统 / 数据架构和设计审查后 Freeze，再实现前后端和测试。
+- 有用户界面的功能在 PRD 初稿和产品总体设计 / 功能架构后必须先引用 `yss-design-system`，再用 `product-design-prototype` 产出页面、原型、交互状态、PRD 回填项和 OpenAPI 反推清单；低保真 `prototype-review` 通过后，必须新增 `high-fidelity-html-prototype` 产物，默认路径为 `docs/design/prototypes/<feature>/index.html`，且必须使用 Ant Design v6，之后才能进入 PRD 校准 / 需求冻结和 UI 驱动的 OpenAPI Draft。
+- 任何 API 契约变更必须先在 `docs/api/specs/*.yaml` 形成 Draft；OpenAPI 不得只基于 PRD 反推，必须结合产品总体设计 / 功能架构；有 UI 的功能还必须结合页面/原型/交互说明、状态矩阵、`prototype-review` 结论和 Ant Design v6 高保真 HTML 原型，经工程基线（如适用）、系统 / 数据架构和设计审查后 Freeze，再实现前后端和测试。
 - API、权限、状态机、数据模型、跨端、新模块或高风险行为变化，应在 Design Review / OpenAPI Freeze 前补充 OpenSpec-style Spec Delta，落点为 `docs/specs/<feature>-spec-delta.md`；小文案、局部样式、配置微调和低风险 Bug 默认不需要。Spec Delta 只记录行为差异、验收场景和测试映射，不恢复 OpenSpec CLI、额外变更目录或状态机。
 - OpenAPI Freeze 后进入 `to-issues`，将冻结范围拆成端到端垂直切片 Issue；不得要求额外状态机或变更目录作为交付前置。
 - 涉及服务边界、部署、集成、性能、安全、可靠性或运维的变更，必须在设计审查前产出系统总体架构或等价设计记录。
@@ -252,7 +257,8 @@ Web Adapter
 |------|----------|------|--------|
 | PRD Review | PRD 完成后 | Product / Domain Review Agent | 用户、痛点、非目标范围、验收标准或安全红线不清 |
 | Grilling Review | 新功能 / 较大改动 PRD 前、Architecture Review 前 | Product / Domain / Architecture Agent with `grill-with-docs` | 用户价值、边界、状态、反例、架构约束、验收标准或安全红线经不起质询 |
-| Prototype Review | 有 UI 的 PRD 初稿完成后、PRD 校准前 | Product Design / UX / Frontend / API Agent | 页面清单、原型/线框、用户流、状态矩阵、PRD 回填项、权限状态或 OpenAPI 反推清单不清 |
+| Prototype Review | 有 UI 的 PRD 初稿完成后、高保真 HTML 原型前 | Product Design / UX / Frontend / API Agent | 页面清单、原型/线框、用户流、状态矩阵、PRD 回填项、权限状态或 OpenAPI 反推清单不清 |
+| High-fidelity HTML Prototype Review | 低保真原型评审通过后、PRD 校准前 | Product Design / UX / Frontend Agent | Ant Design v6 高保真 HTML 原型缺失、主流程/关键状态/响应式/权限体验不可审查 |
 | API Review | OpenAPI Draft 后 | API + Frontend + Backend Agent | schema、错误结构、分页、权限、契约测试不可落地 |
 | Architecture Review | 系统/数据架构后 | Architecture Review Agent | 业务/功能/系统/数据架构、DDD 分层、模块依赖、ADR、状态流或回滚策略不清 |
 | Plan Review | 垂直切片生成后 | Planning / Test Agent | 切片横向拆层、缺测试命令、缺回滚点或范围过大 |

package/template/CONTEXT.md

@@ -12,6 +12,7 @@
 | PRD | 产品需求文档，用于记录用户问题、解决方案、用户故事、关键决策和测试 seam。 | 除非作为既有参考，否则不要写入具体实现文件路径。 |
 | OpenAPI Draft | review-only 的 OpenAPI 3.1 契约草案。 | Freeze 前不得作为前后端稳定实现契约。 |
 | OpenAPI Freeze | 已通过评审、可作为前后端实现和契约测试输入的 OpenAPI 3.1 契约。 | Freeze 后变更必须回到 API 影响分析和设计审查。 |
+| 高保真 HTML 原型 | 低保真原型评审通过后，用于在浏览器中审查真实视觉密度、交互状态和页面流的产品设计资产。 | 不等同于生产前端实现，也不替代 OpenAPI、PRD 校准或垂直切片。 |
 | 垂直切片（Vertical Slice） | 贯穿所有受影响层、可独立验证的窄功能路径。 | 优先使用垂直切片，避免只按层拆分的横向任务。 |
 | ADR | 架构决策记录，用于沉淀难以回滚、非显而易见且存在真实取舍的技术决策。 | 常规实现选择不要写 ADR。 |
 | Fresh Verification | 完成前重新执行的验证证据，包括测试命令、契约校验、关键路径检查或人工审查结论。 | 不等同于“之前跑过”或实现者自述。 |

package/template/docs/api/templates/openapi-draft-review-checklist.md

@@ -16,6 +16,7 @@
 | 原型 / 线框图 |  |  |
 | 状态矩阵 | `docs/design/<feature>-state-matrix.md` |  |
 | 原型评审结论 | `docs/design/<feature>-prototype-review.md` |  |
+| 高保真 HTML 原型 | `docs/design/prototypes/<feature>/index.html` | 有 UI 时必需；必须使用 Ant Design v6 |
 | YSS 工程基线 | `.codex/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md` |  |
 
 ## P0 追踪矩阵
@@ -31,7 +32,8 @@
 | Draft 成熟度 | 明确当前仅为 review-only；实现、生成 client、契约测试固化均等待 OpenAPI Freeze |  |  |
 | OpenAPI 语法 | YAML、`$ref`、path 参数、lint 通过 |  |  |
 | P0 覆盖 | 每个 P0 需求有 endpoint/schema/error/test 或明确非目标 |  |  |
-| 交互输入完整 | Draft 已同时依据 PRD、产品总体设计、交互说明、原型/线框、状态矩阵和 prototype-review；缺任一项需说明无 UI 影响或返回上游补齐 |  |  |
+| 产品总体设计完整 | Draft 已依据 PRD 和产品总体设计 / 功能架构；缺产品总体设计时返回上游补齐 |  |  |
+| 交互输入完整 | 有 UI 时，Draft 已同时依据交互说明、原型/线框、状态矩阵、prototype-review 和 Ant Design v6 高保真 HTML 原型；无 UI 时需说明页面 / 交互资产不适用原因 |  |  |
 | DDD 契约边界 | Endpoint/schema 归属的限界上下文清楚；术语与 `CONTEXT.md` 和功能架构一致；契约不直接暴露内部聚合、Repository 或持久化表结构 |  |  |
 | 页面动作覆盖 | 每个按钮 / 抽屉 / 弹窗动作有 endpoint/non-goal、`actionKey`、权限和错误码 |  |  |
 | 对象生命周期 | manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft 语义闭环 |  |  |

package/template/docs/design/README.md

@@ -7,7 +7,9 @@
 - `docs/design/design.md`：从本地 `Product-Design-System` 引入并整理的 Ant Design 企业级设计系统说明，后续页面设计、交互说明、原型评审和前端实现默认引用该文件。
 - `docs/design/tokens/`：随仓库保存的主题、亮色 / 暗色 / 紧凑 token 和 CSS 变量快照，后续实现不得依赖本机 Downloads 目录。
 
-进入 API 影响分析 / 契约草案前，有用户界面的功能建议先沉淀：
+进入 PRD 初稿 / 需求基线流程后，必须先沉淀产品总体设计 / 功能架构，再进入页面 / 原型 / 交互设计、PRD 校准、API 影响分析 / 契约草案或实现。产品总体设计文档必须包含低保真原型 / 页面草图，用于验证页面结构、关键操作和主流程。无 UI 的功能也需要产品总体设计 / 功能架构来说明功能域、业务对象、模块边界、API / 数据影响和不适用的页面状态；只有不进入 PRD 生命周期的小改动可在影响面评估中记录不适用原因。
+
+进入 API 影响分析 / 契约草案前，有用户界面的功能还必须沉淀：
 
 - 页面清单和信息架构。
 - 用户主路径和异常路径。
@@ -16,12 +18,13 @@
 - 表单、表格、弹窗、抽屉、步骤流等交互说明。
 - loading、empty、error、readonly、disabled、no-permission、conflict 等状态矩阵。
 - 页面字段、筛选条件、操作按钮和权限规则。
+- 低保真原型评审通过后的 Ant Design v6 高保真可交互 HTML 原型，默认路径为 `docs/design/prototypes/<feature>/index.html`。
 
 这些资产用于反推 API 影响、契约草案、OpenAPI 请求 / 响应字段、错误结构、分页筛选、权限状态和前端验收标准。
 
 推荐模板：
 
-- `docs/design/templates/product-overview-design-template.md`：PRD 初稿之后、页面 / 原型 / 交互设计之前，用于团队评审产品总体设计、功能架构、页面/API/数据影响和 PRD 回填项；它是原型设计输入，不是交互说明本身。
+- `docs/design/templates/product-overview-design-template.md`：PRD 初稿之后、页面 / 原型 / 交互设计之前，用于团队评审产品总体设计、功能架构、低保真原型、页面/API/数据影响和 PRD 回填项；它是后续交互设计输入，不替代详细交互说明。
 - `docs/design/templates/interaction-spec-template.md`：页面、流程、交互、PRD 回填项和 OpenAPI 反推清单。
 - `docs/design/templates/state-matrix-template.md`：loading、empty、error、readonly、no-permission、conflict 等状态。
 - `docs/design/templates/prototype-review-checklist.md`：进入 PRD 校准 / API 影响分析 / 契约草案前的原型评审门禁。
@@ -31,15 +34,15 @@
 - `yss-design-system`：项目设计系统与 Ant Design 企业级 UI 风格基线；页面设计、原型评审、UI 实现和主题 token 落地时默认先引用。
 - `product-design-prototype`：基于 PRD 初稿和产品总体设计 / 功能架构，产出页面 / 原型 / 交互设计资产。
 - `wireframe-prototype`：低保真线框、Excalidraw、Figma、Penpot、tldraw、Axure 等原型链接沉淀。
-- `component-story-prototype`：Storybook / Histoire 工程态状态原型。
-- `mock-api-prototype`：MSW / mock fixtures 支撑未冻结 API 前的交互验证。
 - `prototype-review`：原型阶段评审门禁；未通过则不要进入 PRD 校准 / API 影响分析 / 契约草案。
+- `high-fidelity-html-prototype`：低保真原型评审通过后，基于官方 `@ant-design/cli` / Ant Design For Agents 指引生成 Ant Design v6 高保真可交互 HTML 原型；未产出前不要进入 PRD 校准 / API 影响分析 / 契约草案。
 - `excalidraw-diagram-generator`：根据已形成的 Discovery、PRD、OpenAPI Draft、Architecture 或 系统 / 数据架构设计 生成 `.excalidraw` 图；用于说明和审查，不替代文本规格。
 
 推荐目录：
 
 ```text
 docs/design/diagrams/
+docs/design/prototypes/
 docs/architecture/diagrams/
 docs/discovery/diagrams/
 ```

package/template/docs/design/prototypes/.gitkeep

@@ -0,0 +1 @@
+

package/template/docs/design/templates/interaction-spec-template.md

@@ -1,15 +1,17 @@
 # <功能名称> 交互说明模板
 
-> 适用时机：PRD 初稿之后、PRD 校准 / API 影响分析 / 契约草案之前；仅用于有用户界面影响的功能。
+> 适用时机：PRD 初稿和产品总体设计 / 功能架构完成之后，PRD 校准 / API 影响分析 / 契约草案之前；仅用于有用户界面影响的功能。
 
 ## 1. 输入资产
 
 | 资产 | 路径 / 链接 | 说明 |
 |---|---|---|
 | PRD 初稿 | `docs/requirements/<feature>-prd.md` | 原型评审后需要回填和校准 |
+| 产品总体设计 / 功能架构 | `docs/design/<feature>-product-overview-design.md` | 必需；缺失时先返回产品总体设计阶段 |
 | 领域术语 | `CONTEXT.md` | 核心名词、状态和业务规则 |
 | Discovery | `docs/discovery/<feature>-discovery.md` | 可选 |
 | 原型 / 线框图 | `<链接或导出图片路径>` | Excalidraw / Figma / Penpot / tldraw / Axure / Markdown |
+| 高保真 HTML 原型 | `docs/design/prototypes/<feature>/index.html` | 低保真原型评审通过后补齐；必须使用 Ant Design v6 |
 | 现有 API 草案 | `docs/api/specs/<feature>.yaml` | 可选；通常应先完成产品设计和 PRD 校准 |
 
 ## 2. 页面地图
@@ -99,9 +101,9 @@
 ## 8. 前端验收
 
 - loading、empty、error、no-permission、readonly、conflict、dirty-form 状态已展示，或明确不适用。
-- 每个表格列、筛选条件、表单字段、抽屉、弹窗和按钮都有数据来源或 mock fixture。
+- 每个表格列、筛选条件、表单字段、抽屉、弹窗和按钮都有数据来源或契约反推说明。
 - 设计可以拆成独立可演示的垂直切片。
-- 如果需要工程态原型，已规划 Storybook / Histoire 或静态 fixture。
+- 低保真原型评审通过后，高保真 HTML 原型使用 Ant Design v6 覆盖主流程、关键状态和响应式断点。
 
 ## 9. 决策与未决问题