@modus-ai/modus 0.1.1 → 0.1.3

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/

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

@@ -1,3 +1,10 @@
+---
+name: modus-vibe
+description: Use this skill when executing /modus:vibe command for context-aware vibe coding. Loads relevant business Skills before coding so AI works as a knowledgeable project member. Trigger on /modus:vibe command or when user wants to code with business context. Supports --quick flag for simple single-file changes.
+allowed-tools: Read, Write, Glob, Bash
+disable: false
+---
+
 # modus-vibe（氛围编程）
 
 **触发条件：** 用户运行 `/modus:vibe [描述]` 时使用此 Skill。
@@ -117,13 +124,72 @@ B. 继续使用降级模式（无业务上下文，结果质量可能降低）
 如果理解无误，我来开始实现。
 ```
 
+### Step 5.5：内联设计思考（Design Brief CoT）
+
+**触发：** 每次编码任务前强制执行，不可跳过（包括 `--quick` 模式）。  
+**产出：** 内联于当前 LLM 上下文，**不写入任何文件**。
+
+调用 `modus-design-brief` Skill，传入：
+- `mode: vibe`（触发内联输出模式，不落盘）
+- `analysis_doc: 用户 prompt + Step 5 确认的意图摘要`
+- `business_skills: Step 4 已加载的 Skill 内容`
+- `constitution: Step 0 读取的 constitution 字段`
+
+Skill 将按 9 节结构，基于已加载上下文实时推导并输出以下内联块：
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[Design Brief — 内联设计方案，仅用于本次编码，不写文件]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## 1. 基本信息
+模式: vibe | 涉及域: {domain1}, {domain2}
+
+## 2. 业务意图摘要
+{来自 Step 5 的意图摘要}
+
+## 3. 实体与数据模型
+{基于 Skill [model] 条目和用户意图推导，字段带类型}
+
+## 4. API / 接口合同
+{方法签名，带完整包路径}
+
+## 5. 实现蓝图
+Data: {具体 Mapper 类/方法}
+Service: {具体 Manager/Service 类/方法，标注 @Transactional 位置}
+API: {Facade/Controller 类/方法}
+
+## 6. 边界条件与异常处理
+{覆盖关键失败路径，含错误码}
+
+## 7. 代码生成提示
+{来自 Skill key_files 的可复用类 + 命名规范示例}
+
+## 8. 禁止事项与已知坑
+{constitution hard_rules + Skill [pitfall]}
+
+## 9. 需求-任务追踪矩阵
+| 需求点 | 对应实现 | 对应校验方式 |
+|---|---|---|
+| {需求} | {类/方法} | {测试/联调} |
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[End of Design Brief — 开始编码]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**简化原则（vibe 模式）：**
+- 若 Skill 中某节内容明确，可适度精简，但不可省略节标题
+- 节 9 追踪矩阵在 vibe 模式下用「需求点→实现→校验方式」代替完整 Sprint 映射
+- 若 `--quick` 模式，节 3/4/9 可简化为一行摘要，但节 8 禁止事项必须完整输出
+
 ### Step 6：执行编码任务（Level 3 按需加载）
 
-基于已加载的业务上下文和澄清后的意图，执行用户的编码请求：
+基于 Step 5.5 内联设计方案和澄清后的意图，执行用户的编码请求：
 
-- 遵循项目已有的代码风格和命名规范（从 Skill 提取）
-- **严格遵守 constitution 中的 hard_rules**（比 Skill 中的建议优先级更高）
-- 引用已知的实体、接口、关键文件（避免臆造）
+- 以 Step 5.5 内联设计方案中节 5（实现蓝图）为编码路线图
+- 严格遵守节 8（禁止事项）——这是 constitution hard_rules 和 Skill [pitfall] 的汇总
+- 引用节 7（代码生成提示）中的现有类路径，不凭空创造类名
 - **Level 3 加载：** 需要具体代码实现时，按需读取 Skill 中 `关键文件索引` 指向的实际代码文件（而非预先全量读取）
 - 对不确定的业务规则，优先参考 Skill 中的规则描述
 - 如发现 Skill 中记录有误或过时，在回复末尾标注「Skill 更新建议」
@@ -158,9 +224,10 @@ B. 继续使用降级模式（无业务上下文，结果质量可能降低）
 
 ## 氛围编程原则
 
-- **先理解再编码**：先复述对需求的理解，确认后再写代码
+- **先设计再编码**：Step 5.5 内联设计方案是编码的前置必要步骤，不可省略
+- **设计驱动**：编码时以内联设计方案的实现蓝图（节 5）为路线图，禁止事项（节 8）为红线
 - **有据可依**：引用的实体、字段、接口名必须来自 Skill 或已有代码
 - **风格一致**：生成的代码应与项目现有风格保持一致
-- **宪法优先**：constitution.hard_rules 是不可违反的底线，优先于一切
+- **宪法优先**：constitution.hard_rules 是不可违反的底线，优先于一切（已汇总到设计方案节 8）
 - **按需加载**：不预先读取所有 Skill，降低 token 消耗
 - **主动补全**：发现明显缺失（如缺少参数校验、日志）时主动补充