@netpilot/skills 0.3.2 → 0.6.0

package/skills/domain-modeling/references/domain-docs.md

@@ -0,0 +1,53 @@
+# 领域文档约定
+
+工程 skills 探索代码库时，按以下方式使用领域文档。
+
+## 探索前读取
+
+- 根目录的 `CONTEXT.md`；或
+- 根目录存在 `CONTEXT-MAP.md` 时，读取它指向且与当前主题相关的各个 `CONTEXT.md`；
+- `docs/adr/` 中影响当前区域的 ADR；多 context 仓库还要查看对应 `src/<context>/docs/adr/`。
+
+任一文件不存在时安静继续，不把缺失本身当作问题，也不提前建议建立空骨架。`domain-modeling` 只在术语或 decision 真正形成时按需创建它们。
+
+## 文件结构
+
+单 context 仓库：
+
+```text
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+根目录存在 `CONTEXT-MAP.md` 时：
+
+```text
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← 系统级 decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## 使用 glossary 的词汇
+
+Issue title、refactor proposal、hypothesis、test name 和文档正文涉及领域概念时，使用 `CONTEXT.md` 定义的 canonical term，不漂移到 glossary 明确排除的同义词。
+
+需要的概念尚未进入 glossary 时，把它视为信号：要么正在发明项目不用的语言，应重新检查；要么确有领域缺口，应交给 `domain-modeling` 收敛。
+
+## 显式指出 ADR 冲突
+
+产物与现有 ADR 冲突时，不得静默覆盖。明确指出：
+
+> 与 ADR-0007（event-sourced orders）冲突；建议重新打开该 decision，因为……
+
+事实、当前建议和是否要 supersede ADR 必须分开表达。

package/skills/grill-me/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: grill-me
+description: 对计划、设计、决策或想法开展一次毫不松懈的逐题访谈，直到关键分支形成共同理解。
+disable-model-invocation: true
+---
+
+# Grill Me
+
+运行 `$grilling`，以用户当前提供的计划、设计、决策或想法为访谈对象。
+
+`grill-me` 只是显式用户入口；访谈方法、问题顺序和停止判断全部由 `$grilling` 负责。
+
+`grill-me` 是 **stateless**：可以只读查明事实，但不创建或修改任何本地或远程 artifact，包括项目文件、临时交接文件、Git、tracker 或外部状态。唯一产物是当前对话中被磨清的共同理解。如果用户希望在访谈过程中同步维护 `CONTEXT.md`、领域术语或 ADR，说明差异并建议用户显式改用 `$grill-with-docs`，不要在本入口中静默切换为写入模式。

package/skills/grill-me/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Grill Me"
+  short_description: "对计划、设计或决策开展逐题压力测试，直到形成共同理解"
+  default_prompt: "请使用 $grill-me 对这个计划或设计逐题深入访谈，并为每个决策给出推荐答案。"
+policy:
+  allow_implicit_invocation: false

package/skills/grill-with-docs/SKILL.md

@@ -1,75 +1,28 @@
 ---
 name: grill-with-docs
-description: 当用户明确要求在深入访谈中同步维护当前仓库的 CONTEXT.md、领域术语文档或 ADR 时使用。它组合 grilling 与 domain-modeling，把已确认的语言和重要决策最小化沉淀；仅需访谈、仅需建模、没有项目仓库或尚未授权文档写入时不使用。
+description: 对计划或设计开展毫不松懈的逐题访谈，并在决定形成时同步维护项目领域文档与重要决策。
+disable-model-invocation: true
 ---
 
 # Grill With Docs
 
-`grill-with-docs` 是带项目文档沉淀的访谈入口。它不实现第二套访谈算法，也不取代 `domain-modeling`；它只负责让两者在一个有明确写入边界的会话中协作。
+运行 `$grilling`，并在同一会话中使用 `$domain-modeling`。`$grilling` 负责沿决策树一次一题形成共同理解；`$domain-modeling` 负责把刚刚确认的领域语言和长期重要决定沉淀到正确文档。两者保持各自职责，不复制流程。
 
-## 使用边界
+## 写入边界
 
-- 用户显式调用本 skill，或明确要求“边访谈边更新术语表、CONTEXT 或 ADR”时启动。
-- 用户只要求深入盘问、没有要求留下项目文档时，改用 `grill`。
-- 没有项目仓库、当前讨论尚未形成稳定知识，或目标只是编辑普通说明文档时，不使用本 skill。
-- 由 `ask` 或模型隐式推荐、但用户原始要求没有文档写入意图时，先保持只读，并在首次写入前确认目标文件与范围。
+用户显式调用本 skill，表示授权在当前项目内对相关 `CONTEXT.md`、术语文档和 ADR 做最小必要更新。先读取仓库规则和现有文档布局；目标仓库或文档位置不明确时，先确认一次范围。
 
-用户显式调用 `$grill-with-docs`，可视为授权在当前仓库内最小化更新相关领域文档；这不授权修改代码、系统级目录、提交、推送、创建 PR 或写入远程系统。
+这项授权不包括业务代码、项目配置、Git 分支或提交、宿主设置、issue tracker 及其他远程系统。访谈不需要留下项目文档时，应由用户显式改用 `$grill-me`。
 
-## 启动流程
+## 组合循环
 
-1. 读取项目规则、当前计划或设计、相关代码、已有 `CONTEXT-MAP.md`、`CONTEXT.md` 和 ADR。能通过只读检查确认的事实不要询问用户。
-2. 说明本次访谈的决策对象、预计维护的文档和明确不在范围内的文件。写入意图不明确时，只问一个范围问题。
-3. 判断当前主题属于哪个领域上下文。已有 `CONTEXT-MAP.md` 时遵循其映射；归属不清时先确认，不凭目录结构猜测。
-4. 启动 `grilling` 的逐题循环，同时应用 `domain-modeling` 的术语、边界、不变量和文档判断规则。
+1. 读取当前计划或设计、相关项目规则、已有 `CONTEXT.md`、上下文映射和 ADR。可以查明的事实直接查明。
+2. 让 `$grilling` 选择并提出当前唯一的问题，给出推荐答案并等待用户决定。
+3. 决定形成后，让 `$domain-modeling` 判断它是否属于稳定领域语言或值得长期保留的架构决策：
+   - 已确认的主术语、紧凑定义、上下文边界和不变量，最小化更新到相应 `CONTEXT.md`；
+   - 改变成本高、缺少背景会令人意外且存在真实替代方案的决定，按仓库既有格式创建、更新或 supersede ADR；
+   - 假设、临时偏好、普通实现细节和未决问题保留在访谈状态中，不写成项目事实。
+4. 文档处理完成后把控制权交回当前 `$grilling` 循环，再进入下一个决策分支。不要递归启动新的访谈。
+5. 用户确认形成共同理解后，报告已确认结论、实际修改的文档、未写入的假设与未决项，以及适合的下一入口。
 
-## Skill 组合关系
-
-- `grilling` 是唯一访谈引擎：Codex 使用 `$grilling`；Claude Code 用户级安装使用 `/grilling`，插件安装使用 `/netpilot-skills:grilling`。
-- `domain-modeling` 是唯一领域文档能力：Codex 使用 `$domain-modeling`；Claude Code 用户级安装使用 `/domain-modeling`，插件安装使用 `/netpilot-skills:domain-modeling`。
-- 每个答案完成建模和必要的最小文档更新后，控制权回到当前 `grilling` 循环，再选择下一题。
-- 不再调用 `grill`，也不允许 `domain-modeling` 在已有活跃访谈时重新启动 `grilling`，避免双重访谈和循环调用。
-
-## 访谈与沉淀循环
-
-1. 由 `grilling` 选择当前最可能改变范围、模型或风险的一个问题。
-2. 将回答区分为事实、已确认决策、待验证假设和未决问题。
-3. 用现有术语表、ADR 和代码交叉检查回答。发现冲突时展示证据并让用户裁决，不静默覆盖项目事实。
-4. 术语已确认、所属上下文明确且属于领域语言时，立即对相应 `CONTEXT.md` 做最小更新；不要把多个结论积压到会话结束。
-5. 决策可能值得长期保留时，先检查 ADR 门禁。只有同时满足以下三项才提出创建或更新 ADR，并等待用户确认：
-   - 后续改变成本明显，难以轻易回退；
-   - 缺少背景时，未来维护者会对当前选择感到意外；
-   - 存在真实替代方案，并基于具体取舍选择了其中一个。
-6. 假设、临时偏好、容易撤销的实现细节和普通库选择只留在访谈记录中，不写成项目事实。
-7. 继续下一题，直到剩余未知项不再阻塞下一阶段，或必须转入 `research`、`prototype` 才能回答。
-
-## 文档规则
-
-- `CONTEXT.md` 只保存项目特有的领域语言：主名称、紧凑定义、所属上下文和应避免的别名。不得写实现细节、规格草稿、任务清单或未验证假设。
-- 单上下文项目在第一个稳定术语出现时才懒创建根目录 `CONTEXT.md`。多上下文项目遵循已有 `CONTEXT-MAP.md` 和各上下文位置；不要为了本次会话擅自重组文档体系。
-- ADR 遵循仓库现有目录、编号和格式。已有相同决策时优先更新、废弃或建立 supersede 关系，不重复创建。
-- 文档改动保持最小，并在每次写入后检查其是否准确表达刚刚确认的结论。
-
-## 结束产物
-
-会话结束时输出：
-
-- 已确认的领域术语、边界和重要决策；
-- 实际修改的文档及每项修改原因；
-- 未写入文档的假设和未决问题；
-- 建议进入的下一 skill，通常是 `to-spec`、`research` 或 `prototype`。
-
-## 完成标准
-
-- 访谈由 `grilling` 逐题推进，没有复制另一套提问循环。
-- 已确认术语与现有模型、代码和文档的冲突得到裁决。
-- `CONTEXT.md` 只包含稳定领域语言，ADR 全部满足门禁并获得确认。
-- 文档写入范围、实际改动和未决项均已明确报告。
-
-## 反模式
-
-- 不要因为仓库里存在 `CONTEXT.md` 就自动触发本 skill。
-- 不要把每个回答都写进文档，或把 `CONTEXT.md` 变成会议纪要。
-- 不要为容易撤销、没有替代方案或显而易见的选择创建 ADR。
-- 不要在同一会话中递归启动 `grill`、第二个 `grilling` 或另一个 `grill-with-docs`。
-- 不要把显式文档写入授权扩展成代码修改或远程发布授权。
+更新应随着决定形成而发生，不把所有结论积压到会话末尾。发现新回答与现有代码或文档冲突时，展示证据并让用户裁决，不静默覆盖。

package/skills/grill-with-docs/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Grill With Docs"
-  short_description: "在逐题访谈中收敛领域术语，并按门禁更新 CONTEXT.md 与 ADR"
-  default_prompt: "请使用 $grill-with-docs 深入检验这个方案，并把已确认术语与关键决策沉淀到项目文档。"
+  short_description: "逐题挑战计划或设计，同时维护 CONTEXT 与必要 ADR"
+  default_prompt: "请使用 $grill-with-docs 深入检验这个方案，并同步维护已确认的领域术语与重要决策。"
 policy:
-  allow_implicit_invocation: true
+  allow_implicit_invocation: false

package/skills/grilling/SKILL.md

@@ -1,66 +1,22 @@
 ---
 name: grilling
-description: 当另一项 skill 需要通过自适应、一次一个问题的访谈来消除需求歧义，确认边界、约束、取舍和验收标准时使用。它是可复用的内部访谈引擎；不要作为普通问答、头脑风暴或简单任务的默认入口。
+description: 当用户要压力测试一项计划、决策或想法，使用 grill 类触发语，或另一 skill 需要一次一题走完决策树时使用。它负责形成共同理解；普通问答、开放式头脑风暴或已经明确的执行任务不使用。
 ---
 
 # Grilling
 
-通过高信息密度的逐题访谈，把“听起来合理”推进到“决策足以执行”。语气应直接、尊重并保持合作。
+对计划、决策或想法的每个重要方面进行毫不松懈的访谈，直到双方形成共同理解。沿决策树逐个分支推进；先解决上游依赖，再进入依赖它的决定。
 
 ## 访谈循环
 
-1. **建立状态**：整理已知事实、假设、决策、未知项和矛盾。优先读取现有资料。
-2. **选择问题**：挑选当前最可能改变范围、方案或风险的一个未知项。
-3. **提出一题**：一次只问一个问题。适合时给出 2 至 3 个互斥选项，说明推荐项和主要取舍；不要限制用户自由回答。
-4. **检验答案**：把回答转成明确决策，并检查它是否与先前答案冲突、是否留下模糊词或不可验证目标。
-5. **自适应推进**：根据新信息选择下一题，而不是照搬固定清单。
-6. **停止**：当剩余未知项不会阻塞下一阶段，或必须依赖研究、原型、外部权限才能解决时，结束访谈。
+1. 从当前对话、用户提供的材料和可用环境中建立决策树。区分已知事实、暂定假设、用户已经作出的决定和仍开放的分支。
+2. 选择当前最可能改变范围、方案或风险的一个开放分支。
+3. 一次只问一个问题，并等待用户回答后再继续。每个问题都给出你的推荐答案及最关键的理由或取舍；推荐不是替用户作决定。
+4. 检查回答是否解决了该分支，是否与较早决定冲突，以及是否暴露了新的上游依赖。必要时先处理新依赖，再回到原分支。
+5. 更新决策树并继续，直到每个重要分支都已解决、明确 deferred，或经用户确认为 out of scope。需要研究、原型、外部权限或未来信息时，把访谈标记为暂停/阻塞并返回所需证据；不能把这些未决分支当作已经形成 shared understanding。
 
-## 提问原则
+如果一个事实可以通过文件系统、代码、文档或可用工具查明，先自行查明并把证据带回问题中，不要把检索工作转嫁给用户。决定属于用户：即使你有强烈推荐，也要把选择交给用户并等待回答。
 
-- 先问影响最大的分叉，不先问装饰性偏好。
-- 将“快速”“灵活”“企业级”“体验好”等词转成可观察的标准。
-- 发现隐含前提时明确指出，并询问前提不成立时的处理方式。
-- 对高成本、不可逆、安全或数据相关决策，要求说明失败路径和回滚方式。
-- 用户说“不确定”时，提供最小研究或原型建议，不施压猜答案。
-- 能通过只读检查确认的事实，直接检查并展示证据。
+除只读查明事实外，在用户明确确认双方已经形成共同理解前，不基于方案执行任何写入或外部动作，包括实施、建 issue、写 spec、改 tracker 状态或创建 artifact。`grill-with-docs` 是显式 wrapper：它只在每个具体决定已经由用户确认后，按自身授权即时沉淀文档。
 
-## 状态记录
-
-在内部维护以下列表，必要时向用户回顾：
-
-- `Facts`：已有证据支持的事实；
-- `Decisions`：用户已确认的选择；
-- `Assumptions`：暂时采用、仍需验证的前提；
-- `Open questions`：尚未解决的问题；
-- `Risks`：失败影响与缓解方式。
-
-不要在每轮都重复完整列表；只在发生冲突、阶段转换或访谈结束时汇总。
-
-## 结束格式
-
-```markdown
-## 访谈结论
-- 目标：
-- 范围内：
-- 范围外：
-- 关键决策：
-- 验收标准：
-- 待验证假设：
-- 剩余风险：
-- 建议下一步：
-```
-
-## 完成标准
-
-- 目标、范围、关键约束和验收方式足以支持下一阶段。
-- 决策、假设和事实没有混写。
-- 未决项都有明确的验证方式或负责人。
-
-## 反模式
-
-- 不要并排发送多题或隐藏问题清单。
-- 不要问已经能从资料中得到答案的问题。
-- 不要为了显得深入而无止境追问。
-- 不要在访谈中直接实施未批准的方案。
-- 不要把自己的偏好包装成用户已经作出的决定。
+用户确认后才结束访谈并把结果交回调用方。若由另一 skill 调用，返回已确认决定、仍未解决的分支及所需证据，由调用方决定产物格式和下一步；不要夺取调用方的工作流。

package/skills/grilling/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Grilling"
-  short_description: "通过自适应追问消除需求歧义并确认边界、约束与验收标准"
-  default_prompt: "请使用 $grilling 逐题澄清当前需求，直到关键决策和验收标准都明确。"
+  short_description: "沿决策树一次一题深入访谈，并为每个分支给出推荐答案"
+  default_prompt: "请使用 $grilling 沿决策树一次只问一个问题，并为每个问题给出推荐答案。"
 policy:
   allow_implicit_invocation: true

package/skills/handoff/SKILL.md

@@ -1,72 +1,54 @@
 ---
 name: handoff
-description: 当工作需要跨会话、上下文压缩、工具切换、agent 切换或交给人工继续，且必须保留可靠恢复点时使用。它汇总目标、状态、证据、改动和下一步；普通阶段性进度更新或已经完整结束的任务不使用。
+description: 把当前会话压缩成一份可由另一 agent 直接继续执行的交接文档。
+argument-hint: "下一次会话将用于什么？"
+disable-model-invocation: true
 ---
 
 # Handoff
 
-生成一份接手者无需重做调查即可继续工作的交接包。它应记录事实和证据，而不是复述整段对话。
+为新的 agent 编写一份交接文档，使其可以继续当前工作而不必重做核心调查。把文档保存到用户操作系统的临时目录，而不是当前工作区；使用不会覆盖既有文件的名称，例如 `handoff-<timestamp>.md`。
+
+如果用户传入参数，把它当作下一次会话的重点，并据此选择信息和安排下一步。
 
 ## 收集状态
 
-在交接前进行只读检查：
+在写入前只读检查：
 
 - 当前目标、范围和完成标准；
-- 已确认的决策、约束和项目规则；
+- 已确认的决定、约束和项目规则；
 - 已完成、进行中、未开始和被阻塞的工作；
-- 当前分支、工作树状态和本任务涉及文件；
-- 实际运行过的命令、测试与结果；
+- 当前分支、工作树状态和本任务涉及的文件；
+- 实际运行过的命令、测试及其结果；
 - 关键日志、错误、复现步骤和证据位置；
-- 仍未解决的问题、风险与所需授权。
+- 剩余未知项、风险、所需权限和第一条可执行动作。
+
+不要把计划中的动作写成已经执行，也不要遗漏用户原有的未提交改动。
 
-不要把计划中的命令写成已经执行，不要遗漏用户已有的未提交改动。
+## 交接文档
 
-## 交接格式
+使用与任务相称的紧凑结构。只强制保留“下一会话重点”“当前状态”“下一步”和 `Suggested Skills`；其余章节有内容时才加入，空白或不适用章节直接省略：
 
-```markdown
+```md
 # 工作交接
 
+## 下一会话重点
 ## 目标与完成标准
 ## 当前状态
-- 已完成：
-- 进行中：
-- 未开始：
-- 阻塞项：
-
-## 关键决策与约束
-## 相关文件与改动
+## 关键决定与约束
+## 相关文件、提交与外部资料
 ## 验证证据
-| 命令/检查 | 结果 | 说明 |
-
 ## 已排除的路径
 ## 剩余风险与未知项
 ## 下一步
-1. 第一条可直接执行的动作
-2. 后续动作
-
+## Suggested Skills
 ## 恢复提示
 ```
 
-`恢复提示` 应包含接手者必须读取的文件、第一条命令和禁止重复或覆盖的工作。路径、分支、版本和错误信息应精确。
-
-## 安全与体积
-
-- 不记录密钥、token、个人数据或完整敏感日志；使用安全位置的引用。
-- 不粘贴可从文件读取的大段内容，提供路径和关键行即可。
-- 若工作树含用户改动，明确标记归属和重叠风险。
-- 交接本身不授权 commit、push、部署或外部写入。
-
-## 完成标准
+`Suggested Skills` 列出下一位 agent 应由用户显式调用或可按需使用的 skills，并说明每一个的触发条件。需要时用 `恢复提示` 给出必须先读的文件、第一条命令和不能覆盖或重复的工作。
 
-- 新接手者能从一条明确动作继续，而无需重新探索核心上下文。
-- 已执行事实、计划和推断清楚分开。
-- 文件、命令、验证结果和阻塞条件可定位。
-- 敏感信息未进入交接内容。
+已有规格、计划、ADR、issues、commits、diffs 或报告已经保存的信息不要复制进交接文档；用准确路径或 URL 引用它们，只摘录继续工作必需的最小结论。
 
-## 反模式
+删除 API keys、密码、tokens、个人身份信息和完整敏感日志。路径、分支、版本、错误和验证结果应保持精确；事实、推断和计划应明确区分。
 
-- 不要只写“继续完成剩余工作”。
-- 不要粘贴完整聊天记录代替提炼。
-- 不要虚构测试、提交或远程状态。
-- 不要遗漏失败尝试及其教训，导致接手者重复踩坑。
-- 不要在任务已完全结束时制造无意义交接文档。
+写入成功后返回交接文档的绝对路径，并说明下一会话应从哪一步开始。创建临时交接文档不授权修改工作区、Git 状态或远程系统。

package/skills/handoff/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Handoff"
-  short_description: "为跨会话、跨工具或人工接手生成完整、可恢复的工作交接包"
-  default_prompt: "请使用 $handoff 总结当前状态、证据、未决事项和下一步，生成可直接继续的交接包。"
+  short_description: "把当前会话压缩为可供另一 agent 直接接手的临时交接文档"
+  default_prompt: "请使用 $handoff 把当前状态、证据、决定与下一步写成可直接接手的临时交接文档。"
 policy:
-  allow_implicit_invocation: true
+  allow_implicit_invocation: false

package/skills/implement/SKILL.md

@@ -1,68 +1,31 @@
 ---
 name: implement
-description: 当用户已经提供或批准了明确规格、任务边界与验收标准，并要求实际修改代码或项目文件时使用。它按小切片实施、持续验证并报告偏差；探索、只读分析、根因未知的 bug 或尚未批准的设计不使用。
+description: 当用户已经提供或批准明确的 spec、ticket 或任务边界，并要求实际修改代码或项目文件时使用。它按小型垂直切片实施、持续验证、双轴审查并在授权范围内提交；探索、只读分析、根因未知的故障或尚未批准的设计不使用。
+disable-model-invocation: true
 ---
 
 # Implement
 
-按已确认的范围交付最小、正确、可验证的改动。实施不是重新发明规格；发现重大偏差时停止并让决策回到用户。
+实施用户在 spec 或 tickets 中描述的工作。
 
-## 开始前
+## 动作授权
 
-1. 读取仓库规则、规格、当前任务、相邻实现和测试命令。
-2. 检查工作树，区分用户已有改动与本任务范围。保留无关改动，重叠且无法安全处理时报告。
-3. 确认验收标准和允许的写入范围。认证、权限、支付、数据迁移、部署、安全等高风险内容必须先有计划。
-4. 若行为或架构仍有关键歧义，返回 `to-spec` 或 `codebase-design`；若 bug 根因未知，先用 `diagnosing-bugs`。
+用户显式调用 `implement`，且仓库、工作项与目标分支唯一时，可以在执行前用一句话预告后自动：
 
-## 实施循环
+- 创建或切换本地工作分支；
+- 修改范围内文件并运行验证；
+- 创建逻辑清楚的 commit；
+- 更新明确 tracker item 的状态，并在验收证据充分后关闭任务。
 
-对每个最小垂直切片：
+目标不唯一、用户只要求分析、工作项范围与当前 diff 冲突，或需要写入未提及的远程对象时，先展示目标与计划。永不自动 push、创建 PR、merge、deploy 或发布。
 
-1. 说明当前要实现的可观察结果。
-2. 适用时调用 `tdd`，先建立可信失败测试。
-3. 只修改实现该结果必须修改的文件，不做无关重构。
-4. 运行最小定向验证，确认失败或通过的原因符合预期。
-5. 在绿色状态整理局部结构，再运行受影响范围验证。
-6. 检查 diff，确认没有意外文件、调试代码、敏感信息或范围漂移。
-7. 更新任务状态并进入下一切片。
+## 实施
 
-优先使用仓库现有依赖和模式。新增生产依赖前说明必要性、替代方案、维护与安全影响，并获得用户同意。
+1. 从已批准的 spec、ticket 或验收标准开始；范围仍有关键歧义时返回 `ask`、`grilling` 或 `to-spec`，不要自行扩展需求。
+2. 在适用且存在可观察行为时，在预先确认的 seams 上使用 `tdd`，一次完成一个 test → minimal implementation 的垂直切片。纯文档、机械配置或没有可测试行为的改动不适用时记录原因，并执行与风险相称的定向验证。结构整理留到完整 diff 可见后的审查阶段。
+3. 定期运行 typecheck 和单个相关测试文件，使失败靠近引入它的切片。
+4. 所有切片完成后，仓库存在完整测试套件时运行一次。无法运行时如实记录原因与剩余风险，不能把未运行写成通过。
+5. 使用 `code-review` 对同一 fixed point 做 Standards + Spec 双轴审查。修复确认的问题后，重跑受影响验证。
+6. 检查最终 diff 只包含当前任务。按动作授权 commit，并在证据支持时更新 tracker 状态或关闭明确任务。
 
-## 偏差处理
-
-可以自行处理不改变目标的局部实现细节。以下情况必须暂停并说明证据、影响与选项：
-
-- 规格与现有系统事实冲突；
-- 需要改变公共 API、schema、权限、数据或部署策略；
-- 必须扩大范围或引入新生产依赖；
-- 验收标准无法在当前环境验证；
-- 用户已有改动与任务目标直接冲突。
-
-不要悄悄把推断升级为新需求。
-
-## 外部操作
-
-本 skill 不默认执行 commit、push、创建 PR、部署、发布、合并、关闭远程 issue 或修改外部系统。只有用户明确授权相应动作后才执行；授权实施代码不等于授权这些外部操作。
-
-## 交付检查
-
-- 运行与风险成比例的定向测试、类型检查、构建或端到端验证。
-- 宿主提供 `agent:test-verifier` 且验证命令边界清楚时，可以委派它执行现有检查并压缩日志；主 agent 必须核对实际命令、退出码和工作树，不能把子代理摘要本身当成通过证据。
-- 调用 `code-review` 对中大型改动进行独立审查；轻量改动至少自查 diff。
-- 如实记录未运行或失败的验证及原因，不用“应该通过”替代证据。
-- 说明改动摘要、关键文件、设计取舍、验证结果和剩余风险。
-
-## 完成标准
-
-- 所有已批准验收标准都有实现与验证证据。
-- 改动限于任务所需范围，用户已有工作被保留。
-- 没有未解释的测试失败、意外文件或隐藏偏差。
-- 外部可见动作只在明确授权范围内执行。
-
-## 反模式
-
-- 不要在规格仍模糊时边写边替用户做重大决策。
-- 不要为了顺手优化而扩大重构。
-- 不要删除测试、弱化断言或绕过检查来获得绿色结果。
-- 不要把未执行的验证报告为通过。
-- 不要默认提交、推送或关闭任务。
+规格与真实代码约束冲突时停止扩展实现：记录证据、受影响验收标准和最小决策点，把控制权交还用户。

package/skills/implement/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Implement"
-  short_description: "按已确认规格和任务边界实现功能，并持续验证和报告偏差"
-  default_prompt: "请使用 $implement 按当前规格实施任务，持续验证，并在偏离规格前先报告。"
+  short_description: "按明确规格垂直切片实施、持续验证、独立审查并提交结果"
+  default_prompt: "请使用 $implement 按已确认规格实施当前 work item，并完成测试、审查与受控提交。"
 policy:
-  allow_implicit_invocation: true
+  allow_implicit_invocation: false

package/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: improve-codebase-architecture
+description: 扫描代码库中的架构摩擦、浅模块与缺失测试 seam，并用可视化 HTML 报告选择 deepening opportunity。
+disable-model-invocation: true
+---
+
+# Improve Codebase Architecture
+
+发现 architectural friction，并提出把 shallow module 深化为 deep module 的机会。目标是提高 testability、locality、leverage 和 agent navigability。
+
+先调用 `$codebase-design` 获取 Module、Interface、Implementation、Depth、Seam、Adapter、Leverage、Locality、deletion test 与 design-it-twice 的准确含义。领域名称来自 `CONTEXT.md`，已有约束来自 ADR。
+
+## 动作门禁
+
+用户显式调用且扫描范围明确时，可以自动：
+
+- 只读扫描代码库与 Git 历史；
+- 在操作系统临时目录创建 HTML report；
+- 打开报告供用户查看；
+- 用户选择候选项后，在其明确允许的仓库范围内调用访谈与领域建模流程。
+
+范围不明时，先展示拟扫描范围、数据来源和报告动作，等待确认。
+
+本 skill 不自动实施重构，也不自动 commit、push、PR、merge 或 deploy。
+
+## 选择扫描范围
+
+**YAGNI**：Deepening 的收益来自降低未来变化成本，因此扫描前先决定去哪里看，不把全仓库所有可想象的重构都列成候选：
+
+- 用户指定 Module、subsystem 或 pain point 时直接采用；
+- 否则查看一段有代表性的 Git history，找反复变化的 hot spots；
+- 变化分散且没有热点时再扩大范围。
+
+先读领域 glossary 和相关 ADR。
+
+使用只读代码探索，按真实理解摩擦有机寻找：
+
+- 理解一个概念是否需要在许多小 Module 之间跳转；
+- Module 是否 shallow：Interface 几乎和 Implementation 一样复杂；
+- 是否为测试而抽出 pure function，但真正 bug 藏在调用方式里，缺少 Locality；
+- 紧耦合 Module 是否通过 Seam 泄漏；
+- 哪些行为无法通过当前 Interface 可靠测试；
+- 一个变化是否造成 shotgun surgery；
+- Adapter 是否只为假想未来存在。
+
+对每个候选项执行 deletion test：删除该 Module 会让复杂性集中到一个清楚位置，还是只把代码搬到别处？只有前者才是可信 deepening signal。
+
+## 生成 HTML report
+
+把单文件报告写入操作系统临时目录：
+
+- 优先系统 temp API；
+- Unix 可使用 `$TMPDIR`，回退到 `/tmp`；
+- Windows 使用 `%TEMP%`；
+- 文件名为 `architecture-review-<timestamp>.html`。
+
+显式调用时创建后自动打开，并报告绝对路径。报告不得写入仓库。
+
+读取 [HTML report reference](references/html-report.md)，严格遵循其中的 scaffold、visual patterns 与 wording。
+
+每个候选 card 包含：
+
+- Files / Modules；
+- Problem；
+- Solution；
+- Benefits，以 Locality、Leverage 和 test surface 表达；
+- Before / After visual；
+- Recommendation strength：Strong、Worth exploring 或 Speculative；
+- 与 ADR 冲突时的明确 warning。
+
+结尾只给一个 Top recommendation。
+
+使用 `CONTEXT.md` 中的领域名称和 `$codebase-design` 中的架构词汇。不要用泛化的“更干净”“更好维护”代替可解释收益。
+
+这一阶段不要提出具体 Interface。报告完成后只问：“你希望深入哪一个候选项？”
+
+## 深入访谈循环
+
+用户选择候选项后：
+
+1. 调用 `$grilling`，一次一个问题确认约束、依赖、deep Module 的 shape、Seam 后的职责和能够保留的测试。
+2. 领域词汇变化时调用 `$domain-modeling`：
+   - 新概念确实稳定时加入 `CONTEXT.md`；
+   - fuzzy term 被澄清时立即更新；
+   - hard-to-reverse decision 形成时建议 ADR。
+3. 用户以长期有效、会影响未来扫描的理由拒绝候选项时，询问是否记录 ADR；临时性理由不沉淀。
+4. 需要比较多个 Interface 设计时调用 `$codebase-design`，使用 design-it-twice。
+5. 返回 candidate decision、推荐 Interface 方向、测试 Seam 和下一步；实际重构交给 `$to-spec` 或 `$implement`。

package/skills/improve-codebase-architecture/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Improve Codebase Architecture"
+  short_description: "扫描架构摩擦并用可视化报告呈现值得深化的模块候选项"
+  default_prompt: "请使用 $improve-codebase-architecture 扫描当前代码库，生成架构深化候选报告，并等待我选择。"
+policy:
+  allow_implicit_invocation: false