@modus-ai/modus 0.1.7 → 0.2.1

package/README.md

@@ -42,7 +42,7 @@ modus init      # CLI 初始化，生成框架文件和配置
 |------|------|-----------|
 | `/modus:init` | 扫描项目，生成业务/团队/技术三层知识库 + 知识目录 | `.codebuddy/skills/` + `modus/knowledge-catalog.md` |
 | `/modus:vibe` | 氛围编程，渐进式加载业务上下文后直接编码 | 直接修改代码，无新增文件 |
-| `/modus:plan` | 功能规划，复杂度自动分级，含 ADR 决策记录和 pitfall 风险提示 | `modus/plans/{name}/` |
+| `/modus:plan` | 功能规划，两层知识检索 + 3 问澄清 + 单一 plan.md + Build 确认执行 | `modus/plans/{name}/plan.md` |
 | `/modus:spec` | 规范开发，delta specs + GIVEN/WHEN/THEN 验收，含可选 verify + 冲突检测 | `modus/changes/{name}/`，归档合并到 `modus/specs/` |
 | `/modus:auto` | 智能模式推荐：读 TAPD Story，四维评分，推荐 vibe/plan/spec/harness | 启动所选模式后按该模式产出 |
 | `/modus:harness` | 全自动双 Loop 多智能体流程，8 个 SubAgent 协作，含知识沉淀闭环 | `modus/plans/active/{story-id}/` |
@@ -138,7 +138,7 @@ your-project/
     ├── config.yaml                   ← 项目宪法
     ├── knowledge-catalog.md          ← 全景索引（~200 tokens）
     ├── specs/{domain}/spec.md        ← 主规格库（/spec 归档后）
-    ├── plans/{name}/                 ← /plan 活跃目录
+    ├── plans/{name}/plan.md          ← /plan 唯一规划文档（含 .modus-state.yaml）
     ├── plans/active/{story-id}/      ← /harness 产出物
     ├── plans/archive/                ← /plan 归档
     └── changes/                      ← /spec 产出物及归档

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modus-ai/modus",
-  "version": "0.1.7",
+  "version": "0.2.1",
   "description": "Modus — Business-grounded AI coding accelerator for CodeBuddy IDE",
   "keywords": [
     "ai",

package/templates/skills/modus-design-brief/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: modus-design-brief
-description: 在代码开发前生成结构化的设计方案（design-brief），将需求分析信息转化为 LLM 可直接消费的实现指南。由 modus-plan、modus-spec 内部调用（落盘为 design-brief.md），或由 modus-vibe 内联调用（注入上下文，不落盘）。触发条件：plan/spec/vibe Skill 内部 Step 5.5 调用，或用户直接运行 @modus-design-brief。
+description: 在代码开发前生成结构化的设计方案（design-brief），将需求分析信息转化为 LLM 可直接消费的实现指南。由 modus-plan、modus-spec 内部调用（落盘为 design-brief.md），或由 modus-vibe 内联调用（注入上下文，不落盘）。触发条件：plan/spec/vibe Skill 内部 Step 6 调用，或用户直接运行 @modus-design-brief。
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
@@ -305,7 +305,7 @@ public enum {EnumName} {
 
 ### plan / spec 模式调用方式
 
-在 Step 5.5 中，直接调用本 Skill，传入以下参数：
+在 Step 6 中，直接调用本 Skill，传入以下参数：
 ```
 output_path: modus/plans/{name}/design-brief.md   # plan 模式
 output_path: modus/changes/{name}/design-brief.md  # spec 模式

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

@@ -85,7 +85,7 @@ B. 强制继续（无业务上下文，风险较高）
 - 创建工作目录：`modus/plans/active/{story-id}/`
 - 扫描目录，若存在部分产出物（含 HANDOFF 块），从断点处继续
 
-### Step 0.5：澄清意图（仅全新流程）⏸️ 【人工交互节点】
+### Step 1：澄清意图（仅全新流程）⏸️ 【人工交互节点】
 
 读取 TAPD Story 内容后，在启动 SubAgent 01 之前，先确认关键信息：
 
@@ -115,7 +115,7 @@ B. 强制继续（无业务上下文，风险较高）
 启动 Harness 流程...
 ```
 
-### Step 1：INIT——知识注入
+### Step 2：INIT——知识注入
 
 **Level 1 → Level 2 加载：**
 基于用户确认的业务域，调用 SubAgent 00（模式 B：增量更新）：
@@ -261,4 +261,4 @@ feat: {业务摘要}
 5. Gate 失败 → 按规则处理（重入/上报）
 6. 输出本轮进度卡片
 7. 若 SubAgent 07 完成 → 触发 ARCHIVE 知识提取（SubAgent 00 模式 D）
-8. 等待 SubAgent 写入产出物，重复 Step 1
+8. 等待 SubAgent 写入产出物，重复 Step 2

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

@@ -21,9 +21,9 @@ disable: false
 
 读取 `modus/config.yaml`（若存在），提取 `constitution` 字段中的硬性约束，作为整个初始化过程的最高优先级约束。
 
-若 `modus/config.yaml` 不存在，将在 Step 5 创建默认配置。
+若 `modus/config.yaml` 不存在，将在 Step 7 创建默认配置。
 
-### Step 0.5：扫描已有 AI 工具配置
+### Step 1：扫描已有 AI 工具配置
 
 在扫描业务代码之前，先读取项目中已有的 AI 工具配置文件，将存量规则、上下文和 MCP 配置融入 Modus 知识库，避免重复发明轮子。
 
@@ -55,11 +55,11 @@ disable: false
 
 2. **技术栈信息**（`techStack` 字段）
    - 从 `CLAUDE.md` 中寻找构建命令、框架名称等技术栈线索
-   - 与代码文件检测结果合并，用于 Step 5 的技术知识 Skill
+   - 与代码文件检测结果合并，用于 Step 7 的技术知识 Skill
 
 3. **编码规范 / 团队约定**（→ `modus-team-conventions` Skill）
    - 将各工具中找到的约定规则（命名规范、禁止模式、最佳实践等）汇总
-   - 在 Step 4 生成团队约定 Skill 时，把这些规则作为**基础输入**，标注来源（如 `[来源: .cursor/rules/naming.mdc]`）
+   - 在 Step 6 生成团队约定 Skill 时，把这些规则作为**基础输入**，标注来源（如 `[来源: .cursor/rules/naming.mdc]`）
    - 避免重复：如果规则已在其他 Skill 中描述，仅添加引用
 
 4. **MCP 服务器配置**（→ `modus/config.yaml` `mcpServers` 字段）
@@ -88,11 +88,11 @@ disable: false
 继续？[Y/n]
 ```
 
-若用户确认，继续 Step 1；若无任何已有配置，直接进入 Step 1。
+若用户确认，继续 Step 2；若无任何已有配置，直接进入 Step 2。
 
 ---
 
-### Step 1：项目扫描与业务分类
+### Step 2：项目扫描与业务分类
 
 启动一个「项目分析 SubAgent」，执行以下操作：
 
@@ -120,7 +120,7 @@ disable: false
 是否确认以上分类？（可以修改/新增/删除）
 ```
 
-### Step 2：用户确认
+### Step 3：用户确认
 
 等待用户确认或修改业务域列表。用户可以：
 - 直接回复「确认」继续
@@ -128,7 +128,7 @@ disable: false
 - 增加遗漏的业务域
 - 删除不需要的域
 
-### Step 3：生成业务 Skill（Layer 2）—— 并行执行
+### Step 4：生成业务 Skill（Layer 2）—— 并行执行
 
 用户确认后，**同时**为每个业务域启动独立的「Skills Builder SubAgent」（`modus-harness-00-skills-builder` Skill，模式 A），并行生成所有业务 Skill 文件。各域之间完全独立，无需等待彼此完成。
 
@@ -145,11 +145,11 @@ SubAgent-3 (user域)    ──► 扫描用户相关文件 ──► 生成 modu
           │                                              │
           └──────────────── 所有 SubAgent 完成 ──────────┘
                                     ↓
-                         进入 Step 4（串行）
+                         进入 Step 6（串行）
 ```
 
 **每个 SubAgent 的任务（模式 A 标准流程）：**
-1. 接收域名称 + 代表性文件路径列表（来自 Step 1 的分析结果）
+1. 接收域名称 + 代表性文件路径列表（来自 Step 2 的分析结果）
 2. 深度扫描该域的 Service/Manager/Mapper/Domain/Entity 层文件
 3. 提取：核心实体、业务规则、API 契约、关键代码模式
 4. 生成标准格式的 Skill 文件（含 `key_files`、`maturity: draft`）
@@ -164,7 +164,7 @@ SubAgent-3 (user域)    ──► 扫描用户相关文件 ──► 生成 modu
 
 每个 Skill 文件遵循 Business Skill 标准格式（含 maturity/last_referenced/usage_count 字段）。
 
-### Step 3.5：多平台同步（Business Skills）
+### Step 5：多平台同步（Business Skills）
 
 Business Skills 全部生成后，读取 `modus/config.yaml` 的 `platforms` 字段，将每个业务 Skill 同步到其他已选平台。
 
@@ -234,13 +234,13 @@ alwaysApply: false
 
 ---
 
-### Step 4：生成团队约定 Skill（Layer 0-T）
+### Step 6：生成团队约定 Skill（Layer 0-T）
 
 调用「Skills Builder SubAgent」（模式 E：团队约定初始化）：
 
 从以下来源提取团队规范（**按优先级排列**）：
 
-1. **Step 0.5 扫描结果**（最高优先级）
+1. **Step 1 扫描结果**（最高优先级）
    - 从 `CLAUDE.md` / `AGENTS.md` / `.cursor/rules/` / `.codebuddy/rules/` 提取的编码规范
    - 每条规则注明来源，例如：`[来源: .cursor/rules/naming.mdc]`
    - 若同一规则在多个工具中重复，合并为一条并列出所有来源
@@ -253,26 +253,26 @@ alwaysApply: false
 
 生成文件：`.codebuddy/skills/modus-team-conventions/SKILL.md`
 
-**注意：** 若 Step 0.5 中已有来自其他工具的规则，在 Skill 文件开头添加来源声明：
+**注意：** 若 Step 1 中已有来自其他工具的规则，在 Skill 文件开头添加来源声明：
 ```markdown
 > 本 Skill 融合了以下 AI 工具的已有配置：Claude Code (CLAUDE.md)、Cursor (.cursor/rules/)
 > 原始文件保持不变，Modus 仅在此处做统一索引。
 ```
 
-### Step 5：生成技术知识 Skill（Layer 1）
+### Step 7：生成技术知识 Skill（Layer 1）
 
 调用「Skills Builder SubAgent」（模式 E：技术知识初始化），初始化技术知识骨架：
 
 生成文件：`.codebuddy/skills/modus-tech-wiki/SKILL.md`
 
 初始内容来源（按优先级）：
-1. **Step 0.5 扫描结果中的技术信息**
+1. **Step 1 扫描结果中的技术信息**
    - `CLAUDE.md` 中记录的构建命令、测试命令（如 `mvn test`、`npm run test`）
    - `.continue/config.json` 中的模型/上下文提供者配置
 2. 从构建文件提取的技术栈（`pom.xml` → Spring Boot 版本、`package.json` → 框架版本等）
 3. 占位符章节（反模式库、架构决策、跨项目经验——待后续工作流积累）
 
-### Step 6：生成知识全景目录（knowledge-catalog.md）
+### Step 8：生成知识全景目录（knowledge-catalog.md）
 
 在 `modus/knowledge-catalog.md` 创建全景索引，内容如下：
 
@@ -300,7 +300,7 @@ updated: {YYYY-MM-DD}
 衰减规则：proven 12 个月未引用 → verified；verified 6 个月未引用 → draft（标注 ⚠️ 可能已过时）
 ```
 
-### Step 7：初始化 modus/config.yaml（若不存在）
+### Step 9：初始化 modus/config.yaml（若不存在）
 
 若项目尚无 `modus/config.yaml`，生成默认配置：
 
@@ -327,7 +327,7 @@ constitution:
 
 提示用户填写 `constitution` 字段，以便后续命令无需重复说明项目约束。
 
-### Step 8：完成回报
+### Step 10：完成回报
 
 所有业务 Skill 生成完毕后，回复用户：
 
@@ -383,7 +383,7 @@ constitution:
 
 ---
 
-### Step 3 补充：生成 Business Skill 时必须填写 key_files
+### Step 4 补充：生成 Business Skill 时必须填写 key_files
 
 在生成每个业务 Skill（`.codebuddy/skills/modus-biz-{domain}/SKILL.md`）时，**必须**在 frontmatter 中填写 `key_files` 字段：
 

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. Auto-routes to simple/medium/complex depth based on complexity assessment.
+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.
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
@@ -9,19 +9,9 @@ disable: false
 
 **触发条件：** 用户运行 `/modus:plan [需求描述]` 时使用此 Skill。
 
-支持快速模式：`/modus:plan --quick [描述]` 跳过 design.md 和 design-brief.md，仅生成 proposal + tasks。
-
 ## 职责
 
-功能规划入口。通过**三级渐进加载**获取业务上下文（前置更新），先评估需求复杂度自动分级（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） |
+功能规划入口。通过**两层知识检索**获取业务上下文，先评估需求复杂度自动分级（simple/medium/complex），再基于加载的知识向用户提出恰好 3 个精准澄清问题，最终生成单一 `plan.md` 规划文档。文档生成后进入 Build 确认循环，用户可反复修改直至满意后触发代码执行，并将本次规划中的新知识回写到 Skill（后置更新）。
 
 ---
 
@@ -45,11 +35,19 @@ disable: false
 - 若用户选择继续，跳到对应的未完成步骤
 - 若是全新流程，正常从 Step 1 开始
 
+---
+
 ### Step 1：Level 1 加载——读知识目录（~200 tokens）
 
 读取 `modus/knowledge-catalog.md`，了解当前可用 Skill 及其状态。
 
-若不存在，与 vibe 模式相同的降级提示（建议先运行 /modus:init）。
+若不存在，输出降级提示：
+```
+⚠️  未找到 modus/knowledge-catalog.md，建议先运行 /modus:init 初始化知识库。
+    将使用平台规则文件和源码扫描作为替代知识来源继续执行。
+```
+
+---
 
 ### Step 2：域匹配与确认（有则更新，无则新增）
 
@@ -65,9 +63,11 @@ disable: false
 确认？
 ```
 
-### Step 2.5：复杂度评估与自动分级
+---
+
+### Step 3：复杂度评估与自动分级
 
-域确认后，在澄清之前，快速评估需求复杂度并输出分级建议：
+域确认后，快速评估需求复杂度并输出分级建议：
 
 **评估维度：**
 
@@ -94,18 +94,13 @@ disable: false
   ✓ 预估 3-5 个文件变更
   ✓ 无新数据表，无新中间件
   ⚠ 有接口契约变更（影响复杂度）
-
-建议文档深度:
-  {Simple → 建议使用 --quick 模式（proposal + tasks）}
-  {Medium → 完整模式（proposal + design + tasks）}
-  {Complex → 完整模式 + design-brief，或考虑升级为 /modus:spec}
 ```
 
 **复杂度为 Complex 时的特别提示：**
 
 ```
 ⚠️  此需求复杂度较高，建议考虑以下方案：
-  A. 继续使用 /modus:plan（完整模式，含 design-brief）
+  A. 继续使用 /modus:plan（生成 plan.md，含方案对比和任务清单）
   B. 升级为 /modus:spec（可获得 delta specs 和 GIVEN/WHEN/THEN 验收标准）
   C. 拆分需求后分别 /modus:plan
 
@@ -114,56 +109,21 @@ disable: false
 
 若用户选择 B，退出当前 plan 流程，以相同 prompt 启动 `/modus:spec`。
 
-**快速模式自动建议：** 若判定为 Simple 且用户未传 `--quick`，询问：
-```
-需求较简单，是否使用快速模式（跳过 design.md，仅生成 proposal + tasks）？[y/N]
-```
-
-### Step 3：澄清用户意图（AskUserQuestion）
-
-确认域后，在正式启动规划前，提出 1-3 个关键澄清问题：
-
-**提问原则：**
-- 聚焦影响规划方向的不确定点（范围、优先级、约束条件）
-- 若 prompt 已足够具体，可跳过此步
-- 从 Skill 中已有的 `[pitfall]` 和 `[decision]` 检查是否存在相关风险点
-
-**示例问题类型：**
-```
-为了生成准确的规划文档，我需要确认：
-
-1. [范围] 这次改动是否涉及 {相邻域}，还是严格限定在 {domain} 域内？
-2. [优先级] 功能上线有时间限制吗？影响 Sprint 拆分方式。
-3. [兼容性] {已有接口/数据结构} 是否可以修改，还是需要向后兼容？
-4. [规模] 预期数据量级是多少？影响技术方案选型。
-5. [风险] ⚠️ Skill 中记录了已知坑：{pitfall}，是否已考虑到？
-```
-
-等待用户回答后，输出意图摘要：
-
-```
-理解已确认：
-- 目标: {一句话概括}
-- 边界: {在范围内 / 不在范围内}
-- 约束: {技术/业务约束}
-- 项目硬性规则: {来自 constitution 的关键规则}
-
-开始前置更新 Skill，然后生成规划文档。
-```
+---
 
-### Step 4：前置 Skill 更新（Level 2 加载，含 hash 检查）
+### Step 4：Skill 业务域加载（Level 2，含 hash 检查）
 
-确认域和意图后，对每个涉及的业务域执行以下流程（**先 hash 检查，再决定是否全量更新**）：
+域确认后，对每个涉及的业务域执行以下流程（**先 hash 检查，再决定是否全量更新**）：
 
-#### Step 4a：读取 Skill frontmatter（轻量操作，仅读前 20 行）
+#### 4-1：读取 Skill frontmatter（轻量操作，仅读前 20 行）
 
 读取 `.codebuddy/skills/modus-biz-{domain}/SKILL.md` 的 YAML frontmatter，提取：
 - `last_hash`：上次记录的 key_files 内容摘要
 - `key_files`：关键源文件列表
 
-若 Skill 不存在，跳到 Step 4d（新建）。
+若 Skill 不存在，跳到 4-4（新建）。
 
-#### Step 4b：计算当前 key_files 的 hash
+#### 4-2：计算当前 key_files 的 hash
 
 使用 Bash 对 `key_files` 列出的文件内容做 SHA-1 摘要：
 
@@ -175,7 +135,7 @@ shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{
 - 若某个 `key_files` 中的文件不存在（可能已被重命名/删除），视为「已变化」，强制更新
 - 若 `key_files` 为空或缺失，视为「已变化」，强制更新
 
-#### Step 4c：对比 hash，决定是否跳过
+#### 4-3：对比 hash，决定是否跳过
 
 ```
 当前 hash == last_hash（且 last_hash 非空）
@@ -184,10 +144,10 @@ shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{
   → 继续 Step 5
 
 当前 hash != last_hash  OR  last_hash 为空
-  → 进入 Step 4d 执行完整更新
+  → 进入 4-4 执行完整更新
 ```
 
-#### Step 4d：完整前置更新（仅在 hash 不匹配时执行）
+#### 4-4：完整前置更新（仅在 hash 不匹配时执行）
 
 启动「Skill 更新 SubAgent」（`modus-harness-00-skills-builder` 模式 B），执行：
 
@@ -196,7 +156,7 @@ shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{
 3. 对比 Skill 内容与代码现实，识别差异
 4. 更新 Skill 文件中过时的信息，更新 `last_referenced`、`usage_count` 和 `last_hash`
 
-**输出变更摘要 block（透明度关键）：**
+**输出变更摘要 block：**
 
 ```
 ✓ modus-biz-order Skill 已更新
@@ -212,188 +172,194 @@ shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{
 
 若有未初始化的域，调用模式 A 新建 Skill（`last_hash` 留空，`key_files` 由 AI 填写）。
 
-### Step 5：生成计划文档
+**若所有域均已初始化且 Skill 加载成功，直接进入 Step 6，跳过 Step 5。**
 
-基于更新后的 Skill 和已澄清的意图，生成文档到 `modus/plans/{name}/`。
+---
 
-**写入状态文件：**
-创建 `modus/plans/{name}/.modus-state.yaml`：
-```yaml
-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}]
-completed: []
-pending: [proposal, design, design-brief, tasks]  # quick_mode 时 pending 仅含 proposal + tasks
-created: {ISO8601时间戳}
-```
+### Step 5：平台知识兜底扫描（仅在 Step 4 无命中时执行）
 
-**确定 plan 名称：**
-- 从用户 prompt 提取关键词，生成 kebab-case 名称（如 `add-batch-approve`）
-- 如果目录已存在，提示用户确认
+当 `knowledge-catalog.md` 不存在，或当前需求涉及的域全部未初始化时，切换到平台知识扫描模式：
+
+**按已启用平台依次扫描规则文件：**
+
+| 平台 | 扫描路径 |
+|------|---------|
+| CodeBuddy | `.codebuddy/skills/*/SKILL.md` |
+| Claude | `CLAUDE.md` + `.claude/agents/*.md` |
+| Cursor | `.cursor/rules/*.mdc` |
+| Copilot | `.github/copilot-instructions.md` |
 
-**快速模式（`--quick`）产出物：** proposal.md + tasks.md（跳过 design.md 和 design-brief.md）
+扫描完规则文件后，通过 Glob/Read 检索与用户需求关键词相关的源码文件（最多 5 个），提取架构约束与已有模式。
 
-**产出物依赖（完整模式）：**
+**输出兜底加载摘要：**
 
 ```
-proposal.md  ─────────────┐
-                           ▼
-design.md ────────────► design-brief.md ────────────► tasks.md
+⚠️  未找到已初始化的业务 Skill，已切换到平台知识扫描模式
+   已读取: .cursor/rules/modus-biz-order.mdc（Cursor 规则）
+   已读取: CLAUDE.md（项目约定）
+   已扫描: OrderService.java、OrderMapper.java（相关源码，共 2 个文件）
+建议后续运行 /modus:init 正式初始化该业务域 Skill
 ```
 
-**1. proposal.md** — 意图与范围
+---
 
-```markdown
-# Proposal: {功能名称}
+### Step 6：精准 3 问（AskUserQuestion）
 
-## 意图
-{为什么做，业务价值}
+基于 Step 4 或 Step 5 已加载的知识内容，向用户提出**恰好 3 个**澄清问题。
 
-## 范围
-在范围内：
-- {具体事项}
-不在范围内：
-- {明确排除}
+**生成规则（按优先级排序，必须输出恰好 3 个）：**
 
-## 关键约束（来自项目宪法）
-- {constitution.hard_rules 中与本次相关的规则}
+1. **P1 — Skill pitfall 关联问题**（最高优先级）  
+   若加载内容中有与当前需求相关的 `[pitfall]`，必问。  
+   示例：`Skill 中记录了「并发创建订单需加分布式锁」的坑，本次改动是否涉及并发写入场景？`  
+   若有多个相关 pitfall，选取与本次需求匹配度最高的 1 个。
 
-## 已知风险 ⚠️
-<!-- 自动从相关业务 Skill 的 [pitfall] 标签中提取，并结合本次改动范围筛选 -->
-- [pitfall | 来源: modus-biz-order] {具体风险描述，如：并发创建订单时需加分布式锁}
-- [pitfall | 来源: modus-team-conventions] {具体风险描述，如：@Transactional 内部调用不生效}
-<!-- 若相关 Skill 中无 [pitfall] 记录，此章节留空或注明"暂无已知风险" -->
+2. **P2 — 范围/边界问题**  
+   影响规划深度的不确定点（跨域边界、兼容性要求、数据量级）。  
+   示例：`这次改动是否需要向后兼容旧的导出格式，还是可以直接替换？`
+
+3. **P3 — 优先级/约束问题**  
+   时间窗口、技术选型偏好、外部依赖。  
+   示例：`功能是否有明确的上线时间节点？这会影响 Sprint 拆分方式。`
+
+**若 pitfall 不存在**，P1 改为「核心目标澄清」：本次改动的最高优先级目标是什么？
 
-## 影响分析
-涉及文件变更（预估）：
-- {文件路径} — {新增/修改/删除，一句话说明变更目的}
+等待用户回答后，输出意图确认摘要：
 
-## 方案概述
-{技术路径的高层描述}
 ```
+理解已确认：
+- 目标: {一句话概括}
+- 边界: {在范围内 / 不在范围内}
+- 约束: {技术/业务约束}
+- 项目硬性规则: {来自 constitution 的关键规则}
 
-**已知风险章节的生成规则：**
-1. 从 Step 4 已加载的业务 Skill 内容中，提取所有 `[pitfall]` 标签条目
-2. 结合本次改动范围（涉及的域、预估的文件变更），筛选与当前功能相关的 pitfall
-3. 每条 pitfall 注明来源 Skill（`来源: modus-biz-{domain}` 或 `来源: modus-team-conventions`）
-4. 若无相关 pitfall，写 `暂无已知风险（相关 Skill 中未记录 pitfall）`，而非省略章节
+开始生成 plan.md。
+```
 
-**2. design.md** — 技术方案
+---
 
-```markdown
-# Design: {功能名称}
+### Step 7：生成 plan.md
 
-## 技术方案
-{详细实现路径，引用具体的类/方法/接口}
+基于已加载的知识和用户确认的意图，生成单一规划文档到 `modus/plans/{name}/plan.md`。
 
-## 架构决策记录（ADR）[decision]
-<!-- 每个有技术选型的决策点独立记录，后续可沉淀到 modus-tech-wiki -->
+**确定 plan 名称：**
+- 从用户 prompt 提取关键词，生成 kebab-case 名称（如 `add-batch-approve`）
+- 如果目录已存在，提示用户确认
 
-### ADR-01: {决策点标题，如"选择异步 MQ 而非同步 RPC"}
+**写入状态文件：**
+创建 `modus/plans/{name}/.modus-state.yaml`：
+```yaml
+mode: plan
+name: {name}
+status: in-progress
+complexity: medium        # simple | medium | complex（来自 Step 3 评估）
+domains: [{domain1}, {domain2}]
+completed: []
+pending: [plan]
+created: {ISO8601时间戳}
+```
 
-| 字段 | 内容 |
-|------|------|
-| 状态 | 已采纳 / 被否决 / 待评估 |
-| 背景 | {为什么需要做这个决策，2-3 句话} |
-| 选项 | A. {方案A} / B. {方案B} / C. {方案C} |
-| 决策 | 选择方案 {X} |
-| 原因 | {选择理由，包括技术/业务/成本考量} |
-| 放弃理由 | 方案 {Y}：{为什么不选，如：实时性要求高不适合 MQ} |
-| 影响 | {此决策对系统的长期影响，如：引入 MQ 后需维护消费者幂等性} |
+**plan.md 内容结构（对齐 Cursor CreatePlan 风格）：**
 
-<!-- 若有多个决策点，继续添加 ADR-02, ADR-03... -->
+```markdown
+# Plan: {功能名称}
 
-## 数据流
-{文字或 mermaid 图}
+## 概述
+{1-2 句话，说明做什么、为什么做，以及核心业务价值}
 
-## 涉及文件变更
-- {文件路径} — {新增/修改/删除，一句话说明变更目的}
-```
+## 关键约束（来自项目宪法）
+- {constitution.hard_rules 中与本次相关的规则}
+<!-- 若无相关规则，写「以通用团队约定为准」 -->
 
-**ADR 使用规则：**
-- 每个有选型空间的技术决策都应记录一个 ADR
-- 若 Skill 中有 `[decision]` 标签记录了类似决策，在 ADR 背景中引用：`（参考 modus-biz-order 的历史决策：...）`
-- 后置 Skill 更新时，每个 ADR 条目将自动提取为 `[decision]` 写入 `modus-tech-wiki`
+## 已知风险 ⚠️
+<!-- 自动从相关业务 Skill 的 [pitfall] 标签中提取，结合本次改动范围筛选 -->
+- [pitfall | 来源: modus-biz-order] {具体风险描述，如：并发创建订单时需加分布式锁}
+- [pitfall | 来源: modus-team-conventions] {具体风险描述，如：@Transactional 内部调用不生效}
+<!-- 若无相关 pitfall，写「暂无已知风险（相关 Skill 中未记录 pitfall）」 -->
 
-**3. design-brief.md** — 设计方案（代码开发前的精确实现指南）
+## 方案选项对比
+- 方案 A（推荐）：{简述实现路径} — 优：{优点}；劣：{劣点或适用前提}
+- 方案 B：{简述替代路径} — 优：{优点}；劣：{劣点或排除理由}
+<!-- 若只有一种可行方案，写「仅一种可行方案，原因：{说明}」 -->
 
-调用 `modus-design-brief` Skill，传入：
-- `mode: plan`
-- `output_path: modus/plans/{name}/design-brief.md`
-- `analysis_doc: proposal.md 内容`
-- `business_skills: 已加载的 Skill 内容`
-- `constitution: constitution 字段`
+## 实现 Todos
+- [ ] 1. 数据层：{具体任务，如「新增 order_export 表，含 status/created_by 字段」}
+- [ ] 2. 服务层：{具体任务}
+- [ ] 3. 接口层：{具体任务}
+- [ ] 4. 测试：单元测试 + 接口联调
 
-生成后更新 `.modus-state.yaml` 的 `completed` 列表（追加 `design-brief`），并在 `pending` 中移除。
+## 影响文件（预估）
+- `{文件路径}` — {新增/修改/删除，一句话说明变更目的}
+```
 
-**4. tasks.md** — 实现清单
+**已知风险生成规则：**
+1. 从 Step 4/5 已加载内容中，提取所有 `[pitfall]` 标签条目
+2. 结合本次改动范围筛选相关条目，每条注明来源 Skill
+3. 若无相关 pitfall，明确写出而非省略章节
 
-```markdown
-# Tasks: {功能名称}
+生成完成后更新 `.modus-state.yaml` 的 `completed` 列表（追加 `plan`）并从 `pending` 中移除。
 
-## 1. 数据层
-- [ ] 1.1 {具体任务}
+---
 
-## 2. 服务层
-- [ ] 2.1 {具体任务}
+### Step 8：Build 确认循环 ⏸️ 【人工审批节点】
 
-## 3. 接口层
-- [ ] 3.1 {具体任务}
+plan.md 生成后，展示结果并进入确认循环：
 
-## 4. 测试
-- [ ] 4.1 单元测试
-- [ ] 4.2 接口联调
 ```
+✅ plan.md 已就绪：modus/plans/{name}/plan.md
 
-生成每份文档后更新 `.modus-state.yaml` 的 `completed` 列表。
-
-### Step 6：询问归档 ⏸️ 【人工审批节点】
+──────────────────────────────────────────
+你可以：
+  [修改] 直接说出修改意见，我会更新 plan.md，更新后再次展示
+  [Build] 确认方案，开始按 plan.md 中的 Todos 生成代码
+  [归档] 仅保存文档，暂不执行代码生成
 
+等待你的指令。
 ```
-计划文档已生成：
-  modus/plans/{name}/proposal.md
-  modus/plans/{name}/design.md
-  modus/plans/{name}/design-brief.md
-  modus/plans/{name}/tasks.md
 
-状态文件：modus/plans/{name}/.modus-state.yaml
+⏸️ **等待人工确认**
 
-是否归档？归档后文档将移动到 modus/plans/archive/{YYYY-MM-DD}-{name}/
-（归档前可以继续编辑文档）
-```
+**循环逻辑：**
+- 用户提出修改意见 → 更新 `plan.md` → 重新输出上述确认提示（循环，无次数限制）
+- 用户回复「Build」/「开始」/「执行」→ 退出循环，以 `plan.md` 中的 Todos 为输入，启动 `/modus:vibe` 执行代码生成
+- 用户回复「归档」/「稍后」→ 走归档流程，不启动代码生成
 
-⏸️ **等待人工确认**（支持异步：可以在任意时间、任意设备上回复）
+**Build 触发后：**
+```
+🚀 开始执行 plan.md 中的 Todos，启动 /modus:vibe...
+   读取: modus/plans/{name}/plan.md
+   执行范围: {Todos 列表}
+```
 
-用户确认归档后：
-1. 将目录移动到 `modus/plans/archive/{date}-{name}/`
+**归档流程（用户选择归档时）：**
+1. 将目录移动到 `modus/plans/archive/{YYYY-MM-DD}-{name}/`
 2. 更新 `.modus-state.yaml`：`status: archived`
-3. 回复：`✓ 已归档到 modus/plans/archive/{date}-{name}/`
+3. 输出：`✓ 已归档到 modus/plans/archive/{YYYY-MM-DD}-{name}/，可随时运行 /modus:vibe 参考此文档开始编码`
+
+---
 
-### Step 7：后置 Skill 更新（知识回写）
+### Step 9：后置 Skill 更新（知识回写）
 
-归档完成后（或用户选择不归档但完成了规划），执行后置 Skill 更新（模式 C）：
+无论用户选择 Build 还是归档，规划阶段完成后即执行后置知识回写（模式 C）：
 
-1. 从本次生成的 design.md 中提取所有 ADR 条目：
-   - 每个 ADR → `[decision]` 写入 `modus-tech-wiki`（跨项目决策）或对应业务 Skill（域特有决策）
-   - ADR 中的「影响」字段若包含风险点 → 同时写为 `[pitfall]`
-2. 从 proposal.md 的「已知风险」章节中提取任何**本次新发现的**风险（非来自现有 Skill 的已有记录）：
+1. 从 `plan.md` 的「方案选项对比」中提取技术决策：
+   - 每个有选型依据的决策 → `[decision]` 写入 `modus-tech-wiki`（跨项目）或对应业务 Skill（域特有）
+2. 从「已知风险」章节中提取**本次新发现的**风险（非来自现有 Skill 的已有记录）：
    - 新发现的风险 → `[pitfall]` 追加到对应业务 Skill
-3. 从 tasks.md 中提取具体的编码模式或约束 → `[guideline]`
+3. 从「实现 Todos」中提取具体的编码模式或约束 → `[guideline]`
 4. 更新 `modus/knowledge-catalog.md` 的 `last_referenced` 和 maturity
 5. 输出更新摘要：
    ```
    📚 知识已回写到 Skill：
-   - [decision] tech-wiki：批量审批走 MQ 异步（ADR-01）
-   - [decision] tech-wiki：Redis 分布式锁 key 格式规范（ADR-02）
+   - [decision] tech-wiki：批量审批走 MQ 异步
    - [guideline] order 域：批量操作上限 50 条，防止内存溢出
-   - [pitfall] order 域：MQ 消费者需保证幂等性（来自 ADR-01 影响分析）
+   - [pitfall] order 域：MQ 消费者需保证幂等性
    maturity 变化: modus-biz-order draft→verified
    ```
 
-### Step 7.5：多平台 Skill 同步（后置）
+---
+
+### Step 10：多平台 Skill 同步（后置）
 
 知识回写完成后，对所有本次**更新或新建**的业务 Skill 执行多平台同步。
 
@@ -401,6 +367,7 @@ design.md ────────────► design-brief.md ────
 
 1. 读取 `modus/config.yaml` 的 `platforms` 字段
 2. 对受影响的每个业务域（Step 4 前置更新 / 新建的域），按以下规则同步：
+   - **CodeBuddy** → 源文件即 `.codebuddy/skills/modus-biz-{domain}/SKILL.md`（已更新，无需额外操作）
    - **Claude** → 写入 `.claude/agents/modus-biz-{domain}.md`（覆盖旧版本）
    - **Cursor** → 写入 `.cursor/rules/modus-biz-{domain}.mdc`（带 frontmatter，覆盖旧版本）
    - **Copilot** → 在 `.github/copilot-instructions.md` 中替换对应域的标记段落
@@ -424,15 +391,9 @@ modus/
 ├── plans/
 │   ├── add-batch-approve/           ← 活跃计划（未归档）
 │   │   ├── .modus-state.yaml        ← 状态文件（断点续跑用）
-│   │   ├── proposal.md
-│   │   ├── design.md
-│   │   ├── design-brief.md          ← 设计方案（代码开发前的实现指南）
-│   │   └── tasks.md
+│   │   └── plan.md                  ← 唯一规划文档（概述/风险/方案对比/Todos/影响文件）
 │   └── archive/
 │       └── 2026-04-20-add-batch-approve/
 │           ├── .modus-state.yaml    ← status: archived
-│           ├── proposal.md
-│           ├── design.md
-│           ├── design-brief.md
-│           └── tasks.md
+│           └── plan.md
 ```

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

@@ -90,7 +90,7 @@ disable: false
 开始前置更新 Skill，然后生成规范文档。
 ```
 
-### Step 4：前置 Skill 更新（Level 2 加载，含 hash 检查，同 /modus:plan Step 4）
+### Step 4：前置 Skill 更新（Level 2 加载，含 hash 检查，同 /modus:plan Step 5）
 
 对每个涉及的业务域执行以下流程（**先 hash 检查，再决定是否全量更新**）：
 
@@ -254,7 +254,7 @@ proposal.md
 
 生成每份文档后更新 `.modus-state.yaml` 的 `completed` 列表和 `scenarios_covered`。
 
-### Step 5.5：可选实现验证（verify）
+### Step 6：可选实现验证（verify）
 
 文档生成后，询问用户是否执行实现验证（适用于代码已开发完成、准备归档前的场景）：
 
@@ -320,7 +320,7 @@ git diff --name-only HEAD~3 | grep -E 'Test\.java|Spec\.java|test.*\.py'
 
 验证不阻断归档，但警告需用户显式确认后方可继续。
 
-### Step 6：规格冲突检测 + 询问归档 ⏸️ 【人工审批节点】
+### Step 7：规格冲突检测 + 询问归档 ⏸️ 【人工审批节点】
 
 **归档前冲突检测（自动执行）：**
 
@@ -352,7 +352,7 @@ grep -l "### Requirement:" modus/specs/{domain}/spec.md 2>/dev/null
   modus/changes/{name}/tasks.md
   modus/changes/{name}/.modus-state.yaml
 
-实现验证: {passed_with_warnings / passed / skipped}  [Step 5.5 结果]
+实现验证: {passed_with_warnings / passed / skipped}  [Step 6 结果]
 冲突检测: {通过 / N 项需确认}
 
 是否归档？归档后：
@@ -371,7 +371,7 @@ grep -l "### Requirement:" modus/specs/{domain}/spec.md 2>/dev/null
 
 归档完成后更新 `.modus-state.yaml`：`status: archived`。
 
-### Step 7：后置 Skill 更新（知识提取与回写）
+### Step 8：后置 Skill 更新（知识提取与回写）
 
 归档完成后，调用 `modus-harness-00-skills-builder` 模式 C，从 delta specs 中系统性提取知识：
 
@@ -390,7 +390,7 @@ grep -l "### Requirement:" modus/specs/{domain}/spec.md 2>/dev/null
 - knowledge-catalog.md 已更新（order 域 maturity: draft→verified）
 ```
 
-### Step 7.5：多平台 Skill 同步（后置）
+### Step 9：多平台 Skill 同步（后置）
 
 知识提取与回写完成后，对本次涉及的业务域执行多平台同步。
 

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

@@ -124,7 +124,7 @@ B. 继续使用降级模式（无业务上下文，结果质量可能降低）
 如果理解无误，我来开始实现。
 ```
 
-### Step 5.5：内联设计思考（Design Brief CoT）
+### Step 6：内联设计思考（Design Brief CoT）
 
 **触发：** 每次编码任务前强制执行，不可跳过（包括 `--quick` 模式）。  
 **产出：** 内联于当前 LLM 上下文，**不写入任何文件**。
@@ -183,18 +183,18 @@ API: {Facade/Controller 类/方法}
 - 节 9 追踪矩阵在 vibe 模式下用「需求点→实现→校验方式」代替完整 Sprint 映射
 - 若 `--quick` 模式，节 3/4/9 可简化为一行摘要，但节 8 禁止事项必须完整输出
 
-### Step 6：执行编码任务（Level 3 按需加载）
+### Step 7：执行编码任务（Level 3 按需加载）
 
-基于 Step 5.5 内联设计方案和澄清后的意图，执行用户的编码请求：
+基于 Step 6 内联设计方案和澄清后的意图，执行用户的编码请求：
 
-- 以 Step 5.5 内联设计方案中节 5（实现蓝图）为编码路线图
+- 以 Step 6 内联设计方案中节 5（实现蓝图）为编码路线图
 - 严格遵守节 8（禁止事项）——这是 constitution hard_rules 和 Skill [pitfall] 的汇总
 - 引用节 7（代码生成提示）中的现有类路径，不凭空创造类名
 - **Level 3 加载：** 需要具体代码实现时，按需读取 Skill 中 `关键文件索引` 指向的实际代码文件（而非预先全量读取）
 - 对不确定的业务规则，优先参考 Skill 中的规则描述
 - 如发现 Skill 中记录有误或过时，在回复末尾标注「Skill 更新建议」
 
-### Step 7（可选）：Skill 更新建议
+### Step 8（可选）：Skill 更新建议
 
 如果在编码过程中发现业务 Skill 有遗漏或错误，在回复末尾追加：
 
@@ -204,7 +204,7 @@ API: {Facade/Controller 类/方法}
 - [pitfall] order 域：批量操作时若不分页会导致内存溢出
 ```
 
-### Step 8：写入 Session 日志
+### Step 9：写入 Session 日志
 
 编码完成后，将本次会话**追加**（append-only，禁止覆盖原有内容）到 `modus/sessions/vibe-log.md`：
 
@@ -224,7 +224,7 @@ API: {Facade/Controller 类/方法}
 
 ## 氛围编程原则
 
-- **先设计再编码**：Step 5.5 内联设计方案是编码的前置必要步骤，不可省略
+- **先设计再编码**：Step 6 内联设计方案是编码的前置必要步骤，不可省略
 - **设计驱动**：编码时以内联设计方案的实现蓝图（节 5）为路线图，禁止事项（节 8）为红线
 - **有据可依**：引用的实体、字段、接口名必须来自 Skill 或已有代码
 - **风格一致**：生成的代码应与项目现有风格保持一致