@uniqbit/mate-core 0.18.4 → 1.0.0-canary.0

package/src/templates/mate-skills/claude/mate-show-me/SKILL.md

@@ -21,7 +21,7 @@ Explain the current topic visually in a browser-rendered Mate report. Skip the p
 
 ## Subject
 
-- With no argument, explain the current topic or the applied change, as described below.
+- With no argument, review the applied change when the user asks what a change did, or when the conversation is about work in the Working Repository and `git diff` there is not empty; otherwise explain the current topic. When both readings fit, review the change.
 - With an argument naming a spec capability (`$ARGUMENTS`, for example `acme-capability`), explain that capability instead: read its canonical spec under `openspec/specs/` in the Companion Repository and report its purpose, its requirements, and the flow or structure they establish. Name the capability in the report `metadata`, include a `diagram` section, and omit the `diff` section.
 - When the named capability has no canonical spec, say so, suggest close capability names from `openspec/specs/`, and write nothing: no report, no file.
 
@@ -89,6 +89,18 @@ src/
 
 - Show a whole block in the report when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape.
 
+## Reviewing An Applied Change
+
+- Read the change scope before drawing it, and draw the state after the change, not the one it replaced.
+- Decide the diagram by what the change did. When it alters control flow or behaviour - new or changed branches, calls, ordering, return paths, or error handling - the first diagram is a `flowchart TD` of the resulting flow, limited to the part the change touches. A rename, a move, or an extraction that keeps behaviour identical gets one structure diagram and no flowchart.
+- Mark new steps `added` and modified steps `changed`. Removed steps normally do not appear, since the diff shows what was there before; when removing a step is the point of the change, keep it as a `removed` node.
+- When most of the drawn flow is new, marking every step carries no signal: mark at most the entry step `added`, and say in the caption that the flow is new.
+- Keep a flowchart to about twelve nodes. Collapse a run of steps the change did not touch into one node instead of splitting the flow across several diagrams.
+- When the change also alters structure - types, modules, or ownership - follow the flowchart with a structure diagram such as a `classDiagram`. A report carries at most two `diagram` sections, flowchart first, each with its own `caption`.
+- Take the diff from `git diff` in the Working Repository. Keep only repository-relative paths in the patch, default to the working tree, and ask the user when their intent is a committed range instead.
+- Run `git diff --numstat` over the same scope before choosing between the full diff and a curated report. Every excerpt is whole hunks copied unchanged from that diff.
+- When the inspected scope has no changes, say so and omit the `diff` section. Never invent a patch.
+
 ## Browser Delivery
 
 The report is mandatory. Prefer `mate report --input <temporary-json-file>` without `--json` so the CLI reads the complete document reliably and renders self-contained HTML. The CLI chooses the surface: inside a Studio terminal it hosts the report in Studio, elsewhere it opens it in the default browser. The CLI also supports `mate report --input -` when JSON is piped to stdin; if stdin delivery reports empty or truncated JSON, switch to a temporary JSON file rather than retrying the same transport. If validation fails, fix the report document and retry; do not fall back to an inline explanation or JSON-only delivery.
@@ -105,19 +117,33 @@ Build a JSON document that conforms to the `mate-create-report` contract, then h
 A report assembled by this skill carries:
 
 - `metadata` naming the subject and a neutral repository label, never a local path
-- one `diagram` section for the structure or flow at issue, even when the visual is small
+- `diagram` sections, even when the visual is small: one for a topic or capability report, one or two for a change review as Reviewing An Applied Change describes
 - use a `mermaid` payload for runtime control flow, call trees, data flow, or component relationships; use `text` only when a sketch or pseudocode is clearer
-- one `diff` section carrying the unified diff, when there is something to diff
-- a short `text` section next to each visual, saying what the reader should notice
+- what changed, when there is something to diff: the complete unified diff in one `diff` section for a small change or when the user asks for it, otherwise a curated overview and excerpts as described in Curating A Large Diff
+- a short Markdown `caption` on each `diagram` and `diff` section, saying what the reader should notice; do not repeat it in a separate `text` section
+- a `text` section only for explanation that belongs to no single visual, with `"format": "markdown"` when it uses Markdown
+
+A `diagram` section carries exactly one payload: `mermaid` for diagram source the report draws as a picture, or `text` for a monospace ASCII sketch or pseudocode block. A `diff` section carries a unified `patch` string. Both take an optional `caption`, rendered beneath the visual with the Markdown subset described in `mate-create-report`.
+
+```json
+{
+  "id": "flow",
+  "title": "Saving a document",
+  "type": "diagram",
+  "mermaid": "flowchart TD\n  save[save] --> check{unchanged?}\n  check -->|yes| cached[return cached]\n  check -->|no| write[write content]\n  class check,cached added\n  class write changed",
+  "caption": "Unchanged content now **returns early** instead of being rewritten."
+}
+```
 
-A `diagram` section carries exactly one payload: `mermaid` for diagram source the report draws as a picture, or `text` for a monospace ASCII sketch or pseudocode block. A `diff` section carries a unified `patch` string.
+When a change also alters structure, the second `diagram` section is a structure diagram:
 
 ```json
 {
   "id": "structure",
   "title": "Report rendering",
   "type": "diagram",
-  "mermaid": "classDiagram\n  Renderer --> Highlight : uses"
+  "mermaid": "classDiagram\n  Renderer --> Highlight : uses",
+  "caption": "`Renderer` is the only caller of `Highlight`."
 }
 ```
 
@@ -126,23 +152,55 @@ A `diagram` section carries exactly one payload: `mermaid` for diagram source th
   "id": "changes",
   "title": "What changed",
   "type": "diff",
-  "patch": "diff --git a/src/acme.ts b/src/acme.ts\n..."
+  "patch": "diff --git a/src/acme.ts b/src/acme.ts\n...",
+  "caption": "Validation moves **before** rendering."
 }
 ```
 
 If the document fails contract validation, report the diagnostic and correct the document. Do not fall back to hand-written HTML.
 
+## Curating A Large Diff
+
+The reader already has the full diff in git; the report earns its place by choosing what is worth looking at.
+
+- Measure first. Run `git diff --numstat` over the inspected scope and add the added and removed lines of every file; binary files count as zero.
+- At or under 150 changed lines, or whenever the user asks for the full diff, include the complete unified diff in one `diff` section, whatever its size.
+- Above 150 changed lines, curate:
+  - one `table` section with id `changed-files` and the columns File | Added | Removed | Role, listing every changed file in the scope, including tests, snapshots, and generated files. Added and Removed are numbers; Role is a short phrase such as "contract: optional fields" or "snapshot hashes".
+  - one to four focused `diff` sections with ids such as `diff-<topic>`, each making one point and carrying a `caption` that says why its hunks matter. Keep each section under about 60 lines.
+  - a `summary` metric labelled "Changed lines shown" with the value `<shown> of <total>`, where shown counts the `+` and `-` lines in the excerpts and total is the `--numstat` sum.
+- Excerpts stay verbatim. A focused patch is the file's `diff --git`, `---`, and `+++` header followed by one or more whole hunks copied unchanged from `git diff`. Never alter, merge, or invent hunk lines, and never elide lines with `...`. Two hunks of the same file may share a section when they make the same point.
+- Leave supporting files out of the excerpts: tests (`*.test.*`, `*.spec.*`, `__tests__/`), snapshots (`__snapshots__/`, `*.snap`), lockfiles (`bun.lock`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`), generated files (`*.generated.*`), and formatting-only hunks. They still appear in the `changed-files` table. Excerpt them when the change is about them or the user asks for them.
+
+```json
+{
+  "id": "changed-files",
+  "title": "Changed files",
+  "type": "table",
+  "columns": ["File", "Added", "Removed", "Role"],
+  "rows": [
+    ["src/report/contract.ts", 48, 6, "contract: optional fields"],
+    ["src/report/renderer.test.ts", 210, 95, "tests"]
+  ]
+}
+```
+
+```json
+{
+  "id": "diff-contract",
+  "title": "Contract gains optional fields",
+  "type": "diff",
+  "patch": "diff --git a/src/report/contract.ts b/src/report/contract.ts\n--- a/src/report/contract.ts\n+++ b/src/report/contract.ts\n@@ -40,6 +40,8 @@\n...",
+  "caption": "New fields are **optional**, so existing documents still validate."
+}
+```
+
 ## Mermaid Authoring Rules
 
 - Use Mermaid whenever the user asks for a diagram or the subject has meaningful control flow, sequencing, lifecycle, or relationships. A `text` payload is a deliberate fallback, not the default for runtime flows.
-- Pick the diagram type that matches the question: `classDiagram` for structure, `sequenceDiagram` for interaction between components, `stateDiagram-v2` for lifecycles, `flowchart TD` for control flow and call trees.
-- Keep labels short enough to read at report width. A label that needs a sentence belongs in the neighbouring `text` section.
+- Pick the diagram type that matches the question: `classDiagram` for structure, `sequenceDiagram` for interaction between components, `stateDiagram-v2` for lifecycles, `flowchart TD` for control flow and call trees. For a change review, Reviewing An Applied Change decides the diagram instead.
+- Keep labels short enough to read at report width. A label that needs a sentence belongs in the section's `caption`.
 - Do not use ELK-only layouts or math labels. The report loads the single-file mermaid build from a CDN, which does not carry those chunks.
-- Pair each Mermaid visual with a short neighbouring `text` section that calls out the ownership boundary or invariant the reader should notice.
+- To mark nodes, apply the report's theme classes `added`, `changed`, or `removed` with `class a,b added` or `a:::added`. They follow the reader's colour scheme. Never fix a colour with `classDef`, `style`, or `linkStyle`: a fill picked for a white page hides the labels in dark mode, so the dark copy drops those lines.
+- Give each Mermaid visual a short `caption` that calls out the ownership boundary or invariant the reader should notice.
 - Prefer the `text` payload for pseudocode, shallow file trees, or cases where a picture would genuinely obscure the point.
-
-## Reviewing An Applied Change
-
-- Read the change scope before drawing it, then diagram the structure or flow the change establishes - not the structure it replaced.
-- Take the diff from `git diff` in the Working Repository. Keep only repository-relative paths in the patch, default to the working tree, and ask the user when their intent is a committed range instead.
-- When the inspected scope has no changes, say so and omit the `diff` section. Never invent a patch.

package/src/templates/mate-skills/claude/mate-simplify-code/SKILL.md

@@ -19,21 +19,12 @@ Simplify code by reducing complexity while preserving exact behavior. The goal i
 
 - Inspect the requested scope and its callers, callees, and tests before editing. Use the available code-graph tools before broad source scans.
 - Keep the refactor limited to the requested scope; do not make unrelated cleanup changes.
-- Run the relevant tests after each simplification. Do not modify tests merely to make a refactor pass.
+- Do not modify tests merely to make a refactor pass.
 - Format touched files with the project's own formatter — detect it first (see Principle 2); never run a formatter the project has not adopted.
 - Run `mate cap index --tokensave` after code changes.
 - Never commit, push, or create a pull request unless the user explicitly asks.
 
-## When to Use
-
-- After a feature is working and tests pass, but the implementation feels heavier than it needs to be
-- During code review when readability or complexity issues are flagged
-- When you encounter deeply nested logic, long functions, or unclear names
-- When refactoring code written under time pressure
-- When consolidating related logic scattered across files
-- After merging changes that introduced duplication or inconsistency
-
-**When NOT to use:**
+## When NOT to Use
 
 - Code is already clean and readable — don't simplify for the sake of it
 - You don't understand what the code does yet — comprehend before you simplify
@@ -75,25 +66,29 @@ Simplification that breaks project consistency is not simplification — it's ch
 
 Detect the formatter before formatting anything — first match wins:
 
-| Signal in the repo                                                                | Formatter to run                                                                 |
-| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `format` / `fmt` script in `package.json`, `Makefile`, `justfile`, `Taskfile.yml` | Run that script — it encodes the project's intent and needs no further detection |
-| `biome.json` / `biome.jsonc`                                                      | `biome format --write`                                                           |
-| `.oxfmtrc.json`, or `oxfmt` in devDependencies                                    | `oxfmt`                                                                          |
-| `dprint.json` / `.dprint.jsonc`                                                   | `dprint fmt`                                                                     |
-| `.prettierrc*`, `prettier.config.*`, or a `prettier` key in `package.json`        | `prettier --write`                                                               |
-| `rustfmt.toml`, or any Cargo crate                                                | `cargo fmt`                                                                      |
-| `[tool.ruff]` in `pyproject.toml`                                                 | `ruff format`                                                                    |
-| `[tool.black]` in `pyproject.toml`                                                | `black`                                                                          |
-| Go module                                                                         | `gofmt -w` (or `goimports -w` if already used)                                   |
-| Only `.editorconfig`, or no signal at all                                         | Do not format — match the surrounding style by hand                              |
+| Signal in the repo                                                                | Formatter to run                                                    |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `format` / `fmt` script in `package.json`, `Makefile`, `justfile`, `Taskfile.yml` | That script decides — narrow it to your files (see the rules below) |
+| `biome.json` / `biome.jsonc`                                                      | `biome format --write`                                              |
+| `.oxfmtrc.json`, or `oxfmt` in devDependencies                                    | `oxfmt`                                                             |
+| `dprint.json` / `.dprint.jsonc`                                                   | `dprint fmt`                                                        |
+| `.prettierrc*`, `prettier.config.*`, or a `prettier` key in `package.json`        | `prettier --write`                                                  |
+| `rustfmt.toml`, or any Cargo crate                                                | `cargo fmt`                                                         |
+| `[tool.ruff]` in `pyproject.toml`                                                 | `ruff format`                                                       |
+| `[tool.black]` in `pyproject.toml`                                                | `black`                                                             |
+| Go module                                                                         | `gofmt -w` (or `goimports -w` if already used)                      |
+| Only `.editorconfig`, or no signal at all                                         | Do not format — match the surrounding style by hand                 |
 
 Rules:
 
 - Invoke the project's pinned local binary through its package manager or runner, inferred from the lockfile (`bun`, `pnpm`, `yarn`, `npm`) — never a global install and never an `npx`-downloaded version, which may differ from the one that formatted the committed code.
+- **A script decides the tool, not the paths.** Read the script to learn the tool, its config, and its flags, then run that tool on your files only. Scripts usually hard-code their own paths, so passing a file to them adds it to the run instead of narrowing it. If the script chains several steps, run only its formatting steps, each narrowed to your files — a lint `--fix` step is not formatting.
+- In a monorepo, use the script from the nearest package manifest above the files that defines one — often only the repository root does.
+- If a `format` script cannot be narrowed, do not run it: it rewrites files outside the scope, and reverting those with `git checkout` would also discard any uncommitted work in them. Match the surrounding style by hand and report it.
 - If several formatters are configured, the `format` script decides. If there is no script and the signals conflict, ask which is canonical instead of picking one.
 - Format only the files you changed. A repo-wide format pass is a separate change with its own diff.
-- If the formatter rewrites far more than the lines you touched, its config disagrees with the committed code. Stop, revert the formatting, and report it — do not fold that drift into a simplification change.
+- Before running any formatter, save a copy of each file you are about to format to a temporary directory (`$TMPDIR`) — never inside the repository, where a backup can be committed. Git cannot tell a formatter's hunks apart from uncommitted work already in the file; the copy can.
+- If the formatter rewrites far more than the lines you touched, its config disagrees with the committed code. Stop, restore the copies you saved — never `git checkout` the file, which would also discard uncommitted work — match the surrounding style by hand, and report it. Do not fold that drift into a simplification change.
 
 ### 3. Prefer Clarity Over Cleverness
 
@@ -137,6 +132,7 @@ Simplification has a failure mode: over-simplification. Watch for these traps:
 - **Combining unrelated logic** — two simple functions merged into one complex function is not simpler
 - **Removing "unnecessary" abstraction** — some abstractions exist for extensibility or testability, not complexity
 - **Optimizing for line count** — fewer lines is not the goal; easier comprehension is
+- **Stripping return type annotations** — leave them; exported ones are contracts, and inference can silently widen the type
 
 ### 5. Scope to What Changed
 
@@ -160,6 +156,16 @@ BEFORE SIMPLIFYING, ANSWER:
 
 If you can't answer these, you're not ready to simplify. Read more context first.
 
+**When no test exercises the scope**, the safety net that Step 3 relies on is missing. Pick one, and report the missing coverage either way:
+
+- Write characterization tests first. They pin the current behavior, including its quirks, and are never edited later to fit the refactor.
+- In a type-checked project, restrict the pass to changes the type checker verifies on its own, and leave every other candidate in the report:
+  - Rename locals, or remove unused locals whose initializer has no side effects. A call, `await`, `new`, or getter in the initializer can have one, and removing it changes behavior the checker cannot see.
+  - Skip a rename when the local also supplies an object key (`{ user }`), a JSX prop, or a string lookup — renaming it changes data, and the checker cannot see that.
+  - Unexport a symbol only after it clears every box of the pre-removal checklist. The checker catches a broken importer, but not a framework or config that resolves the symbol by name.
+
+Without a type checker, only characterization tests remain.
+
 ### Step 2: Identify Simplification Opportunities
 
 #### Step 2a: Mechanical pre-scan (required)
@@ -181,7 +187,8 @@ PRE-SCAN THE REQUESTED SCOPE:
 
 Do not skip the pre-scan because the file "looks clean". Judgment applies to the
 candidates it produces, not to whether to produce them. Report candidates you
-deliberately leave alone, with the reason.
+deliberately leave alone, with the reason. Every "report it" in this skill means an entry
+in the final [Report](#report), under its bucket.
 
 **A pre-scan hit is a question, not a verdict.** These tools find symbols nothing
 _imports_; they cannot see symbols resolved by name — framework exports, reflective
@@ -292,11 +299,6 @@ design decision rather than a behavior-preserving edit. Both collide with Princi
 Describe the change and the affected files, then stop and let the user decide — the
 same treatment the prop-drilling case gets under React guidance.
 
-**When the pre-scan flags a symbol you cannot prove is unreferenced, leave it and say
-so.** An export you were unsure about and kept costs a line of explanation. An export
-you removed on a guess costs a production incident. Unverifiable candidates are
-reported, not acted on.
-
 ```
 BEFORE REMOVING ANY export, ALL MUST HOLD:
 [ ] Not framework-resolved (checked against the list above)
@@ -310,7 +312,7 @@ Any box unchecked → report the candidate, do not touch it.
 
 ### Step 3: Apply Changes Incrementally
 
-Make one simplification at a time. Run tests after each change. **Submit refactoring changes separately from feature or bug fix changes.** A PR that refactors and adds a feature is two PRs — split them.
+Make one simplification at a time and run tests after each change, so a failure points to the change that caused it. **Submit refactoring changes separately from feature or bug fix changes.** A PR that refactors and adds a feature is two PRs — split them.
 
 ```
 FOR EACH SIMPLIFICATION:
@@ -322,9 +324,7 @@ FOR EACH SIMPLIFICATION:
 4. If either fails → revert and reconsider
 ```
 
-Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.
-
-**The Rule of 500:** If a refactoring would touch more than 500 lines, invest in automation (codemods or AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review.
+**The Rule of 500:** If a refactoring would touch more than 500 lines, stop and propose it — the scope, the approach (codemod or AST transform included), and the affected files — instead of applying it, unless the user explicitly asked for that scope. A change that size is no longer scoped to what changed (Principle 5), and manual edits at that scale are error-prone and exhausting to review.
 
 ### Step 4: Verify the Result
 
@@ -334,29 +334,40 @@ Then step back and evaluate the whole:
 
 ```
 COMPARE BEFORE AND AFTER:
-- Is the simplified version genuinely easier to understand?
-- Did you introduce any new patterns inconsistent with the codebase?
-- Is the diff clean and reviewable?
-- Would a teammate approve this change?
+- Is the simplified version genuinely easier to understand and review?
+- Did you introduce any pattern inconsistent with the surrounding code?
 ```
 
-If the "simplified" version is harder to understand or review, revert. Not every simplification attempt succeeds.
+If either answer is wrong, revert. Not every simplification attempt succeeds.
+
+## Report
+
+End every pass with one report. Every pre-scan candidate lands in exactly one bucket,
+and each entry names the file, the candidate, and the reason. A candidate you could not
+verify goes under **Unsure**, never into the code: an export kept on doubt costs a line
+of explanation, one removed on a guess costs an incident.
+
+**Group the noise, itemize the decisions.** Candidates under **Left alone on purpose**
+that share a tool and a reason collapse into one line with a count and the threshold or
+rule that dismissed them (for example, "14 complexity hits below nesting depth 3"). Every
+candidate in the other buckets gets its own entry.
+
+- **Applied** — what changed, and the check that proved it (type checker, tests)
+- **Not applied — changes behavior** — what the fix would alter: ordering, concurrency,
+  mutation, error surface, or name resolution
+- **Unsure** — what you could not verify, and which evidence is missing
+- **Propose-only** — API reshapes and refactors past the Rule of 500: the proposed change
+  and the files it would touch
+- **Left alone on purpose** — candidates not worth changing, with the reason
+
+Close with anything that limited the pass: missing test coverage, or formatter drift you
+reverted.
 
 ## Language-Specific Guidance
 
 ### TypeScript / JavaScript
 
 ```typescript
-// SIMPLIFY: Unnecessary async wrapper
-// Before
-async function getUser(id: string): Promise<User> {
-  return await userService.findById(id);
-}
-// After
-function getUser(id: string): Promise<User> {
-  return userService.findById(id);
-}
-
 // SIMPLIFY: Verbose conditional assignment
 // Before
 let displayName: string;
@@ -454,15 +465,12 @@ function UserBadge({ user }: Props) {
 
 ## Common Rationalizations
 
-| Rationalization                                      | Reality                                                                                                                                               |
-| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "It's working, no need to touch it"                  | Working code that's hard to read will be hard to fix when it breaks. Simplifying now saves time on every future change.                               |
-| "Fewer lines is always simpler"                      | A 1-line nested ternary is not simpler than a 5-line if/else. Simplicity is about comprehension speed, not line count.                                |
-| "I'll just quickly simplify this unrelated code too" | Unscoped simplification creates noisy diffs and risks regressions in code you didn't intend to change. Stay focused.                                  |
-| "The types make it self-documenting"                 | Types document structure, not intent. A well-named function explains _why_ better than a type signature explains _what_.                              |
-| "This abstraction might be useful later"             | Don't preserve speculative abstractions. If it's not used now, it's complexity without value. Remove it and re-add when needed.                       |
-| "The original author must have had a reason"         | Maybe. Check git blame — apply Chesterton's Fence. But accumulated complexity often has no reason; it's just the residue of iteration under pressure. |
-| "I'll refactor while adding this feature"            | Separate refactoring from feature work. Mixed changes are harder to review, revert, and understand in history.                                        |
+| Rationalization                              | Reality                                                                                                                              |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| "Fewer lines is always simpler"              | A 1-line nested ternary is not simpler than a 5-line if/else. Simplicity is about comprehension speed, not line count.               |
+| "This abstraction might be useful later"     | Speculative abstractions are complexity without value. If nothing uses it now, remove it under the dead-code and export rules above. |
+| "The original author must have had a reason" | Maybe. Check git blame — apply Chesterton's Fence. But accumulated complexity often has no reason; it's the residue of iteration.    |
+| "I'll refactor while adding this feature"    | Separate refactoring from feature work. Mixed changes are harder to review, revert, and understand in history.                       |
 
 ## Red Flags
 
@@ -471,36 +479,34 @@ function UserBadge({ user }: Props) {
 - Renaming things to match your preferences rather than project conventions
 - Removing error handling because "it makes the code cleaner"
 - Simplifying code you don't fully understand
-- Batching many simplifications into one large, hard-to-review commit
-- Refactoring code outside the scope of the current task without being asked
+- Touching code outside the requested scope without being asked
 - Deleting an export because a tool reported it unused, without checking whether the
   framework resolves it by name (`page.tsx`, `route.ts`, stories, config-referenced files)
 - Acting on a pre-scan candidate you could not verify — report it instead
+- Applying a propose-only row (module collapse, barrel deletion) without user sign-off
 - Treating a green test run as proof a visibility change was safe without a type check
 - Unexporting a symbol whose only importer is a test, then editing the test to match
-- Applying a propose-only row (module collapse, barrel deletion) without user sign-off
 - Trusting "the compiler would catch it" in a project the type checker does not cover
+- Dropping `async` or `return await` as a "simplification" — it changes how errors and stack traces surface
 
 ## Verification
 
 After completing a simplification pass:
 
 - [ ] All existing tests pass without modification
+- [ ] Type checker passes, if the project has one
 - [ ] Build succeeds with no new warnings
-- [ ] The project's own formatter was detected and run on the touched files — no formatter the project has not adopted was used
-- [ ] Formatting touched only the changed files (no repo-wide reformat mixed in)
+- [ ] The project's own formatter ran on the touched files only
 - [ ] Linter passes (no style regressions)
 - [ ] Each simplification is a reviewable, incremental change
-- [ ] The diff is clean — no unrelated changes mixed in
+- [ ] The diff holds nothing outside the requested scope
 - [ ] Simplified code follows project conventions (checked against CLAUDE.md or equivalent)
 - [ ] No error handling was removed or weakened
 - [ ] No dead code was left behind (unused imports, unreachable branches)
-- [ ] The Step 2a pre-scan was run, and every candidate is either fixed or explained
-- [ ] Export surface matches actual consumers — nothing exported without a caller outside its file
-- [ ] Type checker passes — no unexport broke an importer
+- [ ] Every removed `export` cleared the pre-removal checklist
 - [ ] No framework-resolved export was unexported, renamed, or deleted
-- [ ] Every removed `export` cleared all boxes of the pre-removal checklist
 - [ ] No test was edited to accommodate a visibility change
 - [ ] Propose-only findings were reported, not applied
+- [ ] Every pre-scan candidate appears in the Report, itemized or counted in a grouped line
 - [ ] Behavior is bit-for-bit identical: same inputs, outputs, side effects, error paths
 - [ ] A teammate or review agent would approve the change as a net improvement

package/src/templates/mate-skills/openspec-references.ts

@@ -0,0 +1,140 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { runOpenSpec } from "../../lib/openspec-cli";
+
+/** OpenSpec workflow → the Mate skill that carries it as `references/<workflow>.md`. */
+export const VENDORED_WORKFLOWS = [
+  { workflow: "openspec-explore", skill: "mate-explore-change" },
+  { workflow: "openspec-propose", skill: "mate-propose-change" },
+  { workflow: "openspec-apply-change", skill: "mate-apply-change" },
+  { workflow: "openspec-update-change", skill: "mate-propose-change" },
+] as const;
+
+/** OpenSpec tools whose generated text is vendored, each into the Mate skill bucket of the same name. */
+const TOOLS = ["claude", "agents"] as const;
+
+/** `/opsx:<command>` and `/openspec-<workflow>` → the Mate skill that replaces both. */
+const COMMAND_REWRITES: Record<string, string> = {
+  "/opsx:explore": "/mate-explore-change",
+  "/openspec-explore": "/mate-explore-change",
+  "/opsx:propose": "/mate-propose-change",
+  "/openspec-propose": "/mate-propose-change",
+  "/opsx:apply": "/mate-apply-change",
+  "/openspec-apply-change": "/mate-apply-change",
+  "/opsx:archive": "/mate-archive-change",
+  "/openspec-archive-change": "/mate-archive-change",
+  "/opsx:update": "/mate-propose-change",
+  "/openspec-update-change": "/mate-propose-change",
+};
+
+/** A slash command, not a path segment such as `references/openspec-explore.md`. */
+const COMMAND_REFERENCE = /(?<![\w.-])\/(?:opsx:|openspec-)[a-z][a-z-]*[a-z]/g;
+const FRONTMATTER = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n)+/;
+
+export const NOTICES_FILE = "THIRD-PARTY-NOTICES.md";
+
+/** Every `/opsx:` or `/openspec-` command reference in `text`, in order. */
+export function findCommandReferences(text: string): string[] {
+  return text.match(COMMAND_REFERENCE) ?? [];
+}
+
+/** Rewrites mapped command references; bare `openspec <command>` CLI calls stay. */
+export function rewriteCommandReferences(text: string): string {
+  return text.replace(COMMAND_REFERENCE, (reference) => COMMAND_REWRITES[reference] ?? reference);
+}
+
+/** Path below `mate-skills/` of a vendored reference file. */
+function referencePath(
+  tool: (typeof TOOLS)[number],
+  { workflow, skill }: (typeof VENDORED_WORKFLOWS)[number],
+): string {
+  return `${tool}/${skill}/references/${workflow}.md`;
+}
+
+async function readPackageFile(cliPath: string, file: string): Promise<string> {
+  return fs.readFile(path.resolve(path.dirname(cliPath), "..", file), "utf8");
+}
+
+async function readVersion(cliPath: string): Promise<string> {
+  return (JSON.parse(await readPackageFile(cliPath, "package.json")) as { version: string })
+    .version;
+}
+
+function header(workflow: string, tool: string, version: string): string {
+  return [
+    `<!-- Vendored from OpenSpec ${version}: the \`${workflow}\` workflow its \`${tool}\` tool generates.`,
+    "     Copyright (c) OpenSpec Contributors, MIT License (see THIRD-PARTY-NOTICES.md in Mate).",
+    "     Regenerated by `bun run vendor:openspec`; do not edit. -->",
+    "",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Each vendored reference file, keyed by its path below `mate-skills/`, rendered from
+ * the OpenSpec CLI at `cliPath`. Throws on a missing skill, missing frontmatter, or a
+ * command reference no rewrite rule maps, so no partial output is ever written.
+ */
+export async function renderOpenSpecReferences(cliPath: string): Promise<Map<string, string>> {
+  const version = await readVersion(cliPath);
+  const workdir = await fs.mkdtemp(path.join(os.tmpdir(), "mate-vendor-openspec-"));
+  try {
+    const init = await runOpenSpec(["init", "--tools", TOOLS.join(","), workdir], {
+      cwd: workdir,
+      bin: cliPath,
+    });
+    if (init.code !== 0) {
+      throw new Error(`openspec init exited with code ${init.code}: ${init.stderr.trim()}`);
+    }
+
+    const files = new Map<string, string>();
+    for (const tool of TOOLS) {
+      for (const vendored of VENDORED_WORKFLOWS) {
+        const { workflow } = vendored;
+        const generated = path.join(workdir, `.${tool}`, "skills", workflow, "SKILL.md");
+        const source = await fs.readFile(generated, "utf8");
+        if (!FRONTMATTER.test(source)) {
+          throw new Error(`OpenSpec ${workflow} (${tool}) has no skill frontmatter to strip.`);
+        }
+        const body = rewriteCommandReferences(source.replace(FRONTMATTER, ""));
+        const unmapped = findCommandReferences(body);
+        if (unmapped.length > 0) {
+          throw new Error(
+            `OpenSpec ${workflow} (${tool}) references commands with no Mate rewrite: ${[...new Set(unmapped)].join(", ")}`,
+          );
+        }
+        files.set(referencePath(tool, vendored), header(workflow, tool, version) + body);
+      }
+    }
+    return files;
+  } finally {
+    await fs.rm(workdir, { recursive: true, force: true });
+  }
+}
+
+/** The notices file for the vendored text, carrying the bundled package's `LICENSE` verbatim. */
+export async function renderOpenSpecNotices(cliPath: string): Promise<string> {
+  const version = await readVersion(cliPath);
+  const license = await readPackageFile(cliPath, "LICENSE");
+  const vendored = TOOLS.flatMap((tool) =>
+    VENDORED_WORKFLOWS.map((workflow) => `- \`${referencePath(tool, workflow)}\``),
+  );
+  return [
+    "# Third-Party Notices",
+    "",
+    `The following files contain workflow text from OpenSpec ${version}`,
+    "(https://github.com/Fission-AI/OpenSpec), with command references rewritten to",
+    "the matching Mate skills:",
+    "",
+    ...vendored,
+    "",
+    "OpenSpec is distributed under this license:",
+    "",
+    "```text",
+    license.trimEnd(),
+    "```",
+    "",
+  ].join("\n");
+}

package/src/templates/root/TEMPLATE_AGENTS.md

@@ -1,7 +1,7 @@
 <!-- MATE:COMPANION:START -->
 
-- When reporting information to me, be extremely concise and sacrifice grammar for the sake of concision. Apply this same preference to JSDoc.
-- Code comments: JSDoc format only (`/** ... */`), never `//`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
+- When reporting information to me, be extremely concise and sacrifice grammar for the sake of concision. Apply this same preference to comments and JSDoc, not implementation code; retain necessary contract details.
+- Code comments: sparse and concise — explain non-obvious intent, constraints, or workarounds; avoid filler, restating code, or artifact rationale. Use JSDoc for JS/TS API documentation; line or ordinary block comments for local implementation notes, including JSX-supported expression comments. Preserve required documentation, tool directives, legal notices, generated files, and language-appropriate syntax. Do not rewrite unchanged comments or unrelated code for this preference.
 - Never add a `Co-Authored-By: <model>` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (`$MATE_REPO_PATH`) unless the user explicitly asks for it.
 - Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.