@modus-ai/modus 0.1.0

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

@@ -0,0 +1,255 @@
+# modus-spec（OpenSpec 规范驱动开发）
+
+**触发条件：** 用户运行 `/modus:spec [需求描述]` 时使用此 Skill。
+
+## 职责
+
+规范驱动开发入口。在 `/modus:plan` 的基础上增加 OpenSpec 风格的行为规格（delta specs），明确「系统的 WHAT」而非「HOW」。通过**三级渐进加载**获取业务上下文，产出物包含 proposal、delta specs、design、tasks，归档后将 delta specs 合并到主规格库，并从中提取带类型标签的知识回写到 Skill。
+
+---
+
+## 执行流程
+
+### Step 0：读取项目宪法 + 断点续跑检查
+
+**读取 constitution：**
+读取 `modus/config.yaml` 的 `constitution` 字段，作为 Spec 编写的最高优先级约束。`hard_rules` 中的规则必须体现在 Scenario 的 THEN 断言中。
+
+**断点续跑检查：**
+扫描 `modus/changes/` 目录，检查是否存在同名的 `.modus-state.yaml`：
+- 若存在且 `status: in-progress`，提示用户恢复或重新开始
+- 若用户选择继续，跳到对应未完成步骤
+
+### Step 1：Level 1 加载——读知识目录（~200 tokens）
+
+读取 `modus/knowledge-catalog.md`，了解当前可用 Skill 及状态。
+若不存在，与 vibe/plan 模式相同的降级提示。
+
+### Step 2：域匹配与确认（有则更新，无则新增）
+
+基于 catalog 目录信息，结合用户 prompt，判断涉及的业务域：
+
+```
+根据你的需求，我认为涉及以下业务域：
+
+✓ order（订单域）    [verified] → 将在前置步骤中更新
+✓ payment（支付域）  [proven]  → 将在前置步骤中更新
+? export（导出域）   [未初始化] → 将在前置步骤中新建
+
+确认？
+```
+
+### Step 3：澄清用户意图（AskUserQuestion）
+
+确认域后，在规范编写前，提出 1-3 个关键澄清问题。
+
+**Spec 模式特别关注的澄清方向：**
+
+```
+为了写出准确的行为规格，我需要确认：
+
+1. [行为边界] {具体业务场景的边界情况}，系统应该怎么处理？
+   （直接影响 GIVEN/WHEN/THEN 场景的编写）
+
+2. [MODIFIED vs ADDED] 这是修改 {已有需求名称} 的行为，
+   还是新增一个独立的需求？（影响 delta spec 使用 MODIFIED 还是 ADDED）
+
+3. [REMOVED 确认] 原有的 {已有功能} 是否明确废弃，
+   还是保留并共存？
+
+4. [验收标准] 你期望的测试 Scenario 中，有哪些边界情况必须覆盖？
+
+5. [已知风险] ⚠️ Skill 中记录了：{pitfall}，Spec 中是否需要为此添加保护性场景？
+```
+
+等待用户回答后，输出意图摘要：
+
+```
+理解已确认：
+- 核心行为变更: {ADDED/MODIFIED/REMOVED 各几条}
+- 关键 Scenario: {用户明确提及的测试场景}
+- 废弃内容: {若有}
+- 项目约束: {来自 constitution 的关键规则}
+
+开始前置更新 Skill，然后生成规范文档。
+```
+
+### Step 4：前置 Skill 更新（Level 2 加载，同 /modus:plan Step 4）
+
+调用 `modus-harness-00-skills-builder` 模式 B，读取并更新相关 Skill。
+
+### Step 5：生成规范文档
+
+基于已澄清的意图，生成文档到 `modus/changes/{name}/`。
+
+**写入状态文件：**
+创建 `modus/changes/{name}/.modus-state.yaml`：
+```yaml
+mode: spec
+name: {name}
+status: in-progress
+domains: [{domain1}]
+delta_stats:
+  added: 0
+  modified: 0
+  removed: 0
+tasks_completed: "0/?"
+scenarios_covered: "0/?"
+completed: []
+pending: [proposal, specs, design, tasks]
+created: {ISO8601时间戳}
+```
+
+**产出物依赖：**
+
+```
+proposal.md
+    │
+    ├──► specs/{domain}/spec.md  (delta specs)
+    │
+    └──► design.md
+              │
+              ▼
+           tasks.md
+```
+
+**1. proposal.md** — 意图与范围（同 /plan）
+
+**2. specs/{domain}/spec.md** — Delta 规格（核心差异）
+
+使用 ADDED/MODIFIED/REMOVED 三段式描述行为变更：
+
+```markdown
+# Delta: {域名} — {功能名称}
+
+## ADDED Requirements（新增行为）
+
+### Requirement: {需求名称}
+系统 SHALL {可观测的行为描述，不涉及实现细节}。
+
+#### Scenario: Happy Path — {场景名称}
+- GIVEN {前置条件}
+- WHEN {触发动作}
+- THEN {预期结果}
+- AND {附加结果}
+
+#### Scenario: 边界条件 — {上限/下限场景}
+- GIVEN {处于边界的前置条件}
+- WHEN {触发动作}
+- THEN {边界行为}
+
+#### Scenario: 异常场景 — {错误处理}
+- GIVEN {前置条件}
+- WHEN {错误触发}
+- THEN 系统 SHALL 返回 {错误码} 和明确的错误提示
+
+## MODIFIED Requirements（修改行为）
+
+### Requirement: {已有需求名称}
+{新的完整描述}
+（原描述：{原来的描述}）
+
+## REMOVED Requirements（废弃行为）
+
+### Requirement: {已废弃需求}
+（废弃原因：{原因}）
+```
+
+生成 delta specs 后更新 `.modus-state.yaml` 的 `delta_stats`。
+
+**3. design.md** — 技术方案（同 /plan）
+
+**4. tasks.md** — 实现清单（含场景驱动的规格验证章节）
+
+在 tasks.md 末尾加入**场景驱动的验证章节**——每个 TODO 项直接追踪到 delta spec 中对应的 Scenario：
+
+```markdown
+## N. 规格验证（场景驱动）
+# 每一项对应 delta spec 中的一个 Scenario，确保代码与规格一致
+
+- [ ] N.1 [Happy Path] {Scenario名称} 有对应单元测试（GIVEN: X, WHEN: Y, THEN: Z）
+- [ ] N.2 [边界条件] {上限=50} 的边界场景有单元测试，超出时返回 {错误码}
+- [ ] N.3 [异常场景] {失败回滚} 场景有集成测试，验证事务完整性
+- [ ] N.4 [接口一致性] {POST /api/v1/{domain}/xxx} 接口行为与 Scenario 一致（通过 API 测试验证）
+- [ ] N.5 [宪法约束] {constitution.hard_rules 中与本次相关的规则} 在代码中得到体现
+```
+
+生成每份文档后更新 `.modus-state.yaml` 的 `completed` 列表和 `scenarios_covered`。
+
+### Step 6：询问归档 ⏸️ 【人工审批节点】
+
+```
+规范文档已生成：
+  modus/changes/{name}/proposal.md
+  modus/changes/{name}/specs/{domain}/spec.md  ← delta specs（{N}个场景）
+  modus/changes/{name}/design.md
+  modus/changes/{name}/tasks.md
+  modus/changes/{name}/.modus-state.yaml
+
+是否归档？归档后：
+  1. delta specs 将合并到 modus/specs/{domain}/spec.md（主规格库）
+  2. 变更文件夹移动到 modus/changes/archive/{YYYY-MM-DD}-{name}/
+```
+
+⏸️ **等待人工确认**（支持异步：可以在任意时间回复）
+
+**归档时的 delta 合并规则：**
+- `## ADDED Requirements` → 追加到主 spec 对应章节末尾
+- `## MODIFIED Requirements` → 替换主 spec 中对应的 Requirement
+- `## REMOVED Requirements` → 从主 spec 中删除对应 Requirement
+
+如果主 spec 不存在，创建新文件并填入所有 ADDED 内容。
+
+归档完成后更新 `.modus-state.yaml`：`status: archived`。
+
+### Step 7：后置 Skill 更新（知识提取与回写）
+
+归档完成后，调用 `modus-harness-00-skills-builder` 模式 C，从 delta specs 中系统性提取知识：
+
+1. `## ADDED Requirements` 中的新业务流程 → `[process]` 追加到业务 Skill
+2. 新增实体/字段/枚举 → `[model]` 追加到业务 Skill
+3. 新约束规则（SHALL/SHALL NOT 描述） → `[guideline]` 追加到业务 Skill
+4. Scenario 中暴露的边界条件/失败模式 → `[pitfall]` 追加到业务 Skill
+5. 更新 `modus/knowledge-catalog.md` 的 `last_referenced`
+
+输出知识提取摘要：
+```
+📚 知识已提取并回写到 Skill：
+- [process] order 域：新增批量审批流程（提交→校验→执行→通知）
+- [guideline] order 域：批量操作上限 50 条（来自 Scenario: 边界条件）
+- [pitfall] order 域：全批失败回滚逻辑需配合 @Transactional + 分布式锁
+- knowledge-catalog.md 已更新（order 域 maturity: draft→verified）
+```
+
+---
+
+## 主规格库结构
+
+```
+modus/
+├── specs/                        ← 当前系统行为的真相来源
+│   ├── order/spec.md
+│   └── payment/spec.md
+├── changes/                      ← 进行中的变更
+│   └── add-batch-approve/
+│       ├── .modus-state.yaml     ← 状态文件（断点续跑）
+│       ├── proposal.md
+│       ├── specs/order/spec.md   ← delta specs
+│       ├── design.md
+│       └── tasks.md
+└── changes/archive/
+    └── 2026-04-20-add-batch-approve/
+        ├── .modus-state.yaml     ← status: archived
+        └── ...
+```
+
+---
+
+## Spec 质量原则
+
+- Spec 描述「什么」，design 描述「怎么做」
+- 每个 Scenario 必须可测试（可直接写成自动化测试）
+- 使用 SHALL（必须）、SHOULD（应该）、MAY（可以）
+- 避免在 spec 中出现类名、方法名、框架名
+- tasks.md 的规格验证章节**必须与 Scenario 一一对应**，不得遗漏
+- constitution 的 hard_rules 必须在 Scenario 中得到体现

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

@@ -0,0 +1,150 @@
+# modus-vibe（氛围编程）
+
+**触发条件：** 用户运行 `/modus:vibe [描述]` 时使用此 Skill。
+
+支持快速模式：`/modus:vibe --quick [描述]` 跳过 Skill 预更新和域确认，适合简单的单文件改动。
+
+## 职责
+
+氛围编程入口。在编码前先通过**三级渐进加载**获取相关业务上下文，让 AI 以「懂业务的资深开发者」身份工作，而不是从零开始理解项目。
+
+---
+
+## 执行流程
+
+### Step 0：读取项目宪法（硬性约束）
+
+读取 `modus/config.yaml`（若存在），提取 `constitution` 字段：
+
+```yaml
+constitution:
+  tech_stack: "..."
+  hard_rules: [...]
+  key_patterns: [...]
+```
+
+将 `hard_rules` 作为**最高优先级约束**，在整个编码过程中强制遵守，不因业务需要而妥协。
+
+若文件不存在或 `constitution` 为空，跳过此步。
+
+### Step 1：Level 1 加载——读知识目录（~200 tokens）
+
+读取 `modus/knowledge-catalog.md`（全景目录索引）：
+- 了解当前项目有哪些可用的 Skill
+- 识别各 Skill 的 maturity 状态
+- 为 Step 2 的域匹配做准备
+
+**如果 `knowledge-catalog.md` 不存在：**
+
+```
+⚠️ 未找到知识目录（modus/knowledge-catalog.md）
+
+建议先运行 /modus:init 初始化知识库，可以让 AI 更准确地理解项目。
+
+是否：
+A. 现在运行快速初始化（约 2-5 分钟）？
+B. 继续使用降级模式（无业务上下文，结果质量可能降低）？
+```
+
+- 选 A → 执行 `/modus:init` 流程，完成后继续
+- 选 B → 跳过知识加载，直接进入编码
+
+### Step 2：快速模式判断
+
+**如果用户使用 `--quick` 标志：**
+- 跳过 Step 3（域识别与确认）和 Step 4（Level 2 加载）
+- 直接进入 Step 5（澄清意图）
+- 仍然遵守 Step 0 读取的 constitution 约束
+
+**如果是普通模式，继续 Step 3。**
+
+### Step 3：域匹配与确认（Level 2 预备）
+
+基于 `knowledge-catalog.md` 的目录信息，结合用户 prompt，**无需读取完整 SKILL.md**，仅凭目录中的一行摘要判断涉及哪些业务域：
+
+```
+根据你的需求，我认为涉及以下业务域：
+
+✓ order（订单域）— 订单创建、状态流转       [verified] → 将加载完整 Skill
+✓ payment（支付域）— 支付发起、回调          [proven]  → 将加载完整 Skill
+? logistics（物流域）— 发货跟踪             [未初始化] → 是否顺便新建？
+
+确认以上分类？（直接回车确认，或告诉我调整）
+```
+
+**`⚠️` 标注的 Skill** 表示可能已过时，提醒用户：「该 Skill 距上次引用已超过阈值，内容可能过时，将以代码为准」。
+
+若用户确认新建缺失的 Skill，调用 Skills Builder SubAgent（模式 A）新建后再继续。
+
+### Step 4：Level 2 加载——读匹配 Skill（~3000 tokens/个）
+
+读取用户确认的业务域对应的完整 SKILL.md 文件，将其内容作为背景知识。
+
+**注意事项：**
+- 只加载确认相关的域，不相关的域 Skill **不读取**（节省 token）
+- 若 Skill 的 `maturity` 为 `draft`，提示：「该 Skill 较新，若与代码有出入，以代码为准」
+- 对 Skill 中的内容进行「有则更新无则新增」的感知：
+  - 若当前代码与 Skill 记录有出入，以代码为准，并在回复末尾标注「Skill 更新建议」
+  - 若 Skill 没有覆盖此次需求的概念，在编码过程中补充
+
+### Step 5：澄清用户意图（AskUserQuestion）
+
+在开始编码前，确保充分理解用户意图。根据用户 prompt 和已加载的 Skill 上下文，提出 1-3 个关键澄清问题。
+
+**提问原则：**
+- 只问影响实现方向的关键问题，不问可以从代码中推断的细节
+- 若 prompt 已足够明确（有具体接口名、明确功能描述），可跳过此步
+- 从 Skill 的 `[pitfall]` 条目中检查是否存在与本次需求相关的已知坑，若有则主动提醒
+
+**示例问题类型：**
+```
+为了准确实现，我需要确认几点：
+
+1. [范围] 这次修改只影响 {domain} 域，还是还涉及 {other domain}？
+2. [行为] {具体业务规则的歧义点，如「审批拒绝后是否可以重新提交」}？
+3. [约束] 有没有特殊的兼容性要求（如需要兼容历史数据 / 不能修改现有接口签名）？
+4. [风险] ⚠️ 此功能涉及到已知的 {pitfall}，请确认是否已考虑到？
+```
+
+等待用户回答后，输出理解摘要：
+
+```
+好的，我的理解是：
+- {要点1}
+- {要点2}
+- 遵守项目约束：{来自 constitution 的关键规则}
+
+如果理解无误，我来开始实现。
+```
+
+### Step 6：执行编码任务（Level 3 按需加载）
+
+基于已加载的业务上下文和澄清后的意图，执行用户的编码请求：
+
+- 遵循项目已有的代码风格和命名规范（从 Skill 提取）
+- **严格遵守 constitution 中的 hard_rules**（比 Skill 中的建议优先级更高）
+- 引用已知的实体、接口、关键文件（避免臆造）
+- **Level 3 加载：** 需要具体代码实现时，按需读取 Skill 中 `关键文件索引` 指向的实际代码文件（而非预先全量读取）
+- 对不确定的业务规则，优先参考 Skill 中的规则描述
+- 如发现 Skill 中记录有误或过时，在回复末尾标注「Skill 更新建议」
+
+### Step 7（可选）：Skill 更新建议
+
+如果在编码过程中发现业务 Skill 有遗漏或错误，在回复末尾追加：
+
+```
+📝 Skill 更新建议（运行 /modus:plan 或 /modus:spec 时会自动应用）：
+- [model] order 域：发现 OrderStatus 枚举新增了 PENDING_REVIEW 状态
+- [pitfall] order 域：批量操作时若不分页会导致内存溢出
+```
+
+---
+
+## 氛围编程原则
+
+- **先理解再编码**：先复述对需求的理解，确认后再写代码
+- **有据可依**：引用的实体、字段、接口名必须来自 Skill 或已有代码
+- **风格一致**：生成的代码应与项目现有风格保持一致
+- **宪法优先**：constitution.hard_rules 是不可违反的底线，优先于一切
+- **按需加载**：不预先读取所有 Skill，降低 token 消耗
+- **主动补全**：发现明显缺失（如缺少参数校验、日志）时主动补充