@modus-ai/modus 0.2.10 → 0.3.0

package/templates/rules/modus-workflow/RULE.mdc

@@ -1,59 +1,66 @@
 ---
-description: Modus workflow conventions. Load this rule when the user runs any /modus:* command or asks about Modus commands, Skills, Harness, plan/spec/vibe workflow, knowledge-catalog, or business Skills.
+description: Modus workflow conventions (v4.0). Load this rule when the user runs any /modus:* command or asks about Modus commands, Skills, Harness, plan/spec/vibe workflow, knowledge_base, artifacts, or business Skills.
 alwaysApply: false
 enabled: true
 ---
 
-# Modus 工作流规范
+# Modus 工作流规范（v4.0）
+
+> 完整路径范式见 `templates/paths-v4.md`。
 
 ## 核心目录结构
 
 ```
-.codebuddy/
-├── skills/
-│   ├── modus-init/SKILL.md          # /modus:init 执行规范
-│   ├── modus-vibe/SKILL.md          # /modus:vibe 执行规范
-│   ├── modus-plan/SKILL.md          # /modus:plan 执行规范
-│   ├── modus-spec/SKILL.md          # /modus:spec 执行规范
-│   ├── modus-harness/SKILL.md       # Harness 调度规范
-│   ├── modus-harness-0*-*/SKILL.md  # Harness SubAgent 规范
-│   ├── modus-team-conventions/      # 团队约定（Layer 0-T）
-│   ├── modus-tech-wiki/             # 技术知识（Layer 1）
-│   └── modus-biz-{domain}/         # 业务知识（Layer 2）
-└── agents/
-    └── modus-harness-0*.md          # Harness SubAgent 定义
-
-modus/
-├── config.yaml                      # 项目配置和 constitution
-├── knowledge-catalog.md             # 知识全景目录（Level 1 索引）
-├── specs/                           # 主规格库
-├── plans/
-│   ├── active/{story-id}/           # 进行中的 Harness 任务
-│   └── archive/                     # 已归档的计划
-├── changes/                         # /modus:spec 变更目录
-└── sessions/vibe-log.md             # /modus:vibe 会话日志
+<项目根>/
+├── .modus/                                      # CLI 中性层
+│   ├── commands/                                # 命令源（所有平台共用）
+│   └── skills/                                  # 团队自定义技能包（如查日志、查监控）
+│
+├── .codebuddy/ | .claude/ | .cursor/ | .continue/   # 平台引用桩（仅 1 行 @import）
+│
+└── modus/                                       # 顶层 Models 层
+    ├── config.yaml                              # 项目配置 + constitution
+    ├── template/                                # 产物模板（pid/design/spec/plan/...）
+    ├── knowledge_base/                          # 知识库（Single Source of Truth）
+    │   ├── map.md                               # L0 全景索引（替代旧 knowledge-catalog.md）
+    │   ├── service-graph.md                     # L0 服务调用图
+    │   └── domain/
+    │       ├── _conventions/code/SKILL.md       # 团队约定
+    │       ├── _tech-wiki/code/SKILL.md         # 技术 Wiki
+    │       └── <domain>/                        # 业务域
+    │           ├── code/                        # 自动生成层（SKILL.md + 4 子文件）
+    │           ├── business/                    # 业务规则（人工维护）
+    │           ├── scenarios/                   # 测试场景
+    │           └── history/                     # 变更历史
+    └── artifacts/<STORY_ID>/                    # 产物（按 Story 隔离）
+        ├── pid/                                 # 需求澄清
+        ├── design/                              # 评估设计
+        ├── code/                                # 编码实施（plan/spec/harness）
+        └── archive/                             # 上线归档
 ```
 
-## 三级渐进加载原则
+## 渐进加载原则（v4.0 四级）
 
 每次 Modus 命令启动时：
-1. **Level 1（必须，~200 tokens）**：读 `modus/knowledge-catalog.md`
-2. **Level 2（按需，~3000 tokens/个）**：基于任务匹配，读对应 `modus-biz-*/SKILL.md`
-3. **Level 3（按需，无限制）**：执行任务时读 Skill 引用的实际代码文件
+1. **Level 1（必须，~200 tokens）**：读 `modus/knowledge_base/map.md`
+2. **Level 2（按需，~500 tokens/域）**：基于任务匹配，读对应 `domain/<d>/code/SKILL.md`（入口含子文件索引）
+3. **Level 3（按需，~800 tokens/文件）**：按需读 `entities.md` / `apis.md` / `services.md` / `data-models.md`
+4. **Level 4（执行时，无上限）**：从知识中的 `key_files` 索引按需读取实际代码文件
 
-不相关的 Skill 不加载，大幅降低 token 消耗。
+不相关的域、子文件不加载，大幅降低 token 消耗。
 
-## 命令速查
+## 命令速查（v4.0 产物路径）
 
-| 命令 | 场景 | 产出物 |
+| 命令 | 场景 | 产出物（v4.0） |
 |------|------|--------|
-| `/modus:init` | 首次初始化或重建知识库 | `.codebuddy/skills/modus-biz-*/SKILL.md` |
-| `/modus:vibe` | 日常编码（含业务上下文） | 代码 + `modus/sessions/vibe-log.md` |
-| `/modus:plan` | 功能规划 | `modus/plans/{name}/proposal+design+tasks.md` |
-| `/modus:spec` | 规范驱动开发 | `modus/changes/{name}/specs/{domain}/spec.md` |
-| `/modus:harness` | 全自动 Harness 流程 | `modus/plans/active/{story-id}/0*.md` |
+| `/modus:init` | 首次初始化或重建知识库 | `modus/knowledge_base/domain/<d>/code/*` |
+| `/modus:vibe` | 日常编码（含业务上下文） | 代码 + `modus/sessions/vibe-log.md`（或 `artifacts/<id>/code/vibe-log.md`） |
+| `/modus:plan` | 功能规划 | `artifacts/<id>/code/plan.md`（Story 模式）/ `modus/plans/{name}/`（独立模式） |
+| `/modus:spec` | 规范驱动开发 | `artifacts/<id>/code/spec/`（Story 模式）/ `modus/changes/{name}/`（独立模式） |
+| `/modus:harness` | 全自动 Harness 流程 | `artifacts/<id>/{pid|design|code}/*` |
+| `/modus:cr` | 代码评审 | `artifacts/<id>/code/cr-report.md` 或 `modus/cr/{date}-{name}/` |
 
-## Skill 知识状态
+## 知识状态
 
 | maturity | 含义 | 衰减规则 |
 |----------|------|---------|

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

@@ -9,7 +9,7 @@ disable: false
 
 **调用方：** Harness Orchestrator（`modus-harness`）  
 **输入：** TAPD Story URL + 相关业务 Skill 内容  
-**产出物：** `modus/stories/{story-id}/harness/01-analysis.md`
+**产出物：** `modus/artifacts/{story_id}/pid/prd.md`（v4.0 路径）
 
 ## 职责
 

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

@@ -9,7 +9,7 @@ disable: false
 
 **调用方：** Harness Orchestrator（Gate A0.5 通过后触发）  
 **输入：** `01-analysis.md` + `02-design-brief.md` + 业务 Skill 内容 + constitution  
-**产出物：** `modus/stories/{story-id}/harness/03-sprint-contract.md` + 代码变更
+**产出物：** `modus/artifacts/{story_id}/code/sprint-contract.md` + 代码变更（v4.0 路径）
 
 ## 职责
 

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

@@ -9,7 +9,7 @@ disable: false
 
 **调用方：** Harness Orchestrator（Gate B 通过后触发）  
 **输入：** 全部产出物（01-analysis.md 至 06-security-report.md）+ 代码变更  
-**产出物：** `modus/stories/{story-id}/harness/cr-report.md`
+**产出物：** `modus/artifacts/{story_id}/code/cr-report.md`（v4.0 路径）
 
 ## 职责
 

package/templates/skills/modus-agents/skill-creator/SKILL.md

@@ -9,7 +9,7 @@ disable: false
 
 **调用方：** `/modus:init` / `/modus:plan` 前置更新 / `/modus:spec` 前置更新 / Harness 后置更新 / Harness ARCHIVE 阶段  
 **输入：** 业务域信息 + 项目代码  
-**产出物：** `.codebuddy/skills/modus-biz-{domain}/SKILL.md` / `modus-team-conventions/SKILL.md` / `modus-tech-wiki/SKILL.md` + `modus/knowledge-catalog.md` 更新
+**产出物：** `modus/knowledge_base/domain/{domain}/code/SKILL.md` （业务域入口） / `modus/knowledge_base/domain/_conventions/code/SKILL.md` / `modus/knowledge_base/domain/_tech-wiki/code/SKILL.md` + `modus/knowledge_base/map.md` 更新
 
 ## 职责
 
@@ -677,7 +677,7 @@ Step 4 扩展：upstream/downstream 双向同步（append-only，Git 无冲突
 
 ### Step 5：更新 knowledge-catalog.md
 
-每次写入 Skill 后，同步更新 `modus/knowledge-catalog.md`（使用升级后的条目格式）：
+每次写入知识后，同步更新 `modus/knowledge_base/map.md`（使用升级后的条目格式）：
 
 ```markdown
 - **modus-biz-order**: 订单域 — 创建/状态流转/查询
@@ -1055,7 +1055,7 @@ layer: "1"
 - 关键文件索引路径必须真实存在
 - 每条知识条目必须打上五类型标签之一：`[model]` `[decision]` `[guideline]` `[pitfall]` `[process]`
 - 更新时必须更新 `updated` 日期和 `last_referenced`
-- 模式 D 每次执行后必须同步更新 `modus/knowledge-catalog.md`
+- 模式 D 每次执行后必须同步更新 `modus/knowledge_base/map.md`
 - 统一使用 `status` 字段（不使用 `maturity`），枚举值：`draft | verified | proven | stale | archived`
 - 新生成的 Skill 默认写入 `format_version: v3`（17节标准格式）；存量 14 节 Skill 保留 `format_version: v2`；存量 7 节 Skill 迁移前标记 `format_version: v1`
 

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

@@ -220,7 +220,7 @@ Modus Auto — 智能模式路由工具
   /modus:auto https://tapd.cn/.../1234 --scores-only --output json
   /modus:auto --resume
 
-更多文档：modus/knowledge-catalog.md
+更多文档：modus/knowledge_base/map.md
 ```
 
 ---
@@ -264,8 +264,8 @@ except MCP_UNAVAILABLE:
 
 # 2. 尝试读取知识目录（文件系统不可用时跳过）
 try:
-    catalog = read("modus/knowledge-catalog.md")
-    # v3.2 路径：modus/knowledge/biz-*/SKILL.md（唯一权威）
+    catalog = read("modus/knowledge_base/map.md")
+    # v3.2 路径：modus/knowledge_base/domain/*/code/SKILL.md（唯一权威）
 except FILESYSTEM_UNAVAILABLE:
     catalog = None
     note += " | 文件系统不可用，跳过 Skill 加载，基于 Story 文本评分"
@@ -297,7 +297,7 @@ context_bundle:
   story_id: "1234567890"
   story_title: "{Story 标题}"
   domains: ["{domain}"]
-  domain_skill_path: "modus/knowledge/{domain}/SKILL.md"   # v3.2 路径
+  domain_skill_path: "modus/knowledge_base/domain/{domain}/code/SKILL.md"   # v3.2 路径
   scores: {complexity: 2, risk: 1, clarity: 3, contract: 1}
   recommended_mode: "spec"
   skip_clarify: true
@@ -359,15 +359,15 @@ if cache.valid:
 
 #### Step 2：读取知识目录
 
-读取 `modus/knowledge-catalog.md`：
+读取 `modus/knowledge_base/map.md`：
 
 ```
 知识库路径（v3.2 Single Source of Truth）：
-  modus/knowledge/biz-*/SKILL.md      ← Layer 2 业务域（唯一权威，v3.1+ 迁移后）
-  modus/knowledge/_tech-wiki/SKILL.md
-  modus/knowledge/_conventions/SKILL.md
+  modus/knowledge_base/domain/*/code/SKILL.md      ← Layer 2 业务域（唯一权威，v3.1+ 迁移后）
+  modus/knowledge_base/domain/_tech-wiki/code/SKILL.md
+  modus/knowledge_base/domain/_conventions/code/SKILL.md
 
-⚠️ 注意（v3.1+ 变更）：业务域 Skill 已迁移至 modus/knowledge/biz-*/SKILL.md，
+⚠️ 注意（v3.1+ 变更）：业务域 Skill 已迁移至 modus/knowledge_base/domain/*/code/SKILL.md，
    .codebuddy/skills/modus-biz-* 为引用桩，不含实际内容，请勿从旧路径读取。
 ```
 
@@ -454,7 +454,7 @@ if cache.valid:
 若用户带 `--preview`，路由完成后输出产物目录预览，然后停止：
 ```
 预览：/modus:spec 将在以下路径生成产物
-  modus/stories/{id}/spec/
+  modus/artifacts/{id}/code/spec/
     ├── .modus-state.yaml
     ├── delta/{domain}.md
     ├── design.md
@@ -521,7 +521,7 @@ if cache.valid:
 确认启动 /modus:plan
   Story 摘要: {标题 + 核心需求}
   业务域:     {domain} [draft]
-  产物路径:   modus/stories/{id}/plan.md  ← v3.2 统一路由
+  产物路径:   modus/artifacts/{id}/code/plan.md  ← v3.2 统一路由
   快速模式（--quick，跳过设计文档）: [y/N]
   
 确认？[Y/n]
@@ -533,7 +533,7 @@ if cache.valid:
   Story URL:  {原始 URL}
   业务域:     {domain} [draft]
   规格级别:   Full（因有接口契约变更）/ 可加 --lite 降级
-  产物路径:   modus/stories/{id}/spec/  ← v3.2 统一路由
+  产物路径:   modus/artifacts/{id}/code/spec/  ← v3.2 统一路由
   验收标准:   已提取 {n} 条，将作为 Scenario 输入
   
 确认？[Y/n]
@@ -543,7 +543,7 @@ if cache.valid:
 ```
 确认启动 /modus:harness
   Story URL:  {原始 URL}
-  产物路径:   modus/stories/{id}/harness/  ← v3.2 统一路由
+  产物路径:   modus/artifacts/{id}/code/  ← v3.2 统一路由
   跳过阶段:   无（如需跳过：--skip [agents]）
   
 ⚠️ Harness 将全自动执行多个 SubAgent，预计耗时较长。
@@ -562,7 +562,7 @@ context_bundle:
   acceptance_criteria: ["{ac1}", "{ac2}"]
   domains: ["{domain}"]
   domain_skill_paths:                           # v3.2 路径（唯一权威）
-    - "modus/knowledge/{domain}/SKILL.md"
+    - "modus/knowledge_base/domain/{domain}/code/SKILL.md"
   domain_skills_loaded: true
   scores:
     complexity: 2
@@ -588,16 +588,16 @@ context_bundle:
 
 ```
 有 --story [id]：
-  modus/stories/{id}/plan.md          # plan 产物
-  modus/stories/{id}/spec/            # spec 产物目录
-  modus/stories/{id}/harness/         # harness 产物目录
+  modus/artifacts/{id}/code/plan.md          # plan 产物
+  modus/artifacts/{id}/code/spec/            # spec 产物目录
+  modus/artifacts/{id}/code/         # harness 产物目录
 
 无 --story（自动推断 feature 名）：
   modus/local/{feature-name}/plan.md
   modus/local/{feature-name}/spec/
 ```
 
-> **v3.2 变更说明**：废弃 `modus/plans/active/{id}/`，统一使用 `modus/stories/{id}/`。
+> **v3.2 变更说明**：废弃 `modus/plans/active/{id}/`，统一使用 `modus/artifacts/{id}/`。
 
 ---
 
@@ -653,7 +653,7 @@ Modus Auto — 请提供需求来源：
 - **--no-confirm 默认生效**：Codex 环境视同携带此参数
 - **文件系统降级**：文件系统不可用时跳过 Skill 加载，仅基于 Story 文本评分，Context Bundle 不写文件
 - **结构化日志**：`--output json` 时输出完整 JSON，便于在 Codex 日志中机器解析
-- **Context Bundle 路径**：使用 `modus/knowledge/biz-*/SKILL.md`（v3.2 唯一权威路径），不读旧路径
+- **Context Bundle 路径**：使用 `modus/knowledge_base/domain/*/code/SKILL.md`（v3.2 唯一权威路径），不读旧路径
 
 ---
 

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

@@ -51,7 +51,7 @@ disable: false
    - 若路径是目录，自动在目录内查找：`design.md` > `plan.md`，以及同级 `tasks.md`
 2. 若有 `--story`，调用 TAPD MCP（`tapd_mcp_http`）读取 Story 描述作为 PRD 补充
 3. `modus/config.yaml`：读取 `constitution`（`hard_rules`、`tech_stack`、`key_patterns`）
-4. `modus/knowledge-catalog.md`：识别相关业务域，加载对应 `modus/knowledge/biz-{domain}/SKILL.md`（仅 hash 检查，不更新）
+4. `modus/knowledge_base/map.md`：识别相关业务域，加载对应 `modus/knowledge_base/domain/{domain}/code/SKILL.md`（仅 hash 检查，不更新）
 
 **输出上下文加载摘要：**
 

package/templates/skills/modus-design-brief/SKILL.md

@@ -27,7 +27,7 @@ disable: false
 
 | `mode` 值 | 来源类型 | 处理方式 |
 |----------|---------|---------|
-| `harness` | 文件路径 | 读取 `modus/stories/{story-id}/harness/01-analysis.md`（v3.2 路径）|
+| `harness` | 文件路径 | 读取 `modus/artifacts/{story_id}/pid/prd.md`（v3.2 路径）|
 | `spec` | 文件路径 | 读取调用方目录下的 `proposal.md`；若存在同级 `specs/*/spec.md` 也一并读取 |
 | `vibe` | 运行时字符串 | `analysis_doc` 参数是调用方直接传入的「用户意图摘要」字符串，**不读取任何文件**；直接将此字符串作为需求描述，与 Step 5 加载的 Skill 内容结合生成设计方案 |
 
@@ -108,7 +108,7 @@ disable: false
 将生成内容写入调用方指定路径：
 - plan 模式：`modus/plans/{name}/design-brief.md`
 - spec 模式：`modus/changes/{name}/design-brief.md`（gate_status 写 `passed`，此模式无 Gate 检查）
-- harness 模式：`modus/stories/{story-id}/harness/02-design-brief.md`
+- harness 模式：`modus/artifacts/{story_id}/design/design.md`
   - **gate_status 必须由 `modus-designer` SubAgent 在 Step 4 后动态评估并填写**（见 `modus-harness-agents/01-5-design/SKILL.md` 的 gate_status 赋值规则）
   - 固定写 `passed` 将使 Gate A0.5 失效，严禁在 harness 模式下硬编码该字段
 
@@ -347,4 +347,4 @@ constitution: {constitution 字段内容}
 
 ### harness 模式调用方式
 
-由 SubAgent 02（设计阶段，原 01.5）独立执行（见 `modus-harness-agents/01-5-design/SKILL.md`），输入为 `modus/stories/{story-id}/harness/01-analysis.md`，输出为 `modus/stories/{story-id}/harness/02-design-brief.md` 含 HANDOFF 块（`agent: "02-design"`）。
+由 SubAgent 02（设计阶段，原 01.5）独立执行（见 `modus-harness-agents/01-5-design/SKILL.md`），输入为 `modus/artifacts/{story_id}/pid/prd.md`，输出为 `modus/artifacts/{story_id}/design/design.md` 含 HANDOFF 块（`agent: "02-design"`）。

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

@@ -101,7 +101,7 @@ Step P1：读取 plan.md
     → continue_token：记录到工作目录 .harness-state.yaml
 
 Step P2：初始化工作目录
-  若 plan.md 含 story_id：工作目录 = modus/stories/{story_id}/harness/
+  若 plan.md 含 story_id：工作目录 = modus/artifacts/{story_id}/code/
   若无 story_id：工作目录 = modus/plans/{PLAN_NAME}/harness/
 
 Step P3：输出接力摘要
@@ -130,10 +130,10 @@ Step P4：设置 SKIP_AGENTS = ["01", "02"]（强制跳过 SA01 + SA02）
 读取 `{project}/modus/config.yaml`（即当前项目根目录下的 `modus/config.yaml`，多项目 workspace 需先通过 `workspace-catalog.md` 确认项目路径，如 `operations-job/modus/config.yaml`）的 `constitution` 字段，将 `hard_rules` 传递给所有 SubAgent 作为硬性约束。SubAgent 直接使用 Orchestrator 传入的 constitution 内容，无需独立解析路径。
 
 **检查业务 Skill：**
-读取 `modus/knowledge-catalog.md`（Level 1 加载）：
+读取 `modus/knowledge_base/map.md`（Level 1 加载）：
 - 若不存在，强烈建议先运行 `/modus:init`：
 ```
-⚠️ 未找到知识目录（modus/knowledge-catalog.md）！
+⚠️ 未找到知识目录（modus/knowledge_base/map.md）！
 
 /modus:harness 依赖业务 Skill 为 SubAgent 提供项目背景知识。
 建议：
@@ -143,14 +143,14 @@ B. 强制继续（无业务上下文，风险较高）
 
 **解析 Story ID + 初始化状态追踪：**
 - 从 TAPD URL 提取 Story ID（格式：`tapd.cn/{project}/stories/view/{id}`）
-- 创建工作目录：`modus/stories/{story-id}/harness/`
+- 创建工作目录：`modus/artifacts/{story_id}/code/`
 
 **`.harness-state.yaml` 断点续跑机制（优先级高于 HANDOFF 块探测）：**
 
 检查工作目录下是否存在 `.harness-state.yaml`；若存在部分产出物（含 HANDOFF frontmatter），也可从断点处继续。
 
 ```yaml
-# 示例：modus/stories/{story-id}/harness/.harness-state.yaml
+# 示例：modus/artifacts/{story_id}/code/.harness-state.yaml
 story_id: "{story-id}"
 loop: 1                         # 当前 Loop 轮次（1 或 2）
 # SubAgent ID 约定：00=INIT 阶段、01/02/03/04/05/06/07/08 为主流程；00-ARCHIVE=ARCHIVE 阶段