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

package/src/templates/mate-skills/agents/mate-clarify-intent/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: mate-clarify-intent
+description: Pick the pre-explore mode a request needs (interview, grilling, or skip) from what it already states, then run that one mode. Use only when the user explicitly starts clarifying an idea before exploring a change.
+disable-model-invocation: true
+license: MIT
+compatibility: Requires the mate CLI and the openspec capability enabled.
+metadata:
+  author: mate
+  version: "1.0"
+---
+
+# Mate Clarify Intent
+
+The optional first stage of the Delivery Path. It runs before `/mate-explore-change`
+and decides how much clarification a request needs: an interview when intent is
+incomplete, grilling when intent is clear but a proposed direction needs testing, or
+nothing at all for a small, fully specified change.
+
+Read only the user's request and this conversation. Do not read or investigate the
+repository; questions that need repository evidence go to explore.
+
+## Step 1: Fill the slot table
+
+Mark each slot `stated`, `implied`, or `missing` from the request and conversation:
+
+| Slot       | Question                                      |
+| ---------- | --------------------------------------------- |
+| Who        | Who benefits or is affected?                  |
+| Why        | What problem or change makes this needed now? |
+| Success    | How will we know it worked?                   |
+| Constraint | What limit binds the solution?                |
+
+`implied` Success counts as `missing`: a guessed success measure is the gap this stage
+exists to close. Then note whether the request proposes a direction (an approach,
+design, or solution shape): yes or no.
+
+## Step 2: Route
+
+Apply the first rule that matches:
+
+1. Any slot `missing` → **interview**.
+2. All slots filled and a direction is proposed → **grill**.
+3. All slots filled, no direction, and the change is minimal-eligible (one Area, low
+   risk, no new dependency or data-model change) → **skip**.
+4. Otherwise → **grill**.
+
+## Step 3: Announce and accept an override
+
+Show the slot table with each slot's mark, the direction answer, and the route with
+its rule in one line, for example:
+
+```text
+Route: interview — Success is missing.
+Reply `interview`, `grill`, or `skip` to switch; anything else continues.
+```
+
+A one-word reply `interview`, `grill`, or `skip` replaces the route without further
+questions. Run exactly one mode.
+
+## Step 4: Run the routed mode
+
+Run the mode by **reading its instructions and following them**, not by invoking a
+skill. Resolve the file relative to this skill's own directory:
+
+- **interview** → read `../mate-interview-me/SKILL.md` and follow it from its first
+  step.
+- **grill** → read `../mate-grill-me/SKILL.md` and follow it.
+- **skip** → run nothing.
+
+`mate-interview-me` and `mate-grill-me` are manual-only skills: never call them through
+the skill mechanism. Reading the file is the supported way to run them from here. If
+the file is missing, report that the companion's Mate skills need
+`mate companion update` and stop.
+
+## Step 5: Hand off
+
+A routed mode ends with its own `PRE-EXPLORE HANDOFF` block naming
+`/mate-explore-change`. For **skip**, emit:
+
+```text
+PRE-EXPLORE HANDOFF (skip)
+Confirmed:   <the four slots as stated>
+Unresolved:  none
+Assumptions: <points explore should verify, or "none">
+Next: /mate-explore-change
+```
+
+Tell the user the next step is `/mate-explore-change`; do not invoke it.
+
+## Mate Boundary
+
+Conversational only. Do not create or modify code, context files, ADRs, OpenSpec
+artifacts, or any other file. This skill runs before `/mate-explore-change`: wide
+repository investigation and option comparison belong there, recorded under
+Unresolved or Assumptions in the handoff.

package/src/templates/mate-skills/agents/mate-explore-change/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: mate-explore-change
+description: Explore a change with its Working Repository and Area resolved from the companion context map, and suggest slicing a large feature into several changes. Builds on the OpenSpec explore workflow. Use when the user wants to explore, investigate, or think through a change before proposing it.
+allowed-tools: Bash(mate:*), Bash(openspec:*), Bash(git:*)
+license: MIT
+compatibility: Requires the mate CLI and the openspec capability enabled.
+metadata:
+  author: mate
+  version: "1.0"
+---
+
+# Mate Explore Change
+
+The Explore change stage of the Delivery Path. It runs the OpenSpec explore workflow
+and adds two things: the scope comes from the companion context map, and a feature too
+large for one change is suggested as several.
+
+## Steps
+
+1. **Follow the OpenSpec workflow.** Read
+   [references/openspec-explore.md](references/openspec-explore.md) and follow it for the
+   exploration itself. When a `PRE-EXPLORE HANDOFF` block is in this conversation, treat
+   its Confirmed points as settled and start from its Unresolved questions and
+   Assumptions.
+
+2. **Resolve scope from the context map.** Before reading code, identify the canonical
+   Working Repository (`org/repository` from its Git remote) and the repository-relative
+   Area (the owning package root in a monorepo). Read the Companion Repository's
+   `CONTEXT-MAP.md`, then only the repository-scoped map for that Working Repository,
+   and load only the contexts it maps to that Area. Use their vocabulary in the
+   exploration. When the map has no entry for the Area, say so instead of borrowing
+   another Area's context.
+
+3. **Suggest slicing when the feature is large.** Slicing test: a feature needs
+   slicing when it spans several Areas, several independent behaviours, or more work
+   than one review can hold (roughly more than 10 tasks or 400 changed lines).
+   Several Areas that only work together stay one change with a scope per Area. When
+   the explored direction passes the test, propose slices: one change per slice,
+   each reviewable and archivable on its own, in dependency order. Name the
+   dependencies between slices; they become `dependsOn` entries when the changes are
+   proposed. Several slices may share one delivery branch. Slicing is a suggestion;
+   the user decides.
+
+4. **Hand off.** End by naming `/mate-propose-change` as the next step, once per agreed
+   slice. Do not invoke it.
+
+## Boundary
+
+Exploration writes no product code. Agent artifacts written while exploring go to the
+Companion Repository, never the Working Repository.

package/src/templates/mate-skills/agents/mate-explore-change/references/openspec-explore.md

@@ -0,0 +1,348 @@
+<!-- Vendored from OpenSpec 1.15.0: the `openspec-explore` workflow its `agents` tool generates.
+     Copyright (c) OpenSpec Contributors, MIT License (see THIRD-PARTY-NOTICES.md in Mate).
+     Regenerated by `bun run vendor:openspec`; do not edit. -->
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, investigate the codebase, and run read-only commands or tools without confirmation, but you must NEVER write code or implement features. If the user asks you to implement something, do not start it here: say that explore mode does not implement, and point them at `/mate-propose-change`, which turns the discussion into a change. The work happens from that change, never from explore mode. You MAY create or update OpenSpec change artifacts (proposals, designs, specs) within a confirmed scope—that's capturing thinking, not implementing. Answering design or clarifying questions is never consent to write. Before the first write-capable action, name the artifacts or files you would change and what you would do, ask a direct yes/no question, and wait for the user's confirmation in a separate message. Confirmation covers only the scope you described; ask again before expanding it. An explicit request from the user to capture the exploration as a new change is itself that confirmation, covering the change and the change artifacts the request names; scaffold it first as described below.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+**Project check:** These steps expect a project that already uses OpenSpec. Before the first step that writes anything (`new change`, `archive`, `sync specs`, or authoring an artifact file), confirm the project has a root: run `openspec list --json` (with `--store <id>` when a store is selected, since the store is then the root) and read `root`. A root object means the project is set up. `"root": null` means it is not - there is no `openspec/` directory here, and a write such as `openspec new change` would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.
+
+One `"root": null` is not about setup: when a `status` error message starts with `Declared in` or `Invalid store declaration in` and names this project's `openspec/config.yaml` (or `config.yml`), the project does use OpenSpec through a store it declares, which this machine cannot resolve (the store is not registered, or the `store:` line is malformed). Do not treat it as uninitialized and skip the branches below: stop before writing and show the user that error's `message` and `fix`.
+
+Otherwise, with no root, what happens next depends on how this workflow was reached:
+
+- **Auto-selected**: you chose this workflow yourself, without the user naming OpenSpec, naming this skill, or running its slash command. Stop using OpenSpec and answer the request normally, as you would with no OpenSpec installed. Do not ask them to set anything up and do not mention OpenSpec setup.
+- **Explicit OpenSpec request**: the user named OpenSpec, named this skill, or ran its slash command. Stop before writing and ask how to proceed: set this project up (`openspec init`), target a store they already have (`--store <id>`), or continue without OpenSpec for this request. Wait for their answer.
+
+In both branches, never create the root as a side effect: do not run `openspec init` until the user asks for it, do not hand-create `openspec/` files, and do not let a command create it.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## Planning a Change
+
+When the user is planning a change, guide them toward shared understanding with focused discovery questions. For open-ended discussion, follow the conversation without imposing an interview or a required output.
+
+Before asking a factual question, follow the context discovery below and inspect relevant OpenSpec artifacts, source, tests, docs, and configuration. Do not ask the user to repeat facts you can verify. Summarize relevant findings without reproducing private context or rules. If evidence is missing, conflicting, or inaccessible, state that limitation and ask only for the clarification needed to proceed.
+
+- **Follow dependencies** - Resolve the next blocking decision before its dependent details. For example, clarify the user's outcome and scope before choosing an API or data model. Revisit downstream assumptions when an earlier answer changes. Skip branches that do not matter to this goal.
+- **Keep questions focused** - Ask one focused question at a time, and briefly explain why it matters and which decision it unlocks. Batch questions only if the user asks for a batch; keep them small and group related decisions.
+- **Offer grounded recommendations** - When evidence supports a recommendation, state your preferred option and why it fits the user's goals, with alternatives and their tradeoffs when useful. Do not invent intent, priorities, or external constraints: ask the user when only they can answer. Avoid a fixed question format.
+- **Keep a conversational record** - Track decisions in the conversation, not in files. Separate confirmed decisions from proposed defaults and unresolved questions. Silence is not acceptance. Accepting an answer or a batch of recommendations is not permission to write. Keep file-write confirmation separate from discovery questions and follow the guardrails below.
+
+Stop asking when the user has enough clarity. Let them pause, pivot, or defer a decision; do not exhaust every branch or force a proposal.
+
+For example, after inspecting the relevant code:
+
+```text
+The CLI already uses SQLite and has no remote service. Is sharing state
+across devices in scope? That determines whether local storage is enough.
+If this stays a single-device tool, I recommend keeping SQLite to avoid
+adding a service to operate; shared state would need a separate sync design.
+```
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
++------------------------------------------+
+|     Use ASCII diagrams liberally         |
++------------------------------------------+
+|                                          |
+|   [State A] -------> [State B]           |
+|       |                                  |
+|       v                                  |
+|   [State C]                              |
+|                                          |
+|   System diagrams, state machines,       |
+|   data flows, architecture sketches,     |
+|   dependency graphs, comparison tables   |
+|                                          |
++------------------------------------------+
+```
+
+**Draw with plain ASCII only** — borders `+` `-` `|`, arrows `-->` `<--` `^` `v`, markers `*` `x`.
+Unicode diagram glyphs can render at different widths across terminals, fonts, and locales, so padded boxes and aligned tables can drift. Keep every diagram character ASCII.
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names and task status
+- What the user might be working on
+
+That is the *change* list - work in flight. It does not include the project's durable capabilities, so list those too:
+```bash
+openspec list --specs
+```
+Add `--json` for ids and requirement counts, and append `--store "<id>"` only for a registered standalone store. This is the inventory of what the project already claims to do, and `openspec list` on its own never shows it. To look at one, run `openspec show "<spec-id>" --type spec --json --no-scenarios` (same `--store` rule) - it returns that capability's purpose and requirement texts without pulling the whole spec file into context, and `--type spec` stops a change of the same name from making it ambiguous.
+
+The filtered read is only an overview. Before deciding what is already covered or what should change, read each relevant spec in full, including scenarios, with `openspec show "<spec-id>" --type spec` (same `--store` rule).
+
+Then read the project's own context from the resolved root - `<root.path>/openspec/config.yaml` (or `config.yml`). Use the `root.path` returned above, and skip this if neither file exists:
+- `context`: project background - tech stack, conventions, constraints
+- `rules`: keyed by artifact id - the entries for an artifact apply only when you write that artifact
+
+Ground your thinking in these. They are constraints for you to follow, not content to reproduce: do NOT copy them into the conversation or into any artifact you create.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+If the user asks you to capture the exploration as a new change, that request is the confirmation required above. It covers scaffolding that change and creating the change artifacts the request names, and nothing else. This holds only when the request is theirs: a yes to an offer you made confirms only the scope your offer itself named, so name the change and the artifacts in the offer. Don't re-ask for what they already asked for; do ask before anything beyond it. Transition seamlessly into the requested capture:
+
+1. Run `openspec new change "<name>"` (with `--store <id>` when applicable) before creating any artifacts. Never create a new change directory under `openspec/changes/` by hand; the CLI scaffold creates required metadata such as `.openspec.yaml`. Keep the selected `--store <id>` on every applicable follow-up `status` and `instructions` command.
+2. Run `openspec status --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store), then process the requested artifacts in dependency order. For each requested artifact that is `ready`, run `openspec instructions "<artifact-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store). Before creating a requested artifact, evaluate any condition in its own `instruction` against the explored change; record a deliberate skip instead when the condition does not apply. If a requested artifact is blocked by a direct prerequisite the user did not request, run `openspec instructions "<prerequisite-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) for that prerequisite whether it is `ready` or `blocked`. If its own `instruction` states a condition, evaluate that condition against the explored change and record a deliberate skip only when the condition does not apply. If the condition applies, or the prerequisite is not conditional, treat it as a normal prerequisite and ask before expanding the capture. Do not create an unrequested prerequisite unless the user approves.
+3. Follow the returned `template` and `instruction` fields. Read completed dependency files listed in `dependencies`, and apply `context` and `rules` as constraints without copying them into the artifact. Choose the output path before creating anything: when `resolvedOutputPath` is a glob, use the instruction to choose a concrete path inside `changeRoot` and verify it remains inside `changeRoot` after resolving symlinks, both in its parent directories and in the file itself if it already exists; if it does not, stop and tell the user. Otherwise the output path is `resolvedOutputPath`. If the instruction delegates creation to a specific skill or command, invoke it only if it can write the artifact to that output path; otherwise stop and tell the user. Otherwise write the artifact to that output path. Verify that the selected concrete output exists at that output path.
+4. After creating each artifact, re-run `openspec status --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) and continue until every requested artifact is `done`, `skipped`, or was deliberately skipped because its own `instruction` stated a condition that did not apply. Tell the user about a deliberate conditional skip, remember it, and do not reconsider it. Dependencies are enablers, not gates: if a requested artifact is still `blocked` only because you deliberately skipped a conditional prerequisite, run `openspec instructions "<artifact-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) despite the blocked status, then create it using step 3 only when those recorded conditional skips are its sole missing dependencies. If a requested artifact is blocked by a prerequisite the user did not ask to capture and cannot be conditionally skipped, explain that dependency and ask before expanding the capture.
+
+Capture the artifact(s) the user requested without asking them to invoke another workflow command. If they asked only to start a change, stop after scaffolding and show its status. When the requested capture is done, stop there and name where the work continues: `/mate-propose-change` writes the remaining planning artifacts, and `/mate-apply-change` implements the change once tasks exist. Capturing artifacts never starts implementing them.
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Resolve and read existing artifacts for context**
+   - Run `openspec status --change "<name>" --json`.
+   - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
+   - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   `<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve an existing capability's full path and follow the project's established organization for new capabilities.
+
+   The files below are the default spec-driven schema's. With another schema, capture each insight in whichever artifact from `artifactPaths` fits it, and name that artifact in your offer; never create an artifact the schema does not define.
+
+    | Insight Type               | Where to Capture                    |
+    |----------------------------|-------------------------------------|
+    | New requirement discovered | `specs/<capability-path>/spec.md` |
+    | Requirement changed        | `specs/<capability-path>/spec.md` |
+    | Design decision made       | `design.md`                       |
+    | Scope changed              | `proposal.md`                     |
+    | New work identified        | `tasks.md`                        |
+    | Assumption invalidated     | Relevant artifact                   |
+
+   Example offers (default schema):
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ============================================
+
+      Awareness          Coordination         Sync
+          |                   |                 |
+          v                   v                 v
+      +--------+         +--------+        +--------+
+      |Presence|         |Cursors |        |  CRDT  |
+      |  "3    |         | Multi  |        |Conflict|
+      |online" |         | select |        |  free  |
+      +--------+         +--------+        +--------+
+          |                   |                 |
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     +---------------------------------------------+
+     |              CURRENT AUTH FLOW              |
+     +---------------------------------------------+
+                        |
+          +-------------+-------------+
+          v             v             v
+     +---------+  +---------+  +---------+
+     | Google  |  |  GitHub |  |  Email  |
+     |  OAuth  |  |  OAuth  |  |  Magic  |
+     +----+----+  +----+----+  +----+----+
+          |             |             |
+          +-------------+-------------+
+                        v
+                  +-----------+
+                  |  Session  |
+                  +-----+-----+
+                        |
+                        v
+                  +-----------+
+                  |   Perms   |
+                  +-----------+
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /mate-explore-change add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     +-------------------------------------------------+
+     |          CLI TOOL DATA STORAGE                  |
+     +-------------------------------------------------+
+
+     Key constraints:
+     - No daemon running
+     - Must work offline
+     - Single user
+
+                  SQLite          Postgres
+     Deployment   embedded        needs server
+     Offline      yes             no
+     Single file  yes             no
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? Run `/mate-propose-change` and this becomes a change."
+- **Result in artifact updates**: "Updated the design with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Turn this into a change: `/mate-propose-change`
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Workflow configuration counts too: creating or editing schemas, templates, or `openspec/config.yaml` is a change, not thinking. Creating or updating OpenSpec change artifacts within the confirmed scope is fine, writing anything else is not. When the user is ready to build, name the handoff rather than starting: `/mate-propose-change` turns the discussion into a change, and the work happens there.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it. Read-only commands and tools need no confirmation. Before the first write-capable action—including `openspec new change` or another command that writes files—name the artifacts or files and proposed changes, ask a direct yes/no question, and wait for explicit confirmation in a separate user message. That confirmation covers only the described scope; ask again before expanding it. Answers to design or clarifying questions are never consent to write. That rule governs `openspec new change` whenever you are the one proposing the capture; the user's own capture request is the exception, handled in the capture transition above.
+- **Don't manually scaffold changes** - Never create a new change directory under `openspec/changes/` by hand. Always use `openspec new change "<name>"` (with `--store <id>` when applicable) so required metadata such as `.openspec.yaml` is created before writing artifacts.
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

package/src/templates/mate-skills/agents/mate-grill-me/SKILL.md

@@ -11,7 +11,7 @@ metadata:
 
 # Mate Grill Me
 
-This skill runs before `/openspec-explore`. It stress-tests decisions; wide
+This skill runs before `/mate-explore-change`. It stress-tests decisions; wide
 repository investigation and option comparison belong to explore. When a
 question would need mapping large parts of the repository, record it under
 Unresolved or Assumptions in the handoff instead of investigating it.
@@ -30,11 +30,11 @@ PRE-EXPLORE HANDOFF (grill)
 Confirmed:   <accepted decisions>
 Unresolved:  <open questions, or "none">
 Assumptions: <untested assumptions explore should verify, or "none">
-Next: /openspec-explore
+Next: /mate-explore-change
 ```
 
 Confirmed decisions are settled; explore should not ask them again. Then tell
-the user the next step is `/openspec-explore`; do not invoke it. The user starts
+the user the next step is `/mate-explore-change`; do not invoke it. The user starts
 it in this conversation.
 
 If grilling stopped on a blocker, still emit the block. List the blocker first

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

@@ -22,7 +22,7 @@ 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.
 
-This skill runs before `/openspec-explore`. It clarifies intent only: do not read
+This skill runs before `/mate-explore-change`. It clarifies intent only: do not read
 or investigate the repository, and do not compare implementation options. When
 an answer would need repository evidence, record it in the handoff for explore
 instead of looking it up.
@@ -143,11 +143,11 @@ PRE-EXPLORE HANDOFF (interview)
 Confirmed:   <Outcome, User, Why now, Success, Constraint, Out of scope>
 Unresolved:  <open questions, or "none">
 Assumptions: <points explore should verify against the repository, or "none">
-Next: /openspec-explore
+Next: /mate-explore-change
 ```
 
 Confirmed points are settled; explore should not ask them again. Then tell the
-user the next step is `/openspec-explore`; do not invoke it. The user starts it
+user the next step is `/mate-explore-change`; do not invoke it. The user starts it
 in this conversation.
 
 If the session stopped on a blocker, still emit the block. Put only explicitly
@@ -166,7 +166,7 @@ its partial intent, blocker, and unresolved questions in the handoff instead.
 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. The only skill this skill
-names is `/openspec-explore`, as the user's next step.
+names is `/mate-explore-change`, as the user's next step.
 
 ## Verification
 
@@ -184,6 +184,6 @@ Before stopping, check that:
 - The user explicitly confirmed the restatement, or the result is clearly marked
   unresolved because of a blocker.
 - The session ended with the `PRE-EXPLORE HANDOFF` block and named
-  `/openspec-explore` as the next step without invoking it.
+  `/mate-explore-change` as the next step without invoking it.
 - No repository investigation was done; evidence needs went to Unresolved or
   Assumptions.

package/src/templates/mate-skills/agents/mate-propose-change/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: mate-propose-change
+description: Propose a change with its schema chosen by the minimal eligibility test (mate-minimal or mate-v1) and one change per agreed slice. Builds on the OpenSpec propose workflow. Use when the user wants to turn an explored direction into a change proposal, or revise an existing change's plan.
+allowed-tools: Bash(mate:*), Bash(openspec:*), Bash(git:*)
+license: MIT
+compatibility: Requires the mate CLI and the openspec capability enabled.
+metadata:
+  author: mate
+  version: "1.0"
+---
+
+# Mate Propose Change
+
+The Propose change stage of the Delivery Path. It runs the OpenSpec propose workflow
+and adds the schema choice and one change per slice. Its revise mode reworks the plan
+of a change that already exists.
+
+## Step 0: Choose the mode
+
+Use **Revise mode** when the named change already exists, or the user asks to revise,
+reconcile, or fold feedback or new decisions into a change's plan. Otherwise run the
+propose steps below.
+
+## Steps
+
+1. **Choose the schema.** Use `mate-minimal` (specs and tasks only) when every
+   statement holds; otherwise use `mate-v1` (proposal, specs, design, tasks):
+
+   - Intent and scope are clear, with nothing left to explore.
+   - The change stays within one Area.
+   - It is low risk: no new dependency, no data-model or public API change, and no
+     security, performance, or migration concern.
+
+   Public API includes command names, flags, exit codes, JSON output fields, config
+   keys, and exported package symbols.
+
+   State the result and the failing statement, if any, in one line. The user may
+   override it.
+
+2. **One change per slice.** Slicing test: a feature needs slicing when it spans
+   several Areas, several independent behaviours, or more work than one review can
+   hold (roughly more than 10 tasks or 400 changed lines). Several Areas that only
+   work together stay one change with a scope per Area. When exploration agreed on
+   several slices, propose one change per slice, each with its own name. When no
+   slices were agreed, apply the slicing test before writing anything. If it passes,
+   suggest slices in dependency order, naming their `dependsOn` entries, and write no
+   artifact until the user agrees to the slices or keeps one change. If the slice
+   boundaries are unclear, suggest `/mate-explore-change` instead of guessing slices.
+   Record a slice's dependency on an earlier change as a `dependsOn` list in the
+   frontmatter of its first artifact, for example `dependsOn: [add-graph-model]`; archive
+   later warns while a dependency is still unarchived.
+
+3. **Follow the OpenSpec workflow.** Read
+   [references/openspec-propose.md](references/openspec-propose.md) and follow it with the
+   chosen schema (pass `--schema <schema>` when creating the change).
+
+4. **Hand off to human review.** Reviews are done by people, not by a skill. List the
+   artifacts to review in schema order (Review proposal, Review specs, Review design,
+   Review tasks for `mate-v1`; Review specs and Review tasks for `mate-minimal`), then
+   name `/mate-apply-change` as the step after review. Do not invoke it, and never
+   describe validation as approval.
+
+## Revise mode
+
+Revises the planning artifacts a change already has, for example after a person reviewed
+them, and keeps them consistent with each other. In this mode the skill is
+not a Delivery Path stage.
+
+1. **Name the change.** Use the change the user names; otherwise infer it from the
+   conversation, or list the active changes and ask.
+
+2. **Follow the OpenSpec workflow.** Read
+   [references/openspec-update-change.md](references/openspec-update-change.md) and follow
+   it. Propose the requested edit together with the matching edits to the other
+   artifacts, and write each one only after the user confirms it.
+
+3. **Upgrade a minimal change when it outgrows the gate.** When a revision makes a
+   `mate-minimal` change fail a statement of the minimal gate (Step 1), or the user asks,
+   name the failing statement and offer the upgrade to `mate-v1` once. Declined: continue
+   the revision unchanged. Confirmed:
+
+   1. Set `schema: mate-v1` in the change's `.openspec.yaml`, first, so `openspec
+      instructions` returns the `mate-v1` text.
+   2. Write the proposal from the existing specs and tasks, then the design, each from
+      `openspec instructions <artifact-id> --change "<name>" --json` and each confirmed
+      before writing.
+   3. Align `tasks.md`: frontmatter `schema: mate-v1`, the `← [[proposal]] | [[design]]`
+      line after the title, one heading per Area. Keep task numbers and check marks.
+   4. Run `openspec validate "<name>" --strict` and `openspec status --change "<name>"`,
+      and report any artifact still missing.
+
+   This upgrade is the only case in which revise mode creates a missing artifact. Never
+   downgrade a `mate-v1` change; suggest a new change instead.
+
+4. **Hand off.** When the change already has checked tasks, name `/mate-apply-change` to
+   carry the revision into code; when every task is checked, name `/mate-archive-change`.
+   Do not invoke them.
+
+Guardrails:
+
+- Planning artifacts only; never edit product code.
+- Reviews are done by people. Never describe a revision or a passing validation as
+  approval.