@modus-ai/modus 0.1.0

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

@@ -0,0 +1,227 @@
+# modus-init
+
+**触发条件：** 用户运行 `/modus:init` 时使用此 Skill。
+
+## 职责
+
+分析当前项目代码库，按业务领域分类，为每个业务域生成 Business Skill 文件，同时初始化团队约定 Skill（Layer 0-T）、技术知识 Skill（Layer 1）和知识全景目录索引（`modus/knowledge-catalog.md`），作为后续所有 Modus 命令的知识底座。
+
+---
+
+## 执行流程
+
+### Step 0：读取项目宪法
+
+读取 `modus/config.yaml`（若存在），提取 `constitution` 字段中的硬性约束，作为整个初始化过程的最高优先级约束。
+
+若 `modus/config.yaml` 不存在，将在 Step 5 创建默认配置。
+
+### Step 1：项目扫描与业务分类
+
+启动一个「项目分析 SubAgent」，执行以下操作：
+
+1. 读取项目根目录结构，识别主要模块、包或服务
+2. 扫描核心代码文件（优先：Controller/Facade、Service、Manager、Mapper/DAO、Domain/Entity、配置文件）
+3. 结合文件名、包名、注释、接口命名，提炼业务域列表
+4. 每个业务域给出：
+   - 域名称（英文，用作目录名，如 `order`, `payment`, `user`）
+   - 中文名称（如 订单域、支付域、用户域）
+   - 核心职责一句话概述
+   - 涉及的主要文件路径（最多 5 个代表性路径）
+
+**输出格式（向用户展示）：**
+
+```
+我识别到以下业务域，请确认：
+
+1. order（订单域）— 订单创建、状态流转、查询
+   关键文件: OrderController, OrderService, OrderMapper, OrderDomain
+2. payment（支付域）— 支付发起、回调、退款
+   关键文件: PayFacade, PayManager, PayRecordMapper
+3. user（用户域）— 用户注册、登录、权限
+   关键文件: UserController, UserService, AuthManager
+
+是否确认以上分类？（可以修改/新增/删除）
+```
+
+### Step 2：用户确认
+
+等待用户确认或修改业务域列表。用户可以：
+- 直接回复「确认」继续
+- 修改某个域的名称或描述
+- 增加遗漏的业务域
+- 删除不需要的域
+
+### Step 3：生成业务 Skill（Layer 2）
+
+用户确认后，为每个业务域调用「Skills Builder SubAgent」（`modus-harness-00-skills-builder` Skill，模式 A），生成对应的业务 Skill 文件：
+
+**目标路径：** `.codebuddy/skills/modus-biz-{domain}/SKILL.md`
+
+每个 Skill 文件遵循 Business Skill 标准格式（含 maturity/last_referenced/usage_count 字段）。
+
+### Step 4：生成团队约定 Skill（Layer 0-T）
+
+调用「Skills Builder SubAgent」（模式 E：团队约定初始化）：
+
+从以下来源提取团队规范：
+1. 项目中已有的 `CONTRIBUTING.md`、`.editorconfig`、`checkstyle.xml`、`pmd.xml` 等规范文件
+2. `modus/config.yaml` 中的 `constitution.hard_rules`
+3. 代码中高频出现的注解模式（如 `@Transactional`、`@DistributedLock` 的用法）
+
+生成文件：`.codebuddy/skills/modus-team-conventions/SKILL.md`
+
+### Step 5：生成技术知识 Skill（Layer 1）
+
+调用「Skills Builder SubAgent」（模式 E：技术知识初始化），初始化一个空的技术知识骨架：
+
+生成文件：`.codebuddy/skills/modus-tech-wiki/SKILL.md`
+
+初始内容包含：
+- 已发现的技术栈（从 `pom.xml` 或 `build.gradle` 提取）
+- 框架版本信息
+- 占位符章节（反模式库、架构决策、跨项目经验——待后续工作流积累）
+
+### Step 6：生成知识全景目录（knowledge-catalog.md）
+
+在 `modus/knowledge-catalog.md` 创建全景索引，内容如下：
+
+```markdown
+# Modus 知识全景目录
+# 所有 Modus 命令启动时先读此文件（~200 tokens），按需加载完整 Skill
+
+updated: {YYYY-MM-DD}
+
+## 团队约定 (Layer 0-T)
+- **modus-team-conventions**: 代码规范/提交规范/最佳实践 [maturity: draft] 更新: {日期}
+
+## 技术知识 (Layer 1)
+- **modus-tech-wiki**: 跨项目技术经验（反模式、架构决策、性能优化） [maturity: draft] 更新: {日期}
+
+## 业务知识 (Layer 2)
+- **modus-biz-order**: 订单域 — 创建/状态流转/查询 [maturity: draft] 最近引用: {日期}
+- **modus-biz-payment**: 支付域 — 发起/回调/退款 [maturity: draft] 最近引用: {日期}
+- **modus-biz-user**: 用户域 — 注册/登录/权限 [maturity: draft] 最近引用: {日期}
+
+## 使用说明
+所有 Skill 初始 maturity 为 draft。随着工作流执行和人工验证：
+- 在 1 个工作流中被成功引用 → verified
+- 在 ≥2 个工作流中验证有效 → proven
+衰减规则：proven 12 个月未引用 → verified；verified 6 个月未引用 → draft（标注 ⚠️ 可能已过时）
+```
+
+### Step 7：初始化 modus/config.yaml（若不存在）
+
+若项目尚无 `modus/config.yaml`，生成默认配置：
+
+```yaml
+# Modus 项目配置
+
+# TAPD 项目 ID（可选，用于 Harness 自动创建 Bug 单）
+tapdProjectId: ""
+
+# Harness 流程配置
+harness:
+  buildCommand: "mvn clean compile -q"
+  environments: [dev, test, pre]
+
+# 项目宪法（所有 SubAgent 必须遵守的硬性约束）
+# 这些约束在每次命令执行时自动加载，无需重复说明
+constitution:
+  tech_stack: ""              # 如 "Java 17 + Spring Boot 3 + MyBatis"
+  test_command: ""            # 如 "mvn test -pl {module}"
+  hard_rules: []              # 如 ["Mapper 接口必须在 dao 包下", "金额使用 Long 单位分"]
+  build_command: ""           # 如 "mvn clean compile -q"
+  key_patterns: []            # 项目特有的技术模式描述
+```
+
+提示用户填写 `constitution` 字段，以便后续命令无需重复说明项目约束。
+
+### Step 8：完成回报
+
+所有业务 Skill 生成完毕后，回复用户：
+
+```
+✅ Modus 知识库初始化完成
+
+生成了 N 个业务 Skill（Layer 2）：
+- .codebuddy/skills/modus-biz-order/SKILL.md    [draft]
+- .codebuddy/skills/modus-biz-payment/SKILL.md  [draft]
+- ...
+
+初始化基础 Skill：
+- .codebuddy/skills/modus-team-conventions/SKILL.md  (Layer 0-T) [draft]
+- .codebuddy/skills/modus-tech-wiki/SKILL.md          (Layer 1)   [draft]
+
+知识目录：
+- modus/knowledge-catalog.md（所有命令的快速索引，~200 tokens）
+
+💡 建议：填写 modus/config.yaml 中的 constitution 字段，
+   记录项目硬性约束（技术栈、命名规范等），后续所有命令将自动加载。
+
+现在可以使用：
+  /modus:vibe  — 氛围编程（自动加载业务上下文）
+  /modus:plan  — 功能规划
+  /modus:spec  — 规范驱动开发
+  /modus:harness — 全自动 Harness 流程
+```
+
+---
+
+## 重新初始化（已有 Skill 时）
+
+如果 `.codebuddy/skills/` 下已存在 `modus-biz-*` 目录：
+
+1. 提示用户当前已有哪些业务 Skill 及其最后更新时间和 maturity
+2. 询问：全量重建 / 仅更新指定域 / 新增缺失域
+3. 按用户选择执行对应操作
+4. 无论何种选择，都更新 `modus/knowledge-catalog.md` 的索引信息
+
+---
+
+## Business Skill 标准格式参考（含知识体系字段）
+
+```markdown
+---
+name: modus-biz-{domain}
+description: "[MODUS:BIZ] {中文域名}业务知识 — {核心职责一句话}"
+version: 1.0.0
+updated: {YYYY-MM-DD}
+maturity: draft             # draft | verified | proven
+last_referenced: {YYYY-MM-DD}
+usage_count: 0
+---
+
+# {中文域名}业务知识
+
+## 1. 域概述
+{业务域的职责边界、核心价值，2-3句话}
+
+## 2. 核心实体 [model]
+| 实体名 | 说明 | 关键字段 |
+|--------|------|----------|
+| ...    | ...  | ...      |
+
+## 3. 业务规则 [process] [guideline]
+- [guideline] {规则1：如 订单状态只能按指定方向流转}
+- [process]   {规则2：如 退款金额不能超过原始支付金额}
+- [pitfall]   {已知坑：如 并发创建订单时需加分布式锁}
+
+## 4. 关键文件 [decision]
+| 层次 | 文件/类 | 说明 |
+|------|---------|------|
+| Controller | ...Controller | ... |
+| Service | ...Service | ... |
+| Mapper | ...Mapper | ... |
+
+## 5. API 契约（重要接口）[model]
+- `POST /api/v1/{domain}/create` — {说明}
+- `GET /api/v1/{domain}/{id}` — {说明}
+
+## 6. 项目特有模式 [decision] [guideline]
+- [decision] {架构决策：如 选择事件驱动而非同步 RPC 的原因}
+- [guideline] {推荐做法：如 AopContext.currentProxy() 解决事务同类调用}
+
+## 7. 典型代码示例
+{重要业务逻辑的代码片段，帮助 AI 理解实现风格}
+```

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

@@ -0,0 +1,246 @@
+# modus-plan（计划模式）
+
+**触发条件：** 用户运行 `/modus:plan [需求描述]` 时使用此 Skill。
+
+支持快速模式：`/modus:plan --quick [描述]` 跳过 design.md，仅生成 proposal + tasks。
+
+## 职责
+
+功能规划入口。通过**三级渐进加载**获取业务上下文（前置更新），基于最新知识生成结构化的 proposal/design/tasks 文档，归档后将本次规划中的新知识回写到 Skill（后置更新），并将状态写入 `.modus-state.yaml` 支持断点续跑。
+
+---
+
+## 执行流程
+
+### Step 0：读取项目宪法 + 断点续跑检查
+
+**读取 constitution：**
+读取 `modus/config.yaml` 的 `constitution` 字段，作为最高优先级约束贯穿整个规划流程。
+
+**断点续跑检查：**
+扫描 `modus/plans/` 目录，检查是否存在同名的 `.modus-state.yaml`：
+- 若存在且 `status: in-progress`，提示用户：
+  ```
+  检测到未完成的规划：{name}
+  已完成：{completed 列表}
+  待完成：{pending 列表}
+  
+  是否继续上次的规划，还是重新开始？
+  ```
+- 若用户选择继续，跳到对应的未完成步骤
+- 若是全新流程，正常从 Step 1 开始
+
+### Step 1：Level 1 加载——读知识目录（~200 tokens）
+
+读取 `modus/knowledge-catalog.md`，了解当前可用 Skill 及其状态。
+
+若不存在，与 vibe 模式相同的降级提示（建议先运行 /modus:init）。
+
+### Step 2：域匹配与确认（有则更新，无则新增）
+
+基于 catalog 目录信息（无需读完整 Skill），结合用户 prompt，判断涉及的业务域：
+
+```
+根据你的需求，我认为涉及以下业务域：
+
+✓ order（订单域）    [verified] → 将前置更新后使用
+✓ payment（支付域）  [proven]  → 将前置更新后使用
+? export（导出域）   [未初始化] → 将在前置步骤中新建
+
+确认？
+```
+
+### Step 3：澄清用户意图（AskUserQuestion）
+
+确认域后，在正式启动规划前，提出 1-3 个关键澄清问题：
+
+**提问原则：**
+- 聚焦影响规划方向的不确定点（范围、优先级、约束条件）
+- 若 prompt 已足够具体，可跳过此步
+- 从 Skill 中已有的 `[pitfall]` 和 `[decision]` 检查是否存在相关风险点
+
+**示例问题类型：**
+```
+为了生成准确的规划文档，我需要确认：
+
+1. [范围] 这次改动是否涉及 {相邻域}，还是严格限定在 {domain} 域内？
+2. [优先级] 功能上线有时间限制吗？影响 Sprint 拆分方式。
+3. [兼容性] {已有接口/数据结构} 是否可以修改，还是需要向后兼容？
+4. [规模] 预期数据量级是多少？影响技术方案选型。
+5. [风险] ⚠️ Skill 中记录了已知坑：{pitfall}，是否已考虑到？
+```
+
+等待用户回答后，输出意图摘要：
+
+```
+理解已确认：
+- 目标: {一句话概括}
+- 边界: {在范围内 / 不在范围内}
+- 约束: {技术/业务约束}
+- 项目硬性规则: {来自 constitution 的关键规则}
+
+开始前置更新 Skill，然后生成规划文档。
+```
+
+### Step 4：前置 Skill 更新（Level 2 加载）
+
+确认域和意图后，启动「Skill 更新 SubAgent」（`modus-harness-00-skills-builder` 模式 B），对每个涉及的业务域执行：
+
+1. **Level 2 加载**：读取完整 SKILL.md 文件
+2. 扫描该域相关的最新代码文件（近期变更的文件）
+3. 对比 Skill 内容与代码现实，识别差异
+4. 更新 Skill 文件中过时的信息，更新 `last_referenced` 和 `usage_count`
+5. 输出更新摘要：`✓ modus-biz-order Skill 已更新（新增: OrderStatus.PENDING_REVIEW | maturity: draft→verified）`
+
+若有未初始化的域，调用模式 A 新建 Skill。
+
+### Step 5：生成计划文档
+
+基于更新后的 Skill 和已澄清的意图，生成文档到 `modus/plans/{name}/`。
+
+**写入状态文件：**
+创建 `modus/plans/{name}/.modus-state.yaml`：
+```yaml
+mode: plan
+name: {name}
+status: in-progress
+domains: [{domain1}, {domain2}]
+quick_mode: false
+completed: []
+pending: [proposal, design, tasks]
+created: {ISO8601时间戳}
+```
+
+**确定 plan 名称：**
+- 从用户 prompt 提取关键词，生成 kebab-case 名称（如 `add-batch-approve`）
+- 如果目录已存在，提示用户确认
+
+**快速模式（`--quick`）产出物：** proposal.md + tasks.md（跳过 design.md）
+
+**产出物依赖（完整模式）：**
+
+```
+proposal.md  ─────────────┐
+                           ▼
+design.md ────────────► tasks.md
+```
+
+**1. proposal.md** — 意图与范围
+
+```markdown
+# Proposal: {功能名称}
+
+## 意图
+{为什么做，业务价值}
+
+## 范围
+在范围内：
+- {具体事项}
+不在范围内：
+- {明确排除}
+
+## 关键约束（来自项目宪法）
+- {constitution.hard_rules 中与本次相关的规则}
+
+## 方案概述
+{技术路径的高层描述}
+```
+
+**2. design.md** — 技术方案
+
+```markdown
+# Design: {功能名称}
+
+## 技术方案
+{详细实现路径，引用具体的类/方法/接口}
+
+## 架构决策 [decision]
+### 决策: {决策点}
+选择方案: {方案}
+原因: {理由}
+
+## 数据流
+{文字或 mermaid 图}
+
+## 涉及文件变更
+- {文件路径} — {新增/修改/删除}
+```
+
+**3. tasks.md** — 实现清单
+
+```markdown
+# Tasks: {功能名称}
+
+## 1. 数据层
+- [ ] 1.1 {具体任务}
+
+## 2. 服务层
+- [ ] 2.1 {具体任务}
+
+## 3. 接口层
+- [ ] 3.1 {具体任务}
+
+## 4. 测试
+- [ ] 4.1 单元测试
+- [ ] 4.2 接口联调
+```
+
+生成每份文档后更新 `.modus-state.yaml` 的 `completed` 列表。
+
+### Step 6：询问归档 ⏸️ 【人工审批节点】
+
+```
+计划文档已生成：
+  modus/plans/{name}/proposal.md
+  modus/plans/{name}/design.md
+  modus/plans/{name}/tasks.md
+
+状态文件：modus/plans/{name}/.modus-state.yaml
+
+是否归档？归档后文档将移动到 modus/plans/archive/{YYYY-MM-DD}-{name}/
+（归档前可以继续编辑文档）
+```
+
+⏸️ **等待人工确认**（支持异步：可以在任意时间、任意设备上回复）
+
+用户确认归档后：
+1. 将目录移动到 `modus/plans/archive/{date}-{name}/`
+2. 更新 `.modus-state.yaml`：`status: archived`
+3. 回复：`✓ 已归档到 modus/plans/archive/{date}-{name}/`
+
+### Step 7：后置 Skill 更新（知识回写）
+
+归档完成后（或用户选择不归档但完成了规划），执行后置 Skill 更新（模式 C）：
+
+1. 从本次生成的 design.md 和 tasks.md 中提取新的技术决策和实现细节
+2. 带类型标签回写到对应业务 Skill：
+   - `[decision]` → 架构决策章节
+   - `[guideline]` → 推荐做法/禁止做法
+   - `[pitfall]` → 已知风险
+3. 更新 `modus/knowledge-catalog.md` 的 `last_referenced` 和 maturity
+4. 输出更新摘要：
+   ```
+   📚 知识已回写到 Skill：
+   - [decision] order 域：新增批量审批走 MQ 异步的架构决策
+   - [guideline] order 域：批量操作上限 50 条，防止内存溢出
+   ```
+
+---
+
+## 产出物目录结构
+
+```
+modus/
+├── plans/
+│   ├── add-batch-approve/           ← 活跃计划（未归档）
+│   │   ├── .modus-state.yaml        ← 状态文件（断点续跑用）
+│   │   ├── proposal.md
+│   │   ├── design.md
+│   │   └── tasks.md
+│   └── archive/
+│       └── 2026-04-20-add-batch-approve/
+│           ├── .modus-state.yaml    ← status: archived
+│           ├── proposal.md
+│           ├── design.md
+│           └── tasks.md
+```