@modus-ai/modus 0.2.1 → 0.2.3

package/templates/skills/modus-harness-agents/00-skills-builder/SKILL.md

@@ -1,367 +0,0 @@
----
-name: modus-harness-00-skills-builder
-description: Use this skill when building, updating, or extracting knowledge to/from Business Skill files. Called by /modus:init (Mode A: new), /modus:plan and /modus:spec pre/post update (Mode B/C), Harness ARCHIVE phase (Mode D), and baseline Skill initialization (Mode E). Trigger when any Modus workflow needs to create or refresh .codebuddy/skills/modus-biz-*/SKILL.md or knowledge-catalog.md.
-allowed-tools: Read, Write, Glob, Bash
-disable: false
----
-
-# modus-harness-00-skills-builder（Skills Builder SubAgent）
-
-**调用方：** `/modus:init` / `/modus:plan` 前置更新 / `/modus:spec` 前置更新 / Harness 后置更新 / Harness ARCHIVE 阶段  
-**输入：** 业务域信息 + 项目代码  
-**产出物：** `.codebuddy/skills/modus-biz-{domain}/SKILL.md` / `modus-team-conventions/SKILL.md` / `modus-tech-wiki/SKILL.md` + `modus/knowledge-catalog.md` 更新
-
-## 职责
-
-从项目代码和工作流产物中提炼业务知识，生成或更新标准格式的 Skill 文件，并维护知识全景目录（`knowledge-catalog.md`）。支持五种调用模式，覆盖从初始化到持续积累的完整知识生命周期。
-
----
-
-## 调用模式
-
-### 模式 A：全量初始化（来自 /modus:init）
-
-为每个确认的业务域从零生成 `modus-biz-{domain}/SKILL.md`，初始 maturity 为 `draft`。
-
-### 模式 B：增量更新（来自 /plan 或 /spec 前置，含 hash 快速检查）
-
-更新已有 `modus-biz-*/SKILL.md`，刷新过时内容，补充新发现的知识。
-
-**执行前必须先进行 hash 检查，避免不必要的全量扫描：**
-
-#### 模式 B — Step 0：hash 检查（每个域独立检查）
-
-1. 读取 SKILL.md frontmatter 的 `last_hash` 和 `key_files`
-2. 使用 Bash 计算当前 `key_files` 内容的 SHA-1 摘要：
-
-   ```bash
-   shasum -a 1 {file1} {file2} ... | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
-   ```
-
-3. 对比结果：
-   - **hash 一致（且 last_hash 非空）** → 跳过全量扫描，仅更新 `last_referenced` 字段，输出：  
-     `✓ modus-biz-{domain} 无变化（hash 匹配），跳过更新（节省 ~2000 tokens）`
-   - **hash 不一致 或 last_hash 为空** → 执行下方完整流程
-   - **key_files 为空 或 某文件不存在** → 视为「已变化」，执行完整流程
-
-#### 模式 B — 完整更新流程（仅 hash 不匹配时执行）
-
-对比现有 Skill 内容与最新代码，**仅修改有变化的部分**，保留无变化的内容。  
-更新完成后，**必须**将新 hash 写入 frontmatter 的 `last_hash` 字段。
-
-### 模式 C：后置回写（来自 /plan、/spec 归档后）
-
-将本次工作中新确立的决策、规则、接口契约追加或更新到对应 Skill 文件。  
-从产出物（design.md、specs/*/spec.md）提取带类型标签的知识：
-- delta spec 的 ADDED Requirements → `[process]` / `[model]` 追加到业务 Skill
-- delta spec 的 MODIFIED Requirements → 更新对应 `[guideline]`
-- design.md 的架构决策章节 → `[decision]` 追加到对应业务 Skill 或 modus-tech-wiki
-
-### 模式 D：知识提取（来自 Harness ARCHIVE 阶段）——新增
-
-从 Harness 全流程产物中系统性提取知识条目，判断提升路径，写回 Skill 并更新 catalog。
-
-**输入产物：** `01-analysis.md`、`02-sprint-contract.md`、`cr-report.md`、`07-deploy-status.md`
-
-**提取规则：**
-
-| 来源产物 | 提取内容 | 知识类型 | 写入目标 |
-|---------|---------|---------|---------|
-| 01-analysis.md 的风险点 | 业务边界条件、并发风险 | `[pitfall]` | modus-biz-{domain} |
-| 02-sprint-contract.md 的架构决策 | 技术选型原因 | `[decision]` | modus-tech-wiki |
-| cr-report.md 的 P1/P2 问题 | 规范违反模式 | `[pitfall]` `[guideline]` | modus-team-conventions |
-| 07-deploy-status.md 的部署注意事项 | 环境特殊配置 | `[guideline]` | modus-tech-wiki |
-
-**成熟度提升判定：**
-- 本次工作流成功验证了某条知识 → `draft` 升为 `verified`，更新 `last_referenced` 和 `usage_count +1`
-- 若该知识已是 `verified` 且跨不同工作流被引用 ≥2 次 → 升为 `proven`
-
-**hash 更新（ARCHIVE 阶段必做）：**
-- 对每个在本次 Harness 中被修改的业务 Skill（modus-biz-*），在写入知识后**重新计算 hash**：
-  ```bash
-  shasum -a 1 {key_files...} | awk '{print $1}' | sort | shasum -a 1 | awk '{print $1}'
-  ```
-- 将新 hash 写入 SKILL.md frontmatter 的 `last_hash` 字段
-- 这确保下次 plan/spec 前置检查时，能正确跳过未变化的 Skill
-
-**衰减检查（每次模式 D 执行时顺带检查）：**
-- 扫描 catalog，检查 `last_referenced` 超过阈值的条目
-- `proven` + 超过 12 个月未引用 → 降为 `verified`，追加注释 `⚠️ 12个月未引用，请验证是否仍然适用`
-- `verified` + 超过 6 个月未引用 → 降为 `draft`，追加注释 `⚠️ 6个月未引用，可能已过时`
-
-### 模式 E：基础 Skill 初始化（来自 /modus:init）——新增
-
-初始化团队约定 Skill（Layer 0-T）和技术知识 Skill（Layer 1）。
-
-**团队约定 Skill（`.codebuddy/skills/modus-team-conventions/SKILL.md`）：**
-- 扫描 `CONTRIBUTING.md`、`.editorconfig`、`checkstyle.xml`、`pmd.xml` 等规范文件
-- 读取 `modus/config.yaml` 的 `constitution.hard_rules`
-- 识别代码中高频注解模式
-
-**技术知识 Skill（`.codebuddy/skills/modus-tech-wiki/SKILL.md`）：**
-- 从 `pom.xml` 或 `build.gradle` 提取技术栈和版本信息
-- 初始化空的反模式库、架构决策章节（占位符）
-
----
-
-## 执行流程
-
-### Step 1：定位相关代码/产物
-
-根据调用模式和传入的域/产物信息，定位代码文件或产物文件。
-
-**扫描策略（按优先级）：**
-1. 读取传入的「关键文件列表」
-2. 按包名/目录名模糊匹配（如 `order`、`Order` 相关文件）
-3. 扫描 Controller/Facade 层入口，顺调用链向下读取 Service/Manager/Mapper
-
-### Step 2：提炼知识内容
-
-从代码或产物中提炼以下信息，并打上知识类型标签：
-
-**知识五类型（MECE 原则）：**
-- `[model]` 实体定义、数据结构、关系图、枚举
-- `[decision]` 技术选型、架构决策及理由
-- `[guideline]` 推荐做法（`recommend`）或禁止做法（`avoid`）
-- `[pitfall]` 已知风险、故障模式、排查步骤
-- `[process]` 业务流程、状态机、操作步骤
-
-**核心提炼内容：**
-- 核心实体（Entity/Domain）：类名、关键字段（业务含义重要的）、枚举值
-- 业务规则（从 Service/Manager 中提炼）：`if/else` 分支、前置校验、状态流转
-- 关键文件索引：各层次主要类文件路径
-- API 契约（从 Controller/Facade 提炼）：接口路径、关键请求/响应字段
-- 典型代码示例（可选，高价值）：体现项目特有模式的代码片段
-
-### Step 3：并发冲突检测（写入前必做）
-
-多人协作时，同一个 Skill 可能被并发更新。写入前先检查：
-
-1. **读取 Skill 文件头部的 `version` 和 `updated` 字段**
-2. **对比当前内容与本次要写入的内容**，判断是否有冲突风险：
-
-```
-冲突场景：
-- 你在准备写入 modus-biz-order v2.0.0
-- 但文件当前已经是 v2.0.0（说明有人已经抢先更新了）
-```
-
-**冲突处理策略（merge-friendly，保证 Git 无冲突）：**
-
-- **新增知识** → 只往文件末尾 **追加**（append），不修改已有行
-  ```markdown
-  ## 更新日志
-
-  ### {YYYY-MM-DD HH:mm} v{N+1} — {更新者描述}
-  - [model] 新增 OrderStatus.PENDING_REVIEW 枚举值
-  - [pitfall] 批量操作超过 500 条会触发慢查询
-  ```
-- **修改已有知识** → 在对应条目后追加 `(已更新: {YYYY-MM-DD})` 注释，不直接覆盖原行
-- **删除过时知识** → 不物理删除，改为在条目前加 `~~` 删除线标记并注明原因
-
-**为什么这样设计：**
-- Git merge 时，append-only 的文件几乎不会产生冲突
-- 保留了变更历史，方便溯源
-- 团队成员可以看到知识演进过程
-
-### Step 4：写入 Skill 文件
-
-按 Business Skill 标准格式生成或更新文件：
-
-**更新策略（模式 B/C/D）：**
-- 对比现有 Skill 内容和最新信息，识别差异
-- **新增内容追加到文件末尾**，修改内容以注释方式标注（见 Step 3）
-- 更新文件头的 `updated` 日期、`version`（自增）、`last_referenced`、`usage_count`
-- **模式 B/D 完整更新后**：重新计算 `key_files` 内容的 SHA-1 并写入 `last_hash`（模式 C 后置回写不更新 hash，因为它是从产出物提取知识而非扫描代码）
-- 在文件末尾追加「本次更新摘要」注释
-
-### Step 5：更新 knowledge-catalog.md
-
-每次写入 Skill 后，同步更新 `modus/knowledge-catalog.md`：
-- 更新对应条目的 `maturity`、`last_referenced`
-- 若有新建 Skill，追加一行
-- 若检测到衰减，在条目后追加 `⚠️` 标记
-
----
-
-## Skill 文件标准格式
-
-### Business Skill（modus-biz-{domain}）
-
-```markdown
----
-name: modus-biz-{domain}
-description: "[MODUS:BIZ] {中文域名}业务知识 — {核心职责一句话描述}"
-version: {N}.0.0
-updated: {YYYY-MM-DD}
-maturity: draft             # draft | verified | proven
-last_referenced: {YYYY-MM-DD}
-usage_count: 0
-last_hash: ""               # SHA-1(key_files 内容)，模式 B/D 更新后自动计算并填入
-key_files:                  # 关键源文件列表，用于 hash 快速检查（最多 10 个）
-  - src/.../service/{Domain}Service.java
-  - src/.../manager/{Domain}Manager.java
-  - src/.../dao/{Domain}Mapper.java
-  - src/.../domain/{Domain}.java
----
-
-# {中文域名}业务知识
-
-> 由 Modus Skills Builder 自动生成。[MODUS:BIZ]
-
-## 1. 域概述
-
-{业务域的职责边界和核心价值，2-3 句话，人类可读}
-
-**边界说明：**
-- 属于本域：{列举主要职责}
-- 不属于本域：{明确排除的职责}
-
-## 2. 核心实体 [model]
-
-| 实体名 | 中文名 | 说明 | 关键字段 |
-|--------|--------|------|----------|
-| Order  | 订单   | ...  | id, status, tenantId, amount |
-
-### 重要枚举 [model]
-
-\`\`\`java
-// OrderStatus — 订单状态
-CREATED(1, "已创建"),
-PAID(2, "已支付"),
-COMPLETED(3, "已完成"),
-CANCELLED(4, "已取消")
-\`\`\`
-
-## 3. 业务规则
-
-- [process]   {流程规则：如 订单状态只能按 CREATED→PAID→COMPLETED 单向流转}
-- [guideline] {推荐做法：如 退款金额必须 ≤ 原始支付金额，在 Service 层校验}
-- [pitfall]   {已知坑：如 并发创建时若不加锁会出现重复订单}
-- [decision]  {架构决策：如 选择 MQ 异步通知而非同步 RPC，原因是解耦和削峰}
-
-## 4. 关键文件索引 [model]
-
-| 层次 | 类名 | 路径 | 说明 |
-|------|------|------|------|
-| Controller | OrderController | src/.../controller/OrderController.java | 订单 REST 接口 |
-| Service | OrderService | src/.../service/OrderService.java | 订单核心逻辑 |
-| Mapper | OrderMapper | src/.../dao/OrderMapper.java | 订单 DB 操作（注意：在 dao 包下）|
-| Domain | Order | src/.../domain/Order.java | 订单领域对象 |
-
-## 5. API 契约 [model]
-
-| 方法 | 路径 | 说明 | 关键参数 |
-|------|------|------|----------|
-| POST | /api/v1/orders | 创建订单 | amount, productId |
-| GET | /api/v1/orders/{id} | 查询订单 | id |
-
-## 6. 项目特有模式 [decision] [guideline]
-
-- [guideline] 事务使用 `AopContext.currentProxy()` 解决同类调用问题（avoid: @Transactional 直接同类调用）
-- [guideline] 分布式锁使用 `@DistributedLock` 注解，key 格式为 `{domain}:{id}`
-- [guideline] 响应统一用 `BaseRpcResponse.build(data)` 包装
-
-## 7. 典型代码示例
-
-\`\`\`java
-// 订单创建的标准模式
-public OrderDTO createOrder(CreateOrderRequest request) {
-    // 1. 参数校验（Service 层）
-    // 2. 业务校验（余额、库存）
-    // 3. 创建 Domain 对象
-    // 4. 持久化
-    // 5. 发送 MQ 通知
-    // 6. 返回 DTO
-}
-\`\`\`
-
----
-<!-- 更新摘要（由 Skills Builder 自动追加）
-[{YYYY-MM-DD}] 模式B更新：新增 OrderStatus.PENDING_REVIEW 枚举值
-[{YYYY-MM-DD}] 模式C回写：新增批量审批接口 POST /orders/batch-approve 的 API 契约
--->
-```
-
-### 团队约定 Skill（modus-team-conventions）
-
-```markdown
----
-name: modus-team-conventions
-description: "[MODUS:TEAM] 团队约定 — 代码规范/提交规范/最佳实践"
-version: 1.0.0
-updated: {YYYY-MM-DD}
-maturity: draft
-layer: "0-T"
----
-
-# 团队约定
-
-> Layer 0-T：团队级约定，所有项目成员和 SubAgent 必须遵守。
-
-## 1. 编码规范 [guideline]
-
-- [guideline] {从 checkstyle/pmd 提取的关键规则}
-- [guideline] {命名规范：如 常量全大写下划线，变量驼峰命名}
-
-## 2. 项目硬性约束 [guideline]
-
-（来自 modus/config.yaml constitution.hard_rules）
-- [guideline] {规则1}
-- [guideline] {规则2}
-
-## 3. 提交规范 [process]
-
-- [process] Commit message 格式：`{type}({scope}): {subject}`
-- [process] type 可选：feat/fix/refactor/test/docs/chore
-
-## 4. 常见反模式 [pitfall]
-
-- [pitfall] {反模式1：如 禁止在 Controller 层写业务逻辑}
-- [pitfall] {反模式2：如 禁止直接修改 final 字段绕过业务校验}
-```
-
-### 技术知识 Skill（modus-tech-wiki）
-
-```markdown
----
-name: modus-tech-wiki
-description: "[MODUS:TECH] 跨项目技术知识 — 架构决策/反模式/性能优化经验"
-version: 1.0.0
-updated: {YYYY-MM-DD}
-maturity: draft
-layer: "1"
----
-
-# 技术知识库
-
-> Layer 1：跨项目通用技术经验，由工作流自动积累。
-
-## 技术栈 [model]
-
-- 框架：{从 pom.xml 提取}
-- 版本：{主要依赖版本}
-
-## 架构决策记录 [decision]
-
-（工作流完成后由 Skills Builder 模式 D 自动追加）
-
-## 跨项目反模式库 [pitfall]
-
-（工作流完成后由 Skills Builder 模式 D 自动追加）
-
-## 性能优化经验 [guideline]
-
-（工作流完成后由 Skills Builder 模式 D 自动追加）
-```
-
----
-
-## Skill 质量标准
-
-- `description` 字段必须包含对应标记：业务 Skill 用 `[MODUS:BIZ]`，团队约定用 `[MODUS:TEAM]`，技术知识用 `[MODUS:TECH]`
-- 业务规则必须来自代码，不能臆造
-- 关键文件索引路径必须真实存在
-- 每条知识条目必须打上五类型标签之一：`[model]` `[decision]` `[guideline]` `[pitfall]` `[process]`
-- 更新时必须更新 `updated` 日期和 `last_referenced`
-- 模式 D 每次执行后必须同步更新 `modus/knowledge-catalog.md`