@netpilot/skills 0.3.2 → 0.6.0

package/scripts/validate.mjs

@@ -1,10 +1,9 @@
-import { readFile, readdir } from "node:fs/promises";
+import { lstat, readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const CHINESE_PATTERN = /[\u3400-\u9fff]/u;
-const NON_SKILL_INLINE_TOKENS = new Set(["name", "description"]);
 const BUILT_IN_AGENT_NAMES = new Set(["default", "worker", "explorer"]);
 const AGENT_REASONING_EFFORTS = new Set([
   "none",
@@ -36,11 +35,24 @@ function parseFrontmatter(content) {
   const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
   if (!match) return null;
   const values = {};
+  const structuralErrors = [];
   for (const line of match[1].split(/\r?\n/u)) {
     const field = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/u);
-    if (field) values[field[1]] = unquote(field[2]);
+    if (!field) continue;
+    const [, key, rawValue] = field;
+    if (Object.hasOwn(values, key)) {
+      structuralErrors.push(`frontmatter 字段重复：${key}`);
+      continue;
+    }
+    const trimmedValue = rawValue.trim();
+    values[key] =
+      trimmedValue === "true"
+        ? true
+        : trimmedValue === "false"
+          ? false
+          : unquote(trimmedValue);
   }
-  return values;
+  return { values, structuralErrors };
 }
 
 function parseOpenAiMetadata(content) {
@@ -253,10 +265,13 @@ export async function validateSkillDirectory(skillDir, knownNames, knownAgentNam
     return { name: directoryName, errors };
   }
 
-  const frontmatter = parseFrontmatter(skillContent);
-  if (!frontmatter) {
+  const parsedFrontmatter = parseFrontmatter(skillContent);
+  let disableModelInvocation = false;
+  if (!parsedFrontmatter) {
     errors.push("SKILL.md 缺少合法 YAML frontmatter");
   } else {
+    const { values: frontmatter, structuralErrors } = parsedFrontmatter;
+    errors.push(...structuralErrors);
     if (!frontmatter.name) errors.push("frontmatter 缺少 name");
     if (frontmatter.name !== directoryName) {
       errors.push(`frontmatter name 必须与目录名一致：${frontmatter.name ?? "<missing>"} != ${directoryName}`);
@@ -267,21 +282,22 @@ export async function validateSkillDirectory(skillDir, knownNames, knownAgentNam
     if (frontmatter.description && !CHINESE_PATTERN.test(frontmatter.description)) {
       errors.push("description 应包含中文说明");
     }
+    if (Object.hasOwn(frontmatter, "disable-model-invocation")) {
+      if (typeof frontmatter["disable-model-invocation"] !== "boolean") {
+        errors.push("disable-model-invocation 必须是 YAML boolean（true 或 false）");
+      } else {
+        disableModelInvocation = frontmatter["disable-model-invocation"];
+      }
+    }
   }
 
   if (/\bTODO\b|\[TODO|PLACEHOLDER/iu.test(skillContent)) errors.push("SKILL.md 包含占位文本");
-  for (const heading of ["## 完成标准", "## 反模式"]) {
-    if (!skillContent.includes(heading)) errors.push(`缺少章节：${heading}`);
-  }
   if (!CHINESE_PATTERN.test(skillContent)) errors.push("SKILL.md 正文应包含中文内容");
 
   const contentWithoutFences = skillContent.replace(/```[\s\S]*?```/gu, "");
   const references = new Set(
     [...contentWithoutFences.matchAll(/\$([a-z0-9]+(?:-[a-z0-9]+)*)/gu)].map((match) => match[1]),
   );
-  for (const match of contentWithoutFences.matchAll(/`([a-z0-9]+(?:-[a-z0-9]+)*)`/gu)) {
-    if (!NON_SKILL_INLINE_TOKENS.has(match[1])) references.add(match[1]);
-  }
   for (const reference of references) {
     if (!knownNames.has(reference)) errors.push(`未知 skill 引用：$${reference}`);
   }
@@ -292,6 +308,39 @@ export async function validateSkillDirectory(skillDir, knownNames, knownAgentNam
   for (const reference of agentReferences) {
     if (!knownAgentNames.has(reference)) errors.push(`未知 Codex agent 引用：agent:${reference}`);
   }
+  for (const match of contentWithoutFences.matchAll(/\[[^\]]*\]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/gu)) {
+    const rawTarget = match[1].replace(/^<|>$/gu, "");
+    if (
+      rawTarget.startsWith("#") ||
+      rawTarget.startsWith("/") ||
+      /^[a-z][a-z0-9+.-]*:/iu.test(rawTarget)
+    ) {
+      continue;
+    }
+    let decodedTarget;
+    try {
+      decodedTarget = decodeURIComponent(rawTarget.split(/[?#]/u, 1)[0]);
+    } catch {
+      errors.push(`相对链接不是合法 URI：${rawTarget}`);
+      continue;
+    }
+    const skillsRoot = path.dirname(skillDir);
+    const resolvedTarget = path.resolve(skillDir, decodedTarget);
+    const relativeTarget = path.relative(skillsRoot, resolvedTarget);
+    if (relativeTarget.startsWith("..") || path.isAbsolute(relativeTarget)) {
+      errors.push(`相对链接超出 skills 集合：${rawTarget}`);
+      continue;
+    }
+    try {
+      await lstat(resolvedTarget);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        errors.push(`相对链接不存在：${rawTarget}`);
+      } else {
+        errors.push(`无法检查相对链接：${rawTarget}（${error.message}）`);
+      }
+    }
+  }
 
   try {
     metadataContent = await readFile(metadataPath, "utf8");
@@ -324,8 +373,13 @@ export async function validateSkillDirectory(skillDir, knownNames, knownAgentNam
     errors.push(`default_prompt 必须显式包含 $${directoryName}`);
   }
   if (typeof invocationPolicy !== "boolean") errors.push("allow_implicit_invocation 必须是 true 或 false");
-  if (invocationPolicy === false) {
-    errors.push("跨宿主单源策略要求 allow_implicit_invocation 为 true；动作权限应由正文门禁控制");
+  if (
+    typeof invocationPolicy === "boolean" &&
+    invocationPolicy !== !disableModelInvocation
+  ) {
+    errors.push(
+      "Claude 的 disable-model-invocation 与 Codex 的 allow_implicit_invocation 调用策略不一致",
+    );
   }
 
   return { name: directoryName, errors };

package/skills/ask/SKILL.md

@@ -1,67 +1,71 @@
 ---
 name: ask
-description: 当用户明确要求选择工作流，或任务的目标、范围、约束、风险、成功标准与下一步不清楚时使用。它是唯一的工作流路由入口：先检查上下文，必要时提出最少量的问题，再选择并启动合适的 skill；不要把它当作普通问答或长期讨论角色。
+description: 当用户明确要求选择工作流，或任务可能跨越访谈、研究、原型、规格、拆票、实施、分诊、审查、架构改进与冲突解决而入口不清楚时使用。它只负责路由，不代替下游 skill 执行工作。
+disable-model-invocation: true
 ---
 
 # Ask
 
-`ask` 是工作流路由器，不是某个个人角色，也不是第二套需求澄清流程。目标是用尽可能少的交互找到正确入口，然后推进工作。
+你不需要记住每个 skill，因此从这里选择。
 
-## 工作流
+**Flow** 是 skills 之间的一条路径。多数工作沿一条 **main flow** 前进，若干 **on-ramp** 汇入主流程；其余能力要么独立使用，要么作为底层词汇层。
 
-1. 先读取当前对话、仓库规则和与任务直接相关的文件。能从上下文或只读检查得到的答案，不询问用户。
-2. 判断任务是否已经具备可执行的目标、范围、约束和完成标准。
-3. 若信息足够，选择一个主 skill，完整读取并按它执行；控制权转交后，`ask` 不再主持后续阶段。只有存在清晰阶段关系时才给出后续 skill 链。
-4. 若缺失信息会实质改变方案、风险或写入范围，一次只问一个高价值问题。优先给出 2 至 3 个互斥选项、推荐项及影响，也允许用户自由回答。问题不阻塞安全、可逆的只读检查或设计时，先继续这些工作；只有答案会改变当前写入范围或造成不可逆影响时才暂停。
-5. 每次回答后重新判断，不机械完成预设问卷。信息足够就停止提问并进入执行。
+## 主流程：idea → ship
 
-## 路由规则
+这是多数产品与工程工作的路线。
 
-| 情形 | 主 skill | 常见后续 |
-| --- | --- | --- |
-| 明确要建立或继续一个跨会话学习工作区 | `teach` | `research` |
-| 需要深入访谈，并明确要求同步维护项目术语、CONTEXT 或 ADR | `grill-with-docs` | `to-spec` |
-| 重大计划、架构或产品决策需要深入访谈 | `grill` | `to-spec` |
-| 想法很大、方向模糊、需要寻找落地路径 | `wayfinder` | `research`、`prototype`、`to-spec` |
-| 陌生技术、事实或方案需要证据 | `research` | `prototype` |
-| 高风险假设需要快速实证 | `prototype` | `to-spec` |
-| 术语、概念边界或业务不变量混乱 | `domain-modeling` | `codebase-design` |
-| 需要决定模块、职责或依赖方向 | `codebase-design` | `to-spec` |
-| 已有讨论，需要形成可验收规格 | `to-spec` | `to-tickets` |
-| 已有规格，需要拆成垂直任务 | `to-tickets` | `implement` |
-| 已有明确任务，需要按边界实施 | `implement` | `code-review` |
-| 行为变更适合测试先行 | `tdd` | `code-review` |
-| bug、测试失败或异常的根因未知 | `diagnosing-bugs` | `tdd` |
-| 需要审查当前变更 | `code-review` | `implement` |
-| 需要跨会话、工具或人员继续 | `handoff` | 无 |
-| 创建或改进 skill | `writing-great-skills` | `code-review` |
+1. **`grill-with-docs`**：通过访谈磨清想法。有代码库，并希望把结论保留到 `CONTEXT.md` 或 ADR 时从这里开始。没有代码库则使用 `grill-me`。二者都复用同一个 `grilling` 访谈引擎；区别是 `grill-with-docs` 会留下项目文档。
+2. **分支——所有问题都能通过讨论确定吗？** 如果某个问题需要可运行答案，例如状态、业务逻辑或必须亲眼比较的 UI，则通过 `handoff` 往返一次原型会话：
+   - 用 `handoff` 保存当前上下文，并在新会话中引用该文件；
+   - 用 `prototype` 以可丢弃代码回答问题；
+   - 再用 `handoff` 把结论带回原想法会话。
+3. **分支——是否需要多个会话才能完成？**
+   - **是**：用 `to-spec` 把讨论整理成规格，再用 `to-tickets` 拆成 tracer-bullet tickets，并声明 blocking edges。远程 tracker 使用 native blocking；本地 tracker 使用一票一文件。随后每个 ticket 都在新鲜上下文中单独调用 `implement`。
+   - **否**：在当前上下文直接调用 `implement`。
 
-同一阶段只指定一个主 skill。不要同时启动多个职责重叠的 skill。
+`implement` 在预先确认的 seams 上使用 `tdd`，一次一个 red-green slice；完成后用 `code-review` 对 diff 做 Standards + Spec 双轴审查，再按权限门禁 commit。只想对一个具体行为 test-first 时，可以独立使用 `tdd`；想相对固定点审查 branch、PR 或工作树时，可以独立使用 `code-review`。
 
-相邻 skill 冲突时按未知项的性质裁决：已有较具体方案、需要挑战决策时选 `grill`；只有用户原始要求明确包含边访谈边更新项目领域文档时才选 `grill-with-docs`，不能因为仓库里存在 `CONTEXT.md` 就自动升级为写入模式；方向与落地路径尚未确定时选 `wayfinder`；主要能由外部证据回答时选 `research`；必须依靠运行结果回答时选 `prototype`。明确任务需要实现且适合测试先行时，以 `tdd` 驱动该实现切片，否则由 `implement` 统筹。
+### 上下文卫生
 
-## 输出
+步骤 1–3 应留在一个连续上下文中：在 `to-tickets` 完成前不要 compact 或 clear，使访谈、规格和 tickets 建立在同一套推理上。每个 `implement` 随后从 ticket 开始，使用独立的新鲜上下文。
 
-信息足够时，用简短说明交代：
+接近当前宿主与模型的可靠推理区边缘时，就提前用 `handoff` 转到新会话；不要等到判断质量已经下降。这里不依赖固定 token 数，因为不同宿主与模型的有效上下文不同。
 
-- 选择的主 skill 及原因；
-- 已确认的关键边界；
-- 仍需验证但不阻塞开始的假设；
-- 紧接着执行的动作。
+## 入口支线
 
-如果只是轻量、明确的任务，不要为了使用 skill 而扩大流程，直接执行最短路径。
+- **原始 bugs、requests 或外部 PR 堆积** → `triage`。它处理别人提交、尚未整理的请求，并产出 agent-ready items。`to-tickets` 创建的 tickets 已经是 agent-ready，不要再次 triage。
+- **某项行为坏了，真实根因未知** → `diagnosing-bugs`。它在形成理论前先建立能对当前故障变红的 tight feedback loop，再以最小复现、假设和证据定位原因并补回归测试。若事后发现根因是缺少可测试 seam，再转向 `improve-codebase-architecture`。
+- **规模巨大且仍在 fog of war 中** → `wayfinder`。它用 tracker 上的 decision tickets 建立共享 map，逐个产出 decisions 而不是 deliverables。路线清楚后回到 `to-spec`，不要直接跳到 `implement`，除非事实证明工作已经足够小。
 
-## 完成标准
+## 代码库健康
 
-- 已选择并开始合适的主 skill，或已提出当前唯一真正阻塞的问题。
-- 用户能看出选择依据、关键边界和下一步。
-- 没有重复询问可从上下文发现的信息。
+`improve-codebase-architecture` 用于日常发现 deepening opportunities。它是寻找候选项的 survey；选定候选后，形成一个想法并回到 `grill-with-docs`。`codebase-design` 则提供设计候选 Module 形状的工作台和统一词汇。
 
-## 反模式
+## 底层词汇
 
-- 不要把 `ask` 和另一个“澄清”skill 串成重复入口。
-- 不要一次抛出长问卷。
-- 不要把推荐列表当作工作成果而停止推进。
-- 不要在目标已经明确时强迫用户重新描述需求。
-- 不要替用户擅自决定会显著改变范围、成本、风险或外部状态的事项。
-- 不要把“请直接开始”解释为授权写入系统级目录、创建远程资源或一次性扩展全部范围。
+这两个 model-invoked references 位于其他流程之下，各自是其词汇的单一来源：
+
+- **`domain-modeling`**：收敛领域语言、解决同词多义，并在必要时更新 `CONTEXT.md` 或记录 ADR。
+- **`codebase-design`**：提供 Module、Interface、Depth、Seam、Adapter、Leverage 与 Locality 等 deep-module 词汇，供 `tdd` 与架构改进流程共同使用。
+
+词语本身是问题时可直接调用；否则由上层流程按需调用。
+
+## 跨会话
+
+- **`handoff`**：当前会话已满、需要分叉到 prototype，或要交给其他 agent/人工时，把上下文写成 Markdown 文件。不要留在原处继续；打开新会话并引用该文件。它是上下文窗口之间的桥。
+- **宿主内置 compact**：留在同一会话，仅将较早消息摘要化。只在阶段之间的有意断点使用；不要在阶段中途 compact。`handoff` 创建新的继续点，compact 延续原会话。
+
+## 独立能力
+
+- **`grill-me`**：无代码库、无本地文档写入的深入访谈。
+- **`prototype`**：用从一开始就可丢弃的小程序回答一个设计问题；保留答案，删除或隔离实验代码。
+- **`research`**：把阅读工作交给 background agent，以一手资料形成带引用的 Markdown artifact。研究为主流程提供材料，不代替后续判断。
+- **`teach`**：以指定目录为状态化工作区，跨会话学习一个主题。
+- **`writing-great-skills`**：创建、改写、本地化或评估 skills。
+- **`resolving-merge-conflicts`**：处理已经开始的 merge/rebase 冲突，不主动发起合并。
+
+## 路由与授权
+
+一次只选择一个主 skill；只有存在清楚的阶段关系时才说明后续链路。能通过安全只读检查得到的信息直接检查；缺失信息会实质改变范围、风险或写入目标时，一次只问一个最高价值问题。
+
+`ask` 本身只做路由。显式调用 `ask` 不等于授权下游写入。只有用户已经明确要求某项下游工作且目标唯一时，才可直接进入相应 skill；否则说明推荐 skill、理由和可能产生的动作，把选择权交还用户。

package/skills/ask/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Ask"
-  short_description: "根据任务目标、范围与风险选择最合适的 skill 和工作流入口"
-  default_prompt: "请使用 $ask 判断当前任务应进入哪个工作流，并只询问真正阻塞推进的信息。"
+  short_description: "为当前工程或产品任务选择唯一合适的主工作流与下一步"
+  default_prompt: "请使用 $ask 判断当前任务应进入哪个主工作流，并说明动作边界。"
 policy:
-  allow_implicit_invocation: true
+  allow_implicit_invocation: false

package/skills/code-review/SKILL.md

@@ -1,79 +1,95 @@
 ---
 name: code-review
-description: 当用户要求审查当前 diff、提交、PR 或一组文件，或 AI 完成中大型代码改动需要独立检查正确性、风险、测试和架构边界时使用。它默认只读并优先报告可执行缺陷；用户要求直接修复评论时改用实施流程。
+description: 当用户要求审查 branch、PR、工作树或相对某个固定点的变更时使用。它把 Standards 与 Spec 两条审查轴隔离执行并并列报告；默认只读，用户要求修复 finding 时转交实施流程。
 ---
 
 # Code Review
 
-代码审查首先寻找会导致错误、回归、安全问题、数据风险或维护边界破坏的具体缺陷。默认保持只读，不因审查请求直接修改文件。
+审查 `HEAD` 或工作树相对固定点的变化，并严格分成两条互不遮蔽的轴：
 
-## 确认范围
+- **Standards**：代码是否遵守仓库文档化规范和固定的 Fowler smell baseline。
+- **Spec**：代码是否忠实实现来源 issue、PRD、spec 或验收标准。
 
-1. 明确审查对象：工作树 diff、指定 commit、PR、文件或实现切片。
-2. 读取适用的仓库规则、规格、验收标准和测试说明。
-3. 检查完整变更及必要上下文，不只看单个片段。
-4. 区分本次改动与仓库原有问题；只有变更引入、暴露或必须阻止交付的问题才作为主要 finding。
+优先让两个相互隔离的只读子代理并行审查，再由主 agent 聚合。宿主不支持子代理时，串行执行两个隔离 pass，不把一条轴的结论带入另一条。
 
-## 审查顺序
+## 流程
 
-按风险优先检查：
+### 1. 固定比较点
 
-1. **正确性**：行为是否满足规格，边界、失败路径、状态转换和并发是否正确。
-2. **安全与数据**：认证授权、租户隔离、输入验证、密钥、注入、迁移和不可逆影响。
-3. **兼容与集成**：公共 API、schema、配置、版本、调用方和回退路径。
-4. **测试证据**：关键行为是否覆盖，测试是否会在实现错误时失败，验证命令是否真实执行。
-5. **架构边界**：所有权、依赖方向、重复规则和不必要复杂度。
-6. **可运维性**：错误信息、日志、指标、故障隔离和资源释放。
+用户给出的 commit、branch、tag 或 merge-base 就是 fixed point。未指定时询问；若用户明确要求审查当前未提交修改，则使用 `HEAD` 并同时包含 staged 与 unstaged diff。
 
-格式或个人偏好只有在违反项目规则、造成真实理解成本或隐藏缺陷时才报告。
+一次性记录并验证比较命令与 commit 列表：
 
-## 子代理协作
+```shell
+git rev-parse <fixed-point>
+git diff <fixed-point>...HEAD
+git log <fixed-point>..HEAD --oneline
+```
+
+工作树审查改用：
 
-只有宿主支持子代理、审查范围确实包含可独立检查的表面时才并行委派：
+```shell
+git diff HEAD
+git ls-files --others --exclude-standard
+```
 
-- 前端变更交给 `agent:frontend-reviewer`；
-- 后端、接口或数据变更交给 `agent:backend-reviewer`；
-- 跨模块边界和依赖方向交给 `agent:architecture-designer`；
-- 大量只读定位可先交给 `agent:code-reader`。
+`git diff HEAD` 已同时覆盖已跟踪文件的 staged 与 unstaged changes；第二条命令固定 untracked 集合。读取每个 untracked 文件的完整内容，并把它标记为新增文件输入两条审查轴。一个明确 diff 范围只输入一次：untracked 文件不得再从其他扫描重复加入；若改用互不重叠的 `git diff` 与 `git diff --cached HEAD`，也必须分别标记范围，不能重复输入 staged hunks。
 
-主 agent 必须先固定 diff 基点、规格和每个子代理的排他范围，等待结果后回到完整 diff 核验证据、去重并统一优先级。custom agent 不可用时，由主 agent 串行执行同一检查维度；小改动不要为并行而并行。审查子代理默认只读，任何 finding 的修复都返回实施流程，不能在并行审查中直接写代码。
+错误引用在启动子代理前直接报告。只有 tracked diff 与 untracked 集合都为空时，才把工作树范围判为空并停止。
 
-## Finding 标准
+### 2. 确定 Spec 来源
 
-每个 finding 必须包含：
+按顺序寻找：
 
-- 优先级：`P0` 阻断性事故，`P1` 高风险，`P2` 应修问题，`P3` 低风险改进；
-- 精确文件和尽可能小的行范围；
-- 哪种输入、状态或环境会触发；
-- 实际影响以及为何由本次变更造成；
-- 最小修复方向，不要求作者猜测意图。
+1. commit message、branch 或 PR 引用的 issue；
+2. 用户传入的路径、issue 编号或 URL；
+3. `docs/`、`specs/`、`.scratch/` 中与 branch 或功能匹配的规格；
+4. 当前对话中明确批准的验收标准。
 
-如果证据不足，先检查或提问，不把可能性写成确定缺陷。合并同一根因的重复评论。
+需要 tracker 内容时只读获取完整 body、comments 与相关链接。找不到时询问用户；若用户确认没有规格，则跳过 Spec 子代理并报告“没有可用规格”。
 
-## 输出格式
+### 3. 确定 Standards 来源
 
-先列 findings，按优先级排序；然后给出假设或未决问题；最后给出简短摘要和验证缺口。如果没有可执行 finding，明确写“未发现可执行问题”，但仍说明审查范围和剩余测试风险。
+读取适用的 `AGENTS.md`、`CONTRIBUTING.md`、编码规范、架构文档、ADR、安全与测试规则。仓库明确规则优先，自动化工具已可靠检查的内容不重复报告。
 
-```markdown
-### [P1] 标题
-- 位置：`path/to/file:line`
-- 触发：
-- 影响：
-- 建议：
-```
+此外，Standards 轴始终携带以下 smell baseline。每项都是 judgement call，不是硬违规：
+
+- **Mysterious Name**：名称没有揭示职责；重命名，若无法诚实命名则重新检查设计。
+- **Duplicated Code**：相同逻辑形状在多个 hunk 或文件中重复；提取共享形状。
+- **Feature Envy**：方法更多依赖其他对象的数据；把行为移向数据所有者。
+- **Data Clumps**：同组字段或参数持续一起出现；形成明确类型。
+- **Primitive Obsession**：primitive 或 string 代替稳定领域概念；建立小型领域类型。
+- **Repeated Switches**：同一类型的分支在多处重复；集中映射或使用合适的多态。
+- **Shotgun Surgery**：一次逻辑变化造成多处散点修改；把共同变化收拢。
+- **Divergent Change**：同一 Module 因多个无关原因变化；按变化原因拆分。
+- **Speculative Generality**：为规格没有提出的未来需求添加抽象、参数或 hook；删除到真实需求出现。
+- **Message Chains**：调用者依赖长导航链；由靠近入口的对象隐藏导航。
+- **Middle Man**：Module 大部分工作只是转发；删除无价值中间层。
+- **Refused Bequest**：继承者拒绝大部分继承契约；改用组合或更准确的抽象。
+
+### 4. 隔离执行两条轴
+
+Standards 子代理必须收到完整 diff 命令、commit 列表、全部规范来源和完整 smell baseline，并使用以下 brief：
+
+> 按文件或 hunk 报告：（a）diff 违反文档化规范的每一处，引用具体规范文件及规则；（b）发现的 baseline smell，点名 smell 并引用对应 hunk。区分 hard violation 与 judgement call：文档化规范可以是 hard violation，baseline smell 始终是 judgement call，且仓库规范覆盖 baseline。跳过工具已经强制检查的内容。少于 400 words。
+
+Spec 子代理必须收到完整 diff 命令、commit 列表和规格全文或 tracker 内容，并使用以下 brief：
+
+> 报告：（a）规格要求但缺失或只实现一部分的内容；（b）diff 中规格没有要求的行为，即 scope creep；（c）看似已实现、但实现行为不正确的要求。每条 finding 引用对应 spec 原文行。少于 400 words。
+
+两个 pass 不得相互审阅，也不得共同重新排序。
+
+### 5. 聚合
+
+在 `## Standards` 和 `## Spec` 下原样呈现或只做轻度文字清理。不要合并、跨轴重排或把 findings 改写成统一的优先级 schema。
+
+结尾只说明每条轴的 finding 数量及该轴最严重的问题；不要选跨轴“总冠军”。本 skill 默认只读；用户要求直接修复时，将 fixed point 和 findings 交给 `implement`。
 
-## 完成标准
+## 为什么必须分成两条轴
 
-- 审查覆盖了完整目标变更与必要上下文。
-- 每个 finding 都可复现、可定位且可执行。
-- 测试充分性和未验证风险被如实说明。
-- 没有用大量风格意见淹没真实风险。
+一条轴通过，不能抵消另一条失败：
 
-## 反模式
+- 完全遵守规范但实现了错误需求：**Standards pass，Spec fail**。
+- 完全实现 issue 但破坏项目约定：**Spec pass，Standards fail**。
 
-- 不要只总结代码而不判断风险。
-- 不要对未改动的历史问题进行无边界审计。
-- 不要报告静态工具已经可靠处理且没有额外影响的噪音。
-- 不要声称某测试通过，除非有实际运行证据。
-- 不要因作者是 AI 或人类而改变证据标准。
-- 不要无差别启动全部 specialist，造成重复评论和额外成本。
+分开报告可以防止一条轴掩盖另一条。

package/skills/code-review/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Code Review"
-  short_description: "基于正确性、风险、测试充分性以及架构边界审查代码变更"
-  default_prompt: "请使用 $code-review 审查当前变更，优先报告可执行的问题、证据和风险。"
+  short_description: "沿 Standards 与 Spec 两条隔离轴审查固定范围内的代码变更"
+  default_prompt: "请使用 $code-review 相对明确 fixed point 分别执行 Standards 与 Spec 审查。"
 policy:
   allow_implicit_invocation: true

package/skills/codebase-design/SKILL.md

@@ -1,78 +1,115 @@
 ---
 name: codebase-design
-description: 当新功能或重构需要确定模块边界、职责归属、依赖方向、公共接口、数据流和测试接缝时使用。它从行为与变更模式设计简单可演进的结构；单文件小改动或领域尚未澄清时不使用。
+description: 当用户要设计或改进模块接口、寻找 deepening 机会、决定 seam 放置、提高可测试性、让代码更容易被人和 AI 理解，或另一 skill 需要 deep-module vocabulary 时使用。它是 deep-module 设计的共享词汇与参考；单文件机械修改、领域语言尚未澄清或只需实现既定方案时不使用。
 ---
 
 # Codebase Design
 
-从要支持的行为和未来最可能发生的变更出发设计代码位置。目标是让相关变化聚在一起，让不相关变化彼此隔离，而不是追求最多层次或最通用抽象。
+设计 **deep Module**：把大量行为藏在小型 **Interface** 后，将 Interface 放在干净的 **Seam** 上，并通过该 Interface 测试。目标是为调用者提供 **Leverage**，为维护者提供 **Locality**，并让测试围绕稳定表面展开。
 
-## 设计前检查
+## 统一词汇
 
-1. 读取仓库规则、入口、目录结构、相邻实现、测试和依赖配置。
-2. 用具体场景列出要支持的行为、失败路径和非目标。
-3. 如果业务概念仍冲突，先调用 `domain-modeling`；如果关键技术能力未知，先调用 `research` 或 `prototype`。
-4. 识别现有约定。除非有可证明的收益，优先延续项目已经工作的结构。
+严格使用以下词汇，不用 component、service、API 或 boundary 随意替换。一致语言本身就是设计工具。
 
-跨模块设计且宿主支持 custom agents 时，可以先让 `agent:code-reader` 只读绘制现状调用链，再让 `agent:architecture-designer` 独立比较候选边界。主 agent 仍负责统一事实、选择方案和向用户暴露真实取舍；agent 不可用或范围较小时，直接串行执行以下步骤。
+**Module（模块）**：任何同时具有 Interface 与 Implementation 的东西。它刻意不限定尺度，可以是函数、类、package，也可以是跨层业务切片。
+_避免_：unit、component、service。
 
-## 设计步骤
+**Interface（接口）**：调用者为了正确使用 Module 必须知道的一切。除类型签名外，还包括不变量、调用顺序、错误模式、必要配置和性能特征。
+_避免_：API、signature；它们只表示类型层表面，范围过窄。
 
-### 1. 绘制变更地图
+**Implementation（实现）**：Module 内部的代码。它与 Adapter 不同：小型 Adapter 可以有大型 Implementation，例如 Postgres repository；大型 Adapter 也可以有小型 Implementation，例如 in-memory fake。讨论 Seam 上的角色时使用 Adapter，其他时候使用 Implementation。
 
-列出各类变化可能触及的职责，例如业务规则、持久化、外部集成、界面、授权和观测。经常一起变化的职责可相邻，不应一起变化的职责要有边界。
+**Depth（深度）**：Interface 提供的杠杆，即调用者或测试每学习一单位 Interface 能驱动多少行为。小 Interface 隐藏大量行为的是 deep Module；Interface 几乎与 Implementation 一样复杂的是 shallow Module。
 
-### 2. 分配所有权
+**Seam（接缝）**：无需在当前位置编辑代码就能改变行为的位置，也就是 Module 的 Interface 所在之处。Seam 放在哪里，与 Seam 后面放什么，是两个不同的设计决策。
+_避免_：boundary；它容易与 DDD bounded context 混淆。
 
-每项核心规则只指定一个权威位置。说明：
+**Adapter（适配器）**：在某个 Seam 上满足 Interface 的具体实现。它描述角色，而不是内部材料。
 
-- 哪个模块拥有状态和不变量；
-- 谁可以调用它；
-- 输入输出使用什么稳定契约；
-- 错误如何跨边界表达；
-- 哪些细节必须保持私有。
+**Leverage（杠杆）**：调用者从 Depth 获得的收益。一份实现可以服务 N 个调用点与 M 个测试。
 
-### 3. 校验依赖方向
+**Locality（局部性）**：维护者从 Depth 获得的收益。变更、缺陷、知识和验证集中在一处；修复一次，所有调用者同时受益。
 
-依赖应指向更稳定、更接近业务规则的边界。框架、数据库和外部服务细节通过窄接口进入，不让领域规则依赖具体传输或存储形式。
+## Deep 与 shallow
 
-### 4. 设计测试接缝
+Deep Module = 小 Interface + 大量 Implementation：
 
-明确哪些行为由单元测试、集成测试、契约测试或端到端测试验证。接缝应来自真实边界，不为 mock 而制造层次。
+```text
+┌─────────────────────┐
+│   Small Interface   │  ← 方法少、参数简单
+├─────────────────────┤
+│                     │
+│ Deep Implementation │  ← 复杂行为被隐藏
+│                     │
+└─────────────────────┘
+```
+
+Shallow Module = 大 Interface + 少量 Implementation，应尽量避免：
 
-### 5. 对比替代方案
+```text
+┌─────────────────────────────────┐
+│       Large Interface           │  ← 方法多、参数复杂
+├─────────────────────────────────┤
+│      Thin Implementation        │  ← 主要负责透传
+└─────────────────────────────────┘
+```
 
-至少记录一个更简单方案和一个主要替代方案。用当前需求、认知负担、迁移成本、故障隔离和可逆性解释选择。
+设计 Interface 时持续追问：
 
-## 输出格式
+- 能否减少方法数量？
+- 能否简化参数？
+- 能否把更多复杂性藏进 Implementation？
 
-```markdown
-## 设计摘要
-- 行为与非目标：
-- 模块与职责：
-- 依赖方向：
-- 数据与控制流：
-- 公共契约：
-- 错误与失败边界：
-- 测试策略：
-- 替代方案与取舍：
-- 迁移步骤与回退：
-```
+## 原则
+
+- **Depth 是 Interface 的性质，不是 Implementation 的大小。** Deep Module 内部仍可由小型、可替换部分组成，只是它们不应泄漏到外部 Interface。Module 可以同时拥有内部测试 seams 与对调用者开放的 external Seam。
+- **Deletion test。** 想象删除这个 Module：如果复杂性随之消失，它只是透传层；如果复杂性重新散落到 N 个调用者，它就在提供价值。
+- **Interface 就是 test surface。** 调用者和测试跨越同一个 Seam。若测试必须绕过 Interface 进入内部，Module 的形状很可能不对。
+- **一个 Adapter 代表假想 Seam，两个 Adapter 才代表真实 Seam。** 除非确有变化需要隔离，不为可能的未来需求预建 Seam。
+
+## 为可测试性设计
+
+1. **接收依赖，不在内部创建依赖。**
+
+   ```ts
+   // 易测试
+   function processOrder(order, paymentGateway) {}
+
+   // 难测试
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **返回结果，不用隐式副作用表达结果。**
+
+   ```ts
+   // 易测试
+   function calculateDiscount(cart): Discount {}
+
+   // 难测试
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **保持小型表面。** 方法越少，需要覆盖的行为组合越少；参数越少，测试准备越简单。
+
+## 关系
 
-复杂关系可以补充一张最小的流程图或依赖图；简单结构用表格或文字即可。
+- 一个 Module 对调用者和测试呈现一个 Interface。
+- Depth 是 Module 相对于 Interface 的性质。
+- Seam 是 Module 的 Interface 所在位置。
+- Adapter 位于 Seam 上并满足 Interface。
+- Depth 为调用者产生 Leverage，为维护者产生 Locality。
 
-## 完成标准
+## 不采用的表述
 
-- 每个关键行为和业务规则都有唯一、合理的归属。
-- 依赖方向、公共契约和失败边界清楚。
-- 设计与现有仓库约定兼容，或明确说明偏离理由。
-- 可以拆成小步、可验证、可回滚的实现切片。
+- 不用“Implementation 行数 / Interface 行数”定义 Depth；它会奖励臃肿实现。这里采用 depth-as-leverage。
+- 不把 Interface 缩窄为语言中的 `interface` 关键字或类的 public methods。
+- 不用 boundary 表示 Seam，以免与 bounded context 混淆。
 
-## 反模式
+## 进一步深入
 
-- 不要为想象中的未来需求提前建立平台。
-- 不要按技术层机械拆分所有功能而忽略业务内聚。
-- 不要用共享工具模块掩盖所有权不清。
-- 不要在没有行为证据时引入新的框架或生产依赖。
-- 不要把目录树本身当作完整设计。
-- 不要把 `agent:architecture-designer` 的建议未经核验直接升级为架构决策或 ADR。
+- 依赖分类、Seam discipline 和 replace-don’t-layer 测试策略见 [deepening.md](references/deepening.md)。
+- 需要以彼此独立的方案探索 Interface 时见 [design-it-twice.md](references/design-it-twice.md)。

package/skills/codebase-design/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Codebase Design"
-  short_description: "从行为、职责与依赖出发设计清晰、简单且可演进的代码结构"
-  default_prompt: "请使用 $codebase-design 为当前需求设计模块边界、依赖方向和代码放置方案。"
+  short_description: "提供 deep Module、Interface、Seam、Adapter、Leverage 与 Locality 的共享词汇"
+  default_prompt: "请使用 $codebase-design 以统一的 deep Module 词汇分析当前 Interface、Seam 与依赖形状。"
 policy:
   allow_implicit_invocation: true