@modus-ai/modus 0.2.5 → 0.2.7

package/templates/commands/modus.md

@@ -1,37 +1,64 @@
-# /modus
+# /modus — Modus AI 编码加速框架
 
-Modus — Business-grounded AI coding accelerator.
+**Modus** — 知识驱动的 AI 编码框架，核心理念：每次工作流都是一次知识积累，用业务 Skill 消除 AI 的冷启动问题。
 
-## Available Commands
+## 可用命令
 
-| Command | Description |
-|---|---|
-| `/modus:init` | Scan codebase, classify business domains, generate domain Skill files |
-| `/modus:vibe` | Context-aware vibe coding with business Skill backing |
-| `/modus:plan` | Plan mode with Skill-backed business context |
-| `/modus:spec` | OpenSpec-style spec-driven development |
-| `/modus:auto` | Smart mode recommendation — reads TAPD Story, scores 4 dimensions, recommends vibe/plan/spec/harness |
-| `/modus:harness` | Full dual-loop multi-agent Harness (analyze → dev → test → review → deploy) |
+| 命令 | 用途 | 常用参数 |
+|------|------|---------|
+| `/modus:init` | 扫描代码库，初始化/更新业务知识库 | `--enhance <domain>`, `--migrate`, `--dry-run` |
+| `/modus:vibe` | 上下文感知日常编码（氛围编程） | `--domain <name>`, `--verbose` |
+| `/modus:plan` | 功能规划（设计文档 + Build 循环） | `--story <url>`, `--design`, `--quick` |
+| `/modus:spec` | 规范驱动开发（行为规格 + 验收标准） | `--story <url>`, `--lite`, `--testcase` |
+| `/modus:auto` | 智能模式推荐（读 TAPD 自动决策） | `--show-scores`, `--force <mode>` |
+| `/modus:harness` | 全自动交付流水线（需求→部署） | `--story <url>`, `--skip`, `--loop1-only` |
+| `/modus:upgrade` | 框架版本升级 | `--check`, `--dry-run`, `--changelog` |
 
-## Quick Start
+所有命令支持 `--help` 参数查看中文完整说明。
 
-1. Run `/modus:init` once to scan your project and build business Skills
-2. Use `/modus:auto [tapd-url]` when unsure which mode fits — AI recommends based on story analysis
-3. Use `/modus:vibe` for day-to-day coding with project context
-4. Use `/modus:harness` for full-cycle feature delivery from a TAPD Story URL
+## 命令选择指南
 
-## Mode Selection Guide
+| 场景 | 推荐命令 |
+|------|---------|
+| 不确定用哪个命令 | `/modus:auto [tapd-url]` |
+| 日常 Bug 修复、小改动 | `/modus:vibe` |
+| 需要设计文档，无需规格 | `/modus:plan` |
+| 有接口契约变更/可测试验收标准 | `/modus:spec` |
+| 有 TAPD Story，全自动到部署 | `/modus:harness` |
+| 项目新接手或代码大重构后 | `/modus:init` |
 
-| Situation | Recommended Command |
-|-----------|-------------------|
-| Not sure which mode to use | `/modus:auto [tapd-url]` |
-| Quick bug fix / small change | `/modus:vibe` |
-| Feature with design docs, no spec needed | `/modus:plan` |
-| Interface contract changes / testable acceptance criteria | `/modus:spec` |
-| Full automation from TAPD story to deployment | `/modus:harness` |
+## 快速开始
 
-## Tips
+```
+# 1. 首次接入：扫描项目，生成业务知识库
+/modus:init
 
-- Business Skill files live in `.codebuddy/skills/modus-biz-*/SKILL.md`
-- Re-run `/modus:init` any time your domain model changes
-- All commands fall back gracefully if business Skills are missing
+# 2. 不确定用哪个命令时：输入 TAPD Story URL 让 AI 推荐
+/modus:auto https://tapd.cn/.../stories/view/1234567890
+
+# 3. 日常编码：描述需求，AI 自动加载业务上下文
+/modus:vibe 给歌曲列表接口加按状态筛选功能
+
+# 4. 全自动交付：输入 Story URL，从需求到部署
+/modus:harness https://tapd.cn/.../stories/view/1234567890
+```
+
+## 知识库路径（v3.2）
+
+```
+modus/knowledge/                   # Single Source of Truth（平台无关）
+├── _conventions/SKILL.md          # 团队约定（Layer 0-T）
+├── _tech-wiki/SKILL.md            # 技术知识（Layer 1）
+└── biz-{domain}/SKILL.md          # 业务域知识（Layer 2）
+
+modus/knowledge-catalog.md         # 项目知识目录（~200 tokens）
+modus/workspace-catalog.md         # 工作区顶层路由（多项目）
+```
+
+重新初始化或更新知识库：
+
+```
+/modus:init --enhance biz-track    # 仅更新某个域
+/modus:init --enhance-all          # 重建所有业务域
+/modus:init --migrate              # 从旧路径迁移到 modus/knowledge/
+```

package/templates/commands/plan.md

@@ -1,28 +1,70 @@
-# /modus:plan
+# /modus:plan — 功能规划（含 Build 执行与知识归档）
 
-Plan mode. Generate structured planning documents (proposal, design, tasks) backed by up-to-date business Skills.
+**用途：** 针对一个具体需求，基于业务 Skill 上下文进行六维复杂度评估，提出 3 个精准澄清问题后生成结构化 `plan.md`，在用户确认后执行代码生成，最后自动回写新知识到 Skill 库。
 
-## Instructions
+**借鉴自：** Cursor Plan Mode（只读规划阶段 + 用户确认后执行）
 
-Read and follow the skill at `.codebuddy/skills/modus-plan/SKILL.md` to execute this command.
+## 参数说明
 
-## Quick Summary
+```
+/modus:plan [需求描述] [参数]
+
+  --help                    显示完整帮助（中文）
+  --story <tapd-url>        关联 TAPD Story（自动填写背景，写入 HANDOFF story_id）
+  --project <name>          指定项目（多项目 workspace 使用）
+  --design                  仅生成技术评估文档（design.md），不生成 tasks（技术方案评审场景）
+  --quick                   跳过澄清 3 问，直接生成 plan（适合简单任务）
+  --enhance                 生成 plan 前强制刷新相关 Skill（hash 检查）
+  --no-build                归档模式：生成 plan.md 但不触发 Build 确认循环
+  --read-only               规划模式：仅输出 plan.md，永远不触发代码生成（Cursor Plan Mode 风格）
+  --resume <name>           从已有 plan 的断点继续（读取 .modus-state.yaml）
+  --complexity <level>      手动指定复杂度（simple|medium|complex），跳过自动评分
+```
+
+## 使用示例
 
-1. Check for business Skills (same fallback as `/modus:vibe`)
-2. Identify relevant business domains from the user's request
-3. **Pre-update Skills**: refresh relevant business Skill files based on latest code
-4. Generate planning documents to `modus/plans/{name}/`:
-   - `proposal.md` — intent and scope
-   - `design.md` — technical approach and decisions
-   - `tasks.md` — implementation checklist
-5. Ask user whether to archive → move to `modus/plans/archive/{YYYY-MM-DD}-{name}/`
-6. **Post-update Skills**: write back new knowledge discovered during planning
+```
+/modus:plan 需要支持歌曲批量导出为 Excel
+/modus:plan --story https://tapd.cn/.../stories/view/123 新增艺人等级评定功能
+/modus:plan --design 评估版权对账系统的重构方案
+/modus:plan --quick 修复版权审核列表分页 bug
+/modus:plan --read-only 分析中央曲库同步的架构方案
+/modus:plan --resume batch-export 继续上次中断的规划
+```
 
-## Output Location
+## 执行流程概览
+
+```
+① 域匹配：基于 knowledge-catalog.md 判断涉及的业务域
+② 复杂度评估：六维评分 → simple / medium / complex 分级
+   complex → 提示考虑升级为 /modus:spec 或 /modus:harness
+③ 两层知识检索：Skill 前置更新（hash 检查）→ 源码按需加载
+④ 精准 3 问：pitfall 关联问题 + 范围边界 + 优先级约束
+⑤ 生成 plan.md：概述 / 关键约束 / 已知风险 / 方案对比 / Todos / 影响文件
+   ⚠️ 规划阶段 — 此时尚未修改任何代码
+⑥ Build 确认循环（人工审批节点）：用户确认后启动代码生成
+⑦ 后置知识回写：技术决策 → [decision]，新风险 → [pitfall]
+```
+
+## 产出物
 
 ```
 modus/plans/{name}/
-├── proposal.md
-├── design.md
-└── tasks.md
+├── .modus-state.yaml   — 状态文件（含 complexity，支持断点续跑）
+└── plan.md             — 规划文档（概述/风险/方案对比/Todos/影响文件）
+
+归档后移动到：modus/plans/archive/{date}-{name}/
 ```
+
+## 与其他命令的对比
+
+| 场景 | 推荐命令 |
+|------|---------|
+| 日常 Bug 修复、小改动 | `/modus:vibe` |
+| 需要设计文档，无需规格 | `/modus:plan`（本命令） |
+| 需要可测试验收标准、接口契约 | `/modus:spec` |
+| 有 TAPD Story，全自动到部署 | `/modus:harness` |
+
+## 执行此命令
+
+读取并执行 `.codebuddy/skills/modus-plan/SKILL.md` 中的完整流程。

package/templates/commands/spec.md

@@ -1,37 +1,81 @@
-# /modus:spec
+# /modus:spec — 规范驱动开发（OpenSpec 行为规格）
 
-OpenSpec-style spec-driven development. Generate behavior specifications (delta specs) + design + tasks, with archive merging specs into the main spec library.
+**用途：** 在 `/plan` 基础上增加行为规格（delta specs），用 GIVEN/WHEN/THEN 明确系统「WHAT」，规格可测试，归档时自动检测冲突并合并到主规格库（Source of Truth）。适用于有接口契约变更、需要可测试验收标准的场景。
 
-## Instructions
+**借鉴自：** OpenSpec 规范 + Gherkin BDD（Cucumber）的 Feature/Scenario 格式
 
-Read and follow the skill at `.codebuddy/skills/modus-spec/SKILL.md` to execute this command.
+## 参数说明
 
-## Quick Summary
+```
+/modus:spec [需求描述] [参数]
+
+  --help                    显示完整帮助（中文）
+  --story <tapd-url>        关联 TAPD Story（自动填写背景，写入 HANDOFF story_id）
+  --project <name>          指定项目（多项目 workspace 使用）
+  --lite                    轻量模式：跳过 design-brief，仅生成 delta-specs + tasks
+  --delta                   仅生成 delta-specs.md（不生成 design 和 tasks）
+  --testcase                归档前同步生成 QA 测试用例文件（testcases.md，JUnit 5 骨架）
+  --verify                  归档前执行三维验证（完整性/正确性/一致性）
+  --resume <name>           从断点继续（读取 .modus-state.yaml）
+  --no-archive              跳过归档到主规格库（适合实验性变更）
+```
+
+## 使用示例
+
+```
+/modus:spec 新增歌曲批量审批功能
+/modus:spec --story https://tapd.cn/.../stories/view/123 艺人等级评定
+/modus:spec --lite 优化版权查询索引
+/modus:spec --testcase 修改支付超时时间从 30 分钟改为 15 分钟
+/modus:spec --verify --story https://tapd.cn/.../123 电子签约批量重签
+/modus:spec --resume batch-approve 继续上次中断的规格
+```
+
+## 与 `/modus:plan` 的区别
 
-1. Check for business Skills (same fallback as `/modus:vibe`)
-2. Identify relevant business domains
-3. **Pre-update Skills**: refresh relevant business Skill files
-4. Generate specification documents to `modus/changes/{name}/`:
-   - `proposal.md` — intent and scope
-   - `specs/{domain}/spec.md` — delta specs (ADDED/MODIFIED/REMOVED requirements with Scenarios)
-   - `design.md` — technical approach
-   - `tasks.md` — implementation checklist (includes spec verification tasks)
-5. Ask user whether to archive:
-   - Delta specs merged into `modus/specs/` (source of truth)
-   - Change folder moved to `modus/changes/archive/{YYYY-MM-DD}-{name}/`
-6. **Post-update Skills**: write back new business rules and contracts
+| 维度 | `/modus:plan` | `/modus:spec` |
+|------|--------------|----------------|
+| 产出物 | 单一 `plan.md` | `delta-specs.md` + `design.md` + `tasks.md` |
+| 目录 | `modus/plans/{name}/` | `modus/changes/{name}/` |
+| 行为规格 | 无 | 有（ADDED/MODIFIED/REMOVED + GIVEN/WHEN/THEN） |
+| 验收标准 | 无 | 有（可测试 Scenario） |
+| 冲突检测 | 无 | 有（MODIFIED/REMOVED 目标必须存在于主库） |
+| 归档目标 | `modus/plans/archive/` | 合并到 `modus/specs/{domain}/spec.md` |
 
-## Delta Spec Format
+## Delta Specs 格式（Gherkin 风格）
 
-Use ADDED/MODIFIED/REMOVED sections with GIVEN/WHEN/THEN scenarios.
-Specs describe WHAT the system does, not HOW.
+```markdown
+Feature: 批量审批订单
 
-## Output Location
+## ADDED Requirements
+
+### Scenario: Happy Path
+  Given 用户已登录且拥有审批权限
+  When 提交包含 ≥1 条订单 ID 的批量审批请求
+  Then 所有订单状态变更为 APPROVED，返回成功数量
+
+### Scenario: 超出上限
+  Given 请求包含 > 50 条订单 ID
+  When 提交批量审批请求
+  Then 系统返回 400 错误："批量操作上限 50 条"
+```
+
+## 产出物
 
 ```
 modus/changes/{name}/
-├── proposal.md
-├── specs/{domain}/spec.md    ← delta specs
-├── design.md
-└── tasks.md
+├── .modus-state.yaml               — 状态文件（支持断点续跑）
+├── proposal.md                     — 意图与范围
+├── specs/{domain}/spec.md          — delta specs（ADDED/MODIFIED/REMOVED）
+├── design.md                       — 技术方案
+├── design-brief.md                 — 精确实现指南（Full 模式）
+├── tasks.md                        — 实现清单（追踪到 Scenario）
+└── testcases.md                    — QA 用例（--testcase 时生成）
+
+归档后：modus/changes/archive/{date}-{name}/
+主规格库：modus/specs/{domain}/spec.md（历次归档合并）
 ```
+
+## 执行此命令
+
+读取并执行 `.codebuddy/skills/modus-spec/SKILL.md` 中的完整流程。

package/templates/commands/upgrade.md

@@ -0,0 +1,54 @@
+# /modus:upgrade — 框架版本升级
+
+**用途：** 检测 Modus 框架新版本，自动执行目录结构迁移和 Skill 格式升级，保持项目与最新规范一致。
+
+## 参数说明
+
+```
+/modus:upgrade [参数]
+
+  --help                    显示完整帮助（中文）
+  --check                   仅检查当前版本和最新版本，不执行升级
+  --dry-run                 预览将修改哪些文件，不实际写入
+  --changelog               显示从当前版本到最新版的变更日志
+  --target <version>        升级到指定版本（默认最新稳定版）
+  --project <name>          仅升级指定项目的 Skill 文件（多项目时）
+  --migrate-only            仅执行文件结构迁移，不更新框架 Skill 模板
+  --backup-dir <path>       指定备份目录（默认 modus/backup/{date}/）
+  --force                   强制升级（即使版本一致，用于修复损坏的文件）
+```
+
+## 使用示例
+
+```
+/modus:upgrade                     # 检查并执行升级到最新版
+/modus:upgrade --check             # 仅检查当前和最新版本
+/modus:upgrade --dry-run           # 预览升级变更，不实际修改
+/modus:upgrade --changelog         # 查看版本变更说明
+/modus:upgrade --target 3.2.0      # 升级到指定版本
+/modus:upgrade --migrate-only      # 仅迁移目录结构，不更新模板
+```
+
+## 版本迁移说明
+
+| 版本 | 主要变更 |
+|------|---------|
+| v3.2.0 | 跨 Skill 路径全面统一到 `modus/knowledge/biz-*/`；步骤编号规范化（禁止小数步骤）；modus-analyst 产出路径更正到 `modus/stories/{id}/harness/`；modus-plan 双路径产出规则（Story 模式 vs 独立模式） |
+| v3.1.0 | 知识库路径迁移：`.codebuddy/skills/modus-biz-*` → `modus/knowledge/biz-*`；新增工作区顶层路由 `modus/workspace-catalog.md`；HANDOFF 协议升级到 schema v1.1 |
+| v3.0.0 | 多项目工作区支持（modus-workspace.yaml）；引用式适配（不复制知识） |
+| v2.x | 初始版本 |
+
+## 升级流程
+
+```
+① 读取本地 modus/config.yaml 的 modus_version 字段
+② 对比目标版本，展示差异摘要
+③ 询问确认（--force 时跳过）
+④ 备份现有文件到 modus/backup/{date}/
+⑤ 执行迁移：文件结构调整 + Skill 格式更新
+⑥ 输出迁移完成报告
+```
+
+## 执行此命令
+
+读取并执行 `.codebuddy/skills/modus-upgrade/SKILL.md` 中的完整流程。

package/templates/commands/vibe.md

@@ -1,12 +1,24 @@
-# /modus:vibe
+# /modus:vibe — 上下文感知编码（氛围编程）
 
-Context-aware vibe coding. Intelligently loads relevant business Skills, auto-syncs stale knowledge, and applies rule-driven clarification before coding so AI works as a knowledgeable project member.
+**用途：** 执行日常编码任务前，自动加载相关业务 Skill，让 AI 以「懂项目的开发者」身份工作，而非冷启动。适合 Bug 修复、小功能迭代、代码重构等日常任务。
 
-## Instructions
+> Context-aware vibe coding. Intelligently loads relevant business Skills, auto-syncs stale knowledge, and applies rule-driven clarification before coding so AI works as a knowledgeable project member.
 
-Read and follow the skill at `.codebuddy/skills/modus-vibe/SKILL.md` to execute this command.
+## 参数说明
 
-## Quick Summary
+```
+/modus:vibe [需求描述] [参数]
+
+  --help                    显示完整帮助（中文）
+  --domain <name>           强制加载指定业务域（跳过自动匹配，如 --domain biz-track）
+  --project <name>          指定项目（多项目 workspace 使用）
+  --context <file>          额外加载指定文件作为上下文（相对路径）
+  --no-skill                跳过 Skill 加载，直接用原始代码上下文（不推荐）
+  --verbose                 显示 Skill 加载过程和 token 预估
+  --dry-run                 仅展示将加载的 Skill 和文件，不执行编码
+```
+
+## 执行流程（概览）
 
 1. Read `modus/config.yaml` for hard constraints (constitution)
 2. Load `modus/knowledge-catalog.md` (Level 1, ~200 tokens)
@@ -20,3 +32,41 @@ Read and follow the skill at `.codebuddy/skills/modus-vibe/SKILL.md` to execute
 10. Append session log to `modus/sessions/vibe-log.md`
 
 **Degraded mode** (no business Skills): proceed without domain context, note quality may be lower, show `[降级模式：无业务上下文，建议先运行 /modus:init]`.
+
+## 使用示例
+
+```
+/modus:vibe 给歌曲列表接口加一个按状态筛选的功能
+/modus:vibe 订单支付回调逻辑有个 NPE，帮我排查
+/modus:vibe --domain biz-track 重构歌曲同步的重试机制
+/modus:vibe --verbose 分析专辑发行流程的性能瓶颈
+/modus:vibe --dry-run 优化版权审核的并发处理
+```
+
+## 知识加载策略（渐进三级）
+
+```
+Level 1（必须，~200 tokens）
+  读 modus/knowledge-catalog.md
+  → 了解可用知识域，匹配当前任务相关域
+
+Level 2（按需，~3000 tokens/个）
+  仅读与任务语义匹配的 modus/knowledge/biz-*/SKILL.md
+  → 不相关的域不加载，节省 ~59% token
+
+Level 3（执行时，无上限）
+  从 Skill 的 key_files 索引按需读取实际代码文件
+  → 绝不预先全量读取
+```
+
+## 无业务 Skill 时的兜底
+
+```
+⚠️ 未找到业务知识库！建议先运行：/modus:init
+A. 现在运行快速初始化
+B. 继续（无业务上下文，结果质量可能降低）
+```
+
+## 执行此命令
+
+读取并执行 `.codebuddy/skills/modus-vibe/SKILL.md` 中的完整流程。

package/templates/knowledge-catalog.md

@@ -1,5 +1,12 @@
-# Modus 知识全景目录
+# Modus 知识全景目录 — {project-name}
 # 所有 Modus 命令启动时先读此文件（Level 1 加载，~200 tokens）
+# 框架版本：3.1.0 | 知识库路径：{project}/modus/knowledge/**（Single Source of Truth）
+# 多平台适配：CLAUDE.md / AGENTS.md / .cursor/rules/ 均为引用式，修改请直接编辑 modus/knowledge/ 下的文件
+#
+# 路由层级：
+#   workspace → modus/workspace-catalog.md（顶层，~100 tokens）
+#   project   → 本文件（~200 tokens）
+#   domain    → modus/knowledge/biz-*/SKILL.md（~3000 tokens/个，按需加载）
 # 按需再读完整 SKILL.md（Level 2，~3000 tokens/个）
 # 或直接读 Skill 引用的实际代码文件（Level 3，按需）
 
@@ -12,20 +19,17 @@ updated: {YYYY-MM-DD}
   [由 /modus:init 生成，不随项目代码变化，手动维护]
 
 ## 团队约定 (Layer 0-T)
-- **modus-team-conventions**: 代码规范/提交规范/最佳实践
-  [status: draft] [format: v2/14节] [upstream: -]
-  更新: {日期}
+- **_conventions**: {规范描述} [maturity: draft] 更新: {日期}
+  - 路径：`{project}/modus/knowledge/_conventions/SKILL.md`
 
 ## 技术知识 (Layer 1)
-- **modus-tech-wiki**: 跨项目技术经验（反模式、架构决策、性能优化）
-  [status: draft] [format: v2/14节] [upstream: -]
-  更新: {日期}
+- **_tech-wiki**: {技术栈描述} [maturity: draft] 更新: {日期}
+  - 路径：`{project}/modus/knowledge/_tech-wiki/SKILL.md`
 
 ## 业务知识 (Layer 2)
 <!-- 由 /modus:init 生成，由各模式工作流自动更新 -->
-- **modus-biz-{domain}**: {中文域名} — {核心职责一句话}
-  [status: draft] [format: v3/17节] [upstream: {依赖域列表，无则写-}]
-  更新: {日期}  hash: {last_hash 前8位}
+- **biz-{domain}**: {中文域名} — {核心职责一句话} [maturity: draft] 最近引用: {日期}
+  - 路径：`{project}/modus/knowledge/biz-{domain}/SKILL.md`
 
 ## 域依赖图 (Dependency Graph)
 <!--
@@ -52,6 +56,15 @@ updated: {YYYY-MM-DD}
 
 目标：不相关的 Skill 不加载，大幅降低 token 消耗。
 
+## 框架命令（快速参考）
+- **modus:init** `--help` `--enhance [domain]` `--enhance-all` `--migrate` `--dry-run` `--force` `--platform [list]` `--no-sync` `--verbose` `--reset-maturity` `--project [name]`
+- **modus:vibe** `--help` `--domain [name]` `--project [name]` `--context [file]` `--no-skill` `--verbose` `--dry-run`
+- **modus:plan** `--help` `--story [url]` `--design` `--quick` `--enhance` `--no-build` `--resume [name]` `--complexity [level]` `--project [name]`
+- **modus:spec** `--help` `--story [url]` `--lite` `--delta` `--testcase` `--verify` `--resume [name]` `--no-archive` `--project [name]`
+- **modus:auto** `--help` `--force [mode]` `--no-confirm` `--show-scores` `--project [name]`
+- **modus:harness** `--help` `--story [url]` `--skip [agents]` `--loop1-only` `--resume` `--dry-run` `--force-rebuild-skill` `--no-deploy` `--max-loop2 [n]` `--notify [channel]` `--project [name]`
+- **modus:upgrade** `--help` `--check` `--dry-run` `--changelog` `--target [version]` `--project [name]`
+
 ## Skill status 生命周期
 
 | status    | 含义                    | 升级方式                          |

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

@@ -9,7 +9,7 @@ disable: false
 
 **调用方：** Harness Orchestrator（`modus-harness`）  
 **输入：** TAPD Story URL + 相关业务 Skill 内容  
-**产出物：** `modus/plans/active/{story-id}/01-analysis.md`
+**产出物：** `modus/stories/{story-id}/harness/01-analysis.md`
 
 ## 职责
 
@@ -23,7 +23,7 @@ disable: false
 
 1. 从 TAPD Story URL 获取需求内容（标题、描述、验收标准）
 2. 读取 Orchestrator 传入的相关业务 Skill 文件
-3. 读取 `modus/config.yaml` 中的项目背景信息
+3. 使用 Orchestrator 传入的 constitution 内容（来自 `{project}/modus/config.yaml`，无需独立读取）
 
 ### Step 2：业务分析
 
@@ -95,20 +95,19 @@ disable: false
 ## 产出物格式（01-analysis.md）
 
 ```markdown
-# 需求分析报告
-
-<!--HANDOFF
+---
+schema_version: "1.1"
 agent: "01-analysis"
+run_id: "{YYYYMMDD}-{story_id_prefix}"
 story_id: "{story-id}"
+task_id: ""
 domains: ["{domain1}", "{domain2}"]
-sprint_count: {N}
-risk_level: "{low|medium|high}"
-key_constraints:
-  - "{约束1，来自 constitution.hard_rules 或需求特殊限制}"
+gate_status: "{passed|failed}"
+artifact_status: "complete"
+issues: []
 skill_refs:
   - "modus-biz-{domain}@{version}"
-gate_status: "{passed|failed}"
--->
+---
 
 ## 基本信息
 - Story ID: {id}
@@ -153,6 +152,6 @@ gate_status: "{passed|failed}"
 - 每个风险点必须附带处理建议
 - Sprint 计划必须可直接指导 SubAgent 02 开发，不能含糊
 - 验收标准必须可测试（能直接写成测试用例）
-- **HANDOFF 块必须位于文件最顶部（Markdown 注释形式）**，`gate_status` 字段不可省略
+- **HANDOFF 块必须位于文件最顶部（YAML frontmatter 形式，`---...---`）**，`gate_status` 字段不可省略
 - `gate_status` 赋值规则：分析完整且无重大歧义 → `passed`；存在无法确认的关键信息 → `failed`（Orchestrator 会重入本 SubAgent）
 - `risk_level` 取值：有事务/并发/数据迁移风险 → `high`；有接口变更但逻辑清晰 → `medium`；纯新增无破坏 → `low`

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

@@ -8,8 +8,8 @@ disable: false
 # modus-developer（代码开发 SubAgent）
 
 **调用方：** Harness Orchestrator（Gate A0.5 通过后触发）  
-**输入：** `01-analysis.md` + `01.5-design-brief.md` + 业务 Skill 内容 + constitution  
-**产出物：** `modus/plans/active/{story-id}/02-sprint-contract.md` + 代码变更
+**输入：** `01-analysis.md` + `02-design-brief.md` + 业务 Skill 内容 + constitution  
+**产出物：** `modus/stories/{story-id}/harness/03-sprint-contract.md` + 代码变更
 
 ## 职责
 
@@ -21,7 +21,7 @@ disable: false
 
 ### Step 1：读取输入
 
-1. 读取 `01.5-design-brief.md`（技术方案，重点关注节 5-8）
+1. 读取 `02-design-brief.md`（技术方案，重点关注节 5-8）
 2. 读取 `01-analysis.md`（Sprint 执行计划、验收标准）
 3. 确认 `constitution.hard_rules` 和 `key_patterns`（最高优先级约束）
 4. 按需读取 Skill 关键文件索引中的实际代码文件（Level 3 加载，≤ 10 个文件）
@@ -105,17 +105,19 @@ Sprint 4：集成层（如有）
 ## 产出物格式（02-sprint-contract.md）
 
 ```markdown
-<!--HANDOFF
-agent: "02-developer"
+---
+schema_version: "1.1"
+agent: "03-dev"
+run_id: "{YYYYMMDD}-{story_id_prefix}"
 story_id: "{story-id}"
-sprint_count: {N}
-sprints_completed: {N}
+task_id: ""
+domains: ["{domain1}", "{domain2}"]
 gate_status: "{passed|failed}"
-changed_files:
-  - "{文件路径}"
-key_decisions:
-  - "{实现中做出的关键决策}"
--->
+artifact_status: "complete"
+issues: []
+skill_refs:
+  - "modus-biz-{domain}@{version}"
+---
 
 # 代码开发执行合同 — {Story 标题}