@modus-ai/modus 0.2.4 → 0.2.6

package/templates/skills/modus-agents/designer/SKILL.md

@@ -1,140 +1,152 @@
 ---
 name: modus-designer
-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.
+description: Use this skill when the Harness orchestrator needs to generate a technical design brief after requirements analysis. Takes 01-analysis.md as input, prompts human for architecture decisions, and produces 01.5-design-brief.md with HANDOFF block. Contains a mandatory human confirmation pause (⏸️) for architecture choices. Triggered by modus-harness after Gate A0 passes.
 allowed-tools: Read, Write, Glob
 disable: false
 ---
 
 # modus-designer（技术方案设计 SubAgent）
 
-**调用方：** Harness Orchestrator（`modus-harness`）  
-**输入：** `modus/plans/active/{story-id}/01-analysis.md` + 相关业务 Skill + constitution  
+**调用方：** Harness Orchestrator（Gate A0 通过后触发）  
+**输入：** `01-analysis.md` + 相关业务 Skill 内容 + constitution.hard_rules  
 **产出物：** `modus/plans/active/{story-id}/01.5-design-brief.md`
 
 ## 职责
 
-承接 SubAgent 01 的需求分析结果，在代码开发开始之前生成结构化设计方案，将 Sprint 执行计划翻译为精确到类名/方法名级别的实现蓝图，作为 SubAgent 02 的核心输入。
+在需求分析（01-analysis.md）与代码开发（SubAgent 02）之间插入设计推导层，生成结构化技术方案（design-brief），消除实现时的架构歧义。包含一个**人工架构决策确认节点**（⏸️），确保关键选型由人决定，而非由 AI 自行猜测。
 
 ---
 
 ## 执行流程
 
-### Step 1：读取需求分析结果
+### Step 1：读取输入
 
-1. 读取 `modus/plans/active/{story-id}/01-analysis.md`
-   - 解析 HANDOFF 块，提取 `domains`、`risk_level`、`key_constraints`
-   - 读取 Sprint 执行计划（各 Sprint 的任务拆分）
-   - 读取验收标准（Scenario 列表）
-   - 读取风险点（事务、并发、性能、安全）
+1. 读取 `01-analysis.md`（需求分析报告）
+2. 读取 Orchestrator 传入的业务 Skill 内容（已由 INIT 阶段加载）
+3. 读取 `modus/config.yaml` 的 `constitution.hard_rules` 和 `tech_stack`
 
-2. 读取 Orchestrator 传入的业务 Skill 内容（已在 Step 1 INIT 阶段加载）
-3. 读取 `modus/config.yaml` 的 `constitution` 字段
+### Step 2：识别架构歧义点
 
-### Step 2：澄清架构决策 ⏸️ 【人工交互节点】
+基于 01-analysis.md 的影响范围和风险点，识别**需要人工确认的架构决策**：
 
-基于需求分析内容，识别并提出 1-3 个关键架构决策问题。
+**必须确认的决策类型：**
+- 存在 2 种以上可行的技术选型（如同步 RPC vs 异步 MQ）
+- 接口设计有破坏性变更（需确认兼容性策略）
+- 业务 Skill 中有冲突的 `[decision]` 记录
+- 01-analysis.md 标注 `risk_level: high` 时，并发/事务策略需确认
 
-**提问原则：**
-- 只问会影响 SubAgent 02 代码结构的决策（接口、模型、事务边界）
-- 若业务 Skill 中已有 `[decision]` 覆盖相关决策，跳过，直接引用
-- `risk_level: high` 时必须包含并发/事务相关决策确认
-- 已在 `key_constraints` 中明确的不再询问
+**不需要确认的情况（直接使用 constitution + Skill 的约束）：**
+- 技术栈已在 constitution 中明确规定
+- 业务 Skill 中有对应场景的唯一 `[guideline]`
+- 变更范围为纯新增、不影响现有接口/数据
+
+### Step 3：⏸️ 人工架构决策确认
+
+**若发现需要确认的决策点，必须暂停等待用户输入：**
 
-**示例问题格式：**
 ```
-Story {id} 需求分析已完成。在生成设计方案前，需确认几个架构决策：
+⏸️ 设计方案需要确认以下架构决策：
 
-1. [数据模型] {具体问题，如「审批记录是新建 approval_record 表，还是扩展 order 表字段？」}
-   （影响：DDL 设计和 Mapper 层实现）
+1. [技术选型] {决策问题，如「批量操作是同步处理还是 MQ 异步？」}
+   - 方案 A: {技术方案 + 优劣}
+   - 方案 B: {技术方案 + 优劣}
+   - 推荐: {基于已有 Skill 知识的建议}
 
-2. [接口方式] {具体问题，如「批量操作是同步返回结果，还是异步 MQ 通知？」}
-   （影响：API 合同和事务边界）
+2. [接口兼容性] {如「旧的 createOrder v1 是否需要兼容？」}
+   - 方案 A: 保留 v1，新增 v2 → 维护两套代码
+   - 方案 B: 直接替换 v1 → 需协调调用方升级
+   - 推荐: {建议}
 
-3. [风险处理] ⚠️ 需求分析标记了 {risk_level} 风险：{具体风险}
-   确认处理策略：{选项A} 还是 {选项B}？
+请回答上述问题（直接告知选择 A/B 或给出具体方案），我将据此生成完整设计方案。
 ```
 
-等待用户确认后，输出决策摘要：
-```
-架构决策已确认，开始生成设计方案...
-- {决策1}: {结果}
-- {决策2}: {结果}
-```
+等待用户回答后继续。
+
+**若无需确认的决策点，直接进入 Step 4（输出标注"架构决策无歧义，直接生成"）。**
 
-### Step 3：生成设计方案
+### Step 4：生成技术方案（design-brief）
 
-调用 `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）。
+```markdown
+## 1. 基本信息
+- Story ID / 需求摘要
+- 设计时间
+- 依赖的业务域及 Skill 版本
+
+## 2. 业务意图摘要
+{1-2 句话，从 01-analysis.md 提炼}
+
+## 3. 实体与数据模型
+- 新增/修改的 Entity 字段（含类型、约束）
+- DB 变更（DDL 摘要）
+- 关键枚举新增值
+
+## 4. API / 接口合同
+- 新增接口（路径、方法、入参、出参）
+- 修改接口（变更前后对比）
+- 接口兼容性策略（v1/v2 并存 or 直接替换）
+
+## 5. 实现蓝图（分层调用链）
+Data:    {Mapper 类/方法}
+Service: {Manager/Service 类/方法}
+API:     {Facade/Controller 类/方法}
+MQ:      {Producer/Consumer（如有）}
+
+## 6. 边界条件与异常处理
+- 前置校验（哪些参数必须校验，校验规则）
+- 异常场景（并发、超时、下游失败）的处理策略
+- 幂等策略（如有）
+
+## 7. 代码生成提示（供 SubAgent 02 使用）
+- 已有的关键类路径（避免重复创建）
+- 必须使用的注解/工具类（来自 Skill guideline）
+- 禁止的做法（来自 Skill pitfall + constitution）
+
+## 8. 禁止事项（汇总自 constitution + Skill）
+{逐条列出 constitution.hard_rules + 业务 Skill [pitfall] 中与本次相关的约束}
+
+## 9. 需求-任务追踪矩阵
+| 需求点 | 对应实现（类/方法） | Sprint | 校验方式 |
+|--------|-----------------|--------|---------|
+| {需求} | {类.方法()} | Sprint N | {测试/联调} |
+```
+
+### Step 5：写入产出物
 
-### Step 4：写入产出物
+将 design-brief 写入 `modus/plans/active/{story-id}/01.5-design-brief.md`，文件头部附加 HANDOFF 块。
+
+---
 
-将 design-brief 内容写入 `modus/plans/active/{story-id}/01.5-design-brief.md`，文件头部必须包含 HANDOFF 块：
+## 产出物格式（01.5-design-brief.md）
 
 ```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"
+decisions_confirmed: {N}
+design_sections: 9
+gate_status: "{passed|warning|failed}"
+key_decisions:
+  - "{已确认的架构决策摘要1}"
+  - "{已确认的架构决策摘要2}"
 -->
-```
-
-**gate_status 判定：**
-- `passed`：质量自检 6/6 通过
-- `warning`：有 `⚠️ 待补充` 标注，但不阻断流程（SubAgent 02 需关注）
-- `failed`：关键节（节 4 / 节 5）有严重缺失，需重新生成（上报 Orchestrator）
 
-### Step 5：输出进度卡片
+# 技术方案 — {Story 标题}
 
+{design-brief 完整内容，见 Step 4}
 ```
-✅ 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 产出（下一步）
-```
+**`gate_status` 赋值规则：**
+- `passed`：所有架构决策已确认，设计方案完整无歧义
+- `warning`：存在低风险的未确认点，但不阻塞开发（如纯优化类决策）
+- `failed`：存在高风险的未确认点，或用户答复后仍有歧义 → Orchestrator 重入本 SubAgent（最多 2 次）
 
 ---
 
-## 与 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` 中记录哪些 `⚠️` 项已额外处理。
+- 追踪矩阵的每行须能追溯到 01-analysis.md 中的具体需求点
+- 「禁止事项」必须包含所有与本次变更相关的 constitution.hard_rules
+- 「实现蓝图」中的类路径必须来自 Skill 的关键文件索引或已有代码，不得凭空创造
+- **HANDOFF 块必须位于文件最顶部**，Orchestrator 仅读此块（≤ 20 行）决策是否继续

package/templates/skills/modus-agents/developer/SKILL.md

@@ -1,109 +1,150 @@
 ---
 name: modus-developer
-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.
+description: Use this skill when the Harness orchestrator needs to implement code based on the sprint plan in 01-analysis.md and design brief in 01.5-design-brief.md. Executes each sprint layer by layer (data→service→orchestration→api), validates with build command after each sprint, and generates 02-sprint-contract.md. Triggered by modus-harness after Gate A0.5 passes.
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
 
 # modus-developer（代码开发 SubAgent）
 
-**调用方：** Harness Orchestrator  
-**输入：** `01-analysis.md` + 相关业务 Skill  
-**产出物：** `modus/plans/active/{story-id}/02-sprint-contract.md` + 实际代码变更
+**调用方：** Harness Orchestrator（Gate A0.5 通过后触发）  
+**输入：** `01-analysis.md` + `02-design-brief.md` + 业务 Skill 内容 + constitution  
+**产出物：** `modus/stories/{story-id}/harness/03-sprint-contract.md` + 代码变更
 
 ## 职责
 
-核心代码生成者。按照需求分析报告中的 Sprint 计划，逐层实现代码，每个 Sprint 完成后验证可构建，遵循项目已有的架构规范和编码风格。
+按照设计方案（01.5-design-brief.md）的实现蓝图和 01-analysis.md 的 Sprint 计划，逐层实现代码。每个 Sprint 完成后自动验证编译，确保代码质量前置。
 
 ---
 
 ## 执行流程
 
-### Step 1：读取上下文
+### Step 1：读取输入
 
-1. 读取 `01-analysis.md`，理解 Sprint 计划和技术影响范围
-2. 读取相关业务 Skill，了解项目规范（层次结构、命名约定、技术约束）
-3. 读取 `modus/config.yaml`，获取项目技术栈信息
+1. 读取 `02-design-brief.md`（技术方案，重点关注节 5-8）
+2. 读取 `01-analysis.md`（Sprint 执行计划、验收标准）
+3. 确认 `constitution.hard_rules` 和 `key_patterns`（最高优先级约束）
+4. 按需读取 Skill 关键文件索引中的实际代码文件（Level 3 加载，≤ 10 个文件）
 
-### Step 2：逐 Sprint 实现
+### Step 2：逐 Sprint 实现（严格按层顺序，禁止跳层）
 
-按 Sprint 计划顺序实现，每个 Sprint 遵循以下步骤：
+**标准层次顺序（每层必须完成并通过编译验证后才能进入下一层）：**
 
-**2a. 分析现有代码**
-- 找到需要修改/新增的文件
-- 理解现有代码风格和命名规范
-- 识别可复用的工具类、基类、常量
+```
+Sprint 1：数据层
+  → Mapper 接口（必须在 dao 包下）
+  → XML Mapper 或注解式 SQL
+  → Domain / Entity 对象
+
+Sprint 2：服务层
+  → Manager / Service（核心业务逻辑）
+  → 事务边界（@Transactional，必须通过 AopContext.currentProxy() 调用）
+  → 分布式锁（如需，@DistributedLock）
+
+Sprint 3：接口层（如有）
+  → Controller / Facade
+  → Request / Response DTO（含 @Valid 校验注解）
+  → 权限注解（如 @UserAuthorization）
+
+Sprint 4：集成层（如有）
+  → MQ Consumer / Producer
+  → 定时任务
+  → 跨服务 RPC 调用
+```
 
-**2b. 实现代码**
-遵循的通用原则：
-- 命名遵循项目现有风格（从 Skill 或现有代码中获取规范）
-- 新增文件放置到正确的包/目录层次
-- 事务注解使用项目规范方式（避免同类内部调用失效）
-- 分布式锁按项目已有模式使用
-- 参数校验在接口层完成，服务层做业务校验
-- 所有数据库操作必须在正确的事务边界内
-- 金额字段使用 BigDecimal，避免浮点精度问题
+**每个 Sprint 完成后立即执行编译验证：**
 
-**2c. Sprint 验证**
-每个 Sprint 完成后记录：
-- 新增/修改的文件列表
-- 关键实现决策（与 `01-analysis.md` 中建议有出入时说明原因）
+```bash
+{constitution.build_command}  # 如 mvn clean compile -q
+```
 
-### Step 3：生成 Sprint Contract
+编译失败 → 立即修复，修复后重新验证，不进入下一 Sprint。
 
-所有 Sprint 完成后，生成 `02-sprint-contract.md`。
+### Step 3：Self Code Review（每个 Sprint 完成后执行）
 
----
+在记录产出物前，对本 Sprint 的代码进行自检：
 
-## 产出物格式（02-sprint-contract.md）
+```
+自检清单（必须全部通过）：
+□ Mapper 接口是否在 dao 包下（来自 constitution.hard_rules）
+□ 金额字段是否符合 constitution 的金额规范
+□ @Transactional 的同类调用是否通过 AopContext.currentProxy()
+□ 是否存在 for 循环内的 DB 查询（N+1 风险）
+□ 新增写入操作是否有事务保护
+□ 对外接口是否有参数校验（@NotNull/@Valid 等）
+□ 是否引用了 Skill [pitfall] 中记录的已知风险点并做了处理
+□ 所有修改是否都能追溯到 01.5-design-brief.md 的追踪矩阵
+```
+
+发现问题 → 立即修复，记入 02-sprint-contract.md 的「自检发现」字段。
+
+### Step 4：写入 Sprint Contract
+
+每个 Sprint 完成后，将执行情况追加到 `02-sprint-contract.md`：
 
 ```markdown
-# Sprint Contract
+## Sprint {N}：{层次名称}
 
-## 执行摘要
-- 完成 Sprint: {N} 个
-- 新增文件: {N} 个
-- 修改文件: {N} 个
-- 实现时间: {YYYY-MM-DD HH:mm}
+### 实现文件
+| 文件路径 | 变更类型 | 说明 |
+|---------|---------|-----|
+| {path} | 新增/修改 | {1句话} |
 
-## Sprint 执行记录
+### 关键实现决策
+- {架构决策：如「选择注解式 SQL 而非 XML，因为逻辑简单」}
 
-### Sprint 1：{名称}
-**状态：** ✅ 完成
+### 自检结果
+- ✅ 所有检查通过 / ⚠️ 发现并修复：{问题描述}
 
-**文件变更：**
-- 新增: `{文件路径}` — {说明}
-- 修改: `{文件路径}` — {变更内容}
+### 编译验证
+- 结果：✅ 通过 / ❌ 失败（已修复）
+```
+
+---
+
+## 产出物格式（02-sprint-contract.md）
 
-**关键实现决策：**
-- {决策说明}
+```markdown
+---
+schema_version: "1.1"
+agent: "03-dev"
+run_id: "{YYYYMMDD}-{story_id_prefix}"
+story_id: "{story-id}"
+task_id: ""
+domains: ["{domain1}", "{domain2}"]
+gate_status: "{passed|failed}"
+artifact_status: "complete"
+issues: []
+skill_refs:
+  - "modus-biz-{domain}@{version}"
+---
 
-### Sprint 2：{名称}
-...
+# 代码开发执行合同 — {Story 标题}
 
-## 已知风险/遗留问题
-- {问题描述：如某个边界情况暂未处理}
+## 开发摘要
+- 开发时间: {YYYY-MM-DD HH:mm}
+- 完成 Sprint: {N}/{总计N}
+- 变更文件数: {N}
 
-## 待 SubAgent 03/04/05 重点关注
-- {代码评审重点关注点}
-- {性能风险点提示}
-- {安全风险点提示}
+{各 Sprint 详情，见 Step 4}
 ```
 
----
+**`gate_status` 赋值规则：**
+- `passed`：所有 Sprint 完成，编译通过，Self Review 无 P1 问题
+- `failed`：编译失败无法自愈，或发现无法自行解决的架构问题 → 上报 Orchestrator
 
-## 编码规范
+---
 
-遵循业务 Skill 中记录的项目规范。如果 Skill 中没有明确说明，参考以下通用原则：
+## 编码规范（来自 constitution + 通用最佳实践）
 
-- **分层架构：** Controller/Facade → Service/Manager → Mapper/DAO，跨层只能向下调用
-- **事务：** `@Transactional` 只在最外层 Service/Manager 方法上，避免同类内部调用失效
-- **异常处理：** 业务异常抛出项目统一的业务异常类，不吞掉异常
-- **日志：** 关键业务入口和异常分支必须有日志，不打印敏感信息
-- **注释：** 复杂逻辑和非直觉的业务规则需要注释说明
+- **最高优先级**：`constitution.hard_rules` 中的规则不可违反
+- **事务**：同类方法调用事务失效问题，统一用 `AopContext.currentProxy().{method}()` 解决
+- **响应封装**：统一用 `constitution.key_patterns` 中规定的响应封装方式
+- **异常处理**：使用项目已有的异常类，不自创异常类
+- **日志**：关键业务操作（创建/修改/删除）必须有入参日志；异常必须 `log.error` 记录
 
-## 禁止行为
+## 越权禁止
 
-- 不修改已有测试用例（留给 SubAgent 03）
-- 不直接修改生产配置文件（留给 SubAgent 07）
-- 发现可能有性能问题但超出当前 Sprint 范围时，在产出物中标注，不擅自重构
+- 不修改测试文件（由 SubAgent 03 负责）
+- 不修改 Skill 文件（由 SubAgent 00 负责）
+- 不操作部署流程（由 SubAgent 07 负责）