@modus-ai/modus 0.2.4 → 0.2.5

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 6 调用，或用户直接运行 @modus-design-brief。
+description: 在代码开发前生成结构化的设计方案（design-brief），将需求分析信息转化为 LLM 可直接消费的实现指南。由 modus-spec 内部调用（落盘为 design-brief.md）或 modus-harness 中 designer SubAgent 调用（落盘为 01.5-design-brief.md），或由 modus-vibe 内联调用（注入上下文，不落盘）。注：modus-plan 不直接调用本 Skill 落盘，而是通过 vibe 内联调用。触发条件：spec/harness/vibe Skill 内部 Step 6 调用，或用户直接运行 @modus-design-brief。
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
@@ -23,9 +23,17 @@ disable: false
 
 按优先级读取以下输入（调用方已传入的直接使用，未传入的自行读取）：
 
-**需求分析文档（必读，二选一）：**
-- harness 模式：读取 `modus/plans/active/{story-id}/01-analysis.md`
-- plan/spec/vibe 模式：读取调用方目录下的 `proposal.md`，若存在同级 `specs/*/spec.md` 也一并读取
+**需求分析文档（必读，三选一，根据 `mode` 参数判断）：**
+
+| `mode` 值 | 来源类型 | 处理方式 |
+|----------|---------|---------|
+| `harness` | 文件路径 | 读取 `modus/plans/active/{story-id}/01-analysis.md` |
+| `spec` | 文件路径 | 读取调用方目录下的 `proposal.md`；若存在同级 `specs/*/spec.md` 也一并读取 |
+| `vibe` | 运行时字符串 | `analysis_doc` 参数是调用方直接传入的「用户意图摘要」字符串，**不读取任何文件**；直接将此字符串作为需求描述，与 Step 5 加载的 Skill 内容结合生成设计方案 |
+
+> **vibe 模式说明**：`/modus:vibe` 没有 proposal.md，调用方（modus-vibe Step 6）直接将用户 prompt + Step 4 确认的意图摘要作为 `analysis_doc` 参数传入。design-brief 在 vibe 模式下不落盘（产出物注入 LLM 上下文，而非写入文件）。
+>
+> **关于 modus-plan**：modus-plan 不直接调用本 Skill 落盘，而是通过 Build 触发 modus-vibe，由 vibe Step 6 以 `mode: vibe` 内联调用。如需为 plan 产出显式的 design-brief.md，请在编码完成后手动运行 `@modus-design-brief`，传入 `plan.md` 作为需求上下文，并指定 `mode: spec`。
 
 **项目宪法（必读）：**
 - 读取 `modus/config.yaml`，提取 `constitution` 字段（`tech_stack`、`hard_rules`、`key_patterns`）
@@ -42,6 +50,7 @@ disable: false
 - 只问会显著影响设计方案的决策（影响实体结构、接口签名、事务边界）
 - 若 Skill 中已有 `[decision]` 明确记录相关决策，跳过此类问题
 - 若需求文档中已明确指定技术方案，跳过此步
+- **若调用方（plan/spec）已在 proposal.md 或澄清阶段中明确记录了相关架构决策，跳过对应问题**（避免重复提问）；判断方式：读取 `proposal.md` 的「技术方案」或「架构决策」章节，若已覆盖该决策点则跳过，并在输出中注明「已采用 proposal.md 中的决策：{内容}」
 
 **典型问题类型：**
 ```
@@ -94,12 +103,13 @@ disable: false
 
 ### Step 4：写入或内联输出
 
-**落盘模式（plan / spec / harness）：**
+**落盘模式（spec / harness）：**
 
 将生成内容写入调用方指定路径：
-- plan 模式：`modus/plans/{name}/design-brief.md`
-- spec 模式：`modus/changes/{name}/design-brief.md`
+- spec 模式：`modus/changes/{name}/design-brief.md`（gate_status 写 `passed`，此模式无 Gate 检查）
 - harness 模式：`modus/plans/active/{story-id}/01.5-design-brief.md`
+  - **gate_status 必须由 `modus-designer` SubAgent 在 Step 4 后动态评估并填写**（见 `modus-agents/designer/SKILL.md` 的 gate_status 赋值规则）
+  - 固定写 `passed` 将使 Gate A0.5 失效，严禁在 harness 模式下硬编码该字段
 
 写入后输出确认：
 ```
@@ -107,6 +117,8 @@ disable: false
   路径: {文件路径}
 ```
 
+> **注：modus-plan 不调用本 Skill 落盘。** modus-plan 通过 Build 触发 modus-vibe，vibe Step 6 内联调用本 Skill（mode: vibe）生成设计方案，不产生落盘文件。
+
 **内联模式（vibe）：**
 
 以分隔线包裹，直接追加到当前对话上下文中，不写入任何文件：
@@ -139,7 +151,12 @@ design_decisions:
   - "{决策2}"
 key_entities: ["{Entity1}", "{Entity2}"]
 api_contracts: ["{方法签名1}", "{方法签名2}"]
-gate_status: "passed"
+gate_status: "{passed|warning|failed}"
+# gate_status 赋值规则（由调用方 modus-designer SubAgent 动态填写，不可固定为 passed）：
+#   passed  — 所有架构决策已确认，设计方案完整无歧义
+#   warning — 存在低风险未确认点，不阻塞开发
+#   failed  — 存在高风险未确认点或用户答复后仍有歧义，Orchestrator 将重入本 SubAgent
+# 注：plan/spec/vibe 模式调用时此字段不参与 Gate 检查，默认写 passed 即可
 -->
 
 ## 1. 基本信息
@@ -303,13 +320,12 @@ public enum {EnumName} {
 
 ## 调用方集成说明
 
-### plan / spec 模式调用方式
+### spec 模式调用方式
 
-在 Step 6 中，直接调用本 Skill，传入以下参数：
+在 modus-spec Step 7-3 中直接调用本 Skill，传入以下参数：
 ```
-output_path: modus/plans/{name}/design-brief.md   # plan 模式
-output_path: modus/changes/{name}/design-brief.md  # spec 模式
-mode: plan | spec
+output_path: modus/changes/{name}/design-brief.md  # spec 模式，落盘为 design-brief.md
+mode: spec
 analysis_doc: {proposal.md 路径}
 business_skills: [{已加载的 Skill 内容}]
 constitution: {constitution 字段内容}
@@ -319,6 +335,8 @@ constitution: {constitution 字段内容}
 
 传入 `mode: vibe`，Skill 不执行 Step 4 的写文件操作，仅在对话输出中内联展示设计方案块。
 
+> **注：modus-plan 不直接调用本 Skill 落盘。** modus-plan 通过 Build 触发 modus-vibe，vibe Step 6 会根据复杂度内联调用本 Skill（mode: vibe）生成设计方案。如需为 plan 产出显式的 design-brief.md，请在 vibe 编码完成后手动运行 `@modus-design-brief`。
+
 ### harness 模式调用方式
 
 由 SubAgent 01.5 独立执行（见 `modus-agents/designer/SKILL.md`），输入为 `01-analysis.md`，输出为 `01.5-design-brief.md` 含 HANDOFF 块。

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

@@ -31,7 +31,7 @@ disable: false
 | 06 | `modus-reviewer` | 代码评审 | `cr-report.md` | ≤ 1 个团队约定 Skill |
 | 07 | `modus-deployer` | 部署发布 | `07-deploy-status.md` | ≤ 1 个 Skill 文件 |
 
-**预算原则：** SubAgent 超出预算时，应优先读 maturity 更高的 Skill；若 catalog 中某 Skill 标注 `⚠️` 可能过时，优先读最新代码而非该 Skill。
+**预算原则：** SubAgent 超出预算时，应优先读 status 更高（proven > verified > draft）的 Skill；若 catalog 中某 Skill 标注 `⚠️` 可能过时，优先读最新代码而非该 Skill。
 
 ---
 
@@ -80,10 +80,49 @@ A. 现在运行快速初始化（推荐，约 3-5 分钟）
 B. 强制继续（无业务上下文，风险较高）
 ```
 
-**解析 Story ID：**
+**解析 Story ID + 初始化状态追踪：**
 - 从 TAPD URL 提取 Story ID（格式：`tapd.cn/{project}/stories/view/{id}`）
 - 创建工作目录：`modus/plans/active/{story-id}/`
-- 扫描目录，若存在部分产出物（含 HANDOFF 块），从断点处继续
+
+**`.harness-state.yaml` 断点续跑机制（优先级高于 HANDOFF 块探测）：**
+
+检查工作目录下是否存在 `.harness-state.yaml`：
+
+```yaml
+# 示例：modus/plans/active/{story-id}/.harness-state.yaml
+story_id: "{story-id}"
+loop: 1                         # 当前 Loop 轮次（1 或 2）
+# SubAgent ID 约定：00=INIT 阶段(skill-creator)、01/01.5/02/03/04/05/06/07 为主流程；00-ARCHIVE=ARCHIVE 阶段
+completed_agents: ["00-INIT", "01", "01.5", "02", "03"]  # 已成功完成的 SubAgent ID
+current_agent: "04"             # 当前正在执行的 SubAgent（空=未开始/全部完成）
+loop2_triggers: []              # Loop 2 触发的 P1/P2 问题列表
+last_updated: "2026-01-01T12:00:00"
+```
+
+**断点续跑逻辑：**
+```
+.harness-state.yaml 存在
+  → 读取 completed_agents 列表
+  → 跳过已完成的 SubAgent（即使其产出物文件存在也不重新执行）
+  → 从 current_agent 或第一个未完成的 SubAgent 继续
+  → 若 current_agent 非空（说明上次中途失败），重新执行该 SubAgent
+
+.harness-state.yaml 不存在
+  → 全新流程，初始化状态文件（completed_agents: []，loop: 1）
+  → 注意：若目录已有产出物但无状态文件（极端情况），以 HANDOFF 块作为降级判断，但输出警告
+
+SubAgent 00 状态写入规则：
+  → INIT 阶段（Step 2 skill-creator 执行完）完成后，写入 "00-INIT" 到 completed_agents
+  → ARCHIVE 阶段（Step Final 完成后），写入 "00-ARCHIVE" 到 completed_agents
+  → 断点续跑时，若 "00-INIT" 已在列表中则跳过 INIT；若 "00-ARCHIVE" 已在列表中则跳过 ARCHIVE
+```
+
+**每个 SubAgent 完成后，立即更新状态文件**（在 Orchestrator 层执行，不依赖 SubAgent 自身）：
+```yaml
+completed_agents: [..., "{刚完成的 subagent_id}"]
+current_agent: "{下一个 subagent_id}"
+last_updated: "{ISO 8601 时间戳}"
+```
 
 ### Step 1：澄清意图（仅全新流程）⏸️ 【人工交互节点】
 
@@ -120,7 +159,7 @@ B. 强制继续（无业务上下文，风险较高）
 **Level 1 → Level 2 加载：**
 基于用户确认的业务域，调用 SubAgent 00（模式 B：增量更新）：
 - 已有 Skill → 更新至最新代码状态，获取最新内容
-- 未有 Skill → 新建（模式 A），初始 maturity 为 draft
+- 未有 Skill → 新建（模式 A），初始 status 为 draft
 
 将 Skill 内容（已加载的完整 SKILL.md）和 constitution.hard_rules 一起传递给 SubAgent 01 作为背景知识。
 
@@ -140,9 +179,10 @@ Constitution: {N} 条硬性规则已加载
 ```
 SubAgent 01（需求分析）
   ↓ 产出 01-analysis.md（含 HANDOFF 块）
-  ↓ Gate A0: 01.5-design-brief.md HANDOFF.gate_status ∈ {passed, warning}
+  ↓ Gate A0: 读 01-analysis.md HANDOFF 块，检查 gate_status = "passed"（需求分析质量门）
 SubAgent 01.5（设计方案生成）⏸️ 含人工架构决策确认
   ↓ 产出 01.5-design-brief.md（含 HANDOFF 块）
+  ↓ Gate A0.5: 读 01.5-design-brief.md HANDOFF 块，检查 gate_status ∈ {passed, warning}
 SubAgent 02（代码开发）
   ↓ 产出 02-sprint-contract.md（含 HANDOFF 块）
   ↓ Gate A: 编译验证（项目构建工具编译，exit code = 0）
@@ -150,6 +190,8 @@ SubAgent 03（代码测试）  ┐
 SubAgent 04（性能审计）  ├─ 并行启动，等全部完成（各自读取相关 Skill，预算独立）
 SubAgent 05（安全审计）  ┘
   ↓ Gate B: 03/04/05 三份报告全部写入（各含 HANDOFF 块）
+            + 各报告 gate_status ≠ "failed"
+            + 05 安全报告无严重/高危未修复问题
 SubAgent 06（代码评审）
   ↓ 产出 cr-report.md（含 HANDOFF 块，issues 字段列出 P1/P2）
   ↓ Gate C: HANDOFF.issues 为空
@@ -163,9 +205,10 @@ SubAgent 07（部署发布）
 
 | Gate | 检查方式 | 失败处理 |
 |------|---------|---------|
-| Gate A0 | 读 `01.5-design-brief.md` HANDOFF 块，检查 `gate_status` ∈ {passed, warning} | `failed` 时重入 SubAgent 01.5，最多 2 次 |
+| Gate A0 | 读 `01-analysis.md` HANDOFF 块，检查 `gate_status` = "passed"（需求分析质量门） | `failed` 时重入 SubAgent 01，最多 2 次 |
+| Gate A0.5 | 读 `01.5-design-brief.md` HANDOFF 块，检查 `gate_status` ∈ {passed, warning} | `failed` 时重入 SubAgent 01.5，最多 2 次 |
 | Gate A | 执行 `constitution.build_command`，exit code = 0 | 重入 SubAgent 02，最多 3 次 |
-| Gate B | 扫描目录，检查 03/04/05 三个 HANDOFF 文件均存在 | 继续等待，超时上报 |
+| Gate B | 扫描目录，检查 03/04/05 三个 HANDOFF 文件均存在，且各文件 HANDOFF 块的 `gate_status ≠ "failed"`；05（安全审计）报告中若存在严重/高危问题则强制拦截 | 继续等待（文件未齐），超时上报；若 gate_status = "failed" 则重入对应 SubAgent（最多 2 次）|
 | Gate C | 读 cr-report.md 的 HANDOFF 块，检查 `issues` 是否为空 | 触发 Loop 2 精准重入 |
 
 **Gate 检查优先读 HANDOFF 块**，只有当 HANDOFF 块信息不足时才读完整文件。
@@ -176,25 +219,47 @@ SubAgent 07（部署发布）
 - 重入后重新执行：02 → Gate A → 03/04/05 → 06（完整验证）
 - 连续 3 次重入仍有 P1/P2 → 暂停流程，上报用户，请求人工介入
 
+**精准重入 Sprint 定位规则：**
+- 优先按 issue 的 `sprint` 字段（整数）定位受影响 Sprint
+- 若 `sprint` 字段缺失或为 0：fallback 为重跑**全量 Sprint**（降级为保守策略）
+- 若同一 Loop 2 中多个 issue 指向不同 Sprint，取 Sprint 编号的**并集**一并重跑
+
 ### Step Final：ARCHIVE——知识提取
 
 SubAgent 07 完成后（进入 Human Final Review 等待阶段），调用 SubAgent 00（模式 D：知识提取）：
 
 ```
 [ARCHIVE 阶段启动]
-产物范围: 01-analysis.md + 02-sprint-contract.md + cr-report.md + 07-deploy-status.md
-提取目标: [decision] [guideline] [pitfall] [process]
+产物范围: 01-analysis.md + 02-sprint-contract.md + 03-test-report.md
+        + 04-perf-report.md + 05-security-report.md + cr-report.md + 07-deploy-status.md
+提取目标: [decision] [guideline] [pitfall] [process] [invariant]
 ```
 
+**各知识类型的典型来源：**
+
+| 产出物 | 可提取的知识类型 |
+|--------|---------------|
+| `cr-report.md` 的 P2/P3 | `[pitfall]`（发现的编码反模式）、`[invariant]`（金额/并发/事务的不变量） |
+| `02-sprint-contract.md` 的架构决策 | `[decision]`（技术选型）、`[process]`（新增业务流程） |
+| `07-deploy-status.md` 的部署注意事项 | `[guideline]`（上线操作规范） |
+| `01-analysis.md` 的业务规则 | `[invariant]`（系统必须始终为真的业务约束，违反即为 Bug） |
+| `04-perf-report.md` 的高/中风险项 | `[pitfall]`（N+1 查询、大数据量无分页等性能反模式） |
+| `05-security-report.md` 的严重/高危项 | `[pitfall]` `[invariant]`（多租户隔离漏洞、权限缺失等安全反模式，必须提取） |
+
 提取完成后输出知识积累摘要：
 ```
 📚 本次 Harness 知识沉淀：
 - [decision] tech-wiki：新增事件驱动架构决策（来自 02-sprint-contract）
 - [pitfall] biz-order：批量审批超 50 条时需分批处理（来自 04-perf-report）
 - [guideline] team-conventions：@Transactional + AopContext 组合用法（来自 cr-report P2）
-- maturity 更新: modus-biz-order draft→verified（首次工作流验证）
+- [invariant] biz-payment：支付金额必须 > 0 且 ≤ 账户余额，违反即为 Bug（来自 cr-report）
+- status 更新: modus-biz-order draft→verified（首次工作流验证）
 ```
 
+**`usage_count` 更新时机（harness 模式）：**
+
+在 **ARCHIVE 阶段**（SubAgent 07 部署完成后）对本次 Harness 涉及的每个业务域执行 `usage_count += 1`，并同步更新对应 Skill 的 frontmatter。等待部署完成是因为 usage_count 代表「真实交付的工作流验证次数」，仅通过代码审查（Gate C）不构成完整验证。
+
 ---
 
 ## 进度卡片规范
@@ -254,8 +319,9 @@ feat: {业务摘要}
 
 1. 扫描 `modus/plans/active/{story-id}/` 目录，列出已有 HANDOFF 块
 2. 只需读各文件的 HANDOFF 块（≤ 20 行），对照串行顺序确定当前阶段
-3. 检查当前阶段的 Gate 条件是否满足（优先读 HANDOFF，必要时读全文）
-   - Gate A0：检查 `01.5-design-brief.md` HANDOFF 的 `gate_status` 字段
+3. 检查当前阶段的 Gate 条件是否满足（优先读 HANDOFF，必要时读全文）。**每个 Gate 仅在对应 SubAgent 完成后单独执行，互相独立，不同时触发**：
+   - Gate A0：**当 SubAgent 01 写入 `01-analysis.md` 后**，检查该文件 HANDOFF 块的 `gate_status` 字段（仅需求分析完成后的质量门，与 Gate A0.5 无关）
+   - Gate A0.5：**当 SubAgent 01.5 写入 `01.5-design-brief.md` 后**，检查该文件 HANDOFF 块的 `gate_status` 字段（仅设计方案完成后的质量门，独立于 Gate A0 执行结果）
 4. Gate 通过 → 调用下一个 SubAgent 的 Skill（传递 constitution + 相关 Skill 内容）
    - 调用 SubAgent 02 时，必须同时传入 `01.5-design-brief.md` 内容
 5. Gate 失败 → 按规则处理（重入/上报）