@modus-ai/modus 0.2.4 → 0.2.6

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

@@ -1,6 +1,6 @@
 ---
 name: modus-plan
-description: Use this skill when executing /modus:plan command to generate a single structured plan.md backed by up-to-date business Skills. Trigger on /modus:plan command or when user wants to plan a feature with full business context. Loads Skill domains first, falls back to platform rules + source scan, then asks exactly 3 targeted questions before generating the plan. Ends with a Build confirmation loop where user can iterate on plan.md before executing code generation.
+description: Use this skill when executing /modus:plan command to generate a single structured plan.md backed by up-to-date business Skills. Trigger on /modus:plan command or when user wants to plan a feature with full business context. Loads Skill domains first, falls back to platform rules + source scan, then asks 0-3 targeted questions (no padding — only ask when truly needed) before generating the plan. Ends with a Build confirmation loop where user can iterate on plan.md before executing code generation.
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
@@ -11,7 +11,7 @@ disable: false
 
 ## 职责
 
-功能规划入口。通过**两层知识检索**获取业务上下文，先评估需求复杂度自动分级（simple/medium/complex），再基于加载的知识向用户提出恰好 3 个精准澄清问题，最终生成单一 `plan.md` 规划文档。文档生成后进入 Build 确认循环，用户可反复修改直至满意后触发代码执行，并将本次规划中的新知识回写到 Skill（后置更新）。
+功能规划入口。通过**两层知识检索**获取业务上下文，先评估需求复杂度自动分级（simple/medium/complex），再基于加载的知识向用户提出 0–3 个精准澄清问题（按需提问，禁止凑数），最终生成单一 `plan.md` 规划文档。文档生成后进入 Build 确认循环，用户可反复修改直至满意后触发代码执行，并将本次规划中的新知识回写到 Skill（后置更新）。
 
 ---
 
@@ -67,6 +67,15 @@ disable: false
 
 ### Step 3：复杂度评估与自动分级
 
+**AUTO_MODE 快速检测（Step 3 执行前）：**
+
+若 prompt 末尾包含 `[AUTO_MODE: questions_confirmed]` 标记（由 `/modus:auto` 自动注入），则：
+- 跳过 Step 6 的精准澄清问题（已在 auto 流程中确认，无需重复提问）
+- 直接使用标记后附带的「已确认的关键信息」作为澄清答案
+- 在输出中注明：`[已从 /modus:auto 继承确认信息，跳过澄清阶段]`
+
+若未包含此标记，正常执行以下评估流程：
+
 域确认后，快速评估需求复杂度并输出分级建议：
 
 **评估维度：**
@@ -117,21 +126,28 @@ disable: false
 
 #### 4-1：读取 Skill frontmatter（轻量操作，仅读前 20 行）
 
-读取 `.codebuddy/skills/modus-biz-{domain}/SKILL.md` 的 YAML frontmatter，提取：
+读取 `modus/knowledge/biz-{domain}/SKILL.md` 的 YAML frontmatter，提取：
 - `last_hash`：上次记录的 key_files 内容摘要
 - `key_files`：关键源文件列表
 
-若 Skill 不存在，跳到 4-4（新建）。
+若 Skill 不存在（包括 modus/knowledge/ 目录下不存在），跳到 4-4（新建）。
+
+> **注意**：`.codebuddy/skills/modus-biz-{domain}/SKILL.md` 自 v3.2 起已降级为引用桩，不含实际内容，请勿从此路径读取。
 
 #### 4-2：计算当前 key_files 的 hash
 
-使用 Bash 对 `key_files` 列出的文件内容做 SHA-1 摘要：
+使用 Bash 对 `key_files` 列出的文件内容做 SHA-1 摘要（**必须使用 modus-init 区块 B 规定的标准算法**）：
 
 ```bash
-# 对每个文件计算 sha1，排序后再做一次 sha1（顺序无关）
-shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
+# 标准全局 hash 计算命令（与 modus-init 生成时的算法完全一致）
+# 对每个文件单独计算 SHA-1，按文件路径排序后拼接，再整体 hash
+for f in $(echo "{key_files}" | tr ' ' '\n' | sort); do
+  echo "$(shasum -a 1 "$f" | awk '{print $1}'):$f"
+done | shasum -a 1 | awk '{print $1}'
 ```
 
+> 注意：禁止使用「内容拼接整体 hash」或「仅 hash 值排序 hash」的替代算法，否则与 init 写入的 last_hash 不匹配，导致每次都误判为 stale。
+
 - 若某个 `key_files` 中的文件不存在（可能已被重命名/删除），视为「已变化」，强制更新
 - 若 `key_files` 为空或缺失，视为「已变化」，强制更新
 
@@ -170,15 +186,28 @@ shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{
   maturity: draft → verified（本次引用后满足晋升条件）
 ```
 
-若有未初始化的域，调用模式 A 新建 Skill（`last_hash` 留空，`key_files` 由 AI 填写）。
+若有未初始化的域，调用模式 A 新建 Skill（`last_hash` 留空，`key_files` 由 AI 填写）；新建完成后将新域纳入本次可用 Skill 集合，继续执行。
 
-**若所有域均已初始化且 Skill 加载成功，直接进入 Step 6，跳过 Step 5。**
+**Step 4 执行完后的分支判断：**
+
+```
+情形 A：所有域均已初始化（含本轮新建）且 Skill 全部加载成功
+  → 直接进入 Step 6，跳过 Step 5
+
+情形 B：knowledge-catalog.md 不存在
+  → 进入 Step 5（平台知识兜底扫描）
+
+情形 C：部分域已初始化、部分域未初始化（混合状态）
+  → 对未初始化的域调用模式 A 新建后，加入到当前 Skill 集合
+  → 新建失败（如目录为空，无代码可扫描）时，对该域仅输出警告，继续处理已有域
+  → 完成处理后进入 Step 6（不触发 Step 5，已有 catalog 作为索引）
+```
 
 ---
 
 ### Step 5：平台知识兜底扫描（仅在 Step 4 无命中时执行）
 
-当 `knowledge-catalog.md` 不存在，或当前需求涉及的域全部未初始化时，切换到平台知识扫描模式：
+当 `knowledge-catalog.md` **不存在**时，切换到平台知识扫描模式作为兜底。注意：若 catalog 存在但部分域未初始化，属于情形 C，由 Step 4 内处理，不触发 Step 5：
 
 **按已启用平台依次扫描规则文件：**
 
@@ -203,26 +232,35 @@ shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{
 
 ---
 
-### Step 6：精准 3 问（AskUserQuestion）
+### Step 6：精准澄清问（AskUserQuestion）
+
+基于 Step 4 或 Step 5 已加载的知识内容，向用户提出**必要的**澄清问题。
 
-基于 Step 4 或 Step 5 已加载的知识内容，向用户提出**恰好 3 个**澄清问题。
+**核心原则：只问真正有歧义或有高风险的点。需求足够清晰时可以只问 1 个（甚至 0 个），不要为了凑数制造问题。上限 3 个，超过 3 个未澄清点说明需求本身需要重新定义。**
 
-**生成规则（按优先级排序，必须输出恰好 3 个）：**
+**必须提问的条件（满足任一即问）：**
 
-1. **P1 — Skill pitfall 关联问题**（最高优先级）  
-   若加载内容中有与当前需求相关的 `[pitfall]`，必问。  
+1. **P1 — Skill pitfall 关联问题**（命中即必问，不可省略）  
+   若加载内容中有与当前需求相关的 `[pitfall]`，必须确认用户是否已知晓并有对策。  
    示例：`Skill 中记录了「并发创建订单需加分布式锁」的坑，本次改动是否涉及并发写入场景？`  
-   若有多个相关 pitfall，选取与本次需求匹配度最高的 1 个。
+   若有多个相关 pitfall，选取与本次需求匹配度最高的 1 个提问。
 
-2. **P2 — 范围/边界问题**  
-   影响规划深度的不确定点（跨域边界、兼容性要求、数据量级）。  
-   示例：`这次改动是否需要向后兼容旧的导出格式，还是可以直接替换？`
+2. **P2 — 影响规划深度的不确定点**（有真实歧义才问）  
+   存在跨域边界不明确、兼容性要求未说明、数据量级未知等会影响技术选型的不确定点。  
+   示例：`这次改动是否需要向后兼容旧的导出格式？`  
+   **若需求描述已足够清晰（单域、单功能、无歧义词），跳过此条。**
 
-3. **P3 — 优先级/约束问题**  
-   时间窗口、技术选型偏好、外部依赖。  
-   示例：`功能是否有明确的上线时间节点？这会影响 Sprint 拆分方式。`
+3. **P3 — 影响 Sprint 拆分的外部约束**（有明确上线压力才问）  
+   功能有明确时间节点、或涉及外部系统联调依赖时才问。  
+   示例：`功能是否有明确的上线时间节点？`  
+   **若用户未提及时间约束且复杂度为 simple，跳过此条。**
 
-**若 pitfall 不存在**，P1 改为「核心目标澄清」：本次改动的最高优先级目标是什么？
+**若上述三条均无命中 → 直接跳过提问，输出：**
+```
+需求清晰，无需额外确认。开始生成 plan.md。
+```
+
+> **设计理由（Karpathy Think Before Coding）：** "恰好 3 个问题"是一种伪精确——它让 Agent 在只有 1 个真实歧义时制造 2 个无意义问题，或在需求清晰时也强制打断用户。真正的 Think Before Coding 是：发现真实的歧义才问，没有歧义就直接开工。
 
 等待用户回答后，输出意图确认摘要：
 
@@ -242,8 +280,17 @@ shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{
 
 基于已加载的知识和用户确认的意图，生成单一规划文档到 `modus/plans/{name}/plan.md`。
 
-**确定 plan 名称：**
-- 从用户 prompt 提取关键词，生成 kebab-case 名称（如 `add-batch-approve`）
+**确定产出路径（Story 模式 vs 独立模式）：**
+
+```
+情形 A：来自 /modus:auto（context_bundle 含 story_id）
+  产出路径：modus/stories/{story-id}/plan.md
+  
+情形 B：用户直接运行 /modus:plan（无 story_id）
+  产出路径：modus/plans/{name}/plan.md
+  plan 名称：从用户 prompt 提取关键词，生成 kebab-case（如 add-batch-approve）
+```
+
 - 如果目录已存在，提示用户确认
 
 **写入状态文件：**
@@ -321,15 +368,35 @@ plan.md 生成后，展示结果并进入确认循环：
 
 **循环逻辑：**
 - 用户提出修改意见 → 更新 `plan.md` → 重新输出上述确认提示（循环，无次数限制）
-- 用户回复「Build」/「开始」/「执行」→ 退出循环，以 `plan.md` 中的 Todos 为输入，启动 `/modus:vibe` 执行代码生成
+- 用户回复「Build」/「开始」/「执行」→ 退出循环，按下方「Build 触发后」的规定启动 `/modus:vibe`
 - 用户回复「归档」/「稍后」→ 走归档流程，不启动代码生成
 
 **Build 触发后：**
-```
-🚀 开始执行 plan.md 中的 Todos，启动 /modus:vibe...
-   读取: modus/plans/{name}/plan.md
-   执行范围: {Todos 列表}
-```
+
+以下是 modus-plan → modus-vibe 的**标准上下文传递协议**：
+
+1. 输出 Build 启动提示（让用户感知上下文已传递）：
+   ```
+   🚀 开始执行 plan.md 中的 Todos，启动 /modus:vibe...
+      规划文件: modus/plans/{name}/plan.md
+      执行范围: {Todos 列表}
+      传递标记: [FROM_PLAN: modus/plans/{name}/plan.md]
+   ```
+
+2. 以如下格式构造 vibe 的输入 prompt（在 **当前上下文中**直接继续执行，不需要用户重新输入命令）：
+   ```
+   按照 [FROM_PLAN: modus/plans/{name}/plan.md] 中的 Todos 逐项实现：
+
+   {plan.md 中「实现 Todos」章节的完整内容}
+
+   已加载的业务上下文：{Step 4 已加载的 Skill 域列表}
+   项目硬性约束：{constitution.hard_rules}
+   ```
+
+3. modus-vibe Step 0 检测到 `[FROM_PLAN:...]` 标记时：
+   - 自动读取指定 plan.md 文件作为任务上下文（跳过用户 prompt 解析阶段）
+   - 将 plan.md 的「已知风险」章节注入 Step 6 Design Brief 的「禁止事项」
+   - 将 plan.md 的「关键约束」章节作为 constitution 补充（低于 constitution.hard_rules 优先级）
 
 **归档流程（用户选择归档时）：**
 1. 将目录移动到 `modus/plans/archive/{YYYY-MM-DD}-{name}/`
@@ -338,24 +405,34 @@ plan.md 生成后，展示结果并进入确认循环：
 
 ---
 
-### Step 9：后置 Skill 更新（知识回写）
+### Step 9：后置 Skill 更新（知识回写，用户确认后执行）
 
-无论用户选择 Build 还是归档，规划阶段完成后即执行后置知识回写（模式 C）：
+规划阶段完成后，先扫描 `plan.md` 中可能值得沉淀的新知识，向用户展示并**请求确认**后再写回：
 
-1. 从 `plan.md` 的「方案选项对比」中提取技术决策：
-   - 每个有选型依据的决策 → `[decision]` 写入 `modus-tech-wiki`（跨项目）或对应业务 Skill（域特有）
-2. 从「已知风险」章节中提取**本次新发现的**风险（非来自现有 Skill 的已有记录）：
-   - 新发现的风险 → `[pitfall]` 追加到对应业务 Skill
-3. 从「实现 Todos」中提取具体的编码模式或约束 → `[guideline]`
-4. 更新 `modus/knowledge-catalog.md` 的 `last_referenced` 和 maturity
-5. 输出更新摘要：
-   ```
-   📚 知识已回写到 Skill：
-   - [decision] tech-wiki：批量审批走 MQ 异步
-   - [guideline] order 域：批量操作上限 50 条，防止内存溢出
-   - [pitfall] order 域：MQ 消费者需保证幂等性
-   maturity 变化: modus-biz-order draft→verified
-   ```
+**扫描内容：**
+1. 从「方案选项对比」提取技术决策 → 候选 `[decision]`
+2. 从「已知风险」提取**本次新发现的**风险（非来自现有 Skill 的已有记录）→ 候选 `[pitfall]`
+3. 从「实现 Todos」提取具体编码约束 → 候选 `[guideline]`
+
+**若发现可沉淀内容，向用户展示并确认：**
+```
+📚 发现 {N} 条可沉淀到 Skill 的新知识，是否写入？[Y/n]
+  · [decision] tech-wiki：批量审批走 MQ 异步（来自方案对比）
+  · [pitfall] order 域：MQ 消费者需保证幂等性（本次新发现）
+  · [guideline] order 域：批量操作上限 50 条（来自 Todos 约束）
+跳过不影响本次规划，可在下次 /modus:init 时统一归档。
+```
+
+**用户确认后**执行写回（模式 C），输出摘要。  
+**用户跳过**则仅更新 `knowledge-catalog.md` 的 `last_referenced`（不修改 Skill 内容）。
+
+**若无可沉淀内容 → 静默跳过，仅更新 `last_referenced`。**
+
+**`usage_count` 更新时机（plan 模式）：**
+
+用户在 Build 确认循环中回复「Build/开始/执行」后（即 Step 8 Build 触发时），对本次 plan 涉及的每个业务域执行 `usage_count += 1`，并同步更新对应 Skill 的 frontmatter。此操作在 Step 8 Build 触发内执行，不依赖后续 vibe session 的完成。
+
+> **设计理由（Karpathy Surgical Changes）：** 用户请求的是"生成规划文档"，不是"更新 Skill 文件"。自动写回会在用户不知情的情况下修改多个知识文件，违反"Touch only what you must"。用户确认机制既保留了知识闭环能力，又把文件修改的控制权还给用户。
 
 ---
 
@@ -367,7 +444,7 @@ plan.md 生成后，展示结果并进入确认循环：
 
 1. 读取 `modus/config.yaml` 的 `platforms` 字段
 2. 对受影响的每个业务域（Step 4 前置更新 / 新建的域），按以下规则同步：
-   - **CodeBuddy** → 源文件即 `.codebuddy/skills/modus-biz-{domain}/SKILL.md`（已更新，无需额外操作）
+   - **CodeBuddy** → 同步更新 `.codebuddy/skills/modus-biz-{domain}/SKILL.md` 引用桩的摘要行（权威源已在 `modus/knowledge/biz-{domain}/SKILL.md` 中更新）
    - **Claude** → 写入 `.claude/agents/modus-biz-{domain}.md`（覆盖旧版本）
    - **Cursor** → 写入 `.cursor/rules/modus-biz-{domain}.mdc`（带 frontmatter，覆盖旧版本）
    - **Copilot** → 在 `.github/copilot-instructions.md` 中替换对应域的标记段落

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

@@ -0,0 +1,271 @@
+---
+name: modus-platform
+description: >
+  Use this skill when executing /modus:platform command for AI platform adapter management.
+  Supports adding new platform adapters via online research (-add), listing registered platforms (-list),
+  and removing platform adapters (-remove). When adding a platform, the AI researches the target
+  platform's rules/commands/skills loading mechanism online and generates a platform.yaml descriptor,
+  which the modus CLI then uses to generate adapter files. This is how Cursor, Claude, CodeBuddy
+  support was originally built — each platform was analyzed and formalized into a generator.
+  Trigger on: /modus:platform, add platform adapter, 添加平台适配, 新增平台, platform -add,
+  platform -list, platform -remove, 注册新平台, 扩展平台支持, 适配新 AI 工具.
+allowed-tools: Read, Write, Glob, Bash, WebSearch, WebFetch
+disable: false
+---
+
+# modus-platform（AI 平台适配管理）
+
+**触发条件：** 用户运行 `/modus:platform [-add|-list|-remove]` 时使用此 Skill。
+
+---
+
+## 职责
+
+管理 Modus 对 AI 编码工具平台的适配。每个平台用一个 `platform.yaml` 描述符注册，
+`modus update` 时自动生成对应的 framework 适配文件，`/modus:init` 时自动同步业务域 biz skill。
+
+**已内置平台**（无需 `-add`）：
+
+| 平台 | 生成器 | 输出位置 |
+|------|--------|---------|
+| codebuddy | codebuddy.ts | `.codebuddy/` |
+| claude | claude.ts | `.claude/` + `CLAUDE.md` |
+| cursor | cursor.ts | `.cursor/rules/` |
+| copilot | copilot.ts | `.github/copilot-instructions.md` |
+| codex | codex.ts | `AGENTS.md` |
+
+**自定义平台**（通过 `-add` 添加）：由 `modus/platforms/{name}/platform.yaml` + `custom.ts` 通用生成器驱动。
+
+---
+
+## 参数说明
+
+```
+/modus:platform -add <platform-name> [--docs <url>] [--force]
+/modus:platform -list
+/modus:platform -remove <platform-name>
+
+  -add <name>      添加新平台适配（联网搜索平台规则，生成 platform.yaml）
+  -list            列出所有已注册平台（内置 + 自定义）
+  -remove <name>   移除自定义平台（删除 platform.yaml 及生成的适配文件）
+  --docs <url>     提供平台官方文档 URL，优先从此处提取信息
+  --force          强制覆盖已存在的 platform.yaml
+```
+
+---
+
+## 执行流程
+
+### 参数解析（优先执行）
+
+```
+-list    → 跳到「-list 流程」
+-remove  → 跳到「-remove 流程」
+-add     → 执行「-add 流程」（主流程）
+无参数   → 输出帮助信息，列出已注册平台
+```
+
+---
+
+## -add 流程：添加新平台适配
+
+### Step 1：前置检查
+
+```
+① 检查 modus/platforms/{name}/platform.yaml 是否已存在
+   → 若存在且未传 --force：提示已注册，建议 -remove 后重新添加或加 --force
+   → 若存在且 --force：继续（将覆盖）
+
+② 检查是否为已内置平台（codebuddy/claude/cursor/copilot/codex）
+   → 若是：提示「该平台已内置支持，无需 -add」，结束执行
+```
+
+### Step 2：联网研究平台规范（核心步骤）
+
+> **这一步对标当时分析 Cursor 平台的过程**——Agent 自主搜集信息，而非用户手动填写。
+
+优先读取 `--docs <url>`（若提供），否则联网搜索：
+
+```
+搜索词（按优先级）：
+  1. "{platform-name} AI coding rules directory"
+  2. "{platform-name} slash commands configuration"
+  3. "{platform-name} context files agent instructions"
+  4. "{platform-name} SKILL.md OR rules.md OR instructions.md"
+```
+
+**需要回答的平台能力问题清单：**
+
+```
+□ Q1: 上下文规则如何加载？
+  → 专用目录（如 .cursor/rules/）？单文件（如 AGENTS.md）？系统提示注入？
+  → outputDir 和 fileExtension
+
+□ Q2: 是否支持多文件 Skill 分散加载？
+  → 渐进式（progressive）/ 全量合并（flat）/ 不支持（none）
+  → capabilities.skillsLoading
+
+□ Q3: 命令如何触发？
+  → /slash 命令？自然语言关键词？配置文件定义？
+  → capabilities.commandsTrigger
+
+□ Q4: 是否有原生多文件规则机制（类似 .cursor/rules/）？
+  → capabilities.nativeRules
+
+□ Q5: 是否支持 Sub-Agent / 并行 Task？
+  → capabilities.subAgents
+
+□ Q6: 业务域 biz skill 应该放在哪里？
+  → bizSkill.outputPath 模板（含 {domain} 占位符）
+  → bizSkill.wrapper（文件头部格式）
+```
+
+**输出分析摘要：**
+
+```
+=== 平台分析：{platform-name} ===
+上下文加载：{结论}
+多文件规则：{支持/不支持}
+命令触发：{slash/natural/file}
+Sub-Agent：{是/否}
+信息来源：{URL 或「搜索推断」}
+置信度：{高/中/低}
+```
+
+### Step 3：生成 platform.yaml
+
+在 `modus/platforms/{name}/platform.yaml` 写入：
+
+```yaml
+# {label} — Modus 平台适配描述符
+# 由 /modus:platform -add 自动生成，可手动调整后运行 modus update 重新生成适配文件
+name: {name}
+label: {label}
+outputDir: {outputDir}
+fileExtension: {fileExtension}
+capabilities:
+  skillsLoading: {progressive|flat|none}
+  subAgents: {true|false}
+  commandsTrigger: {slash|natural|file}
+  nativeRules: {true|false}
+bizSkill:
+  enabled: {true|false}
+  outputPath: "{outputDir}/modus-biz-{domain}.{fileExtension}"
+  wrapper: |
+    # {domain} Business Domain Rules
+    <!-- Source: modus/knowledge/biz-{domain}/SKILL.md -->
+    {content}
+constitutionTemplate: |
+  # Modus Project Rules — {label}
+  {hardRules}
+commandsTemplate: |
+  # Modus Commands — {label}
+  {commands}
+```
+
+### Step 4：更新 modus/config.yaml
+
+在 `customPlatforms` 字段追加平台名（幂等）：
+
+```yaml
+customPlatforms:
+  - {name}
+```
+
+### Step 5：生成 framework 适配文件
+
+提示用户运行 `modus update` 触发 `custom.ts` 生成器，或直接调用（若有权限）：
+
+```
+→ 在 {outputDir}/ 生成：
+  modus-constitution.{ext}    — 项目宪法（hard_rules）
+  modus-commands.{ext}        — 命令索引
+  modus-init.{ext}            — init Skill（若 skillsLoading != none）
+  modus-vibe.{ext}            — vibe Skill
+  modus-plan.{ext}            — plan Skill
+  modus-spec.{ext}            — spec Skill
+  modus-auto.{ext}            — auto Skill
+  modus-harness.{ext}         — harness Skill
+```
+
+### Step 6：验收报告
+
+```
+✅ 平台适配完成：{label}
+
+已生成文件：
+  modus/platforms/{name}/platform.yaml  ← 描述符（可手动调整）
+  {outputDir}/modus-constitution.{ext}
+  {outputDir}/modus-commands.{ext}
+  ... （共 N 个文件）
+
+后续 biz skill 同步：
+  每次运行 /modus:init 时，modus-biz-* 内容会自动同步到：
+  {bizSkill.outputPath}
+
+验证方式：
+  1. 在 {platform-name} 中打开本项目
+  2. 输入 /modus:vibe 或相应触发词
+  3. 确认 AI 能识别业务域知识
+
+已知限制：
+  {根据 capabilities 分析，列出与内置平台的差异，如「不支持 Sub-Agent，harness 降级单步执行」}
+```
+
+---
+
+## -list 流程：列出已注册平台
+
+```
+=== 已注册平台 ===
+
+内置平台：
+  ✓ codebuddy  (.codebuddy/)
+  ✓ claude     (.claude/ + CLAUDE.md)
+  ✓ cursor     (.cursor/rules/)
+  ✓ copilot    (.github/copilot-instructions.md)
+  ✓ codex      (AGENTS.md)
+
+自定义平台（modus/platforms/*/platform.yaml）：
+  ✓ windsurf   (.windsurf/rules/)    [2026-05-18]
+  ✓ aider      (.aider/)             [2026-05-10]
+
+当前启用（modus/config.yaml platforms 字段）：
+  codebuddy, claude, cursor, codex, windsurf
+```
+
+若无自定义平台：
+```
+暂无自定义平台。使用 /modus:platform -add <name> 添加。
+```
+
+---
+
+## -remove 流程：移除自定义平台
+
+```
+Step 1: 确认 modus/platforms/{name}/platform.yaml 存在
+Step 2: 读取 outputDir 配置，确认生成文件列表
+Step 3: 展示将被删除的文件（预览）
+Step 4: 用户确认（--force 时跳过）
+Step 5: 删除 modus/platforms/{name}/ 目录
+Step 6: 删除 {outputDir}/modus-*.{ext} 文件（仅删 modus 生成的，不影响用户文件）
+Step 7: 从 modus/config.yaml customPlatforms 移除该平台名
+Step 8: 输出完成报告
+```
+
+---
+
+## 已知平台特性参考（内置知识）
+
+| 平台 | rules 目录 | Skill 加载 | 命令触发 | Sub-Agent |
+|------|-----------|-----------|---------|-----------|
+| Cursor | `.cursor/rules/` (.mdc) | progressive | /slash | 否（单 Agent） |
+| Claude Code | `.claude/` | flat (agents) | /slash | 是 |
+| CodeBuddy | `.codebuddy/skills/` | progressive | /slash | 是 |
+| GitHub Copilot | `.github/copilot-instructions.md` | flat (单文件) | 自然语言 | 否 |
+| Codex / OpenCode | `AGENTS.md` | flat (单文件) | 自然语言 | 否 |
+| Windsurf (Cascade) | `.windsurfrules` | flat (单文件) | /slash | 否 |
+| Aider | `.aider.conf.yml` | flat (配置) | CLI flags | 否 |
+
+> 上表为已知信息，`-add` 时会通过联网搜索验证最新规范。