@modus-ai/modus 0.2.3 → 0.2.5

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

@@ -3,6 +3,22 @@ name: modus-vibe
 description: Use this skill when executing /modus:vibe command for context-aware vibe coding. Intelligently loads relevant business Skills, auto-syncs stale knowledge, and applies rule-driven AskUserQuestion before coding so AI works as a knowledgeable project member. Trigger on /modus:vibe command or when user wants to code with business context.
 allowed-tools: Read, Write, Glob, Bash
 disable: false
+supported_platforms:
+  claude:
+    status: full
+    notes: "全功能支持。三级渐进加载、防腐触发、Design Brief、知识写回均完整执行。"
+  codebuddy:
+    status: full
+    notes: "全功能支持，与 Claude 能力对等。"
+  cursor:
+    status: partial
+    notes: "核心 vibe 流程可用（Steps 1-7），但 Step 8 知识写回需手动触发（无 post-commit hook）。Cursor Agent 模式下无 Bash 工具，Step 7 中需要执行构建验证时改用 Read 检查文件。"
+    limitations:
+      - "Step 8 知识写回：Cursor 无 post-commit hook，需手动运行 /modus:commit 触发"
+      - "无 Bash：构建验证改为文件内容检查"
+  copilot:
+    status: minimal
+    notes: "vibe 流程退化为无上下文编码模式，知识体系不可用（无分域 Skill）。"
 ---
 
 # modus-vibe（智能氛围编程）
@@ -23,9 +39,9 @@ disable: false
 
 ## 执行流程
 
-### Step 0：读取项目宪法（硬性约束）
+### Step 0：读取项目宪法 + 全局行为守卫
 
-读取 `modus/config.yaml`（若存在），提取 `constitution` 字段：
+**读取 `modus/config.yaml`（若存在）：**
 
 ```yaml
 constitution:
@@ -36,15 +52,27 @@ constitution:
 
 将 `hard_rules` 作为**最高优先级约束**，在整个编码过程中强制遵守，不因业务需要而妥协。
 
-若文件不存在或 `constitution` 为空，跳过此步。
+**读取 `modus/behavior-guard.md`（若存在）：**
+
+加载全局行为约束（Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution），作为本次 session 中所有编码行为的基准。优先级低于 `constitution.hard_rules`，高于 Skill 建议。
+
+若两个文件均不存在，跳过此步，使用默认行为。
+
+**检测 `[FROM_PLAN:]` 标记（modus-plan Build 触发时注入）：**
+
+若用户 prompt 或当前上下文中包含 `[FROM_PLAN: {plan_path}]` 标记，执行以下操作：
+1. 读取 `{plan_path}` 文件，将其「实现 Todos」章节作为本次 vibe session 的**任务清单**
+2. 将 plan.md「已知风险」章节注入 Step 6 Design Brief 的「禁止事项/注意事项」
+3. 将 plan.md「关键约束」章节追加到 constitution（优先级低于 `constitution.hard_rules`）
+4. 跳过 Step 4 的用户意图确认 AskQuestion（任务已在 plan.md 中明确），直接进入 Step 2 域匹配
 
 ---
 
-### Step 1：Level 1 加载——读知识目录（~200 tokens）
+### Step 1：Level 1 加载——读知识目录（token 预算：~200）
 
 读取 `modus/knowledge-catalog.md`（全景目录索引）：
 - 了解当前项目有哪些可用的 Skill
-- 识别各 Skill 的 maturity 状态、最近引用时间
+- 识别各 Skill 的 status 状态、最近引用时间
 - 为 Step 2 的智能分析做准备
 
 **如果 `knowledge-catalog.md` 不存在：**
@@ -59,12 +87,12 @@ A. 现在运行快速初始化（约 2-5 分钟）？
 B. 继续使用降级模式（无业务上下文，结果质量可能降低）？
 ```
 
-- 选 A → 执行 `/modus:init` 流程，完成后继续
-- 选 B → 跳过 Step 2-3，直接进入 Step 4（歧义检测仍然执行）
+- 选 A → 执行 `/modus:init` 流程；init 完成后，**从 Step 1 重新开始**（读取新生成的 knowledge-catalog.md）
+- 选 B → 跳过 Step 2-3，直接进入 Step 4（**降级模式**：歧义检测仅执行 R2/R4，其余规则依赖 Step 2 的复杂度分析，在无 catalog 的情况下不可用）
 
 ---
 
-### Step 2：智能分析引擎
+### Step 2：智能分析引擎（token 预算：~0，基于 catalog 内容推理，不读新文件）
 
 基于用户 prompt 和 knowledge-catalog 内容，推导以下三个维度，**不需要读取完整 SKILL.md**：
 
@@ -80,17 +108,20 @@ B. 继续使用降级模式（无业务上下文，结果质量可能降低）
 ```
 
 **输出规则：**
-- 置信度 ≥ 85% 的**单个域**：自动选中，无需用户确认。在 Step 3 输出前标注 `[自动匹配: {domain} 域]`
-- 多个域或最高置信度 < 85%：展示候选列表，等待用户确认（可直接回车接受建议）
+- 置信度 ≥ 85% 的**单个域**：自动选中并**输出一行可见日志**（不需要等待用户确认，继续下一步）：
+  ```
+  [已匹配 order 域 · 置信度 92%]
+  ```
+  用户若看到匹配错误，在下一条输入中纠正即可，Agent 重新匹配。
+- 多个域，或最高置信度 < 85%：展示候选列表，等待用户确认（可直接回车接受建议）：
+  ```
+  根据你的需求，以下域可能相关：
 
-```
-根据你的需求，我匹配到以下业务域：
-
-✓ order（订单域）— 订单创建、状态流转       [verified] 置信度 92% → 自动加载
-? payment（支付域）— 支付发起、回调          [proven]  置信度 60% → 是否也需要？
+  ✓ order（订单域）— 订单创建、状态流转       [verified] 置信度 72%
+  ? payment（支付域）— 支付发起、回调          [proven]  置信度 60%
 
-直接回车确认 order 域，或告诉我调整。
-```
+  直接回车确认 order 域，或告诉我调整。
+  ```
 
 #### 2B：任务复杂度评估
 
@@ -113,31 +144,59 @@ ambiguity_rules_hit: [R1, R3, ...]  ← 命中的规则 ID，见 Step 4
 
 ---
 
-### Step 3：条件性 Skill 前置同步（轻感知）
+### Step 3：条件性 Skill 前置同步（防腐机制触发）（token 预算：0 正常 / ~3,000 触发更新时）
+
+对 Step 2 确认的每个业务域，按以下步骤轻量检查是否需要更新，不做额外的 hash 计算：
 
-对 Step 2 确认的每个业务域，执行以下检查：
+**检查来源说明（各条件读取不同来源）：**
+- 条件 1/2：从 `modus/knowledge-catalog.md` 读取 `status` 和 `last_referenced`（catalog 轻量字段，~200 tokens 内）
+- 条件 3：从 `.codebuddy/skills/modus-biz-{domain}/SKILL.md` **仅读 frontmatter**（YAML 头部，通常 < 30 行）读取 `stale_cascade` 字段
 
 #### 触发更新的条件（满足任一即触发）
 
-- `maturity = stale`（已被 skill-creator 标记为过期）
-- catalog 中 `last_referenced` 超过 90 天
-- 调用 `modus-skill-creator` 模式 B 的 hash 检查发现 key_files 有变化
+- `status = stale`（已被防腐机制降级，禁止直接引用）
+- catalog 中 `last_referenced` 超过 `stale_after_days`（Skill frontmatter 中配置，默认 90 天）
+- **`stale_cascade = true`**（上游依赖域发生变更，本域知识需要验证——见依赖图传播规则）
+
+**以上三条是 vibe 的触发依据。hash 检查是模式 B 内部的执行逻辑，不在此处重复计算。**
+
+#### 依赖链传播规则（stale_cascade）
+
+当匹配域的 Skill frontmatter 中 `stale_cascade: true` 时，输出差异化提示：
+
+```
+⚠️ [payment 域知识需验证] 上游 order 域已更新，payment 域的跨域调用规范可能受影响。
+   选项：
+   A. 立即验证（~2 min）— 执行 /modus:refresh payment，确认后继续
+   B. 谨慎继续 — 加载旧知识，编码时对跨域接口调用保持警惕
+   C. 忽略 — 本次任务不涉及跨域调用，直接继续
+```
+
+- 选 A → 触发 modus-skill-creator 模式 B 验证 + 重置 stale_cascade
+- 选 B → 继续加载，在 Design Brief（Step 6）中自动标注 `⚠️ 跨域接口未验证`
+- 选 C → 继续，不标注（用户明确声明不涉及）
 
 #### 执行方式
 
 ```
-触发更新 → 静默调用 modus-skill-creator 模式 B（增量更新）
-         → 更新完成后输出单行状态：
-           [已同步 {domain} 域知识]
+触发更新（status=stale 或 last_referenced 超期）
+         → 静默调用 modus-skill-creator 模式 B（模式 B 内部自行做 hash 快速比对）
+         → 模式 B hash 一致：仅更新 last_referenced，不做全量扫描
+         → 模式 B hash 不一致：执行增量更新
+         → 完成后输出单行状态：[已同步 {domain} 域知识]
 
-无需更新 → 直接进入 Step 4，不输出任何提示
+触发联动验证（stale_cascade=true）
+         → 展示上方三选项，等待用户选择
+         → 选 A 时调用 modus-skill-creator 模式 B 并重置 stale_cascade: false
+
+不触发 → 直接进入 Step 4，将 last_referenced 更新为今日并写回 SKILL.md frontmatter（不触发 hash 重算），不输出任何提示
 ```
 
-**注意：** 整个同步过程对用户完全透明，无需确认，不中断流程。若同步耗时较长（超过 3 秒），追加进度提示 `[同步中...]`。
+**说明：** 若三个条件均未命中（status 正常 + 最近用过 + 无上游变更），说明防腐机制认为 Skill 仍然有效，直接加载使用即可。频繁的 vibe session 不会每次都触发 hash 计算，只有防腐机制检测到异常时才召唤模式 B。
 
 ---
 
-### Step 4：规则驱动 AskUserQuestion
+### Step 4：规则驱动 AskUserQuestion（token 预算：~0，基于 Step 2 分析结果）
 
 #### 歧义规则清单
 
@@ -181,18 +240,18 @@ ambiguity_rules_hit: [R1, R3, ...]  ← 命中的规则 ID，见 Step 4
 
 ---
 
-### Step 5：Level 2 加载——读匹配 Skill（~3000 tokens/个）
+### Step 5：Level 2 加载——读匹配 Skill（token 预算：~3,000/个，仅加载匹配域）
 
 读取用户确认的业务域对应的完整 SKILL.md 文件，将其内容作为背景知识。
 
 **注意事项：**
 - 只加载确认相关的域，不相关的域 Skill **不读取**（节省 token）
-- 若 Skill 的 `maturity` 为 `draft`，提示：「该 Skill 较新，若与代码有出入，以代码为准」
+- 若 Skill 的 `status` 为 `draft`，提示：「该 Skill 较新，若与代码有出入，以代码为准」
 - 在 Skill 中重点关注 `[pitfall]`、`[model]`、`[guideline]` 条目，以及 `关键文件索引`
 
 ---
 
-### Step 6：自适应内联设计方案（Design Brief CoT）
+### Step 6：自适应内联设计方案（Design Brief CoT）（token 预算：Simple ~200 / Medium/Complex ~1,000）
 
 **触发：** 每次编码任务前强制执行，不可跳过。  
 **产出：** 内联于当前 LLM 上下文，**不写入任何文件**。
@@ -257,7 +316,21 @@ API:     {Facade/Controller 类/方法}
 
 ---
 
-### Step 7：执行编码任务（Level 3 按需加载）
+### Step 7：执行编码任务（Level 3 按需加载）（token 预算：~500–2,000/文件，仅在需要时读取）
+
+**编码前先声明目标与完成标准（必须，不可跳过）：**
+
+```
+任务目标：{一句话，说明本次编码要实现什么}
+完成标准：
+  · 功能验证：{可运行的验证命令或手动验证步骤，如 mvn test -Dtest=OrderServiceTest}
+  · 影响范围：{仅修改以下文件/类，不涉及其他}
+  · 未在范围内的改动，即使发现问题也只标注不修改
+```
+
+> **设计理由（Karpathy Goal-Driven Execution）：** "Give it success criteria and watch it go." 在开工前声明可验证的完成标准，而不是靠感觉判断"完成了"。用户也能据此快速确认 Agent 理解了意图。
+
+---
 
 基于 Step 6 内联设计方案和澄清后的意图，执行用户的编码请求：
 
@@ -267,6 +340,7 @@ API:     {Facade/Controller 类/方法}
 - **Level 3 加载：** 需要具体代码实现时，按需读取 Skill 中 `关键文件索引` 指向的实际代码文件（而非预先全量读取）
 - 对不确定的业务规则，优先参考 Skill 中的规则描述
 - 如发现 Skill 中记录有误或过时，记录到内部缓冲区，在 Step 8 处理
+- **每个改动的文件都必须能追溯到上方「完成标准」中的影响范围；无法追溯的改动，暂停并问用户**
 
 ---
 
@@ -283,18 +357,45 @@ API:     {Facade/Controller 类/方法}
 
 #### 执行方式
 
+**不在 session 结束时直接写入 Skill 文件，改为缓冲到待沉淀队列：**
+
 ```
-有新知识 → 静默调用 modus-skill-creator 模式 C（知识提取写入）
-          → 写入完成后输出单行提示：
-            [已更新 {domain} 域知识: 新增 [pitfall] {摘要} / 更正 [model] {字段名}]
+有新知识 → 追加到 modus/sessions/pending-knowledge.yaml（append-only）：
+            - domain: {domain}
+              type: pitfall | guideline | model | decision
+              content: {知识内容}
+              evidence: {代码文件路径}
+              session: {session-id}
+              timestamp: {ISO8601}
+          → 输出单行提示：
+            [缓冲 {N} 条新知识 → 将在 git commit 时沉淀到 Skill]
+
+无新知识 → 静默跳过
+```
+
+**写入 Skill 的触发时机：`/modus:commit` 命令（或 git post-commit hook）**
 
-无新知识 → 静默跳过，不输出任何提示
+```bash
+# 用户运行 /modus:commit 替代 git commit，自动执行：
+# 1. 读取 pending-knowledge.yaml 中未沉淀的条目
+# 2. 调用 modus-skill-creator 模式 C 批量写入 Skill
+# 3. 清空已沉淀条目，保留未沉淀的（如 Skill 不存在的域）
+# 4. 执行 git commit
 ```
 
-**写回原则：**
-- 只写入有明确代码证据的知识，不写推测性内容
-- 每次写回最多 3 条新条目，避免批量污染
-- 更正已有条目时，保留原条目并追加修订记录（不覆盖历史）
+**设计理由：**
+- 每次 vibe session 都写回成本高、噪声多（未完成/探索性的 session 不该污染 Skill）
+- git commit 是天然的"知识验证点"——能 commit 的代码是被认可的，对应的知识才值得沉淀
+- `pending-knowledge.yaml` 跨 session 持久化，不会因为 session 结束而丢失
+
+**写回原则（不变）：**
+- 只写有明确代码证据的知识，不写推测性内容
+- 每次写回最多 5 条新条目（跨 session 累积的可以更多）
+- 更正已有条目时，保留原条目并追加修订记录
+
+**`usage_count` 更新时机（vibe 模式）：**
+
+`/modus:commit` 执行成功（git commit exit code = 0）且知识已写入 Skill 后，对本次 vibe session 涉及的每个业务域执行 `usage_count += 1`。由 `/modus:commit` 命令负责执行此更新，不在 vibe session 内部执行。
 
 ---
 
@@ -319,13 +420,13 @@ API:     {Facade/Controller 类/方法}
 
 ## 氛围编程原则
 
-- **智能优先，减少打断**：域匹配明确时自动确认，无需强制等用户输入；任务清晰时跳过提问
+- **智能优先，减少打断**：单域高置信度（≥85%）自动匹配并输出一行日志，无需等待确认；任务清晰时跳过提问直接开工
 - **先设计再编码**：Step 6 内联设计方案是编码的前置必要步骤，不可省略
-- **知识闭环**：每次 vibe 编码都是一次知识更新机会，通过 Step 3 前置同步 + Step 8 后置写回，知识库随项目演进自动积累
+- **知识缓冲，commit 时沉淀**：session 中发现的新知识缓冲到 pending-knowledge.yaml；git commit 时统一沉淀到 Skill，避免噪声污染
 - **有据可依**：引用的实体、字段、接口名必须来自 Skill 或已有代码
 - **宪法优先**：constitution.hard_rules 是不可违反的底线，优先于一切
 - **按需加载**：不预先读取所有 Skill，降低 token 消耗
-- **主动补全**：发现明显缺失（如缺少参数校验、日志）时主动补充
+- **主动补全，不触碰无关文件**：对明显缺失（如必要的参数校验、事务注解）主动补充到当前任务文件中；但不主动修改与当前任务无关的其他文件（发现问题→标注→告知用户）
 
 ---
 
@@ -335,6 +436,8 @@ API:     {Facade/Controller 类/方法}
 
 1. 跳过 Step 2-3（无 catalog 可分析）
 2. Step 4 仅执行 R2（模糊词检测）和 R4（缺少决策参数检测）
-3. Step 6 固定使用 Medium 模式（无法判断复杂度）
+3. Step 6 固定使用 **Simple 模式**（无法判断复杂度，且无 business_skills 可传入）
+   - 输出 Simple 版 3 节 Design Brief（不调用 modus-design-brief Skill，因为无 business_skills 参数）
+   - 在 Design Brief 头部标注：`[降级模式：无业务上下文，禁止事项和实现蓝图仅为通用模板，以代码现状为准]`
 4. Step 8 跳过写回（无 Skill 文件可写入）
 5. 在回复开头标注：`[降级模式：无业务上下文，建议先运行 /modus:init]`