@modus-ai/modus 0.2.5 → 0.2.7

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

@@ -1,59 +1,393 @@
 ---
 name: modus-auto
-description: Use this skill when executing /modus:auto command. Reads a TAPD Story URL, scores it across 4 dimensions (complexity/risk/clarity/contract-impact), recommends the best Modus mode (vibe/plan/spec/harness), presents reasoning, waits for human mode selection, then auto-launches the chosen mode with context pre-filled. Trigger on /modus:auto command.
+description: Use this skill when executing /modus:auto command. Reads a TAPD Story URL (or manual input), scores it across 4 dimensions (complexity/risk/clarity/contract-impact), recommends the best Modus mode (vibe/plan/spec/harness) using Cursor-style mode routing + Swarm-style context handoff, presents reasoning, then launches the chosen mode with full context pre-filled. In Codex environment: single-shot decision with auto-execution (no interactive wait). Trigger on /modus:auto command.
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
 
-# modus-auto（智能模式推荐）
+# modus-auto（智能模式路由）
 
-**触发条件：** 用户运行 `/modus:auto [TAPD Story URL]` 时使用此 Skill。
+**触发条件：** 用户运行 `/modus:auto [TAPD URL 或需求描述]` 时使用此 Skill。
 
-## 职责
+---
+
+## 设计理念
+
+### 业界借鉴
+
+**1. Cursor 三模式路由（Ask / Plan / Agent）**
+
+参照 Cursor 的模式设计哲学：根据任务特征自动选择交互深度。
+- `Ask（只问不改）` → 对应 `vibe`（直接编码，轻量）
+- `Plan（先规划再执行）` → 对应 `plan` / `spec`
+- `Agent（全自动执行）` → 对应 `harness`
+
+Cursor 设计核心：**模式切换有理由，每次推荐都附带简短的切换原因**，降低用户心智负担。本 Skill 完全复用此理念。
+
+**2. OpenAI Swarm 的 Agent Handoff + Context 透传**
+
+参照 Swarm 的 `Handoff` 机制：当 auto 决定路由到某个模式时，不仅仅传递 URL，而是构造一个**完整的结构化上下文包（Context Bundle）**，使目标模式无需重复读取 TAPD，直接进入执行阶段。
+
+```
+Context Bundle = {
+  story_id, story_title, story_desc, acceptance_criteria,
+  domains[], scores{}, recommended_mode, skip_clarify: true
+}
+```
+
+**3. LangGraph 的条件边路由可视化**
+
+输出时展示类似 LangGraph Conditional Edge 的决策路径，让用户看到每个维度如何影响最终路由：
+
+```
+[TAPD Story] → [四维评分] → {复杂度=中,风险=低,契约=有} → [spec]
+```
+
+**4. GitHub Copilot Workspace 的多步规划流程**
+
+参照 Copilot Workspace 在给出建议前先「理解意图 → 分解任务 → 确认方案」的三段式流程，auto 在路由前同样先做意图提取，确保传给目标模式的 Context Bundle 足够准确，避免目标模式从零开始理解需求。
 
-读取 TAPD Story 内容，从四个维度评分，推荐最合适的 Modus 模式（vibe/plan/spec/harness），展示推荐理由和备选对比，等待用户选择，确认参数后自动透传 TAPD 内容启动所选模式。
+**5. Linear / Jira AI 的上下文感知 Issue 路由**
+
+参照 Linear AI 根据 issue 类型、优先级、关联标签自动分配处理流程的理念，auto 的四维评分矩阵等效于 issue 的 label 系统，不同 label 组合触发不同工作流。
+
+---
+
+## 参数参考（完整列表）
+
+```
+/modus:auto [tapd-url 或需求描述] [参数]
+
+输入来源：
+  --story <id>              接受纯 Story ID（不含完整 URL），如 --story 1234567890
+  --skip-tapd               跳过 TAPD MCP 读取，进入手动粘贴模式（离线场景）
+  --context <file>          注入额外上下文文件（需求截图、设计文档路径等，如 --context design.md）
+  --resume                  从上次中断的 auto 会话恢复（断点续跑，读取上次评分缓存）
+
+分析控制：
+  --domain <name>           预先指定业务域（跳过域识别步骤，如 --domain biz-order）
+  --explain                 在评分输出中附上每个维度的详细判定依据说明
+  --scores-only             仅输出四维评分表，不继续路由（供 CI/脚本消费）
+  --show-scores             展示四维评分详情及权重计算过程（比 --explain 更简洁）
+
+执行控制：
+  --force <mode>            强制指定模式（vibe|plan|spec|harness），跳过推荐评分直接启动
+  --no-confirm              跳过二次确认，评分完成后直接启动推荐模式（Codex/CI 场景用）
+  --dry-run                 仅输出推荐结果和路由路径，不启动任何命令
+  --preview                 预览推荐模式的产物目录结构，不执行任何命令
+  --timeout <n>             TAPD MCP 调用超时（秒），默认 10
+  --no-cache                强制重新读取 TAPD，跳过本地缓存
+
+项目与格式：
+  --project <name>          指定项目（多项目 workspace 必填，如 --project my-service）
+  --template <style>        输出样式：minimal（仅结论）| standard（默认）| verbose（含完整推理）
+  --output <format>         结果输出格式（terminal默认 | markdown | json，json 供工具链消费）
+  --lang <zh|en>            响应语言，默认 zh（中文）
+
+调试：
+  --verbose                 输出完整评分推理过程（每个维度的判定理由）
+  --budget <tokens>         限制 Skill 加载的上下文量（默认 3000 tokens，省 token 时用）
+  --help                    显示完整帮助（中文），列出所有参数和用法示例
+```
+
+### 参数组合示例
+
+```bash
+# 最常用：直接分析 TAPD Story
+/modus:auto https://tapd.cn/company/stories/view/1234567890
+
+# 使用纯 Story ID（不需要完整 URL）
+/modus:auto --story 1234567890
+
+# 看评分细节 + 每维度判定说明
+/modus:auto https://tapd.cn/.../1234 --show-scores --explain
+
+# 强制跳过评分，直接 harness
+/modus:auto https://tapd.cn/.../1234 --force harness
+
+# 不带 URL，手动描述需求（Codex 常用）
+/modus:auto 新增批量导出接口，支持按条件筛选，返回 Excel
+
+# CI/全自动场景：只输出评分，不路由
+/modus:auto https://tapd.cn/.../1234 --scores-only --output json
+
+# CI/全自动场景：不等用户确认
+/modus:auto https://tapd.cn/.../1234 --no-confirm
+
+# 预览推荐模式会产出哪些文件，不实际执行
+/modus:auto https://tapd.cn/.../1234 --preview
+
+# 导出 JSON 供外部工具读取
+/modus:auto https://tapd.cn/.../1234 --dry-run --output json
+
+# 离线场景（无 TAPD 访问）
+/modus:auto --skip-tapd
+
+# 注入需求截图/设计文档
+/modus:auto https://tapd.cn/.../1234 --context docs/api-design.md
+
+# 多项目工作区
+/modus:auto https://tapd.cn/.../1234 --project my-service
+
+# 恢复上次中断的 auto 会话
+/modus:auto --resume
+
+# 简洁输出（仅结论，适合快速决策）
+/modus:auto https://tapd.cn/.../1234 --template minimal
+
+# 强制重读 TAPD（Story 内容有更新时）
+/modus:auto https://tapd.cn/.../1234 --no-cache
+```
+
+---
+
+## --help 响应模板
+
+当用户运行 `/modus:auto --help` 时，输出以下内容：
+
+```
+Modus Auto — 智能模式路由工具
+版本：3.3.0
+
+用途：
+  不确定该用哪个 Modus 命令时，首选此命令。
+  读取 TAPD Story（或手动描述需求），从四个维度评分，自动推荐最适合
+  的执行模式（vibe/plan/spec/harness），确认后透传上下文直接启动。
+
+  设计参照：
+    · Cursor Ask/Plan/Agent 三模式路由理念（模式切换有理由）
+    · OpenAI Swarm 的 Context Bundle 透传机制（无缝 Handoff）
+    · LangGraph 的条件边决策可视化（路由过程透明可追溯）
+    · GitHub Copilot Workspace 的意图理解→任务分解三段式流程
+    · Linear AI 的上下文感知 Issue 路由（标签组合触发工作流）
+
+语法：
+  /modus:auto [tapd-url 或需求描述] [参数]
+
+输入来源：
+  --story <id>         接受纯 Story ID，如 --story 1234567890
+  --skip-tapd          跳过 TAPD 读取，手动输入需求
+  --context <file>     注入额外上下文文件（设计文档/截图）
+  --resume             从上次中断的 auto 会话恢复
+
+分析控制：
+  --domain <name>      预指定业务域（如 biz-order/biz-payment），跳过识别
+  --explain            在评分中附上每维度详细判定依据
+  --scores-only        仅输出评分表，不路由（CI 脚本用）
+  --show-scores        显示评分详情及计算过程
+
+执行控制：
+  --force <mode>       强制指定模式（vibe|plan|spec|harness），跳过评分
+  --no-confirm         不等待确认，直接执行推荐模式
+  --dry-run            只推荐不执行
+  --preview            预览推荐模式的产物目录，不执行
+  --timeout <n>        TAPD MCP 调用超时秒数（默认 10）
+  --no-cache           强制重读 TAPD，跳过缓存
+
+项目与格式：
+  --project <name>     指定项目（多项目时使用）
+  --template <style>   输出样式：minimal | standard | verbose
+  --output <format>    输出格式（terminal|markdown|json）
+  --lang <zh|en>       响应语言（默认 zh）
+
+调试：
+  --verbose            输出完整推理过程（含每维度理由）
+  --budget <tokens>    限制上下文加载量（默认 3000）
+  --help               显示本帮助
+
+四种模式说明（行业框架对照）：
+  vibe    → 直接编码，适合低风险、单文件、bug fix
+            类比：GitHub Copilot 内联补全 — 有把握直接写
+  plan    → 先规划再执行，适合明确中等需求
+            类比：Cursor Plan 模式 — 先只读扫描确认方案，再动手
+  spec    → 规范驱动开发，适合接口契约变更、高风险需求
+            类比：OpenAPI Spec + BDD（Cucumber）— 先定契约和验收场景
+  harness → 全自动双Loop流水线，适合模糊复杂需求
+            类比：GitHub Actions CI/CD — 多 SubAgent 串并行全托管
+
+快速决策口诀：
+  改一个文件？→ vibe
+  需求清楚但要规划？→ plan
+  有接口变更或高风险？→ spec
+  需求模糊或要全自动？→ harness
+
+示例：
+  /modus:auto https://tapd.cn/company/stories/view/1234567890
+  /modus:auto --story 1234567890 --domain biz-order
+  /modus:auto 新增批量导出接口 --explain
+  /modus:auto https://tapd.cn/.../1234 --force spec --no-confirm
+  /modus:auto --skip-tapd --verbose
+  /modus:auto https://tapd.cn/.../1234 --scores-only --output json
+  /modus:auto --resume
+
+更多文档：modus/knowledge-catalog.md
+```
 
 ---
 
 ## 执行流程
 
-### Step 1：读取 TAPD Story
+### ⚡ 平台检测（首步）
+
+在执行任何流程前，检测当前运行平台（优先级从高到低）：
+
+```
+检测顺序：
+1. 环境变量 OPENAI_CODEX=1 或 CODEX_ENV=true         → Codex 路径
+2. 存在 AGENTS.md 且运行环境为非交互式终端             → Codex 路径
+3. 用户 prompt 包含 Codex 触发关键词（见下方列表）     → Codex 路径
+4. 无 AskUser 工具可用（最终兜底）                    → Codex 路径
+5. 以上均不满足                                       → 标准交互路径
+
+Codex 自然语言触发关键词（无需 /modus:auto 命令格式）：
+  中文：开始开发、帮我分析这个需求、这个 Story 用哪个模式、全自动跑一遍、
+        帮我路由、分析需求然后开发、选个模式
+  英文：analyze this story, start development, which mode should I use,
+        auto route, run full pipeline, pick a mode for this
+```
+
+---
+
+### 🤖 Codex 单次执行路径（Step 0-C）
+
+> Codex 环境特点：无交互等待、无 AskUser、可能无 TAPD MCP、自然语言触发
+
+**0-C-1：上下文读取（含降级处理）**
+
+```python
+# 1. 尝试读取 TAPD Story（失败则优雅降级）
+try:
+    story = tapd_mcp.get_story(story_id)
+except MCP_UNAVAILABLE:
+    story = extract_from_natural_language(user_input)
+    note = "⚠️ TAPD MCP 不可用，基于描述文本进行评分"
+
+# 2. 尝试读取知识目录（文件系统不可用时跳过）
+try:
+    catalog = read("modus/knowledge-catalog.md")
+    # v3.2 路径：modus/knowledge/biz-*/SKILL.md（唯一权威）
+except FILESYSTEM_UNAVAILABLE:
+    catalog = None
+    note += " | 文件系统不可用，跳过 Skill 加载，基于 Story 文本评分"
+```
+
+**0-C-2：自动评分 + 单次决策**
+
+直接完成四维评分，不等待用户输入，输出推荐结果并**立即启动**推荐模式：
+
+```
+[Codex 模式] 自动分析中...
+─────────────────────────────
+复杂度: 中等 — 涉及 2 个业务域
+风险:   低   — 纯新增功能
+明确度: 高   — 验收标准完整
+契约:   有   — 新增 POST /api/v1/xxx/export
+
+决策路径：中等复杂 + 有接口契约 → spec
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+自动启动 /modus:spec（Codex 模式，跳过确认）
+```
+
+**0-C-3：Context Bundle 透传**
+
+构造结构化上下文包传递给目标模式：
+
+```yaml
+context_bundle:
+  story_id: "1234567890"
+  story_title: "{Story 标题}"
+  domains: ["{domain}"]
+  domain_skill_path: "modus/knowledge/{domain}/SKILL.md"   # v3.2 路径
+  scores: {complexity: 2, risk: 1, clarity: 3, contract: 1}
+  recommended_mode: "spec"
+  skip_clarify: true
+  from_auto: true
+  platform: "codex"
+  filesystem_available: false
+```
+
+**0-C-4：结构化 JSON 日志输出（--output json 时）**
+
+```json
+{
+  "mode": "codex",
+  "story_id": "1234567890",
+  "story_title": "{Story 标题}",
+  "scores": {"complexity": 2, "risk": 1, "clarity": 3, "contract": 1},
+  "recommended": "spec",
+  "reason": "有接口契约变更，建议规范驱动开发",
+  "domains": ["{domain}"],
+  "context_bundle_path": null,
+  "auto_launched": true,
+  "tapd_available": true,
+  "filesystem_available": false
+}
+```
+
+---
+
+### 📋 标准交互路径（Step 1-7）
+
+#### Step 1：读取 TAPD Story
 
 通过 TAPD MCP 读取 Story 内容：
 
 ```bash
-# 从 URL 提取 story-id，调用 TAPD MCP 获取内容
-story_id = extract_from_url(tapd_url)
+story_id = extract_from_url(tapd_url)    # 支持完整 URL
+# 或
+story_id = args["--story"]               # 支持纯 ID（--story 1234567890）
 story = tapd_mcp.get_story(story_id)
 ```
 
-提取以下字段：
-- 标题、描述、验收标准
-- 优先级、预估工时
-- 涉及模块（从标题/描述中判断）
-- 迭代/Sprint 信息
+提取字段：标题、描述、验收标准、优先级、预估工时、涉及模块、迭代信息。
+
+若 TAPD MCP 不可用，提示：
+```
+⚠️ TAPD MCP 不可用，请粘贴 Story 内容（以 ---END--- 结束）：
+```
+
+若用户带 `--skip-tapd` 参数，直接进入手动输入模式。
+
+若用户直接描述需求（非 URL），从自然语言中提取关键信息，继续执行。
 
-若 TAPD MCP 不可用，提示用户手动粘贴 Story 内容，继续执行。
+若用户带 `--resume`，尝试读取上次会话缓存：
+```bash
+cache = read(".modus-auto-cache.yaml")
+if cache.valid:
+    跳过 Step 1-3，直接从 Step 4 路由决策继续
+```
 
-### Step 2：读取知识目录
+#### Step 2：读取知识目录
 
-读取 `modus/knowledge-catalog.md`，了解可用的业务 Skill 及其成熟度。用于判断哪些域已有充足上下文。
+读取 `modus/knowledge-catalog.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
+
+⚠️ 注意（v3.1+ 变更）：业务域 Skill 已迁移至 modus/knowledge/biz-*/SKILL.md，
+   .codebuddy/skills/modus-biz-* 为引用桩，不含实际内容，请勿从旧路径读取。
+```
 
-### Step 3：四维评分
+若用户指定了 `--domain <name>`，跳过自动域识别，直接加载对应 Skill。
 
-对 Story 内容进行结构化分析，输出每个维度的评分：
+若用户指定了 `--budget <tokens>`，按限额裁剪 Skill 加载量。
 
-#### 维度一：复杂度 (Complexity)
+#### Step 3：四维评分
+
+对 Story 进行结构化评分：
+
+##### 维度一：复杂度 (Complexity)
 
 | 分值 | 判定条件 |
 |------|----------|
 | 低 (1) | 单文件修改、bug fix、文案/配置调整 |
 | 中 (2) | 1-2 个业务域、5 个以内文件变更、新增接口但无架构变化 |
-| 高 (3) | 跨 3+ 个域、需新建数据表、涉及消息队列/异步流程 |
-
-判断依据：Story 描述中的关键词（"新增表"、"重构"、"接入 MQ"、涉及文件数估算）
+| 高 (3) | 跨 3+ 个域、需新建数据表、涉及消息队列/异步流程/数据迁移 |
 
-#### 维度二：风险 (Risk)
+##### 维度二：风险 (Risk)
 
 | 分值 | 判定条件 |
 |------|----------|
@@ -61,9 +395,7 @@ story = tapd_mcp.get_story(story_id)
 | 中 (2) | 修改已有接口或业务逻辑，影响单一模块 |
 | 高 (3) | 涉及支付/权限/多租户隔离/金额计算/数据迁移/接口废弃 |
 
-#### 维度三：需求明确度 (Clarity)
-
-> ⚠️ **刻度方向与复杂度/风险相反**：分值越高 = 需求越清晰（好）。判定树中「明确度=低」触发 harness，「明确度=高」支持 plan，方向勿与其他维度混淆。
+##### 维度三：需求明确度 (Clarity)
 
 | 分值 | 判定条件 |
 |------|----------|
@@ -71,155 +403,280 @@ story = tapd_mcp.get_story(story_id)
 | 中 (2) | 有基本描述，部分细节待确认 |
 | 低 (1) | 描述模糊、无验收标准、需大量澄清 |
 
-#### 维度四：接口契约影响 (Contract Impact)
+##### 维度四：接口契约影响 (Contract Impact)
 
 | 分值 | 判定条件 |
 |------|----------|
 | 无 (0) | 纯内部逻辑，不影响对外接口 |
 | 有 (1) | 新增接口、修改现有接口签名/返回值、废弃接口 |
 
-### Step 4：判定推荐模式
-
-根据四维评分，按以下判定树确定推荐模式：
-
+若用户带 `--explain`，对每个维度输出判定依据：
+```
+复杂度=中(2)：涉及单域，预估变更 4 个文件，无新建表，
+               关键词命中：「新增接口」「按条件筛选」
 ```
-复杂度=低 且 风险=低 且 接口契约影响=无
-  → 推荐 vibe（直接编码，无需文档）
 
-复杂度=低/中 且 明确度=高 且 接口契约影响=无
-  → 推荐 plan（功能规划，有 proposal+design+tasks）
+若用户带 `--scores-only`，输出评分表后直接结束，不继续路由。
 
-任意维度满足以下任一：
-  - 接口契约影响=有
-  - 风险=高
-  - 需要可测试的验收标准
-  → 推荐 spec（规范驱动，含 delta specs + GIVEN/WHEN/THEN）
+#### Step 4：路由决策（LangGraph 条件边）
 
-以下情况推荐 harness：
-  - 明确度=低（需求不清晰，AI 自动分析更可靠）
-  - 复杂度=高 且 风险=高
-  - 用户希望全自动从需求到部署
-  → 推荐 harness（双 Loop 全自动流程）
+根据四维评分，按以下决策树路由：
 
-**优先级规则（多条件同时满足时）：**
-  harness > spec > plan > vibe
-  即：若 harness 条件与 spec 条件同时满足，推荐 harness；
-      若 spec 条件与 plan 条件同时满足，推荐 spec；以此类推。
-  向用户展示次优选项以供参考。
+```
+                    ┌─ TAPD Story / 需求描述 ─┐
+                    ▼                          
+             [四维评分引擎]
+          C=复杂度  R=风险  Cl=明确度  I=契约
+                    │
+        ┌───────────┼───────────┬──────────────┐
+        ▼           ▼           ▼              ▼
+   C=低,R=低    Cl=高,无I    I=有或R=高    Cl=低或
+    且无I       且中低复杂    需可测规格   C=高且R=高
+        │           │           │              │
+      vibe        plan         spec          harness
+   直接编码     先规划        规范驱动       全自动流水线
 ```
 
-### Step 5：展示推荐与对比
+**判定规则（优先级从高到低）：**
 
-**输出格式：**
+```
+1. 明确度=低（Cl=1）且 复杂度=高（C=3）  → harness
+2. 接口契约=有（I=1）                     → spec
+3. 风险=高（R=3）                         → spec
+4. 明确度=低（Cl=1）                      → harness
+5. 复杂度=低（C=1）且 风险=低（R=1）      → vibe
+6. 明确度=高（Cl=3）且 契约=无（I=0）     → plan
+7. 其他情况                               → plan（默认安全选择）
+```
+
+若用户带 `--force <mode>`，跳过以上判定，直接路由到指定模式。
 
+若用户带 `--preview`，路由完成后输出产物目录预览，然后停止：
+```
+预览：/modus:spec 将在以下路径生成产物
+  modus/stories/{id}/spec/
+    ├── .modus-state.yaml
+    ├── delta/{domain}.md
+    ├── design.md
+    ├── design-brief.md
+    └── tasks.md
+（--preview 模式：不执行任何命令）
 ```
-📊 需求分析结果 — {Story 标题}
-─────────────────────────────────────────
-复杂度:     {低/中/高}  — {一句话理由}
-风险:       {低/中/高}  — {一句话理由}
-需求明确度: {低/中/高}  — {一句话理由}
-接口契约:   {无/有}    — {一句话理由}
 
-🎯 推荐模式：/modus:{mode}
-理由：{2-3 句话说明为何这个模式最合适}
+若用户带 `--dry-run`，输出推荐结果后停止，不启动任何命令。
 
-📋 其他选项对比：
-  plan    — {适用场景，以及为何当前需求不优先选它}
-  spec    — {适用场景，以及为何当前需求不优先选它}
-  harness — {适用场景，以及为何当前需求不优先选它}
-  vibe    — {适用场景，以及为何当前需求不优先选它}
+#### Step 5：展示推荐与对比（Cursor 风格 + 行业框架名词）
 
-请选择要使用的模式：
-A. /modus:vibe    — 直接编码
-B. /modus:plan    — 功能规划  ← 推荐
-C. /modus:spec    — 规范驱动开发
-D. /modus:harness — 全自动 Harness
+```
+📊 需求路由分析 — {Story 标题}
+══════════════════════════════════════════════════════
+决策路径：[TAPD] → [评分] → {C=中,R=低,Cl=高,I=有} → [spec]
+
+维度评分：
+  复杂度 ████░░ 中等(2/3)  — {判定理由}
+  风险   ██░░░░ 低  (1/3)  — {判定理由}
+  明确度 ██████ 高  (3/3)  — {判定理由}
+  契约   ██████ 有  (1/1)  — {涉及接口}
+
+🎯 推荐：/modus:spec
+   理由：{2-3 句话说明推荐原因}
+
+📋 模式对比（行业框架对照）：
+  vibe    ✗ {不推荐原因}
+            类比：GitHub Copilot 内联补全 — 适合单文件、有把握的小改动
+  plan    △ {可用但非最优原因}
+            类比：Cursor Plan 模式 — 先只读扫描确认方案，再动手修改
+  spec    ✓ 推荐 — {推荐原因}
+            类比：OpenAPI Spec + BDD（Cucumber GIVEN/WHEN/THEN）
+  harness △ {可用但过重原因}
+            类比：GitHub Actions CI/CD — 多 SubAgent 串并行全托管
+
+请选择模式：
+  A. /modus:vibe    — 直接编码（快，类比 Copilot inline edit）
+  B. /modus:plan    — 先规划后执行（均衡，类比 Cursor Plan 模式）
+  C. /modus:spec    — 规范驱动开发  ← 推荐（类比 OpenAPI Spec + BDD）
+  D. /modus:harness — 全自动 Harness（重，类比 GitHub Actions pipeline）
+  
+  或输入 --force <mode> 强制指定
 ```
 
-⏸️ **等待用户选择**
+⏸️ **等待用户选择**（Codex 模式跳过此步）
 
-### Step 6：二次确认窗口
+#### Step 6：参数确认窗口
 
-用户选择模式后，展示参数确认窗口：
+用户选择后，展示参数确认（Swarm 风格）：
 
-**若选择 vibe：**
+**→ vibe：**
 ```
-确认参数：
-  任务描述: {从 Story 标题/描述提取的一句话任务描述}
-  涉及业务域: {自动判断的域列表}
+确认启动 /modus:vibe
+  任务描述: {从 Story 标题+描述生成的一句话任务}
+  业务域:   {domain} [draft]
+  上下文:   已加载 Story 摘要（{token数} tokens）
   
 直接开始编码？[Y/n]
 ```
 
-**若选择 plan：**
+**→ plan：**
+```
+确认启动 /modus:plan
+  Story 摘要: {标题 + 核心需求}
+  业务域:     {domain} [draft]
+  产物路径:   modus/stories/{id}/plan.md  ← v3.2 统一路由
+  快速模式（--quick，跳过设计文档）: [y/N]
+  
+确认？[Y/n]
 ```
-确认参数：
-  需求描述: {从 Story 内容生成的 plan prompt}
-  涉及域: {order, payment}
-  是否快速模式（跳过 design.md）: [y/N]
 
-确认后将启动 /modus:plan，输入以上描述。[Y/n]
+**→ spec：**
+```
+确认启动 /modus:spec
+  Story URL:  {原始 URL}
+  业务域:     {domain} [draft]
+  规格级别:   Full（因有接口契约变更）/ 可加 --lite 降级
+  产物路径:   modus/stories/{id}/spec/  ← v3.2 统一路由
+  验收标准:   已提取 {n} 条，将作为 Scenario 输入
+  
+确认？[Y/n]
 ```
 
-**若选择 spec：**
+**→ harness：**
+```
+确认启动 /modus:harness
+  Story URL:  {原始 URL}
+  产物路径:   modus/stories/{id}/harness/  ← v3.2 统一路由
+  跳过阶段:   无（如需跳过：--skip [agents]）
+  
+⚠️ Harness 将全自动执行多个 SubAgent，预计耗时较长。
+确认？[Y/n]
 ```
-确认参数：
-  需求描述: {从 Story 内容生成的 spec prompt}
-  涉及域: {order}
-  规格级别: Full（因为涉及接口契约变更）/ Lite（--lite flag）
 
-确认后将启动 /modus:spec，输入以上描述。[Y/n]
+⏸️ **等待用户确认**（带 `--no-confirm` 则跳过）
+
+#### Step 7：Context Bundle 透传 + 启动
+
+```yaml
+context_bundle:
+  story_id: "{id}"
+  story_title: "{title}"
+  story_desc: "{desc_summary}"
+  acceptance_criteria: ["{ac1}", "{ac2}"]
+  domains: ["{domain}"]
+  domain_skill_paths:                           # v3.2 路径（唯一权威）
+    - "modus/knowledge/{domain}/SKILL.md"
+  domain_skills_loaded: true
+  scores:
+    complexity: 2
+    risk: 1
+    clarity: 3
+    contract: 1
+  recommended_mode: "spec"
+  user_selected_mode: "spec"
+  skip_clarify: true
+  from_auto: true
+  platform: "cursor"                # cursor | codex | claude | codebuddy
 ```
 
-**若选择 harness：**
+启动各模式时的行为：
+- **vibe**：透传任务描述 + 业务域，跳过域识别步骤
+- **plan**：透传 Story 摘要 + 验收标准，跳过 Step 3 澄清阶段
+- **spec**：透传验收标准作为 Scenario 参考，跳过 TAPD 重读
+- **harness**：透传完整 URL，harness 内部自行处理（无需 bundle）
+
+---
+
+## 产物路径规范（v3.2）
+
+```
+有 --story [id]：
+  modus/stories/{id}/plan.md          # plan 产物
+  modus/stories/{id}/spec/            # spec 产物目录
+  modus/stories/{id}/harness/         # harness 产物目录
+
+无 --story（自动推断 feature 名）：
+  modus/local/{feature-name}/plan.md
+  modus/local/{feature-name}/spec/
 ```
-确认参数：
-  TAPD Story URL: {原始 URL}
-  将直接透传给 /modus:harness
 
-确认？[Y/n]
+> **v3.2 变更说明**：废弃 `modus/plans/active/{id}/`，统一使用 `modus/stories/{id}/`。
+
+---
+
+## 无 TAPD URL 时的处理
+
+若用户直接运行 `/modus:auto`（不带任何参数），提示：
+
 ```
+Modus Auto — 请提供需求来源：
+
+  方式 1：TAPD Story URL
+    /modus:auto https://tapd.cn/company/stories/view/1234567890
 
-⏸️ **等待用户确认**
+  方式 2：纯 Story ID
+    /modus:auto --story 1234567890
 
-### Step 7：启动所选模式
+  方式 3：自然语言描述
+    /modus:auto 新增批量导出接口，支持按条件筛选，返回 Excel
 
-用户确认后，根据选择自动触发对应模式：
+  方式 4：手动粘贴 Story 内容（离线）
+    /modus:auto --skip-tapd
 
-- **vibe**：以已整理的任务描述调用 `/modus:vibe`，上下文包含 Story 摘要
-- **plan**：以整理好的 prompt 调用 `/modus:plan`，在 prompt 末尾附加标记 `[AUTO_MODE: questions_confirmed]` 和答案摘要（格式见下），modus-plan Step 3 识别到此标记后跳过交互式澄清阶段：
-  ```
-  [AUTO_MODE: questions_confirmed]
-  已确认的关键信息：
-  - 业务域: {domain}
-  - 核心目标: {一句话目标}
-  - 技术约束: {列表，若用户在 Step 6 中补充了约束}
-  ```
-- **spec**：以整理好的 prompt 调用 `/modus:spec`，携带 Story 验收标准作为 Scenario 参考输入
-- **harness**：直接调用 `/modus:harness {tapd_url}`
+  不知道选哪个模式？直接输入需求，auto 帮你判断。
+  查看帮助：/modus:auto --help
+```
 
 ---
 
-## 四维评分快速参考卡
+## 快速参考卡
 
-| 模式 | 适用场景 | 不适合场景 |
-|------|----------|-----------|
-| `vibe` | 单文件改动、低风险 bug fix | 需要文档沉淀的功能 |
-| `plan` | 明确需求、中等复杂度、无接口契约变更 | 需要可测试规格、高风险 |
-| `spec` | 接口变更、高风险、需要 GIVEN/WHEN/THEN 验收 | 简单 bug fix、模糊需求 |
-| `harness` | 模糊需求、高复杂高风险、需要全自动流程 | 紧急小改动 |
+| 模式 | 行业框架对照 | 适用场景 | 不适合场景 |
+|------|------------|---------|-----------|
+| `vibe` | GitHub Copilot inline edit | 单文件、低风险 bug fix | 有接口契约变更 |
+| `plan` | Cursor Plan 模式（先只读规划） | 明确需求、中等复杂、无契约 | 高风险、需 GIVEN/WHEN/THEN |
+| `spec` | OpenAPI Spec + BDD（Cucumber） | 接口变更、高风险、需验收规格 | 简单 bug fix、模糊需求 |
+| `harness` | GitHub Actions CI/CD pipeline | 模糊需求、高复杂高风险、全自动 | 紧急小改动、已明确方案 |
+
+**快速决策口诀：**
+```
+改一个文件？→ vibe
+需求清楚但要规划？→ plan
+有接口变更或高风险？→ spec
+需求模糊或要全自动？→ harness
+```
 
 ---
 
-## 无 TAPD URL 时的处理
+## Codex 平台注意事项
 
-若用户直接运行 `/modus:auto`（不带 URL），提示：
+- **无交互等待**：所有 `⏸️ 等待用户` 步骤跳过，直接走推荐模式
+- **TAPD MCP 降级**：MCP 不可用时从自然语言描述提取信息，继续执行
+- **自然语言触发**：无需 `/modus:auto` 命令格式，识别「开始开发」「分析需求」等关键词自动触发
+- **--no-confirm 默认生效**：Codex 环境视同携带此参数
+- **文件系统降级**：文件系统不可用时跳过 Skill 加载，仅基于 Story 文本评分，Context Bundle 不写文件
+- **结构化日志**：`--output json` 时输出完整 JSON，便于在 Codex 日志中机器解析
+- **Context Bundle 路径**：使用 `modus/knowledge/biz-*/SKILL.md`（v3.2 唯一权威路径），不读旧路径
 
-```
-请提供 TAPD Story URL，例如：
-  /modus:auto https://tapd.cn/company/stories/view/1234567890
+---
 
-或粘贴 Story 内容（以 ---END--- 结束输入）：
-```
+## 下游命令优化建议（行业框架参照）
+
+> 本节为 plan/spec SKILL 的优化方向建议，供后续迭代参考。
+
+### /modus:plan 参照 Cursor Plan 模式的优化方向
+
+Cursor Plan 模式的核心理念：**先只读扫描确认方案，用户批准后再执行修改**，确保不产生意外改动。
+
+建议对 `modus-plan` SKILL 的增强：
+- 增加 `--pause-on-risk` 参数：检测到影响现有接口时暂停，等待人工确认再继续
+- `plan.md` 中增加「**修改影响范围**」章节：列出将被修改的文件 + 方法签名，类比 Cursor diff preview
+- 增加 `--read-only-check`：生成 plan 前先做只读扫描，确认涉及文件存在且格式符合预期
+- 增加 `--checkpoint` 参数：每完成一个 Sprint 产出物后暂停等待确认
+
+### /modus:spec 参照 OpenAPI Spec + BDD 的优化方向
+
+OpenAPI Specification 和 Cucumber BDD 的核心理念：**接口即契约，场景即测试，规格与实现双向绑定**。
 
-接受手动粘贴的 Story 内容，跳过 MCP 读取，直接进入 Step 3 分析。
+建议对 `modus-spec` SKILL 的增强：
+- delta spec 的 `### Requirement` 命名统一为 **operationId 风格**（动词+名词，如 `BatchExportItem`），对齐 OpenAPI `operationId` 规范
+- 增加 `--openapi-export` 参数：从 delta spec 自动生成 OpenAPI 3.0 YAML stub
+- 增加 `--gherkin-export` 参数：将 GIVEN/WHEN/THEN 导出为 Cucumber `.feature` 格式
+- 增加 `--schema-validate` 参数：对 delta spec 中定义的请求/响应结构做 JSON Schema 校验