@modus-ai/modus 0.2.4 → 0.2.6

package/templates/commands/auto.md

@@ -1,38 +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
+```
+/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/commit.md

@@ -0,0 +1,63 @@
+# /modus:commit
+
+Knowledge-aware git commit. Drains pending knowledge from `modus/sessions/pending-knowledge.yaml` into the corresponding business Skill files, then executes the actual git commit.
+
+## Instructions
+
+Read and follow the steps below to execute this command.
+
+## What It Does
+
+During `/modus:vibe` sessions, newly discovered knowledge (new enum values, business rules, pitfalls) is buffered to `modus/sessions/pending-knowledge.yaml` rather than written directly to Skill files. This prevents exploratory or incomplete sessions from polluting the knowledge base.
+
+`/modus:commit` is the trigger that drains this buffer at the right moment — when code is confirmed ready to commit.
+
+## Execution Steps
+
+1. **Check pending knowledge buffer:**  
+   Read `modus/sessions/pending-knowledge.yaml` (if it exists).  
+   If empty or absent → skip to Step 4 and execute a normal git commit.
+
+2. **Show pending entries for confirmation:**
+   ```
+   📚 发现 {N} 条待沉淀知识（来自最近 {K} 次 vibe 会话）：
+   
+     · [pitfall] order 域：批量操作超 50 条需分批处理
+       证据: OrderService.java:142
+     · [guideline] order 域：新增审批流必须记录审批人 ID 到日志
+       证据: OrderManager.java:89
+     · [model] payment 域：PayStatus 新增 REFUNDING 枚举值
+       证据: PayStatus.java:15
+   
+   是否将以上知识写入对应 Skill 文件？[Y/n]
+   ```
+
+3. **Write back to Skills (if confirmed):**  
+   For each entry in `pending-knowledge.yaml`:
+   - Call `modus-skill-creator` Mode C to append the entry to the corresponding `modus-biz-{domain}/SKILL.md`
+   - Mark the entry as `settled: true` in `pending-knowledge.yaml`
+   - Output per-entry status: `✓ [pitfall] → modus-biz-order 已写入`
+
+   After all entries processed:
+   - Remove settled entries from `pending-knowledge.yaml` (keep only `settled: false` entries)
+   - Update `modus/knowledge-catalog.md` if any Skill version changed
+
+4. **Execute git commit:**  
+   Run the standard git commit flow:
+   ```bash
+   git add .
+   git commit
+   ```
+   (Opens editor for commit message or accepts message from user input)
+
+5. **Output summary:**
+   ```
+   ✅ 知识沉淀完成（{N} 条已写入 Skill）
+   ✅ Git commit 执行完成
+   ```
+
+## Notes
+
+- If the user skips knowledge write-back (answer `n`), the entries remain in `pending-knowledge.yaml` for the next `/modus:commit` call.
+- Entries with `settled: false` that are older than 30 days will be highlighted with `⚠️ 较旧` to prompt cleanup.
+- This command only handles knowledge write-back for `/modus:vibe` sessions. Knowledge from `/modus:plan`, `/modus:spec`, and `/modus:harness` is written back immediately (not buffered).

package/templates/commands/harness.md

@@ -1,46 +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> [参数]
+
+  --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）
+```
 
-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 7 SubAgents:
+## 使用示例
 
-**Loop 1 (sequential):**
-- SubAgent 01: Requirements analysis → `01-analysis.md`
-- 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
+```
+/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
+```
 
-**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`
+**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
-├── 02-sprint-contract.md
-├── 03-test-report.md
-├── 04-perf-report.md
-├── 05-security-report.md
-├── cr-report.md
-└── 07-deploy-status.md
+├── 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 产出（性能审计 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` 中的完整流程。

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` 中的完整流程。