@modus-ai/modus 0.2.5 → 0.2.7

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

@@ -1,24 +1,14 @@
 ---
 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.
+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 clarification before coding so AI works as a knowledgeable project member.
+  Trigger on: /modus:vibe, vibe coding, 开始编码, 帮我实现, 帮我开发, 写代码,
+  修复这个, 添加功能, 改一下代码, 实现需求, context-aware coding with business knowledge.
+  Supports --codex flag for non-interactive batch mode on Codex platform.
 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（智能氛围编程）
@@ -29,19 +19,46 @@ supported_platforms:
 
 ## 职责
 
-氛围编程入口。在编码前通过**三级渐进加载**获取相关业务上下文，让 AI 以「懂业务的资深开发者」身份工作。相比传统 vibe 模式，增加了三大智能机制：
+氛围编程入口。在编码前通过**三级渐进加载**获取相关业务上下文，让 AI 以「懂业务的资深开发者」身份工作。包含四大智能机制：
 
 1. **智能分析引擎**：自动判断涉及哪些域（置信度 ≥ 85% 时无需用户确认）、任务复杂度（Simple/Medium/Complex）、歧义风险
 2. **Skill 前置同步**：加载前静默检查知识是否过时，按需更新后再加载，用户仅看到一行状态提示
 3. **Skill 后置写回**：编码结束后自动将新发现的知识写入 Skill 文件，形成知识积累闭环
+4. **会话连续性感知**：自动识别是否延续上次会话，相同域无需重复加载（借鉴 Cursor Vibe Coding）
+
+> **业界参考**：本模式核心理念源自 [Cursor Vibe Coding](https://cursor.sh)（Andrej Karpathy 提出），强调零打断流动（Zero-Interrupt Flow）、文件优先感知（File-First Context）、增量迭代（Incremental Iteration）。相比原始 vibe coding，本 Skill 在其基础上增加了企业级业务上下文注入和知识闭环机制。
 
 ---
 
 ## 执行流程
 
-### Step 0：读取项目宪法 + 全局行为守卫
+### 参数解析与 --help 拦截（优先执行，Step 0 之前）
+
+**首先**检测用户输入中的参数标志，设置后续步骤的行为开关：
 
-**读取 `modus/config.yaml`（若存在）：**
+```
+--help       → 直接跳到文末「命令参考」章节，输出帮助内容，结束执行（不进行后续步骤）
+--quick      → QUICK_MODE=true（跳过 Step 3 域确认和 Step 4 规则提问）
+--domain X   → FORCED_DOMAIN=X（Step 3 跳过自动匹配，直接使用指定域）
+--enhance X  → ENHANCE_DOMAIN=X（Step 3 前先增量更新该域 Skill）
+--file X     → FOCUS_FILE=X（Step 3 从该文件推断域，而非 prompt 匹配）
+--no-design  → SKIP_DESIGN=true（跳过 Step 6 Design Brief）
+--story X    → STORY_ID=X（Step 9 日志写入 modus/stories/{X}/vibe-log.md）
+--dry-run    → DRY_RUN=true（Step 7 只输出设计，不生成代码）
+--watch      → WATCH_MODE=true（Step 10 启用文件监听，实验性）
+--codex      → CODEX_MODE=true（禁用交互提问，全批量推断输出）
+--no-skill   → NO_SKILL=true（跳过 Step 3~5 所有 Skill 加载）
+--verbose    → VERBOSE=true（输出详细日志：置信度、token 用量）
+--project X  → PROJECT=X（多项目 workspace 时指定目标项目）
+```
+
+> **Codex 环境自动检测**：若无法判断平台，当用户消息不包含问号且 prompt 明确时，推断为 Codex 环境，自动启用 CODEX_MODE。
+
+---
+
+### Step 0：读取项目宪法（硬性约束）
+
+读取 `modus/config.yaml`（若存在），提取 `constitution` 字段：
 
 ```yaml
 constitution:
@@ -52,27 +69,15 @@ constitution:
 
 将 `hard_rules` 作为**最高优先级约束**，在整个编码过程中强制遵守，不因业务需要而妥协。
 
-**读取 `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 域匹配
+若文件不存在或 `constitution` 为空，跳过此步。
 
 ---
 
-### Step 1：Level 1 加载——读知识目录（token 预算：~200）
+### Step 1：Level 1 加载——读知识目录（~200 tokens）
 
 读取 `modus/knowledge-catalog.md`（全景目录索引）：
 - 了解当前项目有哪些可用的 Skill
-- 识别各 Skill 的 status 状态、最近引用时间
+- 识别各 Skill 的 maturity 状态、最近引用时间
 - 为 Step 2 的智能分析做准备
 
 **如果 `knowledge-catalog.md` 不存在：**
@@ -87,17 +92,33 @@ A. 现在运行快速初始化（约 2-5 分钟）？
 B. 继续使用降级模式（无业务上下文，结果质量可能降低）？
 ```
 
-- 选 A → 执行 `/modus:init` 流程；init 完成后，**从 Step 1 重新开始**（读取新生成的 knowledge-catalog.md）
-- 选 B → 跳过 Step 2-3，直接进入 Step 4（**降级模式**：歧义检测仅执行 R2/R4，其余规则依赖 Step 2 的复杂度分析，在无 catalog 的情况下不可用）
+> Codex 模式（CODEX_MODE=true）：自动选择 B，输出 `[降级模式：无知识库，以代码推断为准]`，不等待用户输入。
+
+- 选 A → 执行 `/modus:init` 流程，完成后继续
+- 选 B → 跳过 Step 2-4，直接进入 Step 5（设计 Brief 仍执行）
+
+**Step 1 尾部：会话连续性检测（Cursor Vibe Coding 借鉴）**
+
+读取 `modus/sessions/vibe-log.md` 最近 3 条记录（若存在）：
+- 若本次 prompt 涉及的域与上次记录的域相同 → 标注 `[续接上次会话: {上次摘要}]`，Step 4 中可跳过已加载的 Skill
+- 若无匹配 → 静默继续
+
+若 `--verbose`，输出：`[会话检测: {匹配/不匹配} | 上次: {日期} {域}]`
 
 ---
 
-### Step 2：智能分析引擎（token 预算：~0，基于 catalog 内容推理，不读新文件）
+### Step 2：智能分析引擎
+
+> **若 NO_SKILL=true**：跳过此步，直接进入 Step 5。
 
 基于用户 prompt 和 knowledge-catalog 内容，推导以下三个维度，**不需要读取完整 SKILL.md**：
 
 #### 2A：域匹配与置信度
 
+若 FORCED_DOMAIN 已设置，直接使用，跳过匹配计算。
+
+若 FOCUS_FILE 已设置，先读取该文件，从包路径、类名中推断域，再进行匹配。
+
 对每个 catalog 中的业务域，计算匹配置信度：
 
 ```
@@ -108,99 +129,78 @@ B. 继续使用降级模式（无业务上下文，结果质量可能降低）
 ```
 
 **输出规则：**
-- 置信度 ≥ 85% 的**单个域**：自动选中并**输出一行可见日志**（不需要等待用户确认，继续下一步）：
-  ```
-  [已匹配 order 域 · 置信度 92%]
-  ```
-  用户若看到匹配错误，在下一条输入中纠正即可，Agent 重新匹配。
-- 多个域，或最高置信度 < 85%：展示候选列表，等待用户确认（可直接回车接受建议）：
-  ```
-  根据你的需求，以下域可能相关：
 
-  ✓ order（订单域）— 订单创建、状态流转       [verified] 置信度 72%
-  ? payment（支付域）— 支付发起、回调          [proven]  置信度 60%
+- 置信度 ≥ 85% 的**单个域**：自动选中，无需用户确认
+- Codex 模式（CODEX_MODE=true）：阈值降低至 70%，更激进地自动推断
+- 多个域或最高置信度未达阈值：展示候选列表（Codex 模式下自动选最高分）
+
+```
+根据你的需求，我匹配到以下业务域：
+
+✓ order（订单域）— 订单创建、状态流转       [verified] 置信度 92% → 自动加载
+? payment（支付域）— 支付发起、回调          [proven]  置信度 60% → 是否也需要？
+
+直接回车确认，或告诉我调整。
+```
 
-  直接回车确认 order 域，或告诉我调整。
-  ```
+若 `--verbose`，输出每个域的完整置信度评分详情。
 
 #### 2B：任务复杂度评估
 
 | 复杂度 | 判定条件 | 后续影响 |
 |--------|---------|---------|
-| `Simple` | 单域 / 有明确接口名和功能描述 / 无跨域依赖 / 改动范围可预估为单文件 | Design Brief 精简为 3 节 |
+| `Simple` | 单域 / 有明确接口名和功能描述 / 无跨域依赖 / 可预估为单文件改动 | Design Brief 精简为 3 节 |
 | `Medium` | 跨域依赖 / 涉及状态机或事务 / 需求描述有一处明显歧义 | Design Brief 完整 9 节 |
 | `Complex` | 多域 + 多处歧义 / 涉及 Pitfall 命中 / prompt 含「大概/可能/随便/看着来/都行」等模糊词 | Design Brief 完整 9 节 + 风险标注 |
 
 #### 2C：输出分析摘要
 
-完成 2A / 2B 后，在内联上下文中记录（不输出给用户）：
+完成 2A / 2B 后，在内联上下文中记录（不输出给用户，除非 --verbose）：
 
 ```
 [ANALYSIS]
 domain: {domain}  confidence: {%}
 complexity: Simple | Medium | Complex
-ambiguity_rules_hit: [R1, R3, ...]  ← 命中的规则 ID，见 Step 4
+ambiguity_rules_hit: [R1, R3, ...]
 ```
 
 ---
 
-### Step 3：条件性 Skill 前置同步（防腐机制触发）（token 预算：0 正常 / ~3,000 触发更新时）
+### Step 3：条件性 Skill 前置同步（轻感知）
 
-对 Step 2 确认的每个业务域，按以下步骤轻量检查是否需要更新，不做额外的 hash 计算：
+> **若 QUICK_MODE=true 或 NO_SKILL=true**：跳过此步。
 
-**检查来源说明（各条件读取不同来源）：**
-- 条件 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` 字段
+**若 ENHANCE_DOMAIN 已设置**：优先对该域触发增量更新（无论是否满足以下条件）。
 
-#### 触发更新的条件（满足任一即触发）
-
-- `status = stale`（已被防腐机制降级，禁止直接引用）
-- catalog 中 `last_referenced` 超过 `stale_after_days`（Skill frontmatter 中配置，默认 90 天）
-- **`stale_cascade = true`**（上游依赖域发生变更，本域知识需要验证——见依赖图传播规则）
-
-**以上三条是 vibe 的触发依据。hash 检查是模式 B 内部的执行逻辑，不在此处重复计算。**
-
-#### 依赖链传播规则（stale_cascade）
+对 Step 2 确认的每个业务域，执行以下检查：
 
-当匹配域的 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 → 继续，不标注（用户明确声明不涉及）
+- `maturity = stale`（已被标记为过期）
+- catalog 中 `last_referenced` 超过 90 天
+- hash 检查发现 key_files 有变化
 
 #### 执行方式
 
 ```
-触发更新（status=stale 或 last_referenced 超期）
-         → 静默调用 modus-skill-creator 模式 B（模式 B 内部自行做 hash 快速比对）
-         → 模式 B hash 一致：仅更新 last_referenced，不做全量扫描
-         → 模式 B hash 不一致：执行增量更新
-         → 完成后输出单行状态：[已同步 {domain} 域知识]
-
-触发联动验证（stale_cascade=true）
-         → 展示上方三选项，等待用户选择
-         → 选 A 时调用 modus-skill-creator 模式 B 并重置 stale_cascade: false
+触发更新 → 静默执行增量 Skill 更新
+         → 更新完成后输出单行状态：
+           [已同步 {domain} 域知识]
 
-不触发 → 直接进入 Step 4，将 last_referenced 更新为今日并写回 SKILL.md frontmatter（不触发 hash 重算），不输出任何提示
+无需更新 → 直接进入 Step 4，不输出任何提示
 ```
 
-**说明：** 若三个条件均未命中（status 正常 + 最近用过 + 无上游变更），说明防腐机制认为 Skill 仍然有效，直接加载使用即可。频繁的 vibe session 不会每次都触发 hash 计算，只有防腐机制检测到异常时才召唤模式 B。
+Codex 模式：所有同步静默执行，不输出状态行（减少干扰）。
 
 ---
 
-### Step 4：规则驱动 AskUserQuestion（token 预算：~0，基于 Step 2 分析结果）
+### Step 4：规则驱动澄清问题
+
+> **若 QUICK_MODE=true 或 CODEX_MODE=true**：跳过此步，直接进入 Step 5。输出 `[Codex 模式：跳过交互确认，自动推断所有决策]`。
 
 #### 歧义规则清单
 
-根据 Step 2C 中记录的 `ambiguity_rules_hit`，判断是否需要提问。
+根据 Step 2C 中记录的 `ambiguity_rules_hit`，判断是否需要提问：
 
 | 规则 ID | 触发条件 | 问题类型 |
 |---------|---------|---------|
@@ -221,39 +221,58 @@ ambiguity_rules_hit: [R1, R3, ...]  ← 命中的规则 ID，见 Step 4
 命中 ≥ 3 条规则 → 优先选择最高影响的 2 条规则提问（R5 > R1 > R3 > R4 > R2）
 ```
 
-**提问格式（命中时）：**
+等待用户回答后，输出一句话确认摘要：`好的，理解了：{核心决策点 1-2 句话}。开始实现。`
 
-```
-编码前需确认几点：
+---
 
-1. [{问题类型}] {具体问题}
-2. [{问题类型}] {具体问题}  ← 最多 2 个
+### Step 5：Level 2 加载——读匹配 Skill（~3000 tokens/个）
 
-回答后我立即开始实现。
-```
+> **若 NO_SKILL=true**：跳过此步。
 
-等待用户回答后，输出一句话确认摘要：
+读取用户确认的业务域对应的完整 Skill 文件：
 
+**路径规则（v3.1 Single Source of Truth）：**
 ```
-好的，理解了：{核心决策点 1-2 句话}。开始实现。
+modus/knowledge/biz-{domain}/SKILL.md
 ```
 
----
-
-### Step 5：Level 2 加载——读匹配 Skill（token 预算：~3,000/个，仅加载匹配域）
+例如：`modus/knowledge/biz-order/SKILL.md`、`modus/knowledge/biz-payment/SKILL.md`
 
-读取用户确认的业务域对应的完整 SKILL.md 文件，将其内容作为背景知识。
+> **注意**：`.codebuddy/skills/modus-biz-{domain}/SKILL.md` 为旧路径引用桩，已废弃，请勿使用。
 
-**注意事项：**
+**加载注意事项：**
 - 只加载确认相关的域，不相关的域 Skill **不读取**（节省 token）
-- 若 Skill 的 `status` 为 `draft`，提示：「该 Skill 较新，若与代码有出入，以代码为准」
+- 若 Skill 的 `maturity` 为 `draft`，提示：「该 Skill 较新，若与代码有出入，以代码为准」
+- 若 Step 1 检测到**续接上次会话**且域相同，可跳过重新加载，直接使用上次上下文
 - 在 Skill 中重点关注 `[pitfall]`、`[model]`、`[guideline]` 条目，以及 `关键文件索引`
 
+若 `--verbose`，输出：`[已加载 {domain} Skill | {token 数} tokens | maturity: {状态}]`
+
+---
+
+### Step 5.5：文件优先感知（Cursor Vibe Coding 借鉴）
+
+> **若 SKIP_DESIGN=true**：跳过此步。
+
+在生成 Design Brief 之前，扫描感知当前代码现状：
+
+**若 FOCUS_FILE 已设置**：读取该文件全文，以其实际代码结构作为设计的优先参考，而非仅凭 Skill 描述。
+
+**普通模式**：从 Step 5 加载的 Skill `关键文件索引` 中，**按需读取** 1-2 个与本次需求最相关的实际代码文件（如主 Manager 类、核心 Mapper），感知：
+- 当前方法签名（避免生成冲突的接口）
+- 已有的命名风格（保持一致）
+- 可复用的基础设施（避免重复造轮子）
+
+输出单行提示：`[已感知代码现状: {file1}, {file2}]`
+
 ---
 
-### Step 6：自适应内联设计方案（Design Brief CoT）（token 预算：Simple ~200 / Medium/Complex ~1,000）
+### Step 6：自适应内联设计方案（Design Brief CoT）
+
+> **若 SKIP_DESIGN=true 或 --no-design**：跳过此步，输出 `[--no-design: 跳过设计，直接编码]`，进入 Step 7。
+> **若 DRY_RUN=true**：执行此步，但 Step 7 停止（只输出设计，不生成代码）。
 
-**触发：** 每次编码任务前强制执行，不可跳过。  
+**触发：** 每次编码任务前强制执行，不可省略（除非 --no-design）。
 **产出：** 内联于当前 LLM 上下文，**不写入任何文件**。
 
 根据 Step 2B 评估的复杂度，输出不同深度的设计方案：
@@ -266,8 +285,8 @@ ambiguity_rules_hit: [R1, R3, ...]  ← 命中的规则 ID，见 Step 4
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ## 实现蓝图
-Data:    {Mapper 类/方法}
-Service: {Manager/Service 类/方法}
+Data:    {Mapper 类/方法}（路径: modus/knowledge/biz-{domain}/SKILL.md → 关键文件索引）
+Service: {Manager/Service 类/方法，标注 @Transactional 位置}
 API:     {Facade/Controller 类/方法}
 
 ## 禁止事项
@@ -278,36 +297,51 @@ API:     {Facade/Controller 类/方法}
 |-------|---------|---------|
 | {需求} | {类/方法} | {测试/联调} |
 
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[End of Design Brief — 开始编码]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 #### Medium/Complex 模式（完整 9 节）
 
-调用 `modus-design-brief` Skill，传入：
-- `mode: vibe`（内联输出模式，不落盘）
-- `complexity: Medium | Complex`
-- `analysis_doc: 用户 prompt + Step 4 确认的意图摘要`
-- `business_skills: Step 5 已加载的 Skill 内容`
-- `constitution: Step 0 读取的 constitution 字段`
-
-**Complex 模式额外要求：**
-- 节 6（边界条件）必须完整展开所有失败路径
-- 节 9（需求追踪矩阵）每行追加 `⚠️` 标注已命中的 Pitfall
-
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 [Design Brief — {Simple|Medium|Complex} | 域: {domain1}, {domain2}]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ## 1. 基本信息
+模式: vibe | 涉及域: {domain1}, {domain2} | 复杂度: {level}
+
 ## 2. 业务意图摘要
+{来自 Step 4 确认的意图，或自动推断}
+
 ## 3. 实体与数据模型
+{基于 Skill [model] 条目和用户意图推导，字段带类型}
+
 ## 4. API / 接口合同
+{方法签名，带完整包路径}
+
 ## 5. 实现蓝图
+Data:    {具体 Mapper 类/方法}
+Service: {具体 Manager/Service 类/方法，标注 @Transactional 位置}
+API:     {Facade/Controller 类/方法}
+
 ## 6. 边界条件与异常处理
+{覆盖关键失败路径，含错误码}
+{Complex 模式：展开所有失败路径，每条附错误码}
+
 ## 7. 代码生成提示
+{来自 Skill 关键文件索引的可复用类 + 命名规范示例}
+{Step 6 感知到的现有代码结构}
+
 ## 8. 禁止事项与已知坑
+{constitution hard_rules + Skill [pitfall]}
+{Complex 模式：每条附 pitfall 来源和影响范围}
+
 ## 9. 需求-任务追踪矩阵
+| 需求点 | 对应实现 | 校验方式 | 风险 |
+|---|---|---|---|
+| {需求} | {类/方法} | {测试/联调} | {⚠️ pitfall（Complex 模式）} |
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 [End of Design Brief — 开始编码]
@@ -316,31 +350,22 @@ API:     {Facade/Controller 类/方法}
 
 ---
 
-### Step 7：执行编码任务（Level 3 按需加载）（token 预算：~500–2,000/文件，仅在需要时读取）
+### Step 7：执行编码任务（Level 3 按需加载）
 
-**编码前先声明目标与完成标准（必须，不可跳过）：**
+> **若 DRY_RUN=true**：输出 `[--dry-run: 已生成 Design Brief，不输出代码。如需实现，去掉 --dry-run 重新运行。]`，结束执行。
 
-```
-任务目标：{一句话，说明本次编码要实现什么}
-完成标准：
-  · 功能验证：{可运行的验证命令或手动验证步骤，如 mvn test -Dtest=OrderServiceTest}
-  · 影响范围：{仅修改以下文件/类，不涉及其他}
-  · 未在范围内的改动，即使发现问题也只标注不修改
-```
-
-> **设计理由（Karpathy Goal-Driven Execution）：** "Give it success criteria and watch it go." 在开工前声明可验证的完成标准，而不是靠感觉判断"完成了"。用户也能据此快速确认 Agent 理解了意图。
-
----
-
-基于 Step 6 内联设计方案和澄清后的意图，执行用户的编码请求：
+基于 Step 6 内联设计方案，执行用户的编码请求：
 
-- 以设计方案中「实现蓝图」为编码路线图
-- 严格遵守「禁止事项」——这是 constitution hard_rules 和 Skill [pitfall] 的汇总
-- 引用「代码生成提示」中的现有类路径，不凭空创造类名
-- **Level 3 加载：** 需要具体代码实现时，按需读取 Skill 中 `关键文件索引` 指向的实际代码文件（而非预先全量读取）
+- 以设计方案中「实现蓝图」（节 5）为编码路线图
+- 严格遵守「禁止事项」（节 8）——这是 constitution hard_rules 和 Skill [pitfall] 的汇总
+- 引用「代码生成提示」（节 7）中的现有类路径，不凭空创造类名
+- **Level 3 加载**：需要具体代码实现时，按需读取 Skill `关键文件索引` 指向的实际代码文件（而非预先全量读取）
+- **编辑优先（Cursor 原则）**：优先修改已有文件，而非创建新文件；改动范围最小化
+- **增量输出（Cursor 原则）**：大改动时分批输出，每批代码可独立编译通过
 - 对不确定的业务规则，优先参考 Skill 中的规则描述
 - 如发现 Skill 中记录有误或过时，记录到内部缓冲区，在 Step 8 处理
-- **每个改动的文件都必须能追溯到上方「完成标准」中的影响范围；无法追溯的改动，暂停并问用户**
+
+Codex 模式下，每个文件生成前输出分隔符：`=== 生成文件: {path} ===`
 
 ---
 
@@ -357,51 +382,28 @@ API:     {Facade/Controller 类/方法}
 
 #### 执行方式
 
-**不在 session 结束时直接写入 Skill 文件，改为缓冲到待沉淀队列：**
-
-```
-有新知识 → 追加到 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]
-
-无新知识 → 静默跳过
 ```
+有新知识 → 写入 modus/knowledge/biz-{domain}/SKILL.md（v3.1 路径）
+          → 写入完成后输出单行提示：
+            [已更新 {domain} 域知识: 新增 [pitfall] {摘要} / 更正 [model] {字段名}]
 
-**写入 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
+无新知识 → 静默跳过，不输出任何提示
 ```
 
-**设计理由：**
-- 每次 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 内部执行。
+**写回原则：**
+- 只写入有明确代码证据的知识，不写推测性内容
+- 每次写回最多 3 条新条目，避免批量污染
+- 更正已有条目时，保留原条目并追加修订记录（不覆盖历史）
+- Codex 模式：写回操作不输出提示
 
 ---
 
 ### Step 9：写入 Session 日志
 
-编码完成后，将本次会话**追加**（append-only，禁止覆盖原有内容）到 `modus/sessions/vibe-log.md`：
+编码完成后，将本次会话**追加**（append-only，禁止覆盖原有内容）到日志文件：
+
+- 若 STORY_ID 已设置：写入 `modus/stories/{STORY_ID}/vibe-log.md`
+- 否则：写入 `modus/sessions/vibe-log.md`
 
 ```markdown
 ## {YYYY-MM-DD HH:mm} — {需求一句话摘要}
@@ -410,6 +412,7 @@ API:     {Facade/Controller 类/方法}
 - **复杂度：** Simple | Medium | Complex
 - **修改文件：** {变更文件列表，最多 5 个}
 - **知识写回：** {本次写回条目摘要，无则填「无」}
+- **platform：** cursor | codex（CODEX_MODE=true 时填 codex）
 
 ---
 ```
@@ -418,15 +421,32 @@ API:     {Facade/Controller 类/方法}
 
 ---
 
+### Step 10：文件监听模式（实验性，--watch）
+
+> **仅当 WATCH_MODE=true 时执行。**
+
+```
+[--watch 模式已启动]
+监听中... 检测到文件变化时自动触发新一轮 vibe 编码。
+按 Ctrl+C 退出监听。
+```
+
+每次文件保存触发时，以修改文件为 `--file` 参数，自动执行 Step 5.5 → Step 7，跳过 Step 2-4。
+
+---
+
 ## 氛围编程原则
 
-- **智能优先，减少打断**：单域高置信度（≥85%）自动匹配并输出一行日志，无需等待确认；任务清晰时跳过提问直接开工
-- **先设计再编码**：Step 6 内联设计方案是编码的前置必要步骤，不可省略
-- **知识缓冲，commit 时沉淀**：session 中发现的新知识缓冲到 pending-knowledge.yaml；git commit 时统一沉淀到 Skill，避免噪声污染
+- **智能优先，减少打断**：域匹配明确时自动确认，无需强制等用户输入；任务清晰时跳过提问
+- **先设计再编码**：Step 6 内联设计方案是编码的前置必要步骤，不可省略（除非 --no-design）
+- **知识闭环**：每次 vibe 编码都是一次知识更新机会，Step 3 前置同步 + Step 8 后置写回，知识库随项目演进自动积累
+- **文件优先感知**：编码前先感知现有代码结构，避免生成冲突的接口或重复的类名（Cursor Vibe 原则）
+- **编辑优先**：优先修改已有文件，改动最小化，每批代码可独立编译（Cursor Vibe 原则）
+- **会话连续**：利用 vibe-log.md 实现跨会话上下文传递，相同域不重复加载（Cursor Vibe 原则）
 - **有据可依**：引用的实体、字段、接口名必须来自 Skill 或已有代码
 - **宪法优先**：constitution.hard_rules 是不可违反的底线，优先于一切
 - **按需加载**：不预先读取所有 Skill，降低 token 消耗
-- **主动补全，不触碰无关文件**：对明显缺失（如必要的参数校验、事务注解）主动补充到当前任务文件中；但不主动修改与当前任务无关的其他文件（发现问题→标注→告知用户）
+- **主动补全**：发现明显缺失（如缺少参数校验、日志）时主动补充
 
 ---
 
@@ -436,8 +456,86 @@ API:     {Facade/Controller 类/方法}
 
 1. 跳过 Step 2-3（无 catalog 可分析）
 2. Step 4 仅执行 R2（模糊词检测）和 R4（缺少决策参数检测）
-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]`
+3. Step 5 跳过（无 Skill 可加载）
+4. Step 6 固定使用 Medium 模式（无法判断复杂度）
+5. Step 8 跳过写回（无 Skill 文件可写入）
+6. 在回复开头标注：`[降级模式：无业务上下文，建议先运行 /modus:init]`
+
+---
+
+## Codex 平台适配说明
+
+Codex 平台与 Cursor 的核心差异及适配方式：
+
+| 特性 | Cursor | Codex | 本 Skill 适配方式 |
+|------|--------|-------|-----------------|
+| 交互提问 | 支持多轮对话 | 单次批量输出 | `--codex` 禁用所有 AskUserQuestion |
+| 域匹配确认 | 等待用户确认 | 自动推断 | Codex 模式阈值降至 70%，自动选最高分 |
+| 进度展示 | IDE 内联显示 | 纯文本输出 | 每 Step 输出清晰分隔符 |
+| 触发方式 | `/modus:vibe` 命令 | 自然语言描述 | description 字段覆盖中英文触发词 |
+
+**在 Codex 平台使用示例（自然语言触发，无需命令格式）：**
+```
+帮我实现歌曲同步状态查询接口 --codex
+修复专辑发行时的 NPE 问题 --codex --domain album
+给版权审核模块新增批量审批功能 --codex --story 1234567
+```
+
+**完整 --codex 行为清单：**
+- Step 0：正常执行（constitution 始终加载）
+- Step 1：知识库不存在时自动选 B 降级
+- Step 2：域匹配阈值降至 70%，自动选最高置信度域
+- Step 3：静默同步，不输出状态行
+- Step 4：**完全跳过**，改为输出 `[Codex 模式：自动推断 → 域={domain}, 复杂度={level}]`
+- Step 5~6：正常执行，每 Step 前输出 `=== Step {N}: {名称} ===`
+- Step 7：每个文件前输出 `=== 生成文件: {path} ===`
+- Step 8：写回静默执行，不输出提示
+- Step 9：日志追加 `platform: codex`
+
+---
+
+## 命令参考（--help 输出内容）
+
+```
+/modus:vibe — 智能氛围编程
+
+用途：
+  在编码前自动加载相关业务知识上下文，让 AI 以「懂业务的资深开发者」身份工作。
+  融合 Cursor Vibe Coding 的零打断流动理念，支持置信度域匹配、自动 Skill 同步、
+  知识闭环写回、Codex 平台批量模式。
+
+用法：
+  /modus:vibe [需求描述] [参数...]
+
+参数：
+  --help                 显示此帮助信息，中止执行
+  --quick                快速模式：跳过域匹配和 Skill 预加载，适合单文件简单改动
+  --domain <name>        直接指定业务域（如 --domain order），跳过自动匹配
+  --enhance <domain>     编码前先对指定域执行增量 Skill 更新（如 --enhance album）
+  --file <path>          聚焦单文件：从该文件推断域，只加载相关 Skill
+  --no-design            跳过 Design Brief 内联设计（极速模式，仅适合单行改动）
+  --story <id>           关联 TAPD Story ID，将编码日志写入 modus/stories/{id}/vibe-log.md
+  --dry-run              只输出 Design Brief，不生成实际代码（用于方案确认）
+  --watch                持续监听文件变化，触发 save-driven vibe coding（实验性）
+  --codex                Codex 平台模式：禁用交互提问，全批量推断输出，自动推断所有决策
+  --no-skill             不加载任何业务 Skill（完全降级模式）
+  --verbose              输出详细日志（域匹配置信度、token 用量、会话检测结果）
+  --project <name>       多项目 workspace 时指定目标项目（覆盖自动路由）
+
+示例：
+  /modus:vibe 修复歌曲同步逻辑的 NPE 问题
+  /modus:vibe 新增批量审批接口 --domain audit --story 1234567
+  /modus:vibe 优化专辑发行流程 --enhance album --verbose
+  /modus:vibe 修改一行注释 --quick --no-design
+  /modus:vibe --dry-run 设计版权购买申请的查询接口
+  /modus:vibe 实现艺人等级更新 --codex --story 9876543
+
+业务知识路径（v3.1）：
+  modus/knowledge/biz-{domain}/SKILL.md
+
+相关命令：
+  /modus:init    初始化/更新知识库（首次使用前建议先跑）
+  /modus:plan    生成功能规划文档（复杂需求建议先 plan 再 vibe）
+  /modus:spec    规范驱动开发（接口契约变更推荐使用）
+  /modus:auto    智能推荐最合适的命令模式
+```