@uniqbit/mate-core 0.15.5 → 0.16.0-canary.1

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

@@ -0,0 +1,156 @@
+---
+name: mate-interview-me
+description: Clarify intent through a focused, one-question-at-a-time conversation before planning.
+disable-model-invocation: true
+---
+
+# Mate Interview Me
+
+> Inspired by [Addy Osmani's interview-me skill](https://github.com/addyosmani/agent-skills/tree/main/skills/interview-me) and adapted here as a Mate process-driven skill.
+
+## Overview
+
+What people ask for and what they actually want are different things. They ask
+for a "dashboard" because that is what one asks for, not because a dashboard
+solves their problem. They say "make it faster" without a number to hit.
+
+The cheapest moment to find this gap is before any plan, spec, or code exists.
+Once implementation has started, switching costs are real and the user may
+rationalize the wrong thing into "good enough." This skill closes the gap before
+it costs anything.
+
+## When to Use
+
+Apply this skill when:
+
+- The ask is missing at least one of: who the user is, why they want it, what
+  success looks like, or the binding constraint.
+- The request is conventional rather than specific and cannot be unpacked
+  without guessing.
+- You are tempted to start with assumptions that have not been surfaced.
+- The user has not said which value they are optimizing for when reasonable
+  values are in tension, such as simplicity versus flexibility.
+- The user explicitly invokes "interview me", "grill me", "are we sure?", or
+  "stress-test my thinking".
+
+**When NOT to use:**
+
+- The ask is unambiguous and self-contained.
+- The user explicitly asked for speed over verification.
+- The request is purely informational.
+- The operation is mechanical, such as a rename, format, or file move.
+- You already have >=95% confidence; reread the stop condition before assuming
+  you do not.
+
+## Loading Constraints
+
+This skill needs a live, responsive user. Do not use it in non-interactive
+contexts such as CI pipelines, scheduled runs, loops, or autonomous runs. If an
+underspecified ask arrives there, report the blocker instead of guessing.
+
+## The Process
+
+### Step 1: Hypothesize, with a confidence number
+
+Before asking anything, write the current best read of what the user wants in one
+sentence, followed by an honest confidence number from 0 to 100 percent. When
+confidence is below 70 percent, state what is missing on the same line.
+
+```text
+HYPOTHESIS: You want <the underlying outcome>, and <the user's wording> was the convention that came to mind. CONFIDENCE: ~30% - missing: <what is unresolved>
+```
+
+The number forces honesty. If you wrote a high number but cannot predict the
+user's reactions to the next three questions, the number is wrong.
+
+### Step 2: Ask one question at a time, each with a guess attached
+
+Ask exactly one focused question that would most reduce uncertainty. Attach your
+best guess about the answer and the reasoning behind it:
+
+```text
+CONFIDENCE: <0-100%> (<change since the previous answer>)
+RESOLVED: <what is now clear>
+REMAINING: <what is still uncertain>
+Q: <one focused question> GUESS: <your hypothesis for the answer and why>
+```
+
+Wait for the answer before asking the next question. Never batch questions or
+advance silently. The guess exposes assumptions and lets the user correct them
+quickly.
+
+After every answer, update the confidence, resolved points, and remaining
+uncertainty before asking the next question. Keep this progress state visible;
+do not report confidence only at the beginning or end.
+
+### Step 3: Listen for "want versus should want"
+
+Watch for best-practice talk without specifics, deference to convention, phrases
+such as "I should probably", and buzzwords used as goals instead of outcomes.
+When you hear one, ask:
+
+> _"If you did not have to justify this to anyone, what would you actually want?"_
+
+### Step 4: Restate intent in the user's own words
+
+When confidence is high, write back a concise restatement using the user's
+language and these fields:
+
+```text
+Outcome:      <one line>
+User:         <one line - who benefits>
+Why now:      <one line - what changed>
+Success:      <one line - how we know it worked>
+Constraint:   <one line - the binding limit>
+Out of scope: <one line - what we are explicitly not doing>
+```
+
+Ask: "Yes, no, or refine?" The out-of-scope line is mandatory; silent disagreement
+about non-goals is a common source of misalignment.
+
+### Step 5: Confirm explicitly
+
+The gate is an explicit yes. These are not confirmation:
+
+- "Whatever you think is best." Ask again with two concrete options.
+- "Sounds good." Ask what the user would refine.
+- "Sure, let us go." Check whether anything was missed.
+- Silence followed by "okay, let us start." Ask whether the user has confirmed
+  the restatement.
+
+If the user corrects the restatement, fold in the correction and restate it again.
+
+### The 95% Confidence Stop
+
+Stop only when you can predict the user's reaction to the next three questions.
+This is a checkable condition, not a feeling. If the user names a blocker before
+that point, stop and label the result unresolved rather than calling it confirmed.
+
+## Output
+
+The deliverable is a confirmed statement of intent: the restatement above plus
+an explicit yes. Specs, plans, and task lists are downstream and do not belong in
+this skill. A blocked session returns its partial intent, blocker, and unresolved
+questions instead.
+
+## Mate Boundary
+
+This is a conversational-only skill. Do not create or modify code, context files,
+ADRs, OpenSpec artifacts, intent documents, or any other files. Do not claim that
+a file was written, and do not invoke another skill.
+
+## Verification
+
+Before stopping, check that:
+
+- An initial hypothesis and confidence number were stated.
+- Every confidence number below 70 percent included its reason.
+- Confidence, resolved points, and remaining uncertainty were shown before each
+  question.
+- Every question was asked one at a time with an attached guess.
+- The want-versus-should-want probe ran when the user gave a convention or
+  sophistication-signaling answer.
+- The restatement includes Outcome, User, Why now, Success, Constraint, and Out
+  of scope.
+- The user explicitly confirmed the restatement, or the result is clearly marked
+  unresolved because of a blocker.

package/src/templates/mate-skills/claude/mate-openspec-backfill/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: mate-openspec-backfill
+description: Reverse-engineer an OpenSpec spec for one existing feature and emit a ready-to-finish backfill change. Use when the user wants to backfill, document, or spec existing or legacy behavior that has no spec yet.
+allowed-tools: Bash(openspec:*), Bash(mate:*)
+license: MIT
+compatibility: Requires the mate CLI and the openspec capability enabled.
+metadata:
+  author: mate
+  version: "1.0"
+---
+
+# Mate OpenSpec Backfill
+
+Create a spec for one feature that already exists in the working repository. The run ends with a standard ready-to-finish change — it never edits main specs and never finishes.
+
+## Scope rules
+
+- **One named feature per run.** Refuse Area-wide or repository-wide sweeps; ask the user to name a single feature and run the skill once per feature.
+- **Interactive by design.** Every ambiguity and every suspected bug becomes a user question. Do not run this skill unattended.
+
+## Steps
+
+1. **Scope.** Map the named feature to code: entry points, callees, tests. Use whatever exploration tooling this project has enabled (code-graph or index tools when present, otherwise search and targeted reading) — assume no specific capability is installed. Then check `openspec/specs/` for an existing capability covering this domain — prefer extending it (`MODIFIED`/`ADDED` deltas) over minting a new capability id.
+
+2. **Sweep.** Extract candidate behaviors and tag each finding:
+   - `[test-backed]` — an existing test verifies it (strongest; scenarios translate almost directly from tests)
+   - `[code-only]` — observable in code but untested
+   - `[inferred]` — assumed intent without direct evidence
+
+   Every candidate requirement needs at least one citation: a test name or `file:line`. Docs and comments corroborate but never stand alone. `[inferred]` findings are not requirements — they become questions for step 3.
+
+3. **Ask.** Batch the open questions to the user:
+   - Behavior that looks unintended → the user rules **spec the actual behavior** or **spec the intent** (with a follow-up fix change). Suspected bugs never silently become requirements.
+   - `[inferred]` findings → confirm, demote to out-of-scope, or convert to a question the emitted proposal records as open.
+
+4. **Emit.** Create the change and build its artifacts in dependency order:
+
+   ```bash
+   openspec new change "backfill-spec-<capability>"
+   openspec status --change "backfill-spec-<capability>" --json
+   openspec instructions <artifact-id> --change "backfill-spec-<capability>" --json
+   ```
+
+   The artifact set comes from the active schema (`schemaName` in the status JSON) — never assume a fixed artifact list. Follow each artifact's returned instructions and template, and state the active schema in the proposal so reviewers know which workflow produced the change. Map the backfill roles onto whatever artifacts the schema defines:
+
+   | Backfill role                                                                                  | Typical artifact (mate-v1 example) |
+   | ---------------------------------------------------------------------------------------------- | ---------------------------------- |
+   | Scope decisions and rulings from step 3                                                        | explore-brief.md                   |
+   | "Documents existing behavior, no code changes" + open questions                                | proposal.md                        |
+   | `ADDED`/`MODIFIED` requirements, behavior only, one citation each                              | specs/                             |
+   | As-built evidence dossier: entry points, test inventory, `file:line` citations per requirement | design.md                          |
+   | Verification checklist: one task per requirement, "confirm behavior at <citation>"             | tasks.md                           |
+
+   The verification task artifact MUST open with this rule, verbatim, so the applying agent sees it without knowing this skill: "These are verification tasks for a docs-only backfill change. If a requirement fails verification, update the delta spec (reword, drop, or re-cite the requirement) — never modify code in this change. A real bug found here becomes a separate fix change."
+
+   Requirements state observable contracts, never implementation detail ("propagates the child exit code", not "uses spawnSync").
+
+5. **Stop.** Report the change as ready-to-finish and hand off:
+   - Verify: `openspec-apply-change` works through tasks.md, checking each requirement against the code.
+   - Publish: `mate-artifact-publish` applies the deltas to main specs and anchors the change.
+
+## Guardrails
+
+- Never write files under `openspec/specs/` — main specs change only through finished changes.
+- Never invoke any finish flow (`mate artifact publish`, `openspec archive`); stop at ready-to-finish.
+- Never emit a requirement without a citation, and never spec a suspected bug without the user's ruling.
+- Keep capability ids opaque kebab-case; extend existing capabilities before creating new ones.

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

@@ -0,0 +1,139 @@
+---
+name: mate-show-me
+description: Explain the current topic or the applied change in a browser-rendered Mate report. Use only when the user explicitly invokes the skill to see how something works, what a change did, or wants a diagram, call tree, or rendered diff of the current work.
+disable-model-invocation: true
+allowed-tools: Bash(git:*), Bash(mate:*)
+license: MIT
+compatibility: Requires the mate CLI and the openspec capability enabled.
+metadata:
+  author: mate
+  version: "1.0"
+---
+
+# Mate Show Me
+
+> Inspired by [humanlayer's show-me skill](https://github.com/humanlayer/skills/tree/main/plugins/show-me/skills/show-me) and adapted here as a Mate process-driven skill.
+
+Explain the current topic visually in a browser-rendered Mate report. Skip the preamble, keep prose brief, and pick the smallest report view that makes the key point clear.
+
+## Mate Workflow
+
+- Explanation only. Never write or edit source code, tests, documentation, OpenSpec artifacts, context files, or ADRs. The only file this skill produces is the report document handed to `mate report --input`, which the CLI writes into the operating system temporary directory.
+- Draw from the repositories, not from memory. Every diagram and every diff line comes from the inspected repository state, never from recollection of the conversation. Use the available code-graph tools before broad source scans.
+- Code lives in the Working Repository; the Companion Repository holds only artifacts. Run `git diff` in the Working Repository.
+- Never put an absolute local path, home directory, username, machine name, temporary report path, Companion Repository path, or raw path-valued environment variable in the report. Use repository-relative paths or neutral labels such as `Working Repository` and `Companion Repository`.
+- Never commit, push, or create a pull request.
+
+## Browser Report Required
+
+Always assemble and open a Mate report, even when a small inline sketch would be sufficient. Do not answer with an inline-only visual or paste the complete diagram or diff into the conversation. The final response should briefly state what the browser report shows without repeating its temporary file path.
+
+## Report Contents
+
+- Show logic or an algorithm as a `diagram` section. Use a `mermaid` payload when branches, stages, or relationships benefit from a rendered visual; reserve `text` for compact pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+- Show runtime control flow as a `diagram` section with a `mermaid` payload. Use `flowchart TD` for a call tree or control flow and `sequenceDiagram` when ordering between components matters:
+
+```mermaid
+flowchart TD
+  renderHTML[renderHTML] --> validate[validateReportDocument]
+  renderHTML --> section[renderHTMLSection]
+  section --> diagram[renderHTMLDiagram]
+  section --> diff[renderHTMLDiff]
+```
+
+- Show UI structure as a `diagram` section with a `mermaid` payload when showing relationships between components or modules. Use a `text` payload only when exact component syntax is the point, including the state boundaries that matter:
+
+```tsx
+<WorkflowView> (studio/views/workflow/index.tsx)
+  workflowPlan(availableSkills)
+  <StepList>
+    <StepRow optional>
+```
+
+- Show file responsibility or a broad refactor as a `diagram` section with a `text` payload containing a shallow file tree:
+
+```text
+src/
+|-- commands/      # parses user actions
+|-- report/        # owns the report contract and renderer
+`-- templates/     # ships assets and skills
+```
+
+- Show what changes as a `diff` section when the surrounding shape already exists. Match the diff shape to the topic - component tree, file layout, call tree, or control flow:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
+```
+
+- 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.
+
+## Browser Delivery
+
+The report is mandatory. Prefer `mate report --input <temporary-json-file>` without `--json` so the CLI reads the complete document reliably, writes self-contained HTML, and 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.
+
+Never hand-write an HTML file, never start a server, and never open a browser by any other means. `mate report` is the only browser surface.
+
+## Assembling The Report
+
+Build a JSON document that conforms to the `mate-create-report` contract, then hand it over:
+
+1. Serialize the complete document to an OS temporary JSON file outside both repositories. Do not place the report input in the Working Repository or Companion Repository.
+2. Run `mate report --input <temporary-json-file>`.
+
+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
+- 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
+
+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.
+
+```json
+{
+  "id": "structure",
+  "title": "Report rendering",
+  "type": "diagram",
+  "mermaid": "classDiagram\n  Renderer --> Highlight : uses"
+}
+```
+
+```json
+{
+  "id": "changes",
+  "title": "What changed",
+  "type": "diff",
+  "patch": "diff --git a/src/acme.ts b/src/acme.ts\n..."
+}
+```
+
+If the document fails contract validation, report the diagnostic and correct the document. Do not fall back to hand-written HTML.
+
+## 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.
+- Do not use ELK-only layouts or math labels. The report inlines the self-contained mermaid bundle, which may 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.
+- 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.