@modus-ai/modus 0.1.0 → 0.1.2

package/templates/skills/modus-harness-agents/00-skills-builder/SKILL.md

@@ -1,3 +1,10 @@
+---
+name: modus-harness-00-skills-builder
+description: Use this skill when building, updating, or extracting knowledge to/from Business Skill files. Called by /modus:init (Mode A: new), /modus:plan and /modus:spec pre/post update (Mode B/C), Harness ARCHIVE phase (Mode D), and baseline Skill initialization (Mode E). Trigger when any Modus workflow needs to create or refresh .codebuddy/skills/modus-biz-*/SKILL.md or knowledge-catalog.md.
+allowed-tools: Read, Write, Glob, Bash
+disable: false
+---
+
 # modus-harness-00-skills-builder（Skills Builder SubAgent）
 
 **调用方：** `/modus:init` / `/modus:plan` 前置更新 / `/modus:spec` 前置更新 / Harness 后置更新 / Harness ARCHIVE 阶段  
@@ -16,10 +23,31 @@
 
 为每个确认的业务域从零生成 `modus-biz-{domain}/SKILL.md`，初始 maturity 为 `draft`。
 
-### 模式 B：增量更新（来自 /plan 或 /spec 前置）
+### 模式 B：增量更新（来自 /plan 或 /spec 前置，含 hash 快速检查）
+
+更新已有 `modus-biz-*/SKILL.md`，刷新过时内容，补充新发现的知识。
+
+**执行前必须先进行 hash 检查，避免不必要的全量扫描：**
+
+#### 模式 B — Step 0：hash 检查（每个域独立检查）
 
-更新已有 `modus-biz-*/SKILL.md`，刷新过时内容，补充新发现的知识。  
-对比现有 Skill 内容与最新代码，**仅修改有变化的部分**，保留无变化的内容。
+1. 读取 SKILL.md frontmatter 的 `last_hash` 和 `key_files`
+2. 使用 Bash 计算当前 `key_files` 内容的 SHA-1 摘要：
+
+   ```bash
+   shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
+   ```
+
+3. 对比结果：
+   - **hash 一致（且 last_hash 非空）** → 跳过全量扫描，仅更新 `last_referenced` 字段，输出：  
+     `✓ modus-biz-{domain} 无变化（hash 匹配），跳过更新（节省 ~2000 tokens）`
+   - **hash 不一致 或 last_hash 为空** → 执行下方完整流程
+   - **key_files 为空 或 某文件不存在** → 视为「已变化」，执行完整流程
+
+#### 模式 B — 完整更新流程（仅 hash 不匹配时执行）
+
+对比现有 Skill 内容与最新代码，**仅修改有变化的部分**，保留无变化的内容。  
+更新完成后，**必须**将新 hash 写入 frontmatter 的 `last_hash` 字段。
 
 ### 模式 C：后置回写（来自 /plan、/spec 归档后）
 
@@ -48,6 +76,14 @@
 - 本次工作流成功验证了某条知识 → `draft` 升为 `verified`，更新 `last_referenced` 和 `usage_count +1`
 - 若该知识已是 `verified` 且跨不同工作流被引用 ≥2 次 → 升为 `proven`
 
+**hash 更新（ARCHIVE 阶段必做）：**
+- 对每个在本次 Harness 中被修改的业务 Skill（modus-biz-*），在写入知识后**重新计算 hash**：
+  ```bash
+  shasum -a 1 {key_files...} | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
+  ```
+- 将新 hash 写入 SKILL.md frontmatter 的 `last_hash` 字段
+- 这确保下次 plan/spec 前置检查时，能正确跳过未变化的 Skill
+
 **衰减检查（每次模式 D 执行时顺带检查）：**
 - 扫描 catalog，检查 `last_referenced` 超过阈值的条目
 - `proven` + 超过 12 个月未引用 → 降为 `verified`，追加注释 `⚠️ 12个月未引用，请验证是否仍然适用`
@@ -97,17 +133,49 @@
 - API 契约（从 Controller/Facade 提炼）：接口路径、关键请求/响应字段
 - 典型代码示例（可选，高价值）：体现项目特有模式的代码片段
 
-### Step 3：写入 Skill 文件
+### Step 3：并发冲突检测（写入前必做）
+
+多人协作时，同一个 Skill 可能被并发更新。写入前先检查：
+
+1. **读取 Skill 文件头部的 `version` 和 `updated` 字段**
+2. **对比当前内容与本次要写入的内容**，判断是否有冲突风险：
+
+```
+冲突场景：
+- 你在准备写入 modus-biz-order v2.0.0
+- 但文件当前已经是 v2.0.0（说明有人已经抢先更新了）
+```
+
+**冲突处理策略（merge-friendly，保证 Git 无冲突）：**
+
+- **新增知识** → 只往文件末尾 **追加**（append），不修改已有行
+  ```markdown
+  ## 更新日志
+
+  ### {YYYY-MM-DD HH:mm} v{N+1} — {更新者描述}
+  - [model] 新增 OrderStatus.PENDING_REVIEW 枚举值
+  - [pitfall] 批量操作超过 500 条会触发慢查询
+  ```
+- **修改已有知识** → 在对应条目后追加 `(已更新: {YYYY-MM-DD})` 注释，不直接覆盖原行
+- **删除过时知识** → 不物理删除，改为在条目前加 `~~` 删除线标记并注明原因
+
+**为什么这样设计：**
+- Git merge 时，append-only 的文件几乎不会产生冲突
+- 保留了变更历史，方便溯源
+- 团队成员可以看到知识演进过程
+
+### Step 4：写入 Skill 文件
 
 按 Business Skill 标准格式生成或更新文件：
 
 **更新策略（模式 B/C/D）：**
 - 对比现有 Skill 内容和最新信息，识别差异
-- 仅修改有变化的部分，保留无变化的内容
+- **新增内容追加到文件末尾**，修改内容以注释方式标注（见 Step 3）
 - 更新文件头的 `updated` 日期、`version`（自增）、`last_referenced`、`usage_count`
+- **模式 B/D 完整更新后**：重新计算 `key_files` 内容的 SHA-1 并写入 `last_hash`（模式 C 后置回写不更新 hash，因为它是从产出物提取知识而非扫描代码）
 - 在文件末尾追加「本次更新摘要」注释
 
-### Step 4：更新 knowledge-catalog.md
+### Step 5：更新 knowledge-catalog.md
 
 每次写入 Skill 后，同步更新 `modus/knowledge-catalog.md`：
 - 更新对应条目的 `maturity`、`last_referenced`
@@ -129,6 +197,12 @@ updated: {YYYY-MM-DD}
 maturity: draft             # draft | verified | proven
 last_referenced: {YYYY-MM-DD}
 usage_count: 0
+last_hash: ""               # SHA-1(key_files 内容)，模式 B/D 更新后自动计算并填入
+key_files:                  # 关键源文件列表，用于 hash 快速检查（最多 10 个）
+  - src/.../service/{Domain}Service.java
+  - src/.../manager/{Domain}Manager.java
+  - src/.../dao/{Domain}Mapper.java
+  - src/.../domain/{Domain}.java
 ---
 
 # {中文域名}业务知识

package/templates/skills/modus-harness-agents/01-5-design/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: modus-harness-01-5-design
+description: Use this skill when the Harness orchestrator needs to generate a design-brief between requirements analysis (01-analysis.md) and code development (02-dev). Reads 01-analysis.md and business Skills, asks architecture clarification questions, and produces 01.5-design-brief.md with HANDOFF block. Triggered automatically by modus-harness after SubAgent 01 completes.
+allowed-tools: Read, Write, Glob
+disable: false
+---
+
+# modus-harness-01-5-design（设计方案 SubAgent）
+
+**调用方：** Harness Orchestrator（`modus-harness`）  
+**输入：** `modus/plans/active/{story-id}/01-analysis.md` + 相关业务 Skill + constitution  
+**产出物：** `modus/plans/active/{story-id}/01.5-design-brief.md`
+
+## 职责
+
+承接 SubAgent 01 的需求分析结果，在代码开发开始之前生成结构化设计方案，将 Sprint 执行计划翻译为精确到类名/方法名级别的实现蓝图，作为 SubAgent 02 的核心输入。
+
+---
+
+## 执行流程
+
+### Step 1：读取需求分析结果
+
+1. 读取 `modus/plans/active/{story-id}/01-analysis.md`
+   - 解析 HANDOFF 块，提取 `domains`、`risk_level`、`key_constraints`
+   - 读取 Sprint 执行计划（各 Sprint 的任务拆分）
+   - 读取验收标准（Scenario 列表）
+   - 读取风险点（事务、并发、性能、安全）
+
+2. 读取 Orchestrator 传入的业务 Skill 内容（已在 Step 1 INIT 阶段加载）
+3. 读取 `modus/config.yaml` 的 `constitution` 字段
+
+### Step 2：澄清架构决策 ⏸️ 【人工交互节点】
+
+基于需求分析内容，识别并提出 1-3 个关键架构决策问题。
+
+**提问原则：**
+- 只问会影响 SubAgent 02 代码结构的决策（接口、模型、事务边界）
+- 若业务 Skill 中已有 `[decision]` 覆盖相关决策，跳过，直接引用
+- `risk_level: high` 时必须包含并发/事务相关决策确认
+- 已在 `key_constraints` 中明确的不再询问
+
+**示例问题格式：**
+```
+Story {id} 需求分析已完成。在生成设计方案前，需确认几个架构决策：
+
+1. [数据模型] {具体问题，如「审批记录是新建 approval_record 表，还是扩展 order 表字段？」}
+   （影响：DDL 设计和 Mapper 层实现）
+
+2. [接口方式] {具体问题，如「批量操作是同步返回结果，还是异步 MQ 通知？」}
+   （影响：API 合同和事务边界）
+
+3. [风险处理] ⚠️ 需求分析标记了 {risk_level} 风险：{具体风险}
+   确认处理策略：{选项A} 还是 {选项B}？
+```
+
+等待用户确认后，输出决策摘要：
+```
+架构决策已确认，开始生成设计方案...
+- {决策1}: {结果}
+- {决策2}: {结果}
+```
+
+### Step 3：生成设计方案
+
+调用 `modus-design-brief` Skill 的核心生成逻辑，传入：
+- `mode: harness`
+- `output_path: modus/plans/active/{story-id}/01.5-design-brief.md`
+- `analysis_doc: 01-analysis.md 内容`
+- `business_skills: 已加载的 Skill 内容`
+- `constitution: constitution 字段`
+- `arch_decisions: Step 2 确认的决策`
+
+生成完整的 9 节 design-brief 内容（格式见 `modus-design-brief` Skill）。
+
+### Step 4：写入产出物
+
+将 design-brief 内容写入 `modus/plans/active/{story-id}/01.5-design-brief.md`，文件头部必须包含 HANDOFF 块：
+
+```markdown
+<!--HANDOFF
+agent: "01.5-design"
+story_id: "{story-id}"
+domains: ["{domain1}", "{domain2}"]
+design_decisions:
+  - "{决策1}"
+  - "{决策2}"
+key_entities: ["{Entity1}", "{Entity2}"]
+api_contracts:
+  - "{com.company.XxxService#methodName}"
+sprint_mapping:
+  Sprint1: "{Data层实现描述}"
+  Sprint2: "{Service层实现描述}"
+  Sprint3: "{API层实现描述}"
+quality_check:
+  passed: {N}
+  total: 6
+  issues: ["{若有未通过项}"]
+gate_status: "passed"
+-->
+```
+
+**gate_status 判定：**
+- `passed`：质量自检 6/6 通过
+- `warning`：有 `⚠️ 待补充` 标注，但不阻断流程（SubAgent 02 需关注）
+- `failed`：关键节（节 4 / 节 5）有严重缺失，需重新生成（上报 Orchestrator）
+
+### Step 5：输出进度卡片
+
+```
+✅ SubAgent 01.5 完成 → 01.5-design-brief.md
+   设计决策: {N}个 | 追踪矩阵: {N}行 | 质量自检: {N}/6
+   关键实体: {Entity1}, {Entity2}
+   接口合同: {方法签名列表（最多3个）}
+   → Gate A0: passed，SubAgent 02 可以启动
+```
+
+---
+
+## 产出物目录
+
+```
+modus/plans/active/{story-id}/
+├── 01-analysis.md          ← SubAgent 01 产出（输入）
+├── 01.5-design-brief.md    ← 本 SubAgent 产出（含 HANDOFF）
+└── 02-sprint-contract.md   ← SubAgent 02 产出（下一步）
+```
+
+---
+
+## 与 SubAgent 02 的交接协议
+
+SubAgent 02 在 Step 1 读取上下文时，**必须读取** `01.5-design-brief.md`：
+
+1. 先读 HANDOFF 块，获取 `key_entities`、`api_contracts`、`sprint_mapping`
+2. 再读完整内容，以节 5（实现蓝图）和节 7（代码生成提示）作为主要编码指南
+3. 以节 8（禁止事项）作为代码审查自检列表
+4. 以节 9（追踪矩阵）作为 Sprint 完成的验收依据
+
+若 HANDOFF `gate_status: warning`，SubAgent 02 需在 `02-sprint-contract.md` 中记录哪些 `⚠️` 项已额外处理。

package/templates/skills/modus-harness-agents/01-analysis/SKILL.md

@@ -1,3 +1,10 @@
+---
+name: modus-harness-01-analysis
+description: Use this skill when the Harness orchestrator needs to perform TAPD Story requirements analysis. Reads the TAPD story, extracts business intent, identifies affected code scope at method level, and generates 01-analysis.md with HANDOFF block. Triggered automatically by modus-harness orchestrator as the first step in Loop 1.
+allowed-tools: Read, Write, Glob, WebFetch
+disable: false
+---
+
 # modus-harness-01-analysis（需求分析 SubAgent）
 
 **调用方：** Harness Orchestrator（`modus-harness`）  

package/templates/skills/modus-harness-agents/02-dev/SKILL.md

@@ -1,3 +1,10 @@
+---
+name: modus-harness-02-dev
+description: Use this skill when the Harness orchestrator needs to implement code changes based on the requirements analysis (01-analysis.md). Implements code layer by layer (data → service → orchestration → interface), runs build compilation, and generates 02-sprint-contract.md. Triggered by modus-harness after SubAgent 01 completes or during Loop 2 re-entry for P1/P2 fixes.
+allowed-tools: Read, Write, Glob, Bash
+disable: false
+---
+
 # modus-harness-02-dev（代码开发 SubAgent）
 
 **调用方：** Harness Orchestrator  

package/templates/skills/modus-harness-agents/03-test/SKILL.md

@@ -1,3 +1,10 @@
+---
+name: modus-harness-03-test
+description: Use this skill when the Harness orchestrator needs to generate unit tests for code changes. Covers Happy Path, boundary conditions, exception paths, and concurrency scenarios. Generates 03-test-report.md. Triggered by modus-harness in parallel with SubAgents 04 and 05 after Gate A passes.
+allowed-tools: Read, Write, Glob, Bash
+disable: false
+---
+
 # modus-harness-03-test（代码测试 SubAgent）
 
 **调用方：** Harness Orchestrator（与 04/05 并行启动）  

package/templates/skills/modus-harness-agents/04-perf/SKILL.md

@@ -1,3 +1,10 @@
+---
+name: modus-harness-04-perf
+description: Use this skill when the Harness orchestrator needs to perform static performance audit on code changes. Detects N+1 queries, missing batch operations, unbounded data fetches, deep pagination risks, and ES query issues. Generates 04-perf-report.md. Triggered by modus-harness in parallel with SubAgents 03 and 05 after Gate A passes.
+allowed-tools: Read, Write, Glob
+disable: false
+---
+
 # modus-harness-04-perf（性能审计 SubAgent）
 
 **调用方：** Harness Orchestrator（与 03/05 并行启动）  

package/templates/skills/modus-harness-agents/05-security/SKILL.md

@@ -1,3 +1,10 @@
+---
+name: modus-harness-05-security
+description: Use this skill when the Harness orchestrator needs to perform security audit on code changes. Checks multi-tenant data isolation, missing authorization annotations, sensitive data logging, SQL injection risks, and bypass interface protection. Generates 05-security-report.md. Triggered by modus-harness in parallel with SubAgents 03 and 04 after Gate A passes.
+allowed-tools: Read, Write, Glob
+disable: false
+---
+
 # modus-harness-05-security（安全审计 SubAgent）
 
 **调用方：** Harness Orchestrator（与 03/04 并行启动）  

package/templates/skills/modus-harness-agents/06-review/SKILL.md

@@ -1,3 +1,10 @@
+---
+name: modus-harness-06-review
+description: Use this skill when the Harness orchestrator needs to perform comprehensive code review after all audit reports are ready. Evaluates all artifacts (01-analysis.md through 05-security-report.md), grades issues as P1/P2/P3, and generates cr-report.md with HANDOFF block. Gate C: if P1/P2 issues found, triggers Loop 2 re-entry. Triggered by modus-harness after Gate B passes.
+allowed-tools: Read, Write, Glob
+disable: false
+---
+
 # modus-harness-06-review（代码评审 SubAgent）
 
 **调用方：** Harness Orchestrator（Gate B 通过后触发）  

package/templates/skills/modus-harness-agents/07-deploy/SKILL.md

@@ -1,3 +1,10 @@
+---
+name: modus-harness-07-deploy
+description: Use this skill when the Harness orchestrator needs to verify deployment after code review passes (no P1/P2 issues). Monitors CI/CD pipeline status, validates service health across environments (dev→uat→pre→prd), runs smoke tests on P0 interfaces, and generates 07-deploy-status.md. Triggered by modus-harness after Gate C passes.
+allowed-tools: Read, Write, Glob, Bash, WebFetch
+disable: false
+---
+
 # modus-harness-07-deploy（部署发布 SubAgent）
 
 **调用方：** Harness Orchestrator（Gate C 通过后触发）  

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

@@ -1,3 +1,10 @@
+---
+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.
+allowed-tools: Read, Write, Glob, Bash
+disable: false
+---
+
 # modus-init
 
 **触发条件：** 用户运行 `/modus:init` 时使用此 Skill。
@@ -179,6 +186,17 @@ constitution:
 
 ---
 
+### Step 3 补充：生成 Business Skill 时必须填写 key_files
+
+在生成每个业务 Skill（`.codebuddy/skills/modus-biz-{domain}/SKILL.md`）时，**必须**在 frontmatter 中填写 `key_files` 字段：
+
+- 列出本域最具代表性的源文件路径（最多 10 个）
+- 优先选择 Service / Manager / Mapper / Domain / Entity 文件
+- 这些文件将用于后续 plan/spec/harness 的「前置 Skill 更新 hash 检查」——若文件内容未变化，则跳过更新，节省 token
+- `last_hash` 初始留空（`""`），下次 plan/spec/harness 触发前置更新时自动计算并填入
+
+---
+
 ## Business Skill 标准格式参考（含知识体系字段）
 
 ```markdown
@@ -190,6 +208,12 @@ updated: {YYYY-MM-DD}
 maturity: draft             # draft | verified | proven
 last_referenced: {YYYY-MM-DD}
 usage_count: 0
+last_hash: ""               # SHA-1(key_files 内容拼接)，前置更新时自动计算并填入
+key_files:                  # 关键源文件列表，用于 hash 检查（最多 10 个，优先 Service/Manager/Mapper）
+  - src/.../service/{Domain}Service.java
+  - src/.../manager/{Domain}Manager.java
+  - src/.../dao/{Domain}Mapper.java
+  - src/.../domain/{Domain}.java
 ---
 
 # {中文域名}业务知识

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

@@ -1,3 +1,10 @@
+---
+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.
+allowed-tools: Read, Write, Glob, Bash
+disable: false
+---
+
 # modus-plan（计划模式）
 
 **触发条件：** 用户运行 `/modus:plan [需求描述]` 时使用此 Skill。
@@ -82,17 +89,53 @@
 开始前置更新 Skill，然后生成规划文档。
 ```
 
-### Step 4：前置 Skill 更新（Level 2 加载）
+### Step 4：前置 Skill 更新（Level 2 加载，含 hash 检查）
+
+确认域和意图后，对每个涉及的业务域执行以下流程（**先 hash 检查，再决定是否全量更新**）：
+
+#### Step 4a：读取 Skill frontmatter（轻量操作，仅读前 20 行）
+
+读取 `.codebuddy/skills/modus-biz-{domain}/SKILL.md` 的 YAML frontmatter，提取：
+- `last_hash`：上次记录的 key_files 内容摘要
+- `key_files`：关键源文件列表
+
+若 Skill 不存在，跳到 Step 4d（新建）。
+
+#### Step 4b：计算当前 key_files 的 hash
+
+使用 Bash 对 `key_files` 列出的文件内容做 SHA-1 摘要：
+
+```bash
+# 对每个文件计算 sha1，排序后再做一次 sha1（顺序无关）
+shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
+```
 
-确认域和意图后，启动「Skill 更新 SubAgent」（`modus-harness-00-skills-builder` 模式 B），对每个涉及的业务域执行：
+- 若某个 `key_files` 中的文件不存在（可能已被重命名/删除），视为「已变化」，强制更新
+- 若 `key_files` 为空或缺失，视为「已变化」，强制更新
+
+#### Step 4c：对比 hash，决定是否跳过
+
+```
+当前 hash == last_hash（且 last_hash 非空）
+  → ✓ modus-biz-{domain} Skill 无变化（hash 匹配），跳过前置更新（节省 ~2000 tokens）
+  → 仅更新 last_referenced 日期（不读取完整代码，不修改 Skill 内容）
+  → 继续 Step 5
+
+当前 hash != last_hash  OR  last_hash 为空
+  → 进入 Step 4d 执行完整更新
+```
+
+#### Step 4d：完整前置更新（仅在 hash 不匹配时执行）
+
+启动「Skill 更新 SubAgent」（`modus-harness-00-skills-builder` 模式 B），执行：
 
 1. **Level 2 加载**：读取完整 SKILL.md 文件
 2. 扫描该域相关的最新代码文件（近期变更的文件）
 3. 对比 Skill 内容与代码现实，识别差异
-4. 更新 Skill 文件中过时的信息，更新 `last_referenced` 和 `usage_count`
+4. 更新 Skill 文件中过时的信息，更新 `last_referenced`、`usage_count` 和 `last_hash`
 5. 输出更新摘要：`✓ modus-biz-order Skill 已更新（新增: OrderStatus.PENDING_REVIEW | maturity: draft→verified）`
 
-若有未初始化的域，调用模式 A 新建 Skill。
+若有未初始化的域，调用模式 A 新建 Skill（`last_hash` 留空，`key_files` 由 AI 填写）。
 
 ### Step 5：生成计划文档
 
@@ -107,7 +150,7 @@ status: in-progress
 domains: [{domain1}, {domain2}]
 quick_mode: false
 completed: []
-pending: [proposal, design, tasks]
+pending: [proposal, design, design-brief, tasks]
 created: {ISO8601时间戳}
 ```
 
@@ -115,14 +158,14 @@ created: {ISO8601时间戳}
 - 从用户 prompt 提取关键词，生成 kebab-case 名称（如 `add-batch-approve`）
 - 如果目录已存在，提示用户确认
 
-**快速模式（`--quick`）产出物：** proposal.md + tasks.md（跳过 design.md）
+**快速模式（`--quick`）产出物：** proposal.md + tasks.md（跳过 design.md 和 design-brief.md）
 
 **产出物依赖（完整模式）：**
 
 ```
 proposal.md  ─────────────┐
                            ▼
-design.md ────────────► tasks.md
+design.md ────────────► design-brief.md ────────────► tasks.md
 ```
 
 **1. proposal.md** — 意图与范围
@@ -166,7 +209,18 @@ design.md ────────────► tasks.md
 - {文件路径} — {新增/修改/删除}
 ```
 
-**3. tasks.md** — 实现清单
+**3. design-brief.md** — 设计方案（代码开发前的精确实现指南）
+
+调用 `modus-design-brief` Skill，传入：
+- `mode: plan`
+- `output_path: modus/plans/{name}/design-brief.md`
+- `analysis_doc: proposal.md 内容`
+- `business_skills: 已加载的 Skill 内容`
+- `constitution: constitution 字段`
+
+生成后更新 `.modus-state.yaml` 的 `completed` 列表（追加 `design-brief`），并在 `pending` 中移除。
+
+**4. tasks.md** — 实现清单
 
 ```markdown
 # Tasks: {功能名称}
@@ -193,6 +247,7 @@ design.md ────────────► tasks.md
 计划文档已生成：
   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
@@ -236,11 +291,13 @@ modus/
 │   │   ├── .modus-state.yaml        ← 状态文件（断点续跑用）
 │   │   ├── proposal.md
 │   │   ├── design.md
+│   │   ├── design-brief.md          ← 设计方案（代码开发前的实现指南）
 │   │   └── tasks.md
 │   └── archive/
 │       └── 2026-04-20-add-batch-approve/
 │           ├── .modus-state.yaml    ← status: archived
 │           ├── proposal.md
 │           ├── design.md
+│           ├── design-brief.md
 │           └── tasks.md
 ```

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

@@ -1,3 +1,10 @@
+---
+name: modus-spec
+description: Use this skill when executing /modus:spec command for OpenSpec-style spec-driven development. Generates delta specs (ADDED/MODIFIED/REMOVED requirements with GIVEN/WHEN/THEN scenarios), design, and tasks. Trigger on /modus:spec command or when user wants behavior specifications before coding.
+allowed-tools: Read, Write, Glob, Bash
+disable: false
+---
+
 # modus-spec（OpenSpec 规范驱动开发）
 
 **触发条件：** 用户运行 `/modus:spec [需求描述]` 时使用此 Skill。
@@ -74,9 +81,51 @@
 开始前置更新 Skill，然后生成规范文档。
 ```
 
-### Step 4：前置 Skill 更新（Level 2 加载，同 /modus:plan Step 4）
+### Step 4：前置 Skill 更新（Level 2 加载，含 hash 检查，同 /modus:plan Step 4）
+
+对每个涉及的业务域执行以下流程（**先 hash 检查，再决定是否全量更新**）：
+
+#### Step 4a：读取 Skill frontmatter（轻量操作，仅读前 20 行）
+
+读取 `.codebuddy/skills/modus-biz-{domain}/SKILL.md` 的 YAML frontmatter，提取：
+- `last_hash`：上次记录的 key_files 内容摘要
+- `key_files`：关键源文件列表
+
+若 Skill 不存在，跳到 Step 4d（新建）。
+
+#### Step 4b：计算当前 key_files 的 hash
+
+使用 Bash 对 `key_files` 列出的文件内容做 SHA-1 摘要：
+
+```bash
+shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
+```
+
+- 若某个文件不存在，视为「已变化」，强制更新
+- 若 `key_files` 为空或缺失，视为「已变化」，强制更新
+
+#### Step 4c：对比 hash，决定是否跳过
+
+```
+当前 hash == last_hash（且 last_hash 非空）
+  → ✓ modus-biz-{domain} Skill 无变化（hash 匹配），跳过前置更新（节省 ~2000 tokens）
+  → 仅更新 last_referenced 日期，继续 Step 5
+
+当前 hash != last_hash  OR  last_hash 为空
+  → 进入 Step 4d 执行完整更新
+```
+
+#### Step 4d：完整前置更新（仅在 hash 不匹配时执行）
+
+调用 `modus-harness-00-skills-builder` 模式 B，执行：
+
+1. **Level 2 加载**：读取完整 SKILL.md 文件
+2. 扫描该域相关的最新代码文件（近期变更的文件）
+3. 对比 Skill 内容与代码现实，识别差异
+4. 更新 Skill 文件中过时的信息，更新 `last_referenced`、`usage_count` 和 `last_hash`
+5. 输出更新摘要：`✓ modus-biz-order Skill 已更新（新增: OrderStatus.PENDING_REVIEW | maturity: draft→verified）`
 
-调用 `modus-harness-00-skills-builder` 模式 B，读取并更新相关 Skill。
+若有未初始化的域，调用模式 A 新建 Skill（`last_hash` 留空，`key_files` 由 AI 填写）。
 
 ### Step 5：生成规范文档
 
@@ -96,7 +145,7 @@ delta_stats:
 tasks_completed: "0/?"
 scenarios_covered: "0/?"
 completed: []
-pending: [proposal, specs, design, tasks]
+pending: [proposal, specs, design, design-brief, tasks]
 created: {ISO8601时间戳}
 ```
 
@@ -110,6 +159,9 @@ proposal.md
     └──► design.md
               │
               ▼
+         design-brief.md  ← 设计方案（代码开发前的精确实现指南）
+              │
+              ▼
            tasks.md
 ```
 
@@ -159,7 +211,20 @@ proposal.md
 
 **3. design.md** — 技术方案（同 /plan）
 
-**4. tasks.md** — 实现清单（含场景驱动的规格验证章节）
+**4. design-brief.md** — 设计方案（代码开发前的精确实现指南）
+
+调用 `modus-design-brief` Skill，传入：
+- `mode: spec`
+- `output_path: modus/changes/{name}/design-brief.md`
+- `analysis_doc: proposal.md + specs/{domain}/spec.md 内容`
+- `business_skills: 已加载的 Skill 内容`
+- `constitution: constitution 字段`
+
+重点：spec 模式的 design-brief 需在节 6（边界条件）中覆盖所有 delta spec 里的 Scenario 失败路径，节 9（追踪矩阵）中每个 ADDED/MODIFIED Requirement 都必须出现。
+
+生成后更新 `.modus-state.yaml`，追加 `design-brief` 到 `completed`。
+
+**5. tasks.md** — 实现清单（含场景驱动的规格验证章节）
 
 在 tasks.md 末尾加入**场景驱动的验证章节**——每个 TODO 项直接追踪到 delta spec 中对应的 Scenario：
 
@@ -183,6 +248,7 @@ proposal.md
   modus/changes/{name}/proposal.md
   modus/changes/{name}/specs/{domain}/spec.md  ← delta specs（{N}个场景）
   modus/changes/{name}/design.md
+  modus/changes/{name}/design-brief.md         ← 设计方案（{N}节 | 追踪矩阵 {N}行）
   modus/changes/{name}/tasks.md
   modus/changes/{name}/.modus-state.yaml
 
@@ -236,6 +302,7 @@ modus/
 │       ├── proposal.md
 │       ├── specs/order/spec.md   ← delta specs
 │       ├── design.md
+│       ├── design-brief.md       ← 设计方案（代码开发前的实现指南）
 │       └── tasks.md
 └── changes/archive/
     └── 2026-04-20-add-batch-approve/