@netpilot/skills 0.7.0 → 0.9.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "netpilot-skills",
       "source": "./",
       "description": "中文工程协作 skills 与可组合工作流",
-      "version": "0.7.0",
+      "version": "0.9.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.9.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.9.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,23 @@
 
 ## Unreleased
 
+## 0.9.0
+
+- 新增 `wizard`，为必须由人完成的控制台与凭证步骤生成分阶段 Bash 向导；保留上游公共模板，并补齐输入中断、dotenv 值保真和明确 GitHub 仓库确认边界。
+- `ask` 增加明确小任务的短路径；`implement` 按需加载验证证据指南，`writing-for-agents` 按需加载独立行为评测指南；`research` 与 `grilling` 在子代理不可用时明确串行降级。
+- 对照上游 1.2.3 与 2026-09-04 默认分支，补齐调试展示前脱敏、HITL 只采集脱敏观察结果、多 context 导航、TDD 设计参考入口、最高层测试 Seam 和架构 ADR 冲突筛选约束。
+- 现有 Skills 采用中文指令与英文行为锚点：翻译普通说明和问卷，补充关键术语中文定义，保留命令、字段、状态标签、步骤顺序与例子作用；静态契约验证不代表模型行为等效。
+
+## 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

@@ -54,6 +54,7 @@ Codex 使用 `$skill-name`；Claude Code 用户级安装使用 `/skill-name`。
 | 重要新功能 | `grill-with-docs → to-spec → to-tickets → implement → code-review` |
 | 明确小改动 | `implement → 定向验证` |
 | Bug 根因未知 | `diagnosing-bugs → tdd → code-review` |
+| 必须由人操作控制台 | `wizard → 用户执行 → 原任务` |
 | 跨会话学习 | `teach → 按需 research / grilling → 下一节课` |
 | 跨会话交付 | `to-spec → to-tickets → implement → handoff` |
 
@@ -70,9 +71,11 @@ 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 |
+| 协作 | `wizard` | 必须由人操作控制台、录入凭证或完成迁移步骤 | 供用户运行的交互式 Bash 向导 |
 | 设计 | `domain-modeling` | 统一术语、状态和不变量 | Glossary、模型与必要 ADR |
 | 设计 | `codebase-design` | 判断 Module、Interface 和 Seam | 设计词汇与接口比较 |
 | 设计 | `improve-codebase-architecture` | 扫描架构摩擦和 deepening 机会 | HTML 报告与候选项 |
@@ -85,7 +88,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
 
@@ -106,6 +110,7 @@ Agents 默认继承当前 Codex 会话模型。代码定位直接使用 Codex
 - 双宿主调用 metadata 由仓库校验器保持一致；调用分类不等于写入权限。
 - 同步器只更新本项目管理且用户未修改的文件，不提供隐式强制覆盖。
 - 上游方法采用 conservation-first 本地化：保留限定词、步骤顺序、失败边界、诊断例子和有方法价值的附件，只移除个人化表达、不存在的命令，并适配真实宿主权限。
+- `wizard` 需要可用 Bash（Windows 可用 Git Bash / WSL）；agent 生成并静态检查，用户执行。模板只支持单行 dotenv，GitHub 写入要求明确仓库和实际确认。
 
 ## 开发
 

package/docs/skill-evolution.md

@@ -0,0 +1,43 @@
+# Skill 增补与优化方案
+
+本次分析承接中文化工作，目标是补齐真实能力缺口，同时保留现有方法的范围、顺序、行为锚点和失败边界。来源固定为 Matt Pocock skills 的 `3cca18b368ae95cdbdebbff572ccafa662551015`（2026-09-04，package 1.2.3）；这是一次方案与验证记录，不建立长期逐 skill 吸收台账。
+
+## 是否新增
+
+| 候选 | 决定 | 原因与归属 |
+| --- | --- | --- |
+| `wizard` | 新增，model-invoked | 现有实现、访谈和交接不能替代人在控制台操作、隐藏录入凭证、按阶段返回结果的交互式产物；保留完整模板和生成流程。 |
+| 独立 `verification` | 不新增 | 验证是交付门禁；将按证据选择检查、UI 观察和 blocked 报告放入 `implement` 的按需参考。 |
+| 独立 skill 评测入口 | 不新增 | 评测属于 `writing-for-agents` 的条件分支，新增按需参考即可。 |
+| `retro` | 暂缓 | 上游 in-progress 版本明确是 STUB；尚无成熟流程，不能当成已验证方法引入。 |
+| `loop-me` | 暂缓 | 上游 Beta 的个人工作流约定尚未证明在本仓库有独立价值；需真实重复失败场景再评估。 |
+| `implement-spec` | 不新增 | 与现有 `implement` 重叠；其委派与 PR 路径需要额外适配，不能默认扩张写入权限。 |
+| `claude-handoff` | 不新增 | 与跨宿主 `handoff` 重叠，宿主专有路径没有必要成为第二入口。 |
+| setup、hooks、项目 deep-module 初始化 | 不新增 | 项目脚手架与 harness engineering 属于独立 Harness；tracker 配置已有现成归属。 |
+
+判断依据是独立触发价值和职责缺口，不以数量覆盖上游为目标。成熟与试验目录见 [engineering](https://github.com/mattpocock/skills/tree/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering) 与 [in-progress](https://github.com/mattpocock/skills/tree/3cca18b368ae95cdbdebbff572ccafa662551015/skills/in-progress)。
+
+## 现有方法的定向调整
+
+- `ask`：先识别目标、范围、结果明确的小任务，复用现有授权，避免重复进入访谈；复杂任务仍保留原来的主流程与阶段边界。
+- `implement`：通过 Context Pointer 加载 [验证证据指南](../skills/implement/references/verification.md)，区分测试通过、真实 UI 观察、执行失败与环境阻塞；审查不能替代验证。
+- `writing-for-agents`：通过 Context Pointer 加载 [行为验证方法](../skills/writing-for-agents/references/behavioral-evaluation.md)，使用独立场景与可观察结果，区分静态检查、单次前向观察和反复 A/B 证据。
+- `research`、`grilling`：子代理不可用或任务不允许时，由当前 agent 串行保持同样的事实与证据要求；不虚构委派，不把可查事实交给用户猜。
+
+普通说明继续用中文，`frontier`、`Seam`、`Context Pointer` 等行为锚点及 canonical 名称保留英文。新增参考只在对应分支加载，避免每次执行承担所有评测或验证细节。
+
+## Wizard 的适配依据
+
+保留上游阶段、清屏、进度、浏览器路径、隐藏输入、env upsert、GitHub 写入和结束摘要的作用，以及公共 library 与任务阶段分离的结构。生成脚本只替换 `STAGES` 以下部分。中文解释配合界面实际英文 label，用户操作真实控制台，agent 静态检查生成物。
+
+对原模板执行隔离测试时，5 项测试中 4 项失败：含 `#` 与空格的 env 值不能准确往返、输入 EOF 后继续保存、多行值能注入额外键、GitHub 写入从 cwd 隐式选仓库。这些是可复现的适配依据，不是为了统一风格而重写模板。
+
+因此增加单行 dotenv 格式检查与保真序列化、输入中断停止、明确 `GH_REPO` 与实际确认；秘密经 stdin 传给 GitHub CLI。复杂现有格式拒绝写入并保留原文件，转交项目认可的配置工具。另补浏览器启动器不可用时的手动路径与未确认写入摘要。值格式的独立测试 oracle 使用 [Node dotenv 解析器](https://nodejs.org/api/environment_variables.html)；远程命令参数依据 [gh secret set](https://cli.github.com/manual/gh_secret_set) 和 [gh variable set](https://cli.github.com/manual/gh_variable_set)。
+
+该模板不是通用 dotenv 编辑器：不支持复杂转义、多行或行尾注释，不提供多文件事务、并发编辑保证或任意项目配置语法兼容。需要可运行 Bash；不能把找到 `bash.exe` 等同于能够执行。原始凭证不进入 agent 对话，生成授权不扩展为运行、远程写入或不可逆动作授权。
+
+## 验收边界
+
+本轮使用真实 Bash 和临时目录测试模板，外部 GitHub 调用均为 stub，凭证均为假值；完整仓库验证覆盖双宿主 metadata、打包、安装与文件冲突保护。静态检查与隔离运行不等于真实服务配置成功，也不证明所有中英文模型行为等效。中文化对照方法和此前证据见 [本地化分析](skill-localization.md)。
+
+独立前向场景检查中，一个未继承本轮讨论的 agent 分别处理明确单句文案任务和需求明确的四会话任务：前者选择直接定向实施，后者保留规格与拆票链路。此结果只支持这两个路由场景，不外推为整个 skill 的普遍效果。独立 Spec 审查曾发现短路径条件过宽，已修正；Standards 审查未发现需要报告的问题。

package/docs/skill-localization.md

@@ -0,0 +1,60 @@
+# Skills 中文化分析与验收方案
+
+核验日期：2026-09-05。范围为仓库现有 23 个 skills 及其运行时附件；本文记录本次分析与验收方法，不维护逐 skill 的来源台账。
+
+## 来源与最新变化
+
+本次从公开 Git 仓库读取 `HEAD` 并完整克隆到临时目录，锁定 `3cca18b368ae95cdbdebbff572ccafa662551015`，提交时间为 2026-09-04。包版本为 `1.2.3`。版本号用于描述发行版本，commit 用于复核具体内容；两者不能互相替代。[固定提交](https://github.com/mattpocock/skills/commit/3cca18b368ae95cdbdebbff572ccafa662551015)、[固定版本 package.json](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/package.json)
+
+上游 `1.2.3` 明列三类改动：`diagnosing-bugs` 增加展示前脱敏；审查与架构探索的子代理说明移除 Claude 专属工具／角色名；`wizard` 移除时间估算。本地已有跨宿主子代理适配，需要补入脱敏约束，并恢复架构探索的子代理动作。`wizard` 不在本次既有技能范围内；它包含人工操作脚本、环境配置和 CI 凭证写入，不能作为翻译附带引入。[固定版本 CHANGELOG](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/CHANGELOG.md)、[Wizard 原文](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/wizard/SKILL.md)
+
+## 为什么选择中文正文与英文锚点
+
+上游强调的是可预测的过程：Leading Word 同时影响正文执行和 pointer 触发；完成条件要可检查、覆盖充分；信息层级、相邻放置和按需展开会影响模型是否关注正确材料。上游也要求通过实际运行判断 No-Op。这些是语言选择的机制依据，没有证明英文普遍优于中文，也没有证明翻译天然等效。[Writing for Agents](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/productivity/writing-for-agents/SKILL.md)
+
+以下是本次工程判断：中文正文便于中文使用者检查条件与例外；保留少量已有英文术语，可以继续连接技能名称、代码和上游方法。完整英文保真成本最低，但不满足中文可读性目标；全部译成中文可能切断共享术语；逐段中英并排则产生两份需同步的正文。因此选择单份中文指令，配必要英文锚点。
+
+| 内容类型 | 选择与理由 | 例子 |
+| --- | --- | --- |
+| 普通叙述、问题、说明 | 翻译完整句子，减少不必要的夹杂 | recipient → 接收者；paragraph → 段落 |
+| 方法与行为锚点 | 保留英文，首次补中文定义 | frontier、tight、red、tracer bullet |
+| 共享设计词汇 | 保留同一英文主名称，复用已有定义 | Module、Interface、Seam、Adapter、Depth |
+| 精确限定词 | 翻译语义，完整保留条件、量词、时机与强度 | each → 每项；where possible → 尽可能 |
+| 名称、命令、文件路径、字段和状态标签 | 原值不变，解释放在外面 | `$tdd`、`CONTEXT.md`、`ready-for-agent`、`<REDACTED>` |
+| 被其他文档识别的模板章节 | 保留原值，必要时追加中文解释 | `Blocked by`、`Destination`、`Suggested Skills` |
+| 仅面向人的问卷和业务例子 | 中文化，并保留例子区分分支的作用 | 手机银行客户查看账户余额；先问发给谁和需要什么 |
+| 用措辞本身说明提示机制的例句 | 保留英文原句并解释 | `tight` 与 `red` 的替换示例 |
+
+`codebase-design` 特别要求统一 Module、Interface 等词，并明确排除容易混淆的相邻词，因此这些词不按普通英文单词逐个替换。调用分类与 Router 权限也保持本地双宿主规则，翻译不改变可达性或动作授权。[设计词汇](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/codebase-design/SKILL.md)、[调用机制](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/productivity/writing-for-agents/SKILL-MECHANICS.md)
+
+## 实施切片与保真边界
+
+1. 固定版本并读取上游变更、相关正文和附件；按普通语言、行为锚点、协议值分类。完成条件：修改使用的来源可以回到固定 commit 复核。
+2. 先固定遗漏行为的失败契约，再补回上游规则。完成条件：脱敏、上下文导航、TDD 参考入口、Seam 选择和 ADR 筛选约束都有定向证据。
+3. 在原位置翻译说明和示例，补关键术语定义，保留短技能和 reference 的原有形状。完成条件：没有因翻译丢失条件、反例、问题格式或引用。
+4. 运行 `npm run verify`，之后独立审查最终 diff。完成条件：测试结果与审查结果分别报告，剩余限制明确。
+
+补回的不只是新发行内容，也包括本地化已有遗漏：`wait-what` 通过 `CONTEXT-MAP.md` 导航；TDD 在 Interface 形状未确定时查共享词汇；规格对现有和新建 Seam 都选择尽可能高的层级，并恢复银行用户故事例子；架构候选只有真实摩擦足以重新审视 ADR 时才提出，记录拒绝理由时跳过临时或自明原因。它们分别改变材料可达性、选择范围与失败边界。[Wait What](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/productivity/wait-what/SKILL.md)、[TDD](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/tdd/SKILL.md)、[To Spec](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/to-spec/SKILL.md)、[架构探索](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/improve-codebase-architecture/SKILL.md)
+
+本地必要的权限、安全与宿主适配继续保留。例如 Node.js HITL 模板继续跨平台运行，新增与上游 Bash 模板对应的回显提醒和脱敏提示；这不代表脚本能自动识别所有秘密。不得用真实凭证验证。[诊断规则](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/diagnosing-bugs/SKILL.md)、[HITL 模板](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/diagnosing-bugs/scripts/hitl-loop.template.sh)
+
+## 模型行为对照方案
+
+静态测试覆盖的是文本契约、引用、结构和 metadata，不能据此声称模型行为等效。要判断效果，应区分两种比较：原始上游与本地的比较包含权限／宿主差异；隔离语言因素的比较则需要两份拥有相同宿主和权限适配的中英文材料。
+
+固定同一模型版本、推理强度、宿主、工具集、仓库快照、输入与用户回答；每次使用新会话且只加载一个版本。每个场景每种语言至少运行三次，交错运行顺序；高方差场景追加次数。三次只是发现明显差异的起点，不构成统计等效证明。只用临时仓库、假数据和工具桩，不对真实 tracker 或用户配置写入。
+
+| 场景 | 同时检查中英文版本的可观察行为 |
+| --- | --- |
+| 访谈有两个独立问题及一个依赖问题 | 同轮询问整个 frontier；依赖问题延后；用户确认前不行动 |
+| 问题依赖可查事实 | 事实由 agent 查；探索只阻塞下游问题 |
+| 问卷接收者掌握缺失信息 | 先问接收者，再问需要拿回什么；每个需求由一个问题覆盖 |
+| 调试日志含虚构认证头 | 展示前脱敏；保留故障信号；无 red-capable loop 不进入假设阶段 |
+| 现有高层和低层测试入口并存 | 优先现有且尽可能高的 Seam；接口设计未定时读取共享参考 |
+| 同一设计可选 Logic 或 UI prototype | 分支正确；保留状态观测、真实页面优先与原型证据；不自动写正式实现 |
+| 大范围机械重构无法逐片 green | 选择 expand–migrate–contract；必要时只在最终集成节点承诺 green |
+| 多 context 仓库中要求重述 | 导航到对应 glossary，补缺失背景，保持简短 |
+| ADR 禁止某个理论重构 | 仅在真实摩擦足以重审时展示候选，不重复建议已确定且无新证据的选择 |
+| 文档新增或改写 | 保持步骤顺序、原位完成条件、按需附件和调用边界 |
+
+每次保留完整输入、工具轨迹、输出与逐条件判定。比较触发正确率、关键条件遗漏、越权、过早结束、返工与任务结果；不要只比较篇幅。任一新增硬边界失败即阻断该切片；差异先判断是翻译、宿主适配还是模型随机性，再修订。没有这类重复运行记录时，结论只能是“已做语义与结构保真核对；行为等效未验证”。

package/package.json

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

package/skills/ask/SKILL.md

@@ -8,17 +8,18 @@ disable-model-invocation: true
 
 你不需要记住每个 skill，因此从这里选择。
 
-**Flow** 是 skills 之间的一条路径。多数工作沿一条 **main flow** 前进，若干 **on-ramp** 汇入主流程；其余能力要么独立使用，要么作为底层词汇层。
+**Flow（流程路径）** 是 skills 之间的一条路径。多数工作沿一条 **main flow（主流程）** 前进，若干 **on-ramp（入口支线）** 汇入主流程；其余能力要么独立使用，要么作为底层词汇层。
 
-## 主流程：idea → ship
+## 先判断是否需要完整流程
+
+用户已经给出明确目标、范围和可检查结果的小改动，直接建议 `$implement`；已有授权覆盖该工作时继续处理，不重复访谈。只读解释或一次定向检查可直接完成。方向、关键决定或验收边界尚未确定时，从下方访谈分支开始；目标已明确但需要多会话交付的工作，仍进入规格与拆票分支。直接处理不跳过项目要求的计划、验证或动作授权。
+
+## 主流程：从想法到交付
 
 这是多数产品与工程工作的路线。
 
 1. **`grill-with-docs`**：通过访谈磨清想法。有代码库，并希望把结论保留到 `CONTEXT.md` 或 ADR 时从这里开始。没有代码库则使用 `grill-me`。二者都复用同一个 `grilling` 访谈引擎；区别是 `grill-with-docs` 会留下项目文档。
-2. **分支——所有问题都能通过讨论确定吗？** 如果某个问题需要可运行答案，例如状态、业务逻辑或必须亲眼比较的 UI，则通过 `handoff` 往返一次原型会话：
-   - 用 `handoff` 保存当前上下文，并在新会话中引用该文件；
-   - 用 `prototype` 以可丢弃代码回答问题；
-   - 再用 `handoff` 把结论带回原想法会话。
+2. **分支——所有问题都能通过讨论确定吗？** 如果某个问题需要可运行的答案，例如状态、business logic 或必须亲眼比较的 UI，则转入 `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 +30,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 阈值。
 
 ## 入口支线
 
@@ -39,7 +40,7 @@ disable-model-invocation: true
 
 ## 代码库健康
 
-`improve-codebase-architecture` 用于日常发现 deepening opportunities。它是寻找候选项的 survey；选定候选后，形成一个想法并回到 `grill-with-docs`。`codebase-design` 则提供设计候选 Module 形状的工作台和统一词汇。
+`improve-codebase-architecture` 用于日常发现 deepening opportunities。它是寻找候选项的扫描；选定候选后，形成一个想法并回到 `grill-with-docs`。`codebase-design` 则提供设计候选 Module 形状的工作台和统一词汇。
 
 ## 底层词汇
 
@@ -50,19 +51,24 @@ disable-model-invocation: true
 
 词语本身是问题时可直接调用；否则由上层流程按需调用。
 
-## 跨会话
+## 阶段边界（Phase Boundaries）
+
+`$handoff` 只在需要 portability 时使用：跨宿主、跨目录或仓库、交给同事，或 mid-phase 分叉 side task。相同宿主、相同目录且 context 仍 relevant 时，它不是一般 context-window bridge。
 
-- **`handoff`**：当前会话已满、需要分叉到 prototype，或要交给其他 agent/人工时，把上下文写成 Markdown 文件。不要留在原处继续；打开新会话并引用该文件。它是上下文窗口之间的桥。
-- **宿主内置 compact**：留在同一会话，仅将较早消息摘要化。只在阶段之间的有意断点使用；不要在阶段中途 compact。`handoff` 创建新的继续点，compact 延续原会话。
+读取 [phase-boundaries.md](references/phase-boundaries.md)，按完整有序决策树比较 Continue、Clear / fresh context、`$handoff`、Subagent 与 Compact。除 Continue 外都会把 Primary Source 变成有损的 Secondary Source，所以先排除 Continue；Compact 是树底部的默认兜底选项，而不是第一选择。
 
 ## 独立能力
 
 - **`grill-me`**：无代码库、无本地文档写入的深入访谈。
-- **`prototype`**：用从一开始就可丢弃的小程序回答一个设计问题；保留答案，删除或隔离实验代码。
+- **`grilling`**：可被其他 skills 复用的基础访谈能力；以 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`**：上一条消息没有讲清楚时，用缺失的上下文和项目 canonical terms 重新讲述；它只修复当前消息。
 - **`teach`**：以指定目录为状态化工作区，跨会话学习一个主题。
-- **`writing-great-skills`**：创建、改写、本地化或评估 skills。
+- **`writing-for-agents`**：创建或改写供 agent 使用的文档，包括 skills、`AGENTS.md` / `CLAUDE.md` 和由 Context Pointer 到达的 reference。
 - **`resolving-merge-conflicts`**：处理已经开始的 merge/rebase 冲突，不主动发起合并。
+- **`wizard`**：流程被必须由人完成的控制台操作或输入阻塞时，生成交互式 Bash 向导。确认人工阶段后交付用户执行，收到脱敏结果再返回原流程；agent 能自行完成的操作不转交给人。
 
 ## 路由与授权
 

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

@@ -0,0 +1,70 @@
+# Phase Boundaries（阶段边界）
+
+**Phase（阶段）** 是一个 task 内的一段工作，例如 grilling、implementation 或 QA。定义刻意保持模糊：当你想到“好，这一段完成了”，一个 phase 就结束。
+
+**Phase boundary（阶段边界）** 是两个 phases 之间的间隙，也是唯一应该做下面选择的位置。Mid-phase 没有这项选择：Continue，或把剩余工作拆给 subagents。Mid-phase 压缩会让 agent 丢失正在处理的 thread。
+
+## 五个选项
+
+| 选项 | 作用 |
+| --- | --- |
+| **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 需要完整的推理原文，而不是它的摘要。Continue 不花时间，也不损失信息，所以必须先排除它，再考虑其他动作。
+
+### 2. 当前上下文是否与下一阶段无关
+
+当前 task 中的探索、决定与走不通的路径是否都可丢弃？如果是，选择 **Clear / fresh context**。这是最便宜的切换：不需要写文档或生成 summary，并把完整上下文窗口交还给下一阶段。
+
+判断错误的成本是单向的。清掉 relevant context 会丢失已经建立的 _why_，之后重新读取 diff 也无法恢复。
+
+### 3. 是否真的需要 handoff
+
+`$handoff` 很窄，只在下列情况需要：
+
+- 切换到新的宿主环境；
+- 移动到新的目录、worktree 或 repo；
+- 把工作交给同事；
+- 不打断当前工作地分叉一个 mid-phase **side task**。
+
+这就是完整适用条件。Handoff 购买的是 **portability**——一份可以移动的文件。如果没有任何内容需要移动，就不需要 handoff。
+
+### 4. 任务能否 AFK 完成
+
+任务是否已经足够窄，可以在人离开键盘后独立执行，不需要用户继续指引？如果是，交给 **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 的完整发生过程被它的摘要或空 context 取代。
+
+| 来源 | 信息 | 噪声 | 可用余量 |
+| --- | --- | --- | --- |
+| Primary（Continue） | 完整 | 多 | 少 |
+| Secondary（Compact、`$handoff` 或 fresh context） | 有损 | 较少 | 多 |
+
+这就是问题 1 放在最前面的原因：只有 staying 的成本大于信息损失时，才支付 lossiness。
+
+## 这些判断依赖具体情境（Judgment Calls）
+
+这些问题没有客观唯一答案；同一个 boundary 在不同日期可能走向不同分支。价值来自只在 boundary 判断，并且每次都按固定顺序询问。

package/skills/code-review/SKILL.md

@@ -7,8 +7,8 @@ description: 当用户要求审查 branch、PR、工作树或相对某个固定
 
 审查 `HEAD` 或工作树相对固定点的变化，并严格分成两条互不遮蔽的轴：
 
-- **Standards**：代码是否遵守仓库文档化规范和固定的 Fowler smell baseline。
-- **Spec**：代码是否忠实实现来源 issue、PRD、spec 或验收标准。
+- **Standards（规范）**：代码是否遵守仓库文档化规范和固定的 Fowler smell baseline。
+- **Spec（规格）**：代码是否忠实实现来源 issue、PRD、spec 或验收标准。
 
 优先让两个相互隔离的只读子代理并行审查，再由主 agent 聚合。宿主不支持子代理时，串行执行两个隔离 pass，不把一条轴的结论带入另一条。
 
@@ -54,18 +54,18 @@ git ls-files --others --exclude-standard
 
 此外，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**：继承者拒绝大部分继承契约；改用组合或更准确的抽象。
+- **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. 隔离执行两条轴
 

package/skills/codebase-design/SKILL.md

@@ -5,7 +5,7 @@ description: 当用户要设计或改进模块接口、寻找 deepening 机会
 
 # Codebase Design
 
-设计 **deep Module**：把大量行为藏在小型 **Interface** 后，将 Interface 放在干净的 **Seam** 上，并通过该 Interface 测试。目标是为调用者提供 **Leverage**，为维护者提供 **Locality**，并让测试围绕稳定表面展开。
+设计 **deep Module（深模块）**：把大量行为藏在小型 **Interface** 后，将 Interface 放在干净的 **Seam** 上，并通过该 Interface 测试。目标是为调用者提供 **Leverage**，为维护者提供 **Locality**，并让测试围绕稳定表面展开。
 
 ## 统一词汇
 
@@ -63,7 +63,7 @@ Shallow Module = 大 Interface + 少量 Implementation，应尽量避免：
 ## 原则
 
 - **Depth 是 Interface 的性质，不是 Implementation 的大小。** Deep Module 内部仍可由小型、可替换部分组成，只是它们不应泄漏到外部 Interface。Module 可以同时拥有内部测试 seams 与对调用者开放的 external Seam。
-- **Deletion test。** 想象删除这个 Module：如果复杂性随之消失，它只是透传层；如果复杂性重新散落到 N 个调用者，它就在提供价值。
+- **Deletion test（删除检验）。** 想象删除这个 Module：如果复杂性随之消失，它只是透传层；如果复杂性重新散落到 N 个调用者，它就在提供价值。
 - **Interface 就是 test surface。** 调用者和测试跨越同一个 Seam。若测试必须绕过 Interface 进入内部，Module 的形状很可能不对。
 - **一个 Adapter 代表假想 Seam，两个 Adapter 才代表真实 Seam。** 除非确有变化需要隔离，不为可能的未来需求预建 Seam。
 

package/skills/diagnosing-bugs/SKILL.md

@@ -11,6 +11,12 @@ description: 当用户要求 diagnose/debug，或报告复杂故障、异常、
 
 探索代码库时读取相关 `CONTEXT.md` 和 ADR，使术语、Module 与约束保持一致。
 
+## Redact（脱敏）
+
+本 skill 会展示命令、输出和捕获产物。**展示前先将每一处秘密替换为 `<REDACTED>`。** 使用环境变量构建循环，让凭证留在环境中，不出现在展示内容里。捕获产物可能携带认证头；只引用承载诊断信号的行。
+
+脱敏后的输出不足以诊断时，明确说明并询问用户。
+
 ## 阶段 1：建立 feedback loop
 
 **这就是本 skill 的核心。** 只要存在一个能在“这个缺陷”上变红的 tight pass/fail signal，就能通过二分、假设检验和 instrumentation 找到原因。没有它，仅靠阅读代码无法可靠定位。
@@ -56,13 +62,13 @@ description: 当用户要求 diagnose/debug，或报告复杂故障、异常、
 
 - 已尝试什么；
 - 为什么不能得到 red-capable signal；
-- 需要用户提供哪一种条件：可复现环境访问、HAR/日志/core dump/带时间戳录屏等 captured artifact，或添加临时生产 instrumentation 的权限。
+- 需要用户提供哪一种条件：可复现环境访问、HAR/日志/core dump/带时间戳录屏等已经脱敏的 captured artifact（捕获产物），或添加临时生产 instrumentation 的权限。
 
 **没有 loop，不进入假设阶段。**
 
 ### 阶段 1 的完成门禁
 
-必须能给出一个已经实际运行至少一次的命令及其输出，并满足：
+必须能给出一个已经实际运行至少一次的命令及其输出，展示前先脱敏，并满足：
 
 - [ ] **Red-capable**：走真实缺陷路径，并断言用户的精确症状；修复前可 red，修复后可 green。
 - [ ] **Deterministic**：每次 verdict 一致；偶发缺陷则具有固定且足够高的复现率。

package/skills/diagnosing-bugs/scripts/hitl-loop.template.mjs

@@ -3,6 +3,8 @@
 // 先复制到 scratch/debug 位置再按当前缺陷修改。
 // 运行方式：node <path>/hitl-loop.mjs
 // 仅使用 Node.js 内置模块，可在 Windows、macOS 与 Linux 运行。
+// capture 会把结果回显到终端，供 agent 读取；只采集已脱敏的观察结果。
+// 登录留给用户在 step 中完成，不采集密码、token 或其他凭证。
 
 import { stdin as input, stdout as output } from "node:process";
 import { createInterface } from "node:readline/promises";
@@ -38,7 +40,7 @@ try {
 
   await step("打开 http://localhost:3000 并登录。");
   await capture("ERRORED", "点击“Export”按钮。是否出现错误？(y/n)");
-  await capture("ERROR_MSG", "粘贴错误信息；没有则输入 none：");
+  await capture("ERROR_MSG", "粘贴已脱敏的错误信息（秘密替换为 <REDACTED>）；没有则输入 none：");
 
   // --- 到这里结束修改 -------------------------------------------------
 } finally {

package/skills/domain-modeling/SKILL.md

@@ -43,7 +43,7 @@ description: 当用户要建立或收紧领域模型、统一 ubiquitous languag
 
 ## 会话中的工作
 
-### 对照 glossary 挑战用词
+### 对照 glossary（术语表）挑战用词
 
 用户使用的词若与现有 `CONTEXT.md` 冲突，立即指出：
 

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