visual-spec 0.1.0 → 0.1.2

package/README.md

@@ -1,31 +1,31 @@
-本工程是一个需求分析与交付辅助 Skill，提供一组以 `/vspec:*` 命令驱动的流程，用于把原始需求逐步产出为规格、模型、原型、细节、验收用例、测试与集成实现所需的输入。
+This repo provides a requirements analysis and delivery assistant Skill. It offers a `/vspec:*` command-driven workflow that turns raw requirements into reviewable artifacts: specs, data models, runnable prototypes, detailed design, acceptance cases, tests, and integrated implementation inputs.
 
-## 功能概览
+## Overview
 
-- 需求分析：从原始描述生成背景、干系人、角色、术语、流程、场景、细节、依赖、功能清单与待确认问题
-- 方案验证：生成数据模型、页面原型与场景确认页
-- 细节梳理：按功能点输出权限/数据权限/交互/校验/日志/通知/MQ/导入导出/定时任务等规格
-- 验收与测试：生成验收测试用例与自动化测试代码
-- 集成开发：生成前后端集成代码（按仓库现有技术栈与约定）
-- 变更响应：分析需求变更影响并更新产物，生成变更日志
-- 排期规划：按功能清单输出估算与排期（HTML）
+- Requirements analysis: generate background, stakeholders, roles, terms, flows, scenarios, details, dependencies, function list, and open questions
+- Solution verification: generate data models, runnable prototypes, and a scenario review page
+- Detailed design: produce RBAC/data-permission/interaction/validation/logging/notification/MQ/import-export/cron specs per function
+- Acceptance & testing: generate acceptance cases and automated test code
+- Integrated implementation: generate backend + frontend integrated code (aligned with the repo’s actual stack and conventions)
+- Change handling: analyze impacts, update artifacts, and produce a change log
+- Planning: estimate and schedule based on the function list (HTML output)
 
-## 命令
+## Commands
 
-- `/vspec:new`：生成基础规格产物（输出到 `/specs/`）
-- `/vspec:refine`：读取 `/docs/refine/` 的修订材料（或命令参数），修订需求并同步更新 `/specs/details/` 与 `/specs/prototypes/`（需已有 details 才执行）
-- `/vspec:refine-q`：基于 `questions.md` 的已回答内容修订需求内容，并更新 `/specs/background/original.md` 中的“当前生效需求”
-- `/vspec:verify`：生成数据模型与 Vue + Ant Design Vue 原型（输出到 `/specs/models/`、`/specs/prototypes/`）
-- `/vspec:detail`：按功能点生成细节规格（输出到 `/specs/details/`）
-- `/vspec:accept`：生成验收测试用例（输出到 `/specs/acceptance/`）
-- `/vspec:test`：生成自动化测试代码（写入仓库既有测试目录或 `/tests/`）
-- `/vspec:impl`：生成前后端集成代码（只允许写入 `/specs/prototypes/` 原型工程内）
-- `/vspec:upgrade`：从 `/docs/`（legacy/current/templates/texts/assets）读取旧系统与新增材料，升级改造并生成/更新 `/specs/`，同步技术规格到 `/scheme.yaml`
-- `/vspec:change`：读取 `/docs/change/` 的变更材料，做影响分析并更新产物，输出 `/specs/change_log.md`（更新前需 git 快照提交）
-- `/vspec:qc`：对 `/specs/` 产物进行质量检查并输出不合格清单（输出到 `/specs/qc_report.md`）
-- `/vspec:plan`：估算与排期（输出到 `/specs/plan_estimate.md`、`/specs/plan_schedule.html`）
+- `/vspec:new`: Generate baseline spec artifacts (writes to `/specs/`)
+- `/vspec:refine`: Apply refinements from `/docs/refine/` (or command arguments) and update `/specs/details/` and `/specs/prototypes/` (requires existing details)
+- `/vspec:refine-q`: Merge answered items from `questions.md` back into the spec and update the canonical requirement in `/specs/background/original.md`
+- `/vspec:detail`: Generate per-function detailed specs (writes to `/specs/details/`)
+- `/vspec:verify`: Generate data models and a stack-selected runnable prototype (per `/scheme.yaml`) (writes to `/specs/models/`, `/specs/prototypes/`; requires non-empty `/specs/details/`)
+- `/vspec:accept`: Generate acceptance test cases (writes to `/specs/acceptance/`)
+- `/vspec:test`: Generate automated test code (writes into the repo’s existing test directories or `/tests/`)
+- `/vspec:impl`: Generate integrated backend + frontend implementation code (writes under `/specs/`)
+- `/vspec:upgrade`: Upgrade/redesign based on legacy + new inputs under `/docs/` (legacy/current/templates/texts/assets), generate/update `/specs/`, and sync technical selections to `/scheme.yaml`
+- `/vspec:change`: Analyze and apply change inputs from `/docs/change/`, update artifacts, and write `/specs/change_log.md` (requires a git snapshot commit before updating)
+- `/vspec:qc`: Run artifact quality checks and write a report (writes to `/specs/qc_report.md`)
+- `/vspec:plan`: Generate estimation and schedule (writes to `/specs/plan/plan_estimate.md`, `/specs/plan/plan_schedule.html`)
 
-## 目录结构
+## Directory Structure
 
-- `.trae/skills/starter-skill/SKILL.md`：Skill 定义与命令流程
-- `.trae/skills/starter-skill/prompts/`：各命令对应的提示词文件
+- `skills/visual-spec-skill/SKILL.md`: Skill definition and command workflow
+- `skills/visual-spec-skill/prompts/`: prompt files used by each command

package/docs/en-US/commands.md

@@ -0,0 +1,87 @@
+## Command Overview
+
+| Command | Purpose | Primary Inputs | Primary Outputs |
+| --- | --- | --- | --- |
+| `/vspec:new` | Generate baseline spec artifacts from raw requirements | Raw requirement text + interactive Q&A | `/specs/` (original, stakeholders, roles, terms, flows, scenarios, scenario_details, dependencies, functions, questions) + initializes `/docs/*` archive directories |
+| `/vspec:refine` | Apply refinement materials and sync impacted details and prototypes | `/docs/refine/*` (or command args) + baseline `/specs/background/original.md` + prerequisite `/specs/details/` | Appends to `/specs/background/original.md` (change list + canonical) + updates impacted `/specs/details/` and `/specs/prototypes/` |
+| `/vspec:refine-q` | Merge answered questions back into the requirement | `/specs/background/original.md` + `/specs/background/questions.md` | Appends to `/specs/background/original.md` (adopted items + change list + canonical) |
+| `/vspec:detail` | Expand per-function detailed specs | `/specs/functions/*` + supporting artifacts (background/flows/roles; models if any) | `/specs/details/<function_slug>/*` (RBAC, interaction, validation, logging, notifications, MQ, import/export, cron, etc.) |
+| `/vspec:verify` | Generate models and prototype for fast validation | Existing `/specs/` artifacts (functions + details + roles) | `/specs/models/*.md`, `/specs/prototypes/` (stack-selected runnable prototype + `scenario.html` review page) |
+| `/vspec:accept` | Generate acceptance test cases | functions/scenarios/details/roles/models | `/specs/acceptance/<function_slug>/acceptance_cases.md`, `/specs/acceptance/index.md` |
+| `/vspec:test` | Generate automated test code | acceptance cases + repo test stack | Writes into existing test directories or `/tests/` |
+| `/vspec:impl` | Generate integrated backend + frontend implementation | specs/details/models/dependencies | Writes integrated implementation code (API contract, backend, frontend integration) |
+| `/vspec:upgrade` | Analyze and generate new specs based on legacy materials | `/docs/current/file_list.md` + `/docs/legacy/*` (optional templates/texts/assets) + existing `/specs/background/original.md` (if any) | Generate/update `/specs/` in `/vspec:new` structure + sync technical selections to `/scheme.yaml` |
+| `/vspec:change` | Apply change inputs, do impact analysis, and update artifacts | `/docs/change/*` (optional file_list.md) + existing `/specs/` | Update impacted files (prefers `/specs/details/<module_slug>/`) + `/specs/change_log.md` (requires git snapshot commit before updating) |
+| `/vspec:qc` | Run quality checks on `/specs/` artifacts | built-in standard + optional project `quality_standard.md` + `/specs/` | `/specs/qc_report.md` |
+| `/vspec:plan` | Estimation and scheduling | functions/roles/flows/dependencies/details | `/specs/plan/plan_estimate.md`, `/specs/plan/plan_schedule.html` |
+
+## `/vspec:new`
+
+- When to use: you just received the requirement and information is incomplete; you need a shared language and a first-cut spec quickly
+- Key outputs: stakeholders, roles, terms, flows, scenarios, function list, open questions
+- Directory initialization: creates `/docs/` and its subdirectories (legacy/current/change/refine/templates/texts/assets) for input archiving and future command inputs
+
+## `/vspec:refine`
+
+- When to use: new information/refinements appear during implementation; you need to update the canonical requirement while keeping traceability, and sync details and prototype
+- Inputs:
+  - Default: `/docs/refine/` (prefers `/docs/refine/file_list.md`, otherwise reads files by name order)
+  - Optional: command args can override with explicit files/directories (higher priority)
+- Prerequisite: `/specs/details/` must exist and be non-empty; otherwise `refine` does not run (to avoid upstream changes without downstream sync)
+- Key outputs:
+  - Append “change list + canonical requirement + impact analysis and artifact updates” to the end of `original.md`
+  - Update impacted `/specs/details/` (prefer updating existing files) and `/specs/prototypes/` (minimal reviewable diff)
+
+## `/vspec:refine-q`
+
+- When to use: business has answered `/specs/background/questions.md`, and you want to merge those answers into the requirement and produce a new canonical version
+- Key outputs: adopted Q&A items + change list + canonical requirement
+
+## `/vspec:detail`
+
+- When to use: before design/implementation, you need each function to be specified at an implementable level
+- Key outputs: RBAC to control level, data permissions, load/interaction/validation matrices, post-submit processing, logging/notification matrices, MQ, import/export, cron jobs
+
+## `/vspec:verify`
+
+- When to use: after details are available, you want to validate the data structure and page shape quickly and reduce misunderstanding risk
+- Prerequisite: `/specs/details/` exists and is non-empty
+- Key outputs: model files (entity splitting), runnable prototype, scenario review page
+- UI spec: generates or reuses `/prototype_ui_convention.md` (same directory as `/scheme.yaml`) and uses it as the single source of truth to constrain prototype UI style and interactions
+- Note: before running `/vspec:verify`, review `/specs/functions/*` and `/specs/details/` to ensure the scope is complete; otherwise models and prototypes may miss features.
+
+## `/vspec:accept`
+
+- When to use: align delivery and acceptance with an executable set of cases
+- Key outputs: per-function acceptance case tables covering happy path, exceptions, boundaries, RBAC, and data permissions
+
+## `/vspec:test`
+
+- When to use: turn acceptance cases into runnable automated tests (E2E/API/unit)
+- Key outputs: reuse the repo’s existing test frameworks and scripts; avoid introducing new dependencies
+
+## `/vspec:impl`
+
+- When to use: convert spec artifacts into runnable integrated backend + frontend code
+- Key outputs: API contract, backend implementation, frontend pages and API integration, RBAC/state machine enforcement
+
+## `/vspec:change`
+
+- When to use: explicit change requests arrive and you need traceable updates and impact assessment
+- Inputs: read from `/docs/change/` (optional `/docs/change/file_list.md` as an ordered entry list; compatible with legacy path `/docs/changes/`)
+- Update strategy: prioritize the impacted module directory `/specs/details/<module_slug>/` and sync models/functions/prototypes/acceptance as needed
+- Pre-update snapshot: if the target repo is a git repo, create a snapshot commit before writing any updates so diffs are reviewable
+- Key outputs: structured change list, impact analysis table, change log, and corresponding artifact updates
+
+## `/vspec:upgrade`
+
+- When to use: do an “upgrade/redesign/migration” analysis based on legacy system materials, inherit what is needed, and generate new spec artifacts
+- Entry list: `/docs/current/file_list.md` (generates a template if missing) to list input files, usage, extracted key points, and whether required
+- Input scope: usually from `/docs/legacy/*` and `/docs/current/*`, optionally combined with `/docs/templates/*`, `/docs/texts/*`, `/docs/assets/*`
+- Key outputs: generate/update `/specs/` using the `/vspec:new` artifact structure, and label inherited/new/adjusted/deprecated items in the function list
+- Stack sync: extract technical selections from “system technical spec” inputs and write them into `/scheme.yaml` for `/vspec:verify` and `/vspec:impl`
+
+## `/vspec:plan`
+
+- When to use: align delivery cadence, decompose via story mapping, and build a schedule
+- Key outputs: story decomposition and estimation (person-days), iteration plan, and an HTML story map

package/docs/en-US/concepts.md

@@ -0,0 +1,36 @@
+## Design Principles
+
+### 1. Collaborate Through Artifacts
+
+- Turn “discussion” into “reviewable artifacts” to reduce alignment cost
+- Artifacts progress by layers: raw requirement → specs (`/specs`) → models (`/specs/models`) → prototype (`/specs/prototypes`) → details (`/specs/details`) → acceptance/tests/code
+
+### 2. Scenario-Driven Decomposition (Not Feature Piling)
+
+- Use node chains (apply/approve/cancel/change/execute-start/execute-end, etc.) to cover the happy path and rollback paths
+- Drive details from scenarios: every function point should map to “executable user actions + verifiable expected outcomes”
+
+### 3. RBAC and Data Permissions First
+
+- RBAC down to page sections and controls to avoid “page is visible but buttons shouldn’t be clickable”
+- Model data permissions independently (row/column/scope/status/org) and compose them with RBAC (authorize first, then filter)
+
+### 4. Implementation-Friendly Detail
+
+- Express page load, interactions, and post-submit behavior as checklists/tables for engineering implementation and review
+- Use “matrices” for validation/logging/notifications to ensure complete coverage and traceability
+
+### 5. Consistency and Observability by Default
+
+- Provide explicit specs for external dependencies, MQ, retries, DLQ, compensations, etc.
+- Require traceability (trace_id/request_id), auditability (activity logs), and alertability (failures/backlogs) by default
+
+### 6. Acceptance → Automation → Integration
+
+- Use acceptance cases as a shared language for dev and QA
+- Prefer reusing existing test frameworks and directory conventions to reduce maintenance
+- Generated code focuses on minimal reviewable diffs and a runnable end-to-end loop
+
+### 7. Requirements That Are Easy to Change
+
+- Generated requirement docs should be editable, readable, easy to spot issues, easy to fix, and quick to adapt to changes.

package/docs/en-US/getting-started.md

@@ -0,0 +1,85 @@
+## Getting Started
+
+This package provides a `/vspec:*` command-driven Skill that turns raw requirements into reviewable artifacts: specs, data models, runnable prototypes, detailed design, acceptance cases, tests, and integrated implementation inputs.
+
+### 1. Installation
+
+Install the npm package, then install the Skill into your AI editor configuration directory:
+
+- Installation and verification: `installation.md`
+
+Install / update (npm):
+
+```bash
+npm install -g visual-spec
+```
+
+Install / update (pnpm):
+
+```bash
+pnpm add -g visual-spec
+```
+
+Install / update (yarn):
+
+Yarn Classic:
+
+```bash
+yarn global add visual-spec
+```
+
+Yarn Berry (v2+):
+
+```bash
+yarn dlx -p visual-spec vspec
+```
+
+### 2. Recommended Workflow
+
+- Initial spec: `/vspec:new`
+  - During execution it generates an open question list (`/specs/background/questions.md`)
+  - Fill in business answers in that file before continuing the workflow
+- Merge Q&A into the canonical requirement: `/vspec:refine-q`
+- Detailed specs: `/vspec:detail`
+- Quick validation (models + prototype): `/vspec:verify` (requires non-empty `/specs/details/`)
+- Acceptance cases: `/vspec:accept`
+- Integrated implementation: `/vspec:impl`
+- Automated tests: `/vspec:test`
+- Change handling: `/vspec:change`
+- Upgrade/redesign (inherit from legacy materials): `/vspec:upgrade`
+
+### 3. Key Directories
+
+- `/docs/`: input archive (legacy/current/change/refine/templates/texts/assets)
+- `/specs/`: generated artifacts (background/details/models/prototypes/acceptance, etc.)
+- `/scheme.yaml`: stack and package manager selection (prototype and implementation must follow it)
+
+Directory structure reference:
+
+- `structure.md`
+ - `structure.md`
+
+Next:
+
+- Read `structure.md` to confirm where inputs are stored and where outputs are generated
+
+### 4. Common Scenarios
+
+#### Refinements (`refine`)
+
+- Put refinement materials into `/docs/refine/`
+- Prerequisite: `/specs/details/` must exist and be non-empty, otherwise `refine` does not run
+- Run: `/vspec:refine`
+- Result: appends updates to `/specs/background/original.md` and syncs impacted `/specs/details/` and `/specs/prototypes/`
+
+#### Changes (`change`)
+
+- Put change materials into `/docs/change/` (optional `file_list.md`)
+- Run: `/vspec:change`
+- Result: performs impact analysis, updates artifacts (prefers `/specs/details/<module_slug>/`), and updates the change log
+
+#### Upgrade/Redesign (`upgrade`)
+
+- List input materials in `/docs/current/file_list.md` (legacy system under `/docs/legacy/`, new inputs under `/docs/current/`)
+- Run: `/vspec:upgrade`
+- Result: generates/updates `/specs/` and syncs technical selections into `/scheme.yaml`

package/docs/en-US/installation.md

@@ -0,0 +1,37 @@
+## Install into Skill-Enabled AI Editors
+
+This package uses a script to copy the built-in Skill directory into your AI editor configuration directory (Trae / Qwen / Kiro, etc.). The exact config path differs by editor, but the installation logic is the same: install `visual-spec-skill` into the target `skills/` directory.
+
+### Prerequisites
+
+- Node.js >= 14
+
+### Install / Update (npm)
+
+```bash
+npm install -g visual-spec
+```
+
+### Install / Update (pnpm)
+
+```bash
+pnpm add -g visual-spec
+```
+
+### Install / Update (yarn)
+
+Yarn Classic:
+
+```bash
+yarn global add visual-spec
+```
+
+Yarn Berry (v2+):
+
+```bash
+yarn dlx -p visual-spec vspec
+```
+
+### Next
+
+- Getting started: `getting-started.md`

package/docs/en-US/scheme.example.yaml

@@ -0,0 +1,71 @@
+schema_version: 1
+
+selected:
+  prototype_frontend_stack: vue3_vite_ts_antdv
+  prototype_frontend_framework: vue
+  prototype_frontend_ui_library: ant-design-vue
+  prototype_backend_stack: java17_springboot3
+  prototype_database: mysql8
+  package_manager: npm
+  language: zh-CN
+
+prototype_options:
+  calendar_view:
+    enabled: auto
+    view_default: month
+    resource_dimension: auto
+
+catalog:
+  prototype_frontend_stacks:
+    - id: vue3_vite_ts_antdv
+      name: Vue 3 + Vite + TypeScript + Ant Design Vue
+      framework: vue
+      framework_version: "3"
+      build_tool: vite
+      language: typescript
+      ui_library: ant-design-vue
+      router: vue-router@4
+      state: pinia
+      http_client: axios
+      charting: echarts
+      date_library: dayjs
+      styling: less
+      lint: eslint
+      formatter: prettier
+      unit_test: vitest
+      e2e_test: playwright
+
+    - id: react18_vite_ts_antd
+      name: React 18 + Vite + TypeScript + Ant Design
+      framework: react
+      framework_version: "18"
+      build_tool: vite
+      language: typescript
+      ui_library: antd
+      router: react-router@6
+      state: redux-toolkit
+      http_client: axios
+      charting: echarts-for-react
+      date_library: dayjs
+      styling: less
+      lint: eslint
+      formatter: prettier
+      unit_test: vitest
+      e2e_test: playwright
+
+  prototype_backend_stacks:
+    - id: java17_springboot3
+      name: Java 17 + Spring Boot 3
+      language: java
+      framework: spring-boot
+      api_style: rest
+      auth: spring-security-jwt
+      orm: jpa_or_mybatis
+
+    - id: node18_nestjs10_ts
+      name: Node.js 18 + NestJS 10 + TypeScript
+      language: typescript
+      framework: nestjs
+      api_style: rest
+      auth: jwt
+      orm: prisma

package/docs/en-US/structure.md

@@ -0,0 +1,74 @@
+# Directory Structure
+
+This document describes the directory structure used in a target project:
+- The `/specs/` artifact tree generated by the Skill (requirements/design deliverables)
+
+
+## Target Project Layout
+
+The Skill generates artifacts under `/specs/` (incrementally by command stage) and maintains a small set of project-level configs and input archive directories. A typical layout:
+
+```text
+<your-project>/
+├─ docs/                                  # Input archive (/vspec:new creates it)
+│  ├─ legacy/                             # Legacy system materials (features, permissions, interactions, APIs, etc.)
+│  ├─ current/                            # New/additional materials for this iteration (goals, deltas, flows, UI constraints, etc.)
+│  │  └─ file_list.md                     # Upgrade entry list (/vspec:upgrade reads/generates)
+│  ├─ change/                             # Change inputs (/vspec:change reads)
+│  │  └─ file_list.md                     # Optional ordered input list
+│  ├─ refine/                             # Refinement inputs (/vspec:refine reads)
+│  │  └─ file_list.md                     # Optional ordered input list
+│  ├─ templates/                          # Templates (PRD/copy/UI/table templates, optional)
+│  ├─ texts/                              # Copywriting (prompts, error messages, agreements, message templates, optional)
+│  └─ assets/                             # Static assets (designs, screenshots, prototypes, images, optional)
+├─ scheme.yaml                            # Prototype stack selection (/vspec:verify uses; created with defaults if missing)
+└─ specs/
+   ├─ background/                         # Background analysis and shared materials
+   │  ├─ original.md                      # Raw requirement (or equivalent input)
+   │  ├─ stakeholders.md                  # Stakeholders
+   │  ├─ roles.md                         # Roles and responsibilities
+   │  ├─ terms.md                         # Glossary
+   │  ├─ scenarios.md                     # Scenario list
+   │  ├─ scenario_details/                # Scenario details per node: pre_post.md/constraints.md/variations.md/boundaries.md/symmetry.md
+   │  ├─ dependencies.md                  # External dependencies
+   │  └─ questions.md                     # Open questions (must be resolved or explicitly skipped before verify)
+   ├─ flows/                              # Flow diagrams (PlantUML)
+   │  └─ *.puml
+   ├─ functions/                           # Function list (split by module)
+   │  └─ *.md
+   ├─ details/                             # Per-function detailed design (/vspec:detail output)
+   │  └─ <module_slug>/
+   │     ├─ rbac/                          # RBAC
+   │     ├─ data_permission/               # Data permissions
+   │     ├─ page_load/
+   │     ├─ interaction/
+   │     ├─ validation_matrix/
+   │     ├─ logging_matrix/
+   │     ├─ notification_matrix/
+   │     ├─ mq/
+   │     ├─ nfp/                           # Non-functional requirements (performance, security, compatibility, resilience, stability)
+   │     ├─ file_import/
+   │     ├─ file_export/
+   │     └─ cron_job/
+   ├─ models/                              # Data models (/vspec:verify output)
+   │  ├─ *.md
+   │  └─ README.md
+   ├─ prototypes/                          # Runnable prototype + review pages (/vspec:verify output)
+   │  └─ ...
+   ├─ acceptance/                          # Acceptance cases (/vspec:accept output)
+   │  ├─ index.md
+   │  └─ ...
+   ├─ qc_report.md                         # Quality report (/vspec:qc output)
+   ├─ plan/                                # Planning outputs (/vspec:plan output)
+   │  ├─ plan_estimate.md                  # Estimation
+   │  └─ plan_schedule.html                # Schedule page
+   └─ change_log.md                        # Change log (/vspec:change output)
+```
+
+Notes:
+- `docs/`: archive business inputs and delivery alignment materials. Use subdirectories like `legacy/current/change/refine/templates/texts/assets` and include source/version in filenames.
+- `scheme.yaml`: selects the stack and options used by `/vspec:verify` and `/vspec:impl`. It reads `scheme.yaml` at the project root first, then `/specs/scheme.yaml`. If neither exists, it creates a default `scheme.yaml`.
+
+Next:
+
+- Read `commands.md` for each `/vspec:*` command’s inputs, outputs, and usage scenarios

package/docs/en-US/ui-spec-modification-notes.md

@@ -0,0 +1,35 @@
+## Background
+
+As the prototype grows (Web + Mobile), the number and types of pages will keep increasing. Without a unified UI convention, it is very easy to get:
+
+- Inconsistent layouts across similar pages (tables/forms/details)
+- Inconsistent status colors and status wording
+- Fragmented visual language between Mobile and Web
+- Inconsistent interaction patterns (create flows, in-page forms, drawer/modal usage)
+
+To prevent this, the prototype generation is constrained by an editable UI convention file: `/prototype_ui_convention.md`.
+
+## What Changed
+
+- Add a project-level constraint file: `/prototype_ui_convention.md` (same directory as `/scheme.yaml`)
+- When `/vspec:verify` generates/updates prototypes:
+  - If `/prototype_ui_convention.md` does not exist: generate a default template first (do not overwrite existing files)
+  - Prototype UI generation must follow `/prototype_ui_convention.md`
+  - If stricter existing rules exist (for example `/docs/current/ui_spec.md` or `/docs/current/ui_style.md`), merge the stricter rules into `/prototype_ui_convention.md` and treat the merged file as the final source of truth
+
+## How to Modify the UI Convention
+
+- Edit `/prototype_ui_convention.md` at the target project root
+- Prefer updating conventions rather than writing implementation details:
+  - Color/status mappings
+  - Common structure for tables/forms/details
+  - Drawer/Modal usage rules
+  - Typography and spacing (Web/Mobile)
+  - Copy and feedback patterns (success/failure/permission/empty/error states)
+- Re-run `/vspec:verify` after changes so newly generated/updated pages align with the updated convention
+
+## Not Recommended
+
+- Do not make the convention a set of page-specific exceptions (it breaks overall consistency)
+- Do not introduce a new UI component library unless the project’s selected stack requires it
+- Do not hardcode lots of page-level colors/sizes in the convention; prefer a small set of global tokens and structural rules

package/docs/en-US/workflows.md

@@ -0,0 +1,65 @@
+## Workflow
+
+### 1. Requirements Analysis (`/vspec:new`)
+
+- Provide the raw requirement input
+- Answer open questions (key assumptions, scope, rules, dependencies)
+- Get baseline artifacts under `/specs/`: roles, terms, flows, scenarios, function list, dependencies, questions
+
+### 2. Detailed Specs (`/vspec:detail`)
+
+- Using `/specs/functions/*` as input, generate per-function specs under `/specs/details/<function_slug>/`
+- Goal: turn “requirements” into implementable design inputs:
+  - RBAC down to control level, and data permissions
+  - load/interaction/validation matrices
+  - post-submit checks/processing/navigation
+  - logging/notification matrices, MQ specs, import/export, cron jobs
+
+### 3. Solution Verification (`/vspec:verify`)
+
+- Prerequisite: `/specs/details/` exists and is non-empty
+- Based on `/specs/` (functions + details + roles), generate:
+  - `/specs/models/*.md`: entities and fields, relationships, state machines, indexes, external field sources
+  - `/specs/prototypes/`: stack-selected runnable prototype (per `scheme.yaml`) and the `scenario.html` scenario review page
+- Goal: expose misunderstandings early and converge to a reviewable solution
+
+Optional: segmented prototype generation
+
+- For large prototypes or tighter control by flow, you can generate incrementally:
+  - `/vspec:proto-apply`: application flow pages + dashboard differences
+  - `/vspec:proto-approve`: approval flow pages + dashboard differences
+  - `/vspec:proto-execute`: execution flow pages (including mobile `/m/*`)
+  - `/vspec:proto-crud`: config/master-data CRUD admin pages
+
+### 4. Acceptance Cases (`/vspec:accept`)
+
+- Generate acceptance cases into `/specs/acceptance/`
+- Goal: define acceptance criteria and coverage (happy path, exceptions, boundaries, RBAC, data permissions)
+
+### 5. Automated Tests (`/vspec:test`)
+
+- Read acceptance cases and the repo’s existing test stack
+- Generate a minimal runnable set of E2E/API/unit tests
+
+### 6. Integrated Implementation (`/vspec:impl`)
+
+- Read specs, details, models, and dependencies
+- Generate integrated backend + frontend code following repo conventions (API contract → backend implementation → frontend integration)
+
+### 7. Planning (`/vspec:plan`)
+
+- Split functions and scenarios into user stories, estimate effort, and build iteration schedules
+- Outputs:
+  - `/specs/plan/plan_estimate.md`
+  - `/specs/plan/plan_schedule.html`
+
+### 8. Change Handling (`/vspec:change`)
+
+- Provide change inputs
+- Output impact analysis and change log, and update impacted artifacts and cases
+
+## Installation (npm)
+
+- Recommended at your project root: `npm install <git-url>`
+- After installation, the Skill is copied to: `<your-project>/.trae/skills/visual-spec-skill/`
+- Manual installation (if needed): `npx vspec --force`