AGENT SKILL

wayfinder

把一大块工作——超出单次 agent 会话能装下的范围——规划成 issue tracker 上共享的决策 tickets 地图,一次解决一张,直到通往目的地的路清晰为止。

License 许可
MIT
最近更新
2026-08-19
Stars
★ 0
Forks
0

01 前言 Front Matter

name
wayfinder
description
把一大块工作——超出单次 agent 会话能装下的范围——规划成 issue tracker 上共享的决策 tickets 地图,一次解决一张,直到通往目的地的路清晰为止。
disable-model-invocation
true

02 资源文件 1

03 SKILL.md 正文

一个松散想法来了——对单次 agent 会话太大,而且裹在雾里:从这里到目的地的路还看不见。Wayfinding 是找出那条路,而不是冲向目的地。本 skill 把路画成仓库 issue tracker 上的共享地图,然后处理其决策 tickets——解决结果是一项决策的问题,而不是要执行的构建切片——一次一张,直到路线清晰。

目的地因每次努力而异,给它命名是绘图的第一动作——它塑造每一张 ticket。它可能是要交接并迭代的 spec、规划开始前要锁定的决策,或就地做出的变更如数据结构迁移。地图与领域无关——engineering 工作、课程内容,任何符合该形态的都行。

规划,不要去做

Wayfinder 默认是规划:每张 ticket 解决一项决策,当地图完成时路已清晰——在有人去做事之前没有剩下要决定的。想直接动手通常是信号:你已到达地图边缘,该交接了。一次努力可以在其 Notes 里覆盖这一点——把执行带进地图本身——但若没有,产出决策,而不是交付物。

按名称引用

每张地图和 ticket 都是一个 issue,所以它有一个名称——其标题。人类读到的一切——叙述、地图的 Decisions-so-far——都用该名称引用,绝不用光秃的 id、编号或 slug。一墙 #42, #43, #44 无法阅读;名称一眼可读。Id 和 URL 不会消失——名称包着其链接——但它们骑在名称里面,从不代替名称。

地图

地图是本仓库 issue tracker 上的单个 issue,打了 wayfinder:map 标签——规范产物。其 tickets 是地图的 child issues。

地图是索引,不是仓库。它列出已做出的决策,并指向持有细节的 tickets;一项决策只活在一个地方——它的 ticket——所以地图从不复述它,只给 gist 并链接。

地图、其子 tickets、blocking 和 frontier 查询实际存放在哪是 tracker 特定的。 Issue tracker 本应已提供给你——若没有,运行 /setup-matt-pocock-skills。查阅 tracker 文档的 "Wayfinding operations" 一节,了解本仓库如何表达它们。若尚未提供 tracker,默认用本地 markdown tracker。

地图正文

整张地图的低分辨率视图,每会话加载一次。开放的 tickets 不列在这里——它们是开放的 child issues,靠查询找到。

## Destination

<what reaching the end of this map looks like — the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>

## Notes

<domain; skills every session should consult; standing preferences for this effort>

## Decisions so far

<!-- the index — one line per closed ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->

- [<closed ticket title>](link) — <one-line gist of the answer>

## Not yet specified

<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->

## Out of scope

<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates -->

Tickets

每张 ticket 是地图的一个 child issue;tracker 的 issue id 是其身份。其正文是问题,体量适合一次 100K token 的 agent 会话:

## Question

<the decision or investigation this ticket resolves>

每张 ticket 带一个 wayfinder:<type> 标签——research、prototype、grilling、task 之一(见 Ticket Types)。

会话通过把 ticket 认领给驱动地图的开发者来 claim——首先,在任何工作之前,这样并发会话会跳过它。该 assignee 就是认领:开放且未指派的 ticket 即未认领。

Blocking 使用 tracker 的原生依赖关系——这很关键,因为它在 tracker 自己的 UI 里把 frontier 可视化出来,这样人不用打开地图就能看到什么可领取。只有缺少原生 blocking 的 tracker 才回退到正文约定。当阻塞它的每张 ticket 都已关闭时,ticket 即解除阻塞;frontier 是开放、未阻塞、未认领的 children——已知的边缘。

答案不是正文的一部分——它在解决时记录(见 走完地图)。解决 ticket 期间创建的资产从 issue 链接,而不是粘贴进去。

Ticket Types

每张 ticket 要么是 HITL——人在回路中,与能为自己说话的人一起做——要么是 AFK,由 agent 独自驱动。HITL ticket 只通过那场实时交流解决;agent 从不代替人的那一侧(自己回答自己问题的 grilling agent 就破坏了这一点)。

  • Research(AFK):阅读文档、第三方 APIs,或知识库等本地资源,挖出某项决策所等待的事实。由 /research subagent 解决。当需要当前工作目录之外的知识时使用。
  • Prototype(HITL):通过做一个便宜、粗糙、具体的产物来提高讨论保真度,供人反应——大纲、粗稿、桩,或经 /prototype skill 的 UI/逻辑代码。把原型作为资产链接。当关键问题是 "how should it look" 或 "how should it behave" 时使用。
  • Grilling(HITL):对话。默认情形。始终调用 /grilling 和 /domain-modeling skills。
  • Task(HITL 或 AFK):必须发生才能做出决策的手工工作——没什么要决定、原型化或调研,但讨论被卡住直到做完。注册某服务以便评判其 API、开通访问、移动数据以便看到其形态。这是唯一做事而不是做决策的类型——它靠解锁一项决策赢得席位,而不是交付目的地。Agent 能独自驱动就独自驱动(AFK);否则交给人一份精确清单(HITL)。工作完成即解决;答案记录做了什么以及后续 tickets 依赖的任何结果事实(凭据位置、新 URLs、行数)。

战争迷雾

地图是故意不完整的:看不见的就不要画。在活着的 tickets 之外是战争迷雾——你能感到即将来临但还钉不下来的决策和调查的朦胧视图,因为它们挂在仍开放的问题上。解决一张 ticket 会清掉它前方的雾,把现在可以规格化的东西毕业成新 tickets——一次一张,直到通往目的地的路清晰且没有 tickets 剩下。

地图的 Not yet specified 一节就是写下那朦胧视图的地方:疑似的问题、稍后要回访的区域。它是朝向目的地的未发现 frontier——这里的一切都在范围内,只是还不够锋利,无法做成 ticket。视图允许写多松就写多松、允许多满就写多满;它也是协作者阅读努力走向何处的路标。

雾还是 ticket? 检验是你现在能否精确陈述问题——不是你现在能否回答它。

  • 做成 ticket,当问题已经锋利——即便它被阻塞、你还不能动手。
  • 放进 Not yet specified,当你还不能那么锋利地措辞。不要预先把雾切成 ticket 大小的块:它比一张 ticket 更粗,一旦 frontier 到达,一块雾可能毕业成若干 tickets,或一张都没有。

Not yet specified 排除已经决定的(Decisions so far)、已经是活 ticket 的,以及超出范围的(下一节)。

超出范围

雾只朝向目的地聚集。目的地固定了范围,所以超出它的工作是超出范围——它不是雾,也不属于 Not yet specified。它在地图上有自己的 Out of scope 一节:你有意识地划出本次努力之外的工作。是范围而不是锋利度让它落在这里。

超出范围的工作永不毕业——frontier 停在目的地——所以只有目的地被重画时它才回来,而且是作为一次新努力,不是恢复。

把某物划出范围是划范围的动作,不是路线上的一步。当一张已存在的 ticket 结果落在目的地之外——绘图时误划进来,或被某次解决暴露——关闭它(关闭的 ticket 明确离开 frontier),并在 Out of scope 一节留一行:gist 加上为何超出范围,链到关闭的 ticket。它留在 Decisions so far 之外,后者记录实际走过的路线——范围边界不是其上的一步。

调用

两种模式。无论哪种,每会话绝不要解决超过一张 ticket——research tickets 除外。

绘制地图

用户带着一个松散想法调用。

  1. 命名目的地。 跑一轮 /grilling 和 /domain-modeling 会话,钉下这张地图要找到通往何处的路——spec、决策或变更。目的地固定范围,所以先定它。
  2. 绘制 frontier。 再 grill,这次广度优先:扇开整个空间,而不是在任一线索上深挖,挖出开放决策和现在可走的第一步。若这没有挖出雾——通往目的地的路已经清晰,整段旅程小到一次会话就够——你不需要地图。停下来问用户想怎么继续。
  3. 创建地图(标签 wayfinder:map):填好 Destination 和 Notes,Decisions-so-far 为空,把雾草进 Not yet specified。
  4. 创建你现在能规格化的 tickets 作为地图的 child issues——然后在第二遍接上阻塞边(issues 需要 ids 才能互相引用)。接线把它们分成 frontier 和被阻塞的;你还不能规格化的一切留在雾里——Not yet specified 一节。
  5. 发射 research subagents。 对你刚创建的每张 research ticket,拉起一个 /research subagent 并行解决,把发现捕获到一次性的 research/<name> 分支,并从 ticket 给出上下文指针。
  6. 停下——绘图是一次会话的工作;它不手解任何东西。

走完地图

用户带着一张地图(URL 或编号)调用。Ticket 是可选的——没有的话,由你挑下一个决策,不是用户。

  1. 加载地图——低分辨率视图,不是每张 ticket 的正文。
  2. 选择 ticket。若用户点了名,就用它。否则按顺序取第一张 frontier ticket。认领它:在任何工作之前指派给自己。
  3. 解决它——按需放大:按需拉取任何相关或已关闭 ticket 的完整正文;调用 ## Notes 块点名的 skills。若有疑问,用 /grilling 和 /domain-modeling。
  4. 记录解决:把答案作为 resolution comment 发出,关闭 issue,并把上下文指针追加到地图的 Decisions-so-far。
  5. 加入新浮现的 tickets(先创建再接线);把答案已使其可规格化的任何雾毕业,从 Not yet specified 清掉每个已毕业的块,使它只作为新 ticket 存在。若答案揭示某张 ticket——这一张或另一张——落在目的地之外,划出范围而不是在路线上解决它。若该决策使地图其他部分失效,更新或删除那些 tickets。

用户可能并行跑未阻塞的 tickets,所以预期其他会话会并发编辑 tracker。

04 同仓库更多 Skills