@modus-ai/modus 0.2.8 → 0.2.10

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

@@ -27,6 +27,7 @@ disable: false
 --help        → 输出帮助文档，结束执行
 --design      → DESIGN_MODE=true（进入设计评审分支，见「Design Mode 流程」）
 --continue X  → CONTINUE_MODE=true，PLAN_NAME=X（进入接力分支，见「Continue 流程」）
+--code X      → CODE_MODE=true，CODE_PLAN=X（进入任务驱动编码分支，见「Code Mode 流程」）
 --quick       → QUICK_MODE=true（跳过域确认和澄清问题）
 --story X     → STORY_ID=X（关联 TAPD Story）
 --project X   → PROJECT=X（多项目指定）
@@ -43,8 +44,11 @@ disable: false
 检测到 --continue X？
   是 → 跳转到「Continue 流程」（完整独立流程，不执行 Step 0-9）
 
+检测到 --code X？
+  是 → 跳转到「Code Mode 流程」（完整独立流程，不执行 Step 0-9）
+
 检测到 --design？
-  是 → 执行 Step 0→Step 1→Step 2→Step 3→Step 4→Step 5→Step 6→Design Mode Step 7（生成 plan.md 后暂停）
+  是 → 执行 Step 0→Step 1→Step 2→Step 3→Step 4→Step 5→Step 6→Design Mode Step 7（生成 design.md + tasks.md 后暂停）
   否 → 执行标准流程（Step 0 → Step 9）
 ```
 
@@ -383,82 +387,226 @@ created: {ISO8601时间戳}
 
 ---
 
-### Step 7（Design Mode 分支）：设计评审模式产出 ⏸️ 【人工审批节点】
+### Step 7（Design Mode 分支）：多 Artifact 设计文档生成 ⏸️ 【人工审批节点】
 
 > **仅在 DESIGN_MODE=true 时执行此分支，替代标准 Step 8（Build 循环）。**
+> 参考：speckit.plan 三阶段 + opsx:propose DAG 状态机
+
+---
+
+#### Phase R：Research（技术可行性研究）
 
-**生成额外的技术评审内容：**
+> **来源：speckit.plan Phase 0** — 先消除所有「NEEDS CLARIFICATION」再进入设计
 
-在标准 plan.md 基础上，追加以下章节（design mode 专属）：
+**复杂度 ≥ medium 时执行，生成 `research.md`；simple 时跳过（研究内容内联融入 design.md）。**
+
+执行步骤：
+1. 基于 Step 4/5 已加载的业务 Skill，定位关键源码文件（`key_files` + 额外 Glob 扫描）
+2. 扫描目标：
+   - 现有代码中与本需求相关的类/方法（复用点 + 修改点）
+   - 依赖库版本与 API 兼容性
+   - 数据库现有表结构（如有变更）
+   - 外部接口契约（如有跨服务调用）
+3. 识别所有「NEEDS CLARIFICATION」点，若有未澄清项且 Step 6 未覆盖，补问（最多 2 个）
+4. 复杂度 ≥ medium 时落盘 `modus/plans/{name}/research.md`：
 
 ```markdown
-## 技术方案评审
+# Research: {功能名称}
+
+## 现有代码分析
+| 类/方法 | 文件路径 | 与本需求的关系 | 变更类型 |
+|---|---|---|---|
+| {ClassName#method} | {路径} | {复用/修改/新建} | {说明} |
+
+## 技术可行性
+- **依赖版本**：{版本信息与兼容性说明}
+- **现有模式**：{项目已有的相似实现，可复用的设计模式}
+- **技术障碍**：{如有，列出并说明解决思路}
+
+## 已消除的模糊点
+| 原问题 | 澄清结果 | 来源 |
+|---|---|---|
+| {模糊点描述} | {明确结论} | {Skill/代码扫描/用户确认} |
+
+## 数据库影响（如有）
+- {表名}：{新增字段/新建表/索引变更}
+
+## 外部依赖（如有）
+- {服务/接口}：{调用方式/影响说明}
+```
+
+**更新 `.modus-state.yaml` 中的 artifact 状态：**
+```yaml
+artifacts:
+  research: done     # 或 skipped（simple 复杂度时）
+  design: ready
+  tasks: blocked     # 依赖 design
+```
+
+---
+
+#### Phase D：Design（DAG 顺序生成 design.md + tasks.md）
+
+> **来源：opsx:propose DAG 状态机 + speckit.tasks T-ID 任务格式**
+
+**DAG 依赖：** `research(done|skipped) → design(ready) → tasks(ready after design done)`
+
+**Artifact 1：`modus/plans/{name}/design.md`**
+
+生成完整技术设计文档（9 节结构）：
+
+```markdown
+---
+schema_version: "1.2"
+agent: "plan"
+design_mode: true
+status: "pending_review"
+risk_level: "{low|medium|high}"
+estimated_effort: "{XS|S|M|L|XL}"
+continue_token: ""
+---
 
-### 需求解读（5W1H）
+# Design: {功能名称}
+
+## 1. 需求解读（5W1H）
 | 维度 | 内容 |
 |------|------|
-| Who | {谁发起/谁受益} |
+| Who  | {谁发起/谁受益} |
 | What | {要做什么} |
-| Why | {业务价值/驱动因素} |
+| Why  | {业务价值/驱动因素} |
 | When | {预期上线时间/Sprint} |
 | Where | {涉及系统/服务范围} |
-| How | {核心实现思路} |
+| How  | {核心实现思路} |
 
-### 技术方案对比（3 个候选方案）
+## 2. 技术方案对比（3 个候选方案）
 
 | | 方案 A（推荐） | 方案 B | 方案 C |
 |---|---|---|---|
 | 实现思路 | ... | ... | ... |
-| 优点 | ... | ... | ... |
+| 优点     | ... | ... | ... |
 | 缺点/风险 | ... | ... | ... |
 | 实现成本 | ... | ... | ... |
 
-**推荐方案：方案 A**
+**推荐方案：方案 A**  
 理由：{1-2 句话}
 
-### 影响范围（方法级）
+## 3. 影响范围（方法级）
 | 文件 | 类/方法 | 变更类型 | 影响说明 |
 |------|--------|---------|---------|
 | {路径} | {类名.方法名} | 新增/修改/删除 | {说明} |
 
-### API 契约草稿
-{若有接口新增/修改，列出方法签名}
+## 4. API 契约草稿
+{若有接口新增/修改，列出方法签名和请求/响应结构}
+
+## 5. 数据模型变更（如有）
+{DDL 变更 / 实体字段新增 / 枚举定义}
 
-### 技术风险点
-| 风险 | 等级 | 应对方案 |
-|------|------|---------|
-| {风险描述} | P1/P2 | {方案} |
+## 6. 关键约束（来自项目宪法）
+- {constitution.hard_rules 中与本次相关的规则}
+
+## 7. 已知风险 ⚠️
+| 风险 | 等级 | 应对方案 | 来源 Skill |
+|------|------|---------|-----------|
+| {风险描述} | P1/P2 | {方案} | {Skill 名称} |
 
-### 估时
+## 8. 估时
 - 预估工作量：{XS/S/M/L/XL}（{N 个工作日}）
 - 主要耗时点：{1-2 句话}
+
+## 9. 相关文档
+- research.md: {存在时附路径，否则「已跳过（simple 复杂度）」}
+- tasks.md: {路径}
 ```
 
-**写入 HANDOFF frontmatter（design mode 专用字段）：**
+**更新 `.modus-state.yaml`：** `artifacts.design: done`，`artifacts.tasks: ready`
+
+**Artifact 2：`modus/plans/{name}/tasks.md`**
+
+生成 spec-kit 风格的带 T-ID 任务清单：
+
+```markdown
+# Tasks: {功能名称}
+> 来源：design.md | 生成时间：{YYYY-MM-DD}
+
+## Phase 1：数据层
+- [ ] T001 [P1] [Req:数据模型] 创建/修改 {表名} — `{路径/文件名}`
+- [ ] T002 [P1] [Req:数据模型] 新增 {MapperClass}#{method} — `{路径}`
+
+## Phase 2：服务层
+- [ ] T003 [P1] [Req:核心逻辑] 实现 {ManagerClass}#{method}（@Transactional） — `{路径}`
+- [ ] T004 [P2] [Req:核心逻辑] 单元测试：{TestClass}#{testMethod} — `{路径}`
+
+## Phase 3：接口层
+- [ ] T005 [P1] [Req:接口契约] 实现 {FacadeClass}#{method}（含参数校验） — `{路径}`
+- [ ] T006 [P2] [Req:接口契约] 接口测试：{TestClass}#{integrationTest} — `{路径}`
+
+## Phase 4：配套工作
+- [ ] T007 [P3] [Req:可观测性] 补充关键日志（入参/出参/异常） — `{路径}`
+```
+
+**任务格式规范（强制）：**
+- 任务 ID：`T{三位数字}`，在本 tasks.md 内唯一递增
+- 优先级：`[P1]`（必须完成）、`[P2]`（应该完成）、`[P3]`（建议完成）
+- 需求引用：`[Req:{简短描述}]`，对应 design.md 中的需求点
+- 文件路径：以 `— \`{相对路径}\`` 结尾（供 `--code` 模式快速定位）
+- 测试任务（含「测试」「Test」关键词）在同 phase 内置于实现任务之后
+
+**更新 `.modus-state.yaml`：** `artifacts.tasks: done`
 
-```yaml
----
-schema_version: "1.2"
-agent: "plan"
-design_mode: true
-status: "pending_review"
-risk_level: "{low|medium|high}"
-estimated_effort: "{XS|S|M|L|XL}"
-continue_token: ""
 ---
+
+#### Phase A：Analyze（自检一致性，只读）
+
+> **来源：speckit.analyze** — 禁止修改任何文件，仅输出内联分析报告
+
+**交叉检查 design.md × tasks.md：**
+
+| 检查项 | 说明 | 严重度 |
+|--------|------|--------|
+| 任务覆盖缺失 | design.md 中某需求点在 tasks.md 无对应任务 | HIGH |
+| 任务冗余 | tasks.md 中某任务无法追溯到 design.md 需求点 | MEDIUM |
+| 风险未对应任务 | design.md「已知风险」中 P1 风险无对应防护任务 | HIGH |
+| 估时与任务量不匹配 | 任务总量与估时明显不符（如 XS 却有 20+ 任务） | MEDIUM |
+| 关键约束未落地 | constitution.hard_rules 中某规则在任务中无体现 | HIGH |
+| 测试任务缺失 | Phase 2/3 无任何测试任务 | MEDIUM |
+
+**严重度处理规则：**
+- **HIGH** → 输出警告，列出具体缺失项，**暂停并询问用户是否修正**
+- **MEDIUM** → 列出建议，但**不阻塞**，继续到暂停节点
+- **LOW** → 仅记录，不展示
+
+**输出示例：**
+```
+🔍 一致性自检完成
+HIGH（需确认）：
+  ⚠️ design.md 第 7 节风险「并发写入需加分布式锁」在 tasks.md 中无对应任务
+     建议：在 Phase 2 新增 T00X [P1] 实现分布式锁保护
+MEDIUM（建议）：
+  ℹ️ Phase 3 缺少接口集成测试任务，建议补充
+
+是否根据以上建议更新 design.md / tasks.md？[Y/n]
 ```
 
-**输出并暂停：**
+- **用户确认修正** → 自动更新对应文件，重新执行 Phase A 检查
+- **用户跳过** → 直接进入暂停节点
+
+---
+
+#### Design Mode 暂停节点 ⏸️
 
 ```
-✅ 技术评审文档已生成：modus/plans/{name}/plan.md
-   设计模式：ON | 状态：pending_review | 风险：{level} | 估时：{effort}
+✅ 设计文档已就绪：modus/plans/{name}/
+   ├── research.md  — {已生成 | 已跳过（simple 复杂度）}
+   ├── design.md    — 待评审 | 风险：{level} | 估时：{effort}
+   └── tasks.md     — {N} 个任务（P1: {n1} / P2: {n2} / P3: {n3}）
 
 ──────────────────────────────────────────
-📋 评审文档包含：需求解读 / 3 个候选方案 / 影响范围 / API 草稿 / 风险点 / 估时
+📋 设计文档包含：5W1H / 3 个候选方案 / 方法级影响范围 / API 草稿 / 风险点 / 估时
+📋 任务清单：{N} 个带 T-ID 和优先级的任务，按 phase 分组
 
-⏸️ 等待人工技术评审。评审通过后运行：
-   /modus:plan --continue {name}
+⏸️ 等待人工技术评审。评审通过后可运行：
+   A. /modus:plan --continue {name}                    → 接力 harness 全流程开发
+   B. /modus:plan --code modus/plans/{name}/design.md  → 直接任务驱动编码
 ──────────────────────────────────────────
 ```
 
@@ -585,12 +733,15 @@ plan.md 生成后，展示结果并进入确认循环：
 modus/
 ├── plans/
 │   ├── add-batch-approve/           ← 活跃计划（未归档）
-│   │   ├── .modus-state.yaml        ← 状态文件（断点续跑用）
-│   │   └── plan.md                  ← 唯一规划文档（概述/风险/方案对比/Todos/影响文件）
+│   │   ├── .modus-state.yaml        ← 状态文件（含 artifacts DAG 状态）
+│   │   ├── plan.md                  ← 标准模式产出（概述/风险/方案对比/Todos/影响文件）
+│   │   ├── design.md                ← --design 模式产出（9 节技术设计文档）
+│   │   ├── tasks.md                 ← --design 模式产出（spec-kit T-ID 任务清单）
+│   │   └── research.md              ← --design 模式产出（复杂度 ≥ medium 时生成）
 │   └── archive/
 │       └── 2026-04-20-add-batch-approve/
 │           ├── .modus-state.yaml    ← status: archived
-│           └── plan.md
+│           └── plan.md / design.md / tasks.md / research.md
 ```
 
 ---
@@ -681,3 +832,140 @@ SA03 将读取 plan.md 中的「实现 Todos」作为代码开发计划。
 ```json
 {"ts":"{ISO8601}","type":"plan_relay","plan_name":"{name}","continue_token":"{token}","skipped_stages":["01-analysis","02-design"]}
 ```
+
+---
+
+## Code Mode 流程（--code 模式，独立完整流程）
+
+> **触发条件：** 用户运行 `/modus:plan --code <技术方案路径或描述>` 时进入此流程。
+> **来源：** opsx:apply contextFiles 状态机 + speckit.implement TDD 逐任务执行
+
+### Code Step 0：解析 [技术方案] 参数
+
+判断 `CODE_PLAN` 参数的输入类型并选择处理路径：
+
+```
+1. 文件路径（以 .md 结尾）→ FILE_MODE
+   - 读取该文件作为技术方案（design.md 或 plan.md）
+   - 在同目录查找 tasks.md
+
+2. 目录路径（以 / 结尾，或目录存在）→ DIR_MODE
+   - 在目录内按优先级查找主文档：design.md > plan.md
+   - 在同目录查找 tasks.md
+
+3. 内联描述（非路径字符串）→ INLINE_MODE
+   - 提示：
+     📋 未找到设计文档文件。建议：
+     A. 先运行 /modus:plan --design <描述> 生成设计文档，再运行 --code
+     B. 在此基础上继续，将自动生成简版 tasks.md（仅含基本任务结构）
+     请选择 [A/b]:
+   - 用户选 B 时：基于描述生成简版 tasks.md（跳过 research 和 design 阶段）
+```
+
+---
+
+### Code Step 1：加载上下文（contextFiles）
+
+按 opsx:apply 的 contextFiles 模式，依次读取：
+
+1. 技术方案主文档（design.md / plan.md）
+2. tasks.md（任务清单，含 checkbox 和 T-ID；若不存在则提示生成）
+3. research.md（若存在，作为代码上下文补充）
+4. `modus/config.yaml` constitution
+5. 相关业务 Skill（从 `knowledge-catalog.md` 按域匹配，仅 hash 检查，不触发全量更新）
+
+加载完成后输出上下文摘要：
+
+```
+📚 上下文加载完成
+   主文档：{design.md 路径}（{功能名称}）
+   任务清单：{tasks.md 路径}（共 {N} 个任务，已完成 {M} 个）
+   业务域：{domain1}, {domain2}
+   约束：{constitution.hard_rules 摘要}
+```
+
+---
+
+### Code Step 2：任务状态检查（state machine）
+
+扫描 tasks.md 中所有 `- [ ]` 和 `- [x]` 任务，计算状态：
+
+```
+state = all_done  → 所有任务已完成（无 [ ] 任务）
+state = blocked   → 存在依赖未满足（tasks.md 中存在 <!-- blocked: {原因} --> 注释）
+state = ready     → 存在可执行的待完成任务
+```
+
+| state | 输出 |
+|-------|------|
+| `all_done` | ✅ 所有 {N} 个任务已完成！建议运行 `/modus:cr --doc {design.md 路径}` 进行代码评审 |
+| `blocked` | ⚠️ 发现阻塞：{阻塞原因}。请先解决阻塞再继续 |
+| `ready` | 展示待执行任务列表，确认后进入 Step 3 |
+
+**state=ready 时的确认输出：**
+
+```
+📋 待执行任务（{N} 个）：
+Phase {X}：{phase 名称}
+  ○ T001 [P1] {任务描述} — {文件路径}
+  ○ T002 [P1] {任务描述} — {文件路径}
+  ○ T003 [P2] {任务描述（测试）} — {文件路径}
+
+共 {M} 个 Phase，{N} 个任务（P1: {n1} / P2: {n2} / P3: {n3}）
+是否开始执行？[Y/n]（--force 时自动确认）
+```
+
+---
+
+### Code Step 3：分 Phase 逐任务执行
+
+> **TDD 原则（来自 speckit.implement）：** 同 Phase 内先实现接口/类签名，再写测试，最后完善实现。
+
+**Phase 执行循环：**
+
+```
+for each Phase（按顺序）:
+  输出：── Phase {X}：{phase 名称}（{N} 个任务）──
+  
+  for each Task in Phase（按 T-ID 顺序）:
+    if 任务含「测试」「Test」关键词:
+      ← 先建类/方法骨架，再写测试，最后补全逻辑
+    else:
+      ← 根据 design.md 对应需求点和 business Skill 直接实现代码
+
+    执行完成后：
+      1. 将 tasks.md 中该任务的 `- [ ]` 改为 `- [x]`
+      2. 输出：✓ {T-ID} 已完成：{一句话说明变更内容}
+      3. 重新检查 state（出现 blocked 时暂停并说明原因）
+
+  Phase 完成后输出：
+  ✅ Phase {X} 完成（{已完成数}/{Total} 个任务）
+```
+
+**单任务执行规范：**
+- 根据任务的 `— \`{路径}\`` 定位目标文件
+- 参考 design.md 中 `[Req:{...}]` 对应的需求点作为实现依据
+- 遵循 constitution.hard_rules 和业务 Skill 中的 `[guideline]`/`[pitfall]`
+- 遵循「外科手术式修改（Surgical Changes）」原则：只改必改的文件
+
+---
+
+### Code Step 4：完成确认 + 后续建议
+
+所有 Phase 完成后输出：
+
+```
+🎉 编码完成！执行摘要：
+  ✅ 共完成 {N} 个任务（P1: {n1} / P2: {n2} / P3: {n3}）
+  📝 修改文件：{已修改文件列表}
+  ⏱️  实际耗时对比：设计估时 {effort}
+
+── 建议后续操作 ──────────────────────────────────
+  A. /modus:cr --doc {design.md 路径}    → 代码评审（推荐）
+  B. /modus:plan --continue {name}        → 接力 harness 完整流程
+  C. /modus:vibe                          → 修复评审后的问题
+────────────────────────────────────────────────
+```
+
+**后置知识回写（与标准 plan Step 9 相同逻辑）：**
+扫描编码过程中新发现的 pitfall/decision，询问用户是否写回 Skill（不强制）。