@namewta/speculo 0.1.21 → 0.2.0

package/template/vendor/matt-pocock/productivity/writing-great-skills/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: writing-great-skills
+description: 编写和编辑高质量 skills 的参考指南 — 使 skill 行为可预测的词汇和原则。
+disable-model-invocation: true
+---
+
+一个 skill 的存在是为了从随机系统中提取确定性。**可预测性** —— 即 agent 每次运行时采取相同的*流程*，而非产生相同的输出 —— 是根本美德；以下每个杠杆都为此服务。
+
+**加粗术语**在 [`GLOSSARY.md`](GLOSSARY.md) 中有定义；可查阅获取完整含义。
+
+## 调用方式
+
+两种选择，付出不同的代价：
+
+- **模型调用** skill 保留 **description**，因此 agent 可以自主触发它，*并且*其他 skills 也可以触达它（你也仍然可以手动输入其名称）。它会产生**上下文负载** —— description 每轮都留在窗口里。实现机制：省略 `disable-model-invocation`，并编写一个面向模型的 description，包含丰富的触发短语（"当用户想要……、提及……时使用"）。
+- **用户调用** skill 将 description 从 agent 的触达范围中移除：只有你手动输入其名称才能调用它 —— 其他 skill 也无法触达它。零上下文负载，但它消耗**认知负载**：*你*是必须记住它存在的索引。实现机制：设置 `disable-model-invocation: true`；`description` 变为面向人类的 —— 一句摘要，去掉触发列表。
+
+只有当 agent 必须自行触达该 skill，或其他 skill 必须触达它时，才选择模型调用。如果它只需手动触发，则设为用户调用，不付出任何上下文负载。
+
+当用户调用 skills 多到你记不住时，积累的认知负载可以通过一个**路由 skill** 来解决：一个用户调用的 skill，列出其他 skills 以及何时使用它们。
+
+## 编写 description
+
+模型调用的 **description** 做两件事 —— 说明该 skill 是什么，并列出应触发它的**分支**。每个词都会增加**上下文负载**，所以 description 比正文更应该被严格修剪：
+
+- **将 skill 的主导词前置** —— description 是它发挥调用作用的地方。
+- **每个分支一个触发器。** 给单个分支换不同说法的同义词属于**重复** —— "使用 TDD 构建功能……要求测试优先开发" 是一个分支写了两次。收拢它们；只保留真正不同的分支。
+- **删除正文中已有的身份信息。** 将 description 限制为触发器，以及任何"当另一个 skill 需要……"的触达子句。
+
+## 信息层级
+
+一个 skill 由两种内容类型构成 —— **步骤**和**参考** —— 它们可以自由混合：一个 skill 可以全是步骤、全是参考，或两者兼有。核心决策是使用哪种以及每种在**信息层级**上的位置，该层级按 agent 对材料需求的紧急程度排序：
+
+1. **skill 内步骤** —— `SKILL.md` 中的有序操作，是最主要的层级：agent 按顺序做什么。每个步骤以一个**完成标准**结束，即告诉 agent 工作完成的条件。使其*可检查*（agent 能否区分已完成和未完成？），并在重要时做到*穷尽*（"每个修改过的模型都已覆盖"，而非"生成一个变更列表"）—— 模糊的标准会引发**过早完成**。
+2. **skill 内参考** —— `SKILL.md` 中的定义、规则或事实，按需查阅。通常是一组合法的扁平同级项（例如一次 review 的所有规则处于同一层级）—— 这是一种合理的安排，不是异味。*本 skill 就是纯参考。*
+3. **外部参考** —— 从 `SKILL.md` 中移出到单独文件的参考，通过**上下文指针**触达，仅在指针被触发时加载。（范围从*已披露*参考 —— 如 `GLOSSARY.md` 这样的同级文件，仍属于该 skill 的一部分 —— 到完全的**外部参考**，存在于 skill 系统之外，任何 skill 都可以指向它。）
+
+一个严格的完成标准驱动彻底的**实地探查** —— agent 在工作过程中的深入挖掘 —— 无论 skill 是否有步骤，因为"每条规则都已应用"绑定扁平参考，正如"每个步骤都已完成"绑定一个顺序一样。
+
+推得太少则顶层膨胀；推得太多则隐藏了 agent 实际需要的材料。这种张力就是整个决策。
+
+**渐进式披露**是沿层级向下移动 —— 从 `SKILL.md` 中移出到链接文件 —— 使顶层保持清晰可读。实现机制：skill 文件夹中一个链接的 `.md` 文件，以其包含的内容命名（本 skill 将其完整定义披露到 `GLOSSARY.md`）。有些 skills 以不止一种方式使用，每种不同的使用方式是一个**分支** —— 不同次运行走 skill 的不同路径。分支是最清晰的披露测试标准：将每个分支都需要的材料内联，将只有某些分支需要的材料放到指针后面。**上下文指针**的*措辞*，而非其目标，决定了 agent 触达该材料的时机和可靠性。
+
+层级决定了一段内容*放在多远的位置*，而**就近原则**决定了*它旁边放什么*：将概念的定义、规则和注意事项放在同一个标题下，而非散落各处，这样读一处就能连带看到其周边内容。
+
+## 何时拆分
+
+**粒度**指你分割 skills 的细密程度，每次切割消耗两种负载之一，因此仅在切割值得时才拆分。两种切割方式：
+
+- **按调用** —— 当你有一个独特的**主导词**应独立触发时，或另一个 skill 必须触达它时，拆分出一个**模型调用** skill。你为新产生的始终加载的 **description** 付出**上下文负载**，所以这种独立触达能力必须值得。
+- **按顺序** —— 当后续步骤（一个步骤的**完成后步骤**）诱使 agent 仓促完成当前步骤（**过早完成**）时，拆分一段**步骤**序列。将它们移出视野鼓励 agent 对当前任务做更多**实地探查**。
+
+## 修剪
+
+将每个含义保留在**单一事实来源**中：一个权威位置，这样改变行为只需修改一处。
+
+检查每一行是否具备**相关性**：它是否仍然影响该 skill 的行为？
+
+然后逐句而非逐行地猎杀**无效操作**：对每个句子单独执行无效操作测试，当句子未通过时，删除整个句子，而非从中修剪词语。要激进 —— 大多数未通过的文本应该删除，而非重写。
+
+## 主导词
+
+**主导词**是一个紧凑的概念，已存在于模型的预训练中，agent 在运行该 skill 时用它来思考（例如*课程*、*战争迷雾*、*示踪子弹*）。它在文本中反复出现（尽管不一定 —— 一个强有力的主导词可能只需出现一次），积累出一种分布式定义，通过调用模型已有的先验知识，以最少的 token 锚定整个行为区域。
+
+它两次服务于可预测性。在正文中它锚定*执行*：每次该词出现时，agent 都会采取相同的行为。在 description 中它锚定*调用*：当同一个词出现在你的提示语、文档和代码中时，agent 将该共享语言与 skill 关联起来，更可靠地触发它。
+
+寻找机会将 skills 重构为使用主导词。在三处地方展开的三元组（**重复**），一个用一整句话来暗示一个概念的 description —— 每一处都是恳请**收拢**为单个 token 的段落。示例如下：
+
+- "快速、确定性、低开销" -> *紧凑* —— 一个在某个阶段被反复重述的特性 —— 收拢为一个预训练词（一个*紧凑*的循环）。
+- "一个你相信的循环" -> *红色* —— 将模糊的门禁转换为二进制可观察状态（循环在 bug 上变*红*，或不变）。
+
+你赢两次：更少的 token，*以及* agent 用来锚定其思考的更锐利的钩子。假定每个 skill 都携带着可以被主导词消除的重述 —— 去找到它们。
+
+## 失败模式
+
+用这些来诊断用户在使用 skill 时可能遇到的问题。
+
+- **过早完成** —— 在真正完成之前就结束一个步骤，注意力滑向*完成状态*。防御手段，按顺序：首先锐化完成标准（成本低，局部修改）；仅当标准不可简化的模糊*且*你观察到仓促行为时，通过拆分（按顺序切割）隐藏完成后步骤。
+- **重复** —— 同一含义出现在不止一个地方。增加维护成本和 token 消耗，并将含义在层级上的显著度虚高到超出其实际排名。
+- **沉积** —— 因为增加感觉安全而删除感觉危险，导致陈旧层堆积。任何没有修剪纪律的 skill 的默认命运。
+- **蔓延** —— skill 过于冗长，即使每一行都是活的且独特的。损害可读性和可维护性，浪费 token。解药是层级：将**参考**披露到指针后面，并按**分支**或顺序拆分，使每条路径只携带其所需的内容。
+- **无效操作** —— 模型默认就会遵守的行，你付出负载却说不出任何效果。测试标准：它是否改变了默认行为？一个弱主导词（当 agent 已经大致做到时要求*彻底*）就是无效操作；修复方法是用更强烈的词（*毫不留情*），而非换一种技巧。
+- **否定** —— 通过禁止来引导会适得其反：*不要想大象* 命名了大象，使其更易被调用，而非更少。使用**积极**措辞 —— 陈述目标行为，使被禁止的行为从未被提及；保留禁止性表述仅作为一种无法用积极方式表达的硬护栏，即便如此，也要成对提供替代行为。

package/template/workflows/matt-pocock/WORKFLOW.md

@@ -0,0 +1,145 @@
+---
+id: matt-pocock
+type: workflow
+workflow: matt-pocock
+name: Matt Pocock Workflow
+description: 以路由优先方式组合原生 Matt Pocock skills，并在 Speculo 私有状态根内持久化
+keywords: [matt-pocock, engineering, productivity, grilling, tdd, review]
+---
+
+# Matt Pocock Workflow
+
+先读取项目根 `speculo/.speculo/workspace.json`，再激活本 workflow。所有状态位于 `state` 根绑定的 `matt-pocock` 子树；所有 route 只按命中分支物理渐进披露。
+
+直接运行 vendor raw skill 不继承本 workflow 的路径上下文和持久化保证。
+
+## 运行时根
+
+```xml
+<runtime-context>
+  <root id="workflow" base="workflows" path="matt-pocock" />
+  <root id="state" base="state" path="matt-pocock" />
+  <root id="vendor:matt-pocock" base="vendor" path="matt-pocock" />
+</runtime-context>
+```
+
+## 持久化命名空间
+
+```xml
+<persistence root="state">
+  <store id="index" role="index" kind="file" path="status.json" create="initialize" />
+  <store id="changes" role="active" kind="directory" path="changes" create="initialize" />
+  <store id="archive" role="archive" kind="directory" path="archive" create="initialize" />
+  <store id="knowledge" role="knowledge" kind="directory" path="knowledge" create="lazy" consumers="docs-sync,retro,knowledge-prune" />
+  <store id="policy" role="policy" kind="directory" path="policy" create="lazy" consumers="docs-sync,knowledge-prune" />
+  <store id="integrations" role="integration" kind="directory" path="integrations" create="lazy" />
+  <store id="backlog" role="backlog" kind="directory" path="backlog" create="lazy" consumers="retro" />
+  <store id="legacy-config" role="legacy-knowledge" kind="directory" path=".config" create="existing-only" legacy="true" consumers="docs-sync,retro,knowledge-prune" />
+</persistence>
+```
+
+`status.json`、`changes/` 和 `archive/` 是 workflow 固定骨架；其余 store 只在 route 产生对应内容时创建。已有 `.config/` 只作为兼容来源读取，不作为新内容默认写入位置。
+
+## 路由
+
+```xml
+<routes>
+  <route id="idea-to-delivery" order="1" root="workflow" path="routes/idea-to-delivery.md">
+    <when>用户要把想法、需求或明确任务推进为规范、实现和交付。</when>
+  </route>
+  <route id="wayfinder" order="2" root="workflow" path="routes/wayfinder.md">
+    <when>目标庞大且跨多个上下文窗口，通往终点的决策路径仍不可见。</when>
+  </route>
+  <route id="triage" order="3" root="workflow" path="routes/triage.md">
+    <when>需要分类收到的 issue 或外部 PR/MR。</when>
+  </route>
+  <route id="diagnose" order="4" root="workflow" path="routes/diagnose.md">
+    <when>存在疑难 bug、异常、失败或性能回退。</when>
+  </route>
+  <route id="architecture" order="5" root="workflow" path="routes/architecture.md">
+    <when>需要扫描或讨论代码仓深化机会。</when>
+  </route>
+  <route id="review" order="6" root="workflow" path="routes/review.md">
+    <when>需要从固定点审查 diff 或作为实现收尾。</when>
+  </route>
+  <route id="merge-conflicts" order="7" root="workflow" path="routes/merge-conflicts.md">
+    <when>仓库正处于 merge 或 rebase 冲突中。</when>
+  </route>
+  <route id="research-prototype" order="8" root="workflow" path="routes/research-prototype.md">
+    <when>需要一手资料研究或一次性原型回答单个设计问题。</when>
+  </route>
+  <route id="productivity" order="9" root="workflow" path="routes/productivity.md">
+    <when>需要 handoff、教学或 skill 写作指导。</when>
+  </route>
+  <route id="experimental" order="10" root="workflow" path="routes/experimental.md">
+    <when>用户明确要求使用 vendor/in-progress 中的实验能力。</when>
+  </route>
+</routes>
+```
+
+## 进入协议
+
+```xml
+<sequence>
+  <phase id="select-change" order="1">
+    <skill root="skills" path="runtime-context/SKILL.md" activation="required" />
+    <artifact root="state" path="status.json" />
+    <completion>已选择唯一 active change，或原子创建新 change 与 .status.json。</completion>
+  </phase>
+  <phase id="route" order="2">
+    <skill root="vendor:matt-pocock" path="engineering/ask-matt/SKILL.md" activation="required" />
+    <completion>已根据用户意图选择一个 route；歧义时一次只澄清一个决策。</completion>
+  </phase>
+  <phase id="lazy-config" order="3">
+    <instructions root="workflow" path="routes/setup.md" />
+    <when>目标 route 依赖尚未配置的 tracker、triage 或 domain 文档。</when>
+    <completion>只补齐目标 route 必需的私有 namespace。</completion>
+  </phase>
+</sequence>
+```
+
+## 依赖
+
+```xml
+<dependencies>
+  <dependency kind="hard" root="vendor:matt-pocock" path="README.md">
+    选择本 workflow 时必须安装完整 matt-pocock vendor 目录。
+  </dependency>
+</dependencies>
+```
+
+## 状态扩展字段
+
+```xml
+<state-schema>
+  <field name="current_route" type="string" />
+  <field name="route_history" type="array" />
+  <field name="skill_history" type="array" />
+  <field name="external_refs" type="array" />
+  <field name="legacy_source" type="object|null" />
+</state-schema>
+```
+
+## 状态转移
+
+```xml
+<transitions>
+  <transition from="route" to="phase">
+    <when>route 已选定且所需 namespace 可用。</when>
+  </transition>
+  <transition from="phase" to="route">
+    <when>当前能力完成并需要进入另一条路线；同一目标继续复用当前 change。</when>
+  </transition>
+  <transition from="active" to="archived">
+    <command root="commands" path="finalize.md" />
+    <when>用户确认交付边界且完成门禁通过。</when>
+  </transition>
+</transitions>
+```
+
+## 持久化与副作用
+
+- 所有本地记录先写入当前 change；长期知识、规则、集成配置和 backlog 只写入已声明的 state namespace。
+- 原 skill 指向根目录、`.scratch/`、`docs/agents/` 或系统临时目录时，改用当前 change 或声明 namespace 中的等价路径。
+- 发布 issue、评论、标签、提交代码、合并或删除 worktree 前必须展示动作并获得明确确认；结果写入 `external_refs`。
+- 项目代码、测试和用户要求更新的项目文档不是 Speculo 运行时产物。临时原型必须删除，保留其结论。

package/template/workflows/matt-pocock/_state/status.json

@@ -0,0 +1,5 @@
+{
+  "schema_version": 1,
+  "workflow": "matt-pocock",
+  "active": []
+}

package/template/workflows/matt-pocock/routes/architecture.md

@@ -0,0 +1,24 @@
+# Architecture
+
+## 阶段
+
+```xml
+<sequence>
+  <phase id="scan" order="1">
+    <skill root="vendor:matt-pocock" path="engineering/improve-codebase-architecture/SKILL.md" activation="adapted" />
+    <skill root="vendor:matt-pocock" path="engineering/codebase-design/SKILL.md" activation="required" />
+    <artifact root="change" path="architecture/candidates.html" />
+    <completion>报告写入当前 change 而非系统临时目录，候选使用统一设计词汇。</completion>
+  </phase>
+  <phase id="select-grill" order="2">
+    <skill root="vendor:matt-pocock" path="productivity/grilling/SKILL.md" activation="required" />
+    <skill root="vendor:matt-pocock" path="engineering/domain-modeling/SKILL.md" activation="required" />
+    <artifact root="change" path="architecture/design.md" />
+    <completion>用户选择的候选已遍历设计树，拒绝理由和 ADR 候选已确认。</completion>
+  </phase>
+  <phase id="deliver" order="3">
+    <instructions root="workflow" path="routes/idea-to-delivery.md" />
+    <completion>选中设计已进入 spec 或 implement。</completion>
+  </phase>
+</sequence>
+```

package/template/workflows/matt-pocock/routes/diagnose.md

@@ -0,0 +1,22 @@
+# Diagnose
+
+## 阶段
+
+```xml
+<sequence>
+  <phase id="feedback-loop" order="1">
+    <skill root="vendor:matt-pocock" path="engineering/diagnosing-bugs/SKILL.md" activation="required" />
+    <artifact root="change" path="diagnosis/feedback-loop.md" />
+    <completion>存在一条已运行、能对当前症状变红、快速且确定的命令；否则 blocked。</completion>
+  </phase>
+  <phase id="diagnose-fix" order="2">
+    <artifact root="change" path="diagnosis/report.md" />
+    <completion>复现已最小化，假设已验证，修复前已有正确缝合点的回归测试。</completion>
+  </phase>
+  <phase id="architecture-followup" order="3">
+    <when>缺少正确测试缝合点或暴露架构摩擦。</when>
+    <instructions root="workflow" path="routes/architecture.md" />
+    <completion>架构发现已记录，不阻塞 bug 修复完成。</completion>
+  </phase>
+</sequence>
+```

package/template/workflows/matt-pocock/routes/experimental.md

@@ -0,0 +1,18 @@
+# Experimental
+
+本 route 不参与默认选择。进入前明确告知能力位于 vendor/in-progress，可能发生破坏性变化。
+
+## 路由
+
+```xml
+<routes>
+  <route id="loop-me" order="1" root="vendor:matt-pocock" path="in-progress/loop-me/SKILL.md" />
+  <route id="wizard" order="2" root="vendor:matt-pocock" path="in-progress/wizard/SKILL.md" />
+  <route id="claude-handoff" order="3" root="vendor:matt-pocock" path="in-progress/claude-handoff/SKILL.md" />
+  <route id="writing-fragments" order="4" root="vendor:matt-pocock" path="in-progress/writing-fragments/SKILL.md" />
+  <route id="writing-beats" order="5" root="vendor:matt-pocock" path="in-progress/writing-beats/SKILL.md" />
+  <route id="writing-shape" order="6" root="vendor:matt-pocock" path="in-progress/writing-shape/SKILL.md" />
+</routes>
+```
+
+所有文件输出改写到当前 change 的 `experimental/<route>/`。启动后台 agent、写 secrets、创建脚本、提交文件或操作外部系统前必须单独确认并记录 receipt。

package/template/workflows/matt-pocock/routes/idea-to-delivery.md

@@ -0,0 +1,63 @@
+# Idea To Delivery
+
+## 阶段
+
+```xml
+<sequence>
+  <phase id="grill" order="1">
+    <skill root="vendor:matt-pocock" path="engineering/grill-with-docs/SKILL.md" activation="conditional">
+      <when>当前任务位于已有代码仓，需要同步领域语言与 ADR 候选。</when>
+    </skill>
+    <skill root="vendor:matt-pocock" path="productivity/grill-me/SKILL.md" activation="conditional">
+      <when>用户显式要求 grill-me，或计划/设计不依赖现有代码仓。</when>
+    </skill>
+    <skill root="vendor:matt-pocock" path="productivity/grilling/SKILL.md" activation="required" />
+    <skill root="vendor:matt-pocock" path="engineering/domain-modeling/SKILL.md" activation="conditional">
+      <when>存在代码仓并需要沉淀领域语言或 ADR 候选。</when>
+    </skill>
+    <artifact root="change" path="decision-log.md" />
+    <completion>一次只确认一个决策；所有关键分支均已清晰且用户确认达成共识后，才允许形成 Plan 或进入 spec。CONTEXT/ADR 仅在确认后写入 knowledge namespace。</completion>
+  </phase>
+  <phase id="detour" order="2">
+    <when>问题需要一手资料或可运行/UI 答案。</when>
+    <instructions root="workflow" path="routes/research-prototype.md" />
+    <completion>答案与来源已回填 decision-log，临时代码已删除。</completion>
+  </phase>
+  <phase id="spec" order="3">
+    <skill root="vendor:matt-pocock" path="engineering/to-spec/SKILL.md" activation="adapted" />
+    <artifact root="change" path="spec/spec.md" />
+    <completion>spec 先本地落盘；外发 tracker 需要单独确认。</completion>
+  </phase>
+  <phase id="tickets" order="4">
+    <when>工作跨多个上下文窗口。</when>
+    <skill root="vendor:matt-pocock" path="engineering/to-tickets/SKILL.md" activation="adapted" />
+    <artifact root="change" path="tracker/tickets.md" />
+    <completion>垂直切片与阻塞边已获用户批准，外发引用已回写。</completion>
+  </phase>
+  <phase id="implement" order="5">
+    <skill root="vendor:matt-pocock" path="engineering/implement/SKILL.md" activation="adapted" />
+    <skill root="vendor:matt-pocock" path="engineering/tdd/SKILL.md" activation="required" />
+    <artifact root="change" path="implementation/log.md" />
+    <completion>每个切片已验证；commit 仅在用户确认后执行。</completion>
+  </phase>
+  <phase id="review" order="6">
+    <instructions root="workflow" path="routes/review.md" />
+    <completion>标准轴与规范轴均已有报告。</completion>
+  </phase>
+  <phase id="finalize" order="7">
+    <command root="commands" path="finalize.md" />
+    <completion>全局完成门禁通过并归档，或明确 blocked。</completion>
+  </phase>
+</sequence>
+```
+
+## 状态转移
+
+```xml
+<transitions>
+  <transition from="grill" to="spec"><when>决策完整且无需继续 detour。</when></transition>
+  <transition from="spec" to="tickets"><when>实现跨上下文。</when></transition>
+  <transition from="spec" to="implement"><when>单上下文可完成。</when></transition>
+  <transition from="review" to="implement"><when>审查发现必须修复的问题。</when></transition>
+</transitions>
+```

package/template/workflows/matt-pocock/routes/merge-conflicts.md

@@ -0,0 +1,19 @@
+# Merge Conflicts
+
+## 阶段
+
+```xml
+<sequence>
+  <phase id="inspect-intent" order="1">
+    <skill root="vendor:matt-pocock" path="engineering/resolving-merge-conflicts/SKILL.md" activation="required" />
+    <artifact root="change" path="merge-conflicts/record.md" />
+    <completion>每个冲突双方的一手意图已查明。</completion>
+  </phase>
+  <phase id="resolve-verify" order="2">
+    <completion>冲突全部解决、自动化检查通过；没有发明新行为或执行 abort。</completion>
+  </phase>
+  <phase id="continue" order="3">
+    <completion>继续 merge/rebase 与 commit 前已展示动作并获得确认。</completion>
+  </phase>
+</sequence>
+```

package/template/workflows/matt-pocock/routes/productivity.md

@@ -0,0 +1,25 @@
+# Productivity
+
+## 路由
+
+```xml
+<routes>
+  <route id="handoff" order="1">
+    <skill root="vendor:matt-pocock" path="productivity/handoff/SKILL.md" activation="adapted" />
+    <artifact root="change" path="handoffs/{topic}.md" />
+    <when>需要跨会话或分叉上下文。</when>
+  </route>
+  <route id="teach" order="2">
+    <skill root="vendor:matt-pocock" path="productivity/teach/SKILL.md" activation="adapted" />
+    <artifact root="change" path="teaching/" />
+    <when>用户要跨会话学习主题。</when>
+  </route>
+  <route id="writing-great-skills" order="3">
+    <skill root="vendor:matt-pocock" path="productivity/writing-great-skills/SKILL.md" activation="required" />
+    <artifact root="change" path="skill-authoring/report.md" />
+    <when>用户要设计或审查 skill。</when>
+  </route>
+</routes>
+```
+
+原 handoff 的系统临时目录与 teach 的当前目录均替换为上述 change 内路径。

package/template/workflows/matt-pocock/routes/research-prototype.md

@@ -0,0 +1,20 @@
+# Research And Prototype
+
+## 阶段
+
+```xml
+<sequence>
+  <phase id="research" order="1">
+    <when>答案需要当前仓库之外的一手来源。</when>
+    <skill root="vendor:matt-pocock" path="engineering/research/SKILL.md" activation="conditional" />
+    <artifact root="change" path="research/{topic}.md" />
+    <completion>每项结论有一手来源，文件留在当前 change。</completion>
+  </phase>
+  <phase id="prototype" order="2">
+    <when>状态、逻辑或 UI 需要可运行答案。</when>
+    <skill root="vendor:matt-pocock" path="engineering/prototype/SKILL.md" activation="conditional" />
+    <artifact root="change" path="prototypes/{topic}/answer.md" />
+    <completion>答案已保留；一次性代码、数据库和路由已删除或明确吸收进实现。</completion>
+  </phase>
+</sequence>
+```

package/template/workflows/matt-pocock/routes/review.md

@@ -0,0 +1,19 @@
+# Review
+
+## 阶段
+
+```xml
+<sequence>
+  <phase id="fixed-point" order="1">
+    <skill root="vendor:matt-pocock" path="engineering/code-review/SKILL.md" activation="required" />
+    <completion>固定点可解析、diff 非空、规范与标准来源已记录。</completion>
+  </phase>
+  <phase id="parallel-axes" order="2">
+    <artifact root="change" path="review/report.md" />
+    <completion>标准轴与规范轴相互隔离执行，并排呈现且不重新排名。</completion>
+  </phase>
+  <phase id="decision" order="3">
+    <completion>发现数量、各轴最严重问题和下一步已记录；未经要求不实施修复。</completion>
+  </phase>
+</sequence>
+```

package/template/workflows/matt-pocock/routes/setup.md

@@ -0,0 +1,42 @@
+# Route Setup
+
+仅在目标 route 缺少配置时读取原 setup skill；保持其探索和逐项确认方法，但使用 Matt 已声明的 state namespace。
+
+## 阶段
+
+```xml
+<sequence>
+  <phase id="discover-config" order="1">
+    <skill root="vendor:matt-pocock" path="engineering/setup-matt-pocock-skills/SKILL.md" activation="adapted" />
+    <completion>已展示仓库、tracker 和领域文档现状。</completion>
+  </phase>
+  <phase id="configure-tracker" order="2">
+    <when>route 需要 issue tracker。</when>
+    <template root="vendor:matt-pocock" path="engineering/setup-matt-pocock-skills/issue-tracker-local.md" />
+    <artifact root="state" path="integrations/issue-tracker.md" />
+    <completion>用户已确认 GitHub、GitLab、本地或其他 tracker；本地 tracker 根为当前 change/tracker。</completion>
+  </phase>
+  <phase id="configure-triage" order="3">
+    <when>route 为 triage 或 wayfinder。</when>
+    <template root="vendor:matt-pocock" path="engineering/setup-matt-pocock-skills/triage-labels.md" />
+    <artifact root="state" path="integrations/triage-labels.md" />
+    <completion>五个角色已映射到真实标签。</completion>
+  </phase>
+  <phase id="configure-domain" order="4">
+    <when>route 会读取或维护领域语言。</when>
+    <template root="vendor:matt-pocock" path="engineering/setup-matt-pocock-skills/domain.md" />
+    <artifact root="state" path="knowledge/domain.md" />
+    <completion>domain.md 指向本 workflow 的 knowledge/context/ 与 knowledge/adr/，未修改项目根 AGENTS/CLAUDE/docs。</completion>
+  </phase>
+</sequence>
+```
+
+## 状态转移
+
+```xml
+<transitions>
+  <transition from="missing-config" to="configured">
+    <when>目标 route 的必要配置均已由用户确认并写入声明 namespace。</when>
+  </transition>
+</transitions>
+```

package/template/workflows/matt-pocock/routes/triage.md

@@ -0,0 +1,25 @@
+# Triage
+
+## 阶段
+
+```xml
+<sequence>
+  <phase id="collect" order="1">
+    <skill root="vendor:matt-pocock" path="engineering/triage/SKILL.md" activation="adapted" />
+    <artifact root="change" path="triage/{item}/record.md" />
+    <completion>完整正文、评论、标签、diff、冗余性与私有 out-of-scope 已检查。</completion>
+  </phase>
+  <phase id="recommend" order="2">
+    <completion>类别与状态建议已向维护者展示并等待决定。</completion>
+  </phase>
+  <phase id="validate-grill" order="3">
+    <when>声明需要复现或需求仍不完整。</when>
+    <skill root="vendor:matt-pocock" path="productivity/grilling/SKILL.md" activation="conditional" />
+    <skill root="vendor:matt-pocock" path="engineering/domain-modeling/SKILL.md" activation="conditional" />
+    <completion>事实已验证，问题逐个解决。</completion>
+  </phase>
+  <phase id="apply" order="4">
+    <completion>拟发布评论、标签、关闭动作先本地记录并经确认；结果引用已写回。</completion>
+  </phase>
+</sequence>
+```

package/template/workflows/matt-pocock/routes/wayfinder.md

@@ -0,0 +1,27 @@
+# Wayfinder
+
+## 阶段
+
+```xml
+<sequence>
+  <phase id="name-destination" order="1">
+    <skill root="vendor:matt-pocock" path="engineering/wayfinder/SKILL.md" activation="required" />
+    <skill root="vendor:matt-pocock" path="productivity/grilling/SKILL.md" activation="required" />
+    <skill root="vendor:matt-pocock" path="engineering/domain-modeling/SKILL.md" activation="required" />
+    <completion>目的地与范围边界已确认。</completion>
+  </phase>
+  <phase id="map-frontier" order="2">
+    <artifact root="change" path="wayfinder/map.md" />
+    <artifact root="change" path="wayfinder/tickets/" />
+    <completion>只创建当前可明确的 tickets，战争迷雾留在 map。</completion>
+  </phase>
+  <phase id="walk-one-ticket" order="3">
+    <completion>一次会话只领取并解决一个前沿 ticket；本地先记录，外发需确认。</completion>
+  </phase>
+  <phase id="handoff" order="4">
+    <when>路径已清晰。</when>
+    <instructions root="workflow" path="routes/idea-to-delivery.md" />
+    <completion>已转入 spec 或 implement，未把寻路当成交付。</completion>
+  </phase>
+</sequence>
+```