用途
Wayfinder 用于规划一个规模超出单个智能体会话所能容纳的工作块。当一个松散的想法已经出现，但通往目的地的路径仍被迷雾笼罩、尚不可见时，它负责“找路”，而不是直接冲向终点。它把这条路绘制成仓库问题追踪器上的一张共享地图，并逐个处理地图上的决策工单（即答案为一项决策、而非一段待执行构建的问题），直到路线清晰。
目的地因具体工作而异，命名目的地是绘图的第一步，因为它决定每张工单的形态。目的地可能是一份用于交接和迭代的规格说明、一个在规划开始前需要锁定的决策，或一处原地做出的改动（如数据结构迁移）。地图与领域无关，工程工作、课程内容等只要符合这种形态都可以使用。
主要概念
地图与工单：地图是仓库问题追踪器上的单个 issue，带 wayfinder:map 标签，是权威产物；工单是地图的子 issue。地图是索引而非仓库：它列出已做出的决策并链接到承载细节的工单，一项决策只存在于一个地方（其工单），地图只做摘要和链接，从不复述。
地图正文包含若干区块：Destination（目的地，一两行说明抵达地图终点是什么样子）、Notes（领域、每次会话应参考的技能、本工作的既定偏好）、Decisions so far（已关闭工单的一行索引及链接）、Not yet specified（尚未成形的迷雾）、Out of scope（明确排除在本工作之外的内容）。
命名引用：每张地图和工单都是一个 issue，因此都有名字（即标题）。在人类阅读的一切内容（叙述、地图的决策记录）中，都应以其名称引用，绝不用裸 id、编号或 slug 代替；id 与 URL 仍保留，但嵌在名称的链接里，不能顶替名称。
认领与阻塞：会话在任何工作之前先把工单指派给自己，作为认领标记，以便并发会话跳过它；开放且未指派的工单即未被认领。阻塞使用追踪器原生的依赖关系，这样追踪器界面本身就能直观显示前沿；仅在追踪器缺少原生阻塞能力时，才回退到正文约定。当所有阻塞该工单的工单都已关闭时，该工单即解除阻塞；前沿是开放、解除阻塞且未被认领的子工单。
工单类型：每张工单要么是 HITL（有人参与，与能代表自己发言的人共同完成），要么是 AFK（由智能体独自驱动）。HITL 工单只能通过实时交流解决，智能体绝不能代替人类一方作答。
- Research（AFK）：阅读文档、第三方 API 或本地知识库等资源，揭示某项决策所等待的事实。由调用 Skill 工具并传入 "research" 的子智能体解决；当需要当前工作目录之外的知识时使用。
- Prototype（HITL）：通过制作廉价、粗糙、具体的产物（提纲、粗略稿、桩代码或 UI/逻辑代码）供人反应，以提高讨论的保真度；将原型作为资产链接。当“应该长什么样”或“应该怎么表现”是核心问题时使用。
- Grilling（HITL）：对话，默认类型。总是调用 Skill 工具两次，分别传入 "grilling" 和 "domain-modeling"。
- Task（HITL 或 AFK）：在做出决策前必须完成的人工工作——无需决策、原型或研究，但讨论会因其未完成而受阻（例如注册某项服务以便评估其 API、开通访问权限、移动数据以便看清其形态）。这是唯一“做而非决”的类型，其价值在于解除某项决策的阻塞，而非交付目的地；能独自完成时由智能体驱动（AFK），否则交给人类一份精确的清单（HITL）。完成后解决，答案记录做了什么以及后续工单依赖的事实（凭据位置、新 URL、行数等）。
迷雾与范围
地图有意保持不完整：不要绘制还看不到的东西。在活跃工单之外是“战争迷雾”——你能感觉到即将到来、但因仍有未解问题而无法确定下来的决策与调查。解决一张工单会驱散其前方的迷雾，将如今已能明确表述的问题逐一毕业为新工单，直到通往目的地的路清晰、不再有工单。
地图的 Not yet specified 区块用于记录这种模糊视野：怀疑的问题、日后重访的领域。它是通往目的地未发现的前沿，此处内容都在范围内，只是还不够清晰，无法开成工单。判断迷雾还是工单的标准是：现在能否精确陈述该问题，而不是现在能否回答它。问题已足够明确就开成工单（即便被阻塞、暂时无法处理）；还不能如此表述就放入 Not yet specified。不要把迷雾预先切成工单大小的碎片，它比工单更粗，一片迷雾可能毕业成多张工单，也可能一张都没有。
Out of scope 区块记录有意识排除在本工作之外的工作。范围而非清晰度决定其归属；超出目的地的工作不属于迷雾，也不进入 Not yet specified。范围外的工作永不毕业（前沿在目的地处停止），只有在目的地被重新划定后才会以全新工作的形式回归，而非续接。若某张已存在的工单被发现位于目的地之外（绘图时误纳入，或被某次解决揭示出来），则关闭它（关闭的工单明确不在前沿），并在 Out of scope 中留一行：摘要、排除原因及该关闭工单的链接；它不进入 Decisions so far，因为后者记录的是实际走过的路线，范围边界不是路线上的一步。
使用方式
有两种模式。无论哪种，每次会话最多解决一张工单（research 工单除外）。
绘制地图（Chart the map）：用户以一个松散想法调用。先命名目的地：调用 Skill 工具两次，分别传入 "grilling" 与 "domain-modeling"，以确定这张地图要通往的规格、决策或改动；目的地决定范围，须先定下来。然后广度优先地再次 grilling，在整个空间铺开而非深挖单一线索，暴露待决问题与现在可迈出的第一步。若此举未发现迷雾（通往目的地的路已清晰、整个旅程小到一次会话即可完成），则不需要地图，停止并向用户询问希望如何推进。接着创建地图（标签 wayfinder:map）：填写 Destination 与 Notes，Decisions so far 留空，将迷雾勾勒进 Not yet specified，填写 Out of scope；除 Decisions so far 外每个区块都要有文字而非只有模板注释，暂时无内容的写 "None yet."。把现在能明确的工单创建为地图的子 issue，然后在第二轮补齐阻塞边（issue 需要先有 id 才能互相引用）；补齐后它们被分为前沿与被阻塞两类，尚不能明确表述的留在迷雾（Not yet specified）中。最后为刚创建的每张 research 工单启动调用 Skill 工具并传入 "research" 的子智能体并行解决，将发现记录在临时 research/<name> 分支上，并从工单留下上下文指针。绘图是一次会话的工作，到此停止，不直接解决任何工单。
沿地图推进（Work through the map）：用户以一张地图（URL 或编号）调用，工单可选；未指定时由智能体而非用户挑选下一项决策。加载地图（低分辨率视图，而非所有工单正文）。若用户指定了工单则用之，否则按顺序取第一张前沿工单；在任何工作前把它指派给自己以认领。按需放大：拉取相关或已关闭工单的完整正文，调用 Notes 区块点名的技能；若有疑问，调用 Skill 工具两次，分别传入 "grilling" 与 "domain-modeling"。记录解决结果：把答案作为解决评论发布，关闭该 issue，并在地图的 Decisions so far 追加一条上下文指针。添加新浮现的工单（先创建后连线），把答案使其可明确的迷雾毕业，并从 Not yet specified 清除已毕业的部分，使其只以新工单形式存在。若答案揭示某张工单（当前或其他）位于目的地之外，则将其排除出范围而非在路线上解决。若该决策使地图其他部分失效，则更新或删除相应工单。用户可能会并行运行未阻塞的工单，因此应预期其他会话同时编辑追踪器。
适用范围与限制
该技能默认“只规划”：每张工单解决一项决策，当地图完成时路线已清晰、在有人动手去做之前不再有需要决定的事项；“忍不住直接干活”的冲动通常意味着已到达地图边缘，应当交接。某项工作可在其 Notes 中覆盖此默认，将执行纳入地图本身；但无此说明时，只产出决策而非交付物。地图与工单的物理存放位置、阻塞与前沿查询方式因追踪器而异，应参阅追踪器文档的 "Wayfinding operations" 部分；若未提供追踪器，默认使用本地 Markdown 追踪器。路径均相对于仓库根目录，相关文档位于 docs/agents/issue-tracker.md。