@netpilot/skills 0.3.2 → 0.6.0

package/skills/triage/references/agent-brief.md

@@ -0,0 +1,168 @@
+# 编写 Agent Brief
+
+Agent brief 是 item 进入 **ready-for-agent** 时写入 tracker 的权威合同。原始 body 与讨论是背景；brief 定义 AFK agent 真正需要完成的工作。
+
+Issue brief 描述从当前系统构建变化。PR brief 描述现有 diff 仍需补齐、修复或验证的部分。
+
+## 原则
+
+### 持久性优先于易失的精确度
+
+Item 可能数周后才被执行：
+
+- 描述 Interface、type 和 behavioral contract；
+- 可以命名稳定类型、函数签名或配置 shape；
+- 不引用具体文件路径或行号；
+- 只引用稳定的 Interface、type、contract、配置键或数据 shape；
+- 不假设当前目录结构长期不变。
+
+### 描述行为，不写编辑步骤
+
+写系统完成后应具备的行为，不写逐步编辑指令。
+
+好：
+
+> `SkillConfig` 接受可选 `schedule: CronExpression`，缺省时保持现有行为。
+
+差：
+
+> 打开某文件第 42 行，加一个字段。
+
+### 完整的验收标准
+
+每条 criterion 独立可验证。避免“工作正常”“体验良好”等不可判定表达。
+
+### 明确范围
+
+明确不属于本 item 的相邻能力，阻止 gold-plating。
+
+## 模板
+
+```markdown
+> *此内容由 AI 在分诊过程中生成。*
+
+## Agent Brief
+
+**Category:** bug / enhancement
+**Summary:** 一句话说明需要实现或完成什么。
+
+**Current behavior:**
+描述当前系统或 PR diff 的真实状态。bug 写损坏行为；enhancement 写 status quo；PR 写现有 diff 已完成和未完成的部分。
+
+**Desired behavior:**
+描述完成后的可观察行为，包括 edge cases 和 error conditions。
+
+**Key interfaces:**
+- `TypeName` — 应具备的 contract
+- `functionName()` — 输入、输出或错误行为
+- Config / schema shape — 必要变化
+
+**Acceptance criteria:**
+- [ ] 具体、可验证标准一
+- [ ] 具体、可验证标准二
+- [ ] 关键失败或边界标准
+
+**Verification evidence available:**
+- 已确认的 reproduction、test、command 或 code path
+- 尚未能执行的验证及原因
+
+**Out of scope:**
+- 相邻但不属于本 item 的内容
+```
+
+## 示例
+
+### Bug 示例
+
+```markdown
+## Agent Brief
+
+**Category:** bug
+**Summary:** Skill description 截断不能在单词中间产生损坏输出。
+
+**Current behavior:**
+description 超过限制后在固定字符位置截断，可能留下半个单词。
+
+**Desired behavior:**
+超过限制时，在限制内最后一个单词边界截断并追加省略号；未超过限制时保持原文。
+
+**Key interfaces:**
+- Description formatter — 输入原文与长度限制，返回符合限制的显示文本
+- Fallback contract — 无空格文本仍必须产生合法、长度受限的结果
+
+**Acceptance criteria:**
+- [ ] 未超过限制的 description 不变化
+- [ ] 超过限制时在单词边界截断
+- [ ] 输出含省略号且总长度不超过限制
+- [ ] 中英文和无空格文本有明确 fallback
+
+**Out of scope:**
+- 修改长度限制
+- 改变 description 的存储格式
+```
+
+### Enhancement 示例
+
+```markdown
+## Agent Brief
+
+**Category:** enhancement
+**Summary:** 为被拒绝的 feature requests 建立按概念归档的 knowledge base。
+
+**Current behavior:**
+拒绝理由只存在于关闭 comment，类似请求到来时难以发现历史决定。
+
+**Desired behavior:**
+每个被拒绝概念对应一份 `.out-of-scope/<concept>.md`，记录 durable reason 与 prior requests。
+
+**Key interfaces:**
+- Out-of-scope entry — 一个概念、一项长期理由和多个 prior requests
+- Triage lookup — 按概念相似性读取历史决定
+
+**Acceptance criteria:**
+- [ ] 拒绝 enhancement 时创建或更新对应概念文件
+- [ ] 同概念请求追加到 prior requests，不产生重复文件
+- [ ] Triage 时读取并展示相似历史决定
+- [ ] Bug 和 already-implemented item 不写入 knowledge base
+
+**Out of scope:**
+- 自动重新打开历史 requests
+```
+
+### External PR 示例
+
+```markdown
+## Agent Brief
+
+**Category:** enhancement
+**Summary:** 完成现有 JSON 输出 diff 的错误路径和测试覆盖。
+
+**Current behavior:**
+PR 的成功路径会输出 JSON，但错误仍是 human text，且缺少覆盖。
+
+**Desired behavior:**
+启用 JSON 模式后成功和失败输出都为合法 JSON，exit code 保持现有 contract；未启用时输出完全不变。
+
+**Key interfaces:**
+- CLI JSON output contract — 成功与失败都输出单个合法 JSON document
+- Exit status contract — JSON 模式不改变既有 exit code 语义
+
+**Acceptance criteria:**
+- [ ] 成功和错误路径均输出合法 JSON
+- [ ] Exit code 与非 JSON 模式一致
+- [ ] 至少覆盖一条成功和一条错误测试
+- [ ] 默认输出保持不变
+
+**Out of scope:**
+- 重命名既有 JSON fields
+- 改变 human-readable 默认输出
+```
+
+以下内容不合格：
+
+```markdown
+## Agent Brief
+修一下 triage。某文件第 150 行有问题。
+```
+
+它没有 category、current/desired behavior、acceptance criteria、scope、验证证据，并依赖易过期的路径与行号。

package/skills/triage/references/issue-tracker-github.md

@@ -0,0 +1,42 @@
+# Issue Tracker：GitHub
+
+GitHub issues 承载 issue、spec/PRD、implementation tickets 与 Wayfinder map。Tracker 选择和项目覆盖先按 [project-config.md](project-config.md) 解析。优先使用当前宿主已连接的 GitHub connector 或 API；不可用时使用官方 `gh` CLI。所有写入都继承调用方 skill 的动作门禁，本文件本身不授予远程写权限。
+
+## 常规操作
+
+- 创建 issue：`gh issue create --title "..." --body-file <path>`
+- 读取 issue：`gh issue view <number> --comments --json number,title,body,labels,comments,author,createdAt,updatedAt`
+- 列出 issues：`gh issue list --state open --json number,title,body,labels,comments`
+- 评论：`gh issue comment <number> --body-file <path>`
+- 增删 labels：`gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- 指派：`gh issue edit <number> --add-assignee @me`
+- 关闭：先写有证据的 resolution comment，再执行 `gh issue close <number>`
+
+多行或来自外部输入的正文使用 connector 的结构化字段或临时 body file，不把不可信内容拼接进 shell 命令。运行在 clone 内时由 `gh` 从 Git remote 识别仓库；仓库不唯一时显式指定。
+
+## PR 作为 triage surface
+
+默认 **否**。只有仓库规则明确把外部 PR 当作 request surface 时才纳入。
+
+- 读取：`gh pr view <number> --comments` 与 `gh pr diff <number>`
+- 列出外部 PR：读取 `authorAssociation`，只保留 `CONTRIBUTOR`、`FIRST_TIME_CONTRIBUTOR` 或 `NONE`
+- 评论、label、关闭：使用 `gh pr comment`、`gh pr edit`、`gh pr close`
+
+GitHub issue 与 PR 共用编号空间。裸 `#42` 可能属于任一 surface：先用 `gh pr view 42` 解析 PR，失败后再用 `gh issue view 42`；两个 surface 都无法读取时才报告目标不存在或权限不足。
+
+## 发布与读取约定
+
+- “发布到 issue tracker”表示创建 GitHub issue。
+- “读取相关 ticket”表示读取完整 body、comments、labels 与关联对象，而不是只看标题。
+- Canonical triage roles 到实际 label 的映射见 [triage-labels.md](triage-labels.md)。
+
+## Wayfinder 操作
+
+- **Map**：单一 issue，label 为 `wayfinder:map`，保存 Destination、Notes、Decisions so far 与 fog。
+- **Child ticket**：优先使用 GitHub sub-issue。不可用时，在 map task list 中链接 child，并在 child 顶部写 `Part of #<map>`。每票带 `wayfinder:<type>` label。
+- **Blocking**：优先使用 GitHub native issue dependencies。当前 `gh issue create` 支持 `--blocked-by <numbers>` 与 `--blocking <numbers>`；需要 API 时，用 `POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>` 添加 edge。`issue_id` 是 blocker 的 numeric database id，可由 `gh api repos/<owner>/<repo>/issues/<n> --jq .id` 获取，不是 `#number` 或 `node_id`。用 `GET .../dependencies/blocked_by` 查询当前 ticket 的 blockers，用 `GET .../dependencies/blocking` 查询它阻塞的 tickets。不可用时回退到 body 顶部的 `Blocked by: #<n>, #<n>`。
+- **Frontier**：列出 map 的 open children，查询每票的 live blocker 状态；优先读取 `blockedBy` / `blocking` 或上述 dependency endpoints，而不是依赖创建时的旧快照。排除仍有 open blocker 或已有 assignee 的 tickets，按 map 顺序取第一项。
+- **Claim**：在任何实质工作前把 ticket 指派给当前维护者。
+- **Resolve**：写独立可读的 resolution comment，关闭 ticket，再把“标题链接 + 一行 gist”的 context pointer 追加到 map。
+
+Assets 和 research branches 只通过链接/context pointer 引用，不把完整产物粘贴到 map body。

package/skills/triage/references/issue-tracker-gitlab.md

@@ -0,0 +1,42 @@
+# Issue Tracker：GitLab
+
+GitLab issues 承载 issue、spec/PRD、implementation tickets 与 Wayfinder map。Tracker 选择和项目覆盖先按 [project-config.md](project-config.md) 解析。优先使用当前宿主已连接的 GitLab API；不可用时使用官方 `glab` CLI。所有写入都继承调用方 skill 的动作门禁。
+
+## 常规操作
+
+- 创建 issue：`glab issue create --title "..." --description "..." --yes`
+- 读取 issue：`glab issue view <number> --comments --output json`
+- 列出 issues：`glab issue list --output json`
+- 评论：`glab issue note <number> --message "..."`
+- 增删 labels：`glab issue update <number> --label "..."` / `--unlabel "..."`
+- 指派：`glab issue update <number> --assignee @me`
+- 关闭：先用 note 写 resolution，再执行 `glab issue close <number>`
+
+长正文优先通过结构化 GitLab API 字段提交；使用 CLI 时将正文作为独立参数传递，不把不可信内容拼接进 shell。运行在 clone 内时可由 Git remote 识别项目；项目不唯一时显式指定。
+
+## Merge Request 作为 triage surface
+
+默认 **否**。只有仓库规则明确把外部 MR 当作 request surface 时才纳入。
+
+- 读取：`glab mr view <number> --comments` 与 `glab mr diff <number>`
+- 列出：`glab mr list --output json`，排除 project member/owner 的维护中工作
+- 评论、label、关闭：使用 `glab mr note`、`glab mr update`、`glab mr close`
+
+GitLab issues 与 MRs 使用不同编号空间，因此必须先知道 surface。
+
+## 发布与读取约定
+
+- “发布到 issue tracker”表示创建 GitLab issue。
+- “读取相关 ticket”表示读取完整 description、notes、labels 与关联对象。
+- Canonical triage roles 到实际 label 的映射见 [triage-labels.md](triage-labels.md)。
+
+## Wayfinder 操作
+
+- **Map**：label 为 `wayfinder:map` 的 issue；有合适 tier 时也可使用 epic，但普通 issue 在所有 tier 可用。
+- **Child ticket**：description 顶部写 `Part of #<map>`，并添加 `wayfinder:<type>` label。
+- **Blocking**：优先使用 native blocking link，例如 `/blocked_by #<n>` quick action。功能不可用时回退到 `Blocked by: #<n>, #<n>`。
+- **Frontier**：列出 map children，排除仍有 open blocker 或 assignee 的 tickets；按 map 顺序选择。
+- **Claim**：任何实质工作前先指派。
+- **Resolve**：写 resolution note，关闭 issue，再把标题链接与一行 gist 追加到 map。
+
+Assets 和 research branches 使用链接/context pointer，不粘贴完整产物。

package/skills/triage/references/issue-tracker-local.md

@@ -0,0 +1,28 @@
+# Issue Tracker：Local Markdown
+
+没有远程 tracker 或用户明确选择本地模式时，issues、specs 与 Wayfinder map 保存在 `.scratch/` 下。Tracker 选择和项目覆盖先按 [project-config.md](project-config.md) 解析；写入仍继承调用方 skill 的动作门禁。
+
+## 常规约定
+
+- 一个 feature 一个目录：`.scratch/<feature-slug>/`
+- Spec：`.scratch/<feature-slug>/spec.md`
+- Implementation tickets：`.scratch/<feature-slug>/issues/<NN>-<slug>.md`
+- Ticket 从 `01` 按依赖顺序编号；每票一个文件，不能合并成单一 tickets 文档
+- Triage state 使用文件顶部附近的 `Status:` 字段
+- 评论与历史追加到 `## Comments`
+- Canonical roles 见 [triage-labels.md](triage-labels.md)
+
+“发布到 issue tracker”表示按上述位置创建文件；“读取 ticket”表示读取用户给出的路径或能唯一解析的编号。不要扫描或覆盖无关 `.scratch/` effort。
+
+## Wayfinder 操作
+
+- **Map**：`.scratch/<effort>/map.md`
+- **Child ticket**：`.scratch/<effort>/issues/<NN>-<slug>.md`
+- **Type**：`research`、`prototype`、`grilling` 或 `task`
+- **Status**：至少区分 open、claimed 与 resolved
+- **Blocking**：顶部使用 `Blocked by: NN, NN`；全部 blockers resolved 后才 unblocked
+- **Frontier**：扫描该 effort 的 issues，选择 open、unblocked、unclaimed 中编号最小者
+- **Claim**：任何实质工作前先写 `Status: claimed`
+- **Resolve**：在 `## Answer` 下追加独立可读的答案，改为 `Status: resolved`，再把标题链接与一行 gist 追加到 map
+
+Research artifact 或 prototype 以相对链接引用；答案和 artifact 不在 map 重复存储。

package/skills/triage/references/out-of-scope.md

@@ -0,0 +1,113 @@
+# 超出范围的知识库
+
+`.out-of-scope/` 保存被明确拒绝的 enhancement 的长期记录：
+
+1. 保留 institutional memory；
+2. 在相似请求再次出现时去重，避免重新争论已经决定的内容。
+
+一份文件对应一个概念，而不是一个 issue。
+
+```text
+.out-of-scope/
+├── dark-mode.md
+├── plugin-system.md
+└── graphql-api.md
+```
+
+## 文件格式
+
+文件应像短设计文档，而不是数据库记录。可以使用段落、例子和必要代码，确保第一次看到的人也理解理由。
+
+```markdown
+# Dark Mode
+
+本项目不提供运行时主题切换。
+
+## Why this is out of scope
+
+说明项目 scope、架构约束或长期战略理由。理由必须在数月后仍成立，不能只写“现在没时间”。
+
+## Prior requests
+
+- [Add dark mode](issue-link)
+- [Night theme](issue-link)
+```
+
+文件名使用表达概念的 kebab-case。多个相同概念请求追加到 Prior requests。
+
+### 完整示例
+
+```markdown
+# Runtime Theme Switching
+
+本产品不提供运行时主题切换；视觉主题由部署时配置决定。
+
+## Why this is out of scope
+
+产品输出需要经过固定主题的像素级审查，并作为可审计快照保存。运行时切换会让同一内容产生多套必须独立验证的视觉状态，同时破坏“一个部署对应一套已批准呈现”的约束。若未来产品目标改为面向终端用户的个性化界面，应作为新的产品方向重新评估，而不是在现有渲染链路上追加开关。
+
+## Prior requests
+
+- [Allow each viewer to choose a theme](issue-link)
+- [Add a night presentation mode](issue-link)
+```
+
+## 持久理由
+
+好的理由通常来自：
+
+- project scope 或 philosophy；
+- 与现有架构的实质冲突；
+- 已批准的战略选择；
+- 成本与项目定位长期不匹配。
+
+“当前优先级低”“这季度没时间”“现在不方便”属于 deferral，不是 rejection，不应写入 knowledge base。
+
+## 何时读取
+
+Triage gather-context 阶段读取所有 `.out-of-scope/*.md`，按概念相似性判断，不只匹配关键词。
+
+发现相似项时向维护者展示：
+
+- 匹配的 concept；
+- 上次拒绝的 durable reason；
+- prior requests；
+- 询问当前决定是否仍成立。
+
+维护者可以：
+
+- **Confirm**：追加新请求并关闭；
+- **Reconsider**：更新或删除 knowledge entry，让请求继续正常 triage；
+- **Distinct**：确认相关但不同，继续 triage。
+
+## 何时写入
+
+仅在 enhancement 被明确拒绝为 wontfix 时写入。外部 enhancement PR 同样适用。
+
+不要写入：
+
+- bug rejection；
+- already-implemented request；
+- temporary deferral；
+- 仍在讨论的想法。
+
+流程：
+
+1. 确认拒绝的是 enhancement；
+2. 查找现有 concept file；
+3. 存在则追加 prior request；
+4. 不存在则创建文件；
+5. tracker comment 解释并引用该记录；
+6. 应用 wontfix 并关闭 item。
+
+若 Git 管理该知识库，显式 triage 且 branch 目标清楚时可以 commit 这次更新，但不得自动 push。
+
+## 更新或删除
+
+维护者改变长期决定时：
+
+- 更新理由，或在明确确认后删除对应文件；
+- 不自动 reopen 历史 issues；
+- 触发重新考虑的新 issue 进入正常 triage。
+
+删除是破坏性动作，必须有明确目标与维护者确认，不能仅凭模型推断执行。

package/skills/triage/references/project-config.md

@@ -0,0 +1,57 @@
+# 项目 Tracker 配置
+
+常规仓库应零配置工作。只有自定义 tracker、自定义 labels、多 remote 或主动启用 PR/MR request surface 时，才需要项目级覆盖；不要修改用户级已安装 Skill 保存项目事实。
+
+## 发现顺序
+
+每次需要 tracker 时按以下顺序解析，并在某一步得到唯一答案后停止：
+
+1. 读取适用的项目 `AGENTS.md`、`CLAUDE.md` 或其他项目规则中明确声明的 tracker、labels 和 request surface。
+2. 兼容读取项目可选文件：
+   - `docs/agents/issue-tracker.md`
+   - `docs/agents/triage-labels.md`
+3. 没有显式配置时，从唯一 Git remote 推断：
+   - `github.com` → GitHub；
+   - `gitlab.com` 或明确 GitLab host → GitLab。
+4. 没有 remote，但当前 effort 已存在 `.scratch/<effort>/issues/` 或用户明确选择本地模式时，使用 Local Markdown。
+5. 仍无法唯一判断、存在多个不同 tracker remote，或 host 属于自定义 tracker 时，展示候选并询问一次；不要猜。
+
+Canonical labels 默认直接使用：
+
+- `needs-triage`
+- `needs-info`
+- `ready-for-agent`
+- `ready-for-human`
+- `wontfix`
+
+PR/MR request surface 默认关闭。只有项目规则或 `docs/agents/issue-tracker.md` 明确启用时，discovery 才把外部 PR/MR 放入 triage buckets；用户显式指定某个 PR/MR 时仍可处理该对象。
+
+## 可选项目覆盖
+
+需要覆盖时，优先沿用仓库已有格式。没有既有格式时，可使用：
+
+```md
+# Issue Tracker
+
+- Type: github | gitlab | local | custom
+- Repository: owner/name 或项目路径
+- PR/MR request surface: yes | no
+
+## Operations
+
+{自定义 tracker 时，写明读取、创建、评论、label、指派、关闭、blocking 和 frontier 的 connector/API/CLI。}
+```
+
+自定义 label 映射保存在 `docs/agents/triage-labels.md`：
+
+```md
+| Canonical role | Tracker label |
+| --- | --- |
+| needs-triage | needs-review |
+| needs-info | awaiting-reporter |
+| ready-for-agent | ready-for-agent |
+| ready-for-human | maintainer-review |
+| wontfix | declined |
+```
+
+自定义 tracker 必须说明对象标识如何唯一解析、写入权限如何获得、blocking/sub-issue 如何表达，以及哪些操作不可逆。配置文件只描述项目事实，不因为调用 Skill 自动扩大动作权限。

package/skills/triage/references/triage-labels.md

@@ -0,0 +1,13 @@
+# Triage Labels
+
+Skills 使用五个 canonical triage roles。本表把这些 roles 映射到当前 tracker 的实际 label 字符串。
+
+| Canonical role | Tracker label | 含义 |
+| --- | --- | --- |
+| `needs-triage` | `needs-triage` | 等待维护者评估 |
+| `needs-info` | `needs-info` | 等待 reporter 补充信息 |
+| `ready-for-agent` | `ready-for-agent` | 合同完整，可由 AFK agent 执行 |
+| `ready-for-human` | `ready-for-human` | 需要人工判断、权限或操作 |
+| `wontfix` | `wontfix` | 不会实施 |
+
+仓库有自定义 label vocabulary 时，在 [项目级配置](project-config.md) 指定的位置维护映射，不修改用户级已安装 Skill。Canonical role 保持不变，只覆盖 tracker 上的实际 label。调用 skill 时先读取项目已有映射；映射不存在时使用上表默认值，发生冲突时询问，不能猜测。