@modus-ai/modus 0.2.5 → 0.2.7

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

@@ -1,6 +1,6 @@
 ---
 name: modus-init
-description: Use this skill when executing /modus:init command to scan the codebase, classify business domains, and generate Business Skill files, team-conventions Skill, tech-wiki Skill, and knowledge-catalog index. Trigger on /modus:init command or when user asks to initialize Modus or build business Skills from scratch.
+description: Use this skill when executing /modus:init command (or /modus:init --help/--enhance/--migrate/--dry-run etc.) to scan the codebase, classify business domains, generate Business Skill files in modus/knowledge/, update knowledge-catalog.md, and sync to multi-platform adapters. Trigger on /modus:init or any of its parameter variants. (Modus v3.2)
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 supported_platforms:
@@ -28,11 +28,84 @@ supported_platforms:
 
 # modus-init
 
-**触发条件：** 用户运行 `/modus:init` 时使用此 Skill。
+**触发条件：** 用户运行 `/modus:init [参数]` 时使用此 Skill。
 
-## 职责
+## 参数参考（完整列表）
 
-分析当前项目代码库，按业务领域分类，为每个业务域生成 Business Skill 文件，同时初始化团队约定 Skill（Layer 0-T）、技术知识 Skill（Layer 1）和知识全景目录索引（`modus/knowledge-catalog.md`），作为后续所有 Modus 命令的知识底座。
+```
+/modus:init [参数]
+
+参数:
+  --help                    显示本帮助文档（中文）
+  --project <name>          指定项目（多项目 workspace 必填，单项目可省略）
+  --enhance <domain>        仅增量更新指定业务域，不重建全部（如 --enhance biz-track）
+  --enhance-all             重建所有业务域 Skill（保留框架 Skill，不影响 _conventions/_tech-wiki）
+  --platform <p1,p2>        仅同步指定平台（claude,cursor,codex,copilot，逗号分隔）
+  --dry-run                 预览将生成/修改的文件清单，不写入磁盘
+  --force                   跳过所有「是否确认」交互，直接执行
+  --no-sync                 跳过多平台同步，仅生成 modus/knowledge/ 下的文件
+  --migrate                 将旧路径 .codebuddy/skills/modus-biz-* 迁移到 modus/knowledge/
+  --verbose                 输出详细扫描过程（文件列表、token 预估、hash 变化）
+  --reset-maturity          重置所有 Skill 的 maturity 为 draft（谨慎使用）
+
+组合示例:
+  /modus:init                          # 全量初始化（首次或大重构后）
+  /modus:init --enhance biz-track      # 仅更新歌曲域知识
+  /modus:init --migrate --dry-run      # 预览迁移操作，不写入
+  /modus:init --migrate                # 执行知识库路径迁移（旧 → modus/knowledge/）
+  /modus:init --enhance-all --no-sync  # 重建所有业务域，不同步平台
+  /modus:init --project operations-job --enhance biz-album  # 多项目指定
+```
+
+---
+
+## --help 响应模板
+
+当用户运行 `/modus:init --help` 时，输出以下内容：
+
+```
+Modus Init — 业务知识库初始化工具
+版本：3.2.0
+
+用途：
+  扫描项目代码，按业务域分类，生成结构化 Skill 文件，作为后续所有
+  Modus 命令（vibe/plan/spec/harness）的知识底座。
+  支持多项目工作区路由，知识库统一存放于 modus/knowledge/（平台无关）。
+
+语法：
+  /modus:init [参数]
+
+参数：
+  --help                    显示本帮助
+  --project <name>          指定项目（多项目时必须）
+  --enhance <domain>        仅增量更新指定业务域
+  --enhance-all             重建所有业务域 Skill
+  --platform <p1,p2>        仅同步指定平台（claude,cursor,codex,copilot）
+  --dry-run                 预览模式，不写入文件
+  --force                   跳过所有确认提示
+  --no-sync                 跳过多平台同步
+  --migrate                 迁移旧知识路径到 modus/knowledge/
+  --verbose                 显示详细扫描日志
+  --reset-maturity          重置 Skill 成熟度为 draft
+
+知识库路径（v3.1）：
+  modus/knowledge/_conventions/SKILL.md   — Layer 0-T 团队约定
+  modus/knowledge/_tech-wiki/SKILL.md     — Layer 1 技术知识
+  modus/knowledge/biz-*/SKILL.md          — Layer 2 业务域知识（Single Source of Truth）
+
+平台适配文件（引用式，勿直接编辑）：
+  .codebuddy/skills/modus-biz-*/SKILL.md  — CodeBuddy 引用桩
+  .cursor/rules/modus-knowledge.mdc       — Cursor 引用
+  CLAUDE.md（Modus 章节）                  — Claude Code 引用
+  AGENTS.md                               — Codex/OpenCode 引用
+
+相关命令：
+  /modus:vibe    -- 上下文感知编码
+  /modus:plan    -- 功能规划
+  /modus:spec    -- 规范驱动开发
+  /modus:harness -- 全自动交付流程
+  /modus:auto    -- 智能模式推荐
+```
 
 ---
 
@@ -42,9 +115,9 @@ supported_platforms:
 
 | 区块 | 内容 | Agent 读取时机 | 典型使用场景 |
 |------|------|----------------|------------|
-| **区块 A：执行流程**（Step 0-11） | Agent 执行 `/modus:init` 时的完整步骤指令 | **每次执行 `/modus:init` 必须完整读取** | 全新初始化、重新初始化（模式 1-4）、补全新节 |
-| **区块 B：防腐机制总览** | 防腐字段说明、双级 hash 规则、活跃度感知衰减、status 全链路图、同步副本管理规约 | 执行 Step 5 生成 Skill 前必读；执行 `/modus:verify`、`/modus:refresh` 前必读 | hash 不一致处理、status 升降级、副本同步问题排查 |
-| **区块 C：Business Skill 标准格式**（v3/17节模板） | 多语言适配说明 + 生成每个业务 Skill 时的完整格式参考 | 执行 Step 5 时按需读取对应节的格式要求；辅助命令 `/modus:verify`、`/modus:refresh` 执行时读取 | 格式参考、节内容门槛检查、信号词归属判断 |
+| **区块 A：执行流程**（Step 0-14） | Agent 执行 `/modus:init` 时的完整步骤指令 | **每次执行 `/modus:init` 必须完整读取** | 全新初始化、重新初始化（模式 1-4）、补全新节 |
+| **区块 B：防腐机制总览** | 防腐字段说明、双级 hash 规则、活跃度感知衰减、status 全链路图、同步副本管理规约 | 执行 Step 8 生成 Skill 前必读；执行 `/modus:verify`、`/modus:refresh` 前必读 | hash 不一致处理、status 升降级、副本同步问题排查 |
+| **区块 C：Business Skill 标准格式**（v3/17节模板） | 多语言适配说明 + 生成每个业务 Skill 时的完整格式参考 | 执行 Step 8 时按需读取对应节的格式要求；辅助命令 `/modus:verify`、`/modus:refresh` 执行时读取 | 格式参考、节内容门槛检查、信号词归属判断 |
 
 ---
 <!-- ============================================================ -->
@@ -53,24 +126,166 @@ supported_platforms:
 
 ## 执行流程
 
-### Step 0：读取项目宪法 + 重新初始化检查
+### Step 0：参数解析
 
-读取 `modus/config.yaml`（若存在），提取 `constitution` 字段中的硬性约束，作为整个初始化过程的最高优先级约束。
+**在做任何其他事之前**，解析用户输入的参数：
 
-若 `modus/config.yaml` 不存在，将在 Step 10 创建默认配置。
+```
+输入：/modus:init [参数字符串]
 
-#### 重新初始化分支检查（Step 0 末尾执行）
+解析规则：
+1. 扫描参数字符串，提取所有 --xxx 和 --xxx value 对
+2. 识别特殊参数：
+   --help       → 输出 --help 响应模板，立即结束，不执行后续 Step
+   --dry-run    → 设置 DRY_RUN=true，所有文件写入操作仅打印不执行
+   --force      → 设置 FORCE=true，跳过所有 confirm 交互
+   --migrate    → 设置 MIGRATE_MODE=true，转入迁移流程（Step 1）
+   --enhance X  → 设置 ENHANCE_DOMAIN=X，转入增量更新流程（Step 2）
+   --enhance-all → 设置 ENHANCE_ALL=true，全量重建业务域（保留框架 Skill）
+   --platform X → 设置 TARGET_PLATFORMS=X（逗号分隔）
+   --no-sync    → 设置 NO_SYNC=true，跳过 Step 6 平台同步
+   --verbose    → 设置 VERBOSE=true，详细输出
+   --project X  → 设置 TARGET_PROJECT=X，读取对应项目路径
+   --reset-maturity → 设置 RESET_MATURITY=true
+```
 
-在进入 Step 1 之前，检查是否已有业务 Skill：
+**参数路由决策树：**
 
-```bash
-# 检查是否存在已有的业务 Skill（支持 Bash 的平台）
-ls .codebuddy/skills/modus-biz-* 2>/dev/null
 ```
+检测到 --help?
+  是 → 输出帮助文档，结束
+  
+检测到 --migrate?
+  是 → 跳转到 Step 1（迁移模式）
+  
+检测到 --enhance <domain> 或 --enhance-all?
+  是 → 跳转到 Step 2（增量更新模式）
+  
+以上都无 → 执行标准全量初始化（Step 3 → Step 14）
+```
+
+---
+
+### Step 1：迁移模式（--migrate）
+
+当用户运行 `/modus:init --migrate` 时执行此流程。
+
+**目标：** 将旧路径 `.codebuddy/skills/modus-biz-*` 迁移到 `modus/knowledge/biz-*`
+
+**执行步骤：**
+
+```
+Step 1-1: 扫描现有文件
+  检测 .codebuddy/skills/modus-biz-*/SKILL.md（旧路径）
+  检测 modus/knowledge/biz-*/SKILL.md（新路径，若已存在则提示）
+
+Step 1-2: 展示迁移计划（即使不带 --dry-run 也先展示）
+  迁移计划（共 N 个域）：
+  ┌──────────────────────────────────────────────────┐
+  │ 从：.codebuddy/skills/modus-biz-track/SKILL.md   │
+  │ 到：modus/knowledge/biz-track/SKILL.md           │
+  │ 操作：复制 → 改写原文件为引用桩                    │
+  └──────────────────────────────────────────────────┘
+  (重复 N 次)
+  同时更新：knowledge-catalog.md 路径引用
+  同时更新：CLAUDE.md / AGENTS.md / .cursor/rules/ 中的路径
+
+Step 1-3: 用户确认（--force 时跳过）
+  确认执行迁移？[Y/n]
+
+Step 1-4: 执行迁移
+  对每个业务域：
+  a. mkdir -p modus/knowledge/biz-{domain}/
+  b. 复制完整 SKILL.md 内容到新路径
+  c. 将原 .codebuddy/skills/modus-biz-{domain}/SKILL.md 改写为引用桩：
+     ---
+     name: modus-biz-{domain}
+     modus_ref: "{project}/modus/knowledge/biz-{domain}/SKILL.md"
+     stub: true
+     ---
+     <!-- MODUS_REF: {project}/modus/knowledge/biz-{domain}/SKILL.md -->
+     > 业务知识已迁移至：`{project}/modus/knowledge/biz-{domain}/SKILL.md`
+  d. 对 _conventions 和 _tech-wiki 同理处理
+
+Step 1-5: 更新所有引用文件
+  - knowledge-catalog.md：更新 Skill 文件路径索引
+  - CLAUDE.md：更新 Modus 章节中的知识库路径说明
+  - AGENTS.md：更新知识库入口路径
+  - .cursor/rules/modus-knowledge.mdc（若存在）：更新路径
+
+Step 1-6: 完成回报
+  ✅ 迁移完成
+  已迁移 N 个业务域：
+    biz-track → modus/knowledge/biz-track/SKILL.md ✓
+    ...
+  已更新引用文件：knowledge-catalog.md, CLAUDE.md, AGENTS.md
+```
+
+---
+
+### Step 2：增量更新模式（--enhance <domain> 或 --enhance-all）
+
+**目标：** 仅重建指定域的 Skill，不触动其他域和框架 Skill
+
+```
+Step 2-1: 确定目标域
+  --enhance biz-track    → 目标：modus/knowledge/biz-track/SKILL.md
+  --enhance-all          → 目标：所有 modus/knowledge/biz-*/SKILL.md
 
-> **Cursor 平台替代**（无 Bash）：使用 Glob 工具匹配 `.codebuddy/skills/modus-biz-*/SKILL.md`；若 Glob 返回结果即表示存在已有 Skill。
+Step 2-2: hash 检查（跳过未变化的域）
+  读取当前 Skill frontmatter 中的 last_hash
+  计算对应 key_files 的当前 SHA-1
+  若 hash 相同 → 跳过，输出 "biz-track: 无变化，跳过重建"
+  若 hash 不同 → 继续重建
 
-**若发现已存在 `modus-biz-*` 目录：**
+Step 2-3: 扫描目标域代码
+  深度扫描 key_files 中列出的源文件
+  提取：核心实体变化、业务规则变化、API 契约变化
+
+Step 2-4: 重建 Skill 文件
+  更新 modus/knowledge/biz-{domain}/SKILL.md
+  更新 frontmatter: updated, last_hash, last_referenced
+
+Step 2-5: 同步引用桩（若平台适配文件存在）
+  更新 .codebuddy/skills/modus-biz-{domain}/SKILL.md 引用桩的摘要行
+  
+Step 2-6: 更新 knowledge-catalog.md 的 updated 时间戳
+
+Step 2-7: 完成回报
+  ✅ 增量更新完成
+    biz-track: 已重建（3 处实体变化，1 条新 pitfall）
+    biz-album: 无变化，已跳过
+```
+
+---
+
+### Step 3：读取项目宪法 + 多项目工作区检测 + 重新初始化检查
+
+**多项目工作区检测：**
+
+```
+优先级：
+1. 若用户传入 --project <name>：直接读取 modus-workspace.yaml 中对应项目配置
+2. 若当前工作目录在某项目子目录内：自动检测项目（匹配 modus-workspace.yaml 中 path）
+3. 若都不满足：读取 modus/workspace-catalog.md，展示项目列表让用户选择
+```
+
+扫描 workspace 根目录是否存在 `modus-workspace.yaml`：
+
+- 若**存在**：读取 `workspace_catalog`（新字段）和 `projects` 列表，按上方优先级路由
+- 若**不存在**：检查当前目录是否为单项目（有 `modus/config.yaml` 或 `pom.xml`），若是直接初始化；若检测到多个子项目，**提示用户是否创建 `modus-workspace.yaml`**
+
+**读取项目宪法：**
+
+读取 `modus/config.yaml`（若存在），提取 `constitution` 字段中的硬性约束，作为整个初始化过程的最高优先级约束。
+
+若 `modus/config.yaml` 不存在，将在 Step 13 创建默认配置。
+
+#### 重新初始化分支检查（Step 3 末尾执行）
+
+在进入 Step 4 之前，检查是否已有业务 Skill（`modus/knowledge/biz-*` 或 `.codebuddy/skills/modus-biz-*`）：
+
+**若发现已存在业务 Skill：**
 
 ```
 当前已有以下业务 Skill：
@@ -88,22 +303,23 @@ ls .codebuddy/skills/modus-biz-* 2>/dev/null
 ```
 
 **各模式执行规则：**
-- **全量重建（模式 1）**：清空 `.codebuddy/skills/modus-biz-*/`，然后从 Step 1 开始全量执行
-- **仅更新指定域（模式 2）**：用户选定域后，对这些域重新执行 Step 2→Step 5；其余域保持不变
-- **新增缺失域（模式 3）**：执行 Step 2 扫描，仅对新发现的域执行 Step 5 生成，已有域跳过
+- **全量重建（模式 1）**：清空业务 Skill 目录，然后从 Step 4 开始全量执行
+- **仅更新指定域（模式 2）**：用户选定域后，对这些域重新执行 Step 5→Step 8；其余域保持不变
+- **新增缺失域（模式 3）**：执行 Step 5 扫描，仅对新发现的域执行 Step 8 生成，已有域跳过
 - **补全新节（模式 4，推荐）**：
   - 读取已有 Skill 的已有节，**不修改任何已有内容**
   - 仅追加缺失节（满足域适用性条件的节，不满足则跳过，不填占位符）
   - 对 v2 → v3 迁移：补充 Section 15（业务不变量）、Section 16（领域词汇表）、Section 17（新人上手指南）
   - 同步扩展 frontmatter 的 `key_files`（补充优先级 2/3 类文件，上限 20 个）
   - 更新 `format_version`（v1→v2 或 v2→v3）、`version`（小版本 +1）和 `updated` 日期
-  - 迁移完成后自动触发 Step 6 多平台同步
+  - 迁移完成后自动触发 Step 9 多平台同步（`--force` 时默认选择「仅新增缺失域」）
 
 无论何种模式，都在最后更新 `modus/knowledge-catalog.md` 的索引信息。
 
-**若未发现已有 Skill：** 继续 Step 1 开始全新初始化流程。
+**若未发现已有 Skill：** 继续 Step 4 开始全新初始化流程。
+
 
-### Step 1：扫描已有 AI 工具配置
+### Step 4：扫描已有 AI 工具配置
 
 在扫描业务代码之前，先读取项目中已有的 AI 工具配置文件，将存量规则、上下文和 MCP 配置融入 Modus 知识库，避免重复发明轮子。
 
@@ -123,7 +339,7 @@ ls .codebuddy/skills/modus-biz-* 2>/dev/null
 | **CodeBuddy** | `.codebuddy/rules/*.mdc` | 项目规则 |
 | **CodeBuddy** | `.codebuddy/settings.json` | MCP 服务器配置 |
 | **Continue.dev** | `.continue/config.json`、`.continue/config.yaml` | 上下文提供者、模型配置 |
-| **OpenCode** | `AGENT.md`、`.claude-internal/AGENT.md` | 项目 Agent 指令 |
+| **OpenCode/Codex** | `AGENTS.md`、`AGENT.md`、`.claude-internal/AGENT.md` | 项目 Agent 指令 |
 
 #### 提取与融合规则
 
@@ -131,29 +347,22 @@ ls .codebuddy/skills/modus-biz-* 2>/dev/null
 
 1. **项目描述 / 背景**（`context` 字段）
    - 从 `CLAUDE.md` / `AGENTS.md` 的开头段落提取项目一句话描述
-   - 若 `modus/config.yaml` 中 `context` 为空，自动填入（需用户确认）
 
 2. **技术栈信息**（`techStack` 字段）
    - 从 `CLAUDE.md` 中寻找构建命令、框架名称等技术栈线索
-   - 与代码文件检测结果合并，用于 Step 7 的技术知识 Skill
 
-3. **编码规范 / 团队约定**（→ `modus-team-conventions` Skill）
-   - 将各工具中找到的约定规则（命名规范、禁止模式、最佳实践等）汇总
-   - 在 Step 6 生成团队约定 Skill 时，把这些规则作为**基础输入**，标注来源（如 `[来源: .cursor/rules/naming.mdc]`）
-   - 避免重复：如果规则已在其他 Skill 中描述，仅添加引用
+3. **编码规范 / 团队约定**（→ `modus/knowledge/_conventions` Skill）
+   - 将各工具中找到的约定规则汇总，标注来源（如 `[来源: .cursor/rules/naming.mdc]`）
 
 4. **MCP 服务器配置**（→ `modus/config.yaml` `mcpServers` 字段）
-   - 若 `modus init` CLI 已自动检测并写入 `mcpServers`，则跳过
-   - 否则从 `.claude/settings.json` / `.cursor/mcp.json` 提取，写入 `modus/config.yaml`
+   - 从 `.claude/settings.json` / `.cursor/mcp.json` 提取，写入 `modus/config.yaml`
 
 5. **已有自定义命令**（仅记录，不重复生成）
-   - 列出 `.claude/commands/` 中已有的命令名称
-   - 在 `/modus:init` 完成回报中提示用户这些命令已存在
 
 #### 向用户展示扫描结果
 
 ```
-🔍 扫描已有 AI 工具配置...
+扫描已有 AI 工具配置...
 
 ✓ Claude Code — 找到 3 个文件
     CLAUDE.md（项目指令 + 构建命令）
@@ -164,15 +373,13 @@ ls .codebuddy/skills/modus-biz-* 2>/dev/null
     .cursor/rules/naming.mdc（命名规范）
     .cursor/mcp.json（MCP: tapd）
 
-将把以上规则融入 modus-team-conventions Skill，MCP 配置写入 modus/config.yaml。
-继续？[Y/n]
+将把以上规则融入 modus/knowledge/_conventions/SKILL.md，MCP 配置写入 modus/config.yaml。
+继续？[Y/n]（--force 时自动确认）
 ```
 
-若用户确认，继续 Step 2；若无任何已有配置，直接进入 Step 2。
-
 ---
 
-### Step 2：项目扫描与业务分类（5 轮全量扫描）
+### Step 5：项目扫描与业务分类（5 轮全量扫描）
 
 启动一个「项目分析 SubAgent」，执行以下 **5 轮结构化扫描**（替代原有的简单目录读取）：
 
@@ -344,7 +551,7 @@ scanRules.exclude_patterns（用户配置）
 
 扫描完成 ─────────────────────────────────────────────
 确认域：{N} 个 | 待确认：{M} 个 | 孤立表：{K} 张
-下一步：展示域汇总，等待用户确认
+下一步：展示域汇总，等待用户确认（Step 6）
 ──────────────────────────────────────────────────────
 ```
 
@@ -375,21 +582,21 @@ scanRules.exclude_patterns（用户配置）
 **扫描结果展示（向用户展示）：**
 
 ```
-我识别到以下业务域，请确认：
+我识别到以下业务域，请确认（将生成到 modus/knowledge/）：
 
-1. order（订单域）— 订单创建、状态流转、查询        [置信度: 9/10 ✅]
+1. biz-order（订单域）— 订单创建、状态流转、查询        [置信度: 9/10 ✅]
    关键文件: OrderController, OrderService, OrderMapper, OrderDomain, OrderStatus(Enum)
    独占表: order_main, order_item（共2个）
    
-2. payment（支付域）— 支付发起、回调、退款          [置信度: 8/10 ✅]
+2. biz-payment（支付域）— 支付发起、回调、退款          [置信度: 8/10 ✅]
    关键文件: PayFacade, PayManager, PayRecordMapper, PayStatus(Enum)
    独占表: payment_record（共1个）
    
-3. user（用户域）— 用户注册、登录、权限             [置信度: 5/10 ⚠️ 请确认]
+3. biz-user（用户域）— 用户注册、登录、权限             [置信度: 5/10 ⚠️ 请确认]
    关键文件: UserController, UserService, AuthManager
    ⚠️ 该域未发现独立 Entity 类（得分偏低），请确认是否独立域？
    
-4. diversion（流量分发）— 流量路由                 [置信度: 2/10 ❌ 需要决策]
+4. biz-diversion（流量分发）— 流量路由                 [置信度: 2/10 ❌ 需要决策]
    ❌ 低置信度：仅 2 个业务类，无 Controller/Facade，无独占表
    建议选择：A) 合并至 user 域  B) 合并至 platform 域  C) 保持独立
 
@@ -422,9 +629,9 @@ scanRules.exclude_patterns（用户配置）
 
 ---
 
-### Step 3：用户确认 + 置信度门槛 + 小包评估 + 大域保护
+### Step 6：用户确认 + 置信度门槛 + 小包评估 + 大域保护
 
-等待用户确认域列表之前，先执行以下评估：
+等待用户确认域列表之前，先执行以下评估（`--force` 时自动确认）：
 
 #### 3.0 置信度门槛强制执行
 
@@ -486,9 +693,9 @@ scanRules.exclude_patterns（用户配置）
 
 ---
 
-### Step 4：结构化访谈问卷（隐性知识捕获）
+### Step 7：结构化访谈问卷（隐性知识捕获）
 
-**触发时机：** 用户确认域列表后、Step 5 启动前执行。
+**触发时机：** 用户确认域列表后、Step 8 启动前执行。`--force` 时自动跳过（隐性知识率标为 0%）。
 
 **核心目的：** 代码扫描只能获得「显性结构知识」，此步骤通过动态生成的针对性问题，补全代码中无法推断的**隐性业务知识**（口口相传的规则、历史决策、业务背景）。
 
@@ -551,20 +758,20 @@ scanRules.exclude_patterns（用户配置）
 
 ---
 
-### Step 5：生成业务 Skill（Layer 2）—— 并行执行
+### Step 8：生成业务 Skill（Layer 2）—— 并行执行
 
 用户确认后，**同时**为每个业务域启动独立的「Skills Builder SubAgent」（`modus-skill-creator` Skill，模式 A），并行生成所有业务 Skill 文件。各域之间完全独立，无需等待彼此完成。
 
-**目标路径：** `.codebuddy/skills/modus-biz-{domain}/SKILL.md`
+**目标路径（v3.1）：** `modus/knowledge/biz-{domain}/SKILL.md`
 
 **并行调度规则：**
 
 ```
 用户确认域列表后，立即并行启动 N 个 SubAgent：
 
-SubAgent-1 (order域)   ──► 扫描订单全量文件（含Enum/MQ/Config等全10类）──► 生成 modus-biz-order/SKILL.md
-SubAgent-2 (payment域) ──► 扫描支付全量文件（含Enum/MQ/Config等全10类）──► 生成 modus-biz-payment/SKILL.md
-SubAgent-3 (user域)    ──► 扫描用户全量文件（含Enum/MQ/Config等全10类）──► 生成 modus-biz-user/SKILL.md
+SubAgent-1 (biz-order域)   ──► 扫描订单全量文件（含Enum/MQ/Config等全10类）──► 生成 modus/knowledge/biz-order/SKILL.md
+SubAgent-2 (biz-payment域) ──► 扫描支付全量文件（含Enum/MQ/Config等全10类）──► 生成 modus/knowledge/biz-payment/SKILL.md
+SubAgent-3 (biz-user域)    ──► 扫描用户全量文件（含Enum/MQ/Config等全10类）──► 生成 modus/knowledge/biz-user/SKILL.md
           │                                                                        │
           └──────────────────── 所有 SubAgent 完成 ─────────────────────────────┘
                                            ↓
@@ -575,7 +782,7 @@ SubAgent-3 (user域)    ──► 扫描用户全量文件（含Enum/MQ/Config
 
 **每个 SubAgent 的任务（模式 A 标准流程）：**
 
-1. 接收域名称 + **全量文件路径列表**（来自 Step 2 轮次 2/3 的分析结果，含所有 10 类文件）
+1. 接收域名称 + **全量文件路径列表**（来自 Step 5 轮次 2/3 的分析结果，含所有 10 类文件）
 2. 按优先级分三批扫描（**无文件数量上限，全量覆盖**）：
    - **第一批（核心知识，必须完整扫描）**
      - ① Controller/Facade → API 契约、权限注解
@@ -605,7 +812,7 @@ SubAgent-3 (user域)    ──► 扫描用户全量文件（含Enum/MQ/Config
   → 在 Skill 末尾标注：「[两段合并扫描: 批次A={N}个 + 批次B={M}个，共 {N+M} 个文件]」
 
 当两段都超限时（超大域 > 200 个文件）：
-  → 按域内子包进一步拆分（如 order-core / order-query / order-settle）
+  → 按域内子包进一步拆分（如 biz-order-core / biz-order-query / biz-order-settle）
   → 提示用户是否手动拆分为多个子域，或接受分段扫描
 ```
 
@@ -618,24 +825,24 @@ SubAgent-3 (user域)    ──► 扫描用户全量文件（含Enum/MQ/Config
 **Section 10 跨域依赖回写（所有 SubAgent 完成后，主流程执行）：**
 
 所有并行 SubAgent 完成后，主流程统一执行一轮跨域依赖分析：
-1. 汇总 Step 2 轮次 4 的跨域依赖关系图
+1. 汇总 Step 5 轮次 4 的跨域依赖关系图
 2. 对每个域 Skill 的 Section 10 进行回写，填入上游依赖域和下游被依赖域
 3. 同步更新各 Skill frontmatter 的 `upstream_skills` 和 `downstream_skills` 字段
-4. 执行 upstream/downstream 双向同步（详见 `modus-skill-creator`（SubAgent 00）Step 4 扩展算法）
+4. 执行 upstream/downstream 双向同步（详见 `modus-skill-creator`（SubAgent 00）Step 7 扩展算法）
 
-**聚合等待：** 所有 SubAgent 完成后，收集各 SubAgent 的完成状态摘要，在主流程中汇总展示：
+**聚合等待：**
 
 ```
-✓ modus-biz-order   已生成（v3/17节，18个key_files，6条业务规则，5个API，状态机含4个状态）
-✓ modus-biz-payment 已生成（v3/17节，12个key_files，5条业务规则，3个API，⚠️ 共87个文件，已覆盖50个）
-✓ modus-biz-user    已生成（v3/17节，10个key_files，4条业务规则，6个API）
+✓ modus/knowledge/biz-order   已生成（v3/17节，18个key_files，6条业务规则，5个API，状态机含4个状态）
+✓ modus/knowledge/biz-payment 已生成（v3/17节，12个key_files，5条业务规则，3个API，⚠️ 共87个文件，已覆盖50个）
+✓ modus/knowledge/biz-user    已生成（v3/17节，10个key_files，4条业务规则，6个API）
 
 跨域依赖 Section 10 回写完成：
-  order.upstream_skills   = [payment, user]
-  payment.downstream_skills = [order, refund]
+  biz-order.upstream_skills   = [biz-payment, biz-user]
+  biz-payment.downstream_skills = [biz-order, biz-refund]
 ```
 
-### Step 5 补充：生成 Business Skill 时必须填写完整 frontmatter（防腐机制核心）
+### Step 8 补充：生成 Business Skill 时必须填写完整 frontmatter（防腐机制核心）
 
 在生成每个业务 Skill（`.codebuddy/skills/modus-biz-{domain}/SKILL.md`）时，**必须**在 frontmatter 中填写以下**完整字段清单**。这些字段是知识防腐机制的核心，缺一不可：
 
@@ -675,10 +882,10 @@ SubAgent-3 (user域)    ──► 扫描用户全量文件（含Enum/MQ/Config
 - 确保 Enum/MQ/ErrorCode/Config 的变化能被 hash 检查感知
 
 #### 四、质量评分字段（必填，用于知识库质量报告）
-- **`domain_confidence`**: 本域的置信度评分（0-10），来自 Step 2 置信度评分矩阵
+- **`domain_confidence`**: 本域的置信度评分（0-10），来自 Step 5 置信度评分矩阵
 - **`invariant_count`**: 生成的业务不变量条目数（Section 15）
 - **`glossary_size`**: 领域词汇表条目数（Section 16）
-- **`hidden_knowledge_rate`**: 隐性知识补全率（0-100，来自 Step 4 访谈问卷）
+- **`hidden_knowledge_rate`**: 隐性知识补全率（0-100，来自 Step 7 访谈问卷）
 - **`contract_version`**: 本域对外暴露接口的当前版本（初始 "1.0"）；接口升级时更新，下游调用域在自己的 Section 10 中记录此版本号
 
 #### 五、跨域依赖字段（由 Section 10 回写阶段自动填入）
@@ -711,29 +918,40 @@ SubAgent-3 (user域)    ──► 扫描用户全量文件（含Enum/MQ/Config
 
 ---
 
-### Step 6：多平台同步（Business Skills）
+### Step 9：多平台同步（Business Skills）
 
-Business Skills 全部生成后，读取 `modus/config.yaml` 的 `platforms` 字段，将每个业务 Skill 同步到其他已选平台。
+Business Skills（Step 8）全部生成后，读取 `modus/config.yaml` 的 `platforms` 字段（若带 `--no-sync` 则跳过此 Step）。
 
-**读取 platforms 配置：**
+**核心设计原则：引用式适配（Reference over Copy）**
 
-```bash
-# 检查已选平台（支持 Bash 的平台）
-grep -A5 "^platforms:" modus/config.yaml
-```
+`modus/knowledge/` 是 Single Source of Truth。各平台适配文件**不复制内容**，只写引用说明。
 
-> **Cursor 平台替代**（无 Bash）：使用 Read 工具读取 `modus/config.yaml` 完整内容，解析其中的 `platforms:` 列表。
+> **读取 platforms 配置**：使用 Read 工具读取 `modus/config.yaml` 完整内容，解析其中的 `platforms:` 列表。（Bash 环境也可用 `grep -A5 "^platforms:" modus/config.yaml`）
 
 **各平台同步规则（仅处理 codebuddy 以外的平台）：**
 
-#### Claude Code（`.claude/agents/modus-biz-{domain}.md`）
+#### Claude Code（更新 `CLAUDE.md` + 创建 `.claude/agents/modus-biz-{domain}.md`）
+
+更新 `CLAUDE.md` 的 Modus 章节（若存在则更新，否则追加）：
+
+```markdown
+## Modus 知识库（AI 编码加速框架）v3.1
+
+执行任何涉及业务逻辑的任务时：
+
+1. 先读取 `modus/knowledge-catalog.md` 或 `modus/workspace-catalog.md`（多项目）
+2. 按需加载 `{project}/modus/knowledge/biz-*/SKILL.md` 获取完整业务上下文
+3. **知识库统一在 modus/knowledge/，不要去 .codebuddy/skills/modus-biz-* 读取（已是引用桩）**
+
+可用命令：/modus:init | /modus:vibe | /modus:plan | /modus:spec | /modus:harness | /modus:auto
+```
 
 对每个业务域，创建 Claude Sub-Agent 定义文件（包含 `<!-- modus:meta -->` 机器可读注释）：
 
 ```markdown
 ---
 name: modus-biz-{domain}
-description: Business knowledge for the {domain} domain — {核心职责一句话}
+description: "[MODUS:BIZ] {中文域名}业务知识。完整知识在 {project}/modus/knowledge/biz-{domain}/SKILL.md"
 ---
 <!-- modus:meta
 last_hash: "{从 CodeBuddy 主文件读取的 last_hash 值}"
@@ -741,181 +959,168 @@ status: "{从 CodeBuddy 主文件读取的 status 值}"
 updated: "{从 CodeBuddy 主文件读取的 updated 日期}"
 -->
 
-{.codebuddy/skills/modus-biz-{domain}/SKILL.md 的完整内容}
+<!-- MODUS_REF: {project}/modus/knowledge/biz-{domain}/SKILL.md -->
+**域：** {中文域名} | **成熟度：** {maturity} | **更新：** {date}
+> 完整知识见：`{project}/modus/knowledge/biz-{domain}/SKILL.md`
 ```
 
 > 注意：`<!-- modus:meta -->` 注释供工具层快速读取核心防腐字段，每次同步时自动从 CodeBuddy 主文件更新，禁止手动修改。
 
-#### Cursor（`.cursor/rules/modus-biz-{domain}.mdc`）
-
-对每个业务域，创建 Cursor 规则文件（带 frontmatter）：
+#### Cursor（更新/创建 `.cursor/rules/modus-knowledge.mdc`）
 
 ```markdown
 ---
-description: "Business rules and conventions for the {domain} domain — {核心职责一句话}"
+description: "[MODUS] 知识库引用规则 — 所有业务知识在 modus/knowledge/"
 alwaysApply: false
 ---
 
-{.codebuddy/skills/modus-biz-{domain}/SKILL.md 的完整内容}
+<!-- MODUS v3.1 知识库路径 -->
+业务知识（Single Source of Truth）：`{project}/modus/knowledge/biz-*/SKILL.md`
+团队约定：`{project}/modus/knowledge/_conventions/SKILL.md`
+技术知识：`{project}/modus/knowledge/_tech-wiki/SKILL.md`
+加载入口：`{project}/modus/knowledge-catalog.md`（~200 tokens）
 ```
 
-#### GitHub Copilot（`.github/copilot-instructions.md`）
+#### OpenAI Codex / OpenCode（`AGENTS.md`）
 
-将每个业务域的 Skill 内容以带标记的段落形式追加或更新（幂等）：
+`AGENTS.md` 由 `modus init` CLI 自动生成和维护（codex 平台），此步骤无需手动写入。
+如需更新业务域引用，调用 `syncBizSkillToCodex` 在 `AGENTS.md` 的业务域索引章节追加条目即可。
 
-```markdown
-<!-- modus:biz-skill:{domain}:start -->
+#### GitHub Copilot（更新 `.github/copilot-instructions.md`）
 
-### Business Skill: {domain}
+在文件中追加/更新 modus 知识库引用段落（幂等，带标记防止重复）。
 
-{.codebuddy/skills/modus-biz-{domain}/SKILL.md 的完整内容}
+#### CodeBuddy（创建引用桩）
 
-<!-- modus:biz-skill:{domain}:end -->
-```
+为每个业务域在 `.codebuddy/skills/modus-biz-{domain}/` 下创建引用桩 SKILL.md（内容见 Step M-4 格式）。
 
-**若文件中已存在对应域的标记段落，替换其内容（不重复追加）。**
+#### 自定义平台（持续同步）
 
-**同步完成输出：**
+扫描 `modus/platforms/*/platform.yaml`，对 `bizSkill.enabled=true` 的自定义平台：
 
 ```
-📡 多平台同步：
-✓ Claude   .claude/agents/modus-biz-order.md
-✓ Claude   .claude/agents/modus-biz-payment.md
-✓ Cursor   .cursor/rules/modus-biz-order.mdc
-✓ Cursor   .cursor/rules/modus-biz-payment.mdc
-✓ Copilot  .github/copilot-instructions.md（已更新 2 个域段落）
+对每个自定义平台 {platformName}：
+  outputPath = platform.yaml 中 bizSkill.outputPath 模板（替换 {domain}、{ext}）
+  body       = platform.yaml 中 bizSkill.wrapper 模板（替换 {domain}、{content}）
+             若 wrapper 未定义，直接写入 Skill 原文
+  写入 outputPath，确保父目录存在
+
+输出：[已同步 {domain} 到自定义平台: {platform1}, {platform2}]
+若无自定义平台：静默跳过
 ```
 
-若 `platforms` 只包含 `codebuddy`（或字段不存在），跳过此步骤。
+> 这一步解决了 `/modus:platform -add` 后的**持续同步痛点**：每次更新业务域知识时，
+> 所有已注册的自定义平台目录都会被自动同步，无需用户手动干预。
 
 ---
 
-### Step 7：生成团队约定 Skill（Layer 0-T）
+### Step 10：生成团队约定 Skill（Layer 0-T）
 
-调用「Skills Builder SubAgent」（模式 E：团队约定初始化）：
+**目标路径（v3.1）：** `modus/knowledge/_conventions/SKILL.md`
 
 从以下来源提取团队规范（**按优先级排列**）：
 
-1. **Step 1 扫描结果**（最高优先级）
-   - 从 `CLAUDE.md` / `AGENTS.md` / `.cursor/rules/` / `.codebuddy/rules/` 提取的编码规范
-   - 每条规则注明来源，例如：`[来源: .cursor/rules/naming.mdc]`
-   - 若同一规则在多个工具中重复，合并为一条并列出所有来源
-
-2. 项目中已有的 `CONTRIBUTING.md`、`.editorconfig`、`checkstyle.xml`、`pmd.xml` 等规范文件
-
+1. **Step 4 扫描结果**（最高优先级）— 各工具中找到的编码规范
+2. 项目中已有的 `CONTRIBUTING.md`、`.editorconfig`、`checkstyle.xml` 等规范文件
 3. `modus/config.yaml` 中的 `constitution.hard_rules`
+4. 代码中高频出现的注解模式
 
-4. 代码中高频出现的注解模式（如 `@Transactional`、`@DistributedLock` 的用法）
-
-生成文件：`.codebuddy/skills/modus-team-conventions/SKILL.md`
-
-**注意：** 若 Step 1 中已有来自其他工具的规则，在 Skill 文件开头添加来源声明：
-```markdown
-> 本 Skill 融合了以下 AI 工具的已有配置：Claude Code (CLAUDE.md)、Cursor (.cursor/rules/)
-> 原始文件保持不变，Modus 仅在此处做统一索引。
-```
+---
 
-### Step 8：生成技术知识 Skill（Layer 1）
 
-调用「Skills Builder SubAgent」（模式 E：技术知识初始化），初始化技术知识骨架：
+### Step 11：生成技术知识 Skill（Layer 1）
 
-生成文件：`.codebuddy/skills/modus-tech-wiki/SKILL.md`
+**目标路径（v3.1）：** `modus/knowledge/_tech-wiki/SKILL.md`
 
 初始内容来源（按优先级）：
-1. **Step 1 扫描结果中的技术信息**
-   - `CLAUDE.md` 中记录的构建命令、测试命令（如 `mvn test`、`npm run test`）
-   - `.continue/config.json` 中的模型/上下文提供者配置
-2. 从构建文件提取的技术栈（`pom.xml` → Spring Boot 版本、`package.json` → 框架版本等）
-3. 占位符章节（反模式库、架构决策、跨项目经验——待后续工作流积累）
+1. Step 4 扫描结果中的技术信息
+2. 从构建文件提取的技术栈（`pom.xml` → Spring Boot 版本等）
+3. 占位符章节（反模式库、架构决策——待后续工作流积累）
+
+---
 
-### Step 9：生成知识全景目录（knowledge-catalog.md）
+### Step 12：生成知识全景目录（knowledge-catalog.md）
 
-在 `modus/knowledge-catalog.md` 创建全景索引。
+在 `modus/knowledge-catalog.md`（项目级）创建全景索引。
 
 > **单一真相来源**：目录结构、层级定义、字段格式以 `modus/templates/knowledge-catalog.md` 模板文件为准，本 Step 不再内嵌重复结构。执行时读取该模板文件并按以下规则替换占位符后写入目标路径。
 
+**路径说明（v3.1 格式）：**
+- Layer 0-T 路径：`{project}/modus/knowledge/_conventions/SKILL.md`
+- Layer 1 路径：`{project}/modus/knowledge/_tech-wiki/SKILL.md`
+- Layer 2 路径：`{project}/modus/knowledge/biz-{domain}/SKILL.md`
+
 **操作步骤：**
 1. 读取 `{MODUS_PACKAGE}/templates/knowledge-catalog.md`（安装包模板）
-2. 将 Layer 2 的 `{domain}` 条目替换为 Step 2/3/4 扫描到的实际业务域列表，每域一行
+2. 将 Layer 2 的 `{domain}` 条目替换为 Step 5/6/7 扫描到的实际业务域列表，每域一行
 3. 完成以下占位符替换：
 
 **写入前必须完成的字段替换（断言，不可遗漏）：**
 - `{YYYY-MM-DD}` → 实际执行日期（如 `2026-05-06`）
 - `{日期}` → 实际执行日期
-- `{domain}` → 扫描到的实际域名（如 `order`、`payment`、`user`）；每个域生成独立条目
+- `{domain}` → 扫描到的实际域名（如 `biz-order`、`biz-payment`、`biz-user`）；每个域生成独立条目
 - `{中文域名}` → 对应域的中文名称（如 `订单`、`支付`、`用户`）
 - `{核心职责一句话}` → 对应域的简短职责描述
-- `{依赖域列表，无则写-}` → upstream_skills 依赖关系（Step 2 扫描结果）
+- `{依赖域列表，无则写-}` → upstream_skills 依赖关系（Step 5 扫描结果）
 - `{last_hash 前8位}` → 运行 hash 计算后的实际值前 8 位；若无法计算，写入 `⚠️ PENDING` 并在知识目录顶部说明原因
-- `{待填入}` → 域依赖图（从 upstream 字段推导：payment --> order, user 等）
+- `{待填入}` → 域依赖图（从 upstream 字段推导：biz-payment --> biz-order 等）
 - 写入后执行自检：`grep -n '{' modus/knowledge-catalog.md | grep -v '<!--'` 输出应为空（注释中的占位符示例不算）
 
-### Step 10：初始化 modus/config.yaml（若不存在）
-
-若项目尚无 `modus/config.yaml`，生成默认配置：
-
-```yaml
-# Modus 项目配置
+同时更新工作区顶层的 `modus/workspace-catalog.md`（若存在）中的项目更新时间。
 
-# TAPD 项目 ID（可选，用于 Harness 自动创建 Bug 单）
-tapdProjectId: ""
+---
 
-# Harness 流程配置
-harness:
-  buildCommand: "mvn clean compile -q"
-  environments: [dev, test, pre]
+### Step 13：初始化 modus/config.yaml（若不存在）
 
-# 项目宪法（所有 SubAgent 必须遵守的硬性约束）
-# 这些约束在每次命令执行时自动加载，无需重复说明
-constitution:
-  tech_stack: ""              # 如 "Java 17 + Spring Boot 3 + MyBatis"
-  test_command: ""            # 如 "mvn test -pl {module}"
-  hard_rules: []              # 如 ["Mapper 接口必须在 dao 包下", "金额使用 Long 单位分"]
-  build_command: ""           # 如 "mvn clean compile -q"
-  key_patterns: []            # 项目特有的技术模式描述
-```
+若项目尚无 `modus/config.yaml`，生成默认配置（参见模板），提示用户填写 `constitution` 字段。
 
-提示用户填写 `constitution` 字段，以便后续命令无需重复说明项目约束。
+---
 
-### Step 11：完成回报
+### Step 14：完成回报
 
-所有业务 Skill 生成完毕后，回复用户：
+所有文件生成完毕后，回复用户：
 
 ```
-✅ Modus 知识库初始化完成
+✅ Modus 知识库初始化完成（v3.2）
+
+知识库路径（Single Source of Truth）：
+  modus/knowledge/_conventions/SKILL.md  (Layer 0-T) [draft]
+  modus/knowledge/_tech-wiki/SKILL.md    (Layer 1)   [draft]
+  modus/knowledge/biz-*/SKILL.md         (Layer 2)   [draft] × N 个域
 
 已融合的已有 AI 工具配置（若有）：
-  Claude Code  — CLAUDE.md + .claude/rules/ (3 条规则已写入 modus-team-conventions)
-  Cursor       — .cursor/rules/ (2 条规则已写入 modus-team-conventions)
-  MCP 服务器   — tapd (来自 .claude/settings.json) 已写入 modus/config.yaml
+  Claude Code  — CLAUDE.md + .claude/rules/ (M 条规则融入 _conventions)
+  Cursor       — .cursor/rules/ (K 条规则融入 _conventions)
 
 生成了 N 个业务 Skill（Layer 2）：
-- .codebuddy/skills/modus-biz-order/SKILL.md    [draft] [v3/17节]
-- .codebuddy/skills/modus-biz-payment/SKILL.md  [draft] [v3/17节]
+- modus/knowledge/biz-order/SKILL.md    [draft] [v3/17节]
+- modus/knowledge/biz-payment/SKILL.md  [draft] [v3/17节]
 - ...
 
-多平台同步（来自 modus/config.yaml platforms 配置）：
-- Claude Code  → .claude/agents/modus-biz-*.md（N 个域）
-- Cursor       → .cursor/rules/modus-biz-*.mdc（N 个域）
-- Copilot      → .github/copilot-instructions.md（N 个域段落）
+多平台同步（引用式适配，来自 modus/config.yaml platforms 配置）：
+  Claude   → CLAUDE.md 更新 + .claude/agents/modus-biz-*.md（N 个）
+  Cursor   → .cursor/rules/modus-knowledge.mdc（路径引用）
+  Codex    → AGENTS.md（由 modus init CLI 生成，此处追加业务域索引条目）
+  Copilot  → .github/copilot-instructions.md（N 个域段落）
+  CodeBuddy → .codebuddy/skills/modus-biz-*/SKILL.md（N 个引用桩）
 
 初始化基础 Skill：
-- .codebuddy/skills/modus-team-conventions/SKILL.md  (Layer 0-T) [draft]
-  └─ 融合来源：CLAUDE.md, .cursor/rules/, CONTRIBUTING.md, 代码注解模式
-- .codebuddy/skills/modus-tech-wiki/SKILL.md          (Layer 1)   [draft]
+  modus/knowledge/_conventions/SKILL.md  (Layer 0-T) [draft]
+    └─ 融合来源：CLAUDE.md, .cursor/rules/, CONTRIBUTING.md, 代码注解模式
+  modus/knowledge/_tech-wiki/SKILL.md    (Layer 1)   [draft]
 
 知识目录：
-- modus/knowledge-catalog.md（所有命令的快速索引，~200 tokens）
+  modus/knowledge-catalog.md（所有命令的快速索引，~200 tokens）
 
 📊 知识库质量评分报告：
 ┌─────────────────┬──────┬──────┬──────┬──────┬──────┬──────────┐
 │ 域名            │置信度│规则数│状态机│API完备│不变量│隐性知识率│
 ├─────────────────┼──────┼──────┼──────┼──────┼──────┼──────────┤
-│ modus-biz-order │ 9/10 │  8条 │ 100% │ 100% │  3条 │   80%    │
-│ modus-biz-payment│ 8/10 │  5条 │ 100% │  80% │  2条 │   60%    │
-│ modus-biz-user  │ 5/10 │  4条 │  -   │  90% │  1条 │   40% ⚠️ │
+│ biz-order       │ 9/10 │  8条 │ 100% │ 100% │  3条 │   80%    │
+│ biz-payment     │ 8/10 │  5条 │ 100% │  80% │  2条 │   60%    │
+│ biz-user        │ 5/10 │  4条 │  -   │  90% │  1条 │   40% ⚠️ │
 └─────────────────┴──────┴──────┴──────┴──────┴──────┴──────────┘
-⚠️ modus-biz-user 隐性知识补全率 40%（低于 60% 阈值），建议补充访谈。
+⚠️ biz-user 隐性知识补全率 40%（低于 60% 阈值），建议补充访谈。
 
 💡 建议：填写 modus/config.yaml 中的 constitution 字段，
    记录项目硬性约束（技术栈、命名规范等），后续所有命令将自动加载。
@@ -925,9 +1130,10 @@ constitution:
 
 现在可以使用：
   /modus:vibe     — 氛围编程（自动加载业务上下文）
-  /modus:plan     — 功能规划
+  /modus:plan     — 功能规划（可带 --story <tapd-url>）
   /modus:spec     — 规范驱动开发
-  /modus:harness  — 全自动 Harness 流程
+  /modus:harness [tapd-url] — 全自动 Harness 流程
+  /modus:auto [tapd-url]    — 智能推荐模式
   /modus:verify   — 升级 Skill 状态（draft → verified）
 ```
 
@@ -940,6 +1146,15 @@ constitution:
 
 > 本章节是防腐机制的**唯一权威来源**。`knowledge-catalog.md`、`modus-init-flow.md` 等其他文档如有冲突，以本章节为准。
 
+**重新初始化逻辑（已有 Skill 时）：**
+
+如果 `modus/knowledge/biz-*` 下已存在业务 Skill：
+
+1. 展示已有域列表及 status、最后更新时间
+2. 询问：全量重建 / 仅更新指定域（`--enhance`）/ 新增缺失域
+3. 按用户选择执行（`--force` 时默认选择「仅新增缺失域」）
+4. 无论何种选择，都更新 `modus/knowledge-catalog.md` 的时间戳
+
 ### 防腐机制全链路图
 
 ```mermaid
@@ -1127,12 +1342,12 @@ name: modus-biz-{domain}
 
 | 文件 | 角色 | 防腐字段权威性 | 更新方式 |
 |------|------|-------------|---------|
-| `.codebuddy/skills/modus-biz-{domain}/SKILL.md` | **权威源** | 所有防腐字段的唯一权威存储 | 命令直接写入 |
+| `modus/knowledge/biz-{domain}/SKILL.md` | **权威源** | 所有防腐字段的唯一权威存储 | 命令直接写入 |
 | `.claude/agents/modus-biz-{domain}.md` | 只读快照 | 仅通过 `<!-- modus:meta -->` 注释暴露核心字段 | Step 6 同步时自动更新 |
-| `.cursor/rules/modus-biz-{domain}.mdc` | 只读快照 | 不存储防腐字段（仅业务上下文） | Step 6 同步时自动更新 |
+| `.cursor/rules/modus-knowledge.mdc` | 只读快照 | 不存储防腐字段（仅路径引用） | Step 6 同步时自动更新 |
 
 **关键原则**：
-- 所有防腐机制的触发（hash 比对、衰减计算、`usage_count` 更新）**均只操作 CodeBuddy 权威源文件**
+- 所有防腐机制的触发（hash 比对、衰减计算、`usage_count` 更新）**均只操作 `modus/knowledge/` 权威源文件**
 - 副本文件发生变更不触发防腐机制，不影响 status
 - 若副本与权威源不一致（如手动修改副本），以权威源为准，下次 Step 6 同步时强制覆盖
 
@@ -1141,7 +1356,7 @@ name: modus-biz-{domain}
 <!-- 区块 C：Business Skill 标准格式参考（执行 Step 5 时按需读取）-->
 <!-- ============================================================ -->
 
-## Business Skill 标准格式参考（v3/17节）
+## Business Skill 标准格式参考（v3.1 / 17节）
 
 ### 多语言适配说明
 
@@ -1162,7 +1377,7 @@ name: modus-biz-{domain}
 
 ```markdown
 ---
-name: modus-biz-{domain}
+name: biz-{domain}
 description: "[MODUS:BIZ] {中文域名}业务知识 — {核心职责一句话}"
 version: 1.0.0
 updated: {YYYY-MM-DD}
@@ -1180,15 +1395,15 @@ glossary_size: 0            # Section 16 领域词汇表条目数
 hidden_knowledge_rate: 0    # 隐性知识补全率（0-100），来自 Step 4 访谈问卷
 contract_version: "1.0"     # 本域对外暴露接口的当前版本；升级接口时同步更新，下游调用域在 Section 10 中记录此版本
 upstream_skills:            # 本 Skill 在 Section 10 中依赖的其他域 Skill
-  - modus-biz-payment
-  - modus-biz-user
+  - biz-payment
+  - biz-user
 downstream_skills:          # 依赖本域的其他 Skill（被依赖方）
-  - modus-biz-refund
+  - biz-refund
 key_files:                  # 关键源文件列表，用于 hash 检查（最多 20 个，覆盖全 10 类文件）
   # 优先级 1：核心业务逻辑（必选）
   - src/.../service/{Domain}Service.java
   - src/.../manager/{Domain}Manager.java
-  - src/.../dao/{Domain}Mapper.java
+  - src/.../dao/{Domain}CustomMapper.java
   - src/.../domain/{Domain}.java
   # 优先级 2：状态与规则（强烈建议）
   - src/.../enums/{Domain}Status.java
@@ -1604,7 +1819,7 @@ Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、J
    - draft(fresh)：usage_count = 0（Skill 刚生成，尚未用于真实任务）
    - draft(used) ：usage_count ≥ 1（已用于至少一次开发，有反馈基础）
 
-1. 读取 .codebuddy/skills/{skill-name}/SKILL.md 的 frontmatter
+1. 读取 modus/knowledge/biz-{domain}/SKILL.md 的 frontmatter（v3.2 Single Source of Truth）
 
 2. 运行质量自检清单：
    □ Section 3：每个 Entity 字段均有业务含义注释？
@@ -1663,7 +1878,7 @@ Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、J
 **执行逻辑：**
 
 ```
-1. 读取 .codebuddy/skills/modus-biz-{domain}/SKILL.md 的 frontmatter：
+1. 读取 modus/knowledge/biz-{domain}/SKILL.md 的 frontmatter（v3.2 Single Source of Truth）：
    - key_files 列表
    - last_hash（上次生成时的 SHA-1 值）
    - status（若已为 archived，询问用户是否继续）