@rosenfan/matrix 0.1.3 → 0.1.5

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

@@ -1,44 +1,47 @@
----
-name: matrix-build
-description: Implement the frozen active Matrix plan with test-first vertical slices. Use when the active Matrix phase is build.
----
-
+---
+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
 
-Run `matrix workflow inspect` and implement only its approved Contract. Full and `legacy-full` read proposal/design/plan. `lightweight` reads the approved compact proposal and must not backfill Design artifacts.
+Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` and implement only its approved Contract. Full and `legacy-full` read proposal/design/plan. `lightweight` reads the approved compact proposal and must not backfill Design artifacts.
 
 Write build evidence and user-facing explanations in `artifact_language`; preserve any Runtime-required English heading tokens.
-
-## Prim
-
-Use Matrix's own implementation and test discipline.
-
-## Arch
-
-- invoke `tdd` when the change modifies observable behavior at a testable seam;
-- invoke `diagnosing-bugs` only when an actual failure exists and root cause is not established;
-- invoke `resolving-merge-conflicts` only for an in-progress merge or rebase conflict.
-
-Announce each triggered capability and reason. No companion may commit, review, transition, archive, or broaden scope. A correctly installed capability gets at most one Matrix-owned fallback for that same capability; record the Skill, failure, fallback, and evidence. Installation-integrity failure stops the phase.
-
-## Scope Discipline
-
+
+## Prim
+
+Use Matrix's own implementation and test discipline.
+
+## Arch
+
+- invoke `tdd` when the change modifies observable behavior at a testable seam;
+- invoke `diagnosing-bugs` only when an actual failure exists and root cause is not established;
+- invoke `writing-for-agents` when the approved Contract changes agent-facing instructions;
+- invoke `wizard` only to generate and statically verify human-run shell steps required by the Contract; never execute the wizard end-to-end or collect secrets.
+
+Resolve an in-progress merge/rebase through Matrix-owned conflict handling. Do not invoke raw `resolving-merge-conflicts`, because it can stage, continue, and commit outside Matrix lifecycle ownership. Never invoke `implement` inside an active Change.
+
+Announce each triggered capability and reason. No companion may commit, review, transition, archive, or broaden scope. A correctly installed capability gets at most one Matrix-owned fallback for that same capability; record the Skill, failure, fallback, and evidence. Installation-integrity failure stops the phase.
+
+## Scope Discipline
+
 If implementation exposes a scope or design change, **stop and run**; a lightweight change is upgraded to full by this Return:
-
-```powershell
-matrix workflow return design --reason design-gap
-```
-
-Then enter `$matrix-design`; do not amend the plan silently. The Runtime preserves old verification evidence in revision history and requires fresh evidence after the redesigned plan returns to Build.
-
-## Process
-
-1. Implement the approved plan in bounded vertical slices.
-2. Use only triggered Arch capabilities.
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs return design --reason design-gap
+```
+
+Then enter `$matrix-design`; do not amend the plan silently. The Runtime preserves old verification evidence in revision history and requires fresh evidence after the redesigned plan returns to Build.
+
+## Process
+
+1. Implement the approved plan in bounded vertical slices.
+2. Use only triggered Arch capabilities.
 3. Record common facts under `## Build evidence`. Hotfix also requires `## Reproduction evidence` and `## Root cause`; tweak also requires `## Scope evidence`.
-4. Run the guard and transition, then enter `$matrix-verify`.
-
-```powershell
-matrix workflow guard build
-matrix workflow transition verify
-```
+4. Run the guard and transition, then enter `$matrix-verify`.
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
+```

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

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

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

@@ -1,98 +1,98 @@
----
-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.
----
-
+---
+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` or `events.jsonl`. It supports only a matching full or legacy-full three-artifact Contract; new lightweight hotfix/tweak changes are intentionally unsupported.
 
 Use `artifact_language` from inspect for human-readable handoff text while retaining the stable machine-readable headings and metadata keys.
-
-## When to Use
-
-Use `$matrix-claude` when:
-- The active change is in Build and the Design -> Build transition has approved the contract
-- 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 build
-```
-
-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 build guard reports `CONTRACT_CHANGED` or `CONTRACT_UNAPPROVED`, return to `$matrix-design` and approve a new contract through Build. The exporter reads the approved bytes of `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 non-matching approved contract 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, execution actor, and approved contract hash**: Claude Code and the exact approved snapshot
-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 `build` phase; export itself does not advance it
-- Claude Code must produce evidence that satisfies the build guard conditions
-- After successful transition to verify, the normal verify流程 continues
+
+## When to Use
+
+Use `$matrix-claude` when:
+- The active change is in Build and the Design -> Build transition has approved the contract
+- 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
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+```
+
+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 build guard reports `CONTRACT_CHANGED` or `CONTRACT_UNAPPROVED`, return to `$matrix-design` and approve a new contract through Build. The exporter reads the approved bytes of `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 non-matching approved contract and does not alter Matrix state.
+
+```powershell
+# Generic project: only exports a Matrix artifact.
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs 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.
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs 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, execution actor, and approved contract hash**: Claude Code and the exact approved snapshot
+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
+   node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+   ```
+
+2. If guard passes, transition to verify:
+   ```powershell
+   node <matrix-skill-directory>/scripts/matrix-runtime.mjs 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 `build` phase; export itself does not advance it
+- Claude Code must produce evidence that satisfies the build guard conditions
+- After successful transition to verify, the normal verify流程 continues

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

@@ -1,4 +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."
+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 → assets}/skills/matrix-design/SKILL.md

@@ -1,71 +1,73 @@
----
-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.
----
-
+---
+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
 
 Design is used by `full` and resumable legacy shortcut changes only. A new lightweight hotfix/tweak moves directly from Open to Build and must not create Design artifacts merely to satisfy the full guard.
 
-Use `artifact_language` from `matrix workflow inspect` for all design and plan prose. Keep Runtime-required English heading tokens unchanged.
-
-Run `matrix workflow inspect`, read the active proposal and frozen `orchestration`, then write `artifacts/design.md` with `## Decisions`, `## Boundaries`, `## Test seams`, and `## Risks`; write `artifacts/plan.md` with `## Steps`, `## Validation`, and `## Stop conditions`.
-
-## Prim
-
-Use Matrix's own capability to investigate the repository and design the change.
-
-## Arch
-
-Invoke only capabilities whose task-fact trigger is proven:
-
-- `domain-modeling` for unclear vocabulary, invariants, or architectural decisions;
-- `research` when required external facts cannot be established from the repository;
-- `wayfinder` when module ownership or dependency seams are unknown;
-- `prototype` when a material design decision needs disposable empirical evidence;
-- `codebase-design` when a deep-module, interface, or test-seam decision remains.
-
-Order follows actual dependencies; never run a fixed companion sequence. Announce each invocation and reason. A correctly installed capability gets at most one same-capability Matrix fallback; installation-integrity failure stops the phase.
-
-Long-lived domain, ADR, or research artifacts follow repository conventions, and material conclusions must be synchronized into the canonical design or plan. Prototypes default to an OS temporary directory unless the approved design promotes a project path. Companion output cannot own Matrix state or create a competing plan.
-
-## Process
-
-1. Establish repository facts and resolve only triggered design questions.
-2. Write and synchronize the canonical Matrix design and plan.
-3. Confirm material architecture choices with the user before freezing.
-4. Run the guard, then choose the implementation actor.
-
-```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
-
-First approve the frozen contract by transitioning to Build, then run `$matrix-claude` to export a bounded task package. This:
-- Does not change the Build phase or state beyond the preceding transition
-- 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 Build guard and enter `$matrix-verify`:
-
-```powershell
-matrix workflow guard build
-matrix workflow transition verify
-```
-
-Then enter `$matrix-verify` to verify the implementation.
+Use `artifact_language` from `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` for all design and plan prose. Keep Runtime-required English heading tokens unchanged.
+
+Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect`, read the active proposal and frozen `orchestration`, then write `artifacts/design.md` with `## Decisions`, `## Boundaries`, `## Test seams`, and `## Risks`; write `artifacts/plan.md` with `## Steps`, `## Validation`, and `## Stop conditions`.
+
+## Prim
+
+Use Matrix's own capability to investigate the repository and design the change.
+
+## Arch
+
+Invoke only capabilities whose task-fact trigger is proven:
+
+- `domain-modeling` for unclear vocabulary, invariants, or architectural decisions;
+- `research` when required external facts cannot be established from the repository;
+- `prototype` when a material design decision needs disposable empirical evidence;
+- `codebase-design` when a deep-module, interface, or test-seam decision remains;
+- `writing-for-agents` when the Contract creates or changes Skills, `AGENTS.md`, `CLAUDE.md`, or documents reached through agent pointers.
+
+Order follows actual dependencies; never run a fixed companion sequence. Announce each invocation and reason. A correctly installed capability gets at most one same-capability Matrix fallback; installation-integrity failure stops the phase.
+
+Long-lived domain, ADR, or research artifacts follow repository conventions, and material conclusions must be synchronized into the canonical design or plan. Prototypes default to an OS temporary directory unless the approved design promotes a project path. Companion output cannot own Matrix state or create a competing plan.
+
+`wayfinder` and `improve-codebase-architecture` are explicit handoffs outside the active Design. Recommend one only when its purpose fits, then let the user invoke it; a selected result may enter a separate governed Change.
+
+## Process
+
+1. Establish repository facts and resolve only triggered design questions.
+2. Write and synchronize the canonical Matrix design and plan.
+3. Confirm material architecture choices with the user before freezing.
+4. Run the guard, then choose the implementation actor.
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs 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
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build
+```
+
+Then enter `$matrix-build` to implement directly in this session.
+
+### Option B: Use Claude Code for implementation
+
+First approve the frozen contract by transitioning to Build, then run `$matrix-claude` to export a bounded task package. This:
+- Does not change the Build phase or state beyond the preceding transition
+- 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 Build guard and enter `$matrix-verify`:
+
+```powershell
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
+```
+
+Then enter `$matrix-verify` to verify the implementation.

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

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

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

@@ -1,8 +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
-
+---
+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`. It uses the shared lightweight lifecycle `open → build → verify → archive`; there is no separate hotfix state machine. Before Build, record expected/actual behavior and a reproducible failure signal, present the compact Contract, and wait for confirmation. Build records reproduction and root-cause evidence; Verify records regression evidence. If the bug requires architecture, public API, schema, or broad coordination, use controlled Return to upgrade the change to full.

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

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

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

@@ -1,11 +1,11 @@
----
-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.
----
-
+---
+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
 
-Run `matrix workflow inspect` and follow its `profile` and `evidence_policy`.
+Run `node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect` and follow its `profile` and `evidence_policy`.
 
 Use its `artifact_language` for all proposal prose. Keep the required English heading tokens exactly as specified for Runtime guards; only the text beneath them is localized.
 
@@ -13,28 +13,30 @@ Use its `artifact_language` for all proposal prose. Keep the required English he
 - **lightweight**: produce the complete compact Contract before editing project implementation. Include `## Goal`, `## Scope`, `## Non-goals`, `## Approach`, `## Acceptance`, `## Validation`, `## Risks`, and `## Upgrade conditions`.
 - **hotfix evidence**: also include `## Expected behavior`, `## Actual behavior`, and `## Reproduction`.
 - **tweak evidence**: also include `## Current behavior`, `## Preserved behavior`, and `## Diff boundary`.
-
-## Prim
-
-Use Matrix's own capability to clarify the request and write the proposal.
-
-## Arch
-
-Invoke `grilling` only when material ambiguity remains or the user asks to stress-test the request. Invoke `domain-modeling` only when domain vocabulary, invariants, or an architectural decision is unclear. Announce the capability and reason before invoking it; selecting Arch already authorizes triggered capabilities.
-
-Companion output is evidence for the Matrix proposal. It must not create another workflow, proposal, confirmation state, or phase transition. If a correctly installed capability fails, perform at most one Matrix-owned fallback for that same capability and record the failure and evidence. Installation-integrity failures require `matrix init --with-mattpocock` and are not eligible for fallback.
-
-## Process
-
-1. Resolve only ambiguities required by the active workflow.
-2. Write the canonical proposal and synchronize material companion conclusions into it.
+
+## Prim
+
+Use Matrix's own capability to clarify the request and write the proposal.
+
+## Arch
+
+Invoke `grilling` only when material ambiguity remains or the user asks to stress-test the request. Invoke `domain-modeling` only when domain vocabulary, invariants, or an architectural decision is unclear. Announce the capability and reason before invoking it; selecting Arch already authorizes triggered capabilities.
+
+If progress is blocked by facts or decisions owned by another person, explain why `to-questionnaire` fits and ask the user to invoke it. Do not invoke the wrapper yourself.
+
+Companion output is evidence for the Matrix proposal. It must not create another workflow, proposal, confirmation state, or phase transition. If a correctly installed capability fails, perform at most one Matrix-owned fallback for that same capability and record the failure and evidence. Installation-integrity failures require `matrix init --with-mattpocock` and are not eligible for fallback.
+
+## Process
+
+1. Resolve only ambiguities required by the active workflow.
+2. Write the canonical proposal and synchronize material companion conclusions into it.
 3. For full, ask for confirmation when scope or risk is material, then enter Design.
 4. For lightweight, always present the compact Contract and wait for explicit confirmation before entering Build.
 
 ```powershell
-matrix workflow guard open
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard open
 # full
-matrix workflow transition design
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition design
 # hotfix/tweak, only after explicit confirmation
-matrix workflow transition build --confirmed
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition build --confirmed
 ```

package/assets/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."

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

@@ -1,15 +1,15 @@
----
-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
-matrix workflow doctor
-```
-
+---
+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
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs inspect
+node <matrix-skill-directory>/scripts/matrix-runtime.mjs doctor
+```
+
 Report the returned change id, workflow, `profile`, `evidence_policy`, frozen `orchestration`, phase, guard result, `next_skill`, Workflow health, unfinished transactions, available strategies, and exact recovery commands. If Arch integrity fails, identify the affected platform/Skill facts and report `matrix init --with-mattpocock`; do not reinterpret the change as Prim. Both commands are read-only. Do not infer status from conversation history, run `--repair`, or modify state. If the guard is failing, name the missing evidence and direct the user to the current phase Skill.

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

@@ -1,4 +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."
+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 → assets}/skills/matrix-tweak/SKILL.md

@@ -1,8 +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
-
+---
+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`. It uses the shared lightweight lifecycle `open → build → verify → archive`; there is no separate tweak state machine or Design phase. Before editing implementation, define current/preserved behavior, the diff boundary, acceptance, and validation in the compact proposal, present it, and wait for confirmation. Build and Verify must prove scope and diff alignment. Use controlled Return to upgrade to full when the change crosses module, API, schema, or architecture boundaries.

package/assets/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."