@rosenfan/matrix 0.1.0

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

@@ -0,0 +1,49 @@
+---
+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.
+
+## Route
+
+First run:
+
+```powershell
+matrix workflow inspect
+```
+
+If and only if the `matrix` executable is reported as absent, run the bundled fallback from this Skill directory instead:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
+```
+
+- If an active change exists, show its phase and enter the returned `next_skill`.
+- 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
+matrix workflow init <change-id> --workflow <full|hotfix|tweak> --title "<title>"
+```
+
+Then enter `$matrix-open`. State initialization creates tracked design artifacts and ignores machine-only state without changing the repository's existing `.gitignore`.
+
+## Optional Claude handoff
+
+`$matrix-claude` is an optional sidecar command that exports a frozen Matrix design to a Claude Code task package. It never changes the Matrix phase, workflow, guard result, or runtime state.
+
+## Cross-Cutting Skills
+
+### Handoff (`handoff`)
+When context is running low and work needs to continue in a fresh session, use `handoff` at any stage boundary. It compacts the conversation into a handoff document with suggested skills for the next agent. Save to the OS temp directory, not the workspace.
+
+## Rules
+
+- A phase can advance only through `matrix workflow transition`; run its guard first.
+- 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 scope expansion, return to `$matrix-design`; never silently continue the old plan.

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

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

package/.claude/skills/matrix/scripts/matrix_claude.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Export a frozen Matrix design to a Claude Code task package without changing Matrix state."""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from matrix_state import active_path, artifact, get_active, guard, parse_flow, root
+
+
+def fail(message: str) -> None:
+    print(f"MATRIX CLAUDE ERROR: {message}", file=sys.stderr)
+    raise SystemExit(2)
+
+
+def read_artifact(change: str, name: str) -> str:
+    path = artifact(change, name)
+    if not path.exists():
+        fail(f"Required Matrix artifact is missing: {path}")
+    return path.read_text(encoding="utf-8").strip()
+
+
+def task_content(change: str, task_id: str, proposal: str, design: str, plan: str, result_path: str) -> str:
+    return f"""# Claude Code 执行任务包：{task_id}
+
+## 元数据
+
+| 字段 | 内容 |
+| --- | --- |
+| 状态 | CLAUDE_QUEUED |
+| Codex 决策人 | Codex |
+| Claude Code 执行人 | Claude Code |
+| Matrix Change | `{change}` |
+| 回执 | `{result_path}` |
+
+## 目标
+
+以下目标来自已冻结的 Matrix proposal，不得扩展：
+
+{proposal}
+
+## 范围
+
+### 允许修改
+
+- 仅修改为完成下列 Matrix 设计与计划所必需的文件。
+- 先阅读仓库级指令与现有测试，再开始实施。
+
+### 禁止修改
+
+- 不得修改 Matrix 状态文件或推进 Matrix phase。
+- 不得自行改变架构、公开接口、数据模型、依赖或任务范围。
+- 不得执行未获授权的网络、部署、破坏性或外部副作用动作。
+
+## 禁止事项
+
+- 不得把设计外的发现直接实现为额外功能。
+- 遇到范围扩大、设计冲突或验收不清时必须停止并写 `NEEDS_DECISION`。
+
+## 已冻结的设计决定
+
+{design}
+
+## 执行步骤
+
+{plan}
+
+## 验收
+
+- 执行 `plan.md` 中的全部验证命令。
+- 为每项行为变化提供测试或可复现验证证据。
+- 完成后保留可供 Codex 固定基线审查的 diff。
+
+## 停止并上报的条件
+
+- 需要修改范围外文件或改变冻结设计。
+- 验收失败且不能在既定范围内修复。
+- 发现安全、授权或项目指令冲突。
+
+## 回执路径
+
+在 `{result_path}` 创建结构化回执，至少包含：
+
+- `## 元数据`：执行状态与任务 ID。
+- `## 改动清单`：实际改动文件和理由。
+- `## 测试结果`：命令与输出摘要。
+- `## 边界确认`：未越界声明，或 `NEEDS_DECISION`。
+- `## 未解决项`：如有。
+
+Codex 才能验收；Claude Code 不得自行宣告任务已接受或完成。
+"""
+
+
+def active_board(task_id: str, task_path: str, result_path: str, change: str) -> str:
+    return f"""# 活跃任务看板
+
+> 这里是唯一实时任务面板：只放当前任务的状态、执行主体、范围、完成条件和下一步。
+
+## 当前状态
+
+| 字段 | 内容 |
+| --- | --- |
+| ID | {task_id} |
+| 状态 | CLAUDE_QUEUED |
+| 执行主体 | Claude Code（由用户通过 `$matrix-claude` 明确选择） |
+| 目标 | 执行 Matrix Change `{change}` 的冻结任务包。 |
+| 冻结设计 | `.matrix/changes/{change}/artifacts/{{proposal,design,plan}}.md` |
+| 任务包 | `{task_path}` |
+| 回执 | `{result_path}` |
+| 完成条件 | 任务包验收命令通过、Claude 回执齐全，并经 Codex 审查实际 diff 和证据。 |
+| 下一步 | Claude Code 按冻结任务包实施；范围冲突时写 `NEEDS_DECISION`。 |
+"""
+
+
+def export(args: argparse.Namespace) -> None:
+    change = get_active()
+    flow = parse_flow(root() / "changes" / change / "matrix.yaml")
+    if flow.get("phase") != "design":
+        fail(f"Matrix change '{change}' is in phase '{flow.get('phase')}', not design.")
+    if not guard(change, "design", output=True):
+        fail("Design guard failed; no Claude task package was written.")
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9-]*", args.task_id):
+        fail("Task id must use letters, digits, and hyphens.")
+    proposal, design, plan = (read_artifact(change, n) for n in ("proposal.md", "design.md", "plan.md"))
+
+    if args.target == "generic":
+        output = artifact(change, "claude-task.md")
+        result = artifact(change, "claude-result.md")
+        output.write_text(task_content(change, args.task_id, proposal, design, plan, str(result.relative_to(Path.cwd())).replace("\\", "/")), encoding="utf-8")
+        print(output)
+        return
+
+    tasks = Path.cwd() / "docs" / "tasks"
+    if not tasks.is_dir() or not (tasks / "active.md").is_file():
+        fail("FnSec target requires docs/tasks/active.md in the current project.")
+    output = tasks / f"claude-task-{args.task_id}.md"
+    result = tasks / f"claude-result-{args.task_id}.md"
+    if output.exists() or result.exists():
+        fail(f"FnSec task or result path already exists for {args.task_id}.")
+    output.write_text(task_content(change, args.task_id, proposal, design, plan, str(result.relative_to(Path.cwd())).replace("\\", "/")), encoding="utf-8")
+    if args.apply_fnsec_board:
+        board = tasks / "active.md"
+        current = board.read_text(encoding="utf-8")
+        if "NO_ACTIVE_OBJECTIVE" not in current:
+            output.unlink()
+            fail("FnSec active.md already has an objective; refused to overwrite it.")
+        board.write_text(active_board(args.task_id, str(output.relative_to(Path.cwd())).replace("\\", "/"), str(result.relative_to(Path.cwd())).replace("\\", "/"), change), encoding="utf-8")
+    print(output)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    subs = parser.add_subparsers(dest="command", required=True)
+    command = subs.add_parser("export")
+    command.add_argument("--task-id", required=True)
+    command.add_argument("--target", choices=("generic", "fnsec"), default="generic")
+    command.add_argument("--apply-fnsec-board", action="store_true")
+    command.set_defaults(func=export)
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/skills/matrix/scripts/matrix_state.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""Deterministic state and guard kernel shared by every Matrix Skill."""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+PHASES = ("open", "design", "build", "verify", "archive")
+NEXT = {"open": "design", "design": "build", "build": "verify", "verify": "archive"}
+SKILLS = {phase: f"$matrix-{phase}" for phase in PHASES}
+
+def now(): return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+def root(): return Path.cwd() / ".matrix"
+def active_path(): return root() / "active.json"
+def fail(message): print(f"MATRIX ERROR: {message}", file=sys.stderr); raise SystemExit(2)
+def write_json(path, value): path.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+def load_json(path): return json.loads(path.read_text(encoding="utf-8"))
+def flow_path(change): return root() / "changes" / change / "matrix.yaml"
+def parse_flow(path):
+    values = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if ":" in line and not line.startswith(" "):
+            key, value = line.split(":", 1); values[key.strip()] = value.strip().strip('"')
+    return values
+def write_flow(path, values):
+    order = ("schema", "id", "workflow", "status", "phase", "title", "created_at", "updated_at", "acceptance", "scope")
+    path.write_text("\n".join(f"{key}: {values.get(key, '')}" for key in order) + "\n", encoding="utf-8")
+def get_active():
+    if not active_path().exists(): fail("No active Matrix change. Start with $matrix <request>.")
+    change = load_json(active_path()).get("change_id")
+    if not isinstance(change, str) or not flow_path(change).exists(): fail("active.json does not reference a valid Matrix change.")
+    return change
+def artifact(change, name): return root() / "changes" / change / "artifacts" / name
+def meaningful(path, headings=()):
+    if not path.exists(): return False
+    text = path.read_text(encoding="utf-8").strip()
+    if len(text) < 40: return False
+    return all(h in text for h in headings)
+def checks(change, phase):
+    base = root() / "changes" / change / "artifacts"
+    if phase == "open":
+        return [("proposal.md has goal, scope, and acceptance", meaningful(base / "proposal.md", ("## Goal", "## Scope", "## Acceptance")))]
+    if phase == "design":
+        return [("design.md has decisions and test seams", meaningful(base / "design.md", ("## Decisions", "## Test seams"))), ("plan.md has ordered implementation steps", meaningful(base / "plan.md", ("## Steps", "## Validation")))]
+    if phase == "build":
+        return [("plan.md exists", meaningful(base / "plan.md", ("## Steps",))), ("verification.md has build evidence", meaningful(base / "verification.md", ("## Build evidence",)))]
+    if phase == "verify":
+        return [("verification.md has test evidence", meaningful(base / "verification.md", ("## Test evidence",))), ("verification.md has review evidence", meaningful(base / "verification.md", ("## Review evidence",)))]
+    return [("verify guard passed before archive", meaningful(base / "verification.md", ("## Test evidence", "## Review evidence")))]
+def guard(change, phase, output=True):
+    results = checks(change, phase)
+    ok = all(result for _, result in results)
+    if output:
+        print(f"Matrix guard: {change} / {phase}")
+        for label, result in results: print(f"[{'PASS' if result else 'FAIL'}] {label}")
+    return ok
+def event(change, event_name, before, after):
+    p = root() / "changes" / change / "events.jsonl"
+    with p.open("a", encoding="utf-8") as handle: handle.write(json.dumps({"at": now(), "event": event_name, "from": before, "to": after}, ensure_ascii=False) + "\n")
+def init(args):
+    change = re.sub(r"[^a-z0-9]+", "-", args.change.lower()).strip("-")
+    if not change: fail("Change id must contain letters or digits.")
+    if active_path().exists(): fail(f"Active Matrix change already exists: {get_active()}.")
+    directory = root() / "changes" / change
+    if directory.exists() or (root() / "archive" / change).exists(): fail(f"Matrix change already exists: {change}.")
+    (directory / "artifacts").mkdir(parents=True)
+    root().mkdir(exist_ok=True); (root() / "archive").mkdir(exist_ok=True)
+    (root() / "config.yaml").write_text("schema: matrix/config/v1\nauto_transition: true\n", encoding="utf-8") if not (root() / "config.yaml").exists() else None
+    gitignore = root() / ".gitignore"
+    ignored = "active.json\ninstallation.json\nchanges/*/run-state.json\nchanges/*/events.jsonl\nchanges/*/artifacts/handoff.md\n"
+    gitignore.write_text(ignored, encoding="utf-8") if not gitignore.exists() else None
+    values = {"schema":"matrix/change/v1", "id":change, "workflow":args.workflow, "status":"active", "phase":"open", "title":args.title, "created_at":now(), "updated_at":now(), "acceptance":"pending", "scope":"pending"}
+    write_flow(directory / "matrix.yaml", values)
+    write_json(directory / "run-state.json", {"schema":"matrix/run/v1", "current_step":"open", "iteration":0, "pending_gate":None, "updated_at":now()})
+    write_json(active_path(), {"change_id":change})
+    event(change, "initialized", None, "open")
+    print(f"Initialized Matrix change '{change}'. Next: {SKILLS['open']}")
+def inspect(_):
+    change = get_active(); flow = parse_flow(flow_path(change)); phase = flow.get("phase", "invalid")
+    if phase not in PHASES: fail(f"Invalid phase '{phase}'.")
+    print(json.dumps({"change_id":change, "workflow":flow.get("workflow"), "phase":phase, "next_skill":SKILLS[phase], "guard_pass":guard(change, phase, False)}, ensure_ascii=False, indent=2))
+def transition(args):
+    change = get_active(); flow = parse_flow(flow_path(change)); before = flow.get("phase")
+    expected = NEXT.get(before)
+    if args.to != expected: fail(f"Illegal transition {before} -> {args.to}; expected {expected or 'archive command' }.")
+    if not guard(change, before): fail("Current phase guard failed; state was not changed.")
+    flow["phase"] = args.to; flow["updated_at"] = now(); write_flow(flow_path(change), flow); event(change, "transition", before, args.to)
+    print(f"Transitioned {change}: {before} -> {args.to}. Next: {SKILLS[args.to]}")
+def archive(_):
+    change = get_active(); flow = parse_flow(flow_path(change))
+    if flow.get("phase") != "archive": fail("Only an archive-phase change can be archived.")
+    if not guard(change, "archive"): fail("Archive guard failed; state was not changed.")
+    flow["status"] = "archived"; flow["updated_at"] = now(); write_flow(flow_path(change), flow); event(change, "archived", "archive", "archived")
+    source = root() / "changes" / change; target = root() / "archive" / change; shutil.move(str(source), str(target)); active_path().unlink()
+    print(f"Archived Matrix change '{change}'.")
+def handoff(_):
+    change = get_active(); flow = parse_flow(flow_path(change)); phase = flow["phase"]
+    p = artifact(change, "handoff.md")
+    p.write_text(f"# Matrix handoff: {change}\n\n- Workflow: {flow['workflow']}\n- Current phase: {phase}\n- Resume with: `{SKILLS[phase]}`\n- Guard passes: {guard(change, phase, False)}\n", encoding="utf-8")
+    print(p)
+def main():
+    parser = argparse.ArgumentParser(); subs = parser.add_subparsers(dest="command", required=True)
+    p = subs.add_parser("init"); p.add_argument("change"); p.add_argument("--workflow", choices=("full","hotfix","tweak"), default="full"); p.add_argument("--title", required=True); p.set_defaults(func=init)
+    subs.add_parser("inspect").set_defaults(func=inspect)
+    p = subs.add_parser("guard"); p.add_argument("phase", choices=PHASES); p.set_defaults(func=lambda a: sys.exit(0 if guard(get_active(), a.phase) else 1))
+    p = subs.add_parser("transition"); p.add_argument("to", choices=PHASES[1:]); p.set_defaults(func=transition)
+    subs.add_parser("archive").set_defaults(func=archive); subs.add_parser("handoff").set_defaults(func=handoff)
+    args = parser.parse_args(); args.func(args)
+if __name__ == "__main__": main()

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

@@ -0,0 +1,26 @@
+---
+name: matrix-archive
+description: Close and archive a verified Matrix change. Use when the active Matrix phase is archive.
+---
+
+# Matrix Archive
+
+This is the **final phase** of the Matrix workflow. After archiving, the workflow is complete.
+
+## Process
+
+1. Read the proposal, plan, and verification evidence
+2. Summarize changed behavior, verification, residual risks, and follow-up work in `artifacts/verification.md` or the project's normal delivery document
+3. Ask for explicit confirmation before committing or archiving
+4. Run the archive command (this also runs the verify guard)
+5. **Workflow complete** — no further phase transitions needed
+
+```powershell
+matrix workflow archive
+```
+
+Do not archive if the verify guard fails.
+
+## After Archive
+
+The change is moved to `.matrix/archive/`. To start a new change, run `$matrix` again.

package/.claude/skills/matrix-archive/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-build/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: matrix-build
+description: Implement the frozen active Matrix plan with test-first vertical slices. Use when the active Matrix phase is build.
+---
+
+# Matrix Build
+
+Read `plan.md`, `design.md`, and repository instructions. Implement only the frozen scope.
+
+## Skills to Use
+
+### Primary: `implement`
+
+Use the `implement` skill to execute the plan. It automatically:
+
+1. Uses `/tdd` at pre-agreed seams for red-green-refactor cycles
+2. Runs typechecking regularly
+3. Runs single test files regularly during development
+4. Runs the full test suite once at the end
+5. Uses `/code-review` to review the work when done
+6. Commits work to the current branch
+
+### On Failure: `diagnosing-bugs`
+
+When encountering crashes, test failures, or build failures:
+
+1. **Stop** — do not propose source code fixes before root cause is located
+2. Load the `diagnosing-bugs` skill
+3. Follow its feedback-loop discipline: build a tight red/pass signal first
+4. Only after root cause is identified, implement the fix through `implement` + `tdd`
+5. Record the diagnosis and fix in `artifacts/verification.md` under `## Build evidence`
+
+### On Merge Conflicts: `resolving-merge-conflicts`
+
+If merge conflicts occur during implementation, use the `resolving-merge-conflicts` skill to resolve them systematically.
+
+## Scope Discipline
+
+If implementation exposes a scope or design change, **stop and return to `$matrix-design`**; do not amend the plan silently.
+
+## Process
+
+1. Load `implement` skill
+2. Implement through vertical slices with TDD
+3. On failure: load `diagnosing-bugs` skill
+4. On merge conflicts: load `resolving-merge-conflicts` skill
+5. Record concrete commands and outcomes under `## Build evidence` in `artifacts/verification.md`
+6. Run the guard
+7. If guard passes, run transition to advance to verify phase
+8. **Then enter `$matrix-verify` to continue the workflow**
+
+```powershell
+matrix workflow guard build
+matrix workflow transition verify
+```

package/.claude/skills/matrix-build/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-claude/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: matrix-claude
+description: Export a frozen Matrix design as a bounded Claude Code task package without changing Matrix workflow state. Use when Codex should design and Claude Code should implement.
+---
+
+# Matrix Claude Handoff
+
+This is an optional Matrix sidecar, not a Matrix phase. It must not call `transition`, `archive`, or write `matrix.yaml`, `run-state.json`, or `events.jsonl`.
+
+## When to Use
+
+Use `$matrix-claude` when:
+- The design phase guard has passed (design is frozen)
+- You want Claude Code (instead of Codex) to implement the design
+- You need a bounded task package with all implementation details
+
+## Preconditions
+
+The exporter performs this read-only check before writing anything:
+
+```powershell
+matrix workflow guard design
+```
+
+If `matrix` is genuinely absent from PATH, use the bundled runtime from the installed root Matrix Skill. Do not fall back when the primary command starts and returns an error.
+
+If the design guard fails, stop and return to `$matrix-design`. The exporter reads the active change's `proposal.md`, `design.md`, and `plan.md`; it does not invent missing facts.
+
+## Export
+
+Treat explicit invocation of `$matrix-claude` as the user's choice of Claude Code as the implementation actor. Generate the package with the deterministic exporter; it refuses a missing design guard and does not alter Matrix state.
+
+```powershell
+# Generic project: only exports a Matrix artifact.
+matrix workflow export --task-id <ID> --target generic
+
+# FnSec: exports its formal task package. Add --apply-fnsec-board only when
+# active.md is NO_ACTIVE_OBJECTIVE; an existing task is never overwritten.
+matrix workflow export --task-id <ID> --target fnsec --apply-fnsec-board
+```
+
+## Task Package Contents
+
+The exported package (`artifacts/claude-task.md`) contains everything Claude Code needs to implement and produce evidence for `$matrix-verify`:
+
+1. **Task ID and execution actor**: Claude Code
+2. **Objective and acceptance criteria** — copied from `proposal.md`
+3. **In-scope and out-of-scope boundaries** — from `proposal.md`
+4. **Frozen design decisions** — from `design.md` (Decisions, Boundaries, Test seams)
+5. **Ordered implementation plan** — from `plan.md` (Steps, Validation)
+6. **Allowed and prohibited files/actions** — to prevent scope creep
+7. **Required commands** — test, lint, typecheck, build commands to run
+8. **Stop conditions** — ambiguity, scope expansion, failing acceptance, design conflict
+9. **Required evidence for verify**:
+   - Changed files list
+   - Commands and their outputs
+   - Test results (pass/fail)
+   - Build evidence
+   - Residual risks
+   - `NEEDS_DECISION` items (if any)
+
+## After Claude Code Completes
+
+When Claude Code returns results, verify that the following evidence is present before proceeding to `$matrix-verify`:
+
+- [ ] `artifacts/verification.md` exists with `## Build evidence` section
+- [ ] Build evidence includes concrete commands and outcomes
+- [ ] All tests in the plan's validation section have been run
+- [ ] Any `NEEDS_DECISION` items have been resolved or documented
+
+If evidence is missing, ask Claude Code to补充 before proceeding.
+
+## Resuming Matrix Workflow
+
+After Claude Code completes and evidence is present:
+
+1. Run build guard to verify evidence:
+   ```powershell
+   matrix workflow guard build
+   ```
+
+2. If guard passes, transition to verify:
+   ```powershell
+   matrix workflow transition verify
+   ```
+
+3. Enter `$matrix-verify` to继续验证流程
+
+If the build guard fails, return to Claude Code to补充 missing evidence.
+
+## Important Notes
+
+- This sidecar does NOT change Matrix phase, workflow, or guard result
+- The Matrix state remains in `design` phase until explicitly transitioned
+- Claude Code must produce evidence that satisfies the build guard conditions
+- After successful transition to verify, the normal verify流程 continues

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Matrix Claude Handoff"
+  short_description: "Export frozen Matrix design as a Claude Code task"
+  default_prompt: "Use $matrix-claude to prepare a Claude Code task package."

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

@@ -0,0 +1,68 @@
+---
+name: matrix-design
+description: Design and freeze the active Matrix change before implementation. Use when the active Matrix phase is design or when build scope requires redesign.
+---
+
+# Matrix Design
+
+Read the active proposal. Write `artifacts/design.md` with `## Decisions`, `## Boundaries`, `## Test seams`, and `## Risks`; write `artifacts/plan.md` with `## Steps`, `## Validation`, and `## Stop conditions`.
+
+## Skills to Use (Recommended Order)
+
+1. **`domain-modeling`** — First, establish or refine the domain vocabulary. Update `CONTEXT.md` with any new terms from the proposal. This ensures all subsequent design work uses consistent language.
+
+2. **`research`** — If the design requires investigating external APIs, documentation, or specifications, spawn a background research agent. It will investigate primary sources and write findings to a Markdown file.
+
+3. **`wayfinder`** — For complex codebases, use this to explore and understand existing module structure, seams, and dependencies before making design decisions.
+
+4. **`prototype`** — When a design question needs empirical validation (e.g., "does this state model feel right?" or "what should this UI look like?"), build a throwaway prototype. Two modes:
+   - **Logic prototype**: interactive terminal app to test state machines
+   - **UI prototype**: multiple UI variations on a single route
+
+5. **`codebase-design`** — Finally, define module boundaries, interfaces, and test seams. Use its "design-it-twice" pattern to explore alternative approaches before committing.
+
+## Process
+
+1. Start with `domain-modeling` to ground the vocabulary
+2. Use `research` for external dependencies (runs in background)
+3. Use `wayfinder` to explore complex existing code
+4. Use `prototype` to validate key design questions
+5. Use `codebase-design` to finalize module boundaries
+6. Confirm material architecture choices with the user before freezing
+7. Run the guard
+8. If guard passes, ask the user to choose implementation method:
+
+```powershell
+matrix workflow guard design
+```
+
+## Implementation Decision Point
+
+After the design guard passes, the user chooses:
+
+### Option A: Continue with Codex (default)
+
+Run transition and enter `$matrix-build`:
+
+```powershell
+matrix workflow transition build
+```
+
+Then enter `$matrix-build` to implement directly in this session.
+
+### Option B: Use Claude Code for implementation
+
+Run `$matrix-claude` to export the frozen design as a bounded task package. This:
+- Does NOT change Matrix phase or state
+- Creates `artifacts/claude-task.md` with all implementation details
+- Includes acceptance criteria, test seams, and required commands
+
+After Claude Code completes and returns results, run the transition and enter `$matrix-verify`:
+
+```powershell
+matrix workflow transition build
+matrix workflow guard build
+matrix workflow transition verify
+```
+
+Then enter `$matrix-verify` to verify the implementation.

package/.claude/skills/matrix-design/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-hotfix/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: matrix-hotfix
+description: Run a constrained Matrix workflow for a reproducible small bug. Use for a bug fix that has no material architecture, API, schema, or multi-module coordination impact.
+---
+
+# Matrix Hotfix
+
+Start through `$matrix` with workflow `hotfix`, then use `diagnosing-bugs` to establish a red-capable feedback loop before changing code. Write the compact proposal, then continue through Matrix gates. If the bug requires architecture change, a new public API, schema work, or broad coordination, pause and ask whether to upgrade to full `$matrix`.

package/.claude/skills/matrix-hotfix/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-open/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: matrix-open
+description: Open or resume the Matrix open phase by clarifying a development request into an evidence-backed proposal. Use after $matrix initializes a change or when the active Matrix phase is open.
+---
+
+# Matrix Open
+
+Read the active Matrix change with `matrix workflow inspect`. Produce `artifacts/proposal.md` containing exactly these substantive sections: `## Goal`, `## Scope`, `## Non-goals`, `## Acceptance`, and `## Risks`.
+
+## Skills to Use
+
+For a **full workflow**, use `grill-with-docs` to resolve ambiguity before writing the proposal. This skill automatically:
+
+1. Runs a `/grilling` session to stress-test the plan through relentless Q&A
+2. Invokes `/domain-modeling` to establish shared vocabulary
+3. Creates or updates `CONTEXT.md` with domain terms
+4. Creates ADRs (Architecture Decision Records) for significant decisions
+
+For **hotfix/tweak**, use `grilling` directly (without docs) — keep it concise but preserve acceptance criteria.
+
+## Process
+
+1. Run `grill-with-docs` (or `grilling` for hotfix/tweak)
+2. Write `proposal.md` with all required sections
+3. Ask the user to confirm when scope or risk is material
+4. Run the guard
+5. If guard passes, run transition to advance to design phase
+6. **Then enter `$matrix-design` to continue the workflow**
+
+```powershell
+matrix workflow guard open
+matrix workflow transition design
+```

package/.claude/skills/matrix-open/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."