@modus-ai/modus 0.2.11 → 0.3.1

package/templates/template/pid.md

@@ -0,0 +1,97 @@
+# PID — 需求澄清（Product Intent Definition）
+
+> **生成位置**：`modus/artifacts/<STORY_ID>/pid/prd.md`
+> **生成命令**：`/modus:plan --pid <tapd-url>` 或 Harness Loop1 SubAgent00（modus-analyst）
+
+---
+
+## 元信息
+
+```yaml
+story_id: ""              # TAPD Story ID
+tapd_url: ""              # TAPD 原始链接
+created_at: ""            # ISO8601
+updated_at: ""            # ISO8601
+status: "draft"           # draft | confirmed | implemented | archived
+priority: "P2"            # P0 | P1 | P2 | P3
+related_stories: []       # 历史关联需求 ID（用于产物复用）
+domain: ""                # 关联业务域（如 contract, copyright）
+```
+
+---
+
+## 1. 业务背景
+
+> 用一段话说清楚：这次需求**为谁解决什么问题**、**为什么现在做**、**不做会怎样**。
+
+（待填充）
+
+---
+
+## 2. 需求范围（变更/不变更对比）
+
+### 2.1 本次变更范围
+- ✅ 新增：（如：歌手等级评定接口、艺人画像扩展字段）
+- ✏️ 修改：（如：现有歌手详情接口返回字段）
+- ❌ 删除：（如：废弃旧 v1 接口）
+
+### 2.2 明确不变更范围（边界声明）
+> 防止过度发散。把容易被误以为要改的、但本次绝不改的列出来。
+
+- 现有 XXX 流程不变
+- YYY 接口签名不变
+- 数据库表 ZZZ 结构不变
+
+---
+
+## 3. 验收标准（Acceptance Criteria）
+
+> 必须可被 spec 命令转化为 Gherkin。每条用「Given-When-Then」可表述。
+
+| AC ID | 场景 | Given | When | Then |
+|-------|------|-------|------|------|
+| AC-01 | 正向主流程 |  |  |  |
+| AC-02 | 异常处理 |  |  |  |
+| AC-03 | 边界值 |  |  |  |
+
+---
+
+## 4. 利益相关方（Stakeholders）
+
+| 角色 | 姓名 | 关注点 |
+|------|------|-------|
+| 产品 |  |  |
+| 后端 |  |  |
+| 前端 |  |  |
+| 测试 |  |  |
+| 运营 |  |  |
+
+---
+
+## 5. 澄清记录（Dialog History 索引）
+
+> 详细对话归档于 `pid/dialog/`，本节只列要点。
+
+| 日期 | 议题 | 决议 | 详细对话文件 |
+|------|------|------|-------------|
+|  |  |  | `dialog/2026-MM-DD-topic.md` |
+
+---
+
+## 6. 风险与未决事项（Open Questions）
+
+- ⚠️ （未澄清的关键点，需在 design 阶段前关闭）
+
+---
+
+## 7. 历史关联（Related Stories）
+
+> 如发现历史需求与本次相似，复用其产物：
+
+| Story ID | 相似度 | 可复用产物 |
+|----------|--------|-----------|
+|  | （高/中/低） | `modus/artifacts/<id>/code/spec/` 等 |
+
+---
+
+> **维护规则**：本模板由 `/modus:plan --pid` 或 modus-analyst 自动填充。人工补充时请保留章节结构；新增章节请标注 `> [人工新增]` 注释。

package/templates/template/plan.md

@@ -0,0 +1,91 @@
+# Plan — 实施计划模板
+
+> **生成位置**：`modus/artifacts/<STORY_ID>/code/plan.md`
+> **生成命令**：`/modus:plan --story <id>` 或独立模式 `/modus:plan <task>`
+
+---
+
+## 元信息
+
+```yaml
+story_id: ""
+pid_ref: "modus/artifacts/<STORY_ID>/pid/prd.md"
+design_ref: "modus/artifacts/<STORY_ID>/design/design.md"
+created_at: ""
+status: "ready"           # ready | in-progress | done
+estimated_effort_hours: 0
+risk_level: "low"         # low | medium | high
+```
+
+---
+
+## 1. 目标摘要
+
+> 一段话：本计划要做什么、不做什么。
+
+---
+
+## 2. 上下文加载（Context Bundle）
+
+| Skill | 路径 | 关键摘录 |
+|-------|------|---------|
+| 业务域 | `modus/knowledge_base/domain/<domain>/code/SKILL.md` |  |
+| 团队约定 | `modus/knowledge_base/domain/_conventions/code/SKILL.md` |  |
+| 技术 Wiki | `modus/knowledge_base/domain/_tech-wiki/code/SKILL.md` |  |
+
+---
+
+## 3. 任务拆分（步骤化，禁止小数步骤）
+
+> 每步必须满足：① 单一职责 ② 可独立验证 ③ 失败可回滚
+
+| 步骤 | 描述 | 涉及文件 | 验证方式 | 预估耗时 |
+|------|------|---------|---------|---------|
+| 1 |  |  |  |  |
+| 2 |  |  |  |  |
+| 3 |  |  |  |  |
+
+---
+
+## 4. 文件变更清单
+
+| 路径 | 变更类型 | 说明 |
+|------|---------|------|
+|  | 新增/修改/删除 |  |
+
+---
+
+## 5. 接口契约（与 design.md 一致）
+
+| 接口 | 入参 | 出参 | 错误码 |
+|------|------|------|-------|
+|  |  |  |  |
+
+---
+
+## 6. 测试计划
+
+- 单元测试覆盖：
+- 集成验证步骤：
+- 回归范围：
+
+---
+
+## 7. 风险与回滚
+
+| 风险 | 触发条件 | 缓解措施 | 回滚方案 |
+|------|---------|---------|---------|
+|  |  |  |  |
+
+---
+
+## 8. 验收清单（DoD）
+
+- [ ] 全部步骤完成且单测通过
+- [ ] CR 报告状态为 PASS
+- [ ] spec 全部场景绿
+- [ ] 文档/CHANGELOG 更新
+
+---
+
+> **维护规则**：plan 由 `/modus:plan` 命令生成；step 编号严格自然数；任何小数步骤（如 1.1, 1.2）需重构为独立顶级步骤。

package/templates/template/spec.md

@@ -0,0 +1,78 @@
+# Spec — Gherkin 验收规格模板
+
+> **生成位置**：`modus/artifacts/<STORY_ID>/code/spec/{feature}.feature.md`
+> **生成命令**：`/modus:spec --story <id>`
+
+---
+
+## 元信息
+
+```yaml
+story_id: ""
+pid_ref: "modus/artifacts/<STORY_ID>/pid/prd.md"
+design_ref: "modus/artifacts/<STORY_ID>/design/design.md"
+feature_name: ""
+created_at: ""
+mode: "delta"             # full | delta（v3.2+ 增量模式）
+```
+
+---
+
+## Feature 描述
+
+```gherkin
+# language: zh-CN
+功能: <feature_name>
+
+  作为 <角色>
+  我想要 <做什么>
+  以便 <达成什么价值>
+
+  # ---- 主流程 ----
+  场景: 主流程成功
+    假设 <前置条件>
+    当 <触发动作>
+    那么 <预期结果>
+    并且 <附加结果>
+
+  # ---- 异常流程 ----
+  场景: <异常分支说明>
+    假设 <异常前置条件>
+    当 <触发动作>
+    那么 <异常处理结果>
+
+  # ---- 边界值 ----
+  场景大纲: <参数化场景>
+    假设 输入参数 <param>
+    当 调用接口
+    那么 结果应为 <expected>
+
+    例子:
+      | param | expected |
+      |       |          |
+```
+
+---
+
+## AC 映射表
+
+> 每条 AC 必须有对应场景；每个场景必须可被自动化用例覆盖。
+
+| AC ID（来自 PID） | 场景名 | 覆盖类型 | 自动化用例路径 |
+|------------------|--------|---------|--------------|
+| AC-01 |  | 主流程 |  |
+| AC-02 |  | 异常 |  |
+
+---
+
+## 增量变更说明（delta 模式必填）
+
+| 变更类型 | 描述 |
+|---------|------|
+| 新增场景 |  |
+| 修改场景 |  |
+| 删除场景 |  |
+
+---
+
+> **维护规则**：spec 命令默认 delta 模式，仅追加变更场景；fullsweep 模式重写全部。

package/templates/template/sprint-contract.md

@@ -0,0 +1,101 @@
+# Sprint Contract — Harness Loop2 契约模板
+
+> **生成位置**：`modus/artifacts/<STORY_ID>/code/sprint-contract.md`
+> **生成命令**：Harness Loop2 SubAgent03（modus-developer）启动时
+
+---
+
+## 元信息
+
+```yaml
+story_id: ""
+sprint_id: ""             # 形如 SPRINT-001 / SPRINT-002
+agent: "modus-developer"
+schema_version: "1.1"
+created_at: ""
+plan_ref: "modus/artifacts/<STORY_ID>/code/plan.md"
+spec_ref: "modus/artifacts/<STORY_ID>/code/spec/"
+design_ref: "modus/artifacts/<STORY_ID>/design/design.md"
+gate_status: "open"       # open | passed | failed
+```
+
+---
+
+## 1. Sprint 范围
+
+| 步骤（来自 plan） | 状态 | 负责文件 |
+|-----------------|------|---------|
+| Step 1 |  |  |
+| Step 2 |  |  |
+
+---
+
+## 2. 输入契约（Input Contract）
+
+> Harness Gate 检查项：所有依赖必须就绪后才能进入实施。
+
+- [ ] plan.md 存在且 status=ready
+- [ ] design.md 存在且 status=approved
+- [ ] spec/ 目录存在且场景非空
+- [ ] 业务域 Skill 已加载：`modus/knowledge_base/domain/<domain>/code/SKILL.md`
+- [ ] CR 工具就绪（modus-reviewer）
+
+---
+
+## 3. 输出契约（Output Contract）
+
+> Sprint 结束时必须满足：
+
+- [ ] 所有计划步骤代码合入
+- [ ] spec 场景绿（自动化用例通过）
+- [ ] cr-report.md 产出且 status=PASS
+- [ ] vibe-log.md 完整记录变更
+- [ ] 单元测试覆盖率 ≥ 既定阈值
+
+---
+
+## 4. 边界声明
+
+> 本 Sprint **不涉及**：（防止越界）
+- ...
+
+---
+
+## 5. 失败处理
+
+| 失败类型 | 处理方式 |
+|---------|---------|
+| spec 场景不绿 | 回到 modus-developer 修复，最多 3 轮 |
+| CR 报告 FAIL | 触发 modus-reviewer 详细分析，标记 needs-human |
+| 测试覆盖不足 | 触发 modus-tester 补测试 |
+
+---
+
+## 6. 状态机变更日志
+
+| 时间 | 状态 | 触发者 | 备注 |
+|------|------|-------|------|
+|  |  |  |  |
+
+---
+
+## HANDOFF（schema v1.1）
+
+```yaml
+schema_version: "1.1"
+from: "modus-developer"
+to: "modus-reviewer"
+story_id: ""
+sprint_id: ""
+status: "ready_for_review"
+artifacts:
+  - "modus/artifacts/<STORY_ID>/code/sprint-contract.md"
+checkpoints:
+  spec_passed: false
+  cr_required: true
+issues: []
+```
+
+---
+
+> **维护规则**：sprint-contract 是 Harness Loop2 的"工作合同"；任何契约变更必须更新本文件并刷新 `.harness-state.yaml`。