@modus-ai/modus 0.2.4 → 0.2.5

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

@@ -97,6 +97,19 @@ disable: false
 ```markdown
 # 需求分析报告
 
+<!--HANDOFF
+agent: "01-analysis"
+story_id: "{story-id}"
+domains: ["{domain1}", "{domain2}"]
+sprint_count: {N}
+risk_level: "{low|medium|high}"
+key_constraints:
+  - "{约束1，来自 constitution.hard_rules 或需求特殊限制}"
+skill_refs:
+  - "modus-biz-{domain}@{version}"
+gate_status: "{passed|failed}"
+-->
+
 ## 基本信息
 - Story ID: {id}
 - 标题: {标题}
@@ -140,3 +153,6 @@ disable: false
 - 每个风险点必须附带处理建议
 - Sprint 计划必须可直接指导 SubAgent 02 开发，不能含糊
 - 验收标准必须可测试（能直接写成测试用例）
+- **HANDOFF 块必须位于文件最顶部（Markdown 注释形式）**，`gate_status` 字段不可省略
+- `gate_status` 赋值规则：分析完整且无重大歧义 → `passed`；存在无法确认的关键信息 → `failed`（Orchestrator 会重入本 SubAgent）
+- `risk_level` 取值：有事务/并发/数据迁移风险 → `high`；有接口变更但逻辑清晰 → `medium`；纯新增无破坏 → `low`

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

@@ -1,108 +1,160 @@
 ---
 name: modus-deployer
-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
+description: Use this skill when the Harness orchestrator needs to verify deployment after code review passes. Monitors CI/CD pipeline status, validates service health across gray environments (dev→uat→pre→prd), runs P0 smoke tests, monitors error logs for 30 minutes after go-live, pauses for human confirmation before prd. Generates 07-deploy-status.md with HANDOFF block. Triggered by modus-harness after Gate C passes.
+allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
 
 # modus-deployer（部署发布 SubAgent）
 
 **调用方：** Harness Orchestrator（Gate C 通过后触发）  
-**输入：** `cr-report.md`（无 P1/P2）+ `02-sprint-contract.md`  
+**输入：** `02-sprint-contract.md` + `modus/config.yaml` 的 harness.environments 配置  
 **产出物：** `modus/plans/active/{story-id}/07-deploy-status.md`
 
 ## 职责
 
-代码合入后的灰度部署验证。监控 CI/CD 流水线，验证各灰度环境服务健康状态，对关键接口执行冒烟测试，监控上线后错误日志变化。
+验证代码从 CI 到逐级灰度环境的部署过程，执行 P0 接口冒烟测试，监控上线后错误日志，prd 环境等待人工确认后才执行。
 
 ---
 
 ## 执行流程
 
-### Step 1：确认部署前提
+### Step 1：读取部署配置
 
-1. 确认 `cr-report.md` 结论为「可合入」（无 P1/P2）
-2. 读取 `modus/config.yaml` 中的部署相关配置（如 CI 地址、环境列表）
-3. 提示用户确认已触发 CI/CD 流水线
+读取 `modus/config.yaml`：
+```yaml
+harness:
+  buildCommand: "mvn clean compile -q"
+  environments: [dev, uat, pre]  # prd 单独人工确认
+tapdProjectId: "{TAPD项目ID}"
+```
+
+读取 `02-sprint-contract.md` 的 `changed_files`，确认本次变更的模块范围。
+
+### Step 2：CI 状态轮询
+
+检查 CI/CD 流水线（如有 API/CLI 访问权限）：
+
+```bash
+# 轮询 CI 状态（每 30 秒检查一次，超时 10 分钟）
+# 根据项目 CI 工具配置具体命令
+```
+
+**若 CI 失败：**
+```
+❌ CI 失败，Harness 无法继续部署验证。
+请检查：{CI 失败的 job 和错误摘要}
+修复后重新运行 /modus:harness（断点续跑）。
+⏸️ 等待用户处理。
+```
+
+### Step 3：逐环境灰度验证
+
+按 `harness.environments` 顺序逐级验证（dev → uat → pre）：
+
+**每个环境的验证步骤：**
+
+1. **服务健康检查：** 确认服务实例正常启动（健康检查接口返回 200）
+2. **P0 冒烟测试：** 执行核心接口的基本功能验证（从 01-analysis.md 验收标准选取最关键的 1-3 个场景）
+3. **错误日志监控：** 检查部署后 5 分钟内是否有新增 ERROR 日志（基线对比）
 
-### Step 2：CI 流水线状态监控
+**冒烟测试规范：**
+```bash
+# 从 01-analysis.md 的验收标准提取 P0 场景
+# 使用 curl / HTTP 客户端执行请求
+# 验证响应码和关键字段
+```
+
+**环境验证通过条件：**
+- 健康检查接口返回 200
+- P0 冒烟测试全部通过
+- 5 分钟内新增 ERROR 日志数 ≤ 基线的 110%（允许少量噪音）
 
-定期询问或读取 CI 状态：
-- 构建是否通过
-- 单元测试是否通过
-- 代码扫描是否通过
+**环境验证失败 → 立即停止，上报 Orchestrator 等待人工介入。**
 
-若 CI 失败，输出失败原因并停止。
+### Step 4：⏸️ prd 人工确认
 
-### Step 3：灰度环境验证
+pre 环境验证通过后，暂停等待人工确认：
+
+```
+✅ pre 环境验证通过
+  冒烟测试: {N}/{N} 通过
+  错误日志: 无新增 ERROR
 
-按 `dev → test → pre（预发）` 顺序验证（不自动部署 prd，prd 需人工确认）：
+⏸️ prd 部署等待人工确认：
+
+变更摘要：
+  - 涉及模块: {模块列表}
+  - 变更文件: {N} 个
+  - 已验证环境: dev ✅ | uat ✅ | pre ✅
+
+是否继续部署到 prd？[Y/n]
+```
 
-对每个环境：
-1. 检查服务健康状态（health check 接口）
-2. 执行 P0 冒烟测试（来自 `01-analysis.md` 的验收 Scenario）
-3. 查询近 15 分钟 ERROR 日志数量，与上线前基线对比
+等待用户确认后继续。
 
-### Step 4：生成部署报告
+### Step 5：prd 上线监控（仅在用户确认后执行）
+
+prd 部署后监控 30 分钟：
+- 每 5 分钟检查一次 ERROR 日志数量
+- 若 ERROR 数量显著增加（> 基线 150%），立即告警并暂停
+
+### Step 6：写入部署状态报告
 
 ---
 
 ## 产出物格式（07-deploy-status.md）
 
 ```markdown
-# 部署状态报告
+<!--HANDOFF
+agent: "07-deployer"
+story_id: "{story-id}"
+gate_status: "{passed|failed|pending_prd}"
+environments_passed: ["{dev}", "{uat}", "{pre}"]
+prd_status: "{deployed|pending|skipped}"
+-->
+
+# 部署状态报告 — {Story 标题}
 
-## 基本信息
-- Story ID: {id}
+## 部署摘要
 - 部署时间: {YYYY-MM-DD HH:mm}
-- 代码分支: {branch}
+- 触发版本: {commit hash 或构建号}
+- 最终状态: {✅ 全部通过 / ❌ 失败 / ⏸️ 等待 prd}
 
-## CI 流水线
-| 阶段 | 状态 | 耗时 |
-|------|------|------|
-| 构建 | ✅ | {N}s |
-| 单元测试 | ✅ | {N}s |
-| 代码扫描 | ✅ | {N}s |
+## 环境验证结果
 
-## 灰度环境验证
+| 环境 | 健康检查 | 冒烟测试 | ERROR日志 | 结论 |
+|-----|---------|---------|---------|-----|
+| dev | ✅ | ✅ N/N | 无新增 | ✅ 通过 |
+| uat | ✅ | ✅ N/N | 无新增 | ✅ 通过 |
+| pre | ✅ | ✅ N/N | 无新增 | ✅ 通过 |
+| prd | ⏸️ 待确认 | — | — | ⏸️ 等待人工 |
 
-### dev 环境
-- 服务状态: ✅ 健康
-- 冒烟测试: {N}/{N} 通过
-- ERROR 日志: 上线前 {N}/h → 上线后 {N}/h（{变化}）
+## 冒烟测试详情
 
-### test 环境
-- 服务状态: ✅ 健康
-- 冒烟测试: {N}/{N} 通过
+### P0 场景：{场景名}
+- 请求: `{HTTP Method} {path}` 
+- 响应: HTTP 200，{关键字段验证}
+- 结果: ✅ 通过
 
-### pre（预发）环境
-- 服务状态: ✅ 健康
-- 冒烟测试: {N}/{N} 通过
-- ERROR 日志: 上线前 {N}/h → 上线后 {N}/h
+## prd 监控日志（上线后 30 分钟）
 
-## prd 环境
-⏸️ 等待人工确认部署
+{prd 部署后补充}
 
-**部署确认单：**
-- [ ] pre 环境验证通过
-- [ ] 业务方确认冒烟通过
-- [ ] 运维确认资源充足
+## 部署注意事项
 
-## 冒烟测试详情
-| 场景 | 接口 | 状态 |
-|------|------|------|
-| {验收场景1} | POST /api/v1/{path} | ✅ |
-| {验收场景2} | GET /api/v1/{path} | ✅ |
-
-## 结论
-{✅ 灰度验证通过，可推进 prd 部署}
-{❌ 灰度验证失败: {失败原因}}
+{记录部署过程中发现的特殊情况，供知识沉淀使用}
 ```
 
+**`gate_status` 赋值规则：**
+- `passed`：所有非 prd 环境通过，prd 也已完成且监控正常
+- `pending_prd`：non-prd 通过，prd 等待人工确认（正常状态）
+- `failed`：任一环境验证失败或 prd 上线后出现 ERROR 激增
+
 ---
 
-## 注意事项
+## 质量标准
 
-- prd 环境不自动部署，必须等待人工确认
-- 若任意灰度环境冒烟失败，立即停止并上报给 Orchestrator
-- ERROR 日志增量超过基线 2 倍时，触发告警提示
+- 冒烟测试场景必须来自 01-analysis.md 的验收标准，不得自行编造
+- prd 环境**必须等待人工确认**，不得自动部署
+- **HANDOFF 块必须位于文件最顶部**，Orchestrator 读取 `prd_status` 决定是否进入 ARCHIVE 阶段

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 行）决策是否继续