visual-spec 0.1.0 → 0.1.2

package/docs/zh-CN/commands.md

@@ -0,0 +1,87 @@
+## 命令总览
+
+| 命令 | 作用 | 主要输入 | 主要输出 |
+| --- | --- | --- | --- |
+| `/vspec:new` | 从原始需求生成第一版规格产物 | 原始需求文本 + 交互式问答 | `/specs/`（original、stakeholders、roles、terms、flows、scenarios、scenario_details、dependencies、functions、questions）+ 初始化 `/docs/*` 输入归档目录 |
+| `/vspec:refine` | 应用补充/澄清材料，并同步更新详情与原型 | `/docs/refine/*`（或命令参数）+ `/specs/background/original.md` + 前置条件 `/specs/details/` | 追加更新到 `/specs/background/original.md`（变更清单 + 最新口径）+ 更新受影响的 `/specs/details/` 与 `/specs/prototypes/` |
+| `/vspec:refine-q` | 将已回答的问题合并回需求并形成新口径 | `/specs/background/original.md` + `/specs/background/questions.md` | 追加到 `/specs/background/original.md`（采纳项 + 变更清单 + 最新口径） |
+| `/vspec:detail` | 展开到“可实现”的单功能详细规格 | `/specs/functions/*` + 支撑产物（background/flows/roles；models 若已存在） | `/specs/details/<function_slug>/*`（RBAC、交互、校验、日志、通知、MQ、导入导出、定时任务等） |
+| `/vspec:verify` | 快速验证：生成模型与可运行原型用于评审 | 现有 `/specs/` 产物（functions + details + roles） | `/specs/models/*.md`、`/specs/prototypes/`（按 `scheme.yaml` 选栈生成可运行原型 + `scenario.html` 评审页） |
+| `/vspec:accept` | 生成验收用例 | functions/scenarios/details/roles/models | `/specs/acceptance/<function_slug>/acceptance_cases.md`、`/specs/acceptance/index.md` |
+| `/vspec:test` | 生成自动化测试代码 | 验收用例 + 仓库测试技术栈 | 写入既有测试目录或 `/tests/` |
+| `/vspec:impl` | 生成后端 + 前端联调实现代码 | specs/details/models/dependencies | 写入集成实现代码（API 合同、后端、前端对接） |
+| `/vspec:upgrade` | 基于遗留材料做升级/重构分析并生成新规格 | `/docs/current/file_list.md` + `/docs/legacy/*`（可选 templates/texts/assets）+ 既有 `/specs/background/original.md`（可选） | 生成/更新 `/specs/`（沿用 `/vspec:new` 结构）+ 同步技术选型到 `/scheme.yaml` |
+| `/vspec:change` | 处理变更：影响分析并更新产物 | `/docs/change/*`（可选 file_list.md）+ 既有 `/specs/` | 更新受影响文件（优先 `/specs/details/<module_slug>/`）+ `/specs/change_log.md`（更新前需要 git 快照提交） |
+| `/vspec:qc` | 对 `/specs/` 产物做质量检查 | 内置标准 + 可选 `quality_standard.md` + `/specs/` | `/specs/qc_report.md` |
+| `/vspec:plan` | 估算与排期 | functions/roles/flows/dependencies/details | `/specs/plan/plan_estimate.md`、`/specs/plan/plan_schedule.html` |
+
+## `/vspec:new`
+
+- 适用场景：刚拿到需求且信息不完整，需要快速形成“可评审的共同语言”
+- 关键输出：干系人、角色、术语、流程、场景、功能清单、开放问题
+- 目录初始化：创建 `/docs/` 及其子目录（legacy/current/change/refine/templates/texts/assets）用于输入归档与后续命令使用
+
+## `/vspec:refine`
+
+- 适用场景：实现中出现新信息/澄清，需要更新需求口径并同步更新详情与原型，且保留可追溯性
+- 输入：
+  - 默认：`/docs/refine/`（优先 `/docs/refine/file_list.md`，否则按文件名顺序读取）
+  - 可选：命令参数指定文件/目录（优先级更高）
+- 前置条件：`/specs/details/` 必须存在且非空；否则不执行（避免上游变化但下游未同步）
+- 关键输出：
+  - 追加“变更清单 + 最新口径 + 影响分析与产物同步”到 `original.md` 末尾
+  - 更新受影响的 `/specs/details/`（优先修改已有文件）与 `/specs/prototypes/`（尽量保持差异最小、可审查）
+
+## `/vspec:refine-q`
+
+- 适用场景：业务已在 `/specs/background/questions.md` 填写答案，需要合并回需求并形成新口径
+- 关键输出：采纳的 Q&A 项 + 变更清单 + 最新口径
+
+## `/vspec:detail`
+
+- 适用场景：在设计/实现前，需要把每个功能点展开到“可实现”的规格粒度
+- 关键输出：RBAC 到控件级、数据权限、加载/交互/校验矩阵、提交后处理、日志/通知矩阵、MQ、导入导出、定时任务等
+
+## `/vspec:verify`
+
+- 适用场景：在 details 已就绪后，尽快验证数据结构与页面形态，降低沟通误差
+- 前置条件：`/specs/details/` 必须存在且非空
+- 关键输出：模型文件（实体拆分/关系/状态机等）、可运行原型、场景评审页
+- UI 规范：生成或复用 `/prototype_ui_convention.md`（与 `/scheme.yaml` 同级），并以其作为唯一口径约束原型 UI 风格与交互
+- Note：执行 `/vspec:verify` 之前务必先审核 `/specs/functions/*` 与 `/specs/details/`，确保覆盖完整；否则原型与模型可能出现功能缺失。
+
+## `/vspec:accept`
+
+- 适用场景：用“可执行用例”对齐交付与验收
+- 关键输出：每功能点验收用例表，覆盖主流程、异常、边界、RBAC、数据权限
+
+## `/vspec:test`
+
+- 适用场景：将验收用例转化为可运行的自动化测试（E2E/API/单测）
+- 关键输出：优先复用仓库现有测试框架与脚本，避免引入新依赖
+
+## `/vspec:impl`
+
+- 适用场景：把规格产物转成可运行的后端 + 前端联调实现
+- 关键输出：API 合同、后端实现、前端页面与 API 对接、RBAC/状态机约束落地
+
+## `/vspec:change`
+
+- 适用场景：收到明确变更请求，需要可追溯的影响评估与更新
+- 输入：从 `/docs/change/` 读取（可选 `/docs/change/file_list.md` 作为有序输入清单；兼容旧路径 `/docs/changes/`）
+- 更新策略：优先更新受影响模块目录 `/specs/details/<module_slug>/`，并同步 models/functions/prototypes/acceptance 等
+- 更新前快照：若目标仓库是 git 仓库，更新前先做一次快照提交，保证差异可审查
+- 关键输出：结构化变更清单、影响分析表、变更日志以及对应产物更新
+
+## `/vspec:upgrade`
+
+- 适用场景：基于遗留系统材料做“升级/重构/迁移”分析，继承必要部分并生成新规格
+- 入口清单：`/docs/current/file_list.md`（缺失时生成模板）用于列出输入文件、用途、提取要点、是否必须
+- 输入范围：通常来自 `/docs/legacy/*` 与 `/docs/current/*`，也可组合 `/docs/templates/*`、`/docs/texts/*`、`/docs/assets/*`
+- 关键输出：按 `/vspec:new` 的产物结构生成/更新 `/specs/`，并在功能清单中标注 继承/新增/调整/废弃
+- 技术选型同步：从“系统技术规格”等输入中提取选型并写入 `/scheme.yaml`，供 `/vspec:verify` 与 `/vspec:impl` 使用
+
+## `/vspec:plan`
+
+- 适用场景：对齐交付节奏，通过故事地图拆解并产出排期
+- 关键输出：故事拆解与估算（人日）、迭代计划、排期页面（HTML）

package/docs/zh-CN/concepts.md

@@ -0,0 +1,36 @@
+## 设计原则
+
+### 1. 通过产物协作
+
+- 把“讨论”转成“可评审的产物”，降低对齐成本
+- 产物分层演进：原始需求 → 规格（`/specs`）→ 模型（`/specs/models`）→ 原型（`/specs/prototypes`）→ 详情（`/specs/details`）→ 验收/测试/代码
+
+### 2. 场景驱动拆解（不是功能堆砌）
+
+- 通过节点链（申请/审批/取消/变更/执行开始/执行结束等）覆盖主流程与回滚路径
+- 从场景驱动细节：每个功能点都应映射到“可执行的用户动作 + 可验证的预期结果”
+
+### 3. RBAC 与数据权限优先
+
+- RBAC 下沉到页面区域与控件级，避免“页面可见但按钮不该可点”
+- 数据权限独立建模（行/列/范围/状态/组织），再与 RBAC 组合（先授权，再过滤）
+
+### 4. 便于实现的细节表达
+
+- 用清单/表格表达页面加载、交互与提交后行为，便于工程实现与评审
+- 用“矩阵”表达校验/日志/通知，确保覆盖完整与可追溯
+
+### 5. 默认一致性与可观测性
+
+- 对外部依赖、MQ、重试、DLQ、补偿等给出明确规格
+- 默认要求可追踪（trace_id/request_id）、可审计（操作日志）、可告警（失败/积压）
+
+### 6. 验收 → 自动化 → 集成
+
+- 用验收用例作为研发与 QA 的共同语言
+- 优先复用仓库既有测试框架与目录约定，降低维护成本
+- 生成代码以“最小可审查差异 + 可运行端到端闭环”为目标
+
+### 7. 易于变更的需求
+
+- 生成的需求文档应可编辑、可阅读、问题易发现、修改成本低，并能快速适配变更

package/docs/zh-CN/getting-started.md

@@ -0,0 +1,84 @@
+## 快速开始
+
+本包提供一套由 `/vspec:*` 命令驱动的 Skill 工作流，用于把原始需求转成可评审的交付产物：规格、数据模型、可运行原型、详细设计、验收用例、测试与集成实现输入。
+
+### 1. 安装
+
+先全局安装 npm 包，再把 Skill 安装到 AI 编辑器的配置目录：
+
+- 安装与校验：`installation.md`
+
+安装/更新（npm）：
+
+```bash
+npm install -g visual-spec
+```
+
+安装/更新（pnpm）：
+
+```bash
+pnpm add -g visual-spec
+```
+
+安装/更新（yarn）：
+
+Yarn Classic：
+
+```bash
+yarn global add visual-spec
+```
+
+Yarn Berry（v2+）：
+
+```bash
+yarn dlx -p visual-spec vspec
+```
+
+### 2. 推荐流程
+
+- 初始规格：`/vspec:new`
+  - 执行过程中会生成开放问题清单（`/specs/background/questions.md`）
+  - 在继续流程前，把业务答案填写到该文件
+- 合并 Q&A 到需求口径：`/vspec:refine-q`
+- 详细规格：`/vspec:detail`
+- 快速验证（模型 + 原型）：`/vspec:verify`（要求 `/specs/details/` 非空）
+- 验收用例：`/vspec:accept`
+- 集成实现：`/vspec:impl`
+- 自动化测试：`/vspec:test`
+- 变更处理：`/vspec:change`
+- 升级/重构（继承遗留材料）：`/vspec:upgrade`
+
+### 3. 关键目录
+
+- `/docs/`：输入归档（legacy/current/change/refine/templates/texts/assets）
+- `/specs/`：生成产物（background/details/models/prototypes/acceptance 等）
+- `/scheme.yaml`：技术栈与包管理器选择（原型与实现必须遵循）
+
+目录结构参考：
+
+- `structure.md`
+
+下一步：
+
+- 阅读 `structure.md`，确认输入放在哪里、输出会生成到哪里
+
+### 4. 常见场景
+
+#### 补充/澄清（`refine`）
+
+- 把补充材料放到 `/docs/refine/`
+- 前置条件：`/specs/details/` 必须存在且非空，否则 `refine` 不执行
+- 运行：`/vspec:refine`
+- 结果：向 `/specs/background/original.md` 追加更新，并同步更新受影响的 `/specs/details/` 与 `/specs/prototypes/`
+
+#### 变更（`change`）
+
+- 把变更材料放到 `/docs/change/`（可选 `file_list.md`）
+- 运行：`/vspec:change`
+- 结果：做影响分析并更新产物（优先 `/specs/details/<module_slug>/`），同时更新变更日志
+
+#### 升级/重构（`upgrade`）
+
+- 在 `/docs/current/file_list.md` 中列出输入材料（遗留系统在 `/docs/legacy/`，新增输入在 `/docs/current/`）
+- 运行：`/vspec:upgrade`
+- 结果：生成/更新 `/specs/`，并把技术选型同步到 `/scheme.yaml`

package/docs/zh-CN/installation.md

@@ -0,0 +1,37 @@
+## 安装到支持 Skill 的 AI 编辑器
+
+本包使用脚本把内置的 Skill 目录复制到你的 AI 编辑器配置目录（Trae / Qwen / Kiro 等）。不同编辑器的配置路径可能不同，但安装逻辑一致：把 `visual-spec-skill` 安装到目标目录的 `skills/` 下。
+
+### 前置条件
+
+- Node.js >= 14
+
+### 安装/更新（npm）
+
+```bash
+npm install -g visual-spec
+```
+
+### 安装/更新（pnpm）
+
+```bash
+pnpm add -g visual-spec
+```
+
+### 安装/更新（yarn）
+
+Yarn Classic：
+
+```bash
+yarn global add visual-spec
+```
+
+Yarn Berry（v2+）：
+
+```bash
+yarn dlx -p visual-spec vspec
+```
+
+### 下一步
+
+- 快速开始：`getting-started.md`

package/docs/zh-CN/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/zh-CN/structure.md

@@ -0,0 +1,73 @@
+# 目录结构
+
+本文描述目标项目中使用的目录结构：
+- Skill 生成的 `/specs/` 产物树（需求/设计交付物）
+
+## 目标项目布局
+
+Skill 会按命令阶段逐步在 `/specs/` 下生成产物，并维护少量项目级配置与输入归档目录。典型目录结构如下：
+
+```text
+<your-project>/
+├─ docs/                                  # 输入归档（/vspec:new 会创建）
+│  ├─ legacy/                             # 遗留系统材料（功能、权限、交互、API 等）
+│  ├─ current/                            # 本次迭代新增/补充材料（目标、差异、流程、UI 约束等）
+│  │  └─ file_list.md                     # upgrade 入口清单（/vspec:upgrade 读取/生成）
+│  ├─ change/                             # 变更输入（/vspec:change 读取）
+│  │  └─ file_list.md                     # 可选：有序输入清单
+│  ├─ refine/                             # 补充/澄清输入（/vspec:refine 读取）
+│  │  └─ file_list.md                     # 可选：有序输入清单
+│  ├─ templates/                          # 模板（PRD/文案/UI/表格模板，可选）
+│  ├─ texts/                              # 文案（提示语、错误信息、协议、消息模板，可选）
+│  └─ assets/                             # 静态资源（设计稿、截图、原型图、图片等，可选）
+├─ scheme.yaml                            # 原型选栈（/vspec:verify 使用；缺失时会生成默认值）
+└─ specs/
+   ├─ background/                         # 背景分析与共享材料
+   │  ├─ original.md                      # 原始需求（或等价输入）
+   │  ├─ stakeholders.md                  # 干系人
+   │  ├─ roles.md                         # 角色与职责
+   │  ├─ terms.md                         # 术语表
+   │  ├─ scenarios.md                     # 场景清单
+   │  ├─ scenario_details/                # 场景节点细化：pre_post.md/constraints.md/variations.md/boundaries.md/symmetry.md
+   │  ├─ dependencies.md                  # 外部依赖
+   │  └─ questions.md                     # 开放问题（verify 前必须解决或显式跳过）
+   ├─ flows/                              # 流程图（PlantUML）
+   │  └─ *.puml
+   ├─ functions/                          # 功能清单（按模块拆分）
+   │  └─ *.md
+   ├─ details/                            # 单功能详细设计（/vspec:detail 输出）
+   │  └─ <module_slug>/
+   │     ├─ rbac/                         # RBAC
+   │     ├─ data_permission/              # 数据权限
+   │     ├─ page_load/
+   │     ├─ interaction/
+   │     ├─ validation_matrix/
+   │     ├─ logging_matrix/
+   │     ├─ notification_matrix/
+   │     ├─ mq/
+   │     ├─ nfp/                          # 非功能：性能/安全/兼容性/韧性/稳定性
+   │     ├─ file_import/
+   │     ├─ file_export/
+   │     └─ cron_job/
+   ├─ models/                             # 数据模型（/vspec:verify 输出）
+   │  ├─ *.md
+   │  └─ README.md
+   ├─ prototypes/                         # 可运行原型 + 评审页（/vspec:verify 输出）
+   │  └─ ...
+   ├─ acceptance/                         # 验收用例（/vspec:accept 输出）
+   │  ├─ index.md
+   │  └─ ...
+   ├─ qc_report.md                        # 质量报告（/vspec:qc 输出）
+   ├─ plan/                               # 规划输出（/vspec:plan 输出）
+   │  ├─ plan_estimate.md                 # 估算
+   │  └─ plan_schedule.html               # 排期页面
+   └─ change_log.md                       # 变更日志（/vspec:change 输出）
+```
+
+说明：
+- `docs/`：归档业务输入与交付对齐材料。建议使用 `legacy/current/change/refine/templates/texts/assets` 等子目录，并在文件名中包含来源/版本信息。
+- `scheme.yaml`：选择 `/vspec:verify` 与 `/vspec:impl` 使用的技术栈与选项。读取顺序为项目根目录的 `scheme.yaml` 优先，其次 `/specs/scheme.yaml`。若都不存在则生成默认 `scheme.yaml`。
+
+下一步：
+
+- 阅读 `commands.md`，了解各 `/vspec:*` 命令的输入、输出与使用场景

package/docs/zh-CN/ui-spec-modification-notes.md

@@ -0,0 +1,35 @@
+## 背景
+
+原型生成过程中，页面数量与类型会持续增长（Web + Mobile），如果没有统一的 UI 规范，很容易出现：
+
+- 同类页面布局不一致（表格/表单/详情）
+- 状态色与状态文案口径不一致
+- Mobile 与 Web 视觉语言割裂
+- 交互方式随意（新建页、页内表单、抽屉/弹窗使用不统一）
+
+因此引入统一且可编辑的 UI 规范文件：`/prototype_ui_convention.md`。
+
+## 变更点
+
+- 新增约束文件：`/prototype_ui_convention.md`（与 `/scheme.yaml` 同级）
+- `/vspec:verify` 生成/更新原型时：
+  - 若 `/prototype_ui_convention.md` 不存在：先生成默认模板（不覆盖已存在文件）
+  - 原型 UI 生成必须严格遵守 `/prototype_ui_convention.md`
+  - 若存在更严格的现有规范（例如 `/docs/current/ui_spec.md` 或 `/docs/current/ui_style.md`）：需把更严格的规则合并进 `/prototype_ui_convention.md`，并以合并后的结果作为最终口径
+
+## 如何修改 UI 规范
+
+- 直接编辑目标项目根目录的 `/prototype_ui_convention.md`
+- 建议只改“口径”，不要写具体实现细节：
+  - 色彩与状态映射
+  - 表格/表单/详情的通用结构
+  - Drawer/Modal 的使用规则
+  - 字体与间距（Web/Mobile）
+  - 文案与反馈（成功/失败/权限/空态/错误态）
+- 修改完成后重跑 `/vspec:verify`，使生成/更新的页面整体对齐新规范
+
+## 不建议的修改
+
+- 不建议把规范写成某个页面的特例规则（会破坏整体一致性）
+- 不建议引入新的 UI 组件库（除非项目技术栈明确要求）
+- 不建议在规范中硬编码大量页面级颜色/尺寸（优先抽象为少量全局变量与结构规则）

package/docs/zh-CN/workflows.md

@@ -0,0 +1,65 @@
+## 工作流
+
+### 1. 需求分析（`/vspec:new`）
+
+- 输入原始需求
+- 回答开放问题（关键假设、范围、规则、依赖）
+- 在 `/specs/` 下得到第一版产物：角色、术语、流程、场景、功能清单、依赖、问题清单
+
+### 2. 详细规格（`/vspec:detail`）
+
+- 以 `/specs/functions/*` 为输入，在 `/specs/details/<function_slug>/` 下生成单功能规格
+- 目标：把“需求”转成可实现的设计输入：
+  - RBAC 到控件级 + 数据权限
+  - 加载/交互/校验矩阵
+  - 提交后检查/处理/跳转
+  - 日志/通知矩阵、MQ、导入导出、定时任务
+
+### 3. 方案验证（`/vspec:verify`）
+
+- 前置条件：`/specs/details/` 存在且非空
+- 基于 `/specs/`（functions + details + roles）生成：
+  - `/specs/models/*.md`：实体与字段、关系、状态机、索引、外部字段来源
+  - `/specs/prototypes/`：按 `scheme.yaml` 选栈生成可运行原型，以及 `scenario.html` 场景评审页
+- 目标：尽早暴露理解偏差，尽快收敛到可评审方案
+
+可选：分段生成原型
+
+- 原型很大或希望按流程更细粒度控制时，可按阶段增量生成：
+  - `/vspec:proto-apply`：申请流页面 + 工作台差异
+  - `/vspec:proto-approve`：审批流页面 + 工作台差异
+  - `/vspec:proto-execute`：执行流页面（包含移动端 `/m/*`）
+  - `/vspec:proto-crud`：配置/主数据 CRUD 管理页
+
+### 4. 验收用例（`/vspec:accept`）
+
+- 在 `/specs/acceptance/` 下生成验收用例
+- 目标：定义验收口径与覆盖范围（主流程、异常、边界、RBAC、数据权限）
+
+### 5. 自动化测试（`/vspec:test`）
+
+- 读取验收用例与仓库现有测试技术栈
+- 生成最小可运行的一组 E2E/API/单测
+
+### 6. 集成实现（`/vspec:impl`）
+
+- 读取 specs、details、models、dependencies
+- 按仓库约定生成后端 + 前端联调代码（API 合同 → 后端实现 → 前端对接）
+
+### 7. 估算与排期（`/vspec:plan`）
+
+- 把功能与场景拆成用户故事，估算工作量，并生成迭代排期
+- 输出：
+  - `/specs/plan/plan_estimate.md`
+  - `/specs/plan/plan_schedule.html`
+
+### 8. 变更处理（`/vspec:change`）
+
+- 提供变更输入
+- 输出影响分析与变更日志，并更新受影响的产物与用例
+
+## 安装（npm）
+
+- 推荐在目标项目根目录安装：`npm install <git-url>`
+- 安装后 Skill 会被复制到：`<your-project>/.trae/skills/visual-spec-skill/`
+- 需要时可手动安装：`npx vspec --force`

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "visual-spec",
-  "version": "0.1.0",
-  "description": "Trae skill: visual-spec-skill (/vspec:* commands) for requirement analysis, prototyping, detailing, testing, and planning.",
+  "version": "0.1.2",
+  "description": "AI skill: visual-spec-skill (/vspec:* commands) for requirement analysis, prototyping, detailing, testing, and planning.",
   "license": "MIT",
   "type": "commonjs",
   "bin": {
-    "vreq-skill": "bin/vreq-skill.cjs"
+    "vspec": "bin/vspec.cjs"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.cjs",
@@ -13,7 +13,7 @@
     "dry-run": "node scripts/postinstall.cjs --dry-run"
   },
   "files": [
-    ".trae/skills/starter-skill/",
+    "skills/visual-spec-skill/",
     "bin/",
     "docs/",
     "scripts/",

package/scripts/postinstall.cjs

@@ -12,6 +12,8 @@ function parseArgs(argv) {
     dryRun: args.has("--dry-run"),
     force: args.has("--force"),
     target: getValue("--target"),
+    skillDir: getValue("--skill-dir") || getValue("--target-skill-dir"),
+    skillsDir: getValue("--skills-dir") || getValue("--target-skills-dir"),
   };
 }
 
@@ -71,12 +73,20 @@ async function copyDirRecursive(fromDir, toDir) {
 }
 
 async function main() {
-  const { dryRun, force, target } = parseArgs(process.argv.slice(2));
+  const { dryRun, force, target, skillDir, skillsDir } = parseArgs(process.argv.slice(2));
 
   const packageRoot = path.resolve(__dirname, "..");
-  const sourceSkillDir = path.join(packageRoot, ".trae", "skills", "starter-skill");
+  const sourceSkillDir = path.join(packageRoot, "skills", "visual-spec-skill");
   const initCwd = target || process.env.INIT_CWD || process.cwd();
-  const targetSkillDir = path.join(initCwd, ".trae", "skills", "starter-skill");
+  const resolvedSkillsDir =
+    skillsDir && path.resolve(initCwd, skillsDir);
+  const resolvedSkillDir =
+    skillDir && path.resolve(initCwd, skillDir);
+  const targetSkillDir =
+    resolvedSkillDir ||
+    (resolvedSkillsDir
+      ? path.join(resolvedSkillsDir, "visual-spec-skill")
+      : path.join(initCwd, ".trae", "skills", "visual-spec-skill"));
 
   if (!(await pathExists(sourceSkillDir))) {
     throw new Error(`Skill source directory not found: ${sourceSkillDir}`);
@@ -91,7 +101,7 @@ async function main() {
   if (dryRun) {
     process.stdout.write(
       [
-        "[vreq-skill] dry-run",
+        "[vspec] dry-run",
         `- source: ${sourceSkillDir}`,
         `- target: ${targetSkillDir}`,
       ].join("\n") + "\n",
@@ -107,10 +117,10 @@ async function main() {
   }
 
   await copyDirRecursive(sourceSkillDir, targetSkillDir);
-  process.stdout.write(`[vreq-skill] installed to ${targetSkillDir}\n`);
+  process.stdout.write(`[vspec] installed to ${targetSkillDir}\n`);
 }
 
 main().catch((error) => {
-  process.stderr.write(`[vreq-skill] install failed: ${error?.message || error}\n`);
+  process.stderr.write(`[vspec] install failed: ${error?.message || error}\n`);
   process.exitCode = 1;
 });