@namewta/speculo 0.2.1 → 0.2.2

package/README.md

@@ -67,14 +67,16 @@ After initialization, the target project gains the following AI agent-callable a
 
 ### 2 Workflow Packages
 
-| Workflow | Routes | Description |
-|---|---|---|
-| **matt-pocock** | 10 | Route-first composition of Matt Pocock native skills (engineering + productivity) |
-| **person** | 1 | Persona-methodology-based consulting workflow |
+| Workflow | Routes | Atomic coverage | Description |
+|---|---:|---|---|
+| **matt-pocock** | 10 | Complete vendor inventory | Route composition plus one-to-one access to every stable and experimental Matt Pocock SKILL |
+| **person** | 1 | None | Persona-methodology-based consulting workflow without synthetic skill wrappers |
+
+Every workflow ships a peer `PERSISTENCE.md` as its sole runtime contract. `WORKFLOW.md` and each `atomic-skills/<id>.md` entry load it first, so composed routes and direct atomic calls resolve the same state root, active change, namespaces, and confirmation boundaries.
 
 ### Vendor Skill Collections
 
-- **Matt Pocock skills** — Engineering (ask-matt, implement, wayfinder, tdd, code-review, diagnosing-bugs, prototyping, research, domain-modeling, codebase-design, triage, setup, to-spec, to-tickets, grill-with-docs, improve-codebase-architecture) and Productivity (grill-me, handoff, teach, writing-great-skills)
+- **Matt Pocock skills** — The complete stable and explicitly enabled `in-progress` inventory, preserved as read-only vendor sources behind workflow-owned atomic wrappers.
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Workflow-packaged specification-driven development assets with install, update, and migration tooling.",
   "type": "module",
   "bin": {

package/template/.speculo/README.md

@@ -5,8 +5,8 @@
 ## 读取顺序
 
 1. 读取 `workspace.json`，以当前打开项目为 `project_root` 解析公共 roots。
-2. 读取 `../workflows/<workflow>/WORKFLOW.md` 的 `<runtime-context>` 与 `<persistence>`。
-3. 读取 `<workflow>/status.json`，再读取 `changes/<change>/.status.json` 和当前 route 产物。
+2. 从 `../workflows/<workflow>/WORKFLOW.md` 或 `atomic-skills/<id>.md` 进入，并首先读取同级 `PERSISTENCE.md` 的 `<runtime-context>`、`<persistence>` 与 change 启动协议。
+3. 读取 `<workflow>/status.json`，再读取 `changes/<change>/.status.json` 和当前 route/direct 产物。
 4. 历史 change 只从 `<workflow>/archive/YYYY-MM/<change>/` 读取。
 5. Command 报告位于 `commands/<command>/*.md`，command state 位于 `commands/<command>/state.json`。
 6. 首次 docs-sync 确认后读取 `<workflow>/docs-sync.json`；它分列该 workflow 的项目文档和私有 state 更新范围。
@@ -17,4 +17,4 @@
 - `docs-sync.json` 是 docs-sync command 拥有的延迟 sidecar，不进入 `_state`，也不授予越过 workflow 确认规则的权限。
 - `.config` 不是标准目录；只有 workflow 声明时才可使用。
 - Command 报告命名为 `<YYYY-MM-DD>-<scope>-<topic>[-NN].md`，禁止覆盖。
-- Skill 只使用调用方提供并完成边界校验的路径。
+- Atomic wrapper 可独立启动，但只使用 `PERSISTENCE.md` 解析并完成边界校验的路径；raw vendor SKILL 不直接选择持久化根。

package/template/commands/docs-sync.md

@@ -20,7 +20,7 @@ keywords: [docs-sync, readme, changelog, agents, documentation]
 
 1. 读取 `../skills/runtime-context/SKILL.md` 与 `../skills/docs-sync/SKILL.md`，解析 command 路径、`speculo/config.json`（不存在时以默认值静默降级）和全部已安装 workflow/state 根。
 2. 按 skill 的 Git 契约检查 tracked、staged、unstaged 与 untracked 内容；安全且校验通过时显式暂存并创建 checkpoint，异常时无损阻塞。
-3. 读取全局 state、各 `WORKFLOW.md` 和 sidecar。首次运行统一展示全局与每个 workflow 的候选范围；用户确认后为所有已安装 workflow 创建 sidecar，空范围也保留。
+3. 读取全局 state、各 `WORKFLOW.md`、同级 `PERSISTENCE.md` 和 sidecar。首次运行统一展示全局与每个 workflow 的候选范围；用户确认后为所有已安装 workflow 创建 sidecar，空范围也保留。
 4. 由 skill 收集精确 commit 区间、archive 与声明 store 证据，整份审计命中文档并执行新增、更新、删除段落、合并或保留。整文件/目录删除和受保护知识仍逐次确认。
 5. 运行项目与文档校验，原子写入报告、state 和 sidecar，再显式暂存本次产物并创建同步或 no-op commit。
 6. 重新读取 Git、state、报告与 sidecar；只有工作区干净、节点可复现且所有文件已提交时完成。

package/template/commands/knowledge-prune.md

@@ -14,7 +14,7 @@ keywords: [knowledge, prune, rules, lessons, context, adr]
 
 ## 执行
 
-1. 读取 `../skills/runtime-context/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级），选择 workflow 并解析其 `<persistence>` 声明的 knowledge/policy namespace。
+1. 读取 `../skills/runtime-context/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级），选择 workflow 并解析其 `PERSISTENCE.md` 声明的 knowledge/policy namespace。
 2. 读取 `../skills/knowledge-prune/SKILL.md`，默认执行 dry-run，生成 `delete | merge | rewrite | keep | needs-confirmation` 清单。
 3. 将报告写入 command 专属目录；无用户确认时不删除、重命名或改写任何 namespace。
 4. 用户确认后再次执行路径包含检查，逐项操作并复查 git、引用和报告结果。

package/template/commands/retro.md

@@ -25,7 +25,7 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
 
 ## 执行步骤
 
-1. 读取 `../skills/runtime-context/SKILL.md` 与 `../skills/speculo-retro/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级），采集对话、command 报告、change 状态以及 workflow 声明的 lessons/knowledge store。
+1. 读取 `../skills/runtime-context/SKILL.md` 与 `../skills/speculo-retro/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级），采集对话、command 报告、change 状态以及各 `PERSISTENCE.md` 声明的 lessons/knowledge store。
 2. 用该 skill 产出规范化复盘结论：去重、分级、根因化的 issue-ready 提案清单，附丢弃/合并说明与每条处置建议。
 3. 创建 command 专属目录 `speculo/.speculo/commands/retro/`，把复盘结论写入带 scope 的 Markdown 报告。
 4. **解析目标仓库**：默认框架反馈上游 `NAMEWTA/Speculo`；用户在请求中显式指定其他 `owner/repo` 时覆盖默认。无论如何，在调用 `gh` 前回显解析到的 `owner/repo`，让用户确认或改正。

package/template/skills/docs-sync/assets/report-template.md

@@ -30,7 +30,7 @@ generated_at: <ISO-8601>
 
 ## Workflow Sources
 
-[按 workflow 记录读取的 WORKFLOW、archive、声明 store 和受保护候选；空集合写 `[]`。]
+[按 workflow 记录读取的 WORKFLOW/PERSISTENCE、archive、声明 store 和受保护候选；空集合写 `[]`。]
 
 ## Synced Assets
 

package/template/skills/docs-sync/references/workflow-scope-contract.md

@@ -1,12 +1,12 @@
 # Workflow 范围契约
 
-docs-sync 必须遵循每个 workflow 的 `WORKFLOW.md`、持久化声明与确认规则。`docs-sync.json` 是 command 拥有的标准延迟 sidecar，不属于 workflow `_state` 固定骨架。
+docs-sync 必须遵循每个 workflow 的 `WORKFLOW.md` 与同级 `PERSISTENCE.md`。`docs-sync.json` 是 command 拥有的标准延迟 sidecar，不属于 workflow `_state` 固定骨架。
 
 ## 发现
 
 1. 从 `speculo/workflows/*/WORKFLOW.md` 发现已安装 workflow。
 2. 每个包必须有匹配的 `speculo/.speculo/<workflow>/` 状态根；包或状态根单边缺失时阻塞，不猜测归属。
-3. 读取 `<runtime-context>`、`<persistence>`、固定 archive 和所有 `consumers` 包含 `docs-sync` 的 store。
+3. 读取同级 `PERSISTENCE.md` 的 `<runtime-context>`、`<persistence>`、固定 archive 和所有 `consumers` 包含 `docs-sync` 的 store。
 4. 状态根存在但没有已安装 package 时只报告 orphan，不创建 sidecar。
 
 ## Sidecar v1

package/template/skills/knowledge-prune/SKILL.md

@@ -12,7 +12,7 @@ description: dry-run 审计 workflow 声明的知识与策略 namespace，返回
 ## 输入
 
 - `runtime-context` 返回的 workflow/state 根。
-- `WORKFLOW.md#persistence` 中 role 为 knowledge、policy 或 legacy-knowledge 的 namespace。
+- `PERSISTENCE.md#persistence` 中 role 为 knowledge、policy 或 legacy-knowledge 的 namespace。
 - 用户确认状态：`dry-run | confirmed`。
 
 ## 流程

package/template/skills/knowledge-prune/references/audit-rules.md

@@ -2,7 +2,7 @@
 
 ## 扫描范围
 
-1. 读取目标 workflow 的 `<persistence>`，选择 role 为 `knowledge | policy | legacy-knowledge` 且真实存在的 store。
+1. 读取目标 workflow `PERSISTENCE.md` 的 `<persistence>`，选择 role 为 `knowledge | policy | legacy-knowledge` 且真实存在的 store。
 2. `create="lazy"` 但不存在的 store 记为 `missing`，不为审计而创建；`existing-only` store 只读。
 3. 扫描代码、文档、active changes 和 archive 中对 ADR、CONTEXT、LESSONS、RULES 及具体文件名的引用。
 

package/template/skills/runtime-context/SKILL.md

@@ -7,18 +7,18 @@ description: 解析 Speculo 项目根、资产根和 workflow 状态根，向 co
 
 # Runtime Context
 
-从项目根注册表和 workflow XML 声明构造一次运行所需的全部路径。调用方持有持久化责任；本 skill 只解析和验证路径。
+从项目根注册表和 workflow `PERSISTENCE.md` 构造一次运行所需的全部路径。调用方持有持久化责任；本 skill 只解析和验证路径。
 
 ## 输入
 
 - 当前工作目录或用户指定的项目目录。
-- workflow id，以及对应 `WORKFLOW.md` 中的 `<runtime-context>` 和 `<persistence>`。
+- workflow id，以及对应 `PERSISTENCE.md` 中的 `<runtime-context>` 和 `<persistence>`。
 - 可选 change 名称和 command id。
 
 ## 流程
 
 1. 按 `references/path-resolution.md` 向上定位 `speculo/.speculo/workspace.json`；找不到唯一项目根时返回 blocked。
-2. 读取注册表与 workflow 根别名，解析 `workflow/state/commands/skills/vendor`。
+2. 读取注册表与 workflow 的 `PERSISTENCE.md`，解析 `workflow/state/commands/skills/vendor`。
    - 对每个解析后的 vendor root 执行存在性验证：目标目录必须存在，否则返回明确错误信息指明缺失的具体路径，禁止静默跳过。
    - 任一路径越界或目标缺失时返回 blocked。
 3. 读取 `speculo/config.json`（若存在）；不存在时以默认值静默降级（`language: "en"`、`persistence.root_override: null`、`defaults.confirm_before_external_write: true`、`defaults.report_language: "en"`）。

package/template/skills/runtime-context/references/path-resolution.md

@@ -14,7 +14,7 @@
 
 ## Workflow 绑定
 
-读取 workflow 的 `<runtime-context>`：
+读取 workflow 同级 `PERSISTENCE.md` 的 `<runtime-context>`：
 
 - `base` 必须引用 `workspace.json#roots` 中已有根。
 - `path` 不能是绝对路径，不能包含 `..` 或反斜杠。
@@ -38,4 +38,4 @@ change_root = changes_root/<change>
 - `<artifact root="change">` 只能落在当前 change。
 - `<artifact root="state">` 只能落在 `<persistence>` 声明的额外命名空间。
 - command 报告只能落在 `state/commands/<command>/`，skill 不自行选择路径。
-- raw vendor skill 未经 workflow runtime context 激活时，不承诺 Speculo 持久化边界。
+- raw vendor SKILL 只通过同 workflow 的一对一 atomic wrapper 激活；wrapper 先加载 `PERSISTENCE.md`，嵌套 skill 名称继续解析到 wrapper。

package/template/skills/speculo-retro/SKILL.md

@@ -10,7 +10,7 @@ description: 从 Speculo 使用证据中提取、去重、分级和根因化摩
 ## 输入
 
 - 当前对话与本次使用的 commands/workflows。
-- `commands/<command>/*.md` 报告、active change 状态、archive 和 workflow 声明的 lessons/knowledge store。
+- `commands/<command>/*.md` 报告、active change 状态、archive 和 `PERSISTENCE.md` 声明的 lessons/knowledge store。
 - 可选已有 issues，用于语义去重。
 
 ## 流程

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

@@ -0,0 +1,80 @@
+# Matt Pocock Persistence
+
+本文件是 `matt-pocock` 的唯一运行契约。`WORKFLOW.md` 与 `atomic-skills/*.md` 只能引用本文件，不得复制 runtime roots、store、change 启动或副作用规则。无论从 workflow 还是 atomic wrapper 进入，都先读取项目根 `speculo/.speculo/workspace.json`，再执行本文件。
+
+## 运行时根
+
+```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/` 是固定骨架；lazy store 只在产生对应内容并确认长期归属时创建。已有 `.config/` 只读，不接收新内容。
+
+## 启动协议
+
+```xml
+<sequence>
+  <phase id="resolve-runtime" order="1">
+    <skill root="skills" path="runtime-context/SKILL.md" activation="required" />
+    <completion>workspace、config、workflow/state/vendor roots 均已解析并通过边界与存在性检查；同一运行已解析时复用结果。</completion>
+  </phase>
+  <phase id="select-change" order="2">
+    <artifact root="state" path="status.json" />
+    <completion>已选择用户指定或唯一 active change；没有 active change 时原子创建 `changes/YYYY-MM-DD-&lt;kebab-topic&gt;/.status.json` 并更新索引；多个候选时先消歧。</completion>
+  </phase>
+</sequence>
+```
+
+创建 change 时初始化 schema version 1、workflow/name/timestamps、`change_status: active`、空的 `route_history`、`skill_history` 与 `external_refs`。已有 change 缺少这些数组时按空数组读取，在下一次真实更新时补齐，不要求迁移。
+
+## 状态字段
+
+```xml
+<state-schema>
+  <field name="current_route" type="string|null" />
+  <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>
+```
+
+- route 调用维护 `current_route` 与 `route_history`；direct atomic 调用保持二者不变。
+- 每次 atomic wrapper 调用向 `skill_history` 追加 skill id、`direct|route` 模式、进入/完成时间、结果和真实的项目相对产物路径。
+- 外部系统结果只写入 `external_refs`；状态不保存派生绝对路径。
+
+## 路径分配
+
+1. route 的 `<artifact>` 指针优先，wrapper 使用调用方已声明路径。
+2. direct 调用没有 route 产物声明时，运行时文件由目标 skill 在当前 change 内按需新建；只强制 `change_root` 边界，不强制 `atomic-skills/<id>` 子目录。
+3. 项目代码、测试和用户明确要求的项目文档属于项目产物，可写入经确认的项目相对路径；同时把验证或结果指针记录到当前 change。
+4. 长期知识、规则和集成配置先在 change 中形成，经确认后才写入已声明的 lazy store。raw skill 中的 `CONTEXT.md`、ADR、`docs/agents/`、`.out-of-scope/` 等逻辑位置分别映射到 `knowledge`、`integrations` 或 `policy`，不在项目根自行创建私有运行状态。
+5. 临时原型、数据库、脚本和报告必须删除或吸收；保留的结论写入当前 change。raw skill 指向系统临时目录、当前目录或 `.scratch/` 时，同样受本规则约束。
+
+raw skill 内部提及另一个 `/skill` 时，解析到 `atomic-skills/<skill-id>.md`；只有该 wrapper 可以直接引用对应 vendor `SKILL.md`。
+
+## 副作用边界
+
+- 发布 issue、评论、标签，写 secret，启动后台 agent，提交代码，继续 merge/rebase，合并或删除 worktree 前，展示动作与目标并取得明确确认。
+- 已确认动作的结果、URL、commit 或失败状态写入 `external_refs`；敏感值不得写入 change 或状态。
+- vendor 内容保持只读；所有路径改写和确认规则由本文件提供。
+

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

@@ -3,105 +3,27 @@ id: matt-pocock
 type: workflow
 workflow: matt-pocock
 name: Matt Pocock Workflow
-description: 以路由优先方式组合原生 Matt Pocock skills，并在 Speculo 私有状态根内持久化
+description: 以路由和原子入口组合 Matt Pocock skills，并共享同一持久化契约
 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>
-```
+先读取 [PERSISTENCE.md](./PERSISTENCE.md)。该文件是 runtime roots、store、change 启动和副作用边界的唯一来源；本入口只负责选择组合 route 或单个 atomic skill。
 
 ## 进入协议
 
 ```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（名称 = `YYYY-MM-DD-&lt;kebab-topic&gt;`，日期前缀自动生成，格式不匹配则阻塞）与 .status.json。</completion>
+  <phase id="load-persistence" order="1">
+    <instructions root="workflow" path="PERSISTENCE.md" activation="required" />
+    <completion>runtime context 与 current change 已按唯一持久化契约解析。</completion>
   </phase>
-  <phase id="init-config" order="2">
-    <skill root="skills" path="runtime-context/SKILL.md" activation="required" />
-    <artifact root="speculo" path="config.json" />
-    <when>speculo/config.json 存在时读取；不存在时以默认值静默降级。</when>
-    <completion>config 已解析并纳入 runtime context，后续所有 phase 可引用 config.language / config.defaults 等字段。</completion>
+  <phase id="route" order="2">
+    <instructions root="workflow" path="atomic-skills/ask-matt.md" activation="required" />
+    <completion>已根据用户意图选择一个组合 route 或 atomic skill；歧义时一次只澄清一个决策。</completion>
   </phase>
-  <phase id="init-vendor" order="3">
-    <skill root="skills" path="runtime-context/SKILL.md" activation="required" />
-    <when>workflow 声明了 vendor root；对每个解析后的 vendor root 执行存在性验证。</when>
-    <completion>所有 vendor root 均已通过存在性验证并纳入 skill 搜索范围；缺失 vendor 目录时返回明确错误。</completion>
-  </phase>
-  <phase id="route" order="4">
-    <skill root="vendor:matt-pocock" path="engineering/ask-matt/SKILL.md" activation="required" />
-    <completion>已根据用户意图选择一个 route；歧义时一次只澄清一个决策。</completion>
-  </phase>
-  <phase id="lazy-config" order="5">
+  <phase id="lazy-config" order="3">
     <instructions root="workflow" path="routes/setup.md" />
     <when>目标 route 依赖尚未配置的 tracker、triage 或 domain 文档。</when>
     <completion>只补齐目标 route 必需的私有 namespace。</completion>
@@ -109,48 +31,73 @@ keywords: [matt-pocock, engineering, productivity, grilling, tdd, review]
 </sequence>
 ```
 
-## 依赖
+## 路由
 
 ```xml
-<dependencies>
-  <dependency kind="hard" root="vendor:matt-pocock" path="README.md">
-    选择本 workflow 时必须安装完整 matt-pocock vendor 目录。
-  </dependency>
-</dependencies>
+<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
-<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>
+<atomic-skills source-root="vendor:matt-pocock" coverage="complete">
+  <atomic-skill id="ask-matt" order="1" root="workflow" path="atomic-skills/ask-matt.md"><when>询问应使用哪种 skill 或 route。</when></atomic-skill>
+  <atomic-skill id="claude-handoff" order="2" root="workflow" path="atomic-skills/claude-handoff.md"><when>明确要求把会话交给 Claude 后台 agent。</when></atomic-skill>
+  <atomic-skill id="code-review" order="3" root="workflow" path="atomic-skills/code-review.md"><when>从固定点进行标准与规范双轴审查。</when></atomic-skill>
+  <atomic-skill id="codebase-design" order="4" root="workflow" path="atomic-skills/codebase-design.md"><when>设计深层模块、接口或 seam。</when></atomic-skill>
+  <atomic-skill id="diagnosing-bugs" order="5" root="workflow" path="atomic-skills/diagnosing-bugs.md"><when>以反馈循环诊断疑难 bug 或性能回退。</when></atomic-skill>
+  <atomic-skill id="domain-modeling" order="6" root="workflow" path="atomic-skills/domain-modeling.md"><when>精炼领域词汇、上下文或 ADR。</when></atomic-skill>
+  <atomic-skill id="grill-me" order="7" root="workflow" path="atomic-skills/grill-me.md"><when>用户明确要求对计划或设计进行访谈打磨。</when></atomic-skill>
+  <atomic-skill id="grill-with-docs" order="8" root="workflow" path="atomic-skills/grill-with-docs.md"><when>在已有代码仓中访谈并同步领域决策。</when></atomic-skill>
+  <atomic-skill id="grilling" order="9" root="workflow" path="atomic-skills/grilling.md"><when>其他能力需要复用逐问访谈循环。</when></atomic-skill>
+  <atomic-skill id="handoff" order="10" root="workflow" path="atomic-skills/handoff.md"><when>用户明确要求为另一个会话保存交接上下文。</when></atomic-skill>
+  <atomic-skill id="implement" order="11" root="workflow" path="atomic-skills/implement.md"><when>用户明确要求实现既有 spec 或 tickets。</when></atomic-skill>
+  <atomic-skill id="improve-codebase-architecture" order="12" root="workflow" path="atomic-skills/improve-codebase-architecture.md"><when>用户明确要求扫描架构深化机会。</when></atomic-skill>
+  <atomic-skill id="loop-me" order="13" root="workflow" path="atomic-skills/loop-me.md"><when>用户明确要求实验性的工作流规格访谈。</when></atomic-skill>
+  <atomic-skill id="prototype" order="14" root="workflow" path="atomic-skills/prototype.md"><when>用一次性逻辑或 UI 原型回答设计问题。</when></atomic-skill>
+  <atomic-skill id="research" order="15" root="workflow" path="atomic-skills/research.md"><when>需要以一手来源调查问题。</when></atomic-skill>
+  <atomic-skill id="resolving-merge-conflicts" order="16" root="workflow" path="atomic-skills/resolving-merge-conflicts.md"><when>解决进行中的 merge 或 rebase 冲突。</when></atomic-skill>
+  <atomic-skill id="setup-matt-pocock-skills" order="17" root="workflow" path="atomic-skills/setup-matt-pocock-skills.md"><when>用户明确要求配置 tracker、标签或领域布局。</when></atomic-skill>
+  <atomic-skill id="tdd" order="18" root="workflow" path="atomic-skills/tdd.md"><when>以红绿重构循环构建一个垂直切片。</when></atomic-skill>
+  <atomic-skill id="teach" order="19" root="workflow" path="atomic-skills/teach.md"><when>用户明确要求跨会话学习主题。</when></atomic-skill>
+  <atomic-skill id="to-spec" order="20" root="workflow" path="atomic-skills/to-spec.md"><when>用户明确要求把既有讨论综合为 spec。</when></atomic-skill>
+  <atomic-skill id="to-tickets" order="21" root="workflow" path="atomic-skills/to-tickets.md"><when>用户明确要求把计划或 spec 拆为 tickets。</when></atomic-skill>
+  <atomic-skill id="triage" order="22" root="workflow" path="atomic-skills/triage.md"><when>用户明确要求分类 issue 或外部 PR。</when></atomic-skill>
+  <atomic-skill id="wayfinder" order="23" root="workflow" path="atomic-skills/wayfinder.md"><when>用户明确要求为大型模糊目标建立调查地图。</when></atomic-skill>
+  <atomic-skill id="wizard" order="24" root="workflow" path="atomic-skills/wizard.md"><when>用户明确要求实验性生成交互式 bash 向导。</when></atomic-skill>
+  <atomic-skill id="writing-beats" order="25" root="workflow" path="atomic-skills/writing-beats.md"><when>用户明确要求用节拍路径组装文章。</when></atomic-skill>
+  <atomic-skill id="writing-fragments" order="26" root="workflow" path="atomic-skills/writing-fragments.md"><when>用户明确要求访谈并积累写作碎片。</when></atomic-skill>
+  <atomic-skill id="writing-great-skills" order="27" root="workflow" path="atomic-skills/writing-great-skills.md"><when>用户明确要求设计或审查 skill。</when></atomic-skill>
+  <atomic-skill id="writing-shape" order="28" root="workflow" path="atomic-skills/writing-shape.md"><when>用户明确要求逐段塑造文章结构。</when></atomic-skill>
+</atomic-skills>
 ```
 
-## 状态转移
+## 依赖与状态转移
+
+```xml
+<dependencies>
+  <dependency kind="hard" root="vendor:matt-pocock" path="README.md">选择本 workflow 时必须安装完整 matt-pocock vendor 目录。</dependency>
+</dependencies>
+```
 
 ```xml
 <transitions>
-  <transition from="route" to="phase">
-    <when>route 已选定且所需 namespace 可用。</when>
-  </transition>
-  <transition from="phase" to="route">
-    <when>当前能力完成并需要进入另一条路线；同一目标继续复用当前 change。</when>
-  </transition>
+  <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/atomic-skills/ask-matt.md

@@ -0,0 +1,21 @@
+---
+id: ask-matt
+type: atomic-skill
+workflow: matt-pocock
+name: Ask Matt
+description: 为当前情况选择合适的 Matt Pocock skill 或 route。
+stability: stable
+invocation: user-only
+---
+
+# Ask Matt
+
+直接调用前必须读取 [PERSISTENCE.md](../PERSISTENCE.md)。
+
+```xml
+<sequence>
+  <phase id="load-persistence" order="1"><instructions root="workflow" path="PERSISTENCE.md" activation="required" /><completion>current change 与写入边界已解析。</completion></phase>
+  <phase id="invoke" order="2"><skill root="vendor:matt-pocock" path="engineering/ask-matt/SKILL.md" activation="adapted" /><completion>目标 skill 已执行并记录 skill history；后续 skill 名称继续解析到本目录 wrapper。</completion></phase>
+</sequence>
+```
+

package/template/workflows/matt-pocock/atomic-skills/claude-handoff.md

@@ -0,0 +1,21 @@
+---
+id: claude-handoff
+type: atomic-skill
+workflow: matt-pocock
+name: Claude Handoff
+description: 将当前对话交给新的 Claude 后台 agent。
+stability: experimental
+invocation: user-only
+---
+
+# Claude Handoff
+
+本能力不稳定，仅在用户明确要求时启用。直接调用前必须读取 [PERSISTENCE.md](../PERSISTENCE.md)。
+
+```xml
+<sequence>
+  <phase id="load-persistence" order="1"><instructions root="workflow" path="PERSISTENCE.md" activation="required" /><completion>current change 与后台 agent 确认边界已解析。</completion></phase>
+  <phase id="invoke" order="2"><skill root="vendor:matt-pocock" path="in-progress/claude-handoff/SKILL.md" activation="adapted" /><completion>目标 skill 已执行；启动结果已脱敏并记录到 skill history/external refs。</completion></phase>
+</sequence>
+```
+

package/template/workflows/matt-pocock/atomic-skills/code-review.md

@@ -0,0 +1,21 @@
+---
+id: code-review
+type: atomic-skill
+workflow: matt-pocock
+name: Code Review
+description: 从固定点执行标准与规范双轴代码审查。
+stability: stable
+invocation: model-allowed
+---
+
+# Code Review
+
+直接调用前必须读取 [PERSISTENCE.md](../PERSISTENCE.md)。
+
+```xml
+<sequence>
+  <phase id="load-persistence" order="1"><instructions root="workflow" path="PERSISTENCE.md" activation="required" /><completion>current change 与写入边界已解析。</completion></phase>
+  <phase id="invoke" order="2"><skill root="vendor:matt-pocock" path="engineering/code-review/SKILL.md" activation="adapted" /><completion>双轴结果已返回，实际报告路径已记录到 skill history。</completion></phase>
+</sequence>
+```
+

package/template/workflows/matt-pocock/atomic-skills/codebase-design.md

@@ -0,0 +1,21 @@
+---
+id: codebase-design
+type: atomic-skill
+workflow: matt-pocock
+name: Codebase Design
+description: 使用深层模块词汇设计接口与 seam。
+stability: stable
+invocation: model-allowed
+---
+
+# Codebase Design
+
+直接调用前必须读取 [PERSISTENCE.md](../PERSISTENCE.md)。
+
+```xml
+<sequence>
+  <phase id="load-persistence" order="1"><instructions root="workflow" path="PERSISTENCE.md" activation="required" /><completion>current change 与知识边界已解析。</completion></phase>
+  <phase id="invoke" order="2"><skill root="vendor:matt-pocock" path="engineering/codebase-design/SKILL.md" activation="adapted" /><completion>设计结论已返回，实际产物路径已记录到 skill history。</completion></phase>
+</sequence>
+```
+

package/template/workflows/matt-pocock/atomic-skills/diagnosing-bugs.md

@@ -0,0 +1,21 @@
+---
+id: diagnosing-bugs
+type: atomic-skill
+workflow: matt-pocock
+name: Diagnosing Bugs
+description: 用紧凑反馈循环诊断疑难 bug 或性能回退。
+stability: stable
+invocation: model-allowed
+---
+
+# Diagnosing Bugs
+
+直接调用前必须读取 [PERSISTENCE.md](../PERSISTENCE.md)。
+
+```xml
+<sequence>
+  <phase id="load-persistence" order="1"><instructions root="workflow" path="PERSISTENCE.md" activation="required" /><completion>current change 与诊断产物边界已解析。</completion></phase>
+  <phase id="invoke" order="2"><skill root="vendor:matt-pocock" path="engineering/diagnosing-bugs/SKILL.md" activation="adapted" /><completion>诊断结果与回归证据已返回，路径已记录到 skill history。</completion></phase>
+</sequence>
+```
+