@netpilot/skills 0.7.0 → 0.8.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "netpilot-skills",
       "source": "./",
       "description": "中文工程协作 skills 与可组合工作流",
-      "version": "0.7.0",
+      "version": "0.8.0",
       "author": {
         "name": "NetPilot"
       },

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "netpilot-skills",
   "displayName": "NetPilot Skills",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "面向 Claude Code 的中文工程协作 skills 与可组合工作流",
   "author": {
     "name": "NetPilot"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "netpilot-skills",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "面向 Codex 的中文工程协作 skills 与可组合工作流",
   "author": {
     "name": "NetPilot"

package/AGENTS.md

@@ -13,7 +13,7 @@
 
 ## Skill 编写
 
-- 修改 skill 前读取 `skills/writing-great-skills/SKILL.md`。
+- 修改 skill 前读取 `skills/writing-for-agents/SKILL.md`；涉及 Skill invocation、frontmatter 或 Router Skill 时继续读取其 `SKILL-MECHANICS.md`。
 - 每个 `SKILL.md` 的 description 必须说明触发范围和关键边界。Skill 真正包含顺序 steps 时，每一步在原位置结束于可检查的 completion criterion；reference-only skill 不为此伪造步骤。不得强制追加全局“完成标准”或“反模式”模板，反模式只在它提供上游方法本身的诊断价值时保留。
 - 新 skill 使用 kebab-case，并通过官方 skill 脚手架创建。
 - 每个 skill 必须提供 `agents/openai.yaml`；`default_prompt` 显式提到 `$skill-name`。

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 ## Unreleased
 
+## 0.8.0
+
+- 按“保留优先”同步上游 v1.2.2 的关键方法：保留限定词、步骤顺序、completion criteria、诊断例子与 progressive disclosure 附件，只做去个人化、中文化、真实宿主映射和权限门禁适配。
+- 将 `writing-great-skills` 原子迁移为 model-invoked 的 `writing-for-agents`，把适用范围扩展到全部 agent-consumed documents，并保留独立的 `SKILL-MECHANICS.md`；受管理的旧安装会安全移除，用户修改过的旧副本继续作为冲突保留。
+- 将 `grilling` 及其调用方同步为 rounds/frontier 访谈：每轮询问所有已解锁决策，事实探索只阻塞其下游问题，frontier 清空后仍须用户确认 shared understanding。
+- 为 `ask` 恢复完整 phase-boundary decision tree，固定 Continue → Clear / fresh context → `$handoff` → Subagent → Compact 的判断顺序，并把 handoff 收紧到真正需要 portability 的场景。
+- 将 logic prototype 从 TUI 改为可双击和转交的单文件 HTML，恢复 free-play、tabbed walkthroughs、pure logic/DOM separation，以及 UI prototype 中用于区分两种形态的例子、理由和失败模式。
+- 新增显式入口 `to-questionnaire` 与 `wait-what`：前者生成面向外部知识持有者的完整 discovery questionnaire，后者保持极短，只用项目术语补足上下文并重述上一条消息。
+- 与 `@netpilot/harness` 协调发布同一 `v0.8.0` 标签；Skills 继续负责用户级能力，Harness 只负责项目级工程约束和 Agents。
+
 ## 0.7.0
 
 - 新增用户级 `security-reviewer` 与 `migration-reviewer`：前者按应用、Agent/Tool 与供应链 profile 审查信任边界，后者按 Expand → Migrate → Contract 审查 schema、回填、兼容切换与恢复；两者均保持 high / read-only 和统一 P0–P3 证据契约。

package/README.md

@@ -70,6 +70,7 @@ Codex 使用 `$skill-name`；Claude Code 用户级安装使用 `/skill-name`。
 | 访谈 | `grill-me` | 深入盘问但不写文档 | 当前对话中的共识 |
 | 访谈 | `grill-with-docs` | 访谈时同步沉淀文档 | 领域文档与 ADR |
 | 访谈 | `grilling` | 供其他 Skills 复用访谈 | 已确认决定与未决分支 |
+| 访谈 | `to-questionnaire` | 向掌握关键信息的人收集事实或决定 | 可异步填写的问卷 |
 | 探索 | `wayfinder` | 大型工作仍处于 fog of war | Decision map 与 frontier |
 | 探索 | `research` | 核验陌生或变化中的事实 | 带一手引用的研究文档 |
 | 探索 | `prototype` | 用低成本实验验证假设 | Throwaway artifact 与 verdict |
@@ -85,7 +86,8 @@ Codex 使用 `$skill-name`；Claude Code 用户级安装使用 `/skill-name`。
 | 质量 | `resolving-merge-conflicts` | 解决 merge/rebase 冲突 | 已验证的冲突解决结果 |
 | 维护 | `triage` | 推进 issue 或外部 PR | 标签、brief、评论或关闭结果 |
 | 连续性 | `handoff` | 跨会话或人员交接 | 可恢复的状态与下一步 |
-| 维护 | `writing-great-skills` | 创建、本地化或审查 Skill | 可验证的 Skill |
+| 连续性 | `wait-what` | 上一条消息缺少背景或过于复杂 | 更简明的重述 |
+| 维护 | `writing-for-agents` | 编写 Agent 使用的规则、Skill 或指针文档 | 可预测的 Agent 文档 |
 
 ## Codex Agents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netpilot/skills",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "面向 Codex 与 Claude Code 的中文工程协作 skills 与可选 Codex agents",
   "keywords": [
     "codex",

package/skills/ask/SKILL.md

@@ -15,10 +15,7 @@ disable-model-invocation: true
 这是多数产品与工程工作的路线。
 
 1. **`grill-with-docs`**：通过访谈磨清想法。有代码库，并希望把结论保留到 `CONTEXT.md` 或 ADR 时从这里开始。没有代码库则使用 `grill-me`。二者都复用同一个 `grilling` 访谈引擎；区别是 `grill-with-docs` 会留下项目文档。
-2. **分支——所有问题都能通过讨论确定吗？** 如果某个问题需要可运行答案，例如状态、业务逻辑或必须亲眼比较的 UI，则通过 `handoff` 往返一次原型会话：
-   - 用 `handoff` 保存当前上下文，并在新会话中引用该文件；
-   - 用 `prototype` 以可丢弃代码回答问题；
-   - 再用 `handoff` 把结论带回原想法会话。
+2. **分支——所有问题都能通过讨论确定吗？** 如果某个问题需要 runnable answer，例如状态、business logic 或必须亲眼比较的 UI，则 detour 到 `prototype`。在 phase boundary 按 [Phase Boundaries](references/phase-boundaries.md) 选择承载方式：同一 task 可以保留 Primary Source 时 Continue；prototype 需要独立且可 AFK 时使用 Subagent；只有切换宿主、目录或 worktree 等确实需要 portability 时，才用 `$handoff` 往返。
 3. **分支——是否需要多个会话才能完成？**
    - **是**：用 `to-spec` 把讨论整理成规格，再用 `to-tickets` 拆成 tracer-bullet tickets，并声明 blocking edges。远程 tracker 使用 native blocking；本地 tracker 使用一票一文件。随后每个 ticket 都在新鲜上下文中单独调用 `implement`。
    - **否**：在当前上下文直接调用 `implement`。
@@ -29,7 +26,7 @@ disable-model-invocation: true
 
 步骤 1–3 应留在一个连续上下文中：在 `to-tickets` 完成前不要 compact 或 clear，使访谈、规格和 tickets 建立在同一套推理上。每个 `implement` 随后从 ticket 开始，使用独立的新鲜上下文。
 
-接近当前宿主与模型的可靠推理区边缘时，就提前用 `handoff` 转到新会话；不要等到判断质量已经下降。这里不依赖固定 token 数，因为不同宿主与模型的有效上下文不同。
+只在 phase boundary 做这项选择；按 Continue → Clear / fresh context → `$handoff` → Subagent → Compact 的顺序，首个 yes 即为结果。若下一阶段需要当前 context 作为 Primary Source，或当前宿主与模型的可靠推理区仍足够，优先 Continue；若 relevant context 不能继续容纳下一阶段，使用宿主真实的 Compact 能力，而不是伪造固定 token 阈值。
 
 ## 入口支线
 
@@ -50,18 +47,22 @@ disable-model-invocation: true
 
 词语本身是问题时可直接调用；否则由上层流程按需调用。
 
-## 跨会话
+## Phase Boundaries
 
-- **`handoff`**：当前会话已满、需要分叉到 prototype，或要交给其他 agent/人工时，把上下文写成 Markdown 文件。不要留在原处继续；打开新会话并引用该文件。它是上下文窗口之间的桥。
-- **宿主内置 compact**：留在同一会话，仅将较早消息摘要化。只在阶段之间的有意断点使用；不要在阶段中途 compact。`handoff` 创建新的继续点，compact 延续原会话。
+`$handoff` 只在需要 portability 时使用：跨宿主、跨目录或仓库、交给同事，或 mid-phase 分叉 side task。相同宿主、相同目录且 context 仍 relevant 时，它不是一般 context-window bridge。
+
+读取 [phase-boundaries.md](references/phase-boundaries.md)，按完整 ordered tree 比较 Continue、Clear / fresh context、`$handoff`、Subagent 与 Compact。除 Continue 外都会把 Primary Source 变成 lossy Secondary Source，所以先排除 Continue；Compact 是树底部的 default，而不是 first reach。
 
 ## 独立能力
 
 - **`grill-me`**：无代码库、无本地文档写入的深入访谈。
-- **`prototype`**：用从一开始就可丢弃的小程序回答一个设计问题；保留答案，删除或隔离实验代码。
+- **`grilling`**：可被其他 skills 复用的访谈 primitive；以 rounds 询问整个 frontier，facts 由 agent 查明，decisions 由用户作出。
+- **`prototype`**：用从一开始就可丢弃的小程序回答一个设计问题；保留答案，把完整实验代码移出 main 并留在带 context pointer 的 throwaway branch。
 - **`research`**：把阅读工作交给 background agent，以一手资料形成带引用的 Markdown artifact。研究为主流程提供材料，不代替后续判断。
+- **`to-questionnaire`**：当阻塞信息在另一位知识持有者手里时，先询问 send 而不是 subject，再生成交给对方填写的 discovery questionnaire。回答可进入 `grill-with-docs` 或 `to-spec`。
+- **`wait-what`**：上一条消息没有讲清楚时，用缺失 context 和项目 canonical terms 重新讲述；它只修复当前消息。
 - **`teach`**：以指定目录为状态化工作区，跨会话学习一个主题。
-- **`writing-great-skills`**：创建、改写、本地化或评估 skills。
+- **`writing-for-agents`**：创建或改写供 agent 使用的文档，包括 skills、`AGENTS.md` / `CLAUDE.md` 和由 Context Pointer 到达的 reference。
 - **`resolving-merge-conflicts`**：处理已经开始的 merge/rebase 冲突，不主动发起合并。
 
 ## 路由与授权

package/skills/ask/references/phase-boundaries.md

@@ -0,0 +1,70 @@
+# Phase Boundaries
+
+**Phase** 是一个 task 内的一段工作，例如 grilling、implementation 或 QA。定义刻意保持 fuzzy：当你想到“好，这一段完成了”，一个 phase 就结束。
+
+**Phase boundary** 是两个 phases 之间的间隙，也是唯一应该做下面选择的位置。Mid-phase 没有这项选择：Continue，或把剩余工作拆给 subagents。Mid-phase 压缩会让 agent 丢失正在处理的 thread。
+
+## 五个选项
+
+| Option | 作用 |
+| --- | --- |
+| **Continue** | 留在当前 task，不发生 context switch。 |
+| **Clear / fresh context** | 在完全不携带当前 context 的新 task 中开始。宿主有原生 clear 时使用该能力，否则显式新建 task。 |
+| **`$handoff`** | 写一份 portable Markdown，并用它在其他位置启动 task。 |
+| **Subagent** | 把任务发送到独立 context window，等待其报告返回。 |
+| **Compact** | 用宿主真实的 context compaction / summary 能力压缩当前 context，再继续下一阶段。 |
+
+## 决策树
+
+在 boundary 从上到下判断，第一个 **yes** 获胜。
+
+### 1. 能否继续留在当前任务
+
+有两种 yes：
+
+- 下一 phase 需要当前 phase 作为 **Primary Source**；
+- 当前宿主与模型的可靠推理区仍足以容纳下一 phase。
+
+Grilling → implementation 是标准 yes：implementation 需要逐字的 reasoning，而不是它的 summary。Continue 不花时间，也不损失信息，所以必须先排除它，再考虑其他动作。
+
+### 2. 当前上下文是否与下一阶段无关
+
+当前 task 中的 exploration、decisions 与 dead ends 是否都可丢弃？如果是，选择 **Clear / fresh context**。这是最便宜的切换：不需要写文档或生成 summary，并把完整 window 交还给下一阶段。
+
+判断错误的成本是单向的。清掉 relevant context 会丢失已经建立的 _why_，之后重新读取 diff 也无法恢复。
+
+### 3. 是否真的需要 handoff
+
+`$handoff` 很窄，只在下列情况需要：
+
+- 切换到 **new harness**；
+- 移动到 **new directory**、worktree 或 repo；
+- 把工作交给 **colleague**；
+- 不打断当前工作地分叉一个 mid-phase **side task**。
+
+这就是完整 clause。Handoff 购买的是 **portability**——一份可以移动的文件。如果没有任何内容需要移动，就不需要 handoff。
+
+### 4. 任务能否 AFK 完成
+
+任务是否已经足够窄，可以在人离开键盘后独立执行，不需要 steering？如果是，交给 **Subagent**，当前 task 保持不动。自动 review 是标准例子：subagent 读取 diff 并返回报告，执行期间不需要用户。
+
+### 5. 否则选择 Compact
+
+Context 仍然 relevant、宿主和目录不变，而且用户需要留在 loop 中时，决策树落到 **Compact**。给 compaction 一条说明，明确下一 phase 需要什么，例如“接下来要 QA 这个区域”，使 summary 保留所需材料。
+
+Compact 是 **default, not the first reach**。它位于树的底部，因为前四个问题都更便宜或更精确。从 Compact 开始的 Failure Mode，是一个 fresh task 对 summary 压平的 decision 产生自信但错误的理解。
+
+## Primary Source 与 Secondary Source
+
+除 Continue 外，每个选择都会把 **Primary Source** 转成 **Secondary Source**：原 task 的完整发生过程被它的 summary 或空 context 取代。
+
+| Source | Information | Noise | Room to move |
+| --- | --- | --- | --- |
+| Primary（Continue） | Full | Lots | Little |
+| Secondary（Compact、`$handoff` 或 fresh context） | Lossy | Less | Lots |
+
+这就是问题 1 放在最前面的原因：只有 staying 的成本大于信息损失时，才支付 lossiness。
+
+## 这些是 Judgment Calls
+
+这些问题没有客观唯一答案；同一个 boundary 在不同日期可能走向不同分支。价值来自只在 boundary 判断，并且每次都按固定顺序询问。

package/skills/grill-me/SKILL.md

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

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

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

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

@@ -1,12 +1,12 @@
 ---
 name: grill-with-docs
-description: 对计划或设计开展毫不松懈的逐题访谈，并在决定形成时同步维护项目领域文档与重要决策。
+description: 对计划或设计开展毫不松懈的分轮访谈，并在每轮决定形成时同步维护项目领域文档与重要决策。
 disable-model-invocation: true
 ---
 
 # Grill With Docs
 
-运行 `$grilling`，并在同一会话中使用 `$domain-modeling`。`$grilling` 负责沿决策树一次一题形成共同理解；`$domain-modeling` 负责把刚刚确认的领域语言和长期重要决定沉淀到正确文档。两者保持各自职责，不复制流程。
+运行 `$grilling`，并在同一会话中使用 `$domain-modeling`。`$grilling` 负责沿 design tree 以 rounds 询问整个 frontier；`$domain-modeling` 负责把当前 round 刚刚确认的领域语言和长期重要 decisions 沉淀到正确文档。两者保持各自职责，不复制流程。
 
 ## 写入边界
 
@@ -17,12 +17,12 @@ disable-model-invocation: true
 ## 组合循环
 
 1. 读取当前计划或设计、相关项目规则、已有 `CONTEXT.md`、上下文映射和 ADR。可以查明的事实直接查明。
-2. 让 `$grilling` 选择并提出当前唯一的问题，给出推荐答案并等待用户决定。
-3. 决定形成后，让 `$domain-modeling` 判断它是否属于稳定领域语言或值得长期保留的架构决策：
+2. 让 `$grilling` 计算并提出当前整个 frontier，逐题给出推荐答案，然后等待用户回答本轮。
+3. 对本轮已经由用户确认的每个 decision，让 `$domain-modeling` 判断它是否属于稳定领域语言或值得长期保留的架构决策：
    - 已确认的主术语、紧凑定义、上下文边界和不变量，最小化更新到相应 `CONTEXT.md`；
    - 改变成本高、缺少背景会令人意外且存在真实替代方案的决定，按仓库既有格式创建、更新或 supersede ADR；
    - 假设、临时偏好、普通实现细节和未决问题保留在访谈状态中，不写成项目事实。
-4. 文档处理完成后把控制权交回当前 `$grilling` 循环，再进入下一个决策分支。不要递归启动新的访谈。
+4. 本轮文档处理完成后把控制权交回当前 `$grilling`，根据回答重新计算 frontier，再进入下一轮。不要递归启动新的访谈。
 5. 用户确认形成共同理解后，报告已确认结论、实际修改的文档、未写入的假设与未决项，以及适合的下一入口。
 
 更新应随着决定形成而发生，不把所有结论积压到会话末尾。发现新回答与现有代码或文档冲突时，展示证据并让用户裁决，不静默覆盖。

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

@@ -1,6 +1,6 @@
 interface:
   display_name: "Grill With Docs"
-  short_description: "逐题挑战计划或设计，同时维护 CONTEXT 与必要 ADR"
+  short_description: "分轮挑战计划或设计，同时维护 CONTEXT 与必要 ADR"
   default_prompt: "请使用 $grill-with-docs 深入检验这个方案，并同步维护已确认的领域术语与重要决策。"
 policy:
   allow_implicit_invocation: false

package/skills/grilling/SKILL.md

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

@@ -78,7 +78,7 @@ 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 被澄清时立即更新；

package/skills/prototype/SKILL.md

@@ -11,7 +11,7 @@ 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** 时使用：这些模型在纸面上看起来合理，只有真正经过具体情形时才会显出不对劲。
 
-## 适用情形
+因为它只有一个文件、无需安装，所以可以直接交给非开发者，例如 designer、PM 或 domain expert，让他们亲自感受模型。因此它必须使用他们的语言，而不是代码作者的语言。
 
-- “我不确定 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 的尝试；它们正是纸面上难以推理的部分。
 
-- “这个动作此时不应该合法。”
-- “我以为这个字段会变成另一种状态。”
-- “这里缺少一个状态。”
+外观可以漂亮，但要克制：清楚的 typography、宽松的 spacing、一个 accent colour。不要 animations 或 gimmicks，不要让任何东西与 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`。