@modus-ai/modus 0.2.10 → 0.3.0

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

@@ -43,7 +43,7 @@ disable: false
 --enhance X  → ENHANCE_DOMAIN=X（Step 3 前先增量更新该域 Skill）
 --file X     → FOCUS_FILE=X（Step 3 从该文件推断域，而非 prompt 匹配）
 --no-design  → SKIP_DESIGN=true（跳过 Step 6 Design Brief）
---story X    → STORY_ID=X（Step 9 日志写入 modus/stories/{X}/vibe-log.md）
+--story X    → STORY_ID=X（Step 9 日志写入 modus/artifacts/{X}/code/vibe-log.md）
 --dry-run    → DRY_RUN=true（Step 7 只输出设计，不生成代码）
 --watch      → WATCH_MODE=true（Step 10 启用文件监听，实验性）
 --codex      → CODEX_MODE=true（禁用交互提问，全批量推断输出）
@@ -75,7 +75,7 @@ constitution:
 
 ### Step 1：Level 1 加载——读知识目录（~200 tokens）
 
-读取 `modus/knowledge-catalog.md`（全景目录索引）：
+读取 `modus/knowledge_base/map.md`（全景目录索引）：
 - 了解当前项目有哪些可用的 Skill
 - 识别各 Skill 的 maturity 状态、最近引用时间
 - 为 Step 2 的智能分析做准备
@@ -83,7 +83,7 @@ constitution:
 **如果 `knowledge-catalog.md` 不存在：**
 
 ```
-⚠️ 未找到知识目录（modus/knowledge-catalog.md）
+⚠️ 未找到知识目录（modus/knowledge_base/map.md）
 
 建议先运行 /modus:init 初始化知识库，可以让 AI 更准确地理解项目。
 
@@ -233,10 +233,10 @@ Codex 模式：所有同步静默执行，不输出状态行（减少干扰）
 
 **路径规则（v3.1 Single Source of Truth）：**
 ```
-modus/knowledge/biz-{domain}/SKILL.md
+modus/knowledge_base/domain/{domain}/code/SKILL.md
 ```
 
-例如：`modus/knowledge/biz-order/SKILL.md`、`modus/knowledge/biz-payment/SKILL.md`
+例如：`modus/knowledge_base/biz-order/SKILL.md`、`modus/knowledge_base/biz-payment/SKILL.md`
 
 > **注意**：`.codebuddy/skills/modus-biz-{domain}/SKILL.md` 为旧路径引用桩，已废弃，请勿使用。
 
@@ -285,7 +285,7 @@ modus/knowledge/biz-{domain}/SKILL.md
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ## 实现蓝图
-Data:    {Mapper 类/方法}（路径: modus/knowledge/biz-{domain}/SKILL.md → 关键文件索引）
+Data:    {Mapper 类/方法}（路径: modus/knowledge_base/domain/{domain}/code/SKILL.md → 关键文件索引）
 Service: {Manager/Service 类/方法，标注 @Transactional 位置}
 API:     {Facade/Controller 类/方法}
 
@@ -383,7 +383,7 @@ Codex 模式下，每个文件生成前输出分隔符：`=== 生成文件: {pat
 #### 执行方式
 
 ```
-有新知识 → 写入 modus/knowledge/biz-{domain}/SKILL.md（v3.1 路径）
+有新知识 → 写入 modus/knowledge_base/domain/{domain}/code/SKILL.md（v3.1 路径）
           → 写入完成后输出单行提示：
             [已更新 {domain} 域知识: 新增 [pitfall] {摘要} / 更正 [model] {字段名}]
 
@@ -402,7 +402,7 @@ Codex 模式下，每个文件生成前输出分隔符：`=== 生成文件: {pat
 
 编码完成后，将本次会话**追加**（append-only，禁止覆盖原有内容）到日志文件：
 
-- 若 STORY_ID 已设置：写入 `modus/stories/{STORY_ID}/vibe-log.md`
+- 若 STORY_ID 已设置：写入 `modus/artifacts/{STORY_ID}/code/vibe-log.md`
 - 否则：写入 `modus/sessions/vibe-log.md`
 
 ```markdown
@@ -514,7 +514,7 @@ Codex 平台与 Cursor 的核心差异及适配方式：
   --enhance <domain>     编码前先对指定域执行增量 Skill 更新（如 --enhance album）
   --file <path>          聚焦单文件：从该文件推断域，只加载相关 Skill
   --no-design            跳过 Design Brief 内联设计（极速模式，仅适合单行改动）
-  --story <id>           关联 TAPD Story ID，将编码日志写入 modus/stories/{id}/vibe-log.md
+  --story <id>           关联 TAPD Story ID，将编码日志写入 modus/artifacts/{id}/code/vibe-log.md
   --dry-run              只输出 Design Brief，不生成实际代码（用于方案确认）
   --watch                持续监听文件变化，触发 save-driven vibe coding（实验性）
   --codex                Codex 平台模式：禁用交互提问，全批量推断输出，自动推断所有决策
@@ -531,7 +531,7 @@ Codex 平台与 Cursor 的核心差异及适配方式：
   /modus:vibe 实现艺人等级更新 --codex --story 9876543
 
 业务知识路径（v3.1）：
-  modus/knowledge/biz-{domain}/SKILL.md
+  modus/knowledge_base/domain/{domain}/code/SKILL.md
 
 相关命令：
   /modus:init    初始化/更新知识库（首次使用前建议先跑）

package/templates/template/analysis.md

@@ -0,0 +1,83 @@
+# Analysis — Harness Loop1 分析报告模板
+
+> **生成位置**：（v3.2 旧）`modus/stories/<id>/harness/01-analysis.md`
+> **生成位置**：（v4.0 新）通常拆为 `modus/artifacts/<id>/pid/prd.md` + `modus/artifacts/<id>/design/design.md`
+> 当只需轻量分析（不区分 PID/Design）时，使用本模板，置于 `modus/artifacts/<id>/pid/analysis.md`
+> **生成命令**：Harness Loop1 SubAgent00（modus-analyst）
+
+---
+
+## 元信息
+
+```yaml
+story_id: ""
+agent: "modus-analyst"
+schema_version: "1.1"
+created_at: ""
+input:
+  tapd_url: ""
+  prd_attachments: []
+output:
+  next_subagent: "modus-designer"
+  handoff_block: "see HANDOFF below"
+```
+
+---
+
+## 1. 需求理解
+
+### 1.1 一句话总结
+
+### 1.2 详细需求（结构化）
+- **谁**：（用户角色）
+- **做什么**：（业务动作）
+- **价值**：（业务价值）
+- **场景**：（典型场景）
+
+---
+
+## 2. 关键信息抽取
+
+| 字段 | 值 | 来源 |
+|------|-----|------|
+| 优先级 |  | TAPD/产品 |
+| 截止日期 |  |  |
+| 涉及模块 |  |  |
+
+---
+
+## 3. 不确定项（必须澄清后才能进入 Design）
+
+| 不确定点 | 影响范围 | 候选方案 | 推荐 |
+|---------|---------|---------|------|
+|  |  |  |  |
+
+---
+
+## 4. 历史相似需求
+
+| Story ID | 相似度 | 差异点 |
+|----------|--------|-------|
+|  |  |  |
+
+---
+
+## HANDOFF（schema v1.1）
+
+```yaml
+schema_version: "1.1"
+from: "modus-analyst"
+to: "modus-designer"
+story_id: ""
+status: "ready_for_design"
+artifacts:
+  - "modus/artifacts/<id>/pid/prd.md"
+checkpoints:
+  unresolved_questions: []
+  related_stories: []
+issues: []
+```
+
+---
+
+> **维护规则**：本模板仅用于 Harness Loop1 内部 handoff；最终用户阅读产物以 `pid/prd.md` 为准。

package/templates/template/design.md

@@ -0,0 +1,160 @@
+# Design — 技术评估设计
+
+> **生成位置**：`modus/artifacts/<STORY_ID>/design/design.md`
+> **生成命令**：`/modus:plan --design <pid-path>` 或 Harness Loop1 SubAgent01.5（modus-designer）
+
+---
+
+## 元信息
+
+```yaml
+story_id: ""
+pid_ref: "modus/artifacts/<STORY_ID>/pid/prd.md"
+created_at: ""
+updated_at: ""
+status: "draft"           # draft | reviewed | approved | implemented
+reviewers: []             # 评审人列表
+related_designs: []       # 历史可复用设计
+```
+
+---
+
+## 1. 设计目标
+
+> 一段话：本次方案要达到的技术目标 + 与 PID 验收标准的对应关系。
+
+---
+
+## 2. 整体架构
+
+### 2.1 上下游关系
+```mermaid
+graph LR
+  A[上游系统] --> B[本服务]
+  B --> C[下游系统]
+```
+
+### 2.2 涉及模块清单
+
+| 模块 | 是否新增 | 变更类型 | 说明 |
+|------|---------|---------|------|
+|  |  | （新增/修改/删除） |  |
+
+---
+
+## 3. 接口设计
+
+### 3.1 对外暴露接口
+
+| 接口名 | 类型 | 路径/Topic | 是否新增 | 入参 | 出参 |
+|-------|------|-----------|---------|------|------|
+|  | HTTP/MQ/RPC |  |  |  |  |
+
+### 3.2 调用下游接口
+
+| 下游服务 | 接口 | 调用频率 | 超时 | 重试策略 | 降级方案 |
+|---------|------|---------|------|---------|---------|
+|  |  |  |  |  |  |
+
+> ⚠️ **超时必填**：每个下游调用必须明确写出超时时间和重试次数，不接受"按默认"。
+
+---
+
+## 4. 数据模型
+
+### 4.1 新增/修改的表
+
+| 表名 | 字段 | 类型 | 是否索引 | 说明 |
+|------|------|------|---------|------|
+|  |  |  |  |  |
+
+### 4.2 数据迁移
+
+- 是否需要迁移：（是/否）
+- 迁移方式：（脚本/在线 DDL/双写切流）
+- 回滚方案：
+
+---
+
+## 5. 状态流转（如适用）
+
+```mermaid
+stateDiagram-v2
+  [*] --> 待审核
+  待审核 --> 已通过
+  待审核 --> 已驳回
+  已通过 --> [*]
+  已驳回 --> [*]
+```
+
+| 状态 | 流入条件 | 流出条件 | 副作用 |
+|------|---------|---------|--------|
+|  |  |  |  |
+
+---
+
+## 6. 边界控制
+
+> 明确**本设计不解决**的问题，以及**与既有设计冲突点**的解决方案。
+
+- ❌ 不解决：（如：跨地域容灾，由基础设施层兜底）
+- ⚠️ 冲突点：与 XXX 模块的 YYY 字段语义存在歧义，约定使用 ZZZ
+- 🛡️ 兜底：当下游 A 不可用时，降级返回 B 的默认值
+
+---
+
+## 7. 性能与并发
+
+| 维度 | 目标 | 风险点 | 缓解措施 |
+|------|------|-------|---------|
+| QPS |  |  |  |
+| P99 延迟 |  |  |  |
+| 并发锁 |  |  |  |
+| 缓存穿透 |  |  |  |
+
+---
+
+## 8. 安全与合规
+
+- 鉴权方式：
+- 数据脱敏：
+- 审计日志：
+
+---
+
+## 9. 测试策略
+
+- 单元测试：
+- 集成测试：
+- 性能测试：
+- 灰度方案：
+
+---
+
+## 10. 实施步骤（高阶）
+
+> 仅描述大步骤；细粒度步骤在 plan.md 中展开。
+
+1. （步骤一）
+2. （步骤二）
+3. （步骤三）
+
+---
+
+## 11. 历史可复用资产
+
+| 来源 Story | 可复用内容 | 复用路径 |
+|-----------|-----------|---------|
+|  |  | `modus/artifacts/<id>/design/design.md` |
+
+---
+
+## 12. 评审记录
+
+| 日期 | 评审人 | 关键意见 | 决议 |
+|------|-------|---------|------|
+|  |  |  |  |
+
+---
+
+> **维护规则**：本模板由 modus-designer 自动填充第 1-10 节；评审记录由人工填写。

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`。