@modus-ai/modus 0.2.5 → 0.2.7

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

@@ -126,11 +126,13 @@ 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
 
@@ -278,8 +280,17 @@ done | shasum -a 1 | awk '{print $1}'
 
 基于已加载的知识和用户确认的意图，生成单一规划文档到 `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）
+```
+
 - 如果目录已存在，提示用户确认
 
 **写入状态文件：**
@@ -433,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` 时会通过联网搜索验证最新规范。