wayfinder
把一大块工作(超过一个 agent 会话能装下的)规划为 issue 跟踪器上一张由决策 ticket 构成的共享地图,然后一次解决一个,直到通往目的地的路清晰可见。
- License 许可
- MIT
- 最近更新
- 2026-10-19
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- wayfinder
- description
- 把一大块工作(超过一个 agent 会话能装下的)规划为 issue 跟踪器上一张由决策 ticket 构成的共享地图,然后一次解决一个,直到通往目的地的路清晰可见。
- commit_version
- 8295b8e10d4cdb6cce772a56dda7b7c37075074d
- disable-model-invocation
- true
02 资源文件 1
- 参考文档agents/openai.yaml150 B
03 SKILL.md 正文
一个模糊的想法出现了,太大,一个 agent 会话装不下,而且笼罩在迷雾中:从这里到目的地的路还看不见。Wayfinding 是关于找到那条路,而不是朝目的地猛冲。本技能把这条路绘制成仓库 issue 跟踪器上的一张共享地图,然后一次一个地处理它的决策 ticket(解决结果是一个决定的问题,而不是要执行的构建切片),直到路线清晰。
目的地因每项工作而异,而命名它是绘制地图的第一个动作,它塑造每一个 ticket。它可能是一份要交接并迭代的规格、一个要在规划开始前敲定的决定,或一次就地完成的改动(比如数据结构迁移)。地图是领域无关的:工程工作、课程内容,任何符合这个形状的东西都行。
规划,而不是执行
Wayfinder 默认是规划:每个 ticket 解决一个决策,当路清晰时地图就完成了:在有人去真正做那件事之前,没有剩下要决定的东西。想要直接动手做的冲动,通常就是你已经到达地图边缘、该交接了的信号。一项工作可以在它的 Notes 中覆盖这一点(把执行带进地图本身),但如果没有这样的覆盖,就产出决定,而不是交付物。
用名字称呼
每张地图和每个 ticket 都是一个 issue,所以它有一个名字:它的标题。在一切人类会读到的内容中(叙述、地图的 Decisions-so-far),用那个名字称呼它,永远不要用光秃秃的 id、编号或 slug。一墙 #42, #43, #44 是没法读的;名字一目了然。id 和 URL 不会消失(名字包裹着它的链接),但它们待在名字_内部_,永远不代表名字本身。
地图
地图是本仓库 issue 跟踪器上的单个 issue,带 wayfinder:map 标签,它是权威制品。它的 ticket 是地图的子 issue。
地图是索引,不是仓库。它列出已做出的决定,并指向保存其细节的 ticket;一个决定恰好只存在于一个地方(它的 ticket),所以地图从不复述它,只做摘要并链接。
地图、它的子 ticket、阻塞和 frontier 查询在物理上存放在哪里,是因跟踪器而异的。 issue 跟踪器应该已经提供给你了。如果没有,告诉用户运行 /setup-matt-pocock-skills。查阅跟踪器文档的 "Wayfinding operations" 小节,了解_本_仓库如何表达它们。如果没有提供跟踪器,默认使用本地 markdown 跟踪器。
地图正文
整张地图的低分辨率视图,每个会话加载一次。未关闭的 ticket不列出:它们是未关闭的子 issue,通过查询找到。
## Destination
<到达这张地图终点是什么样子,即这项工作正在寻找通往它的路的那个规格、决定或改动。一两行;每个会话在选择 ticket 之前先以此定向。>
## Notes
<领域;每个会话都应查阅的技能;这项工作的长期偏好>
## Decisions so far
<!-- 索引:每个已关闭 ticket 一行:足以判断相关性,然后放大链接去看 ticket 保存的细节 -->
- [<closed ticket title>](link) — <答案的一句话摘要>
## Not yet specified
<!-- 见"战争迷雾":还无法做成 ticket 的在范围内迷雾;随 frontier 推进而毕业 -->
## Out of scope
<!-- 见"超出范围":被判定在目的地之外的工作;已关闭,永不毕业 -->
Ticket
每个 ticket 是地图的一个子 issue;跟踪器的 issue id 就是它的身份。它的正文是那个问题,大小以一个 100K token 的 agent 会话为准:
## Question
<这个 ticket 要解决的决策或调查>
每个 ticket 携带一个 wayfinder:<type> 标签:research、prototype、grilling、task 之一(见 Ticket 类型)。wayfinder: 标签是地图及其 ticket 携带的唯一标签,绝不挂 ready-for-agent 之类的 triage 标签:它们是决策,不是实现工作。
会话通过把 ticket 指派给驱动地图的开发者来认领它,最先做,在任何工作之前,这样并发会话会跳过它。那个指派人_就是_认领:一个未关闭、未指派的 ticket 就是未认领的。
阻塞使用跟踪器的原生依赖关系,这很关键,因为它能在跟踪器自己的 UI 中_可视化地_呈现 frontier,让人类不用打开地图就能看到什么可以拿。只有缺乏原生阻塞的跟踪器才退回正文约定。当阻塞一个 ticket 的所有 ticket 都关闭时,它就是未阻塞的;frontier 是那些未关闭、未阻塞、未认领的子 ticket,即已知的边缘。
答案不属于正文:它在解决时记录(见走遍地图)。解决 ticket 过程中产出的资产从 issue 上链接,而不是粘贴进去。
Ticket 类型
每个 ticket 要么是 HITL(人类在环中,与为自己发言的人类_一起_处理),要么是 AFK,由 agent 单独驱动。HITL ticket 只能通过那种实时交流来解决;agent 永远代替不了人类的那一方(一个自问自答的 grilling agent 就破坏了这一点)。
- Research(AFK):阅读文档、第三方 API 或本地资源(如知识库),浮现某个决策所等待的事实。由调用 Skill 工具并传入 "research" 的子 agent 解决。当需要当前工作目录之外的知识时使用。
- Prototype(HITL):通过做一个便宜、粗糙、具体、可供评头论足的制品来提高讨论的保真度:一个大纲、一个粗略的尝试、一个 stub,或 UI/逻辑代码,通过调用 Skill 工具并传入 "prototype" 完成。把原型链接为资产。当"它应该长什么样"或"它应该怎么表现"是关键问题时使用。
- Grilling(HITL):对话。默认情况。始终调用 Skill 工具两次,分别传入 "grilling" 和 "domain-modeling"。
- Task(HITL 或 AFK):在做出某个_决定_之前必须完成的手工工作:没有什么要决定、原型或研究的,但在它完成之前讨论被卡住。注册一个服务以便评估它的 API、开通访问权限、移动数据以便看清它的形状。这是唯一一个_动手做_而不是做决定的类型:它赢得自己位置的方式是解锁一个决策,而不是交付目的地。agent 能单独驱动就单独驱动(AFK);否则交给人类一份精确的清单(HITL)。工作完成即解决;答案记录做了什么以及后续 ticket 依赖的任何事实(凭据位置、新 URL、行数)。
战争迷雾
地图是_刻意_不完整的:不要绘制你还看不见的东西。在活跃 ticket 之外是战争迷雾,即对那些你能感觉到正在逼近、但还无法确定的决策和调查的朦胧视野,因为它们悬在仍未解决的问题上。解决一个 ticket 会清除它前方的迷雾,让现在可以说清楚的东西毕业成为新的 ticket,一次一个,直到通往目的地的路清晰、再没有 ticket 剩余。
地图的 Not yet specified 小节就是那个朦胧视野被写下来的地方:疑似的问题、以后要重访的区域。它是朝向目的地的未发现 frontier:这里的一切都在范围内,只是还不够清晰、无法做成 ticket。视野允许多宽松就写多宽松、多完整就写多完整;它同时充当协作者了解这项工作走向的路标。
迷雾还是 ticket? 检验标准是你现在能否精确陈述那个问题,而_不是_你能否现在回答它。
- 当问题已经足够清晰时做成ticket,即使它被阻塞、你还无法行动。
- 当你还无法把它表述得那么清晰时放进 Not yet specified。不要把迷雾预先切成 ticket 大小的块:它比 ticket 粗,而且当 frontier 抵达时,一片迷雾可能毕业成好几个 ticket,也可能一个都没有。
Not yet specified 排除已决定的事(Decisions so far)、已是活跃 ticket 的事,以及超出范围的事(下一节)。
超出范围
迷雾只朝目的地方向聚集。目的地固定了范围,所以超出它的工作是超出范围的:它不是迷雾,也不属于 Not yet specified。它在地图上有自己的 Out of scope 小节:你有意识地排除在_这_项工作之外的东西。让它落在这里的是范围,不是清晰度。
超出范围的工作永不毕业(frontier 在目的地处停止),所以它只有在目的地被重新绘制时才会回来,而且那时是作为一项全新的工作,而不是恢复。
把某件事判定为超出范围是一个定界行为,不是路线上的一步。当一个已存在的 ticket 被发现位于目的地之外(绘制时被错误地圈进了范围,或被某个解决暴露出来),关闭它(关闭的 ticket 明确地离开 frontier),并在 Out of scope 小节留一行:摘要加为什么超出范围,链接到已关闭的 ticket。它留在 Decisions so far 之外,因为后者记录的是实际走过的路线:范围边界不是路线上的一步。
调用方式
两种模式。无论哪种,每个会话解决的 ticket 永远不要超过一个,research ticket 除外。
绘制地图
用户带着一个模糊的想法调用。
- 命名目的地。 调用 Skill 工具两次,分别传入 "grilling" 和 "domain-modeling",确定这张地图在寻找通往什么的路:那个规格、决定或改动。目的地固定范围,所以它最先敲定。
- 绘制 frontier。 再次 grill,这次是广度优先:在整个空间上扇形展开,而不是在任何一条线上深入,浮现未决的决策和现在就能迈出的第一步。如果这没有浮现任何迷雾(通往目的地的路已经清晰,整段旅程小到一个会话就够),你不需要地图。停下来问用户想怎么继续。
- 创建地图(标签
wayfinder:map):填好 Destination 和 Notes,Decisions-so-far 留空,迷雾草图写进 Not yet specified。 - 创建你现在就能说清楚的 ticket,作为地图的子 issue,然后在第二遍中接好阻塞边(issue 需要先获得 id 才能互相引用)。交叉引用也在这一遍里用真实 id 写好:占位符
#<n>会自动链接到无关的 issue。接线把它们分拣进 frontier 和被阻塞的两堆;你尚且无法说清楚的一切都留在迷雾里,即 Not yet specified 小节。 - 发射 research 子 agent。 对你刚创建的每个
researchticket,启动一个调用 Skill 工具并传入 "research" 的子 agent 来并行解决它,把发现捕获到一个一次性的research/<name>分支上,并从 ticket 留下上下文指针。推送分支,但不开 PR:它永远不会被合并。 - 停下:绘制就是一个会话的工作;它不亲手解决任何东西。
走遍地图
用户带着一张地图(URL 或编号)调用。ticket 是可选的:没有指定时,由你来挑下一个决策,而不是用户。
- 加载地图:低分辨率视图,而不是每个 ticket 的正文。
- 选择 ticket。如果用户点名了一个,用它。否则按顺序取第一个 frontier ticket。认领它:在任何工作之前把它指派给自己。
- 按它的
wayfinder:<type>标签所命名的类型解决它(见 Ticket 类型)。读标签,不要只读正文:正文从不说明类型。按需放大:按需获取任何相关或已关闭 ticket 的完整正文;调用 Skill 工具并传入## Notes块点名的技能。拿不准时,调用 Skill 工具两次,分别传入 "grilling" 和 "domain-modeling"。 - 记录解决方案:把答案发布为一条解决评论,关闭 issue,并向地图的 Decisions-so-far 追加上下文指针。
- 添加新浮现的 ticket(先创建后接线);让答案已能说清楚的迷雾毕业,把每片毕业的迷雾从 Not yet specified 中清除,让它只以新 ticket 的形式存在。如果答案揭示某个 ticket(这一个或另一个)位于目的地之外,把它判定为超出范围,而不是在路线上解决它。如果这个决定使地图的其他部分失效,更新或删除那些 ticket。
用户可能会并行处理未阻塞的 ticket,所以要预期其他会话正在并发编辑跟踪器。
04 同仓库更多 Skills
skills-link
管理 muscaestar/skills 仓库的 skill 安装。当用户想安装/卸载某个 skill、查看已装清单、把 skill 装到全局或某个项目、或问"这个 skill 装了没有"时使用。也用于向用户解释三层结构与全局/项目双范围安装策略。
writing-shape
写作之 exploit:把原始素材塑形成一篇文章,逐段进行。
writing-fragments
写作之 explore:开采原始碎片,还没有结构。
writing-for-agents
为 agents 编写文档。在创建或编辑技能,或修改 AGENTS.md 或 CLAUDE.md 时使用。
writing-beats
写作之 exploit;把原始素材组装成一段由节拍(beat)构成的旅程,在每个节拍倚赖某个术语之前先把它落地。
wizard
生成一个交互式 bash 向导,引导人类完成只有他们才能执行的步骤。当需要配置基础设施、设置凭据或 CI secret、摸索不熟悉的第三方仪表盘,或执行一次性的迁移或切换时使用。不要为 agent 自己能执行的步骤调用本技能。