docs: 配置 Agent Skills

AGENTS.md

@@ -44,3 +44,17 @@
 - 当代码或配置变更导致本文件中的命令、路径或约定失效时，在同一任务中更新本文件。
 - 将重复出现的错误假设或评审反馈写入适用范围最近的 `AGENTS.md`；仅在需要临时替换同目录规则时使用 `AGENTS.override.md`。
 - 完成任务后报告修改文件、执行的命令、结果和剩余风险。
+
+## Agent skills
+
+### 议题跟踪器
+
+议题和 PRD 统一记录在本仓库的 GitHub Issues 中。详见 `docs/agents/issue-tracker.md`。
+
+### Triage 标签
+
+使用五个默认 triage 标签，不设置覆盖映射。详见 `docs/agents/triage-labels.md`。
+
+### 领域文档
+
+本仓库采用 single-context 布局，在仓库根目录维护 `CONTEXT.md` 和 `docs/adr/`。详见 `docs/agents/domain.md`。

docs/agents/domain.md

@@ -0,0 +1,34 @@
+# 领域文档
+
+本文件说明工程 Skills 在探索代码库时应如何使用本仓库的领域文档。
+
+## 探索前读取
+
+- 仓库根目录的 **`CONTEXT.md`**。
+- **`docs/adr/`**：读取与即将处理区域相关的 ADR。
+
+如果上述文件或目录不存在，**直接继续，不作提示**。不要将缺失视为问题，也不要预先建议创建。`/domain-modeling` Skill（可通过 `/grill-with-docs` 和 `/improve-codebase-architecture` 进入）会在术语或决策真正明确时按需创建这些文件。
+
+## 文件结构
+
+本仓库采用 single-context 布局：
+
+```text
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+└── src/
+```
+
+## 使用术语表中的词汇
+
+输出中提及领域概念时——例如议题标题、重构提案、假设或测试名称——使用 `CONTEXT.md` 定义的术语。不要改用术语表明确排除的同义词。
+
+如果术语表尚未包含所需概念，这通常意味着两种情况之一：正在创造项目并未使用的词汇，应重新考虑；或者确实存在领域空白，应记录下来交由 `/domain-modeling` 处理。
+
+## 标明与 ADR 的冲突
+
+如果输出与现有 ADR 冲突，应明确指出，而不是静默覆盖：
+
+> _与 ADR-0007 冲突——但值得重新讨论，因为……_

docs/agents/issue-tracker.md

@@ -0,0 +1,45 @@
+# 议题跟踪器：GitHub
+
+本仓库的议题和 PRD 记录在 GitHub Issues 中。所有操作均使用 `gh` CLI。
+
+## 约定
+
+- **创建议题**：`gh issue create --title "..." --body "..."`。多行正文使用 heredoc。
+- **读取议题**：`gh issue view <number> --comments`；使用 `jq` 筛选评论时，同时获取标签。
+- **列出议题**：`gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'`，并按需添加 `--label` 和 `--state` 筛选条件。
+- **评论议题**：`gh issue comment <number> --body "..."`
+- **添加或移除标签**：`gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **关闭议题**：`gh issue close <number> --comment "..."`
+
+通过 `git remote -v` 推断仓库；在克隆仓库内运行时，`gh` 会自动完成推断。
+
+## 将拉取请求作为 triage 入口
+
+**PRs as a request surface: no（不将 PR 作为请求入口）。** _（如果本仓库将外部 PR 视为功能请求，可改为 `yes`；`/triage` 会读取此标志。）_
+
+设置为 `yes` 后，PR 使用与议题相同的标签和状态流转，并改用对应的 `gh pr` 命令：
+
+- **读取 PR**：`gh pr view <number> --comments`，并使用 `gh pr diff <number>` 查看差异。
+- **列出待 triage 的外部 PR**：运行 `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments`，只保留 `authorAssociation` 为 `CONTRIBUTOR`、`FIRST_TIME_CONTRIBUTOR` 或 `NONE` 的 PR，排除 `OWNER`、`MEMBER` 和 `COLLABORATOR`。
+- **评论、添加标签或关闭**：使用 `gh pr comment`、`gh pr edit --add-label` / `--remove-label` 和 `gh pr close`。
+
+GitHub 的议题与 PR 共用同一编号空间，因此单独的 `#42` 可能指向其中任意一种对象；先运行 `gh pr view 42`，失败后再运行 `gh issue view 42`。
+
+## 当 Skill 要求“publish to the issue tracker（发布到议题跟踪器）”时
+
+创建一个 GitHub Issue。
+
+## 当 Skill 要求“fetch the relevant ticket（获取相关任务单）”时
+
+运行 `gh issue view <number> --comments`。
+
+## Wayfinding 操作
+
+供 `/wayfinder` 使用。**地图（map）**是一个单独的议题，**子议题（child）**是具体任务单。
+
+- **地图**：一个带有 `wayfinder:map` 标签的议题，其正文维护 Notes / Decisions-so-far / Fog。使用 `gh issue create --label wayfinder:map` 创建。
+- **子任务单**：通过 GitHub 子议题关联到地图（使用 `gh api` 调用 sub-issues 端点）。如果仓库未启用子议题，则将子任务添加到地图正文的任务列表，并在子任务正文顶部写入 `Part of #<map>`。标签使用 `wayfinder:<type>`，其中类型为 `research`、`prototype`、`grilling` 或 `task`。任务被领取后，将其分配给负责推进的开发者。
+- **阻塞关系**：GitHub 原生 issue dependencies 是规范且在界面中可见的表达方式。使用 `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>` 添加依赖边，其中 `<blocker-db-id>` 是阻塞议题的数字数据库 ID，可通过 `gh api repos/<owner>/<repo>/issues/<n> --jq .id` 获取；它不是 `#number` 或 `node_id`。GitHub 通过 `issue_dependencies_summary.blocked_by` 报告尚未关闭的阻塞项，这是实时放行条件。如果依赖功能不可用，则在子任务正文顶部使用 `Blocked by: #<n>, #<n>`。所有阻塞议题关闭后，任务才算解除阻塞。
+- **前沿查询**：列出地图中尚未关闭的子任务（运行 `gh issue list --state open`，并限定在地图的子议题或任务列表内），排除仍有未关闭阻塞项（`issue_dependencies_summary.blocked_by > 0`，或 `Blocked by` 行引用了未关闭议题）或已有受理人的任务；按地图中的顺序选择第一个候选项。
+- **领取**：运行 `gh issue edit <n> --add-assignee @me`；这是会话中的第一次写操作。
+- **解决**：运行 `gh issue comment <n> --body "<answer>"`，再运行 `gh issue close <n>`，最后在地图的 Decisions-so-far 中追加上下文指针（gist 及其链接）。

docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage 标签
+
+这些 Skills 使用五个规范 triage 角色。本文件将这些角色映射到本仓库议题跟踪器实际使用的标签字符串。
+
+| mattpocock/skills 中的标签 | 本仓库标签        | 含义                         |
+| -------------------------- | ----------------- | ---------------------------- |
+| `needs-triage`             | `needs-triage`    | 需要维护者评估该议题         |
+| `needs-info`               | `needs-info`      | 等待报告者提供更多信息       |
+| `ready-for-agent`          | `ready-for-agent` | 需求已完整，可交给 AFK Agent |
+| `ready-for-human`          | `ready-for-human` | 需要由人工实现               |
+| `wontfix`                  | `wontfix`         | 不会处理                     |
+
+当 Skill 提到某个角色时（例如“应用可由 AFK Agent 处理的 triage 标签”），使用表中对应的标签字符串。
+
+如果本仓库实际使用其他标签词汇，请修改右侧“本仓库标签”列。