@rosenfan/matrix 0.1.5 → 0.1.7

package/assets/skills-zh-CN/matrix/SKILL.md

@@ -1,83 +1,84 @@
----
-name: matrix
-description: 启动、恢复并治理持久化的 Matrix 开发工作流。
----
-
-# Matrix
-
-以当前仓库的 `.matrix/` 为唯一状态来源；不得从聊天记录推断阶段。
-
-读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 的 `artifact_language`。规范 Markdown 标题 token 必须保持不变；面向用户的产物正文、说明和 handoff 在 `zh-CN` 时写中文，在 `en` 时写英文。
-
-所有 workflow 命令都先执行当前项目 Matrix Skill 自带的 Runtime，使项目兼容性权威优先于不同版本的全局启动器：
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
-```
-
-全局 `matrix` 命令只负责 init、update 和 bootstrap。受信任的 0.1.4 启动器只会自动委派给版本与 hash 都精确匹配的 0.1.4 项目 Runtime。项目 Runtime 属于不同版本或无法识别版本时仍是项目权威，但必须执行启动器返回的精确直连命令；旧版启动器不具备这项跨版本检查，不能作为项目 workflow 入口。
-
-有活动变更时，报告其 phase、冻结的 `orchestration` 以及 Arch 安装完整性，再按 Runtime 结果进入 `next_skill`。没有活动变更时，为开发请求创建简短 kebab-case ID：
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs init <change-id> --workflow <full|hotfix|tweak> --orchestration <prim|arch> --title "<title>"
-```
-
-显式模式优先，否则使用项目 `default_orchestration`。解析后的模式在整个 change 生命周期中不可切换。
-
-## 编排模式
-
-- **Prim**：各阶段使用 Matrix 自身能力，不依赖 Matt Skills。
-- **Arch**：仅在任务事实满足触发条件时，调用活动 Change 冻结的十项自动能力。Matrix 0.1.4 审查 Matt Skills v1.2.3 官方 25 项角色，只把其中 23 项兼容 Skill 安装在项目本地；排除 `implement` 与 raw `resolving-merge-conflicts`。
-
-两种编排模式使用已选定的 workflow profile：`full` 走 `open → design → build → verify → archive`；`hotfix` 与 `tweak` 共用内部 `lightweight` profile，走 `open → build → verify → archive`，仅证据策略不同。Arch 能力不得写 Matrix 状态、推进阶段、提交、归档或创建竞争工作流。
-
-正确安装的 Arch 能力执行失败时，最多允许一次同能力的 Matrix fallback，并记录失败与证据。缺失、修改或不完整的 Arch 安装必须通过 `matrix init --with-mattpocock` 修复，不得切换活动 change 到 Prim。
-
-## 恢复
-
-只能通过 Runtime 恢复，不得手工修改状态：
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs return build --reason verification-failed
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason acceptance-or-design-gap
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs abort --reason <requirement-cancelled|superseded|no-longer-valuable|blocked|other>
-```
-
-Return 会把当前 `verification.md` 轮换至按 revision 编号的证据历史。Archive 等待确认期间若验收或设计改变，只能使用 `archive -> design` 的 `acceptance-or-design-gap` Return。Abort 将终态变更移入 `.matrix/archive/`，但不会撤销工作区代码。
-
-任何 mutation 返回 `WORKFLOW_RECOVERY_REQUIRED` 时，停止正常阶段操作并先执行只读诊断：
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor
-```
-
-不得推断恢复目标或策略，只能执行 doctor 返回的精确命令：
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor --repair --transaction <id> --strategy <continue|rollback>
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor --repair --lock <id>
-```
-
-## 精确 Contract
-
-full 的 `design -> build` 会批准 proposal/design/plan；lightweight 的 `open -> build --confirmed` 只批准紧凑 proposal，并拒绝初始化后、批准前发生的项目实现改动。Contract 后续漂移都会阻断推进。
-
-## 可选 Claude 交接
-
-`$matrix-claude` 只在已批准的 Build 中使用，导出同一 Contract 快照给 Claude Code。它不拥有阶段推进或验收；直接由 Codex 实现仍使用原有 Matrix 主流程。
-只有用户明确选择“Codex 设计、Claude Code 实现”时才使用，不得自动插入标准流程。
-
-## 显式 Matt handoff
-
-Matrix 不嵌套 user-invoked Skill。适用时只解释原因，并让用户显式调用：一次性配置使用 `setup-matt-pocock-skills`，工作流外架构扫描使用 `improve-codebase-architecture`，独立大型候选生成使用 `wayfinder`，上下文边界使用 `handoff`，他人掌握阻塞事实时使用 `to-questionnaire`。`ask-matt`、`grill-with-docs`、`triage`、`to-spec`、`to-tickets`、`grill-me`、`teach`、`wait-what` 保持 standalone。Matrix 不安装也不管理 `implement` 或 raw `resolving-merge-conflicts`；已有副本保留为未管理额外项，活动 Change 内不得建议使用。
-
-## 规则
-
-- 阶段只能经 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition` 正向推进。
-- 只能经上述明确的 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return` 反向推进。
-- 成功 Archive 必须使用两步乐观提交：先运行 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --dry-run`，再将其精确 hash 传给 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --expect-preflight <sha256>`；不得绕过预演。
-- `node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor` 始终只读；transaction 与陈旧锁 repair 必须显式绑定 doctor 报告的 identity，不得手工编辑或删除 `.matrix/transactions/`、`.matrix/workflow.lock`。
-- 重大架构/范围决定和 archive/commit 前应暂停等待用户确认。
-- shortcut 范围扩大时执行 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap`；Runtime 将其升级为 full。
+---
+name: matrix
+description: 启动、恢复并治理持久化的 Matrix 开发工作流。
+---
+
+# Matrix
+
+以当前仓库的 `.matrix/` 为唯一状态来源；不得从聊天记录推断阶段。
+
+读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 的 `artifact_language`。规范 Markdown 标题 token 必须保持不变；面向用户的产物正文、说明和 handoff 在 `zh-CN` 时写中文，在 `en` 时写英文。
+
+所有 workflow 命令都先执行当前项目 Matrix Skill 自带的 Runtime，使项目兼容性权威优先于不同版本的全局启动器：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
+```
+
+全局 `matrix` 命令只负责 init、update 和 bootstrap。受信任的 0.1.4 启动器只会自动委派给版本与 hash 都精确匹配的 0.1.4 项目 Runtime。项目 Runtime 属于不同版本或无法识别版本时仍是项目权威，但必须执行启动器返回的精确直连命令；旧版启动器不具备这项跨版本检查，不能作为项目 workflow 入口。
+
+有活动变更时，报告其 phase、冻结的 `orchestration` 以及 Arch 安装完整性，再按 Runtime 结果进入 `next_skill`。没有活动变更时，为开发请求创建简短 kebab-case ID：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs init <change-id> --workflow <full|hotfix|tweak> --orchestration <prim|arch> --title "<title>"
+```
+
+显式模式优先，否则使用项目 `default_orchestration`。解析后的模式在整个 change 生命周期中不可切换。
+
+## 编排模式
+
+- **Prim**：各阶段使用 Matrix 自身能力，不依赖 Matt Skills。
+- **Arch**：仅在任务事实满足触发条件时，调用活动 Change 冻结的十项自动能力。Matrix 0.1.7 审查 Matt Skills v1.3.1 官方 27 项角色，只把其中 25 项兼容 Skill 安装在项目本地；排除 `implement` 与 `implement-spec`。
+
+两种编排模式使用已选定的 workflow profile：`full` 走 `open → design → build → verify → archive`；`hotfix` 与 `tweak` 共用内部 `lightweight` profile，走 `open → build → verify → archive`，仅证据策略不同。Arch 能力不得写 Matrix 状态、推进阶段、提交、归档或创建竞争工作流。
+
+正确安装的 Arch 能力执行失败时，最多允许一次同能力的 Matrix fallback，并记录失败与证据。缺失、修改或不完整的 Arch 安装必须通过 `matrix init --with-mattpocock` 修复，不得切换活动 change 到 Prim。
+
+## 恢复
+
+只能通过 Runtime 恢复，不得手工修改状态：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return build --reason verification-failed
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason acceptance-or-design-gap
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs abort --reason <requirement-cancelled|superseded|no-longer-valuable|blocked|other>
+```
+
+Return 会把当前 `verification.md` 轮换至按 revision 编号的证据历史。Archive 等待确认期间若验收或设计改变，只能使用 `archive -> design` 的 `acceptance-or-design-gap` Return。Abort 将终态变更移入 `.matrix/archive/`，但不会撤销工作区代码。
+
+任何 mutation 返回 `WORKFLOW_RECOVERY_REQUIRED` 时，停止正常阶段操作并先执行只读诊断：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor
+```
+
+不得推断恢复目标或策略，只能执行 doctor 返回的精确命令：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor --repair --transaction <id> --strategy <continue|rollback>
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor --repair --lock <id>
+```
+
+## 精确 Contract
+
+full 的 `design -> build` 会批准 proposal/design/plan；lightweight 的 `open -> build --confirmed` 只批准紧凑 proposal，并拒绝初始化后、批准前发生的项目实现改动。Contract 后续漂移都会阻断推进。
+
+## 可选 agent 交接（Implementation Handoff）
+
+`$matrix-handoff` 只在已批准的 Build 中使用，通过 `export --agent <agent-id>` 将 Contract 快照导出为用户选择的实现 agent 的有界任务包（例如 Codex 设计、Claude Code 实现，或 zcode 设计、opencode 实现）。它不拥有阶段推进或验收；由当前 agent 继续实现仍使用原有 Matrix 主流程。
+只有用户明确选择切换实现 agent 时才使用，不得自动插入标准流程。
+
+## 显式 Matt handoff
+
+Matrix 不嵌套 user-invoked Skill。适用时只解释原因，并让用户显式调用：一次性配置使用 `setup-matt-pocock-skills`，工作流外架构扫描使用 `improve-codebase-architecture`，独立大型候选生成使用 `wayfinder`，上下文边界使用 `handoff`，会话复盘改进 agent 环境使用 `retro`，他人掌握阻塞事实时使用 `to-questionnaire`。`ask-matt`、`grill-with-docs`、`triage`、`to-spec`、`to-tickets`、`grill-me`、`teach`、`wait-what`、`pr` 保持 standalone。Matrix 不安装也不管理 `implement` 与 `implement-spec`；已有副本（含遗留的 `resolving-merge-conflicts`）保留为未管理额外项，活动 Change 内不得建议使用。
+
+## 规则
+
+- 阶段只能经 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition` 正向推进。
+- 只能经上述明确的 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return` 反向推进。
+- 成功 Archive 必须使用两步乐观提交：先运行 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --dry-run`，再将其精确 hash 传给 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --expect-preflight <sha256>`；不得绕过预演。
+- `node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor` 始终只读；transaction 与陈旧锁 repair 必须显式绑定 doctor 报告的 identity，不得手工编辑或删除 `.matrix/transactions/`、`.matrix/workflow.lock`。
+- 重大架构/范围决定和 archive/commit 前应暂停等待用户确认。
+- 进入 Build 前（full 在 design guard 之后；lightweight 并入 `transition build --confirmed` 的暂停）必须呈现执行主体选择——当前 agent/原模型继续、用户客户端切换模型、或经 `$matrix-handoff` 切换实现 agent——并将决策随 Contract 记录。
+- shortcut 范围扩大时执行 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap`；Runtime 将其升级为 full。

package/assets/skills-zh-CN/matrix-archive/SKILL.md

@@ -34,3 +34,5 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason
 ```
 
 提交成功后，变更位于 `.matrix/archive/`，工作流完成。
+
+可选：当本次会话产生了值得保留的发现（反复出现的摩擦、缺失的护栏、不清晰的指针等），可建议用户显式运行 `retro`（user-invoked Matt handoff）把它们转化为 agent 环境改进。仅建议，绝不在工作流内代为调用。

package/assets/skills-zh-CN/matrix-build/SKILL.md

@@ -1,41 +1,41 @@
----
-name: matrix-build
-description: 用测试优先的纵向切片实现冻结的 Matrix 计划。仅在活动 Matrix 阶段为 build 时使用。
----
-
-# Matrix Build
-
-读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 与已批准 Contract。full/legacy-full 读取 proposal/design/plan；lightweight 只读取紧凑 proposal，不补写 Design 产物。
-
-Build 证据与面向用户的说明使用 `artifact_language`；Runtime 所需英文标题 token 保持不变。
-
-## 编排
-
-- **Prim**：使用 Matrix 自身实现与测试能力。
-- **Arch**：可测试行为变化时调用 `tdd`；真实失败且根因未知时调用 `diagnosing-bugs`；批准 Contract 修改 agent-facing 指令时调用 `writing-for-agents`；只有 Contract 需要人工执行 shell 步骤时，才用 `wizard` 生成并静态验证脚本，绝不端到端执行或收集秘密。
-
-进行中的 merge/rebase 冲突由 Matrix 自身治理，不调用会 stage、continue 或 commit 的 raw `resolving-merge-conflicts`。活动 Change 内不得调用 `implement`。
-
-调用前说明能力与原因。companion 不得 commit、review、transition、archive 或扩大范围。正确安装的能力失败时最多执行一次同能力 Matrix fallback，并记录调用、失败、fallback 与证据；安装完整性问题必须停止并修复。
-
-## 范围纪律
-
-若实现暴露范围或设计变化，停止并执行：
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap
-```
-
-回到 Design 会清除既有 Contract 批准并轮换当前验证证据；重新进入 Build 必须生成新的批准与新证据。
-
-## 流程
-
-1. 对可测试的行为变化使用 `tdd` 纵向切片；纯文档或不可观察的机械变更使用相称的静态检查。
-2. 在 `## Build evidence` 记录共同事实；hotfix 另写 `## Reproduction evidence`、`## Root cause`，tweak 另写 `## Scope evidence`。
-3. 运行 Build guard；它同时确认批准的 Contract 仍精确匹配。
-4. 通过后推进至 Verify，并进入 `$matrix-verify`。
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
-```
+---
+name: matrix-build
+description: 用测试优先的纵向切片实现冻结的 Matrix 计划。仅在活动 Matrix 阶段为 build 时使用。
+---
+
+# Matrix Build
+
+读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 与已批准 Contract。full/legacy-full 读取 proposal/design/plan；lightweight 只读取紧凑 proposal，不补写 Design 产物。
+
+Build 证据与面向用户的说明使用 `artifact_language`；Runtime 所需英文标题 token 保持不变。
+
+## 编排
+
+- **Prim**：使用 Matrix 自身实现与测试能力。
+- **Arch**：可测试行为变化时调用 `tdd`；真实失败且根因未知时调用 `diagnosing-bugs`；批准 Contract 修改 agent-facing 指令时调用 `writing-for-agents`；只有 Contract 需要人工执行 shell 步骤时，才用 `wizard` 生成并静态验证脚本，绝不端到端执行或收集秘密。
+
+进行中的 merge/rebase 冲突由 Matrix 自身治理，不得把生命周期控制交给遗留的 `resolving-merge-conflicts` 副本或任何会自行 stage、continue、commit 的 skill。活动 Change 内不得调用 `implement` 与 `implement-spec`。
+
+调用前说明能力与原因。companion 不得 commit、review、transition、archive 或扩大范围。正确安装的能力失败时最多执行一次同能力 Matrix fallback，并记录调用、失败、fallback 与证据；安装完整性问题必须停止并修复。
+
+## 范围纪律
+
+若实现暴露范围或设计变化，停止并执行：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap
+```
+
+回到 Design 会清除既有 Contract 批准并轮换当前验证证据；重新进入 Build 必须生成新的批准与新证据。
+
+## 流程
+
+1. 对可测试的行为变化使用 `tdd` 纵向切片；纯文档或不可观察的机械变更使用相称的静态检查。
+2. 在 `## Build evidence` 记录共同事实；hotfix 另写 `## Reproduction evidence`、`## Root cause`，tweak 另写 `## Scope evidence`。
+3. 运行 Build guard；它同时确认批准的 Contract 仍精确匹配。
+4. 通过后推进至 Verify，并进入 `$matrix-verify`。
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
+```

package/assets/skills-zh-CN/matrix-design/SKILL.md

@@ -1,24 +1,41 @@
----
-name: matrix-design
-description: 在实现前设计并冻结活动 Matrix 变更。
----
-
-# Matrix Design
-
-Design 只用于 full 和可恢复的旧 shortcut change。新的 lightweight hotfix/tweak 从 Open 直接进入 Build，不得为满足 full guard 补写 Design 产物。
-
-design 和 plan 正文使用 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 的 `artifact_language`；Runtime 所需英文标题 token 保持不变。
-
-读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect`、proposal 与冻结 `orchestration`，写入 `design.md`（`## Decisions`、`## Boundaries`、`## Test seams`、`## Risks`）与 `plan.md`（`## Steps`、`## Validation`、`## Stop conditions`）。
-
-- **Prim**：使用 Matrix 自身能力调查并设计。
-- **Arch**：仅按事实触发 `domain-modeling`、`research`、`prototype`、`codebase-design`；当 Contract 修改 Skill、`AGENTS.md`、`CLAUDE.md` 或 agent 指针可达文档时触发 `writing-for-agents`。不得机械执行固定序列；每次调用前说明能力与原因。
-
-长期有效的领域、ADR 或研究产物遵循仓库约定，关键结论必须同步进入 Matrix design/plan。prototype 默认写入系统临时目录。companion 不得拥有 Matrix 状态或创建竞争计划。重大范围或架构决策须先由用户确认。
-
-`wayfinder` 与 `improve-codebase-architecture` 只能作为活动 Design 外的显式 handoff；说明原因后由用户调用，选中的结果可另行进入受治理 Change。
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard design
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build
-```
+---
+name: matrix-design
+description: 在实现前设计并冻结活动 Matrix 变更。
+---
+
+# Matrix Design
+
+Design 只用于 full 和可恢复的旧 shortcut change。新的 lightweight hotfix/tweak 从 Open 直接进入 Build，不得为满足 full guard 补写 Design 产物。
+
+design 和 plan 正文使用 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 的 `artifact_language`；Runtime 所需英文标题 token 保持不变。
+
+读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect`、proposal 与冻结 `orchestration`，写入 `design.md`（`## Decisions`、`## Boundaries`、`## Test seams`、`## Risks`）与 `plan.md`（`## Steps`、`## Validation`、`## Stop conditions`）。
+
+- **Prim**：使用 Matrix 自身能力调查并设计。
+- **Arch**：仅按事实触发 `domain-modeling`、`research`、`prototype`、`codebase-design`；当 Contract 修改 Skill、`AGENTS.md`、`CLAUDE.md` 或 agent 指针可达文档时触发 `writing-for-agents`。不得机械执行固定序列；每次调用前说明能力与原因。
+
+长期有效的领域、ADR 或研究产物遵循仓库约定，关键结论必须同步进入 Matrix design/plan。prototype 默认写入系统临时目录。companion 不得拥有 Matrix 状态或创建竞争计划。重大范围或架构决策须先由用户确认。
+
+`wayfinder` 与 `improve-codebase-architecture` 只能作为活动 Design 外的显式 handoff；说明原因后由用户调用，选中的结果可另行进入受治理 Change。
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard design
+```
+
+## 执行主体确认点（Build 前）
+
+`guard design` 通过后、`transition build` 之前，必须暂停并向用户确认执行主体，未确认不得推进：
+
+- **选项 A：当前 agent / 原模型继续（默认）**——直接推进：
+  ```powershell
+  node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build
+  ```
+  随后进入 `$matrix-build` 在本会话内实现。
+- **选项 B：切换模型、保留本 agent**——用户在自己的客户端完成模型切换（例如设计用强模型、实现用高性价比模型），回到会话确认后按选项 A 推进。Matrix 无法感知客户端模型，只提供强制暂停点。
+- **选项 C：切换执行 agent**——先推进进 Build 批准冻结 Contract，再用 `$matrix-handoff` 为目标 agent 导出有界任务包（例如 Codex 设计、Claude Code 实现，或 zcode 设计、opencode 实现）。实现 agent 完成并补齐 `## Build evidence` 后：
+  ```powershell
+  node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+  node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
+  ```
+
+所选选项必须写入 `design.md` 的 `## Decisions`，随 Contract 冻结。

package/assets/skills-zh-CN/matrix-handoff/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: matrix-handoff
+description: 将已批准的 Matrix Contract 导出为受边界约束的通用 agent 任务包（Claude Code、opencode 或其他 agent），不改变 Matrix 工作流状态。
+---
+
+# Matrix Handoff（Implementation Handoff）
+
+这是可选旁路，不是 Matrix phase。它不得执行 `transition`、`archive`，也不得写入 `matrix.yaml` 或 `events.jsonl`。它只支持匹配的 full 或 legacy-full 三产物 Contract；新的 lightweight hotfix/tweak 不支持导出。
+
+人类可读 handoff 内容使用 inspect 的 `artifact_language`；稳定的机器可读标题和 metadata key 保持不变。
+
+## 何时使用
+
+满足以下条件时使用 `$matrix-handoff`：
+
+- 变更已进入 Build，且 `design -> build` 已批准精确 Contract；
+- 你希望由另一个 agent 实现冻结的设计——例如 Codex 设计、Claude Code 实现，或 zcode 设计、opencode 实现；
+- 你需要一份带全部实现细节的有界任务包。
+
+## 前置条件
+
+导出器写任何内容前先做只读检查：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+```
+
+若结果为 `CONTRACT_CHANGED`、`CONTRACT_UNAPPROVED` 或 `CONTRACT_READ_FAILED`，回到 `$matrix-design`，修订后重新进入 Build 取得新批准。导出只读取批准快照中的 `proposal.md`、`design.md` 与 `plan.md`。
+
+## 导出
+
+实现 agent 由用户显式选择，通过 `--agent <agent-id>`（kebab-case）传入；可用 `--from <agent-id>` 标注设计方 agent。
+
+```powershell
+# 通用 agent 交接：写入 artifacts/handoff-task-<ID>.md
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --agent opencode
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --agent claude-code --from codex
+
+# 兼容形态（Claude Code）：写入 artifacts/claude-task.md
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target generic
+
+# FnSec：仅在 active.md 含有 NO_ACTIVE_OBJECTIVE 时更新看板
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target fnsec --apply-fnsec-board
+```
+
+`--agent` 与 `--target` 互斥。新交接推荐 `--agent`；`--target generic` 仅为兼容保留。
+
+## 任务包内容
+
+导出包（`artifacts/handoff-task-<task-id>.md`）的元数据记录 `Implementation actor`（`--agent` 值）与 `Decision owner`（`--from` 值，缺省为 "Matrix change owner"），并包含批准的 Contract hash 与 revision，以及同一冻结快照的 proposal、design、plan。Objective、Allowed/Prohibited work 与 Stop conditions 原样携带——它们与具体 agent 无关。
+
+## 实现 agent 完成后
+
+继续 `$matrix-verify` 前先核对以下证据：
+
+- [ ] `artifacts/verification.md` 存在且含 `## Build evidence`
+- [ ] Build evidence 含具体命令与结果
+- [ ] plan 的 Validation 命令全部执行
+- [ ] `NEEDS_DECISION` 项已解决或已记录
+
+证据缺失时，让实现 agent 补齐后再继续。
+
+## 恢复 Matrix 工作流
+
+实现 agent 完成且证据齐备后：
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
+```
+
+guard 失败则退回实现 agent 补齐缺失证据；通过后进入 `$matrix-verify` 继续验证流程。
+
+## 重要约束
+
+- 本旁路不改变 Matrix 阶段、workflow 或 guard 结果
+- Matrix 状态停留在 `build`；导出本身不推进阶段
+- 实现 agent 产出的证据必须满足 build guard 条件
+- 成功 transition 到 verify 后，走正常验证流程

package/assets/skills-zh-CN/matrix-open/SKILL.md

@@ -1,30 +1,40 @@
----
-name: matrix-open
-description: 将开发请求澄清为有证据的 Matrix 提案。
----
-
-# Matrix Open
-
-读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 返回的 `profile` 与 `evidence_policy`。
-
-proposal 正文使用其中的 `artifact_language`；Runtime 所需的英文标题 token 必须原样保留，仅标题下内容本地化。
-
-- full proposal 包含 `## Goal`、`## Scope`、`## Non-goals`、`## Acceptance`、`## Risks`，随后进入 Design。
-- lightweight proposal 在修改项目实现前完整定义 `## Goal`、`## Scope`、`## Non-goals`、`## Approach`、`## Acceptance`、`## Validation`、`## Risks`、`## Upgrade conditions`。
-- hotfix 额外包含 `## Expected behavior`、`## Actual behavior`、`## Reproduction`。
-- tweak 额外包含 `## Current behavior`、`## Preserved behavior`、`## Diff boundary`。
-
-- **Prim**：使用 Matrix 自身能力澄清并编写提案。
-- **Arch**：仅在存在重大歧义或用户要求压力测试时调用 `grilling`；仅在领域词汇、不变量或架构决定不清晰时调用 `domain-modeling`。调用前说明能力与原因。
-
-若进展被另一人掌握的事实或决定阻塞，说明 `to-questionnaire` 适用的原因并让用户显式调用；Matrix 不得自行嵌套该 wrapper。
-
-companion 输出只能作为当前 proposal 的证据，不得创建第二套工作流、提案、确认状态或阶段转换。正确安装的能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须修复。
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard open
-# full
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition design
-# hotfix/tweak，仅在用户明确确认后
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --confirmed
-```
+---
+name: matrix-open
+description: 将开发请求澄清为有证据的 Matrix 提案。
+---
+
+# Matrix Open
+
+读取 `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` 返回的 `profile` 与 `evidence_policy`。
+
+proposal 正文使用其中的 `artifact_language`；Runtime 所需的英文标题 token 必须原样保留，仅标题下内容本地化。
+
+- full proposal 包含 `## Goal`、`## Scope`、`## Non-goals`、`## Acceptance`、`## Risks`，随后进入 Design。
+- lightweight proposal 在修改项目实现前完整定义 `## Goal`、`## Scope`、`## Non-goals`、`## Approach`、`## Acceptance`、`## Validation`、`## Risks`、`## Upgrade conditions`。
+- hotfix 额外包含 `## Expected behavior`、`## Actual behavior`、`## Reproduction`。
+- tweak 额外包含 `## Current behavior`、`## Preserved behavior`、`## Diff boundary`。
+
+- **Prim**：使用 Matrix 自身能力进行结构化澄清（目标、范围、非目标、验收标准、风险、时限），并编写提案。
+- **Arch**：Open 开始即说明能力与原因，默认调用 `grilling` 澄清需求；仅在领域词汇、不变量或架构决定不清晰时调用 `domain-modeling`。
+- **豁免澄清**：仅当用户同时满足 (1) 自带清晰的执行计划，(2) 明确说明不需要澄清过程 时，才可跳过澄清；跳过仍必须生成 `clarification.md` 的豁免记录。
+
+## 澄清产物（强制）
+
+在编写 proposal 之前生成 `<change>/clarification.md`，无论澄清或豁免都必须落盘：
+
+- 正常澄清：`## Questions` / `## Answers` / `## Resolved scope`（英文标题 token 固定，正文使用 `artifact_language`）；
+- 豁免路径：`## Exemption record`（豁免原因 + 用户计划要点 + proposal 如何采纳该计划）。
+
+lightweight（hotfix/tweak）同样适用，但澄清精简为一轮核心问题。该文件是 Open 阶段的证据类产物：不参与 Contract identity 计算，Runtime 不校验其存在；0.1.5 及更早创建、停在 open 的 change 无需补写即可继续推进。
+
+若进展被另一人掌握的事实或决定阻塞，说明 `to-questionnaire` 适用的原因并让用户显式调用；Matrix 不得自行嵌套该 wrapper。
+
+companion 输出只能作为当前 proposal 的证据，不得创建第二套工作流、提案、确认状态或阶段转换。正确安装的能力失败时最多执行一次同能力 Matrix fallback；安装完整性问题必须修复。
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard open
+# full
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition design
+# hotfix/tweak，仅在用户明确确认后
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --confirmed
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rosenfan/matrix",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Evidence-driven development workflow with Prim and Arch agent-skill orchestration.",
   "license": "MIT",
   "type": "module",

package/src/catalog.js

@@ -6,10 +6,10 @@ import { fileURLToPath } from "node:url";
 import { MATT_INSTALLABLE_SKILLS, MATT_ROLES } from "./matt-catalog.mjs";
 
 export const LANGUAGE_IDS = ["en", "zh-CN"];
-export const PLATFORM_IDS = ["claude-code", "codex"];
+export const PLATFORM_IDS = ["claude-code", "codex", "zcode"];
 export const MATRIX_SKILLS = [
   "matrix", "matrix-open", "matrix-design", "matrix-build", "matrix-verify",
-  "matrix-archive", "matrix-hotfix", "matrix-tweak", "matrix-status", "matrix-claude"
+  "matrix-archive", "matrix-hotfix", "matrix-tweak", "matrix-status", "matrix-handoff"
 ];
 export const MATT_SKILLS = MATT_INSTALLABLE_SKILLS;
 export const UNMANAGED_MATT_SKILLS = MATT_ROLES.incompatible;
@@ -28,6 +28,14 @@ export const PLATFORMS = {
     id: "codex", name: "Codex", skillsCliAgent: "codex",
     skillRoot(base) { return path.join(base, ".agents", "skills"); },
     legacyRoots(base) { return [path.join(base, ".codex", "skills")]; }
+  },
+  // Agents that read the Agent Skills open-standard directory (.agents/skills)
+  // by default — opencode, Kimi Code, and other compatible tools — share the
+  // Codex installation and need no dedicated platform entry.
+  zcode: {
+    id: "zcode", name: "ZCode", skillsCliAgent: "zcode",
+    skillRoot(base) { return path.join(base, ".zcode", "skills"); },
+    legacyRoots() { return []; }
   }
 };