@modus-ai/modus 0.2.3 → 0.2.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 a single structured plan.md backed by up-to-date business Skills. Trigger on /modus:plan command or when user wants to plan a feature with full business context. Loads Skill domains first, falls back to platform rules + source scan, then asks exactly 3 targeted questions before generating the plan. Ends with a Build confirmation loop where user can iterate on plan.md before executing code generation.
+description: Use this skill when executing /modus:plan command to generate a single structured plan.md backed by up-to-date business Skills. Trigger on /modus:plan command or when user wants to plan a feature with full business context. Loads Skill domains first, falls back to platform rules + source scan, then asks 0-3 targeted questions (no padding — only ask when truly needed) before generating the plan. Ends with a Build confirmation loop where user can iterate on plan.md before executing code generation.
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
@@ -11,7 +11,7 @@ disable: false
 
 ## 职责
 
-功能规划入口。通过**两层知识检索**获取业务上下文，先评估需求复杂度自动分级（simple/medium/complex），再基于加载的知识向用户提出恰好 3 个精准澄清问题，最终生成单一 `plan.md` 规划文档。文档生成后进入 Build 确认循环，用户可反复修改直至满意后触发代码执行，并将本次规划中的新知识回写到 Skill（后置更新）。
+功能规划入口。通过**两层知识检索**获取业务上下文，先评估需求复杂度自动分级（simple/medium/complex），再基于加载的知识向用户提出 0–3 个精准澄清问题（按需提问，禁止凑数），最终生成单一 `plan.md` 规划文档。文档生成后进入 Build 确认循环，用户可反复修改直至满意后触发代码执行，并将本次规划中的新知识回写到 Skill（后置更新）。
 
 ---
 
@@ -67,6 +67,15 @@ disable: false
 
 ### Step 3：复杂度评估与自动分级
 
+**AUTO_MODE 快速检测（Step 3 执行前）：**
+
+若 prompt 末尾包含 `[AUTO_MODE: questions_confirmed]` 标记（由 `/modus:auto` 自动注入），则：
+- 跳过 Step 6 的精准澄清问题（已在 auto 流程中确认，无需重复提问）
+- 直接使用标记后附带的「已确认的关键信息」作为澄清答案
+- 在输出中注明：`[已从 /modus:auto 继承确认信息，跳过澄清阶段]`
+
+若未包含此标记，正常执行以下评估流程：
+
 域确认后，快速评估需求复杂度并输出分级建议：
 
 **评估维度：**
@@ -125,13 +134,18 @@ disable: false
 
 #### 4-2：计算当前 key_files 的 hash
 
-使用 Bash 对 `key_files` 列出的文件内容做 SHA-1 摘要：
+使用 Bash 对 `key_files` 列出的文件内容做 SHA-1 摘要（**必须使用 modus-init 区块 B 规定的标准算法**）：
 
 ```bash
-# 对每个文件计算 sha1，排序后再做一次 sha1（顺序无关）
-shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
+# 标准全局 hash 计算命令（与 modus-init 生成时的算法完全一致）
+# 对每个文件单独计算 SHA-1，按文件路径排序后拼接，再整体 hash
+for f in $(echo "{key_files}" | tr ' ' '\n' | sort); do
+  echo "$(shasum -a 1 "$f" | awk '{print $1}'):$f"
+done | shasum -a 1 | awk '{print $1}'
 ```
 
+> 注意：禁止使用「内容拼接整体 hash」或「仅 hash 值排序 hash」的替代算法，否则与 init 写入的 last_hash 不匹配，导致每次都误判为 stale。
+
 - 若某个 `key_files` 中的文件不存在（可能已被重命名/删除），视为「已变化」，强制更新
 - 若 `key_files` 为空或缺失，视为「已变化」，强制更新
 
@@ -170,15 +184,28 @@ shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{
   maturity: draft → verified（本次引用后满足晋升条件）
 ```
 
-若有未初始化的域，调用模式 A 新建 Skill（`last_hash` 留空，`key_files` 由 AI 填写）。
+若有未初始化的域，调用模式 A 新建 Skill（`last_hash` 留空，`key_files` 由 AI 填写）；新建完成后将新域纳入本次可用 Skill 集合，继续执行。
+
+**Step 4 执行完后的分支判断：**
 
-**若所有域均已初始化且 Skill 加载成功，直接进入 Step 6，跳过 Step 5。**
+```
+情形 A：所有域均已初始化（含本轮新建）且 Skill 全部加载成功
+  → 直接进入 Step 6，跳过 Step 5
+
+情形 B：knowledge-catalog.md 不存在
+  → 进入 Step 5（平台知识兜底扫描）
+
+情形 C：部分域已初始化、部分域未初始化（混合状态）
+  → 对未初始化的域调用模式 A 新建后，加入到当前 Skill 集合
+  → 新建失败（如目录为空，无代码可扫描）时，对该域仅输出警告，继续处理已有域
+  → 完成处理后进入 Step 6（不触发 Step 5，已有 catalog 作为索引）
+```
 
 ---
 
 ### Step 5：平台知识兜底扫描（仅在 Step 4 无命中时执行）
 
-当 `knowledge-catalog.md` 不存在，或当前需求涉及的域全部未初始化时，切换到平台知识扫描模式：
+当 `knowledge-catalog.md` **不存在**时，切换到平台知识扫描模式作为兜底。注意：若 catalog 存在但部分域未初始化，属于情形 C，由 Step 4 内处理，不触发 Step 5：
 
 **按已启用平台依次扫描规则文件：**
 
@@ -203,26 +230,35 @@ shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{
 
 ---
 
-### Step 6：精准 3 问（AskUserQuestion）
+### Step 6：精准澄清问（AskUserQuestion）
 
-基于 Step 4 或 Step 5 已加载的知识内容，向用户提出**恰好 3 个**澄清问题。
+基于 Step 4 或 Step 5 已加载的知识内容，向用户提出**必要的**澄清问题。
 
-**生成规则（按优先级排序，必须输出恰好 3 个）：**
+**核心原则：只问真正有歧义或有高风险的点。需求足够清晰时可以只问 1 个（甚至 0 个），不要为了凑数制造问题。上限 3 个，超过 3 个未澄清点说明需求本身需要重新定义。**
 
-1. **P1 — Skill pitfall 关联问题**（最高优先级）  
-   若加载内容中有与当前需求相关的 `[pitfall]`，必问。  
+**必须提问的条件（满足任一即问）：**
+
+1. **P1 — Skill pitfall 关联问题**（命中即必问，不可省略）  
+   若加载内容中有与当前需求相关的 `[pitfall]`，必须确认用户是否已知晓并有对策。  
    示例：`Skill 中记录了「并发创建订单需加分布式锁」的坑，本次改动是否涉及并发写入场景？`  
-   若有多个相关 pitfall，选取与本次需求匹配度最高的 1 个。
+   若有多个相关 pitfall，选取与本次需求匹配度最高的 1 个提问。
 
-2. **P2 — 范围/边界问题**  
-   影响规划深度的不确定点（跨域边界、兼容性要求、数据量级）。  
-   示例：`这次改动是否需要向后兼容旧的导出格式，还是可以直接替换？`
+2. **P2 — 影响规划深度的不确定点**（有真实歧义才问）  
+   存在跨域边界不明确、兼容性要求未说明、数据量级未知等会影响技术选型的不确定点。  
+   示例：`这次改动是否需要向后兼容旧的导出格式？`  
+   **若需求描述已足够清晰（单域、单功能、无歧义词），跳过此条。**
 
-3. **P3 — 优先级/约束问题**  
-   时间窗口、技术选型偏好、外部依赖。  
-   示例：`功能是否有明确的上线时间节点？这会影响 Sprint 拆分方式。`
+3. **P3 — 影响 Sprint 拆分的外部约束**（有明确上线压力才问）  
+   功能有明确时间节点、或涉及外部系统联调依赖时才问。  
+   示例：`功能是否有明确的上线时间节点？`  
+   **若用户未提及时间约束且复杂度为 simple，跳过此条。**
 
-**若 pitfall 不存在**，P1 改为「核心目标澄清」：本次改动的最高优先级目标是什么？
+**若上述三条均无命中 → 直接跳过提问，输出：**
+```
+需求清晰，无需额外确认。开始生成 plan.md。
+```
+
+> **设计理由（Karpathy Think Before Coding）：** "恰好 3 个问题"是一种伪精确——它让 Agent 在只有 1 个真实歧义时制造 2 个无意义问题，或在需求清晰时也强制打断用户。真正的 Think Before Coding 是：发现真实的歧义才问，没有歧义就直接开工。
 
 等待用户回答后，输出意图确认摘要：
 
@@ -321,15 +357,35 @@ plan.md 生成后，展示结果并进入确认循环：
 
 **循环逻辑：**
 - 用户提出修改意见 → 更新 `plan.md` → 重新输出上述确认提示（循环，无次数限制）
-- 用户回复「Build」/「开始」/「执行」→ 退出循环，以 `plan.md` 中的 Todos 为输入，启动 `/modus:vibe` 执行代码生成
+- 用户回复「Build」/「开始」/「执行」→ 退出循环，按下方「Build 触发后」的规定启动 `/modus:vibe`
 - 用户回复「归档」/「稍后」→ 走归档流程，不启动代码生成
 
 **Build 触发后：**
-```
-🚀 开始执行 plan.md 中的 Todos，启动 /modus:vibe...
-   读取: modus/plans/{name}/plan.md
-   执行范围: {Todos 列表}
-```
+
+以下是 modus-plan → modus-vibe 的**标准上下文传递协议**：
+
+1. 输出 Build 启动提示（让用户感知上下文已传递）：
+   ```
+   🚀 开始执行 plan.md 中的 Todos，启动 /modus:vibe...
+      规划文件: modus/plans/{name}/plan.md
+      执行范围: {Todos 列表}
+      传递标记: [FROM_PLAN: modus/plans/{name}/plan.md]
+   ```
+
+2. 以如下格式构造 vibe 的输入 prompt（在 **当前上下文中**直接继续执行，不需要用户重新输入命令）：
+   ```
+   按照 [FROM_PLAN: modus/plans/{name}/plan.md] 中的 Todos 逐项实现：
+
+   {plan.md 中「实现 Todos」章节的完整内容}
+
+   已加载的业务上下文：{Step 4 已加载的 Skill 域列表}
+   项目硬性约束：{constitution.hard_rules}
+   ```
+
+3. modus-vibe Step 0 检测到 `[FROM_PLAN:...]` 标记时：
+   - 自动读取指定 plan.md 文件作为任务上下文（跳过用户 prompt 解析阶段）
+   - 将 plan.md 的「已知风险」章节注入 Step 6 Design Brief 的「禁止事项」
+   - 将 plan.md 的「关键约束」章节作为 constitution 补充（低于 constitution.hard_rules 优先级）
 
 **归档流程（用户选择归档时）：**
 1. 将目录移动到 `modus/plans/archive/{YYYY-MM-DD}-{name}/`
@@ -338,24 +394,34 @@ plan.md 生成后，展示结果并进入确认循环：
 
 ---
 
-### Step 9：后置 Skill 更新（知识回写）
+### Step 9：后置 Skill 更新（知识回写，用户确认后执行）
 
-无论用户选择 Build 还是归档，规划阶段完成后即执行后置知识回写（模式 C）：
+规划阶段完成后，先扫描 `plan.md` 中可能值得沉淀的新知识，向用户展示并**请求确认**后再写回：
 
-1. 从 `plan.md` 的「方案选项对比」中提取技术决策：
-   - 每个有选型依据的决策 → `[decision]` 写入 `modus-tech-wiki`（跨项目）或对应业务 Skill（域特有）
-2. 从「已知风险」章节中提取**本次新发现的**风险（非来自现有 Skill 的已有记录）：
-   - 新发现的风险 → `[pitfall]` 追加到对应业务 Skill
-3. 从「实现 Todos」中提取具体的编码模式或约束 → `[guideline]`
-4. 更新 `modus/knowledge-catalog.md` 的 `last_referenced` 和 maturity
-5. 输出更新摘要：
-   ```
-   📚 知识已回写到 Skill：
-   - [decision] tech-wiki：批量审批走 MQ 异步
-   - [guideline] order 域：批量操作上限 50 条，防止内存溢出
-   - [pitfall] order 域：MQ 消费者需保证幂等性
-   maturity 变化: modus-biz-order draft→verified
-   ```
+**扫描内容：**
+1. 从「方案选项对比」提取技术决策 → 候选 `[decision]`
+2. 从「已知风险」提取**本次新发现的**风险（非来自现有 Skill 的已有记录）→ 候选 `[pitfall]`
+3. 从「实现 Todos」提取具体编码约束 → 候选 `[guideline]`
+
+**若发现可沉淀内容，向用户展示并确认：**
+```
+📚 发现 {N} 条可沉淀到 Skill 的新知识，是否写入？[Y/n]
+  · [decision] tech-wiki：批量审批走 MQ 异步（来自方案对比）
+  · [pitfall] order 域：MQ 消费者需保证幂等性（本次新发现）
+  · [guideline] order 域：批量操作上限 50 条（来自 Todos 约束）
+跳过不影响本次规划，可在下次 /modus:init 时统一归档。
+```
+
+**用户确认后**执行写回（模式 C），输出摘要。  
+**用户跳过**则仅更新 `knowledge-catalog.md` 的 `last_referenced`（不修改 Skill 内容）。
+
+**若无可沉淀内容 → 静默跳过，仅更新 `last_referenced`。**
+
+**`usage_count` 更新时机（plan 模式）：**
+
+用户在 Build 确认循环中回复「Build/开始/执行」后（即 Step 8 Build 触发时），对本次 plan 涉及的每个业务域执行 `usage_count += 1`，并同步更新对应 Skill 的 frontmatter。此操作在 Step 8 Build 触发内执行，不依赖后续 vibe session 的完成。
+
+> **设计理由（Karpathy Surgical Changes）：** 用户请求的是"生成规划文档"，不是"更新 Skill 文件"。自动写回会在用户不知情的情况下修改多个知识文件，违反"Touch only what you must"。用户确认机制既保留了知识闭环能力，又把文件修改的控制权还给用户。
 
 ---