ai-spec-tool 0.1.0

package/assets/.agents/skills/rules-creator/assets/vision-gen.md

@@ -0,0 +1,613 @@
+# Vision File Generator (Spec) — 逐步询问版
+
+## 0) 生成目标（不可变，不询问用户）
+
+* 输出文件：`./docs/global/vision.md`
+* 输出格式：Markdown
+* 语言：中文为主
+* 目标：通过逐步提问收集信息，形成项目愿景与边界
+* 禁止使用默认内容、禁止跳过提问
+
+---
+
+## 1) 交互入口（必须逐步询问）
+
+### 1.0 启动语（必须最先执行）
+
+第一句只说：
+
+> 现在开始创建项目愿景（Vision）。
+> 我会一步一步问你问题，你只需要按问题回答即可。
+> 先从第 1 题开始：这个项目要解决的核心问题是什么？
+
+---
+
+## 2) 必问题清单（严格顺序、一次只问一题）
+
+### Q1. 核心问题（Problem）
+
+询问：
+
+> 这个项目要解决的**核心问题**是什么？
+> 用一句话描述：谁在什么情况下遇到什么痛点？
+
+补问规则（若过于模糊）：
+
+* 追问：痛点发生的场景是什么？
+* 追问：现有解决方案为什么不够好？
+
+---
+
+### Q2. 目标用户（Target User）
+
+询问：
+
+> 主要用户是谁？
+> A) 个人用户  
+> B) 开发者  
+> C) 团队/公司  
+> D) 仅自己内部使用  
+> E) 其他（说明）
+
+---
+
+### Q3. 成功结果（Outcome）
+
+询问：
+
+> 做完这个项目后，用户能完成什么“之前做不到或很麻烦的事”？
+> 请写 1–3 条可验证的结果。
+
+---
+
+>>>>
+
+<<<<
+
+## Q4. 核心范围（Scope / MVP 设计）
+
+### 目的
+
+基于用户已回答的 **Q1–Q3（核心问题 / 目标用户 / 成功结果）**，
+**由系统先生成一个合理的 MVP 能力草案**，再由用户确认或调整，
+而不是要求用户从零开始自己列功能。
+
+---
+
+### 执行流程（严格顺序）
+
+#### Step 1：系统生成 MVP 草案（必须）
+
+在询问用户前，你必须先：
+
+* 综合以下已知信息：
+
+  * Q1：核心问题
+  * Q2：目标用户
+  * Q3：成功结果
+* 推导出一个 **合理、克制、可落地的 MVP 功能清单**
+* 数量控制在 **3–5 项**，每一项必须：
+
+  * 直接服务于“成功结果”
+  * 避免实现细节
+  * 用一句话描述“能力”，而不是“实现方式”
+
+然后向用户展示，例如：
+
+> 基于你目前的回答，我为你整理了一个**第一阶段 MVP 能力草案**：
+>
+> 1. …
+> 2. …
+> 3. …
+> 4. …
+
+---
+
+#### Step 2：请求用户确认或调整（必须）
+
+紧接着询问用户（只能二选一，不开放发散）：
+
+> 你希望如何处理这个 MVP 草案？
+> A) 接受这个版本
+> B) 我来调整（请直接修改或增删）
+
+---
+
+#### Step 3：用户反馈处理规则
+
+* 若用户选择 **A（接受）**：
+
+  * 将该清单作为 MVP Scope
+  * 进入下一题（Q5）
+
+* 若用户选择 **B（我来调整）**：
+
+  * 用户可以：
+
+    * 删除某项
+    * 合并某项
+    * 新增能力
+  * 你只做 **整理与澄清**，不得擅自加入新能力
+  * 整理完成后，**必须再次让用户确认最终版本**
+
+---
+
+### 数量与收敛规则（防止 scope 爆炸）
+
+* 若最终功能点 > 7：
+
+  * 必须提示：
+
+    > 当前功能点较多，已超出典型 MVP 范围
+    > 请圈出 **最关键的 5 条**
+* 若用户坚持保留全部：
+
+  * 接受，但在文档中标注：`⚠️ 范围偏大（用户确认）`
+
+---
+
+### 禁止事项（非常重要）
+
+* ❌ 不允许直接让用户“自己随便列”
+* ❌ 不允许系统擅自决定最终范围
+* ❌ 不允许引入未出现在 Q1–Q3 中的目标
+* ❌ 不允许讨论实现方式（技术、框架、架构）
+
+---
+
+## Q5. 非目标（Non-goals）— 强制（协作式收敛）
+
+### 目的
+
+基于 **Q1–Q4（核心问题 / 用户 / 成功结果 / MVP 范围）**，
+**由系统先提出“合理的不做清单”**，
+再由用户确认或调整，用于**明确边界、防止范围膨胀**。
+
+---
+
+### 执行流程（严格顺序）
+
+---
+
+### Step 1：系统生成 Non-goals 建议清单（必须）
+
+在询问用户前，你必须先：
+
+* 综合以下信息：
+
+  * Q1：核心问题（项目为何存在）
+  * Q2：目标用户（谁在用）
+  * Q3：成功结果（做到什么算成功）
+  * Q4：已确认的 MVP 范围（现在只做什么）
+
+* 推导出一个 **“合理且克制”的 Non-goals 建议清单**
+
+* 数量为 **3–6 条**
+
+* 每一条必须满足：
+
+  * 明确排除一个「常见但当前不必要」的扩展方向
+  * 与当前 MVP 目标 **不直接冲突**
+  * 使用“不做……”句式
+
+然后向用户展示，例如：
+
+> 基于你目前的回答，以及当前 MVP 范围，我建议在第一阶段**明确不做以下内容**：
+>
+> * 不做多端同步
+> * 不做社交 / 社区功能
+> * 不做复杂权限与角色系统
+> * 不做付费 / 订阅机制
+
+---
+
+### Step 2：请求用户确认或调整（必须）
+
+紧接着询问用户（只能以下几种操作）：
+
+> 对这份「非目标」清单，你希望如何处理？
+> A) 全部接受
+> B) 删除某几项（请指出）
+> C) 新增我认为现在不做的项（请补充）
+
+> ⚠️ 不允许回答“随便 / 都可以”
+
+---
+
+### Step 3：用户反馈处理规则
+
+* 若用户选择 **A（全部接受）**：
+
+  * 该清单直接作为 Non-goals
+  * 进入下一题（Q6）
+
+* 若用户选择 **B（删除）**：
+
+  * 删除指定项
+  * 不自动补新项
+  * 若剩余项 < 3：
+
+    * 提示用户需至少保留 3 条，并请其补充
+
+* 若用户选择 **C（新增）**：
+
+  * 接受用户新增内容
+  * 只做语言整理，不改变含义
+  * 新增项必须使用“不做……”句式
+
+* 任何情况下：
+
+  * 最终 Non-goals 数量必须 ≥ 3
+  * 若不足，必须要求用户补齐
+
+---
+
+### 防失控规则（非常重要）
+
+* 若用户试图删除**所有** Non-goals：
+
+  * 必须提醒：
+
+    > 如果没有明确的非目标，项目范围会持续膨胀
+    > 请至少保留 3 条当前阶段明确不做的内容
+
+* 若用户新增的 Non-goals 与 Q4 MVP 范围冲突：
+
+  * 必须指出冲突并请求澄清
+
+---
+
+### 禁止事项
+
+* ❌ 不允许系统擅自决定最终 Non-goals
+* ❌ 不允许引入与 Q1–Q4 无关的排除项
+* ❌ 不允许讨论“以后可能做”（那是 roadmap，不是 Non-goals）
+* ❌ 不允许出现模糊描述（如：不做太复杂的东西）
+
+---
+
+### Q6. 约束与偏好（Constraints）
+
+询问：
+
+> 有哪些硬约束或偏好吗？（可多选/补充）
+> A) 技术栈固定（说明）
+> B) 时间限制（说明）
+> C) 预算限制（说明）
+> D) 必须可扩展/长期维护
+> E) 需要快速上线验证
+> F) 其他（说明）
+
+---
+
+## Q7. 成功标准（Success Criteria）— 强制（协作式定义）
+
+### 目的
+
+基于 **Q1–Q6（核心问题 / 目标用户 / 成功结果 / MVP 范围 / 非目标 / 约束）**，
+**由系统先提出一组“可验证、可执行的成功标准建议”**，
+再由用户确认或调整，用于：
+
+* 明确「什么算完成」
+* 作为后续 bugfix / update / refactor / plan 的最高验收依据
+* 防止项目在“感觉差不多了”时失控
+
+---
+
+### 执行流程（严格顺序）
+
+---
+
+### Step 1：系统生成成功标准建议（必须）
+
+在询问用户前，你必须先：
+
+* 综合以下信息：
+
+  * Q1：核心问题（解决什么）
+  * Q2：目标用户（给谁用）
+  * Q3：成功结果（用户能做到什么）
+  * Q4：已确认 MVP 范围（现在只做什么）
+  * Q5：非目标（明确不做什么）
+  * Q6：约束与偏好（时间 / 技术 / 质量侧重）
+
+* 推导出一组 **“与当前阶段匹配的成功标准建议”**
+
+* 数量控制在 **3–6 条**
+
+* 每一条必须满足：
+
+  * **可观察 / 可验证**（不是感觉好不好）
+  * 不依赖未来功能或 Non-goals
+  * 明确指向“是否达成项目目标”
+  * 使用客观描述，而非情绪或主观判断
+
+#### 成功标准类型（至少覆盖 3 个维度）
+
+系统生成的建议中，**必须覆盖以下维度中的至少 3 类**：
+
+* 功能达成（用户是否能完成核心任务）
+* 稳定性（错误 / 崩溃 / 异常）
+* 性能或响应（如有明确交互）
+* 可维护性（结构、边界、可扩展）
+* 可用性（用户是否无需额外指导）
+
+---
+
+### Step 2：向用户展示并请求确认（必须）
+
+向用户展示生成的建议清单，例如：
+
+> 基于目前对项目的理解，我为你整理了一组**第一阶段的成功标准建议**：
+>
+> 1. …
+> 2. …
+> 3. …
+> 4. …
+
+然后询问（只能以下几种操作）：
+
+> 对这组成功标准，你希望如何处理？
+> A) 全部接受
+> B) 修改其中某几条（请指出）
+> C) 新增我认为必要的标准（请补充）
+
+> ⚠️ 不允许回答“随便 / 都可以”
+
+---
+
+### Step 3：用户反馈处理规则
+
+* 若用户选择 **A（全部接受）**：
+
+  * 将该清单作为最终 Success Criteria
+  * 进入下一题或生成阶段
+
+* 若用户选择 **B（修改）**：
+
+  * 只允许修改表述或阈值，不允许引入新维度
+  * 修改后，必须再次向用户确认最终版本
+
+* 若用户选择 **C（新增）**：
+
+  * 接受用户新增内容
+  * 检查是否与 Q4 MVP 或 Q5 Non-goals 冲突
+  * 若冲突，必须指出并请求澄清
+
+---
+
+### 数量与质量控制规则（强制）
+
+* 最终成功标准数量必须在 **3–6 条** 之间
+* 若用户新增导致 >6 条：
+
+  * 必须提示：
+
+    > 当前成功标准偏多，建议保留最关键的 5 条
+* 不允许出现以下模糊表述：
+
+  * “用户觉得好用”
+  * “性能还不错”
+  * “系统比较稳定”
+* 必须将模糊表述转换为**可验证描述**
+
+---
+
+### 禁止事项（非常重要）
+
+* ❌ 不允许系统擅自决定最终成功标准
+* ❌ 不允许引入尚未定义的未来功能
+* ❌ 不允许与 Non-goals 冲突
+* ❌ 不允许使用时间型承诺（如：上线一周内）
+
+---
+
+## Q8. 关键风险（Risks）— 强制（协作式识别）
+
+### 目的
+
+基于 **Q1–Q7（问题 / 用户 / 成功结果 / MVP 范围 / 非目标 / 约束 / 成功标准）**，
+**由系统先识别并提出“当前阶段最可能影响项目成功的关键风险”**，
+再由用户确认或调整，用于：
+
+* 提前暴露高风险点
+* 影响后续架构、实现顺序与验证策略
+* 防止“做完才发现根本跑不通”
+
+---
+
+### 执行流程（严格顺序）
+
+---
+
+### Step 1：系统生成关键风险建议（必须）
+
+在询问用户前，你必须先：
+
+* 综合以下信息：
+
+  * Q1：核心问题（问题是否真实、是否可解）
+  * Q2：目标用户（是否能触达、是否真的需要）
+  * Q3：成功结果（是否可验证）
+  * Q4：已确认 MVP 范围（是否过大 / 过小）
+  * Q5：非目标（是否留下关键空洞）
+  * Q6：约束与偏好（时间 / 技术 / 资源）
+  * Q7：成功标准（是否过于严格或模糊）
+
+* 识别出 **当前阶段最可能阻碍成功的风险**
+
+* 提出 **2–4 条风险建议**（不少于 2 条）
+
+* 每一条风险必须：
+
+  * 与现有信息直接相关（不是泛泛而谈）
+  * 明确“风险来源”
+  * 用一句话说明“为什么这是风险”
+
+#### 常见风险类型（用于推导，不必全部覆盖）
+
+* 需求风险（问题是否被正确理解）
+* 技术风险（实现难度、性能、依赖不确定）
+* 数据风险（数据来源、质量、权限）
+* 用户风险（获取、留存、使用成本）
+* 范围风险（scope 过大 / MVP 不聚焦）
+* 合规与安全风险（若相关）
+
+---
+
+### Step 2：向用户展示并请求确认（必须）
+
+向用户展示生成的风险清单，例如：
+
+> 基于目前对项目的理解，我识别出以下**第一阶段关键风险**：
+>
+> 1. …（原因说明）
+> 2. …
+> 3. …
+
+然后询问（只能以下几种操作）：
+
+> 对这组风险判断，你希望如何处理？
+> A) 全部接受
+> B) 删除我认为不成立的风险（请指出）
+> C) 新增你认为重要但未列出的风险（请补充）
+
+> ⚠️ 不允许回答“随便 / 都可以”
+
+---
+
+### Step 3：用户反馈处理规则
+
+* 若用户选择 **A（全部接受）**：
+
+  * 将该清单作为最终关键风险
+  * 结束 Vision 访谈流程，进入生成阶段
+
+* 若用户选择 **B（删除）**：
+
+  * 删除指定项
+  * 若剩余风险 < 1：
+
+    * 提示用户至少需要 1 条关键风险
+
+* 若用户选择 **C（新增）**：
+
+  * 接受用户新增风险
+  * 仅做语言整理，不改变含义
+  * 若新增风险与现有信息冲突：
+
+    * 必须指出并请求澄清
+
+---
+
+### 风险数量与质量控制（强制）
+
+* 最终风险数量必须在 **1–4 条** 之间
+* 不允许出现以下模糊表述：
+
+  * “可能会有点难”
+  * “风险不大”
+  * “应该没问题”
+* 必须将模糊描述转换为**具体风险来源**
+
+---
+
+### 禁止事项（非常重要）
+
+* ❌ 不允许系统擅自决定最终风险
+* ❌ 不允许引入与 Q1–Q7 无关的泛化风险
+* ❌ 不允许将“以后可以优化”当作风险
+* ❌ 不允许讨论解决方案（风险 ≠ 对策）
+
+> 风险对策应在后续 `plan / architecture / roadmap` 中处理
+
+---
+
+## 3) 用户回答不足时的处理（统一规则）
+
+* 若用户回答过短/模糊：只追问当前题的澄清点，不跳题
+* 若用户说「随便/你定」：
+
+  * 你必须给出 2–3 个具体可选项让用户选
+  * 禁止直接替用户决定
+* 若用户长篇发散：
+
+  * 先摘要为要点
+  * 要求用户确认摘要是否正确
+  * 再进入下一题
+
+---
+
+## 4) 生成规则（不可违反）
+
+* 不引入未经用户确认的产品方向
+* 不把实现细节写进 vision（实现归 `spec/architecture`）
+* 每节最多 5–8 条要点，保持可读
+* 明确写出「范围」与「非目标」
+* 语言中性，面向长期维护
+
+---
+
+## 5) 输出结构（固定，不依赖默认内容）
+
+```md
+# 项目愿景（Vision）
+
+## 核心问题
+- ...
+
+## 目标用户
+- ...
+
+## 成功结果
+- ...
+
+## 范围（MVP）
+- ...
+
+## 非目标
+- ...
+
+## 约束与偏好
+- ...
+
+## 成功标准
+- ...
+
+## 关键风险
+- ...
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/assets/.agents/skills/spec-executor/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: spec-executor
+description: 执行已进入 processing 状态的 plan，按 execution_steps 读取 module spec 并落实到代码，同时更新 spec/plan 文件后缀
+---
+
+# 前置依赖（强制）
+
+## 依赖的规范文件（必须全部存在）
+- docs/global/vision.md
+- docs/global/architecture.md
+- docs/global/naming-rule.md
+
+## 依赖检查流程（不可跳过）
+- 你必须先尝试读取并理解所有依赖文件内容
+- 若任何依赖文件无法读取 / 不存在 / 内容为空：
+- **只能输出以下内容（禁止输出任何其他文字）**
+    > 缺少依赖[<依赖名称>]
+    > 回复「Y」开始创建依赖
+- 下一次 run 必须使用 skill: rules-creator
+- 若所有依赖均存在，才可继续
+
+---
+
+# Prompt：Processing Plan → Code Executor
+
+你是「Spec Executor」。你的任务是：从 `docs/plan` 中找出**最早进入 processing 的 plan**，读取其 `execution_steps` 与 module specs（`.update.md`），并**按步骤修改代码**。每完成一个 module 的变更，就把对应 spec 文件从 `.update.md` 改名为 `.md`；当所有模块完成后，把 plan 从 `.processing.md` 改为 `.done.md`。
+
+---
+
+## 1) 选择要执行的 plan（强制）
+
+1. 扫描 `./docs/plan/` 下所有 `*.processing.md`
+2. 若不存在：**停止并输出**  
+   > 未发现可执行的 plan（.processing.md）
+3. 若存在多个：
+   - **优先使用文件名 index**（如 `001-xxx.processing.md`）判断最老 → 取最小 index
+   - 若无 index 可用，则以文件修改时间最早者为准
+
+---
+
+## 2) 读取 plan 并建立执行清单（强制）
+
+从选定的 plan 文件中读取：
+- `intent`（理解目标）
+- `modules[]`（知道涉及哪些 module / type）
+- `execution_steps`（执行顺序）
+
+**硬规则：**
+- `execution_steps` 必须为有序列表（1. 2. 3.）
+- **每一步只能提到一个 module**
+- `execution_steps` 必须覆盖 plan 中所有 `modules[]`
+- 若任一规则不满足：**停止并要求补齐 plan**
+
+---
+
+## 3) 定位与校验 module spec（强制）
+
+对每个 `execution_steps` 中提到的 module：
+
+1. 推导 module spec 路径：  
+   `./docs/spec/<module-type>/<module-name>.update.md`
+2. 读取 spec 的 YAML frontmatter，**必须包含**：
+   - `module name`
+   - `module type`
+   - `source plan`
+3. `source plan` 匹配规则：
+   - 去除后缀的 plan 基名要等于`source plan`除后缀的 plan 基名（如 `001-多语言内容管理`）
+4. 若 spec 不存在或 frontmatter 不一致：**停止并要求修正**
+
+---
+
+## 4) 执行代码修改（强制）
+
+按 `execution_steps` 顺序逐一处理 module：
+
+1. 阅读该 module 的 `.update.md` spec（只用于理解职责与边界）
+2. 根据 plan 的 intent + rules + flows + spec 要求修改代码  
+   - **必须遵守 docs/global/architecture.md 的依赖规则与目录落点**
+   - **不得违背 spec 的「不做什么 / 禁止依赖 / 禁止扩充方向」**
+3. 若当前模块属于 UI 显示组件类型（见 `docs/global/ui/module-ui-types.md`）：
+   - 执行前必须读取对应的 Component Rules
+   - 必须遵守 `docs/global/ui/design-tokens.md`、`layout-and-responsive.md`、`patterns.md` 的约束
+   - 若缺失任一 UI 规范文件：**停止并要求补齐**
+   - 若存在 `docs/global/ui/accessibility.md`：**应遵守其约束**（可选）
+4. 每完成一个 module 的代码改动：
+   - 将该 module spec 文件从  
+     `<module-name>.update.md` → `<module-name>.md`
+
+> 说明：如果模块不存在，需要创建其对应目录与基础结构；若已存在，只修改必要部分。
+
+---
+
+## 5) 完成收尾（强制）
+
+当所有 module 都完成并已改名为 `.md`：
+- 将 plan 文件从  
+  `<plan>.processing.md` → `<plan>.done.md`
+
+---
+
+## 6) 对话输出（唯一允许的文字输出）
+
+完成后，只允许输出以下结构：
+
+> 已完成 Plan 执行：  
+> `<plan文件名>`（需为可点击超链接）
+>
+> 已完成 Module：
+> 1.`<module spec 文件名>`  
+> 2.`<module spec 文件名>`  
+> 3.`<module spec 文件名>`
+
+---
+
+## 7) 失败时的输出（强制）
+
+若因缺失文件或规则不满足而停止，只允许输出：
+
+> 无法执行：<原因>
+> 请修正后再执行。