@modus-ai/modus 0.1.4 → 0.1.5

package/templates/skills/modus-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: modus-plan
-description: Use this skill when executing /modus:plan command to generate structured planning documents (proposal, design, tasks) backed by up-to-date business Skills. Trigger on /modus:plan command or when user wants to plan a feature with full business context. Supports --quick flag to skip design.md.
+description: Use this skill when executing /modus:plan command to generate structured planning documents (proposal, design, tasks) backed by up-to-date business Skills. Trigger on /modus:plan command or when user wants to plan a feature with full business context. Supports --quick flag to skip design.md. Auto-routes to simple/medium/complex depth based on complexity assessment.
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
@@ -9,11 +9,19 @@ disable: false
 
 **触发条件：** 用户运行 `/modus:plan [需求描述]` 时使用此 Skill。
 
-支持快速模式：`/modus:plan --quick [描述]` 跳过 design.md，仅生成 proposal + tasks。
+支持快速模式：`/modus:plan --quick [描述]` 跳过 design.md 和 design-brief.md，仅生成 proposal + tasks。
 
 ## 职责
 
-功能规划入口。通过**三级渐进加载**获取业务上下文（前置更新），基于最新知识生成结构化的 proposal/design/tasks 文档，归档后将本次规划中的新知识回写到 Skill（后置更新），并将状态写入 `.modus-state.yaml` 支持断点续跑。
+功能规划入口。通过**三级渐进加载**获取业务上下文（前置更新），先评估需求复杂度自动分级（simple/medium/complex），再基于最新知识生成结构化的 proposal/design/tasks 文档（proposal 自动融入 Skill pitfall 生成已知风险章节），归档后将本次规划中的新知识回写到 Skill（后置更新），并将状态写入 `.modus-state.yaml` 支持断点续跑。
+
+### 复杂度分级与产出物对应
+
+| 级别 | 判定标准 | 产出物 | 自动建议 |
+|------|----------|--------|---------|
+| Simple | 单域、≤3 文件变更、无架构变化、bug fix 类 | proposal + tasks | 自动建议 `--quick` |
+| Medium | 1-2 个域、有新接口但无架构变化、≤5 文件 | proposal + design + tasks | 完整模式 |
+| Complex | 跨 3+ 域 / 新增数据表 / 引入新中间件 / 重构 | proposal + design + design-brief + tasks | 完整模式（提示考虑 /spec） |
 
 ---
 
@@ -57,6 +65,60 @@ disable: false
 确认？
 ```
 
+### Step 2.5：复杂度评估与自动分级
+
+域确认后，在澄清之前，快速评估需求复杂度并输出分级建议：
+
+**评估维度：**
+
+| 维度 | 简单 (1) | 中等 (2) | 复杂 (3) |
+|------|----------|----------|----------|
+| 涉及域数量 | 1 个 | 1-2 个 | 3+ 个 |
+| 预估文件变更 | 1-3 个 | 3-8 个 | 8+ 个 |
+| 是否新增数据表 | 否 | 否 | 是 |
+| 是否引入新中间件 | 否 | 否 | 是 |
+| 是否有接口契约变更 | 否 | 新增接口 | 修改/废弃接口 |
+| 是否涉及重构 | 否 | 局部 | 大范围 |
+
+**评分规则：** 各维度得分相加，总分 ≤ 7 为 simple，8-12 为 medium，≥ 13 为 complex。
+
+**输出分级建议：**
+
+```
+📊 需求复杂度评估
+
+级别:  {Simple / Medium / Complex}
+得分:  {N}/18
+理由:
+  ✓ 涉及 1 个域（order）
+  ✓ 预估 3-5 个文件变更
+  ✓ 无新数据表，无新中间件
+  ⚠ 有接口契约变更（影响复杂度）
+
+建议文档深度:
+  {Simple → 建议使用 --quick 模式（proposal + tasks）}
+  {Medium → 完整模式（proposal + design + tasks）}
+  {Complex → 完整模式 + design-brief，或考虑升级为 /modus:spec}
+```
+
+**复杂度为 Complex 时的特别提示：**
+
+```
+⚠️  此需求复杂度较高，建议考虑以下方案：
+  A. 继续使用 /modus:plan（完整模式，含 design-brief）
+  B. 升级为 /modus:spec（可获得 delta specs 和 GIVEN/WHEN/THEN 验收标准）
+  C. 拆分需求后分别 /modus:plan
+
+请选择处理方式 [A/b/c]:
+```
+
+若用户选择 B，退出当前 plan 流程，以相同 prompt 启动 `/modus:spec`。
+
+**快速模式自动建议：** 若判定为 Simple 且用户未传 `--quick`，询问：
+```
+需求较简单，是否使用快速模式（跳过 design.md，仅生成 proposal + tasks）？[y/N]
+```
+
 ### Step 3：澄清用户意图（AskUserQuestion）
 
 确认域后，在正式启动规划前，提出 1-3 个关键澄清问题：
@@ -133,7 +195,20 @@ shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{
 2. 扫描该域相关的最新代码文件（近期变更的文件）
 3. 对比 Skill 内容与代码现实，识别差异
 4. 更新 Skill 文件中过时的信息，更新 `last_referenced`、`usage_count` 和 `last_hash`
-5. 输出更新摘要：`✓ modus-biz-order Skill 已更新（新增: OrderStatus.PENDING_REVIEW | maturity: draft→verified）`
+
+**输出变更摘要 block（透明度关键）：**
+
+```
+✓ modus-biz-order Skill 已更新
+  新增内容:
+    [model]   OrderStatus.PENDING_REVIEW（待评审状态，2026-04 新增）
+    [process] 批量审批流程：提交 → 校验 → 执行 → 通知
+  修改内容:
+    [pitfall] 并发创建订单分布式锁 → 更新锁 key 格式为 order:create:{userId}
+  删除内容:
+    [model]   OrderStatus.LEGACY_CANCELLED（已废弃枚举值）
+  maturity: draft → verified（本次引用后满足晋升条件）
+```
 
 若有未初始化的域，调用模式 A 新建 Skill（`last_hash` 留空，`key_files` 由 AI 填写）。
 
@@ -147,10 +222,11 @@ shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{
 mode: plan
 name: {name}
 status: in-progress
+complexity: medium        # simple | medium | complex（来自 Step 2.5 评估）
+quick_mode: false         # --quick flag 或 simple 复杂度时用户选择跳过 design
 domains: [{domain1}, {domain2}]
-quick_mode: false
 completed: []
-pending: [proposal, design, design-brief, tasks]
+pending: [proposal, design, design-brief, tasks]  # quick_mode 时 pending 仅含 proposal + tasks
 created: {ISO8601时间戳}
 ```
 
@@ -185,10 +261,26 @@ design.md ────────────► design-brief.md ────
 ## 关键约束（来自项目宪法）
 - {constitution.hard_rules 中与本次相关的规则}
 
+## 已知风险 ⚠️
+<!-- 自动从相关业务 Skill 的 [pitfall] 标签中提取，并结合本次改动范围筛选 -->
+- [pitfall | 来源: modus-biz-order] {具体风险描述，如：并发创建订单时需加分布式锁}
+- [pitfall | 来源: modus-team-conventions] {具体风险描述，如：@Transactional 内部调用不生效}
+<!-- 若相关 Skill 中无 [pitfall] 记录，此章节留空或注明"暂无已知风险" -->
+
+## 影响分析
+涉及文件变更（预估）：
+- {文件路径} — {新增/修改/删除，一句话说明变更目的}
+
 ## 方案概述
 {技术路径的高层描述}
 ```
 
+**已知风险章节的生成规则：**
+1. 从 Step 4 已加载的业务 Skill 内容中，提取所有 `[pitfall]` 标签条目
+2. 结合本次改动范围（涉及的域、预估的文件变更），筛选与当前功能相关的 pitfall
+3. 每条 pitfall 注明来源 Skill（`来源: modus-biz-{domain}` 或 `来源: modus-team-conventions`）
+4. 若无相关 pitfall，写 `暂无已知风险（相关 Skill 中未记录 pitfall）`，而非省略章节
+
 **2. design.md** — 技术方案
 
 ```markdown
@@ -197,18 +289,35 @@ design.md ────────────► design-brief.md ────
 ## 技术方案
 {详细实现路径，引用具体的类/方法/接口}
 
-## 架构决策 [decision]
-### 决策: {决策点}
-选择方案: {方案}
-原因: {理由}
+## 架构决策记录（ADR）[decision]
+<!-- 每个有技术选型的决策点独立记录，后续可沉淀到 modus-tech-wiki -->
+
+### ADR-01: {决策点标题，如"选择异步 MQ 而非同步 RPC"}
+
+| 字段 | 内容 |
+|------|------|
+| 状态 | 已采纳 / 被否决 / 待评估 |
+| 背景 | {为什么需要做这个决策，2-3 句话} |
+| 选项 | A. {方案A} / B. {方案B} / C. {方案C} |
+| 决策 | 选择方案 {X} |
+| 原因 | {选择理由，包括技术/业务/成本考量} |
+| 放弃理由 | 方案 {Y}：{为什么不选，如：实时性要求高不适合 MQ} |
+| 影响 | {此决策对系统的长期影响，如：引入 MQ 后需维护消费者幂等性} |
+
+<!-- 若有多个决策点，继续添加 ADR-02, ADR-03... -->
 
 ## 数据流
 {文字或 mermaid 图}
 
 ## 涉及文件变更
-- {文件路径} — {新增/修改/删除}
+- {文件路径} — {新增/修改/删除，一句话说明变更目的}
 ```
 
+**ADR 使用规则：**
+- 每个有选型空间的技术决策都应记录一个 ADR
+- 若 Skill 中有 `[decision]` 标签记录了类似决策，在 ADR 背景中引用：`（参考 modus-biz-order 的历史决策：...）`
+- 后置 Skill 更新时，每个 ADR 条目将自动提取为 `[decision]` 写入 `modus-tech-wiki`
+
 **3. design-brief.md** — 设计方案（代码开发前的精确实现指南）
 
 调用 `modus-design-brief` Skill，传入：
@@ -267,17 +376,21 @@ design.md ────────────► design-brief.md ────
 
 归档完成后（或用户选择不归档但完成了规划），执行后置 Skill 更新（模式 C）：
 
-1. 从本次生成的 design.md 和 tasks.md 中提取新的技术决策和实现细节
-2. 带类型标签回写到对应业务 Skill：
-   - `[decision]` → 架构决策章节
-   - `[guideline]` → 推荐做法/禁止做法
-   - `[pitfall]` → 已知风险
-3. 更新 `modus/knowledge-catalog.md` 的 `last_referenced` 和 maturity
-4. 输出更新摘要：
+1. 从本次生成的 design.md 中提取所有 ADR 条目：
+   - 每个 ADR → `[decision]` 写入 `modus-tech-wiki`（跨项目决策）或对应业务 Skill（域特有决策）
+   - ADR 中的「影响」字段若包含风险点 → 同时写为 `[pitfall]`
+2. 从 proposal.md 的「已知风险」章节中提取任何**本次新发现的**风险（非来自现有 Skill 的已有记录）：
+   - 新发现的风险 → `[pitfall]` 追加到对应业务 Skill
+3. 从 tasks.md 中提取具体的编码模式或约束 → `[guideline]`
+4. 更新 `modus/knowledge-catalog.md` 的 `last_referenced` 和 maturity
+5. 输出更新摘要：
    ```
    📚 知识已回写到 Skill：
-   - [decision] order 域：新增批量审批走 MQ 异步的架构决策
+   - [decision] tech-wiki：批量审批走 MQ 异步（ADR-01）
+   - [decision] tech-wiki：Redis 分布式锁 key 格式规范（ADR-02）
    - [guideline] order 域：批量操作上限 50 条，防止内存溢出
+   - [pitfall] order 域：MQ 消费者需保证幂等性（来自 ADR-01 影响分析）
+   maturity 变化: modus-biz-order draft→verified
    ```
 
 ---

package/templates/skills/modus-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: modus-spec
-description: Use this skill when executing /modus:spec command for OpenSpec-style spec-driven development. Generates delta specs (ADDED/MODIFIED/REMOVED requirements with GIVEN/WHEN/THEN scenarios), design, and tasks. Trigger on /modus:spec command or when user wants behavior specifications before coding.
+description: Use this skill when executing /modus:spec command for OpenSpec-style spec-driven development. Generates delta specs (ADDED/MODIFIED/REMOVED requirements with GIVEN/WHEN/THEN scenarios), design, and tasks. Supports --lite flag to skip design-brief for low-risk changes. Trigger on /modus:spec command or when user wants behavior specifications before coding.
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
@@ -9,9 +9,18 @@ disable: false
 
 **触发条件：** 用户运行 `/modus:spec [需求描述]` 时使用此 Skill。
 
+支持轻量模式：`/modus:spec --lite [描述]` 跳过 design-brief，适用于低风险小变更。
+
 ## 职责
 
-规范驱动开发入口。在 `/modus:plan` 的基础上增加 OpenSpec 风格的行为规格（delta specs），明确「系统的 WHAT」而非「HOW」。通过**三级渐进加载**获取业务上下文，产出物包含 proposal、delta specs、design、tasks，归档后将 delta specs 合并到主规格库，并从中提取带类型标签的知识回写到 Skill。
+规范驱动开发入口。在 `/modus:plan` 的基础上增加 OpenSpec 风格的行为规格（delta specs），明确「系统的 WHAT」而非「HOW」。通过**三级渐进加载**获取业务上下文，产出物包含 proposal、delta specs、design、tasks，归档前可选执行实现验证（verify），归档时自动检测规格冲突，合并 delta specs 到主规格库，并从中提取带类型标签的知识回写到 Skill。
+
+### 规格级别
+
+| 模式 | 标志 | 产出物 | 适用场景 |
+|------|------|--------|---------|
+| Full（默认） | 无 | proposal + delta specs + design + design-brief + tasks | 接口契约变更、高风险、跨域需求 |
+| Lite | `--lite` | proposal + delta specs + tasks（无 design-brief） | 低风险内部逻辑变更、简单新增 |
 
 ---
 
@@ -137,6 +146,7 @@ shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{
 mode: spec
 name: {name}
 status: in-progress
+lite_mode: false        # --lite flag 时为 true，跳过 design-brief
 domains: [{domain1}]
 delta_stats:
   added: 0
@@ -144,8 +154,9 @@ delta_stats:
   removed: 0
 tasks_completed: "0/?"
 scenarios_covered: "0/?"
+verify_status: skipped  # skipped | passed | passed_with_warnings
 completed: []
-pending: [proposal, specs, design, design-brief, tasks]
+pending: [proposal, specs, design, design-brief, tasks]  # lite_mode 时 pending 不含 design-brief
 created: {ISO8601时间戳}
 ```
 
@@ -213,6 +224,8 @@ proposal.md
 
 **4. design-brief.md** — 设计方案（代码开发前的精确实现指南）
 
+**跳过条件：** `--lite` 模式时直接跳过此步骤，在 `.modus-state.yaml` 中标记 `lite_mode: true`。
+
 调用 `modus-design-brief` Skill，传入：
 - `mode: spec`
 - `output_path: modus/changes/{name}/design-brief.md`
@@ -241,17 +254,107 @@ proposal.md
 
 生成每份文档后更新 `.modus-state.yaml` 的 `completed` 列表和 `scenarios_covered`。
 
-### Step 6：询问归档 ⏸️ 【人工审批节点】
+### Step 5.5：可选实现验证（verify）
+
+文档生成后，询问用户是否执行实现验证（适用于代码已开发完成、准备归档前的场景）：
+
+```
+规范文档已生成。是否对当前代码实现执行验证？
+
+  Y — 执行验证（推荐：确保代码与规格一致）
+  N — 跳过验证，直接进入归档（文档阶段可跳过）
+```
+
+若用户选择执行验证，从三个维度检查：
+
+#### 维度一：完整性（Completeness）
+
+检查内容：
+- `tasks.md` 中的规格验证章节每一项是否已有对应测试或代码
+- delta spec 中每个 ADDED/MODIFIED Requirement 是否有对应实现
+- 每个 Scenario 是否有对应的测试用例（单元测试或接口测试）
+
+```bash
+# 扫描近期修改的测试文件
+git diff --name-only HEAD~3 | grep -E 'Test\.java|Spec\.java|test.*\.py'
+```
+
+输出格式：
+```
+完整性检查：
+✓ 12/12 tasks.md 任务已完成
+✓ 3/3 ADDED Requirements 有对应代码
+⚠ Scenario "边界条件 — 批量上限 50 条" 未找到对应测试
+```
+
+#### 维度二：正确性（Correctness）
+
+检查内容：
+- 代码中的主要逻辑是否与 Scenario 的 THEN 断言一致
+- 错误处理是否覆盖 Scenario 中的异常路径
+- constitution 的 `hard_rules` 是否在代码中得到体现
+
+#### 维度三：一致性（Coherence）
+
+检查内容：
+- design.md 中的架构决策是否反映在代码结构中
+- 命名约定是否与 design.md 一致
+- 若有 design-brief.md，其追踪矩阵中每个 Requirement 是否均已实现
+
+**验证输出摘要：**
+
+```
+📋 实现验证结果 — {name}
+─────────────────────────────────────────
+完整性  ✓  12/12 任务已完成 | 3/3 需求有实现 | ⚠ 1 个 Scenario 缺测试
+正确性  ✓  主要逻辑与规格一致 | ✓ 错误处理完整
+一致性  ✓  架构决策已反映 | ⚠ design.md 提到事件驱动但代码使用同步调用
+
+严重问题: 0 | 警告: 2
+建议：
+1. 为 "边界条件 — 批量上限 50 条" 添加单元测试
+2. 更新 design.md 说明改为同步调用的原因，或重构为事件驱动
+
+可以归档（有警告）[Y/n]
+```
+
+验证不阻断归档，但警告需用户显式确认后方可继续。
+
+### Step 6：规格冲突检测 + 询问归档 ⏸️ 【人工审批节点】
+
+**归档前冲突检测（自动执行）：**
+
+在执行归档前，检查主规格库中是否存在冲突条目：
+
+```bash
+# 检查主规格库是否存在同名 Requirement
+grep -l "### Requirement:" modus/specs/{domain}/spec.md 2>/dev/null
+```
+
+对 delta spec 中每个 MODIFIED/REMOVED Requirement，在主规格库 `modus/specs/{domain}/spec.md` 中查找同名条目：
+
+```
+冲突检测结果：
+✓ 主规格库存在 "单个审批接口" → MODIFIED 操作可正常执行
+✓ 主规格库存在 "Remember Me"  → REMOVED 操作可正常执行
+⚠ 主规格库不存在 "批量审批订单" 的 MODIFIED 目标 → 建议改为 ADDED
+  （若此需求是全新的，请将 delta spec 中 MODIFIED 改为 ADDED）
+```
+
+若检测到冲突，询问用户如何处理（修改 delta spec 或强制执行）。
 
 ```
 规范文档已生成：
   modus/changes/{name}/proposal.md
-  modus/changes/{name}/specs/{domain}/spec.md  ← delta specs（{N}个场景）
+  modus/changes/{name}/specs/{domain}/spec.md  ← delta specs（ADDED:{A} MODIFIED:{M} REMOVED:{R}，共{N}个场景）
   modus/changes/{name}/design.md
-  modus/changes/{name}/design-brief.md         ← 设计方案（{N}节 | 追踪矩阵 {N}行）
+  modus/changes/{name}/design-brief.md         ← 设计方案（{N}节 | 追踪矩阵 {N}行）[lite 模式时不生成]
   modus/changes/{name}/tasks.md
   modus/changes/{name}/.modus-state.yaml
 
+实现验证: {passed_with_warnings / passed / skipped}  [Step 5.5 结果]
+冲突检测: {通过 / N 项需确认}
+
 是否归档？归档后：
   1. delta specs 将合并到 modus/specs/{domain}/spec.md（主规格库）
   2. 变更文件夹移动到 modus/changes/archive/{YYYY-MM-DD}-{name}/