@rosenfan/matrix 0.1.0

package/.claude/skills/matrix-status/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: matrix-status
+description: Inspect the active Matrix workflow and report its disk-backed phase, guard result, and recovery command. Use when the user asks for Matrix status, next step, or to resume interrupted Matrix work.
+---
+
+# Matrix Status
+
+Run the same Matrix state kernel used by the main entry and every phase Skill:
+
+```powershell
+matrix workflow inspect
+```
+
+Report the returned change id, workflow, phase, guard result, and `next_skill`. Do not infer status from conversation history and do not modify state. If the guard is failing, name the missing evidence and direct the user to the current phase Skill.

package/.claude/skills/matrix-status/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Matrix Status"
+  short_description: "Inspect and recover active Matrix workflow state"
+  default_prompt: "Use $matrix-status to inspect the active Matrix workflow."

package/.claude/skills/matrix-tweak/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: matrix-tweak
+description: Run a lightweight Matrix workflow for a bounded small development change. Use for a small request with no schema, public API, architecture, or cross-module coordination impact.
+---
+
+# Matrix Tweak
+
+Start through `$matrix` with workflow `tweak`. Keep proposal and design concise, but still define acceptance criteria and test seams. Upgrade to full `$matrix` when the change crosses module, API, schema, or architecture boundaries.

package/.claude/skills/matrix-tweak/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Matrix Workflow"
+  short_description: "Persistent development workflow stage"
+  default_prompt: "Use $name to continue a Matrix development workflow."

package/.claude/skills/matrix-verify/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: matrix-verify
+description: Verify the active Matrix change against its plan and review its diff. Use when the active Matrix phase is verify.
+---
+
+# Matrix Verify
+
+Run the plan's acceptance commands and record their output summaries under `## Test evidence` in `artifacts/verification.md`.
+
+## Input Sources
+
+This phase can receive implementation from two sources:
+
+1. **Direct Codex implementation** — from `$matrix-build` phase
+2. **Claude Code implementation** — from `$matrix-claude` sidecar
+
+Regardless of source, the verification process is the same: check that implementation evidence meets the plan's requirements.
+
+## Prerequisites
+
+Before starting verification, ensure:
+
+- [ ] `artifacts/verification.md` exists
+- [ ] `## Build evidence` section is present and substantive
+- [ ] All commands from the plan's `## Validation` section have been run
+- [ ] Test results are recorded
+
+If these are missing (e.g., Claude Code didn't produce complete evidence), return to `$matrix-build` or ask Claude Code to补充.
+
+## Skills to Use
+
+### Primary: `code-review`
+
+Use the `code-review` skill to perform a two-axis review of the diff:
+
+1. **Standards axis** — Does the code conform to this repo's documented coding standards? Includes a "smell baseline" (Fowler code smells) even when no standards are documented.
+
+2. **Spec axis** — Does the code faithfully implement the originating issue/PRD/spec? Checks for:
+   - Missing or partial requirements
+   - Scope creep (behavior not asked for)
+   - Wrong implementations of required behavior
+
+Both axes run as parallel sub-agents and report separately. Record findings under `## Review evidence` in `artifacts/verification.md`.
+
+### Optional: `improve-codebase-architecture`
+
+After verification passes, if the change touched modules that could be deepened, use `improve-codebase-architecture` to scan for shallow-module opportunities. This is advisory — skip it for simple changes or when time is constrained.
+
+## Failure Handling
+
+If verification or review fails:
+- If the issue is in the implementation → **return to `$matrix-build`** or ask Claude Code to fix
+- If the issue is in the plan/design → return to `$matrix-design`
+
+If documents or public behavior changed, record the required synchronization work before the guard.
+
+## Process
+
+1. Check that `artifacts/verification.md` exists with `## Build evidence`
+2. Run the plan's acceptance commands (from `plan.md` `## Validation` section)
+3. Record test output under `## Test evidence`
+4. Load `code-review` skill
+5. Run both axes (Standards + Spec) in parallel
+6. Record findings under `## Review evidence`
+7. Optionally run `improve-codebase-architecture`
+8. Run the guard
+9. If guard passes, run transition to advance to archive phase
+10. **Then enter `$matrix-archive` to continue the workflow**
+
+```powershell
+matrix workflow guard verify
+matrix workflow transition archive
+```
+
+## Evidence Requirements
+
+The guard checks for:
+
+1. **Test evidence** — Output from running the plan's validation commands
+2. **Review evidence** — Findings from the two-axis code review
+
+Both must be present and substantive (>40 chars each) to pass the guard.

package/.claude/skills/matrix-verify/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Matrix Workflow"
+  short_description: "Persistent development workflow stage"
+  default_prompt: "Use $name to continue a Matrix development workflow."

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,273 @@
+# Matrix Workflow
+
+A structured workflow orchestrator for [Matt Pocock's Claude Code skills](https://github.com/mattpocock/skills), inspired by [Comet](https://github.com/rpamis/comet). It enforces evidence-based phase transitions to standardize your development process when using these skills.
+
+English | **[中文](./README.zh-CN.md)**
+
+<p align="center">
+  <img src="./assets/matrix-workflow-poster-en.svg" alt="Matrix Workflow" width="100%">
+</p>
+
+---
+
+## Table of Contents
+
+- [Why Matrix?](#why-matrix)
+- [What It Does](#what-it-does)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Workflow Phases](#workflow-phases)
+- [How It Works](#how-it-works)
+- [Workflow Types](#workflow-types)
+- [Integration with Matt Pocock's Skills](#integration-with-matt-pococks-skills)
+- [License](#license)
+
+---
+
+## Why Matrix
+
+[Matt Pocock's skills](https://github.com/mattpocock/skills) are excellent individual tools — `/grill-with-docs` for requirements, `/tdd` for test-driven development, `/implement` for execution. But using them in isolation leads to common problems:
+
+- **No process memory**: You grill, then implement, but there's no record of what was decided
+- **Phase confusion**: Did we finish design? Are we in build? Hard to tell after context loss
+- **Silent scope creep**: Requirements change mid-build without returning to design
+- **Missing evidence**: "Looks done" without verification proof
+
+Matrix solves this by wrapping these skills into a deterministic state machine with explicit phases, guard conditions, and artifact tracking — inspired by [Comet](https://github.com/rpamis/comet)'s phase-based approach.
+
+---
+
+## What It Does
+
+Matrix orchestrates Matt Pocock's skills into a structured workflow:
+
+```
+open → design → build → verify → archive
+  ↓       ↓        ↓        ↓        ↓
+grill   plan    implement  tdd    commit
+        design            review
+```
+
+Each phase:
+- Has specific deliverables (artifacts)
+- Has guard conditions that must pass
+- Logs all transitions
+- Survives context loss (state on disk)
+
+---
+
+## Prerequisites
+
+- [Claude Code](https://docs.anthropic.com/claude-code) and/or Codex installed
+- Node.js 18+ (for the installer)
+- Python is optional during the compatibility window; new installations run the bundled Node workflow runtime.
+
+---
+
+## Installation
+
+Install the Matrix CLI once:
+
+```bash
+npm install --global @rosenfan/matrix
+```
+
+Then initialize Matrix inside any project:
+
+```bash
+cd /path/to/your/project
+matrix init
+```
+
+The interactive setup lets you:
+
+- Choose English or Chinese, project or global scope, and Claude Code, Codex, or both
+- Copy skills (recommended) or symlink them for local development
+- Safely update an existing installation with an automatic backup
+- Install Matt Pocock's companion skills in the same flow
+
+For automation and CI:
+
+```bash
+# Safe non-interactive installation for both verified platforms
+matrix init --yes --platform claude-code --platform codex --with-mattpocock
+
+# Preview exactly what would change (including backups) without writing
+matrix init --platform codex --dry-run --json
+
+# Inspect Matrix ownership, Matt Skills inheritance, and the selected platform
+matrix doctor --platform codex
+```
+
+Until the npm package is published, install directly from GitHub:
+
+```bash
+npm install --global github:Rosenfan/Matrix
+```
+
+Matrix installs:
+- `matrix/` — Entry point and state management
+- `matrix-open/` — Open phase (uses `/grill-with-docs`)
+- `matrix-design/` — Design phase (uses `/prototype`, `/research`)
+- `matrix-build/` — Build phase (uses `/implement`, `/tdd`)
+- `matrix-verify/` — Verify phase (uses `/code-review`)
+- `matrix-archive/` — Archive phase
+- `matrix-hotfix/` — Shortcut for small bugs
+- `matrix-tweak/` — Shortcut for bounded changes
+- `matrix-status/` — Check current state
+- `matrix-claude/` — Optional: export for Claude Code
+
+---
+
+## Quick Start
+
+In Claude Code:
+
+```
+$matrix I want to add user authentication
+```
+
+Matrix will:
+1. Initialize a change with workflow type `full`
+2. Enter `open` phase → invokes `/grill-with-docs` to clarify requirements
+3. Create `proposal.md` with Goal, Scope, Acceptance, Risks
+4. Guard check: are all sections substantive?
+5. If pass → transition to `design`
+
+---
+
+## Workflow Phases
+
+| Phase | Matt Pocock Skills Used | Deliverables | Guard Condition |
+|-------|-------------------------|--------------|-----------------|
+| **open** | `/grill-with-docs` (auto-invokes `/grilling` + `/domain-modeling`) | `proposal.md`, `CONTEXT.md`, ADRs | Goal, Scope, Acceptance, Risks present |
+| **design** | `/domain-modeling` → `/research` → `/wayfinder` → `/prototype` → `/codebase-design` | `design.md`, `plan.md` | Decisions, Test seams, Steps documented |
+| **build** | `/implement` (auto-invokes `/tdd` + `/code-review`), `/diagnosing-bugs`, `/resolving-merge-conflicts` | Code, `verification.md` | Plan exists, build evidence recorded |
+| **verify** | `/code-review` (two-axis: Standards + Spec), `/improve-codebase-architecture` | Test & review evidence | Test and review evidence present |
+| **archive** | — | Git commit | Verify guard passed |
+
+---
+
+## How It Works
+
+State is stored in `.matrix/`:
+
+```
+.matrix/
+├── active.json              # Current change ID
+├── config.yaml
+├── changes/
+│   └── <change-id>/
+│       ├── matrix.yaml      # Phase, workflow, timestamps
+│       ├── run-state.json
+│       ├── events.jsonl
+│       └── artifacts/
+│           ├── proposal.md
+│           ├── design.md
+│           ├── plan.md
+│           └── verification.md
+└── archive/
+```
+
+The state machine enforces transitions:
+
+```bash
+# Check guard
+python .claude/skills/matrix/scripts/matrix_state.py guard open
+
+# Advance (only if guard passes)
+python .claude/skills/matrix/scripts/matrix_state.py transition design
+```
+
+---
+
+## Workflow Types
+
+| Type | When to Use | Phases |
+|------|-------------|--------|
+| **full** | New features, architecture changes | All 5 phases |
+| **hotfix** | Reproducible small bugs | Simplified: open → build → verify → archive |
+| **tweak** | Bounded changes, no API/schema impact | Simplified: open → build → verify → archive |
+
+---
+
+## Special Feature: matrix-claude
+
+**Default usage**: Just use the main workflow (`$matrix`). Whether you're using Codex or Claude Code, the standard flow works for both:
+
+```
+$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.
+
+| 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 |
+
+### How matrix-claude 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`
+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.
+
+---
+
+## Integration with Matt Pocock's Skills
+
+Matrix is designed to work **on top of** Matt Pocock's skills, not replace them. Here's how they map:
+
+### open Phase
+
+| Skill | How Matrix Uses It |
+|-------|-------------------|
+| `/grill-with-docs` | Main skill: runs `/grilling` + `/domain-modeling` to clarify requirements |
+| `/grilling` | Stress-tests the plan through relentless Q&A |
+| `/domain-modeling` | Establishes shared vocabulary, creates `CONTEXT.md` and ADRs |
+
+### design Phase (Recommended Order)
+
+| Order | Skill | How Matrix Uses It |
+|-------|-------|-------------------|
+| 1 | `/domain-modeling` | Establish or refine domain vocabulary from the proposal |
+| 2 | `/research` | Investigate external APIs, docs, specs (runs in background) |
+| 3 | `/wayfinder` | Explore complex codebase structure and dependencies |
+| 4 | `/prototype` | Validate design questions with throwaway experiments |
+| 5 | `/codebase-design` | Define module boundaries, interfaces, test seams |
+
+### build Phase
+
+| Skill | How Matrix Uses It |
+|-------|-------------------|
+| `/implement` | Main skill: executes plan with TDD, then runs code review, then commits |
+| `/tdd` | Auto-invoked by `/implement`: red-green-refactor at pre-agreed seams |
+| `/diagnosing-bugs` | On failure: builds tight feedback loop before fixing |
+| `/resolving-merge-conflicts` | On merge conflicts: systematic resolution |
+
+### verify Phase
+
+| Skill | How Matrix Uses It |
+|-------|-------------------|
+| `/code-review` | Two-axis review: **Standards** (coding conventions) + **Spec** (requirements fidelity) |
+| `/improve-codebase-architecture` | Optional: scan for shallow-module deepening opportunities |
+
+---
+
+**Key difference**: Matt Pocock's skills are individual tools. Matrix adds:
+- **State persistence**: Survives context loss
+- **Phase enforcement**: Can't skip design and jump to build
+- **Evidence requirements**: Guards check for artifacts, not assertions
+- **Transition logging**: Full audit trail of phase changes
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,271 @@
+# Matrix Workflow
+
+一个基于 [Matt Pocock 的 Claude Code skills](https://github.com/mattpocock/skills) 的结构化工作流编排器，灵感来自 [Comet](https://github.com/rpamis/comet)。它通过强制执行基于证据的阶段转换，规范使用这些 skills 时的开发流程。
+
+**[English](./README.md)** | 中文
+
+<p align="center">
+  <img src="./assets/matrix-workflow-poster-zh.svg" alt="Matrix Workflow" width="100%">
+</p>
+
+---
+
+## 目录
+
+- [为什么需要 Matrix](#为什么需要-matrix)
+- [它做了什么](#它做了什么)
+- [前置条件](#前置条件)
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [工作流阶段](#工作流阶段)
+- [工作原理](#工作原理)
+- [工作流类型](#工作流类型)
+- [与 Matt Pocock Skills 的集成](#与-matt-pocock-skills-的集成)
+- [许可证](#许可证)
+
+---
+
+## 为什么需要 Matrix
+
+[Matt Pocock 的 skills](https://github.com/mattpocock/skills) 是优秀的独立工具 —— `/grill-with-docs` 用于需求澄清，`/tdd` 用于测试驱动开发，`/implement` 用于执行实现。但单独使用它们会导致常见问题：
+
+- **无流程记忆**：你进行了 grilling，然后实现，但没有记录决策过程
+- **阶段混乱**：设计完成了吗？我们在构建阶段吗？上下文丢失后很难判断
+- **静默范围蔓延**：需求在构建过程中变更，却没有返回设计阶段
+- **缺少证据**："看起来完成了"却没有验证证明
+
+Matrix 通过将这些 skills 封装到确定性状态机中来解决这些问题 —— 包含明确的阶段、守卫条件和产物追踪。灵感来自 [Comet](https://github.com/rpamis/comet) 的阶段式方法。
+
+---
+
+## 它做了什么
+
+Matrix 将 Matt Pocock 的 skills 编排成结构化工作流：
+
+```
+open → design → build → verify → archive
+(开放)  (设计)   (构建)   (验证)   (归档)
+  ↓       ↓        ↓        ↓        ↓
+grill   plan    implement  tdd    commit
+        design            review
+```
+
+每个阶段：
+- 有特定的交付物（产物）
+- 有必须通过的守卫条件
+- 记录所有转换
+- 可承受上下文丢失（状态存储在磁盘上）
+
+---
+
+## 前置条件
+
+- 已安装 [Claude Code](https://docs.anthropic.com/claude-code)
+- Node.js 18+（用于运行安装器）
+- Python 3.8+ 已添加到 PATH
+
+---
+
+## 安装
+
+只需全局安装一次 Matrix CLI：
+
+```bash
+npm install --global @rosenfan/matrix
+```
+
+之后在任意项目中初始化：
+
+```bash
+cd /path/to/your/project
+matrix init
+```
+
+交互式初始化支持：
+
+- 选择安装到当前项目或全局
+- 复制 skills（推荐）或为本地开发创建符号链接
+- 更新已有安装，并自动备份被替换的 Matrix 文件
+- 在同一流程中安装 Matt Pocock 的配套 skills
+
+自动化或 CI 环境可以使用：
+
+```bash
+# 使用推荐的项目级默认值，不显示交互问题
+matrix init --yes --with-mattpocock
+
+# 检查安装完整性和运行环境
+matrix doctor
+```
+
+npm 包正式发布前，也可以直接从 GitHub 安装：
+
+```bash
+npm install --global github:Rosenfan/Matrix
+```
+
+Matrix 将安装：
+- `matrix/` — 入口点和状态管理
+- `matrix-open/` — 开放阶段（使用 `/grill-with-docs`）
+- `matrix-design/` — 设计阶段（使用 `/prototype`、`/research`）
+- `matrix-build/` — 构建阶段（使用 `/implement`、`/tdd`）
+- `matrix-verify/` — 验证阶段（使用 `/code-review`）
+- `matrix-archive/` — 归档阶段
+- `matrix-hotfix/` — 小型 Bug 快捷方式
+- `matrix-tweak/` — 有界变更快捷方式
+- `matrix-status/` — 检查当前状态
+- `matrix-claude/` — 可选：导出供 Claude Code 使用
+
+---
+
+## 快速开始
+
+在 Claude Code 中：
+
+```
+$matrix 我想给 API 添加用户认证
+```
+
+Matrix 将会：
+1. 用工作流类型 `full` 初始化一个变更
+2. 进入 `open` 阶段 → 调用 `/grill-with-docs` 澄清需求
+3. 创建 `proposal.md`，包含目标、范围、验收标准、风险
+4. 守卫检查：所有章节是否内容充实？
+5. 如果通过 → 转换到 `design`
+
+---
+
+## 工作流阶段
+
+| 阶段 | 使用的 Matt Pocock Skills | 交付物 | 守卫条件 |
+|------|---------------------------|--------|----------|
+| **open** | `/grill-with-docs`（自动调用 `/grilling` + `/domain-modeling`） | `proposal.md`、`CONTEXT.md`、ADRs | 目标、范围、验收标准、风险存在 |
+| **design** | `/domain-modeling` → `/research` → `/wayfinder` → `/prototype` → `/codebase-design` | `design.md`、`plan.md` | 决策、测试点、步骤已记录 |
+| **build** | `/implement`（自动调用 `/tdd` + `/code-review`）、`/diagnosing-bugs`、`/resolving-merge-conflicts` | 代码、`verification.md` | 计划存在，构建证据已记录 |
+| **verify** | `/code-review`（双轴：Standards + Spec）、`/improve-codebase-architecture` | 测试和审查证据 | 测试和审查证据存在 |
+| **archive** | — | Git commit | 验证守卫通过 |
+
+---
+
+## 工作原理
+
+状态存储在 `.matrix/` 目录：
+
+```
+.matrix/
+├── active.json              # 当前变更 ID
+├── config.yaml
+├── changes/
+│   └── <change-id>/
+│       ├── matrix.yaml      # 阶段、工作流、时间戳
+│       ├── run-state.json
+│       ├── events.jsonl
+│       └── artifacts/
+│           ├── proposal.md
+│           ├── design.md
+│           ├── plan.md
+│           └── verification.md
+└── archive/
+```
+
+状态机强制执行转换：
+
+```bash
+# 检查守卫
+python .claude/skills/matrix/scripts/matrix_state.py guard open
+
+# 推进（仅在守卫通过时）
+python .claude/skills/matrix/scripts/matrix_state.py transition design
+```
+
+---
+
+## 工作流类型
+
+| 类型 | 使用场景 | 阶段 |
+|------|----------|------|
+| **full** | 新功能、架构变更 | 全部 5 个阶段 |
+| **hotfix** | 可复现的小型 Bug | 简化：open → build → verify → archive |
+| **tweak** | 有界变更，无 API/架构影响 | 简化：open → build → verify → archive |
+
+---
+
+## 特别功能：matrix-claude
+
+**默认用法**：直接使用主流程即可。无论你用 Codex 还是 Claude Code，标准流程都适用：
+
+```
+$matrix → open → design → build → verify → archive
+```
+
+**何时使用 `$matrix-claude`**：仅当你想**跨工具拆分工作**时 —— 用 Codex 设计，然后交给 Claude Code 实现。
+
+| 场景 | 操作 |
+|------|------|
+| 一个工具完成所有工作（默认） | 直接用 `$matrix`，无需额外步骤 |
+| Codex 设计 + Codex 实现 | 标准流程：design → build → verify |
+| Codex 设计 + Claude Code 实现 | design → `$matrix-claude` → Claude Code → verify |
+
+### matrix-claude 工作原理
+
+1. 设计阶段完成，守卫通过
+2. 运行 `$matrix-claude` → 导出冻结的设计为 `artifacts/claude-task.md`
+3. Claude Code 读取任务包并实现
+4. Claude Code 在 `artifacts/verification.md` 中产生证据
+5. 返回 Matrix：构建守卫 → 验证 → 归档
+
+此 sidecar 不会改变 Matrix 状态。它只是纯粹的导出 —— 就像为另一个工具拍一张设计快照。
+
+---
+
+## 与 Matt Pocock Skills 的集成
+
+Matrix 设计为**在 Matt Pocock 的 skills 之上工作**，而非替代它们。以下是各阶段的详细映射：
+
+### open 阶段
+
+| Skill | Matrix 如何使用 |
+|-------|-----------------|
+| `/grill-with-docs` | 主技能：运行 `/grilling` + `/domain-modeling` 澄清需求 |
+| `/grilling` | 通过连续提问压力测试计划 |
+| `/domain-modeling` | 建立共享词汇，创建 `CONTEXT.md` 和 ADRs |
+
+### design 阶段（推荐顺序）
+
+| 顺序 | Skill | Matrix 如何使用 |
+|------|-------|-----------------|
+| 1 | `/domain-modeling` | 从提案中建立或精炼领域词汇 |
+| 2 | `/research` | 调查外部 API、文档、规范（后台运行） |
+| 3 | `/wayfinder` | 探索复杂代码库结构和依赖 |
+| 4 | `/prototype` | 用一次性实验验证设计问题 |
+| 5 | `/codebase-design` | 定义模块边界、接口、测试点 |
+
+### build 阶段
+
+| Skill | Matrix 如何使用 |
+|-------|-----------------|
+| `/implement` | 主技能：执行计划，使用 TDD，运行代码审查，然后提交 |
+| `/tdd` | 由 `/implement` 自动调用：在确认的接缝处进行红绿重构 |
+| `/diagnosing-bugs` | 遇到失败时：先构建紧凑的反馈循环再修复 |
+| `/resolving-merge-conflicts` | 遇到合并冲突时：系统性解决 |
+
+### verify 阶段
+
+| Skill | Matrix 如何使用 |
+|-------|-----------------|
+| `/code-review` | 双轴审查：**Standards**（编码规范）+ **Spec**（需求忠实度） |
+| `/improve-codebase-architecture` | 可选：扫描浅模块深化机会 |
+
+---
+
+**关键区别**：Matt Pocock 的 skills 是独立工具。Matrix 增加了：
+- **状态持久化**：可承受上下文丢失
+- **阶段强制**：不能跳过设计直接进入构建
+- **证据要求**：守卫检查产物，而非断言
+- **转换日志**：完整的阶段变更审计记录
+
+---
+
+## 许可证
+
+[MIT](./LICENSE)