visual-spec 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/docs/en-US/workflows.md +0 -5
  2. package/docs/zh-CN/workflows.md +0 -5
  3. package/package.json +2 -2
  4. package/skills/visual-spec-skill/SKILL-zh-CN.md +11 -8
  5. package/skills/visual-spec-skill/SKILL.md +11 -8
  6. package/skills/visual-spec-skill/prompts/vspec_detail/cron_job.md +1 -1
  7. package/skills/visual-spec-skill/prompts/vspec_detail/nfp.md +1 -1
  8. package/skills/visual-spec-skill/prompts/vspec_detail/state_machine.md +1 -1
  9. package/skills/visual-spec-skill/prompts/vspec_detail/timeline.md +1 -1
  10. package/skills/visual-spec-skill/prompts/vspec_refine/refine.md +1 -1
  11. package/skills/visual-spec-skill/prompts/vspec_refine/refine_q.md +4 -0
  12. package/skills/visual-spec-skill/prompts/vspec_verify/model.md +3 -0
  13. package/skills/visual-spec-skill/prompts/vspec_verify/prototype.md +5 -0
package/docs/en-US/workflows.md CHANGED
@@ -1,10 +1,5 @@
1
1
  ## Workflow
2
2
 
3
- ### 0. Setup
4
-
5
- - Install this Skill at your project root (the target project contains `.trae/`)
6
- - Ensure `.trae/skills/visual-spec-skill/` exists in the target project (see “Installation” below)
7
-
8
3
  ### 1. Requirements Analysis (`/vspec:new`)
9
4
 
10
5
  - Provide the raw requirement input
package/docs/zh-CN/workflows.md CHANGED
@@ -1,10 +1,5 @@
1
1
  ## 工作流
2
2
 
3
- ### 0. 准备
4
-
5
- - 在目标项目根目录安装本 Skill（目标项目包含 `.trae/`）
6
- - 确保目标项目存在 `.trae/skills/visual-spec-skill/`（见下方“安装”）
7
-
8
3
  ### 1. 需求分析（`/vspec:new`）
9
4
 
10
5
  - 输入原始需求
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "visual-spec",
3
- "version": "0.1.1",
4
- "description": "Trae skill: visual-spec-skill (/vspec:* commands) for requirement analysis, prototyping, detailing, testing, and planning.",
3
+ "version": "0.1.2",
4
+ "description": "AI skill: visual-spec-skill (/vspec:* commands) for requirement analysis, prototyping, detailing, testing, and planning.",
5
5
  "license": "MIT",
6
6
  "type": "commonjs",
7
7
  "bin": {
package/skills/visual-spec-skill/SKILL-zh-CN.md CHANGED
@@ -74,18 +74,21 @@ description: "将原始需求分析为可评审的视觉规格，并生成相关
74
74
  1. 读取 refine 输入：
75
75
  - 若命令参数提供了路径，将其视为 refine 输入源（文件/目录）。
76
76
  - 否则读取 `/docs/refine/`（若存在优先读 `/docs/refine/file_list.md`；否则按文件名顺序读取）。
77
- 2. 加载 `prompts/vspec_refine/refine.md` 应用补充信息、更新需求口径并同步更新受影响的产物。
78
- 3. 将 refine 结果追加到 `/specs/background/original.md`，并更新受影响的 `/specs/details/` 与 `/specs/prototypes/`。
77
+ 2. 若 `prompts/vspec_refine/refine.md` 不存在：立即结束，不执行任何写入。
78
+ 3. 加载 `prompts/vspec_refine/refine.md` 应用补充信息、更新需求口径并同步更新受影响的产物。
79
+ 4. 将 refine 结果追加到 `/specs/background/original.md`，并更新受影响的 `/specs/details/` 与 `/specs/prototypes/`。
79
80
 
80
81
  ### `/vspec:refine-q`
81
82
 
82
83
  用于基于“已回答的问题”补充与更新需求。
83
84
 
84
85
  流程：
85
- 1. 读取 `/specs/background/questions.md` 并选择已回答项。
86
- 2. 加载 `prompts/vspec_refine/refine_q.md` 将答案合并进最新口径。
87
- 3. 将结果追加到 `/specs/background/original.md`。
88
- 4. 更新 `/specs/background/questions.md`，标记本次运行中已视为回答的条目：
86
+ 1. 若 `/specs/background/questions.md` 不存在：立即结束，不执行任何写入。
87
+ 2. 若 `/specs/background/questions.md` 中不存在待回答的问题：立即结束，不执行任何写入。
88
+ 3. 读取 `/specs/background/questions.md` 并选择已回答项。
89
+ 4. 加载 `prompts/vspec_refine/refine_q.md` 将答案合并进最新口径。
90
+ 5. 将结果追加到 `/specs/background/original.md`。
91
+ 6. 更新 `/specs/background/questions.md`，标记本次运行中已视为回答的条目：
89
92
  - 用 `<mark>...</mark>` 包裹 `回答` 与 `状态`，以高亮已回答项。
90
93
 
91
94
  ### `/vspec:detail`
@@ -124,14 +127,14 @@ description: "将原始需求分析为可评审的视觉规格，并生成相关
124
127
  - `cron_job.md`：模块定时任务总结（模块整体，不按功能拆分）。
125
128
  4. 仅写入生成的（涉及的）详情文档：
126
129
  - 单功能：`/specs/details/<module_slug>/<logic_type>/<function_slug>.(md|html)`
127
- - 模块级：`/specs/details/<module_slug>/<logic_type>/overall.(md|html)`
130
+ - 模块级：`/specs/details/<module_slug>/<logic_type>/<module_slug>.(md|html)`
128
131
 
129
132
  ### `/vspec:verify`
130
133
 
131
134
  用于生成模型与可运行原型，用于快速验证与评审。
132
135
 
133
136
  流程：
134
- 0. 确保 `/specs/details/` 存在且非空；若缺失则停止并提示用户先运行 `/vspec:detail`。
137
+ 0. 确保 `/specs/details/` 存在且非空；若缺失则立即停止并提示前置条件：“请先执行 /vspec:detail 生成 /specs/details/，再执行 /vspec:verify”。
135
138
  1. 若 `/specs/background/questions.md` 存在且仍有未回答的问题，先要求用户回答再继续（允许逐条跳过，但必须保证不存在“未处理”的问题）。
136
139
  2. 加载 `prompts/vspec_verify/model.md` 生成数据模型。
137
140
  3. 将模型文件写入 `/specs/models/*.md`。
package/skills/visual-spec-skill/SKILL.md CHANGED
@@ -75,18 +75,21 @@ Flow:
75
75
  1. Read refine inputs:
76
76
  - If command arguments are provided, treat them as refine input sources (files/directories).
77
77
  - Otherwise, read `/docs/refine/` (prefer `/docs/refine/file_list.md` as the entry if present; else read files in name order).
78
- 2. Load `prompts/vspec_refine/refine.md` to apply the refinement, update the canonical requirement, and update impacted artifacts.
79
- 3. Append the refinement result to `/specs/background/original.md`, and update impacted `/specs/details/` and `/specs/prototypes/` accordingly.
78
+ 2. If `prompts/vspec_refine/refine.md` is missing, stop immediately and do nothing.
79
+ 3. Load `prompts/vspec_refine/refine.md` to apply the refinement, update the canonical requirement, and update impacted artifacts.
80
+ 4. Append the refinement result to `/specs/background/original.md`, and update impacted `/specs/details/` and `/specs/prototypes/` accordingly.
80
81
 
81
82
  ### `/vspec:refine-q`
82
83
 
83
84
  Use this command to refine and update the requirement based on answered questions.
84
85
 
85
86
  Flow:
86
- 1. Read `/specs/background/questions.md` and pick answered items.
87
- 2. Load `prompts/vspec_refine/refine_q.md` to merge answers into the canonical requirement.
88
- 3. Append the refinement result to `/specs/background/original.md`.
89
- 4. Update `/specs/background/questions.md` to mark items that are treated as answered in this run:
87
+ 1. If `/specs/background/questions.md` is missing, stop immediately and do nothing.
88
+ 2. If `/specs/background/questions.md` contains no pending/unanswered questions, stop immediately and do nothing.
89
+ 3. Read `/specs/background/questions.md` and pick answered items.
90
+ 4. Load `prompts/vspec_refine/refine_q.md` to merge answers into the canonical requirement.
91
+ 5. Append the refinement result to `/specs/background/original.md`.
92
+ 6. Update `/specs/background/questions.md` to mark items that are treated as answered in this run:
90
93
  - Wrap the `回答` and `状态` values with `<mark>...</mark>` so the answered items are visually highlighted.
91
94
 
92
95
  ### `/vspec:detail`
@@ -125,14 +128,14 @@ Flow:
125
128
  - `cron_job.md`: scheduled jobs summary for the module (overall; not per function).
126
129
  4. Write only the generated (involved) detail documents:
127
130
  - Per-function: `/specs/details/<module_slug>/<logic_type>/<function_slug>.(md|html)`
128
- - Module-level: `/specs/details/<module_slug>/<logic_type>/overall.(md|html)`
131
+ - Module-level: `/specs/details/<module_slug>/<logic_type>/<module_slug>.(md|html)`
129
132
 
130
133
  ### `/vspec:verify`
131
134
 
132
135
  Use this command to generate models and a runnable prototype for validation.
133
136
 
134
137
  Flow:
135
- 0. Ensure `/specs/details/` exists and is non-empty; if missing, stop and ask the user to run `/vspec:detail` first.
138
+ 0. Ensure `/specs/details/` exists and is non-empty; if missing, stop and output the prerequisite message: “Run /vspec:detail to generate /specs/details/ before /vspec:verify”.
136
139
  1. If `/specs/background/questions.md` exists and contains unanswered questions, ask the user to answer them before continuing (allow skip per question, but ensure none remains unanswered).
137
140
  2. Load `prompts/vspec_verify/model.md` to generate data models.
138
141
  3. Write model files to `/specs/models/*.md`.
package/skills/visual-spec-skill/prompts/vspec_detail/cron_job.md CHANGED
@@ -21,4 +21,4 @@
21
21
  3. 若同一模块有多个任务，按任务分段输出（可用二级标题 `## {名称}`），每段仅包含上述表格，不要额外追加其他表格结构。
22
22
 
23
23
  输出写入：
24
- - 将结果写入上游指定的 markdown 文件路径（通常在 `/specs/details/<module_slug>/cron_job/overall.md`）
24
+ - 将结果写入上游指定的 markdown 文件路径（通常在 `/specs/details/<module_slug>/cron_job/<module_slug>.md`）
package/skills/visual-spec-skill/prompts/vspec_detail/nfp.md CHANGED
@@ -28,4 +28,4 @@
28
28
  - 若该模块没有任何可明确的非功能性约束/指标（例如纯离线 demo、无外部依赖、无数据规模假设），输出单行：`SKIP`
29
29
 
30
30
  输出写入：
31
- - 将结果写入上游指定的 markdown 文件路径（通常在 `/specs/details/<module_slug>/nfp/overall.md`）
31
+ - 将结果写入上游指定的 markdown 文件路径（通常在 `/specs/details/<module_slug>/nfp/<module_slug>.md`）
package/skills/visual-spec-skill/prompts/vspec_detail/state_machine.md CHANGED
@@ -22,4 +22,4 @@
22
22
  - 每条迁移箭头必须标注 Trigger；如有关键 Guard，用 `[ ... ]` 标注在箭头文案中
23
23
 
24
24
  输出写入：
25
- - 将结果写入上游指定的 markdown 文件路径（通常在 `/specs/details/<module_slug>/state_machine/overall.md`）
25
+ - 将结果写入上游指定的 markdown 文件路径（通常在 `/specs/details/<module_slug>/state_machine/<module_slug>.md`）
package/skills/visual-spec-skill/prompts/vspec_detail/timeline.md CHANGED
@@ -120,4 +120,4 @@ HTML 模板（必须逐字遵守结构；不要输出任何 markdown 文本，
120
120
  4. segment-label：用“行为/结果”描述（例如：允许提交、禁止变更、需补充审批、按新税率计算、进入降级队列），必须可验收
121
121
 
122
122
  输出写入：
123
- - 将结果写入上游指定的文件路径（通常在 `/specs/details/<module_slug>/timeline/overall.html`）
123
+ - 将结果写入上游指定的文件路径（通常在 `/specs/details/<module_slug>/timeline/<module_slug>.html`）
package/skills/visual-spec-skill/prompts/vspec_refine/refine.md CHANGED
@@ -45,7 +45,7 @@
45
45
  - 必须更新 `/specs/details/` 下受影响模块的文档（优先更新既有文件，避免无意义新文件）：
46
46
  - 若变更涉及角色/权限：更新 `rbac/` 与 `data_permission/`
47
47
  - 若变更涉及页面交互/字段/流程：更新 `interaction/`、`page_load/`、`validation_matrix/`、`post_submit_*` 等相关文档
48
- - 若变更涉及状态/操作可用性：更新 `state_machine/overall.*`（如存在）与 `decision_matrix/`、`validation_matrix/`
48
+ - 若变更涉及状态/操作可用性：更新 `state_machine/<module_slug>.*`（如存在）与 `decision_matrix/`、`validation_matrix/`
49
49
  - 若变更涉及外部依赖：更新 `dependencies.md` 对应模块的调用时机与失败兜底，并在细节规格中体现
50
50
  - 必须更新 `/specs/prototypes/`：
51
51
  - 页面/路由/菜单/按钮/表单字段必须与最新的细节规格一致
package/skills/visual-spec-skill/prompts/vspec_refine/refine_q.md CHANGED
@@ -1,5 +1,9 @@
1
1
  你是一名资深需求分析师。你的任务是：基于“待确认问题”的回答内容，将新增澄清与决策合并进需求归档文件，并更新“当前生效需求（Canonical）”。本命令用于从 questions 的答案反向修订 original。
2
2
 
3
+ 终止条件（必须）：
4
+ 1. 若 `/specs/background/questions.md` 不存在：立即结束，不做任何写入；仅输出一句“未找到 questions.md，/vspec:refine-q 结束”。
5
+ 2. 若 `/specs/background/questions.md` 中不存在“待回答的问题”（判断口径：存在 `状态` 为“未回答/待确认/需修改/待补充/待澄清”之一，或 `回答` 为空/仅空白）：立即结束，不做任何写入；仅输出一句“无待回答问题，/vspec:refine-q 结束”。
6
+
3
7
  输入信息包含：
4
8
  - 现有需求归档与分析：`/specs/background/original.md`
5
9
  - 问答列表：`/specs/background/questions.md`（包含“回答/状态/回答者/回答时间”等字段）
package/skills/visual-spec-skill/prompts/vspec_verify/model.md CHANGED
@@ -1,6 +1,8 @@
1
1
  你是一名资深数据架构师。你的任务是：基于已有需求分析产物，产出一组可评审的数据模型文档，并写入 `/specs/models/*.md`。
2
2
 
3
3
  前置规则（必须）：
4
+ 0. 在开始建模前，必须检查 `/specs/details/` 是否存在且非空：
5
+ - 若不存在或为空：立即停止，不生成任何模型文件；仅输出一句“前置条件不满足：请先执行 /vspec:detail 生成 /specs/details/，再执行 /vspec:verify”。
4
6
  1. 在开始建模前，先检查是否存在 `/specs/background/questions.md`。
5
7
  2. 若存在，则解析其中的问答列表（markdown 列表格式），找出“状态”为“未回答”（或“回答”为空）的所有问题。
6
8
  3. 对所有未回答的问题，必须先向用户逐条提问并等待用户回复后再继续建模：
@@ -19,6 +21,7 @@
19
21
  - 术语表（/specs/background/terms.md）
20
22
  - 角色与任务（/specs/background/roles.md）
21
23
  - 功能清单（/specs/functions/*）
24
+ - 需求细节（/specs/details/，必须参考其中的 RBAC/数据权限/状态机/校验/通知/MQ/导入导出/定时任务等约束）
22
25
  - 场景与细节（/specs/background/scenarios.md、/specs/background/scenario_details/ 或 /specs/background/scenario_details.md（旧版））
23
26
  - 外部依赖（/specs/background/dependencies.md）
24
27
 
package/skills/visual-spec-skill/prompts/vspec_verify/prototype.md CHANGED
@@ -1,9 +1,14 @@
1
1
  你是一名资深前端原型工程师。你的任务是：基于功能清单、数据模型、角色列表，生成一套可运行的页面原型，并写入 `/specs/prototypes/`。原型工程必须严格按 `scheme.yaml` 选择技术栈；禁止随意切换 UI 框架/构建工具。
2
2
 
3
+ 前置条件（必须）：
4
+ 1. 在生成任何模型/原型之前，必须检查 `/specs/details/` 是否存在且非空：
5
+ - 若不存在或为空：立即停止，不生成任何原型文件；仅输出一句“前置条件不满足：请先执行 /vspec:detail 生成 /specs/details/，再执行 /vspec:verify”。
6
+
3
7
  输入信息包含：
4
8
  - 角色与任务（/specs/background/roles.md）
5
9
  - 功能清单（/specs/functions/*，尤其是 core.md）
6
10
  - 数据模型（/specs/models/*.md）
11
+ - 需求细节（/specs/details/，必须以其为准约束页面字段、校验、状态流转、按钮可用性、权限与数据范围）
7
12
  - 场景与流程（/specs/background/scenarios.md、/specs/flows/*.puml）
8
13
 
9
14
  技术栈选择（scheme.yaml，必须）：