@modus-ai/modus 0.2.7 → 0.2.9

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

@@ -1,6 +1,6 @@
 ---
 name: modus-plan
-description: Use this skill when executing /modus:plan command to generate a single structured plan.md backed by up-to-date business Skills. Trigger on /modus:plan command or when user wants to plan a feature with full business context. Loads Skill domains first, falls back to platform rules + source scan, then asks 0-3 targeted questions (no padding — only ask when truly needed) before generating the plan. Ends with a Build confirmation loop where user can iterate on plan.md before executing code generation.
+description: Use this skill when executing /modus:plan command to generate a single structured plan.md backed by up-to-date business Skills. Trigger on /modus:plan command or when user wants to plan a feature with full business context. Loads Skill domains first, falls back to platform rules + source scan, then asks 0-3 targeted questions (no padding — only ask when truly needed) before generating the plan. Ends with a Build confirmation loop where user can iterate on plan.md before executing code generation. Also handles --design mode (design-review-only, no code gen) and --continue mode (relay plan.md to harness).
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
@@ -13,6 +13,45 @@ disable: false
 
 功能规划入口。通过**两层知识检索**获取业务上下文，先评估需求复杂度自动分级（simple/medium/complex），再基于加载的知识向用户提出 0–3 个精准澄清问题（按需提问，禁止凑数），最终生成单一 `plan.md` 规划文档。文档生成后进入 Build 确认循环，用户可反复修改直至满意后触发代码执行，并将本次规划中的新知识回写到 Skill（后置更新）。
 
+支持两种特殊模式（v4.0 新增）：
+- **`--design` 设计评审模式**：仅生成技术评审文档，`status: pending_review`，不触发代码生成
+- **`--continue <name>` 接力模式**：读取已批准的 plan.md，直接接力触发 `harness --from-plan`
+
+---
+
+## 参数解析（优先执行，Step 0 之前）
+
+**首先**检测用户输入中的参数标志，决定执行路径：
+
+```
+--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（多项目指定）
+--enhance X   → ENHANCE_DOMAIN=X（前置强制刷新指定域 Skill）
+--no-build    → NO_BUILD=true（生成 plan.md 后跳过 Build 循环）
+--read-only   → READ_ONLY=true（同 NO_BUILD，永远不触发代码生成）
+--resume X    → RESUME_NAME=X（断点续跑）
+--complexity X → FORCED_COMPLEXITY=X
+```
+
+**路由决策树：**
+
+```
+检测到 --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（生成 design.md + tasks.md 后暂停）
+  否 → 执行标准流程（Step 0 → Step 9）
+```
+
 ---
 
 ## 执行流程
@@ -348,6 +387,233 @@ created: {ISO8601时间戳}
 
 ---
 
+### 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」再进入设计
+
+**复杂度 ≥ 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: ""
+---
+
+# Design: {功能名称}
+
+## 1. 需求解读（5W1H）
+| 维度 | 内容 |
+|------|------|
+| Who  | {谁发起/谁受益} |
+| What | {要做什么} |
+| Why  | {业务价值/驱动因素} |
+| When | {预期上线时间/Sprint} |
+| Where | {涉及系统/服务范围} |
+| How  | {核心实现思路} |
+
+## 2. 技术方案对比（3 个候选方案）
+
+| | 方案 A（推荐） | 方案 B | 方案 C |
+|---|---|---|---|
+| 实现思路 | ... | ... | ... |
+| 优点     | ... | ... | ... |
+| 缺点/风险 | ... | ... | ... |
+| 实现成本 | ... | ... | ... |
+
+**推荐方案：方案 A**  
+理由：{1-2 句话}
+
+## 3. 影响范围（方法级）
+| 文件 | 类/方法 | 变更类型 | 影响说明 |
+|------|--------|---------|---------|
+| {路径} | {类名.方法名} | 新增/修改/删除 | {说明} |
+
+## 4. API 契约草稿
+{若有接口新增/修改，列出方法签名和请求/响应结构}
+
+## 5. 数据模型变更（如有）
+{DDL 变更 / 实体字段新增 / 枚举定义}
+
+## 6. 关键约束（来自项目宪法）
+- {constitution.hard_rules 中与本次相关的规则}
+
+## 7. 已知风险 ⚠️
+| 风险 | 等级 | 应对方案 | 来源 Skill |
+|------|------|---------|-----------|
+| {风险描述} | P1/P2 | {方案} | {Skill 名称} |
+
+## 8. 估时
+- 预估工作量：{XS/S/M/L/XL}（{N 个工作日}）
+- 主要耗时点：{1-2 句话}
+
+## 9. 相关文档
+- research.md: {存在时附路径，否则「已跳过（simple 复杂度）」}
+- tasks.md: {路径}
+```
+
+**更新 `.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`
+
+---
+
+#### 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}/
+   ├── research.md  — {已生成 | 已跳过（simple 复杂度）}
+   ├── design.md    — 待评审 | 风险：{level} | 估时：{effort}
+   └── tasks.md     — {N} 个任务（P1: {n1} / P2: {n2} / P3: {n3}）
+
+──────────────────────────────────────────
+📋 设计文档包含：5W1H / 3 个候选方案 / 方法级影响范围 / API 草稿 / 风险点 / 估时
+📋 任务清单：{N} 个带 T-ID 和优先级的任务，按 phase 分组
+
+⏸️ 等待人工技术评审。评审通过后可运行：
+   A. /modus:plan --continue {name}                    → 接力 harness 全流程开发
+   B. /modus:plan --code modus/plans/{name}/design.md  → 直接任务驱动编码
+──────────────────────────────────────────
+```
+
+⏸️ **等待人工确认** — 此时**不触发任何代码生成**，整个 Design Mode 流程到此结束。
+
+---
+
 ### Step 8：Build 确认循环 ⏸️ 【人工审批节点】
 
 plan.md 生成后，展示结果并进入确认循环：
@@ -467,10 +733,239 @@ 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
+```
+
+---
+
+## Continue 流程（--continue 模式，独立完整流程）
+
+> **触发条件：** 用户运行 `/modus:plan --continue <name>` 时进入此流程。
+
+### Continue Step 1：读取 plan.md 并验证状态
+
+```
+读取 modus/plans/{name}/plan.md 的 HANDOFF frontmatter：
+  → 检查 design_mode = true（不是 design 模式的 plan 不能用 --continue）
+  → 检查 status ∈ {pending_review, approved}（已完成或已 continued 的不重复触发）
+  → 若 status = continued：提示「此 plan 已接力，是否重新触发？[y/N]」
+
+若 plan.md 不存在 → 报错：
+  ❌ 未找到 plan：modus/plans/{name}/plan.md
+     请先运行 /modus:plan --design 生成技术评审文档
+```
+
+### Continue Step 2：展示接力确认
+
+```
+准备接力 harness：
+
+📋 plan：{name}
+   状态：{pending_review → 即将变更为 approved}
+   业务域：{domains}
+   风险等级：{risk_level}
+   估时：{estimated_effort}
+
+⚡ 接力后将跳过：SA01（需求分析）+ SA02（设计方案）
+   直接从：SA03 代码开发 开始
+
+SA03 将读取 plan.md 中的「实现 Todos」作为代码开发计划。
+是否确认接力？[Y/n]（--force 时自动确认）
+```
+
+### Continue Step 3：生成 continue_token 并更新状态
+
+```
+生成 continue_token：{name}:{YYYYMMDD}
+更新 plan.md frontmatter：
+  status: "approved" → 写入后立即变更为 "continued"
+  continue_token: "{name}:{YYYYMMDD}"
+
+写入 .modus-state.yaml：
+  status: continued
+  continued_at: {ISO8601 时间戳}
+  harness_triggered: true
+```
+
+### Continue Step 4：接力触发 harness
+
+输出启动提示：
+
+```
+🚀 plan --continue 接力启动
+   规划文件：modus/plans/{name}/plan.md
+   传递标记：[FROM_PLAN: {name} | token: {continue_token}]
+   跳过阶段：SA01（需求分析）+ SA02（设计方案）
+   直接启动：SA03 代码开发
+
+启动 /modus:harness --from-plan {name}...
+```
+
+以如下格式构造 harness 的入参（在**当前上下文中**直接继续执行 modus-harness Skill）：
+
+```
+/modus:harness --from-plan {name}
+
+传递上下文：
+  plan_file: modus/plans/{name}/plan.md
+  continue_token: {token}
+  domains: {plan.md 中的 domains}
+  constitution: {当前 config.yaml constitution}
+  skip_agents: ["01", "02"]
+```
+
+`modus-harness` Skill 检测到 `--from-plan` 时，读取 plan.md 中的以下内容作为 SA03 的输入：
+- 「实现 Todos」→ 作为代码开发计划（替代 01-analysis.md + 02-design-brief.md 中的 Sprint 拆分）
+- 「技术方案评审 → 推荐方案」→ 作为架构决策（替代 SA02 的设计方案）
+- 「已知风险」→ 传递给 SA07（代码评审）作为审查重点
+
+### Continue Step 5：写入进度事件（若 events.jsonl 存在）
+
+```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（不强制）。