@rosenfan/matrix 0.1.4 → 0.1.6

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Rosen
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Rosen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -93,10 +93,10 @@ matrix init
 
 The interactive setup lets you:
 
-- Choose English or Chinese, project or global Matrix discovery scope, and Claude Code, Codex, or both
+- Choose English or Chinese, project or global Matrix discovery scope, and Claude Code, Codex, or both
 - Copy skills (recommended) or symlink them for local development
 - Safely reconfigure an existing installation with an automatic backup
-- Review all 25 official Matt Skills v1.2.3 roles and install the 23 compatible Skills into the target project
+- Review all 25 official Matt Skills v1.2.3 roles and install the 23 compatible Skills into the target project
 - Choose **Prim** or **Arch** as the project default without disabling the other available mode
 
 For automation and CI:
@@ -105,17 +105,17 @@ For automation and CI:
 # Safe non-interactive installation for both verified platforms
 matrix init --yes --platform claude-code --platform codex --with-mattpocock
 
-# Explicitly select the project default
-matrix init --yes --with-mattpocock --default-orchestration arch
-
-# Replace locally modified Matt Skills only after an explicit backup authorization
-matrix init --yes --with-mattpocock --force-matt
+# Explicitly select the project default
+matrix init --yes --with-mattpocock --default-orchestration arch
+
+# Replace locally modified Matt Skills only after an explicit backup authorization
+matrix init --yes --with-mattpocock --force-matt
 
 # Preview exactly what would change (including backups) without writing
 matrix init --platform codex --dry-run --json
 
-# Inspect Matrix ownership, project-local Matt compatibility, and the selected platform
-matrix doctor --platform codex
+# Inspect Matrix ownership, project-local Matt compatibility, and the selected platform
+matrix doctor --platform codex
 ```
 
 Update an initialized project:
@@ -131,9 +131,9 @@ matrix update --skip-self-update
 matrix update --yes
 ```
 
-`matrix update` preserves the installation's scope, platforms, language, mode, and orchestration. It first validates a newer npm package in isolation, then re-runs the new CLI to refresh Matrix assets. It never downloads, installs, repairs, or deletes Matt Skills; after the Matrix update it reports the local Matt compatibility status and, when needed, points to `matrix init . --with-mattpocock`. npm and project assets are separate transactions: if asset refresh fails after a CLI upgrade, run `matrix update --skip-self-update` to retry.
-
-Matrix 0.1.4 is bound to Matt Skills v1.2.3 at commit `6acc160e4e0cd062dbbbd7a1b26ae92855edf07e`. `matrix init --with-mattpocock` always uses that exact archive and its reviewed 23-Skill compatible manifest, even if upstream has a newer release. The two official but incompatible Skills, `implement` and raw `resolving-merge-conflicts`, are not Matrix-managed or installed. Matrix scope controls Matrix Skill discovery only: Matt Skills and `.matrix/matt-installation.json` are always project-local. Global Matt copies are preserved but never used to complete project readiness.
+`matrix update` preserves the installation's scope, platforms, language, mode, and orchestration. It first validates a newer npm package in isolation, then re-runs the new CLI to refresh Matrix assets. When the local Matt Skills are incomplete or outdated, an interactive `matrix update` asks once and repairs them to the supported release in the same run — CLI upgrade, asset refresh, and Matt repair complete in a single command (`--with-mattpocock` gives non-interactive/CI the same behavior; `--force-matt` additionally replaces locally modified Matt Skills and requires that flag; Matt Skills are never removed by `matrix update`). `--all` extends the run to every indexed project (`~/.matrix/projects.json`); each project updates in isolation and missing directories are pruned from the index. npm and project assets are separate transactions: if asset refresh fails after a CLI upgrade, run `matrix update --skip-self-update` to retry. On Windows the self-update chain runs npm through Node (no shell), so one-command upgrades work without manual steps.
+
+Matrix 0.1.6 is bound to Matt Skills v1.2.3 at commit `6acc160e4e0cd062dbbbd7a1b26ae92855edf07e`. `matrix init --with-mattpocock` always uses that exact archive and its reviewed 23-Skill compatible manifest, even if upstream has a newer release. The two official but incompatible Skills, `implement` and raw `resolving-merge-conflicts`, are not Matrix-managed or installed. Matrix scope controls Matrix Skill discovery only: Matt Skills and `.matrix/matt-installation.json` are always project-local. Global Matt copies are preserved but never used to complete project readiness.
 
 The language selected by `matrix init` controls the prose in new Matrix artifacts. Markdown headings required by Matrix guards remain stable English tokens; the artifact body is Chinese for `zh-CN` and English for `en`. A change freezes this language at creation time.
 
@@ -153,7 +153,7 @@ Matrix installs:
 - `matrix-hotfix/` — Shortcut for small bugs
 - `matrix-tweak/` — Shortcut for bounded changes
 - `matrix-status/` — Check current state
-- `matrix-claude/` — Optional: export for Claude Code
+- `matrix-handoff/` — Optional: export to any implementation agent (Claude Code, opencode, ...)
 
 ---
 
@@ -179,9 +179,9 @@ Matrix will:
 | Phase | Arch capabilities (triggered, not a fixed sequence) | Deliverables | Guard Condition |
 |-------|------------------------------------------------------|--------------|-----------------|
 | **open** | `/grilling`, `/domain-modeling` | `proposal.md`; optional repository-standard context/ADR evidence | Goal, Scope, Non-goals, Acceptance, Risks present |
-| **design** | `/domain-modeling`, `/research`, `/prototype`, `/codebase-design`, conditional `/writing-for-agents` | `design.md`, `plan.md` | Decisions, Test seams, Steps documented |
-| **build** | `/tdd`, `/diagnosing-bugs`, conditional `/writing-for-agents` and generate-only `/wizard` | Code, `verification.md` | Exact approved Contract matches; build evidence recorded |
-| **verify** | `/code-review` | Test evidence, two-axis review, Arch receipt | Evidence is substantive; Arch receipt matches the current Contract, review, and workspace |
+| **design** | `/domain-modeling`, `/research`, `/prototype`, `/codebase-design`, conditional `/writing-for-agents` | `design.md`, `plan.md` | Decisions, Test seams, Steps documented |
+| **build** | `/tdd`, `/diagnosing-bugs`, conditional `/writing-for-agents` and generate-only `/wizard` | Code, `verification.md` | Exact approved Contract matches; build evidence recorded |
+| **verify** | `/code-review` | Test evidence, two-axis review, Arch receipt | Evidence is substantive; Arch receipt matches the current Contract, review, and workspace |
 | **archive** | None; Matrix-owned in both modes | Archive record | Verify guard passed |
 
 ---
@@ -255,28 +255,29 @@ Hotfix and tweak reference the same internal `lightweight` transition profile. T
 
 ---
 
-## Special Feature: matrix-claude
+## Special Feature: matrix-handoff
 
-**Default usage**: Just use the main workflow (`$matrix`). Whether you're using Codex or Claude Code, the standard flow works for both:
+**Default usage**: Just use the main workflow (`$matrix`). Whether you're using Codex, Claude Code, zcode, or opencode, the standard flow works for all of them:
 
 ```
 $matrix → open → design → build → verify → archive
 ```
 
-**When to use `$matrix-claude`**: Only when you want to **split the work across tools** — use Codex for design, then hand off to Claude Code for implementation.
+**When to use `$matrix-handoff`**: Only when you want to **split the work across tools** — design in one agent, implement in another.
 
 | Scenario | What to Do |
 |----------|------------|
 | Use one tool for everything (default) | Just use `$matrix`, no extra steps |
-| Codex designs + Codex implements | Standard flow: design → build → verify |
-| Codex designs + Claude Code implements | design → `$matrix-claude` → Claude Code → verify |
+| Same agent designs and implements | Standard flow: design → build → verify |
+| Codex designs + Claude Code implements | design → `$matrix-handoff` → `export --agent claude-code` → Claude Code → verify |
+| zcode designs + opencode implements | design → `$matrix-handoff` → `export --agent opencode` → opencode → verify |
 
-### How matrix-claude Works
+### How matrix-handoff Works
 
-1. Design phase completes, guard passes
-2. Run `$matrix-claude` → exports frozen design as `artifacts/claude-task.md`
-3. Claude Code reads the task package and implements
-4. Claude Code produces evidence in `artifacts/verification.md`
+1. Design phase completes, guard passes, and you choose the implementation agent at the Design -> Build decision point
+2. Run `$matrix-handoff` → exports the frozen contract as `artifacts/handoff-task-<task-id>.md` (`export --agent <agent-id>`; `--target generic` remains as the legacy Claude Code form, `artifacts/claude-task.md`)
+3. The implementation agent reads the task package and implements
+4. The implementation agent produces evidence in `artifacts/verification.md`
 5. Return to Matrix: build guard → verify → archive
 
 The sidecar does NOT change Matrix state. It's a pure export — like taking a snapshot of the design for another tool to consume.
@@ -285,26 +286,26 @@ The sidecar does NOT change Matrix state. It's a pure export — like taking a s
 
 ## Integration with Matt Pocock's Skills
 
-Prim uses Matrix's own capability. Matrix reviews all 25 official Matt v1.2.3 roles, installs the 23 compatible Skills, and lets Arch automatically invoke only this reviewed ten-capability cohort:
+Prim uses Matrix's own capability. Matrix reviews all 25 official Matt v1.2.3 roles, installs the 23 compatible Skills, and lets Arch automatically invoke only this reviewed ten-capability cohort:
 
 | Phase | Capability | Trigger |
 |---|---|---|
 | open | `/grilling` | Material ambiguity or explicit stress-test request |
 | open/design | `/domain-modeling` | Unclear vocabulary, invariants, or architectural decisions |
 | design | `/research` | Required external facts are unavailable in the repository |
-| design | `/prototype` | A material design question needs disposable evidence |
-| design | `/codebase-design` | A deep-module, interface, or test-seam decision remains |
-| design/build | `/writing-for-agents` | The Contract changes agent-facing instructions or pointer-reached documents |
-| build | `/tdd` | Observable behavior changes at a testable seam |
-| build | `/diagnosing-bugs` | An actual failure exists and root cause is unknown |
-| build | `/wizard` | The Contract requires generated human-run shell steps; Matrix never runs them end-to-end |
-| verify | `/code-review` | Standards and Spec review evidence is required |
-
-Matrix may recommend but never nest these user-invoked handoffs: `setup-matt-pocock-skills`, `improve-codebase-architecture`, `wayfinder`, `handoff`, and `to-questionnaire`. The user explicitly runs them outside the active phase; selected output may enter a governed Change.
-
-Arch records a Runtime-managed review receipt after `code-review`, binding its fixed point and committed HEAD diff to the current Contract, review evidence, and workspace. A normal `code-review` receipt requires a clean candidate worktree outside Matrix-managed assets. When Git has no usable baseline, the committed diff is empty, staged/unstaged/untracked candidate files still exist, or the correctly installed capability fails, Matrix may perform one explicitly labelled same-capability fallback for that revision. The `uncommitted-worktree` fallback binds both the fixed point and a content hash of the complete worktree candidate. Installation-integrity failures never fall back. A heading or self-description without the matching receipt cannot advance Verify.
-
-Installed standalone Skills are `ask-matt`, `grill-with-docs`, `triage`, `to-spec`, `to-tickets`, `grill-me`, `teach`, and `wait-what`. `implement` and raw `resolving-merge-conflicts` are incompatible because they can take over TDD/review/staging/commit effects owned by Matrix, so 0.1.4 neither installs nor manages them. Pre-existing copies are preserved and reported as unmanaged extras. Installation never grants automatic invocation, and no companion may transition, commit, archive, recover, or write Matrix state.
+| design | `/prototype` | A material design question needs disposable evidence |
+| design | `/codebase-design` | A deep-module, interface, or test-seam decision remains |
+| design/build | `/writing-for-agents` | The Contract changes agent-facing instructions or pointer-reached documents |
+| build | `/tdd` | Observable behavior changes at a testable seam |
+| build | `/diagnosing-bugs` | An actual failure exists and root cause is unknown |
+| build | `/wizard` | The Contract requires generated human-run shell steps; Matrix never runs them end-to-end |
+| verify | `/code-review` | Standards and Spec review evidence is required |
+
+Matrix may recommend but never nest these user-invoked handoffs: `setup-matt-pocock-skills`, `improve-codebase-architecture`, `wayfinder`, `handoff`, and `to-questionnaire`. The user explicitly runs them outside the active phase; selected output may enter a governed Change.
+
+Arch records a Runtime-managed review receipt after `code-review`, binding its fixed point and committed HEAD diff to the current Contract, review evidence, and workspace. A normal `code-review` receipt requires a clean candidate worktree outside Matrix-managed assets. When Git has no usable baseline, the committed diff is empty, staged/unstaged/untracked candidate files still exist, or the correctly installed capability fails, Matrix may perform one explicitly labelled same-capability fallback for that revision. The `uncommitted-worktree` fallback binds both the fixed point and a content hash of the complete worktree candidate. Installation-integrity failures never fall back. A heading or self-description without the matching receipt cannot advance Verify.
+
+Installed standalone Skills are `ask-matt`, `grill-with-docs`, `triage`, `to-spec`, `to-tickets`, `grill-me`, `teach`, and `wait-what`. `implement` and raw `resolving-merge-conflicts` are incompatible because they can take over TDD/review/staging/commit effects owned by Matrix, so 0.1.5 neither installs nor manages them. Pre-existing copies are preserved and reported as unmanaged extras. Installation never grants automatic invocation, and no companion may transition, commit, archive, recover, or write Matrix state.
 
 ---
 

package/README.zh-CN.md

@@ -93,10 +93,10 @@ matrix init
 
 交互式初始化支持：
 
-- 选择 Matrix Skill 发现入口安装到当前项目或全局
+- 选择 Matrix Skill 发现入口安装到当前项目或全局
 - 复制 skills（推荐）或为本地开发创建符号链接
 - 安全地重新配置已有安装，并自动备份被替换的 Matrix 文件
-- 审查 Matt Skills v1.2.3 官方 25 项角色，并在目标项目安装其中 23 项兼容 Skill
+- 审查 Matt Skills v1.2.3 官方 25 项角色，并在目标项目安装其中 23 项兼容 Skill
 - 选择 Prim 或 Arch 作为项目默认值，且不禁用另一种可用模式
 
 自动化或 CI 环境可以使用：
@@ -105,11 +105,11 @@ matrix init
 # 使用推荐的项目级默认值，不显示交互问题
 matrix init --yes --with-mattpocock
 
-# 显式选择项目默认编排
-matrix init --yes --with-mattpocock --default-orchestration arch
-
-# 只有明确授权备份后才替换被本地修改的 Matt Skills
-matrix init --yes --with-mattpocock --force-matt
+# 显式选择项目默认编排
+matrix init --yes --with-mattpocock --default-orchestration arch
+
+# 只有明确授权备份后才替换被本地修改的 Matt Skills
+matrix init --yes --with-mattpocock --force-matt
 
 # 检查安装完整性和运行环境
 matrix doctor
@@ -128,9 +128,9 @@ matrix update --skip-self-update
 matrix update --yes
 ```
 
-`matrix update` 会保留既有安装的 scope、平台、语言、mode 与 orchestration。它先隔离验证 npm 新包，再由新 CLI 同步 Matrix 资产；它绝不下载、安装、修复或删除 Matt Skills。Matrix 更新完成后只读报告项目 Matt 兼容状态，必要时提示 `matrix init . --with-mattpocock`。npm 与项目资产是两个事务：若 CLI 已更新但资产同步失败，可运行 `matrix update --skip-self-update` 重试。
-
-Matrix 0.1.4 固定对应 Matt Skills v1.2.3，commit 为 `6acc160e4e0cd062dbbbd7a1b26ae92855edf07e`。即使上游已有新版，`matrix init --with-mattpocock` 仍使用该确切 archive 与经过审查的 23 项兼容 manifest。官方角色中的 `implement` 与 raw `resolving-merge-conflicts` 不兼容，因此 Matrix 不安装也不管理它们。Matrix scope 只控制 Matrix Skill 的发现位置；Matt Skills 与 `.matrix/matt-installation.json` 始终属于目标项目。全局 Matt 副本会保留，但绝不用于补齐项目 readiness。
+`matrix update` 会保留既有安装的 scope、平台、语言、mode 与 orchestration。它先隔离验证 npm 新包，再由新 CLI 同步 Matrix 资产。当本地 Matt Skills 不完整或过期时，交互式 `matrix update` 会询问一次，并在同一轮把 Matt 修复到受支持 release——CLI 升级、资产刷新、Matt 修复一条命令完成（`--with-mattpocock` 为自动化/CI 提供等价的非交互行为；`--force-matt` 可额外替换被本地修改的 Matt Skills，且必须与 `--with-mattpocock` 同传；`matrix update` 绝不删除 Matt Skills）。`--all` 可将更新扩展到全部已索引项目（`~/.matrix/projects.json`），各项目隔离更新，失效目录自动从索引清理。npm 与项目资产是两个事务：若 CLI 已更新但资产同步失败，可运行 `matrix update --skip-self-update` 重试。Windows 上自升级链路经 Node 调用 npm（不经 shell），一条命令升级无需手动步骤。
+
+Matrix 0.1.6 固定对应 Matt Skills v1.2.3，commit 为 `6acc160e4e0cd062dbbbd7a1b26ae92855edf07e`。即使上游已有新版，`matrix init --with-mattpocock` 仍使用该确切 archive 与经过审查的 23 项兼容 manifest。官方角色中的 `implement` 与 raw `resolving-merge-conflicts` 不兼容，因此 Matrix 不安装也不管理它们。Matrix scope 只控制 Matrix Skill 的发现位置；Matt Skills 与 `.matrix/matt-installation.json` 始终属于目标项目。全局 Matt 副本会保留，但绝不用于补齐项目 readiness。
 
 `matrix init` 选择的语言决定新 Matrix 产物的正文语言：`zh-CN` 使用中文、`en` 使用英文。Runtime 守卫依赖的 Markdown 英文标题 token 保持不变；每个 change 在创建时冻结该语言。
 
@@ -150,7 +150,7 @@ Matrix 将安装：
 - `matrix-hotfix/` — 小型 Bug 快捷方式
 - `matrix-tweak/` — 有界变更快捷方式
 - `matrix-status/` — 检查当前状态
-- `matrix-claude/` — 可选：导出供 Claude Code 使用
+- `matrix-handoff/` — 可选：导出给任意实现 agent（Claude Code、opencode 等）
 
 ---
 
@@ -176,9 +176,9 @@ Matrix 将会：
 | 阶段 | Arch 能力（按事实触发，不是固定序列） | 交付物 | 守卫条件 |
 |------|----------------------------------------|--------|----------|
 | **open** | `/grilling`、`/domain-modeling` | `proposal.md`；可选仓库约定的 context/ADR 证据 | 目标、范围、验收标准、风险存在 |
-| **design** | `/domain-modeling`、`/research`、`/prototype`、`/codebase-design`、条件触发的 `/writing-for-agents` | `design.md`、`plan.md` | 决策、测试点、步骤已记录 |
-| **build** | `/tdd`、`/diagnosing-bugs`、条件触发的 `/writing-for-agents` 与仅生成的 `/wizard` | 代码、`verification.md` | 已批准的精确 Contract 匹配，且已记录构建证据 |
-| **verify** | `/code-review` | 测试证据、双轴审查、Arch 回执 | 证据内容充分；Arch 回执匹配当前 Contract、审查正文和工作区 |
+| **design** | `/domain-modeling`、`/research`、`/prototype`、`/codebase-design`、条件触发的 `/writing-for-agents` | `design.md`、`plan.md` | 决策、测试点、步骤已记录 |
+| **build** | `/tdd`、`/diagnosing-bugs`、条件触发的 `/writing-for-agents` 与仅生成的 `/wizard` | 代码、`verification.md` | 已批准的精确 Contract 匹配，且已记录构建证据 |
+| **verify** | `/code-review` | 测试证据、双轴审查、Arch 回执 | 证据内容充分；Arch 回执匹配当前 Contract、审查正文和工作区 |
 | **archive** | 无；两种模式均由 Matrix 拥有 | 归档记录 | 验证守卫通过 |
 
 ---
@@ -252,28 +252,29 @@ hotfix 与 tweak 引用同一个内部 `lightweight` 迁移 profile，只在入
 
 ---
 
-## 特别功能：matrix-claude
+## 特别功能：matrix-handoff
 
-**默认用法**：直接使用主流程即可。无论你用 Codex 还是 Claude Code，标准流程都适用：
+**默认用法**：直接使用主流程即可。无论你用 Codex、Claude Code、zcode 还是 opencode，标准流程都适用：
 
 ```
 $matrix → open → design → build → verify → archive
 ```
 
-**何时使用 `$matrix-claude`**：仅当你想**跨工具拆分工作**时 —— 用 Codex 设计，然后交给 Claude Code 实现。
+**何时使用 `$matrix-handoff`**：仅当你想**跨工具拆分工作**时 —— 用一个 agent 设计，交给另一个 agent 实现。
 
 | 场景 | 操作 |
 |------|------|
 | 一个工具完成所有工作（默认） | 直接用 `$matrix`，无需额外步骤 |
-| Codex 设计 + Codex 实现 | 标准流程：design → build → verify |
-| Codex 设计 + Claude Code 实现 | design → build（批准 Contract）→ `$matrix-claude` → Claude Code → verify |
+| 同一 agent 设计 + 实现 | 标准流程：design → build → verify |
+| Codex 设计 + Claude Code 实现 | design → build（批准 Contract）→ `$matrix-handoff` → `export --agent claude-code` → Claude Code → verify |
+| zcode 设计 + opencode 实现 | design → build（批准 Contract）→ `$matrix-handoff` → `export --agent opencode` → opencode → verify |
 
-### matrix-claude 工作原理
+### matrix-handoff 工作原理
 
-1. 设计阶段完成，守卫通过
-2. 运行 `$matrix-claude` → 导出冻结的设计为 `artifacts/claude-task.md`
-3. Claude Code 读取任务包并实现
-4. Claude Code 在 `artifacts/verification.md` 中产生证据
+1. 设计阶段完成，守卫通过，并在 design→build 决策点选择实现 agent
+2. 运行 `$matrix-handoff` → 导出冻结 Contract 为 `artifacts/handoff-task-<task-id>.md`（`export --agent <agent-id>`；`--target generic` 为兼容的 Claude Code 旧形态，产出 `artifacts/claude-task.md`）
+3. 实现 agent 读取任务包并实现
+4. 实现 agent 在 `artifacts/verification.md` 中产生证据
 5. 返回 Matrix：构建守卫 → 验证 → 归档
 
 此 sidecar 不会改变 Matrix 状态。它只是纯粹的导出 —— 就像为另一个工具拍一张设计快照。
@@ -282,26 +283,26 @@ $matrix → open → design → build → verify → archive
 
 ## 与 Matt Pocock Skills 的集成
 
-Prim 使用 Matrix 自身能力。Matrix 会审查 Matt v1.2.3 官方 25 项角色，安装其中 23 项兼容 Skill，但 Arch 只自动调用以下十项经过审查的能力：
+Prim 使用 Matrix 自身能力。Matrix 会审查 Matt v1.2.3 官方 25 项角色，安装其中 23 项兼容 Skill，但 Arch 只自动调用以下十项经过审查的能力：
 
 | 阶段 | 能力 | 触发条件 |
 |---|---|---|
 | open | `/grilling` | 存在重大歧义或用户明确要求压力测试 |
 | open/design | `/domain-modeling` | 词汇、不变量或架构决定不清晰 |
 | design | `/research` | 仓库内无法获得必需的外部事实 |
-| design | `/prototype` | 重大设计问题需要一次性实验证据 |
-| design | `/codebase-design` | 深模块、接口或测试接缝决定尚未完成 |
-| design/build | `/writing-for-agents` | Contract 修改 agent-facing 指令或指针可达文档 |
-| build | `/tdd` | 可测试接缝上的可观察行为发生变化 |
-| build | `/diagnosing-bugs` | 存在真实失败且根因未知 |
-| build | `/wizard` | Contract 需要生成人工执行的 shell 步骤；Matrix 不端到端运行 |
-| verify | `/code-review` | 需要 Standards 与 Spec 双轴证据 |
-
-Matrix 可以推荐但绝不嵌套以下 user-invoked handoff：`setup-matt-pocock-skills`、`improve-codebase-architecture`、`wayfinder`、`handoff`、`to-questionnaire`。它们由用户在活动阶段外显式运行，选中的结果可以再进入受治理 Change。
-
-Arch 在 `code-review` 后记录由 Runtime 管理的审查回执，把 fixed point 与已提交的 HEAD diff 绑定到当前 Contract、审查正文和工作区。正常的 `code-review` 回执要求 Matrix 管理资产之外的候选工作区是干净的。无可用 Git 基线、已提交 diff 为空、仍存在 staged/unstaged/untracked 候选，或正确安装的 capability 真实失败时，Matrix 可为该 revision 执行一次明确标记的同能力 fallback；其中 `uncommitted-worktree` 会同时绑定 fixed point 与完整工作区候选的内容 hash。安装完整性失败不得 fallback。只有标题或自述、但没有匹配回执时，Verify 不能推进。
-
-安装但保持 standalone 的 Skill 是 `ask-matt`、`grill-with-docs`、`triage`、`to-spec`、`to-tickets`、`grill-me`、`teach`、`wait-what`。`implement` 与 raw `resolving-merge-conflicts` 可能接管 Matrix 所有的 TDD、review、stage 或 commit 副作用，因此 0.1.4 不安装也不管理它们；已有副本会被保留并报告为未管理额外项。安装不代表自动调用；任何 companion 都不得推进、提交、归档、恢复或写 Matrix 状态。
+| design | `/prototype` | 重大设计问题需要一次性实验证据 |
+| design | `/codebase-design` | 深模块、接口或测试接缝决定尚未完成 |
+| design/build | `/writing-for-agents` | Contract 修改 agent-facing 指令或指针可达文档 |
+| build | `/tdd` | 可测试接缝上的可观察行为发生变化 |
+| build | `/diagnosing-bugs` | 存在真实失败且根因未知 |
+| build | `/wizard` | Contract 需要生成人工执行的 shell 步骤；Matrix 不端到端运行 |
+| verify | `/code-review` | 需要 Standards 与 Spec 双轴证据 |
+
+Matrix 可以推荐但绝不嵌套以下 user-invoked handoff：`setup-matt-pocock-skills`、`improve-codebase-architecture`、`wayfinder`、`handoff`、`to-questionnaire`。它们由用户在活动阶段外显式运行，选中的结果可以再进入受治理 Change。
+
+Arch 在 `code-review` 后记录由 Runtime 管理的审查回执，把 fixed point 与已提交的 HEAD diff 绑定到当前 Contract、审查正文和工作区。正常的 `code-review` 回执要求 Matrix 管理资产之外的候选工作区是干净的。无可用 Git 基线、已提交 diff 为空、仍存在 staged/unstaged/untracked 候选，或正确安装的 capability 真实失败时，Matrix 可为该 revision 执行一次明确标记的同能力 fallback；其中 `uncommitted-worktree` 会同时绑定 fixed point 与完整工作区候选的内容 hash。安装完整性失败不得 fallback。只有标题或自述、但没有匹配回执时，Verify 不能推进。
+
+安装但保持 standalone 的 Skill 是 `ask-matt`、`grill-with-docs`、`triage`、`to-spec`、`to-tickets`、`grill-me`、`teach`、`wait-what`。`implement` 与 raw `resolving-merge-conflicts` 可能接管 Matrix 所有的 TDD、review、stage 或 commit 副作用，因此 0.1.5 不安装也不管理它们；已有副本会被保留并报告为未管理额外项。安装不代表自动调用；任何 companion 都不得推进、提交、归档、恢复或写 Matrix 状态。
 
 ---
 

package/{.claude → assets}/skills/matrix/SKILL.md

@@ -1,16 +1,16 @@
----
-name: matrix
-description: Route, initialize, resume, and govern a persistent Matrix development workflow. Use when the user starts a feature, change, bug fix, or asks to resume managed development.
----
-
-# Matrix
-
-Use Matrix as the development-workflow entrypoint. Its source of truth is the current repository's `.matrix/`; never infer a phase from chat history.
-
-Read `artifact_language` from `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect`. Keep required Markdown heading tokens unchanged, but write every user-facing artifact body, explanation, and handoff in that language: English for `en`, Chinese for `zh-CN`.
-
-## Route
-
+---
+name: matrix
+description: Route, initialize, resume, and govern a persistent Matrix development workflow. Use when the user starts a feature, change, bug fix, or asks to resume managed development.
+---
+
+# Matrix
+
+Use Matrix as the development-workflow entrypoint. Its source of truth is the current repository's `.matrix/`; never infer a phase from chat history.
+
+Read `artifact_language` from `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect`. Keep required Markdown heading tokens unchanged, but write every user-facing artifact body, explanation, and handoff in that language: English for `en`, Chinese for `zh-CN`.
+
+## Route
+
 For every workflow command, run the Runtime bundled with this project Skill so the project compatibility authority wins over a different global launcher:
 
 ```powershell
@@ -18,70 +18,71 @@ node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
 ```
 
 Use the global `matrix` command for `init`, `update`, and bootstrap only. A trusted 0.1.4 launcher auto-delegates only to an exact, hash-verified 0.1.4 project Runtime. A different or unidentified project release remains authoritative but must be invoked through the exact direct command returned by the launcher. Older launchers cannot provide this cross-release check and must not be used as the project workflow entrypoint.
-
-- If an active change exists, show its phase and frozen `orchestration`, report any Arch installation-integrity failure, and enter the returned `next_skill` only when the Runtime permits continuation.
-- If no active change exists, classify the request: reproducible small bug → `$matrix-hotfix` with workflow `hotfix`; bounded small change with no public API/schema/architecture impact → `$matrix-tweak` with workflow `tweak`; otherwise full Matrix with workflow `full`.
-- Do not create Matrix state for questions, read-only investigation, or requests outside software development.
-- Before `init`, derive a short kebab-case change id and an accurate title. Start with `full` unless a shortcut clearly applies.
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs init <change-id> --workflow <full|hotfix|tweak> --orchestration <prim|arch> --title "<title>"
-```
-
-An explicit mode wins; otherwise Runtime uses the project `default_orchestration`. The resolved value is immutable for the change and is shown in init, inspect, and the initialized Event. Then enter `$matrix-open`.
-
-## Orchestration
-
-- **Prim** uses Matrix's own capability in every phase and never requires Matt Skills.
+
+- If an active change exists, show its phase and frozen `orchestration`, report any Arch installation-integrity failure, and enter the returned `next_skill` only when the Runtime permits continuation.
+- If no active change exists, classify the request: reproducible small bug → `$matrix-hotfix` with workflow `hotfix`; bounded small change with no public API/schema/architecture impact → `$matrix-tweak` with workflow `tweak`; otherwise full Matrix with workflow `full`.
+- Do not create Matrix state for questions, read-only investigation, or requests outside software development.
+- Before `init`, derive a short kebab-case change id and an accurate title. Start with `full` unless a shortcut clearly applies.
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs init <change-id> --workflow <full|hotfix|tweak> --orchestration <prim|arch> --title "<title>"
+```
+
+An explicit mode wins; otherwise Runtime uses the project `default_orchestration`. The resolved value is immutable for the change and is shown in init, inspect, and the initialized Event. Then enter `$matrix-open`.
+
+## Orchestration
+
+- **Prim** uses Matrix's own capability in every phase and never requires Matt Skills.
 - **Arch** conditionally invokes the ten reviewed automatic capabilities frozen by the active Change. Matrix 0.1.4 reviews all 25 official Matt Skills v1.2.3 roles and installs only the 23 compatible Skills project-locally; `implement` and raw `resolving-merge-conflicts` are excluded.
-
-Both orchestration modes use the same selected workflow profile. `full` uses `open → design → build → verify → archive`; `hotfix` and `tweak` share one internal `lightweight` profile, `open → build → verify → archive`, with different evidence policies. Companion Skills never write Matrix state, transition, commit, archive, or create competing workflow artifacts.
-
-A correctly installed Arch capability that fails gets at most one Matrix-owned fallback for the same bounded capability, with failure and evidence recorded. A missing, modified, or incomplete Arch installation must be repaired with `matrix init --with-mattpocock`; never switch the active change to Prim.
-
-## Recovery
-
-Use Runtime commands instead of editing Matrix state:
-
-```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 return design --reason acceptance-or-design-gap # from Archive, before terminal archive
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs abort --reason <requirement-cancelled|superseded|no-longer-valuable|blocked|other>
-```
-
-Return preserves the change but moves the current `verification.md` into revisioned evidence history, so the returned phase must produce fresh current evidence. Abort preserves the last phase and moves the terminal change into `.matrix/archive/`; it never undoes worktree changes.
-
-If any mutation reports `WORKFLOW_RECOVERY_REQUIRED`, stop normal phase work and run the read-only diagnosis:
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor
-```
-
-Never infer a repair target or strategy. Use only the exact command returned by 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>
-```
-
-## Optional Claude handoff
-
-`$matrix-claude` is an optional sidecar command used after the approved Design -> Build transition. It exports the matching approved contract to a Claude Code task package. It never changes the Matrix phase, workflow, guard result, or runtime state.
-Use it only when the user explicitly chooses Codex design with Claude Code implementation; never inject it into the standard path.
-
-## Cross-Cutting Skills
-
+
+Both orchestration modes use the same selected workflow profile. `full` uses `open → design → build → verify → archive`; `hotfix` and `tweak` share one internal `lightweight` profile, `open → build → verify → archive`, with different evidence policies. Companion Skills never write Matrix state, transition, commit, archive, or create competing workflow artifacts.
+
+A correctly installed Arch capability that fails gets at most one Matrix-owned fallback for the same bounded capability, with failure and evidence recorded. A missing, modified, or incomplete Arch installation must be repaired with `matrix init --with-mattpocock`; never switch the active change to Prim.
+
+## Recovery
+
+Use Runtime commands instead of editing Matrix state:
+
+```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 return design --reason acceptance-or-design-gap # from Archive, before terminal archive
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs abort --reason <requirement-cancelled|superseded|no-longer-valuable|blocked|other>
+```
+
+Return preserves the change but moves the current `verification.md` into revisioned evidence history, so the returned phase must produce fresh current evidence. Abort preserves the last phase and moves the terminal change into `.matrix/archive/`; it never undoes worktree changes.
+
+If any mutation reports `WORKFLOW_RECOVERY_REQUIRED`, stop normal phase work and run the read-only diagnosis:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor
+```
+
+Never infer a repair target or strategy. Use only the exact command returned by 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>
+```
+
+## Optional implementation handoff
+
+`$matrix-handoff` is an optional sidecar command used after the approved Design -> Build transition. It exports the matching approved contract as a bounded task package for the implementation agent the user chooses (`export --agent <agent-id>`, for example Codex designing and Claude Code implementing, or zcode designing and opencode implementing). It never changes the Matrix phase, workflow, guard result, or runtime state.
+Use it only when the user explicitly chooses a different implementation agent; never inject it into the standard path.
+
+## Cross-Cutting Skills
+
 Matrix never nests user-invoked Matt Skills. When relevant, explain the reason and ask the user to invoke one explicitly: `setup-matt-pocock-skills` for one-time setup, `improve-codebase-architecture` for an out-of-band scan, `wayfinder` for generating a separate large-effort candidate, `handoff` at a context boundary, or `to-questionnaire` when another person owns blocking facts. `ask-matt`, `grill-with-docs`, `triage`, `to-spec`, `to-tickets`, `grill-me`, `teach`, and `wait-what` remain standalone. Matrix does not install or manage `implement` or raw `resolving-merge-conflicts`; preserve pre-existing copies as unmanaged extras and never suggest them inside an active Change.
-
-## Rules
-
-- A phase can advance only through `node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition`; run its guard first.
-- A phase can move backward only through one of the documented `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return` intents.
-- Full Build approval binds proposal, design, and plan. Lightweight Build approval binds its compact proposal, requires `transition build --confirmed`, and rejects project implementation changes made after initialization but before approval.
-- A successful Archive is always a two-step optimistic commit: run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --dry-run`, then pass its exact hash to `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --expect-preflight <sha256>`. Never bypass the preflight.
-- `node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor` is read-only. Every transaction or stale-lock repair must explicitly bind the identity reported by doctor; do not edit or delete `.matrix/transactions/` or `.matrix/workflow.lock`.
-- Do not replace required evidence with an assertion that work is complete.
-- Pause for user confirmation at material architecture/scope decisions and before archive/commit.
-- On shortcut scope expansion, run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap`; Runtime upgrades the change to `full`. Never silently continue the old contract.
+
+## Rules
+
+- A phase can advance only through `node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition`; run its guard first.
+- A phase can move backward only through one of the documented `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return` intents.
+- Full Build approval binds proposal, design, and plan. Lightweight Build approval binds its compact proposal, requires `transition build --confirmed`, and rejects project implementation changes made after initialization but before approval.
+- A successful Archive is always a two-step optimistic commit: run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --dry-run`, then pass its exact hash to `node <matrix-skill-directory>/scripts/matrix-runtime.mjs archive --expect-preflight <sha256>`. Never bypass the preflight.
+- `node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor` is read-only. Every transaction or stale-lock repair must explicitly bind the identity reported by doctor; do not edit or delete `.matrix/transactions/` or `.matrix/workflow.lock`.
+- Do not replace required evidence with an assertion that work is complete.
+- Pause for user confirmation at material architecture/scope decisions and before archive/commit.
+- Before entering Build (full: after the design guard; lightweight: merged into the `transition build --confirmed` pause), present the implementation-actor choice — continue with the current agent/model, switch the model in the user's client, or switch the implementation agent via `$matrix-handoff` — and record the decision with the Contract.
+- On shortcut scope expansion, run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap`; Runtime upgrades the change to `full`. Never silently continue the old contract.

package/{.claude → assets}/skills/matrix/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Matrix"
-  short_description: "Route, resume, and govern development changes"
-  default_prompt: "Use $matrix to start or resume a development change."
+interface:
+  display_name: "Matrix"
+  short_description: "Route, resume, and govern development changes"
+  default_prompt: "Use $matrix to start or resume a development change."

package/{.claude → assets}/skills/matrix/scripts/matrix_claude.py

@@ -1,11 +1,11 @@
-#!/usr/bin/env python3
-"""Compatibility adapter for the authoritative Node workflow exporter."""
-from __future__ import annotations
-
-import sys
-
-from matrix_state import run_runtime
-
-
-if __name__ == "__main__":
-    raise SystemExit(run_runtime(sys.argv[1:]))
+#!/usr/bin/env python3
+"""Compatibility adapter for the authoritative Node workflow exporter."""
+from __future__ import annotations
+
+import sys
+
+from matrix_state import run_runtime
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_runtime(sys.argv[1:]))