@netpilot/skills 0.3.2 → 0.6.0

package/skills/teach/references/resources-format.md

@@ -1,28 +1,46 @@
 # `RESOURCES.md` 格式
 
-`RESOURCES.md` 保存经过筛选的可信资料以及可选的真实实践社区。课程中的事实性知识优先来自这里。
+`RESOURCES.md` 是本主题经过筛选的可信来源集合。课程中的 Knowledge 从这里获得，而不是来自参数化猜测；Wisdom 则通过这里记录的真实实践共同体获得。
 
-```markdown
+## 模板
+
+```md
 # {主题} Resources
 
-## Knowledge
+## 知识（Knowledge）
+
+- [{资料类型：标题 — 作者或机构}]({URL})
+  内容：{它可靠回答什么问题}。使用时机：{哪些 lessons 或问题应查它}。版本/日期：{如适用}。
+- [{规范、论文、书籍、官方课程或原始数据}]({URL})
+  内容：{一句说明}。使用时机：{一句说明}。
 
-- [{资料标题} — {作者或机构}]({URL})
-  适用：{它回答什么问题，何时使用}。版本或日期：{如适用}。
+## 判断力来源（Wisdom / Communities）
 
-## Practice and community
+- [{线上或线下共同体}]({URL 或地点})
+  特点：{为什么它具有高质量反馈}。使用时机：{适合检验什么 skill 或判断}。
 
-- [{社区、课程或实践场所}]({URL})
-  适用：{能够获得什么真实反馈}。
+## 资料缺口（Gaps）
 
-## Gaps
-- {当前缺少可靠资料的问题}
+- {mission 需要、但目前没有找到可靠来源的问题}
 ```
 
-规则：
+## 完整条目示例
+
+```md
+## 知识（Knowledge）
+
+- [Node.js File system documentation — Node.js project](https://nodejs.org/api/fs.html)
+  内容：Node.js `fs` API 的官方 contract、异常与平台差异。使用时机：课程需要核验文件读取、写入或路径行为时。版本/日期：记录教学工作区实际使用的 Node.js major version。
+```
+
+示例展示注释的完整度；只有主题确实涉及 Node.js 文件系统且已打开核验时，才把它加入真实 `RESOURCES.md`。
+
+## 规则
 
-- 优先官方文档、规范、原始论文、数据、维护者声明和公认专业资料。
-- 每条都写清用途；无注释链接不进入清单。
-- 标注版本、日期和适用边界，区分事实、推断与经验。
-- 发现资料错误、过时或偏离目标时删除或替换，不用数量掩盖质量。
-- 社区仅作建议；记录用户拒绝参与的偏好，不重复推动。
+- **只收录高可信来源。** 优先官方文档、标准、原始研究、原始数据、公认专家和治理严格的共同体。把营销包装成教育的内容留在清单之外。
+- **每条都注释。** 裸链接几个月后没有价值；说明它覆盖什么、为什么可信、何时使用，并在适用时记录版本或日期。
+- **区分 Knowledge 与 Wisdom。** 资料可以只属于一组。Knowledge 支撑可核验主张；共同体用于把 skills 放进真实世界检验。
+- **显式暴露缺口。** mission 需要但没有可靠资料时，新增 `Gaps`，让后续 research 有清楚问题和停止条件。
+- **无情裁剪。** 发现资料错误、浅薄、过期或偏离 mission 时删除或替换；五个锋利来源胜过三十个一般链接。
+- **记录共同体偏好。** 用户不想参与共同体时在这里记录，后续会话不再反复推动。
+- **不伪造来源。** 模板占位符不是可用引用；加入清单前必须实际打开并核验目标资料。

package/skills/to-spec/SKILL.md

@@ -1,76 +1,81 @@
 ---
 name: to-spec
-description: 当需求、访谈或研究结论已经基本明确，需要整理成范围清楚、决策完整、可实现且可验收的规格时使用。它消除剩余歧义并定义行为与边界；探索阶段的大想法或已经存在合格规格时不使用。
+description: 当当前对话与代码库理解已经足够明确，需要综合成可实现、可验收的 spec（也可称 PRD）并发布到项目 tracker 时使用。它不重新访谈或探索产品方向；关键决策仍缺失时返回 grilling、research 或 prototype。
+disable-model-invocation: true
 ---
 
 # To Spec
 
-把已确认的意图转换成实现团队和 AI 可以独立执行的规格（specification）。规格描述问题、行为和约束，不预写未经论证的代码实现。
+把当前对话和代码库理解综合成 spec，并发布到项目 issue tracker。不要重新采访用户；本 skill 负责整理已经讨论清楚的内容。
 
-## 输入门禁
+## 动作授权
 
-先确认已有：目标用户或调用方、要解决的问题、范围、主要约束和成功信号。缺少会改变方案的信息时调用 `grilling`；方向仍模糊时返回 `wayfinder`；事实或可行性未知时调用 `research` 或 `prototype`。
+用户显式调用本 skill，且仓库、tracker 与来源工作项唯一时，可以在一句话预告后创建或更新 spec issue，并应用 `ready-for-agent` label。目标、tracker mapping 或待覆盖 issue 不唯一时，先只读加载并展示目标。
 
-读取仓库中的规则、相邻功能、领域文档和现有接口，避免规格与实际系统脱节。
+先按 `triage` 的 [项目 tracker 配置](../triage/references/project-config.md) 发现目标，再读取对应的 [GitHub](../triage/references/issue-tracker-github.md)、[GitLab](../triage/references/issue-tracker-gitlab.md) 或 [Local Markdown](../triage/references/issue-tracker-local.md) 参考。永不自动 push、创建 PR、merge、deploy 或发布软件。
 
-## 编写规格
+## 流程
 
-使用与项目匹配的结构，至少包含：
+1. 若尚未完成，探索仓库当前状态。全文使用项目 glossary 的 canonical terms，并遵守相关 ADR。
+2. 草拟测试 feature 的 Seams：
+   - 优先复用现有 Seam；
+   - 必须增加时，尽可能放在最高层；
+   - Seam 越少越好，理想情况只有一个。
 
-```markdown
-# 标题
-## 背景与问题
-## 目标与成功指标
-## 范围内
-## 范围外
-## 用户或系统场景
-## 功能需求
-## 业务规则与不变量
-## 数据、接口与状态变化
-## 错误与边界情况
-## 权限、安全、隐私与审计影响
-## 兼容、迁移与回退
-## 可观测性与运维要求
-## 验收标准
-## 未决问题
+   向用户校准这些 Seams 是否符合预期。这是规格发布前的定向确认，不重新开始需求访谈。
+3. 使用下面的结构写 spec，然后发布到 tracker。应用 `ready-for-agent` 后无需再次 triage。
+
+## Spec 结构
+
+### Problem Statement
+
+从用户视角描述其面对的问题。
+
+### Solution
+
+从用户视角描述解决方案。
+
+### User Stories
+
+使用足够详尽的编号列表覆盖所有用户可观察行为；每条都能独立检查，合在一起覆盖 feature 的全部方面：
+
+```text
+1. As a <actor>, I want a <feature>, so that <benefit>.
 ```
 
-与任务无关的章节可以标记“不适用”并说明原因，不要填充空泛模板文字。
+### Implementation Decisions
+
+记录已经形成的实施决定，包括：
+
+- 要新增或修改的 Modules；
+- 这些 Modules 的 Interfaces；
+- 来自开发者的技术澄清；
+- 架构决定；
+- schema changes；
+- API contracts；
+- 具体 interactions；
+- 相关时才加入兼容性、迁移、安全、回滚或观测决定。
 
-## 写作规则
+不要写具体文件路径或工作代码，它们很快会过时。唯一例外：prototype 产生的 state machine、reducer、schema 或 type shape 比文字更精确时，可以只嵌入承载 decision 的最小片段，并注明来自 prototype。
 
-- 每项需求使用可观察、可验证的语言，避免“快速”“友好”“智能”等未定义形容词。
-- 清楚区分事实、已批准决策、暂定假设和未决问题。
-- 用 Given/When/Then 或等价场景描述关键行为，包括失败和边界路径。
-- 公共 API、schema、权限、计费、迁移、部署等高风险变更要明确兼容和回退策略。
-- 只包含当前范围需要的设计约束。代码结构由 `codebase-design` 负责，任务拆分由 `to-tickets` 负责。
-- 发现现有行为与目标冲突时，展示证据并请求决策，不悄悄选择一方。
+### Testing Decisions
 
-## 验收标准检查
+至少说明：
 
-每条验收标准都应：
+- 好测试只通过外部 Interface 验证 behavior；
+- 哪些 Modules / Seams 要测试；
+- 代码库中可复用的同类测试先例。
 
-- 能由测试、可观察运行结果或人工验收直接判断；
-- 包含必要前置条件和预期结果；
-- 不依赖“实现得合理”之类主观判断；
-- 覆盖至少一个关键失败或边界场景；
-- 能追溯到某项目标或业务规则。
+### Acceptance Criteria
 
-## 交付
+用可观察、可验证的条件定义完成。适合时使用 Given / When / Then；不要把“修改某文件”当作用户行为的验收条件。
 
-默认在回答中给出规格，或写入用户指定/项目约定的本地文档位置。未经明确授权，不创建远程文档、issue 或项目任务。
+### Out of Scope
 
-## 完成标准
+明确与当前 spec 相邻但不包含的事项。
 
-- 目标、范围、非目标和验收标准一致且可追溯。
-- 关键业务规则、状态、失败路径和风险边界已定义。
-- 未决问题不阻塞拆票；若阻塞，明确指出并停止进入 `to-tickets`。
-- 规格足以让另一位执行者在不猜核心决策的情况下实施。
+### Further Notes
 
-## 反模式
+只放无法归入以上章节、但实施者确实需要的补充信息；没有内容时省略。
 
-- 不要把会议纪要重新排版后称为规格。
-- 不要隐藏未决问题或把假设写成要求。
-- 不要把具体文件改动列表冒充产品行为。
-- 不要在规格中提前锁定没有证据的复杂架构。
-- 不要用大而模糊的“完成所有功能”作为验收标准。
+发布前确认文档足以让实现 agent 无需额外产品 triage 即可开始。

package/skills/to-spec/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "To Spec"
-  short_description: "将已澄清需求整理为范围明确、决策完整且可验收的实现规格"
-  default_prompt: "请使用 $to-spec 把当前讨论整理成可实现、可审查且有验收标准的规格。"
+  short_description: "把已确认的讨论综合为可验收规格，并发布到明确的任务系统"
+  default_prompt: "请使用 $to-spec 把当前已确认结论综合成规格，并发布到明确的 tracker。"
 policy:
-  allow_implicit_invocation: true
+  allow_implicit_invocation: false

package/skills/to-tickets/SKILL.md

@@ -1,69 +1,108 @@
 ---
 name: to-tickets
-description: 当已有经过确认且不存在关键阻塞问题的规格，需要拆成可独立交付、可验证和可排序的垂直任务时使用。它建立依赖关系与完成证据；需求仍在探索、只有模糊想法或用户只要高层路线时不使用。
+description: 当已有经过确认的 plan、spec 或对话结论，需要拆成 tracer-bullet tickets、声明 blocking edges 并发布到项目 tracker 时使用。需求仍在探索或关键决定缺失时不使用。
+disable-model-invocation: true
 ---
 
 # To Tickets
 
-把规格拆成小而完整的价值切片。每个任务应让执行者知道为什么做、做什么、如何验证，同时避免把核心设计决策下放成猜测。
+把 plan、spec 或当前对话拆成一组 **tracer-bullet vertical slices**。每个 ticket 都声明阻塞它的 **blocking edges**。
 
-## 前置检查
+## 动作授权
 
-1. 读取完整规格、仓库规则和相关代码结构。
-2. 确认规格中的阻塞问题已经解决。若关键行为、范围或契约仍未定，返回 `to-spec` 或 `grilling`。
-3. 提取目标、业务规则、外部契约、迁移要求和验收标准，建立追踪关系。
+本 skill 先给用户校准拆分；用户批准后，且 tracker 与 parent 唯一时，可以自动创建远程 issues 或本地 ticket 文件、添加 `ready-for-agent` label、建立 native blocking / sub-issue 关系并返回 frontier。目标不唯一或 tracker mapping 不清时先只读展示。
 
-## 拆分原则
+不得关闭或改写 parent issue。永不自动 push、创建 PR、merge、deploy 或发布。
 
-- **垂直切片**：优先交付一个可观察的端到端行为，不按数据库、后端、前端机械拆成孤立层任务。
-- **单一结果**：每票只有一个清楚的业务或工程结果。
-- **独立验证**：每票有可执行的测试、命令、截图、检查或其他证据。
-- **最少依赖**：明确真实先后关系，能并行的任务不要人为串行。
-- **可回退**：高风险变化包含兼容、迁移、开关或恢复步骤。
-- **边界完整**：把安全、权限、数据、观测和文档要求放进相关切片，不留到模糊的“收尾票”。
+先按 `triage` 的 [项目 tracker 配置](../triage/references/project-config.md) 发现目标，再读取对应的 [GitHub](../triage/references/issue-tracker-github.md)、[GitLab](../triage/references/issue-tracker-gitlab.md) 或 [Local Markdown](../triage/references/issue-tracker-local.md) 参考。
 
-必要时先用 `codebase-design` 明确模块与契约，再拆票。
+## 流程
 
-## 任务格式
+### 1. 收集上下文
 
-```markdown
-## T01 — 动词开头的结果标题
-- 目的：这项工作支持哪个目标？
-- 范围：包含哪些行为和边界？
-- 不包含：明确避免范围漂移。
-- 依赖：无 / Txx / 外部决策。
-- 实现提示：必须遵守的契约与约束，不预写全部代码。
-- 验收标准：可观察结果。
-- 验证：具体测试、命令或人工检查。
-- 风险与回退：仅在相关时填写。
+使用当前对话已有信息。用户传入 spec 路径、issue 编号或 URL 时，读取完整 body 与 comments。
+
+### 2. 按需探索代码库
+
+尚不了解当前实现时再探索。Ticket 标题和描述使用项目 glossary 词汇，并遵守相关 ADR。
+
+寻找能让后续工作更简单的 prefactoring：“make the change easy, then make the easy change”。需要 prefactoring 时先建独立 ticket，并让后续 slices 被它阻塞。
+
+### 3. 草拟垂直切片
+
+每个 tracer bullet 必须：
+
+- 以狭窄但完整的路径穿过所需层次，例如 schema、API、UI 与 tests；不能只横切某一层；
+- 独立完成后可演示或验证；
+- 能在一个新鲜上下文窗口中完成；
+- 声明真正阻塞它的 tickets；没有 blockers 的 ticket 可立即开始。
+
+**Wide refactor 是垂直切片的例外。** 识别信号不是“改动文件很多”，而是一次不可避免的机械变化——例如 **rename a column** 或 **retype a shared symbol**——会同时打破大量调用点，使普通垂直切片无法先 green。此时使用 **expand–migrate–contract**：
+
+1. **Expand**：让新旧形式并存，不破坏现有调用者；
+2. **Migrate**：按 package、目录或其他 blast-radius 边界拆成批次，每批一个 ticket，均被 expand 阻塞，并保持每批 CI green；
+3. **Contract**：所有 migrate batches 完成后删除旧形式，该 ticket 被全部 batches 阻塞。
+
+若连单批也无法独立 green，仍保留上述顺序，但让批次共享 integration branch，并全部阻塞最终 integrate-and-verify ticket；只有最终节点承诺 green。
+
+### 4. 向用户校准
+
+以编号列表展示每票：
+
+- **Title**：简短描述；
+- **Blocked by**：真正的 blockers；
+- **What it delivers**：该 ticket 独立带来的端到端 behavior。
+
+询问粒度是否合适、blocking edges 是否真实、哪些 tickets 应合并或拆分。迭代到用户批准。
+
+### 5. 发布
+
+**Local Markdown**：在 `.scratch/<feature-slug>/issues/` 下按依赖顺序从 `01` 开始，每票一个文件：
+
+```md
+# <NN> — <Ticket title>
+
+**What to build:** 从用户视角描述该 ticket 使其工作的端到端 behavior。
+
+**Blocked by:** 阻塞它的编号/标题，或 `None — can start immediately`。
+
+**Status:** ready-for-agent
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Verification
+
+- 验证该独立 slice 的命令或观察方式。
 ```
 
-推荐每票可在一次专注工作周期内完成并审查。如果任务标题包含多个无关“以及”，继续拆分；如果拆分后没有独立价值或无法验证，则合并回垂直切片。
+**远程 tracker**：按依赖顺序创建一票一个 issue，拿到真实标识符后再建立 blocking edges。平台支持时使用 native blocking / sub-issue；否则在 body 中记录 `Blocked by`。除非用户另有指示，应用 `ready-for-agent`。
+
+```md
+## Parent
 
-## 排序
+来源 parent 的链接；没有 parent 时省略。
 
-先做能够降低未知、建立必要契约或形成最小端到端路径的任务。排序时说明：
+## What to build
 
-- 阻塞关系；
-- 风险降低价值；
-- 是否可以并行；
-- 哪些任务在某项验证失败时应取消。
+从用户视角描述该 ticket 使其工作的端到端 behavior。
 
-## 本地与远程
+## Acceptance criteria
 
-默认在回答或用户指定的本地 Markdown 文件中输出任务。只有用户明确授权、指定仓库/项目和目标系统后，才创建或修改 GitHub、Jira 等远程任务；创建前先展示拟写入内容和数量。
+- [ ] Criterion 1
+- [ ] Criterion 2
 
-## 完成标准
+## Verification
 
-- 规格中的每项验收标准都能追溯到至少一个任务。
-- 每个任务都有明确范围、依赖和验证方式。
-- 任务以垂直价值切分，没有孤立的“建表”“写接口”“做页面”层票。
-- 执行顺序和可并行部分清楚。
+- 验证该独立 slice 的命令或观察方式。
+
+## Blocked by
+
+- Blocking ticket，或 `None — can start immediately`。
+```
 
-## 反模式
+只有确实需要防止相邻范围混入时才增加 `Out of scope`。避免具体文件路径和工作代码；prototype 的 decision-rich snippet 是唯一例外，且只保留必要片段并注明来源。
 
-- 不要在规格未确认时用拆票掩盖决策缺失。
-- 不要创建无法独立验收的技术层任务堆。
-- 不要把测试、安全和迁移全部推迟到最后。
-- 不要未经授权写入远程 tracker。
-- 不要用任务数量代表计划质量。
+发布后返回 **frontier**：所有 blockers 已完成、当前可领取的 tickets。纯线性依赖图就是从上到下工作。

package/skills/to-tickets/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "To Tickets"
-  short_description: "将确认后的规格拆分为独立、可交付并且可验证的垂直任务"
-  default_prompt: "请使用 $to-tickets 将这份规格拆成有依赖关系和验收方式的垂直任务。"
+  short_description: "把规格拆成 tracer-bullet tickets，建立依赖并发布到 tracker"
+  default_prompt: "请使用 $to-tickets 把已确认规格拆成可独立验证的 tickets，并在我批准后发布。"
 policy:
-  allow_implicit_invocation: true
+  allow_implicit_invocation: false

package/skills/triage/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: triage
+description: 把原始 issue 或外部 PR 通过分类、核验、追问和 agent brief 推进到明确状态。
+disable-model-invocation: true
+---
+
+# Triage
+
+把 issue 和配置允许的外部 PR 推进通过一套小型状态机。外部 PR 是“附带代码的 issue”：共享分类、状态和决策流程，但验证时还要检查 diff。
+
+每段由本 skill 写入 tracker 的 comment、issue body 或 brief 必须以此开头：
+
+```markdown
+> *此内容由 AI 在分诊过程中生成。*
+```
+
+使用前读取：
+
+- [项目 tracker 配置与零配置发现](references/project-config.md)
+- [Agent brief reference](references/agent-brief.md)
+- [Out-of-scope reference](references/out-of-scope.md)
+- [Triage label mapping](references/triage-labels.md)
+- 当前仓库对应的 tracker 参考：[GitHub](references/issue-tracker-github.md)、[GitLab](references/issue-tracker-gitlab.md) 或 [Local Markdown](references/issue-tracker-local.md)
+
+## 动作门禁
+
+用户显式调用且 tracker、item 与目标状态清楚时，可以自动读取、评论、改 label、指派、创建 brief、关闭 item、按规则更新 `.out-of-scope/`，并在访谈确认稳定领域语言或满足 ADR 门禁的决定时，对唯一相关的领域文档做最小更新。
+
+执行前用一句话列出拟进行的状态变化和写入，无需再次确认。
+
+若只是“triage 这个 item”但最终状态仍需维护者判断，先给 recommendation 并等待。bare number 无法唯一解析、label mapping 不明或状态冲突时，只读检查并询问。
+
+永不自动 push、创建 PR、merge、deploy 或发布。若 `.out-of-scope/` 更新需要 commit，只能在明确本地 branch 上提交；不自动 push。
+
+## 分类与状态
+
+两个 category：
+
+- **bug**：已有行为损坏；
+- **enhancement**：新增功能或改进。
+
+五个 state：
+
+- **needs-triage**：等待维护者评估；
+- **needs-info**：等待 reporter 补充；
+- **ready-for-agent**：合同完整，AFK agent 可执行；
+- **ready-for-human**：需要人工判断、权限或操作；
+- **wontfix**：不会实施。
+
+每个已 triage item 必须恰好有一个 category 和一个 state。实际 label 字符串按项目 tracker 配置解析；没有自定义映射时直接使用 canonical labels，只有映射冲突或 tracker 不唯一时才询问。不能引用 setup 指令。
+
+PR 的 **ready-for-agent** 表示 agent brief 描述了 diff 还需要完成什么；**ready-for-human** 表示代码已具备人工 merge 判断条件。Triage 本身不 merge。
+
+状态机：
+
+- unlabeled → needs-triage；
+- needs-triage → needs-info / ready-for-agent / ready-for-human / wontfix；
+- reporter 回复后 needs-info → needs-triage；
+- 维护者可以覆盖，但异常转换应指出原因。
+
+state labels 冲突时停止写入，先请求维护者决定。
+
+## 模式一：显示需要关注的内容
+
+按最旧优先查询三个 bucket：
+
+1. unlabeled；
+2. needs-triage；
+3. needs-info 且 reporter 在最后一条 triage note 之后有新活动。
+
+若 tracker 配置把外部 PR 纳入 triage，发现列表只包含外部作者 PR，并标记 `[PR]` 或 `[issue]`。显式指定的 PR 不受该发现过滤限制。
+
+输出每个 bucket 的数量与每项一行摘要，让维护者选择。
+
+## 模式二：Triage 一个 item
+
+### 收集上下文
+
+读取完整 body、comments、labels、author、dates；PR 还需读取 diff 与 checks。解析过去 triage notes，避免重复提问。
+
+读取领域 glossary、相关 ADR 和代码。
+
+执行两项代码库检查：
+
+- **Redundancy**：按领域概念搜索现有实现，而不只搜索 reporter 原话，并说明查过哪里。已实现则进入 wontfix，但不写 `.out-of-scope/`。
+- **Prior rejection**：读取 `.out-of-scope/*.md`，按概念相似性寻找以前的拒绝。
+
+### 给出建议
+
+给出：
+
+- category recommendation；
+- state recommendation；
+- 相关代码路径与现状摘要；
+- 是否已实现；
+- 是否命中 prior rejection；
+- recommendation 的证据和仍缺信息。
+
+若用户只要求评估，在这里等待方向。若用户显式授权“按最佳判断应用结果”，且目标唯一，可以继续。
+
+### 核验 claim
+
+在 grilling 前核验：
+
+- bug：按 reporter 步骤复现，记录命令、输入、结果和代码路径；
+- PR：把 attached code 检出到隔离 worktree，或读取确定对应该 head SHA 的 CI/check artifact，再针对该代码运行相关检查，验证它是否实现声称行为。仅阅读 diff 可以形成 review evidence，不能形成 verified claim；无法安全检出或取得对应 artifact 时报告 verification unavailable / insufficient detail；
+- enhancement：确认当前系统确实没有该能力和等价路径。
+
+结果只能是 confirmed、failed to reproduce / claim not supported，或 insufficient detail。
+
+### 必要时深入访谈
+
+请求仍缺关键决定时调用 `$grilling`；术语、状态或不变量需要沉淀时同时调用 `$domain-modeling`。
+
+一次一个问题。已确认内容写入 triage notes，后续 session 不重问。
+
+### 应用结果
+
+- **ready-for-agent**
+  - 按 Agent brief reference 写权威 brief；
+  - comment；
+  - 应用 category 和 state。
+- **ready-for-human**
+  - 使用同样结构；
+  - 明确为什么不能交给 AFK agent：人工判断、外部权限、设计选择或手工验证。
+- **needs-info**
+  - 写 triage notes；
+  - 应用状态。
+- **wontfix**
+  - 已实现：指出实现位置，关闭；不写 out-of-scope。
+  - 拒绝 bug：礼貌解释并关闭；不写 out-of-scope。
+  - 拒绝 enhancement：创建或更新 out-of-scope knowledge entry，comment 链接理由，应用状态并关闭。
+- **needs-triage**
+  - 应用状态；
+  - 有部分进展时可附 triage notes。
+
+## 直接覆盖状态
+
+用户明确说“把 item 移到某状态”时，信任该指令并直接执行，不启动 grilling。
+
+若目标是 ready-for-agent：
+
+- 已有合格 brief：直接应用；
+- 现有上下文足以生成 brief：自动生成后应用；
+- 信息不足以形成可验证 brief：展示缺口并询问，不能把空壳 item 标为 agent-ready。
+
+## Needs-info 模板
+
+```markdown
+> *此内容由 AI 在分诊过程中生成。*
+
+## Triage Notes
+
+**已经确认：**
+- 事实一
+- 事实二
+
+**仍需要 @reporter 提供：**
+- 具体、可执行的问题一
+- 具体、可执行的问题二
+```
+
+## 恢复分诊
+
+已有 triage notes 时：
+
+1. 读取已确认内容和未答问题；
+2. 检查 reporter 后续回复；
+3. 标出哪些问题已解决；
+4. 展示更新后的 picture；
+5. 只询问仍未解决的问题。

package/skills/triage/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Triage"
+  short_description: "通过分类、核验、追问和 agent brief 推进 issue 与外部 PR"
+  default_prompt: "请使用 $triage 检查并推进这个 issue 或外部 PR 的分诊状态。"
+policy:
+  allow_implicit_invocation: false