@modus-ai/modus 0.2.5 → 0.2.7

package/schemas/harness-schema.yaml

@@ -1,91 +1,216 @@
-# Modus Harness Schema
+# Modus Harness Schema v2.0
 # 定义 /modus:harness 双 Loop 多智能体流程的产出物及调度规则
+# 与 modus-harness/SKILL.md 保持完全一致（9 个 SubAgent：SA00~SA08）
+# 更新时间：2026-05-18
+
 name: harness
-description: 双 Loop 多智能体 Harness — 全自动需求分析、开发、测试、评审、部署流程
+version: "2.0"
+description: 双 Loop 多智能体 Harness — 全自动需求分析、设计、开发、测试、评审、部署流程
+schema_version: "1.1"  # HANDOFF 协议版本（见 docs/protocol.md）
+
+# 产物根目录（v3.2）
+directories:
+  harness: "modus/stories/{story-id}/harness/"
+  knowledge: "modus/knowledge/"
+  sessions: "modus/sessions/"
 
+# SubAgent 清单（SA00~SA08，共 9 个）
+# 命名偏移说明：SA02（设计）对应 Skill modus-harness-01-5-design（插入在 01 和 02 之间），
+# 导致后续 Skill 文件名编号比 SubAgent ID 少 1。HANDOFF agent 值以 SubAgent ID 为基准。
 subAgents:
+
+  - id: "00"
+    skill: modus-harness-00-skills-builder
+    handoff_agent: "00-skills-builder"
+    name: 知识注入/提取（Skills Builder）
+    generates:
+      - "Skill 文件（modus/knowledge/biz-*/SKILL.md）"
+      - "modus/knowledge-catalog.md"
+    requires: []
+    loop: 1
+    modes:
+      - "A: 新建 Skill"
+      - "B: 增量更新 Skill"
+      - "C: 知识批量写回"
+      - "D: ARCHIVE 知识提取"
+    notes: "INIT 阶段调用模式 B 更新知识，ARCHIVE 阶段调用模式 D 提取知识"
+
   - id: "01"
-    skill: modus-analyst
+    skill: modus-harness-01-analysis
+    handoff_agent: "01-analysis"
     name: 需求分析
-    generates: 01-analysis.md
-    requires: []
+    generates: ["modus/stories/{story-id}/harness/01-analysis.md"]
+    requires: ["00-INIT"]
     loop: 1
+    gateAfter: A0   # Gate A0: 检查 01-analysis.md HANDOFF gate_status = "passed"
+    max_retry: 2    # Gate A0 失败时最多重入 2 次
 
   - id: "02"
-    skill: modus-developer
-    name: 代码开发
-    generates: 02-sprint-contract.md
+    skill: modus-harness-01-5-design
+    handoff_agent: "02-design"
+    name: 设计方案生成
+    generates: ["modus/stories/{story-id}/harness/02-design-brief.md"]
     requires: ["01"]
     loop: 1
-    gateAfter: compile  # Gate A: 编译验证
+    human_checkpoint: true   # 架构决策确认 ⏸️ 人工交互节点
+    gateAfter: A05  # Gate A0.5: 检查 02-design-brief.md HANDOFF gate_status ∈ {passed, warning}
+    max_retry: 2
 
   - id: "03"
-    skill: modus-tester
-    name: 代码测试
-    generates: 03-test-report.md
+    skill: modus-harness-02-dev
+    handoff_agent: "03-dev"
+    name: 代码开发
+    generates: ["modus/stories/{story-id}/harness/03-sprint-contract.md"]
     requires: ["02"]
     loop: 1
-    parallel: ["03", "04", "05"]  # 与 04/05 并行
+    gateAfter: A    # Gate A: 执行 constitution.build_command，exit code = 0
+    max_retry: 3    # Gate A 失败时最多重入 3 次（含 Loop 2 精准重入）
 
   - id: "04"
-    skill: modus-perf-auditor
-    name: 性能审计
-    generates: 04-perf-report.md
-    requires: ["02"]
+    skill: modus-harness-03-test
+    handoff_agent: "04-test"
+    name: 代码测试（单元测试）
+    generates: ["modus/stories/{story-id}/harness/04-test-report.md"]
+    requires: ["03"]
     loop: 1
-    parallel: ["03", "04", "05"]
+    parallel: ["04", "05", "06"]  # 与 SA05/SA06 并行执行
+    gateAfter: B    # Gate B: 三份报告全部 artifact_status=complete
+    max_retry: 2
 
   - id: "05"
-    skill: modus-security-auditor
-    name: 安全审计
-    generates: 05-security-report.md
-    requires: ["02"]
+    skill: modus-harness-04-perf
+    handoff_agent: "05-perf"
+    name: 性能审计
+    generates: ["modus/stories/{story-id}/harness/05-perf-report.md"]
+    requires: ["03"]
     loop: 1
-    parallel: ["03", "04", "05"]
+    parallel: ["04", "05", "06"]
+    gateAfter: B
+    max_retry: 2
 
   - id: "06"
-    skill: modus-reviewer
-    name: 代码评审
-    generates: cr-report.md
-    requires: ["03", "04", "05"]  # Gate B: 等待 03/04/05 全部完成
-    loop: 2
+    skill: modus-harness-05-security
+    handoff_agent: "06-security"
+    name: 安全审计
+    generates: ["modus/stories/{story-id}/harness/06-security-report.md"]
+    requires: ["03"]
+    loop: 1
+    parallel: ["04", "05", "06"]
+    gateAfter: B    # Gate B 额外条件：安全报告无严重/高危未修复问题（强制拦截）
+    max_retry: 2
 
   - id: "07"
-    skill: modus-deployer
+    skill: modus-harness-06-review
+    handoff_agent: "07-review"
+    name: 代码评审（CR）
+    generates: ["modus/stories/{story-id}/harness/cr-report.md"]
+    requires: ["04", "05", "06"]  # Gate B 通过后触发
+    loop: 1                        # CR 在 Loop 1 执行；Loop 2 是对 SA03 的精准重入，非 CR 重跑
+    gateAfter: C    # Gate C: cr-report.md HANDOFF issues 为空或全为 P3
+
+  - id: "08"
+    skill: modus-harness-07-deploy
+    handoff_agent: "08-deploy"
     name: 部署发布
-    generates: 07-deploy-status.md
-    requires: ["06"]
-    loop: 2
-    gateAfter: noPnPProblems  # Gate C: cr-report.md 无 P1/P2
+    generates: ["modus/stories/{story-id}/harness/08-deploy-status.md"]
+    requires: ["07"]  # Gate C 通过后触发
+    loop: 1
+    human_checkpoint: true  # prd 环境等待人工确认
 
+# Gate 规则（强制，不可跳过）
 gates:
-  compile:
-    description: 编译验证
-    condition: "项目构建工具编译，exit code = 0"
+  A0:
+    description: "需求分析质量门"
+    checkFile: "01-analysis.md"
+    checkField: "gate_status"
+    condition: "gate_status = \"passed\""
+    onFail: retrySubAgent01
+    maxRetry: 2
+
+  A05:
+    description: "设计方案确认门（Gate A0.5）"
+    checkFile: "02-design-brief.md"
+    checkField: "gate_status"
+    condition: "gate_status ∈ {passed, warning}"
     onFail: retrySubAgent02
-    maxRetry: 3
+    maxRetry: 2
 
-  noPnPProblems:
-    description: 代码评审质量门
-    condition: "cr-report.md 中 P1 和 P2 问题数量为 0"
-    onFail: retryFromSubAgent02
+  A:
+    description: "编译验证门"
+    checkMethod: "execute constitution.build_command"
+    condition: "exit_code = 0"
+    onFail: retrySubAgent03
     maxRetry: 3
 
+  B:
+    description: "并行审计完成门"
+    checkFiles:
+      - "04-test-report.md"
+      - "05-perf-report.md"
+      - "06-security-report.md"
+    checkField: "artifact_status"
+    condition: "三份报告 artifact_status 均为 complete，且各 gate_status ≠ failed"
+    extraCondition: "06-security-report.md 中无严重/高危未修复问题（强制拦截）"
+    onFail: "继续等待（文件未齐）；gate_status=failed 则重入对应 SubAgent（最多 2 次）；超时 30 分钟上报用户"
+    timeout: "30m"
+
+  C:
+    description: "代码评审质量门"
+    checkFile: "cr-report.md"
+    checkField: "issues"
+    condition: "issues 数组为空，或全部 level 为 P3"
+    onFail: triggerLoop2
+    maxLoop2Retries: 3
+
+# Loop 2 精准重入规则
 loop2:
-  trigger: "cr-report.md 中存在 P1 或 P2 问题"
-  action: "定位涉及的 Sprint，精准重入 SubAgent 02（非全量重跑）"
-  rerunPath: ["02", "Gate A", "03+04+05", "06"]
-  maxLoops: 3
-  onMaxLoopsReached: "暂停流程，上报用户，请求人工介入"
+  trigger: "Gate C 失败（cr-report.md HANDOFF issues 含 P1 或 P2）"
+  sprintLocating:
+    primary: "issues[].affected_sprint 字段（整数，如 Sprint 2）"
+    fallback: "affected_sprint 缺失或为 0 时，重跑全量 Sprint（保守策略）"
+    multiple: "多个 issue 指向不同 Sprint 时，取编号并集一并重跑"
+  rerunPath: ["03（受影响 Sprint）", "Gate A", "04+05+06（并行）", "07"]
+  maxRetries: 3
+  onMaxRetriesReached: "暂停流程，上报用户，请求人工介入，写入 .harness-state.yaml"
 
-finalReview:
-  trigger: "Gate C 通过（cr-report.md 无 P1/P2）"
-  action: "等待人工 Final Review，确认后合入主干"
+# ARCHIVE 阶段（SA08 完成后触发，进入 Human Final Review 等待前执行）
+archive:
+  trigger: "SA08 部署完成（08-deploy-status.md artifact_status=complete）"
+  callSubAgent: "00（模式 D：知识提取）"
+  sourceArtifacts:
+    - "01-analysis.md"
+    - "02-design-brief.md"    # 提取架构决策 [decision] 知识
+    - "03-sprint-contract.md"
+    - "04-test-report.md"
+    - "05-perf-report.md"
+    - "06-security-report.md"
+    - "cr-report.md"
+    - "08-deploy-status.md"
+  knowledgeTypes:
+    - "[decision] - 来自 02-design-brief.md/03-sprint-contract.md 的技术选型"
+    - "[guideline] - 来自 08-deploy-status.md 的上线操作规范"
+    - "[pitfall] - 来自 cr-report.md P2/P3 和 04/05 报告高风险项"
+    - "[process] - 来自 01-analysis.md 的业务流程"
+    - "[invariant] - 来自 cr-report.md 和 01-analysis.md 的业务约束"
 
+# 断点续跑状态文件
+stateFile:
+  path: "modus/stories/{story-id}/harness/.harness-state.yaml"
+  fields:
+    story_id: "string"
+    loop: "integer（1 或 2）"
+    completed_agents: "string[]（已完成的 SubAgent ID 列表）"
+    current_agent: "string（当前正在执行的 SubAgent，空=全部完成）"
+    loop2_triggers: "Issue[]（Loop 2 触发的 P1/P2 问题列表）"
+    last_updated: "ISO 8601 时间戳"
+
+# 超时配置
 timeout:
-  perSubAgent: 15m
+  perSubAgent: "15m"
+  parallelGroup: "30m（SA04/05/06 并行组整体超时）"
   action: "汇报卡点，询问用户是否重试"
 
-directories:
-  active: modus/plans/active
-  archive: modus/plans/archive
+# Human Final Review
+finalReview:
+  trigger: "Gate C 通过 + ARCHIVE 完成"
+  action: "输出推荐 Commit Message，等待人工确认合入主干"

package/templates/agents/modus-analyst.md

@@ -9,6 +9,6 @@ enabled: true
 
 读取并严格遵循 `.codebuddy/skills/modus-analyst/SKILL.md` 中的执行规范。
 
-产出物路径：`modus/plans/active/{story-id}/01-analysis.md`
+产出物路径：`modus/stories/{story-id}/harness/01-analysis.md`
 
 产出物头部必须包含 HANDOFF 块，包含 `agent`、`story_id`、`domains`、`risk_level`、`key_constraints`、`skill_refs`、`gate_status` 字段。

package/templates/commands/auto.md

@@ -1,40 +1,74 @@
-# /modus:auto
+# /modus:auto — 智能模式推荐
 
-Smart mode recommendation. Reads a TAPD Story, scores it across 4 dimensions, recommends the best Modus mode, then launches it after human confirmation.
+**用途：** 读取 TAPD Story，从四个维度（复杂度/风险/需求明确度/接口契约）进行评分，自动推荐最适合的 Modus 命令（vibe/plan/spec/harness），确认后自动启动。**不确定用哪个命令时，首选此命令。**
 
-## Instructions
+## 执行流程
 
-Read and follow the skill at `.codebuddy/skills/modus-auto/SKILL.md` to execute this command.
+1. 接受 TAPD Story URL（或提示手动粘贴内容）
+2. 通过 TAPD MCP 读取 Story
+3. 四维评分：复杂度 / 风险 / 需求明确度 / 接口契约影响
+4. 应用决策树 → 推荐：vibe / plan / spec / harness
+5. 展示推荐结果 + 其他选项对比
+6. 等待人工选择确认
+7. 展示参数确认窗口（二次确认）
+8. 以 TAPD 上下文自动启动所选模式：
+   - **plan** 模式：附加 `[AUTO_MODE: questions_confirmed]` 标记，modus-plan Step 3 检测到后跳过交互式澄清
+   - **vibe** / **spec** / **harness** 模式：直接传入 TAPD 上下文
 
-## Quick Summary
+## 参数说明
 
-1. Accept a TAPD Story URL (or prompt for manual input if omitted)
-2. Read Story content via TAPD MCP
-3. Score the story across 4 dimensions: Complexity / Risk / Clarity / Contract Impact
-4. Apply the decision tree → recommend one of: vibe / plan / spec / harness
-5. Show recommendation with reasoning + comparison table of other options
-6. Wait for human mode selection
-7. Show parameter confirmation window (second confirmation step)
-8. Auto-launch the selected mode with TAPD context pre-filled:
-   - **plan** mode: appends `[AUTO_MODE: questions_confirmed]` + confirmed key info summary to the prompt; modus-plan Step 3 will skip interactive clarification when it detects this marker
-   - **vibe** / **spec** / **harness** modes: pass TAPD context directly without this marker
+```
+/modus:auto [tapd-url] [参数]
+
+  --help                    显示完整帮助（中文）
+  --project <name>          指定项目（多项目 workspace 使用）
+  --force <mode>            强制指定模式（vibe|plan|spec|harness），跳过推荐评分
+  --no-confirm              二次确认直接启动（CI/自动化场景使用）
+  --show-scores             展示四维评分详情（复杂度/风险/明确度/契约）
+  --dry-run                 仅展示推荐结果，不启动任何命令
+```
+
+## 使用示例
+
+```
+/modus:auto https://tapd.cn/.../stories/view/1234567890
+/modus:auto                              # 不带 URL，手动粘贴 Story 内容
+/modus:auto https://tapd.cn/.../1234 --show-scores
+/modus:auto https://tapd.cn/.../1234 --force harness
+/modus:auto https://tapd.cn/.../1234 --dry-run
+```
+
+## 推荐逻辑（四维评分）
 
-## Usage
+```
+维度 1 - 复杂度：预估文件变更数、跨域数量
+维度 2 - 风险：支付/权限/多租户/金额是否涉及
+维度 3 - 需求明确度：验收标准是否完整
+维度 4 - 接口契约影响：是否新增/修改/废弃接口
 
+推荐规则：
+  低复杂+低风险+无契约    → vibe
+  明确+中等+无契约        → plan
+  有接口契约/高风险       → spec
+  不明确/高复杂+高风险    → harness
 ```
-/modus:auto https://tapd.cn/company/stories/view/1234567890
-/modus:auto   (without URL — will prompt for manual Story content)
+
+## 推荐输出示例
+
 ```
+需求分析结果 — 新增歌曲批量导出功能
+──────────────────────────────────────
+复杂度:     中等  — 预估 4 个文件变更
+风险:       低    — 纯新增，不修改现有逻辑
+需求明确度: 高    — 验收标准完整
+接口契约:   有    — 新增 POST /api/v1/track/batch-export
 
-## Decision Tree (summary)
+推荐模式：/modus:spec
+理由：有新接口契约，建议用 spec 生成可测试验收规格。
 
-| Score | Recommended Mode |
-|-------|-----------------|
-| Low complexity + Low risk + No contract change | vibe |
-| Medium complexity + High clarity + No contract change | plan |
-| Any contract change OR High risk OR needs testable acceptance criteria | spec |
-| Low clarity OR High complexity + High risk OR full automation needed | harness |
+请选择：A. vibe  B. plan  C. spec（推荐）  D. harness
+```
 
-## When to Use
+## 执行此命令
 
-Use `/modus:auto` when you have a TAPD Story but are unsure which Modus mode fits best. The AI analyzes the story and presents a reasoned recommendation — you still make the final call.
+读取并执行 `.codebuddy/skills/modus-auto/SKILL.md` 中的完整流程。

package/templates/commands/harness.md

@@ -1,53 +1,113 @@
-# /modus:harness
+# /modus:harness — 双 Loop 全自动开发流程
 
-Full dual-loop multi-agent Harness. Automated end-to-end development flow from requirements analysis to deployment.
+**用途：** 输入 TAPD Story URL，自动执行从需求分析到部署验证的完整开发流程。8 个专业 SubAgent 分工协作，双 Loop 质量闭环，最终将开发经验自动沉淀到知识库。
 
-## Instructions
+**借鉴自：** GitHub Actions Job/Step/Gate 模型 + Devin 多步骤 Agent 架构
 
-Read and follow the skill at `.codebuddy/skills/modus-harness/SKILL.md` to execute this command.
+## 参数说明
 
-## Quick Summary
+```
+/modus:harness <tapd-url> [参数]
 
-1. Check for business Skills — if absent, strongly recommend running `/modus:init` first
-2. Accept TAPD Story URL as input
-3. Create working directory: `modus/plans/active/{story-id}/`
-4. Run the Harness Orchestrator which coordinates up to 9 SubAgents (00–07 + 01.5):
+  --help                    显示完整帮助（中文）
+  --project <name>          指定项目（多项目 workspace 使用）
+  --story <tapd-url>        与直接传 URL 等价（alias）
+  --skip <agents>           跳过指定 SubAgent（逗号分隔，如 "04-perf,05-security"）
+  --loop1-only              仅执行 Loop 1，不触发 Loop 2 自动修复
+  --resume                  从最后完成的 SubAgent 断点继续
+  --dry-run                 展示将执行的 SubAgent 列表和配置，不实际执行
+  --force-rebuild-skill     强制重建 Skill（忽略 hash 检查）
+  --no-deploy               跳过 07-deploy SubAgent（仅交付到 pre 环境）
+  --max-loop2 <n>           Loop 2 最大重入次数（默认 3，填 0 禁用 Loop 2）
+  --notify <channel>        完成后通知渠道（wework|dingtalk|slack）
+```
 
-**Loop 1 (sequential):**
-- SubAgent 00: Knowledge injection (Skill update/creation)
-- SubAgent 01: Requirements analysis → `01-analysis.md`
-- Gate A0: Validate `01-analysis.md` HANDOFF gate_status = "passed"
-- SubAgent 01.5: Design brief generation ⏸️ (human architecture decision confirmation) → `01.5-design-brief.md`
-- Gate A0.5: Validate `01.5-design-brief.md` HANDOFF gate_status ∈ {passed, warning}
-- SubAgent 02: Code development → `02-sprint-contract.md` + code changes
-- Gate A: Build compilation check
-- SubAgent 03/04/05 (parallel): Tests + Performance audit + Security audit
-- Gate B: Wait for all 3 reports
+## 使用示例
 
-**Loop 2 (quality gate):**
-- SubAgent 06: Code review → `cr-report.md`
-- If P1/P2 found → precise re-entry to SubAgent 02 → repeat
-- Gate C: No P1/P2 → proceed
-- SubAgent 07: Deployment verification → `07-deploy-status.md`
+```
+/modus:harness https://tapd.cn/.../stories/view/1234567890
+/modus:harness https://tapd.cn/.../1234 --dry-run
+/modus:harness https://tapd.cn/.../1234 --skip 04-perf,05-security
+/modus:harness https://tapd.cn/.../1234 --loop1-only
+/modus:harness https://tapd.cn/.../1234 --resume
+/modus:harness https://tapd.cn/.../1234 --max-loop2 0 --no-deploy
+```
 
 **Step Final:** SubAgent 00 (Mode D) — ARCHIVE knowledge extraction
 
 5. Final Review: human confirms before merging
 
-## Working Directory
+## 双 Loop 流程总览
+
+```
+Loop 1（生产层）
+  INIT:   SubAgent 00 知识注入（更新相关 Skill 至最新）
+  SA 01:  需求分析 → 01-analysis.md
+  SA 02:  代码开发 → 02-sprint-contract.md + 代码变更
+  Gate A: 编译验证（mvn clean compile）→ 失败重入 SA 02，最多 3 次
+  SA 03+04+05: 并行（测试/性能/安全）
+  Gate B: 三份报告全部 complete
+  SA 06:  代码评审 → cr-report.md
+
+Loop 2（修复层）
+  Gate C: 读 cr-report.md 的 issues 列表
+  → 有 P1/P2：精准重入受影响 Sprint（非全量重跑），最多 3 次
+  → 通过：进入收尾
+
+收尾
+  SA 07:  部署验证 → 07-deploy-status.md（prd 等待人工确认）
+  ARCHIVE: 知识提取回写 Skill + 更新 catalog
+  Human Final Review: 人工确认后合入主干
+```
+
+## Pipeline 状态输出（GitHub Actions 风格）
+
+```
+[SA-00] ✓ 知识注入 (3 Skill 更新, 0s)
+[SA-01] ✓ 需求分析 (2 Sprint, Gate: N/A, 45s)
+[SA-02] ✓ 代码开发 (4 files, Gate A: passed, 2m30s)
+[SA-03] ✓ 单元测试 (coverage: 82%, Gate B: -, 1m15s)
+[SA-04] ✓ 性能审计 (0 high, 1 medium, Gate B: -, 45s)
+[SA-05] ✓ 安全审计 (0 critical, Gate B: passed, 50s)
+[SA-06] ✓ 代码评审 (P1:0 P2:1 P3:2, Gate C: failed → Loop2)
+[Loop2] ✓ 精准修复 Sprint-2 (1 P2 已修复, 1m20s)
+[SA-06] ✓ 代码评审 Re-run (P1:0 P2:0 P3:2, Gate C: passed)
+[SA-07] ✓ 部署验证 dev→uat→pre (3/3 通过, prd 等待人工)
+[ARCH]  ✓ 知识沉淀 (2 [pitfall], 1 [decision] 回写)
+```
+
+## 产出物
 
 ```
 modus/plans/active/{story-id}/
-├── 01-analysis.md          ← SubAgent 01 产出，含 HANDOFF 块
+├── 01-analysis.md          ← SubAgent 01 产出，含 HANDOFF 块（影响范围、Sprint 拆分）
 ├── 01.5-design-brief.md    ← SubAgent 01.5 产出，含架构决策
-├── 02-sprint-contract.md   ← SubAgent 02 产出，含代码变更清单
-├── 03-test-report.md       ← SubAgent 03 产出
-├── 04-perf-report.md       ← SubAgent 04 产出
-├── 05-security-report.md   ← SubAgent 05 产出
-├── cr-report.md            ← SubAgent 06 产出，含 HANDOFF.issues
-└── 07-deploy-status.md     ← SubAgent 07 产出
+├── 02-sprint-contract.md   ← SubAgent 02 产出，含代码变更清单（接口契约）
+├── 03-test-report.md       ← SubAgent 03 产出（单元测试报告）
+├── 04-perf-report.md       ← SubAgent 04 产出（性能审计 N+1/分页风险）
+├── 05-security-report.md   ← SubAgent 05 产出（安全审计 多租户/权限）
+├── cr-report.md            ← SubAgent 06 产出，含 HANDOFF.issues（P1/P2/P3）
+└── 07-deploy-status.md     ← SubAgent 07 产出（部署状态 各环境结果）
+```
+
+所有产出物头部包含 HANDOFF 块（schema v1.1，见 `modus/docs/protocol.md`）。
+
+## HANDOFF 协议（SubAgent 间传递信息）
+
+```markdown
+<!--HANDOFF
+schema_version: "1.1"
+agent: "01-analysis"
+run_id: "{YYYYMMDD}-{story_id}"
+story_id: "{tapd-story-id}"
+domains: ["biz-track", "biz-album"]
+gate_status: "passed"
+artifact_status: "complete"
+issues: []
+skill_refs: ["biz-track@v2.1"]
+-->
 ```
 
-## Resume Support
+## 执行此命令
 
-If `modus/plans/active/{story-id}/` already contains partial artifacts, resume from the last completed SubAgent.
+读取并执行 `.codebuddy/skills/modus-harness/SKILL.md` 中的完整流程。

package/templates/commands/init.md

@@ -1,16 +1,49 @@
-# /modus:init
+# /modus:init — 业务知识库初始化
 
-Analyze the project codebase, classify it by business domains, and generate business Skill files for each domain.
+**用途：** 扫描项目代码，按业务域分类，在 `modus/knowledge/` 下生成结构化 Skill 文件，作为后续所有 Modus 命令的知识底座。支持多项目工作区路由和多平台引用式适配。
 
-## Instructions
+## 参数说明
 
-Read and follow the skill at `.codebuddy/skills/modus-init/SKILL.md` to execute this command.
+```
+/modus:init [参数]
 
-## Quick Summary
+  --help                    显示完整帮助（中文）
+  --project <name>          指定项目（多项目 workspace 使用）
+  --enhance <domain>        仅增量更新指定业务域（如 --enhance biz-track）
+  --enhance-all             重建所有业务域 Skill（保留框架 Skill）
+  --platform <p1,p2>        仅同步指定平台（claude,cursor,codex,copilot）
+  --dry-run                 预览将生成/修改的文件，不写入磁盘
+  --force                   跳过所有确认提示，直接执行
+  --no-sync                 跳过多平台同步，仅生成 modus/knowledge/
+  --migrate                 迁移旧路径 .codebuddy/skills/modus-biz-* → modus/knowledge/
+  --verbose                 输出详细扫描过程
+  --reset-maturity          重置所有 Skill 的 maturity 为 draft
+```
 
-1. Scan the project structure and identify business domains
-2. Present the domain classification to the user for confirmation
-3. For each confirmed domain, generate `.codebuddy/skills/modus-biz-{domain}/SKILL.md`
-4. Report completion
+## 使用示例
 
-If `.codebuddy/skills/modus-biz-*` directories already exist, offer to update or rebuild them.
+```
+/modus:init                          # 全量初始化（首次使用或大重构后）
+/modus:init --help                   # 查看帮助
+/modus:init --enhance biz-track      # 仅更新歌曲域知识
+/modus:init --migrate --dry-run      # 预览知识库路径迁移
+/modus:init --migrate                # 执行迁移（旧路径 → modus/knowledge/）
+/modus:init --enhance-all --no-sync  # 重建所有域，不同步平台
+/modus:init --project operations-job # 多项目时指定项目
+```
+
+## 产出物
+
+```
+modus/knowledge/
+├── _conventions/SKILL.md   — Layer 0-T 团队约定（融合各平台规则）
+├── _tech-wiki/SKILL.md     — Layer 1 技术知识骨架
+└── biz-{domain}/SKILL.md   — Layer 2 业务域知识（每个域一个）
+
+modus/knowledge-catalog.md  — 全景索引（所有命令的快速入口）
+modus/workspace-catalog.md  — 工作区顶层路由（多项目）
+```
+
+## 执行此命令
+
+读取并执行 `.codebuddy/skills/modus-init/SKILL.md` 中的完整流程。