@netpilot/skills 0.7.0 → 0.9.0

package/skills/grilling/SKILL.md

@@ -1,22 +1,38 @@
 ---
 name: grilling
-description: 当用户要压力测试一项计划、决策或想法，使用 grill 类触发语，或另一 skill 需要一次一题走完决策树时使用。它负责形成共同理解；普通问答、开放式头脑风暴或已经明确的执行任务不使用。
+description: 当用户要压力测试一项计划、决策或想法，使用 grill 类触发语，或另一 skill 需要通过 rounds 与 frontier 形成共同理解时使用；普通问答、开放式头脑风暴或已明确的执行任务不使用。
 ---
 
 # Grilling
 
-对计划、决策或想法的每个重要方面进行毫不松懈的访谈，直到双方形成共同理解。沿决策树逐个分支推进；先解决上游依赖，再进入依赖它的决定。
+**Relentless（毫不松懈）**地访谈用户，直到双方形成共同理解。把讨论绘制成 **design tree（决策树）**：每项决定都会分叉出依赖它的其他决定。
 
-## 访谈循环
+以 **rounds（轮次）**推进这棵树。**frontier（当前可询问的决策集合）**是前置条件已经解决的全部决定，也就是现在不需要猜测尚未听到的答案、可以立即询问的问题。每一轮询问整个 frontier：给每个问题编号，并给出推荐答案。随后等待用户回答，再进入下一轮。
 
-1. 从当前对话、用户提供的材料和可用环境中建立决策树。区分已知事实、暂定假设、用户已经作出的决定和仍开放的分支。
-2. 选择当前最可能改变范围、方案或风险的一个开放分支。
-3. 一次只问一个问题，并等待用户回答后再继续。每个问题都给出你的推荐答案及最关键的理由或取舍；推荐不是替用户作决定。
-4. 检查回答是否解决了该分支，是否与较早决定冲突，以及是否暴露了新的上游依赖。必要时先处理新依赖，再回到原分支。
-5. 更新决策树并继续，直到每个重要分支都已解决、明确 deferred，或经用户确认为 out of scope。需要研究、原型、外部权限或未来信息时，把访谈标记为暂停/阻塞并返回所需证据；不能把这些未决分支当作已经形成 shared understanding。
+每轮使用下面的格式，保留问题编号、推荐答案和问题之间的分隔：
 
-如果一个事实可以通过文件系统、代码、文档或可用工具查明，先自行查明并把证据带回问题中，不要把检索工作转嫁给用户。决定属于用户：即使你有强烈推荐，也要把选择交给用户并等待回答。
+```text
+❓ **Q1** - **<问题标题>**：<问题正文；可以包含多个段落或选项>
 
-除只读查明事实外，在用户明确确认双方已经形成共同理解前，不基于方案执行任何写入或外部动作，包括实施、建 issue、写 spec、改 tracker 状态或创建 artifact。`grill-with-docs` 是显式 wrapper：它只在每个具体决定已经由用户确认后，按自身授权即时沉淀文档。
+➡️ <推荐答案>
 
-用户确认后才结束访谈并把结果交回调用方。若由另一 skill 调用，返回已确认决定、仍未解决的分支及所需证据，由调用方决定产物格式和下一步；不要夺取调用方的工作流。
+---
+
+❓ **Q2** - **<问题标题>**：<问题正文；可以包含多个段落或选项>
+
+➡️ <推荐答案>
+```
+
+用户每回答一轮，design tree 都会改变：已解决的决定会把 frontier 向外推进，并解锁依赖它们的问题。根据回答重新计算 frontier，再询问下一轮。本轮中某个问题如果仍依赖另一个开放问题的答案，就属于后续轮次，不能放进当前轮。
+
+查明 _facts（事实）_ 是 agent 的工作，不能转嫁给用户。Frontier 问题需要文件系统、工具或其他环境事实时，dispatch subagent（派发子代理）去查明。不要因此阻塞整个轮次：正在运行的探索是一个尚未解决的前置条件，所以只有依赖它的问题等待 subagent 返回；立即询问 frontier 中其余问题。_decisions 属于用户_：把每项选择交给用户并等待回答，推荐答案不能替用户作决定。
+
+宿主没有可用子代理，或当前任务禁止委派时，由当前 agent 只读查明该事实；本轮其余已就绪问题仍可先问，依赖该事实的问题留到查明后。只降级执行方式，不猜答案，也不把可自行查明的事实转问用户。
+
+当 frontier 为空时，访谈达到 Completion Criterion（完成条件）：design tree 的每个 branch 都已访问，没有 silent assumption（未明说的假设）。
+
+Frontier 为空后仍不能立即行动；必须等待用户确认双方已经形成共同理解。
+
+除只读查明 facts 外，在用户明确确认双方已经形成共同理解前，不基于方案执行任何写入或外部动作，包括实施、建 issue、写 spec、改 tracker 状态或创建 artifact。`grill-with-docs` 是显式 wrapper：它只在当前 round 中每个具体 decision 已由用户确认后，按自身授权即时沉淀文档。
+
+用户确认后才结束访谈并把结果交回调用方。若由另一 skill 调用，返回已确认 decisions、仍未解决的 branches 及所需证据，由调用方决定产物格式和下一步；不要夺取调用方的 workflow。

package/skills/grilling/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Grilling"
-  short_description: "沿决策树一次一题深入访谈，并为每个分支给出推荐答案"
-  default_prompt: "请使用 $grilling 沿决策树一次只问一个问题，并为每个问题给出推荐答案。"
+  short_description: "按 frontier 分轮压力测试计划、决策或想法，并逐题给出推荐答案"
+  default_prompt: "请使用 $grilling 建立 design tree，每轮询问整个 frontier，并为每个问题给出推荐答案。"
 policy:
   allow_implicit_invocation: true

package/skills/handoff/SKILL.md

@@ -41,7 +41,7 @@ disable-model-invocation: true
 ## 已排除的路径
 ## 剩余风险与未知项
 ## 下一步
-## Suggested Skills
+## Suggested Skills（建议技能）
 ## 恢复提示
 ```
 

package/skills/implement/SKILL.md

@@ -24,8 +24,8 @@ disable-model-invocation: true
 1. 从已批准的 spec、ticket 或验收标准开始；范围仍有关键歧义时返回 `ask`、`grilling` 或 `to-spec`，不要自行扩展需求。
 2. 在适用且存在可观察行为时，在预先确认的 seams 上使用 `tdd`，一次完成一个 test → minimal implementation 的垂直切片。纯文档、机械配置或没有可测试行为的改动不适用时记录原因，并执行与风险相称的定向验证。结构整理留到完整 diff 可见后的审查阶段。
 3. 定期运行 typecheck 和单个相关测试文件，使失败靠近引入它的切片。
-4. 所有切片完成后，仓库存在完整测试套件时运行一次。无法运行时如实记录原因与剩余风险，不能把未运行写成通过。
-5. 使用 `code-review` 对同一 fixed point 做 Standards + Spec 双轴审查。修复确认的问题后，重跑受影响验证。
+4. 所有切片完成后，仓库存在完整测试套件时运行一次。无法运行时如实记录原因与剩余风险，不能把未运行写成通过。需要证明用户可观察结果、执行浏览器验收或处理检查阻塞时，读取 [验收证据](references/verification.md)，完成后返回本流程。
+5. 使用 `code-review` 对同一 fixed point（固定比较点） 做 Standards + Spec 双轴审查。修复确认的问题后，重跑受影响验证。
 6. 检查最终 diff 只包含当前任务。按动作授权 commit，并在证据支持时更新 tracker 状态或关闭明确任务。
 
 规格与真实代码约束冲突时停止扩展实现：记录证据、受影响验收标准和最小决策点，把控制权交还用户。

package/skills/implement/references/verification.md

@@ -0,0 +1,32 @@
+# 验收证据
+
+用于实施后的验收，不是另一个工作流入口。先从当前用户要求、已批准规格和项目验证规则确定必需证据；只读分析、纯文档和机械修改不自动升级成浏览器或端到端测试。
+
+## 把检查对应到要求
+
+每项验收要求应对应实际检查或可定位证据；同一证据可覆盖多项要求。复用仓库现有命令和测试，不凭空发明 `qa`、`verification` 命令，也不为凑清单安装工具。已有有效证据可复用，但要核对它对应当前待交付版本；审查后有修改时重跑受影响检查。
+
+| 变更与要求 | 合适的证据 |
+| --- | --- |
+| 文档、metadata、命令说明 | 结构与引用检查；说明涉及命令时确认其实际存在 |
+| 逻辑、状态、API 行为 | 在已确认 Seam 上运行定向测试，覆盖该要求涉及的成功和失败路径 |
+| 页面布局、交互或可访问性 | 按项目认可的浏览器工具操作实际页面，记录入口、步骤与结果；涉及视觉结果时保留截图 |
+| 构建、配置或产物生成 | 项目要求的构建／配置检查，并读取生成结果；编译成功不能替代行为验收 |
+
+UI 验收从本次改变的行为出发：例如表单提交，就核对实际输入、提交结果、失败反馈与重复操作；布局修改就核对受影响的视口和内容状态。仅当对应要求或变更风险相关时扩大到键盘、响应式、空态、加载态和错误态，不机械要求每次覆盖整个产品。
+
+## 工具与权限边界
+
+已有 `agent:test-verifier` 可执行命令验证时，传入范围、必需检查和项目规则，让它返回实际命令与证据；不可用时主 agent 执行同样检查。浏览器操作使用当前可用且项目认可的工具，不把只读前端审查当成真实浏览器验收。
+
+测试优先使用本地或隔离环境及假数据。遇到真实支付、发送消息、生产写入或其他未授权副作用时停在该动作之前，继续执行独立的安全检查，并准确报告缺少哪项授权或替代环境。
+
+## 结果与恢复
+
+- **passed**：当前范围的必需检查均已执行成功，并有对应证据。
+- **failed**：已执行的检查观察到不符合要求的结果；记录复现入口和失败信号。
+- **blocked**：必需检查无法执行；记录缺失环境、工具、访问条件及恢复后的第一步。其他检查通过不能抵消该缺口。
+
+同时存在失败与阻塞时，两者都报告。结论只覆盖本次实际检查的范围；截图只证明捕获的页面状态，单元测试通过不证明真实服务连接成功。报告保留命令、退出码、关键观察和证据路径，避免复制完整日志或敏感内容。
+
+记录检查前后的工作树变化。工具产生非预期受版本控制修改时保留现场并交由实施流程处理，不清理或回滚用户改动，也不把该次验证报告为全部通过。验收完成后回到 `implement` 的独立审查与交付步骤，不因验收通过而自动提交或发布。

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # Improve Codebase Architecture
 
-发现 architectural friction，并提出把 shallow module 深化为 deep module 的机会。目标是提高 testability、locality、leverage 和 agent navigability。
+发现 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。
 
@@ -33,7 +33,7 @@ disable-model-invocation: true
 
 先读领域 glossary 和相关 ADR。
 
-使用只读代码探索，按真实理解摩擦有机寻找：
+启动一个只读子代理探索代码库，按真实理解摩擦有机寻找；宿主不支持子代理时由当前 agent 执行相同的只读探索：
 
 - 理解一个概念是否需要在许多小 Module 之间跳转；
 - Module 是否 shallow：Interface 几乎和 Implementation 一样复杂；
@@ -45,7 +45,7 @@ disable-model-invocation: true
 
 对每个候选项执行 deletion test：删除该 Module 会让复杂性集中到一个清楚位置，还是只把代码搬到别处？只有前者才是可信 deepening signal。
 
-## 生成 HTML report
+## 生成 HTML 报告
 
 把单文件报告写入操作系统临时目录：
 
@@ -68,6 +68,8 @@ disable-model-invocation: true
 - Recommendation strength：Strong、Worth exploring 或 Speculative；
 - 与 ADR 冲突时的明确 warning。
 
+**ADR 冲突**：只有真实摩擦足以支持重新审视该 ADR 时才展示候选，并明确标记，例如“与 ADR-0007 冲突，但值得重新讨论，因为……”。不要列出 ADR 禁止的所有理论重构。
+
 结尾只给一个 Top recommendation。
 
 使用 `CONTEXT.md` 中的领域名称和 `$codebase-design` 中的架构词汇。不要用泛化的“更干净”“更好维护”代替可解释收益。
@@ -78,11 +80,11 @@ disable-model-invocation: true
 
 用户选择候选项后：
 
-1. 调用 `$grilling`，一次一个问题确认约束、依赖、deep Module 的 shape、Seam 后的职责和能够保留的测试。
+1. 调用 `$grilling`，以 rounds 询问当前全部 frontier，确认约束、依赖、deep Module 的 shape、Seam 后的职责和能够保留的测试。
 2. 领域词汇变化时调用 `$domain-modeling`：
    - 新概念确实稳定时加入 `CONTEXT.md`；
    - fuzzy term 被澄清时立即更新；
    - hard-to-reverse decision 形成时建议 ADR。
-3. 用户以长期有效、会影响未来扫描的理由拒绝候选项时，询问是否记录 ADR；临时性理由不沉淀。
+3. 用户以长期有效、会影响未来扫描的理由拒绝候选项时，询问是否记录 ADR；跳过临时性理由（例如“现在不值得做”）和自明的理由。
 4. 需要比较多个 Interface 设计时调用 `$codebase-design`，使用 design-it-twice。
 5. 返回 candidate decision、推荐 Interface 方向、测试 Seam 和下一步；实际重构交给 `$to-spec` 或 `$implement`。

package/skills/prototype/SKILL.md

@@ -5,13 +5,13 @@ description: 当关键设计问题不能只靠讨论确定，需要用可丢弃
 
 # Prototype
 
-Prototype 是**用可丢弃代码回答一个问题**。问题决定它的形状。
+Prototype（原型）是**用可丢弃代码回答一个问题**。问题决定它的形状。
 
 ## 选择分支
 
 从用户提示、相邻代码或一次澄清中确认问题：
 
-- **“这套 logic / state model 是否合理？”** → 读取 [logic.md](references/logic.md)，构建一个小型交互式 terminal app，让用户推动纸面上难以判断的状态。
+- **“这套 logic / state model 是否合理？”** → 读取 [logic.md](references/logic.md)，构建一个可分享的单文件 HTML：同时提供 free-play buttons（自由操作按钮）与 tabbed guided walkthroughs（分标签页的引导演练），让非开发者也能推动纸面上难以判断的状态。
 - **“它应该长什么样？”** → 读取 [ui.md](references/ui.md)，在一个 route 上生成数个结构上明显不同的 UI variants，通过 URL search param 和浮动底栏切换。
 
 两个分支产物完全不同，选错会浪费整个实验。问题确实有歧义且用户暂时不可达时，根据相邻代码选择：backend Module 默认 logic，page/component 默认 UI，并在 prototype 顶部明确写出假设。
@@ -19,7 +19,7 @@ Prototype 是**用可丢弃代码回答一个问题**。问题决定它的形状
 ## 两种分支都遵守的规则
 
 1. **从第一天起就是 throwaway，并明确标记。** 代码放在最接近未来使用位置的地方，使上下文清楚；命名必须让读者一眼看出它不是 production。UI route 遵循项目既有 routing convention，不发明新的顶层结构。
-2. **一条命令运行。** 使用项目已有 task runner，例如 `pnpm <name>`、`python <path>` 或 `bun <path>`；用户不应记忆内部文件路径。
+2. **启动不需要思考。** UI prototype 从项目现有 task runner 的一条命令启动，例如 `pnpm <name>`、`python <path>` 或 `bun <path>`；logic demo 是用户双击即可打开的单个 HTML 文件。
 3. **默认不持久化。** 状态放在内存。若问题本身涉及数据库，使用 scratch database 或名称明确标注 `PROTOTYPE — wipe me` 的本地文件。
 4. **跳过 polish。** 不写测试，不补与可运行无关的错误处理，不提前抽象。目标是快速学习。
 5. **完整展示状态。** 每次 logic action 或 UI variant 切换后，输出或渲染完整相关状态，使变化可见。

package/skills/prototype/references/logic.md

@@ -1,87 +1,67 @@
 # Logic Prototype
 
-构建一个小型交互式 terminal app，让用户手动推动 business logic、state transition 或 data shape。
+一个自包含的 HTML 文件——一份 **shareable demo（可分享演示）**——让任何人通过点击按钮推动 state model。问题涉及 **business logic、state transitions 或 data shape** 时使用：这些模型在纸面上看起来合理，只有真正经过具体情形时才会显出不对劲。
 
-## 适用情形
+因为它只有一个文件、无需安装，所以可以直接交给非开发者，例如设计师、产品经理或领域专家，让他们亲自感受模型。因此它必须使用他们的语言，而不是代码作者的语言。
 
-- “我不确定 X 后再发生 Y 时，这个 state machine 是否正确。”
-- “这套 data model 能否表达某个边界情况？”
-- “实现前我想先感受一下 API 应该是什么形状。”
-- 用户需要“按键并观察状态改变”。
+## 何时适合这种形态
 
-若问题是“它应该长什么样”，改用 `ui.md`。
+- “我不确定 X 之后再发生 Y 时，这个 state machine 是否正确处理 edge case。”
+- “这套 data model 是否真的能表达某种情况？”
+- “写正式实现前，我想先感受 API 应该是什么形状。”
+- 任何需要某个人 **按按钮并观察状态改变** 的问题。
+
+如果问题是“它应该长什么样”，说明选错了分支，改用 [ui.md](ui.md)。
 
 ## 流程
 
 ### 1. 写明问题
 
-在 README 或主文件顶部用一段话写明待验证的 state model 与问题。用户无论在线还是之后回来，都必须能判断 prototype 是否回答了正确问题。
-
-### 2. 选择语言
-
-使用宿主项目已有语言、runtime 与 task runner。项目没有明显 runtime 时再询问，不要只为 prototype 引入新工具链。
-
-### 3. 把 logic 隔离为可移植 Module
-
-把真正回答问题的逻辑放到小而 pure 的 Interface 后。TUI 是 throwaway；logic module 应能独立提取。
-
-按问题选择：
-
-- **Pure reducer**：`(state, action) => state`。适用于 actions 是离散 events，且 state 可表示为单一值的情况。
-- **Explicit state machine**：适用于“当前究竟允许哪些 actions”本身就是待验证问题的情况。
-- **作用于 plain data type 的一组 pure functions**：适用于不存在隐式 current state、只有数据转换的情况。
-- **Method surface 清楚的 class/module**：仅在 logic 确实拥有持续内部状态时使用。
-
-根据问题选择，不根据 TUI 接线便利选择。Logic 内不得包含 I/O、terminal code 或用于控制流的 `console.log`。TUI 可以 import logic，logic 不得反向依赖 TUI。
-
-### 4. 构建最小 TUI
+写代码前，先写明要验证哪套 state model、回答哪个问题。用一段话放在 demo 顶部可见的 intro 中，而不只是代码 comment。回答错问题的 logic prototype 完全是浪费；明确写出问题，用户无论正在旁观还是之后 AFK 回来，都能核对它。
 
-每个 tick 清屏并重绘整个 frame，而不是不断追加 scrollback。
+### 2. 在可移植 Module 中隔离 logic
 
-Frame 按顺序包含：
+把真正回答问题的 logic 放进单一 `<script>` block，写成小而 pure、以后可从页面中提取并放进真实 codebase 的 Module。周围的页面是 throwaway；这个 Module 不是。
 
-1. **Current state**：每字段一行或 formatted JSON。字段名/标题可用 bold，timestamp、ID、derived value 可用 dim。已有 styling library 才复用；否则 ANSI escape 足够。
-2. **Keyboard shortcuts**：例如 `[a] add user  [d] delete user  [t] tick clock  [q] quit`。
+正确形态取决于问题：
 
-行为：
+- **Pure reducer**——`(state, action) => state`。Actions 是离散 events，且 state 是单一值时适用。
+- **State machine**——显式 states 与 transitions。“当前究竟允许哪些 actions”本身就是问题的一部分时适用。
+- **作用于 plain data type 的少量 pure functions**。没有隐式 current state、只有 transformations 时适用。
+- **拥有清楚 method surface 的 class 或 module**。仅在 logic 确实拥有持续内部状态时使用。
 
-1. 初始化单一 in-memory state；
-2. 启动时渲染；
-3. 每次读取一个 key 或一行；
-4. dispatch 到 handler；
-5. 每次 action 后重绘完整 frame；
-6. 持续循环直到 quit。
+选择最符合问题的形态，*而不是*最容易接到页面上的形态。保持 pure：不引用 DOM，不引用 `document`，button handlers 也不能伸进内部。页面单向调用 logic，logic 不反向流向页面。这样 prototype 才能超越自身寿命：问题回答后，已经验证的 reducer、machine 或 function set 可以独立进入正式 Module；只有另行授权 `$implement` 后才能执行这项正式写入。
 
-整个 frame 应能放入一个 terminal screen。
+### 3. 构建 shareable HTML 文件
 
-### 5. 一条命令运行
+只用一个 plain HTML/CSS/JS 文件：不用 framework、bundler 或 server，全部 inline，使它可以双击打开，也可以通过邮件转交。任何人打开文件就能运行。
 
-把运行入口加入现有 `package.json`、`Makefile`、`justfile` 或 `pyproject.toml`。用户应只需执行 `pnpm run <prototype-name>` 或等价命令。
+面向非开发者编写。每个 label 都使用 **domain language**，而不是代码术语；buttons 和 state 应像业务，而不是像 reducer。用朴素语言解释正在发生什么。
 
-项目没有 task runner 时，把完整命令写在 prototype 顶部。
+从上到下采用清楚的层级：
 
-### 6. 交给用户操作
+1. **标题和一句话说明**：说明这个 demo 能探索什么，也就是步骤 1 的问题。
+2. **当前状态**：把完整相关 state 渲染为可读 panel，使用有 label 的字段而不是 raw JSON；每次点击后重新渲染，让变化可见。若能帮助非开发者跟上，再指出刚刚改变了什么。
+3. **Free-play buttons**（自由操作按钮）：每个 action 一个 button，并且始终可用，让任何人按任意顺序探索模型。每次点击都 dispatch 对应 action，再重新渲染 state。
+4. **Guided walkthroughs**（引导演练）：提供一组 **scenarios（场景）**，每个 scenario 一个 tab。每个 tab 先用简短的日常语言说明它建立的情形和需要观察的重点，再列出该 scenario 中应按顺序点击的 **buttons**。每一步都是真实 button：点击会执行该 action 并进入下一步。启动 walkthrough 时重置到已知 initial state，使同一 scenario 每次都以相同方式运行。
 
-给出运行命令，由用户亲手驱动。最有价值的反馈通常是：
+选择能展示棘手情况的 scenarios：happy path、tricky edge case，以及一次本应 illegal 的尝试；它们正是纸面上难以推理的部分。
 
-- “这个动作此时不应该合法。”
-- “我以为这个字段会变成另一种状态。”
-- “这里缺少一个状态。”
+外观可以漂亮，但要克制：清楚的排版、宽松的间距、一种强调色。不要动画或噱头，不要让任何东西与 state 和 buttons 争夺注意力。
 
-用户需要新 action 时可以追加，但每次追加都必须继续服务原问题。
+### 4. 交给对方操作
 
-### 7. 捕获答案与证据
+把文件发给对方，或替对方打开。他们可以在方便时完成 walkthroughs 和 free-play；最有价值的时刻通常是“等等，这不应该发生”或“原来如此，我以为 X 会不一样”——这些是 *idea* 中的 bugs，也正是 prototype 的目的。对方需要新 action 或新 scenario 时就加入；prototypes 会演进。
 
-问题回答后：
+### 5. 捕获答案与 prototype
 
-- validated reducer、machine 或 pure functions 可以作为正式实现输入；只有另行授权 `$implement` 后才写入正式代码；
-- TUI shell 与完整实验记录保留在已授权的 throwaway branch；
-- 主分支不保留 TUI shell。
+Prototype 回答问题后，先捕获答案，再按主 [SKILL](../SKILL.md) 的方式捕获 prototype。Logic 分支的映射是：已经验证的 reducer、machine 或 function set 是可供正式实现吸收的 decision；只有另行授权 `$implement` 后才写入正式 Module。HTML shell 则进入保留 prototype 一手证据的 throwaway branch；因为它是单个自包含文件，所以在那里仍然可以轻松重新运行。
 
 ## 反模式
 
-- 不给 prototype 本身补测试。
-- 除非问题就是 persistence，否则不连接真实数据库。
-- 不泛化未来可能需求。
-- 不把 logic 与 TUI 混在一起。
-- 不把 TUI shell 直接送入生产。
+- **不要补测试。** 需要测试的 prototype 已经不再是 prototype。
+- **不要连接真实数据库。** 除非问题专门关于 persistence，否则使用 in-memory state。
+- **不要泛化。** 不处理“以后可能支持 X”之类的问题；prototype 只回答一个问题。
+- **不要把 logic 与页面混在一起。** Pure Module 一旦引用 DOM、`document` 或 button handlers，就无法独立提取。页面只是 pure Module 外的一层薄 shell。
+- **不要引入 framework、bundler 或 server。** 接收者应当双击一个文件；React app 或 dev server 会破坏“shareable”这一目标。
+- **不要把 HTML shell 送入 production。** 页面是为了人工点击而优化的；真正值得保留的是背后的 logic Module，而且仍须另行授权 `$implement`。

package/skills/prototype/references/ui.md

@@ -1,57 +1,64 @@
 # UI Prototype
 
-在一个 route 上生成数个结构上显著不同的 UI variants，通过浮动底部 switcher 切换。用户可以选择一个方案，或组合不同方案的优点，其余最终丢弃。
+在一个 route 上生成 **数个结构上显著不同的 UI variants**，并通过浮动底栏切换。用户在浏览器中逐个比较，选定一个方案或组合各方案的优点，然后丢弃其余方案。
 
-若问题是 logic/state，改用 `logic.md`。
+如果问题是 logic/state 而不是外观，说明选错了分支，改用 [logic.md](logic.md)。
 
-## 适用情形
+## 何时适合这种形态
 
-- “这个 page 应该长什么样？”
-- “实现 dashboard 前先看几个方案。”
-- “尝试 settings screen 的不同 layout。”
+- “这个页面应该长什么样？”
+- “实现 dashboard 前，我想先看几个方案。”
+- “尝试 settings screen 的另一种 layout。”
+- 任何本来会让用户花一天在脑中比较三份模糊 mockup（界面草图） 的情形。
 
-## 两种形态
+## 两种形态——强烈优先 A
 
-强烈优先 A。Variant 与真实 header、sidebar、data 和 density 相邻时，才容易判断。
+当 UI prototype **紧贴应用其余部分**——真实页头、真实侧栏、真实数据、真实信息密度——时，会更容易判断。孤立的 throwaway route 是一个 vacuum：每个 variant 单独看起来都不错。只要存在合理的已有页面可以承载 variants，就默认使用 A；只有 prototype 确实没有附近的归宿时才使用 B。
 
 ### A：调整已有页面
 
-Route 已存在。通过 `?variant=` 在同一 route 切换 render subtree；保留原 data fetching、params 和 auth。
+Route 已经存在。通过 `?variant=` URL search param 在 **同一个 route** 上切换 variants。现有 data fetching、params 和 auth 全部保留，只替换 render。除非有具体理由，否则选择 A。
 
-即使新内容尚无独立 page，只要它自然属于已有 dashboard、settings 或 flow，也仍使用 A，把 variants mount 到 host page。
+即使新内容还没有自己的 page，只要它自然属于某个已有页面——dashboard 的新 section、settings screen 的新 card，或现有 flow 的新 step——仍属于 A。把 variants mount 到 host page 内。
 
 ### B：全新页面
 
-只有完全没有合理 host page 的全新顶层 surface 或 flow 才使用。
+只有要验证的内容确实没有任何已有页面可容纳时才使用，例如完全新的 top-level surface，或无法合理嵌入别处的 flow。
 
-按项目 routing convention 创建明确标记 prototype 的 throwaway route，例如 `/prototype/<name>`，同样使用 `?variant=`。不要自创新的顶层目录结构。
+按项目已有 routing convention 创建 **throwaway route**，不要发明新的顶层结构。名称必须明显表明它是 prototype，例如 path 或 filename 包含 `prototype`。仍使用相同的 `?variant=` pattern。
 
-进入 B 前再次确认：它真的无法嵌入任何现有 page 吗？
+选择 B 前再核对一次：它真的无法嵌入已有页面吗？空 route 会隐藏 design problems，而有真实内容的页面会把它们暴露出来。
+
+两种形态共用完全相同的浮动底栏。
 
 ## 流程
 
-### 1. 写明问题并确定数量
+### 1. 写明问题并选择 N
 
-默认 **3 variants**，最多 5 个。超过 5 个往往不再是 radically different，而只是噪声。
+默认 **3 variants**。超过 5 个后，它们通常不再 radically different，而只是噪声，因此上限为 5。
 
-在 prototype 位置写一行：
+在 prototype 所在位置或文件顶部 comment 写下一行 plan：
 
 > 在现有 `/settings` route 上提供 3 个 settings page variants，通过 `?variant=` 切换。
 
+无论用户在线可以提出异议，还是暂时 AFK，这行 plan 都能供之后核对。
+
 ### 2. 生成结构上显著不同的 variants
 
-每个 variant 必须符合：
+起草每个 variant，并逐一满足：
 
-- page purpose 与可用 data；
-- 项目已有 component library / styling system；
+- page purpose 与它可以访问的 data；
+- 项目既有 component library / styling system，例如 TailwindCSS、shadcn、MUI 或 plain CSS；
 - 清楚的 exported component name，例如 `VariantA`、`VariantB`、`VariantC`。
 
-Variants 必须在 layout、information hierarchy 或 primary affordance 上不同，而不只是颜色、copy 或 card 间距不同。若两个方案太像，明确要求其中一个不用 card grid 并重新设计。
+Variants 必须 **结构不同**：布局、信息层级或主要操作方式不同，而不只是颜色。三个只有轻微差别的 card grid 不是 UI prototype，只是 wallpaper。两个 draft 太相似时，明确要求其中一个“不要使用 card grid”并重新设计。
 
 ### 3. 连接切换逻辑
 
+在 route 上创建单一 switcher component：
+
 ```tsx
-// pseudo-code：按项目 framework 调整
+// pseudo-code——按项目 framework 调整
 const variant = searchParams.get("variant") ?? "A";
 
 return (
@@ -67,42 +74,43 @@ return (
 );
 ```
 
-Sub-shape A：所有现有 data fetching 保留在 switcher 上方，只替换 render subtree。
-Sub-shape B：throwaway route mount 同一个 switcher。
+形态 A：所有现有 data fetching 留在 switcher 上方，只替换各 variant 的 rendered subtree。
+
+形态 B：`/prototype/<name>` 下的 throwaway route mount 同一个 switcher。
 
 ### 4. 浮动 switcher
 
-底部中央固定一个小 bar：
+在屏幕底部中央固定一个小型栏，包含三部分：
 
-- 左箭头：切换前一 variant，首尾循环；
-- label：显示当前 key 与名称，例如 `B — Sidebar layout`；
-- 右箭头：切换后一 variant，首尾循环。
+- **左箭头**：切换到前一个 variant，并首尾循环；
+- **Variant label**：显示当前 variant key；如果 variant export 了名称，也一起显示，例如 `B — Sidebar layout`；
+- **右箭头**：向后切换，并首尾循环。
 
 行为：
 
-- 使用项目 router 更新 URL search param，使 variant 可分享、reload 后稳定；
-- `←` 与 `→` 键切换；
-- focus 位于 `input`、`textarea` 或 `[contenteditable]` 时不截获方向键；
-- 视觉上明显独立于被评估页面；
-- 通过 `NODE_ENV !== "production"` 或等价条件确保 production build 隐藏；
-- switcher 只实现一次，放在项目合理的 shared UI 位置。
+- 点击箭头时用项目 framework 的 router 更新 URL search param，例如 Next 的 `router.replace` 或 React Router 的 `navigate`，使 variant 可分享并在 reload 后保持稳定；
+- `←` 与 `→` 键也可切换；focus 位于 `<input>`、`<textarea>` 或 `[contenteditable]` 时不得截获方向键；
+- switcher 必须在视觉上明显独立于被评估页面，例如高对比胶囊形样式加轻微阴影，使人清楚它不属于设计本身；
+- 在 production builds 中隐藏：使用 `process.env.NODE_ENV !== "production"` 或等价检查，避免一次意外 merge 把底栏交付给用户。
+
+Switcher 只实现一次，放在项目既有 shared UI 位置，让两种形态复用。
 
 ### 5. 交给用户比较
 
-给出完整 URL 与 variant keys。用户可能会提出“B 的 header 加 C 的 sidebar”，这种组合反馈正是 prototype 要发现的答案。
+给出完整 URL 与 `?variant=` keys。用户可以在方便时逐个比较。最有价值的反馈通常是“我想要 B 的 header 和 C 的 sidebar”——这才是他们真正想要的设计。
 
 ### 6. 捕获结论并清理
 
-选定方案后记录 winner 与原因：
+Variant 胜出后，先捕获答案——哪个 variant 以及为什么——再按主 [SKILL](../SKILL.md) 的方式捕获 prototype。只有另行授权 `$implement` 后，才能把 winner 写入正式代码；其余内容进入 throwaway branch，而不是 main：
+
+- **形态 A**：把 winner 作为现有 page 的正式实现输入；获得 `$implement` 授权后吸收 winner，并从 main 移除 losing variants 与 switcher。
+- **形态 B**：把 winner 作为真实 route 的正式实现输入；获得 `$implement` 授权后吸收 winner，并从 main 移除 throwaway route 与 switcher。
 
-- Sub-shape A：把 winner 作为现有 page 的实现输入；只有另行授权 `$implement` 后才写入正式代码，并从主分支移除 losing variants 与 switcher。
-- Sub-shape B：把 winner 作为真实 route 的实现输入；只有另行授权 `$implement` 后才写入正式代码，并从主分支移除 throwaway route 与 switcher。
-- 完整 variants 作为 primary source 留在已授权的 throwaway branch，而不是主分支。
+完整 variants 是 primary source，因此保留在 throwaway branch，而不是丢进垃圾箱；variant components 与 switcher 如果留在 main，会很快 rot，并让下一位读者困惑。
 
 ## 反模式
 
-- Variants 只改变颜色或 copy。
-- 共享过多 layout 代码，使各方案无法真正不同。
-- 把 prototype 连接到真实 mutation；需要 mutation 时使用 stub。
-- 把 prototype variant 直接提升为生产实现；正式吸收时必须补生产级错误处理与测试。
-- 把 losing variants 或 switcher 留在主分支腐化。
+- **Variants 只改变颜色或文案。** 那只是 tweak，不是 prototype；真正的 variants 对结构持不同意见。
+- **Variants 共享过多代码。** 共用 `<Header>` 没问题，共用 `<Layout>` 会破坏目的；每个 variant 都必须能丢掉现有 layout。
+- **把 variants 接到真实 mutations。** 只读 prototype 没问题；需要 mutation 时指向 stub。问题是“它应该长什么样”，不是“backend 是否工作”。
+- **把 prototype 直接提升为 production。** Variant code 是在 prototype 约束下写的，没有测试，错误处理也最少。获得 `$implement` 授权后，仍须按生产标准重新实现、补齐 error handling 和 tests。

package/skills/research/SKILL.md

@@ -5,11 +5,13 @@ description: 当任务需要依据高可信一手资料调查问题、核验文
 
 # Research
 
-启动一个 **background agent** 执行阅读工作，使调用者可以同时推进其他不依赖研究结论的任务。
+启动一个 **background agent（后台子代理）** 执行阅读工作，使调用者可以同时推进其他不依赖研究结论的任务。
+
+宿主没有可用子代理，或当前任务禁止委派时，由当前 agent 执行同样的研究并保存相同证据；明确说明改为串行，不虚构派发。并行只能改变执行方式，不能降低下列来源与引用要求。
 
 后台 agent 的职责只有三项：
 
-1. 依据 **primary sources** 调查问题：官方文档、源代码、规范、论文或 first-party API，而不是二手总结。每项事实都追溯到拥有该事实的一手来源。
+1. 依据 **primary sources（一手来源）** 调查问题：官方文档、源代码、规范、论文或 first-party API，而不是二手总结。每项事实都追溯到拥有该事实的一手来源。
 2. 把结论写入一份 Markdown 文件；每项可验证 claim 或事实都在出现位置直接引用拥有该事实的一手来源，而不是只给整篇文档附一组链接。
 3. 遵循仓库现有研究文档位置与命名约定；没有约定时选择合理位置，并明确返回绝对或仓库相对路径。
 

package/skills/resolving-merge-conflicts/SKILL.md

@@ -5,7 +5,7 @@ description: 当 Git 已处于 merge 或 rebase 中且存在冲突，需要依
 
 # Resolving Merge Conflicts
 
-逐 hunk 解决正在进行的 merge 或 rebase。目标是保存双方原始意图，并使项目重新通过检查；不是选择“ours 全赢”或“theirs 全赢”。
+逐 hunk（差异块）解决正在进行的 merge 或 rebase。目标是保存双方原始意图，并使项目重新通过检查；不是选择“ours 全赢”或“theirs 全赢”。
 
 ## 动作门禁
 

package/skills/tdd/SKILL.md

@@ -11,7 +11,7 @@ TDD 是 **red → green** 循环。本 skill 说明什么测试值得保留、
 
 ## 好测试是什么
 
-测试通过 public Interface 验证 behavior，而不是 Implementation details。代码内部可以完全重写；只要外部 behavior 不变，测试就不应变化。
+测试通过公开 Interface 验证 behavior，而不是 Implementation 内部细节。代码内部可以完全重写；只要外部 behavior 不变，测试就不应变化。
 
 好测试读起来像 specification，例如：
 
@@ -21,19 +21,21 @@ TDD 是 **red → green** 循环。本 skill 说明什么测试值得保留、
 
 ## Seam：测试放在哪里
 
-**Seam** 是测试观察 behavior 的 public Interface。测试位于 Seam，不伸进 internals。
+**Seam** 是测试观察 behavior 的公开 Interface。测试位于 Seam，不伸进内部实现。
 
-只在预先确认的 Seams 上测试。写测试前列出 public Interface 与本次要测试的 Seams，并取得用户确认，或确认它们已在批准的 spec/plan 中明确；不要在每个 cycle 重复询问已批准的同一 Seam。
+只在预先确认的 Seams 上测试。写测试前列出公开 Interface 与本次要测试的 Seams，并取得用户确认，或确认它们已在批准的 spec/plan 中明确；不要在每个 cycle 重复询问已批准的同一 Seam。
 
 核心问题：
 
-> Public Interface 是什么？哪些 Seams 值得测试？
+> 公开 Interface 是什么？哪些 Seams 值得测试？
+
+当 Interface 的形状本身仍未确定——Module 应有多深、Seam 放在哪里、Interface 暴露什么——读取 `$codebase-design`（Claude 使用 Skill 工具调用 `codebase-design`）的共享参考。它统一 Module、Interface、Depth、Seam、Adapter、Leverage 与 Locality 的含义；读完返回当前 TDD 循环，不另开设计会话。
 
 ## 反模式
 
-- **Implementation-coupled**：mock 内部 collaborators、测试 private methods，或通过 side channel 验证，例如绕过 Interface 直接查询数据库。判断信号是：behavior 没变，内部重构却让测试失败。
-- **Tautological**：断言用与 Implementation 相同的方式重新计算 expected value，例如 `expect(add(a, b)).toBe(a + b)`。它按构造就无法反驳代码。Expected value 必须来自独立事实：known-good literal、手工演算例子或 spec。
-- **Horizontal slicing**：先写完所有测试，再写全部实现。批量测试验证的是想象中的 behavior，过早锁定测试结构，也无法利用上一轮实现带来的信息。改用 **vertical slices**：一个 test → 一个 implementation → 重复；每个 test 都是响应上一轮事实的 **tracer bullet**。
+- **Implementation-coupled（与实现耦合）**：mock 内部协作者、测试私有方法，或通过旁路验证，例如绕过 Interface 直接查询数据库。判断信号是：behavior 没变，内部重构却让测试失败。
+- **Tautological（同义反复）**：断言用与 Implementation 相同的方式重新计算 expected value，例如 `expect(add(a, b)).toBe(a + b)`。它按构造就无法反驳代码。Expected value 必须来自独立事实：known-good literal、手工演算例子或 spec。
+- **Horizontal slicing（水平切片）**：先写完所有测试，再写全部实现。批量测试验证的是想象中的 behavior，过早锁定测试结构，也无法利用上一轮实现带来的信息。改用 **vertical slices（垂直切片）**：一个 test → 一个 implementation → 重复；每个 test 都是响应上一轮事实的 **tracer bullet（曳光弹）**。
 
 ## 循环规则
 

package/skills/teach/SKILL.md

@@ -30,9 +30,9 @@ disable-model-invocation: true
 
 深层学习需要三样东西：
 
-- **Knowledge**：来自高质量、高可信资料的知识；
-- **Skills**：通过与你设计的、高度相关且可交互的课程练习获得的技能；
-- **Wisdom**：在学习环境之外与其他学习者和实践者互动后形成的判断力。
+- **Knowledge（知识）**：来自高质量、高可信资料的知识；
+- **Skills（技能）**：通过与你设计的、高度相关且可交互的课程练习获得的技能；
+- **Wisdom（实践判断力）**：在学习环境之外与其他学习者和实践者互动后形成的判断力。
 
 在 `RESOURCES.md` 尚未拥有足够可靠资料前，优先补齐资料。不要把参数化记忆当作事实来源。不同主题的重心不同：理论主题可能更依赖 Knowledge；身体、表演或操作性主题可能更依赖 Skills。
 
@@ -40,14 +40,14 @@ disable-model-invocation: true
 
 区分两种学习强度：
 
-- **Fluency strength**：当下能够顺畅提取或复述；
-- **Storage strength**：经过时间后仍能提取、应用和迁移。
+- **Fluency strength（流畅强度）**：当下能够顺畅提取或复述；
+- **Storage strength（存储强度）**：经过时间后仍能提取、应用和迁移。
 
-流畅会制造已经掌握的错觉，长期保持才是目标。用 desirable difficulty 建立 Storage strength：
+流畅会制造已经掌握的错觉，长期保持才是目标。用 desirable difficulty（有益难度） 建立 Storage strength：
 
-- retrieval practice：不看答案，从记忆中提取；
-- spacing：把练习分散到不同时间；
-- interleaving：在技能练习中交错相关主题，而不是连续重复同一题型。
+- retrieval practice（提取练习）：不看答案，从记忆中提取；
+- spacing（间隔练习）：把练习分散到不同时间；
+- interleaving（交错练习）：在技能练习中交错相关主题，而不是连续重复同一题型。
 
 ## 每次教学会话
 
@@ -56,7 +56,7 @@ disable-model-invocation: true
 3. 用短诊断、回忆题或小任务估计用户当前基础和 Zone of Proximal Development。自述可以作为线索，但不能替代掌握证据。
 4. 从高可信资料获得本课所需 Knowledge；资料不足、事实可能变化或用户要求核验时，使用 `$research` 完成有停止条件的调查，再把筛选后的来源写入 `RESOURCES.md`。
 5. 只设计下一节最小课程：一个目标、必要知识、一次主动练习、紧反馈和一个高可信主要来源。课程必须直接服务 mission，并位于用户的 Zone of Proximal Development。
-6. 用户完成练习后检查证据。只有用户能正确回忆、应用或迁移时，才更新学习记录或术语表；material covered 不等于 material learned。
+6. 用户完成练习后检查证据。只有用户能正确回忆、应用或迁移时，才更新学习记录或术语表；讲过不等于学会。
 7. 总结本次小胜利、仍不稳固之处、适合的复习时机和下一节候选目标。
 
 `$teach` 可以调用 `$grilling` 或 `$research`；被调用 skill 返回访谈结果或证据后，控制权回到当前教学会话，不启动第二个 `$teach`。
@@ -97,11 +97,11 @@ Mission 会随着 Skills 和 Knowledge 增长而变化。变化时先与用户
 
 Lesson 应围绕用户要获得的一项 skill 设计，只教授获得该 skill 必需的 Knowledge。先给必要知识，再让用户进入互动反馈循环。
 
-Knowledge 必须优先来自 `RESOURCES.md` 中的可信资料。课程中的事实性主张应就近链接外部来源；推断和经验判断明确标注。获取 Knowledge 时，无关难度会占用理解所需的 working memory，应尽量降低。
+Knowledge 必须优先来自 `RESOURCES.md` 中的可信资料。课程中的事实性主张应就近链接外部来源；推断和经验判断明确标注。获取 Knowledge 时，无关难度会占用理解所需的工作记忆，应尽量降低。
 
 ## 技能
 
-Knowledge 关乎获得，Skills 关乎耐久与迁移。技能练习可以有意增加难度，因为 effortful retrieval 会提高 Storage strength。
+Knowledge 关乎获得，Skills 关乎耐久与迁移。技能练习可以有意增加难度，因为 effortful retrieval（费力提取） 会提高 Storage strength。
 
 可用形式包括：
 
@@ -127,7 +127,7 @@ Wisdom 来自在学习环境之外检验 Skills。遇到需要实践判断的问
 - 流程的算法与流程图；
 - 动作、姿势和练习序列；
 - 训练动作与计划；
-- 任何有专门 nomenclature 的主题 glossary。
+- 任何具有专门术语的主题 glossary。
 
 Glossary 尤其重要。一旦建立，后续 lessons、references 和 learning records 都应使用其中的 canonical language。