@uniqbit/mate-core 0.17.2-canary.3 → 0.18.0-canary.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.17.2-canary.3",
+  "version": "0.18.0-canary.0",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [

package/src/cli/commands/companion/update.ts

@@ -29,7 +29,8 @@ const SKILLS_LOCKFILE = "skills-lock.json";
  * pre-existing uncommitted edits there are stale output, never local work worth separating.
  */
 const OPENSPEC_GENERATED = [
-  /^\.(claude|opencode)\/skills\/openspec-[^/]+(\/|$)/,
+  /^\.(claude|agents|opencode)\/skills\/openspec-[^/]+(\/|$)/,
+  /^\.agents\/skills\/\.openspec-target$/,
   /^\.claude\/commands\/opsx(\/|$)/,
   /^\.opencode\/commands\/opsx-[^/]+$/,
 ];

package/src/cli/commands/install.ts

@@ -166,9 +166,11 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
       );
       if (drift.length > 0) {
         process.stderr.write(
-          `${FRAMEWORK_NAME}: warning: plugin-generated files differ from the committed checkout: ${drift.join(", ")}\n` +
+          `${FRAMEWORK_NAME}: plugin-generated files differ from the committed checkout: ${drift.join(", ")}\n` +
             `Prepare and commit them in the companion's authoring flow; the checkout was left unchanged.\n`,
         );
+        process.exitCode = 1;
+        return false;
       }
     } else {
       await reconcileInstalledCompanion(plan);

package/src/cli/commands/plugin/plugin.ts

@@ -11,7 +11,7 @@ export async function runPluginCommand(
       await runPluginInstallCommand(argv);
       return;
     case "verify":
-      await runPluginVerifyCommand(argv);
+      await runPluginVerifyCommand();
       return;
     default:
       console.error(`Unknown plugin command: ${subcommand ?? ""}`);

package/src/cli/commands/plugin/verify.ts

@@ -1,22 +1,19 @@
 import { FRAMEWORK_NAME } from "../../../framework";
 import { resolveInstallContext } from "../../../lib/install";
-import { inspectDeclaredPlugins } from "../../../tools/setup/dynamic-plugins/verify";
+import { verifyDeclaredPlugins } from "../../../tools/setup/dynamic-plugins/verify";
 
 /**
  * @command mate plugin verify
- * @description Strict, installation-free check that every plugin declared by the companion is installed, and loadable with the current environment. Exits non-zero naming each failing package. With `--json`, prints `{"capabilities": [...]}` listing the capability IDs the verified plugins provide.
+ * @description Strict, installation-free check that every plugin declared by the companion is allowed by `MATE_ALLOWED_PLUGINS`, installed, and loadable with the current environment. Exits non-zero naming each failing package.
  */
-export async function runPluginVerifyCommand(
-  argv: string[] = [],
-  cwd = process.cwd(),
-): Promise<boolean> {
+export async function runPluginVerifyCommand(cwd = process.cwd()): Promise<boolean> {
   const context = await resolveInstallContext(cwd);
   if ((context.kind !== "companion" && context.kind !== "hub") || !context.companionPath) {
     process.stderr.write(`${FRAMEWORK_NAME}: \`plugin verify\` requires a companion context.\n`);
     process.exitCode = 1;
     return false;
   }
-  const { failures, capabilities } = await inspectDeclaredPlugins(context.companionPath);
+  const failures = await verifyDeclaredPlugins(context.companionPath);
   for (const failure of failures) {
     process.stderr.write(`${FRAMEWORK_NAME}: plugin ${failure.package}: ${failure.reason}\n`);
   }
@@ -24,6 +21,5 @@ export async function runPluginVerifyCommand(
     process.exitCode = 1;
     return false;
   }
-  if (argv.includes("--json")) process.stdout.write(`${JSON.stringify({ capabilities })}\n`);
   return true;
 }

package/src/cli/commands/studio/terminal-launch.ts

@@ -1,4 +1,3 @@
-import fs from "node:fs";
 import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
@@ -27,56 +26,11 @@ export async function launchableAgents(
   return TERMINAL_AGENTS.filter((agent) => allowed.includes(agent) && installed(agent));
 }
 
-/** Lowercase letters, digits and hyphens, so a name can never carry shell syntax or a flag. */
-export const AGENT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
-
-const AGENT_DEFINITION_DIRS: Record<TerminalAgent, string> = {
-  claude: path.join(".claude", "agents"),
-  opencode: path.join(".opencode", "agents"),
-};
-
-export interface DefaultAgentOutcome {
-  agentArgs?: string[];
-  notice?: string;
-}
-
-/**
- * The companion's `studio.terminal.agent` for one provider. Never throws and
- * never echoes the configured value into the notice.
- */
-export async function defaultAgentFor(
-  companionPath: string,
-  agent: TerminalAgent,
-): Promise<DefaultAgentOutcome> {
-  const configPath = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
-  if (!fs.existsSync(configPath)) return {};
-  let name: unknown;
-  try {
-    name = (await new ConfigStore(configPath).load()).studio?.terminal?.agent;
-  } catch {
-    return {};
-  }
-  if (name === undefined || name === null) return {};
-  if (typeof name !== "string" || !AGENT_NAME_PATTERN.test(name)) {
-    return {
-      notice: "Default agent not applied: studio.terminal.agent is not a valid agent name.",
-    };
-  }
-  const definition = path.join(companionPath, AGENT_DEFINITION_DIRS[agent], `${name}.md`);
-  if (!fs.existsSync(definition)) {
-    return {
-      notice: `Default agent "${name}" not applied: this companion has no ${agent} definition for it.`,
-    };
-  }
-  return { agentArgs: ["--agent", name] };
-}
-
 export interface LaunchResolverOptions {
   collectInventory: () => Promise<StudioInventory>;
   /** Pinned by `serve --companion`; overrides the page selection. */
   launchCompanion?: string | null;
   launchableAgents?: (companionPath: string) => Promise<TerminalAgent[]>;
-  defaultAgent?: (companionPath: string, agent: TerminalAgent) => Promise<DefaultAgentOutcome>;
 }
 
 /** The companion a launch targets: the pinned one, else the page's, both read from the current inventory. */
@@ -96,7 +50,6 @@ export function createLaunchResolver(
   options: LaunchResolverOptions,
 ): (agent: string, digest: string | null) => Promise<TerminalLaunchResolution> {
   const agents = options.launchableAgents ?? launchableAgents;
-  const defaultAgent = options.defaultAgent ?? defaultAgentFor;
   return async (agent, digest) => {
     const companion = await effectiveLaunchCompanion(
       await options.collectInventory(),
@@ -113,9 +66,6 @@ export function createLaunchResolver(
     if (!(await agents(companion.path)).includes(agent as TerminalAgent)) {
       return { reason: `${agent} is not allowed by this companion or is not installed` };
     }
-    return {
-      companionPath: companion.path,
-      ...(await defaultAgent(companion.path, agent as TerminalAgent)),
-    };
+    return { companionPath: companion.path };
   };
 }

package/src/cli/commands/studio/terminal.ts

@@ -177,15 +177,7 @@ export interface TerminalSessionInfo {
   startedAt: number;
 }
 
-export type TerminalLaunchResolution =
-  | {
-      companionPath: string;
-      /** Extra argv entries for the managed launch; set only by companion configuration. */
-      agentArgs?: string[];
-      /** Written to the terminal before the agent starts. */
-      notice?: string;
-    }
-  | { reason: string };
+export type TerminalLaunchResolution = { companionPath: string } | { reason: string };
 
 export interface TerminalRegistryOptions {
   detachMs: number;
@@ -396,7 +388,7 @@ export class TerminalRegistry {
       void this.finish(detached, { type: "ended", reason: "evicted" });
     }
 
-    const session = this.launch(agent, resolved.companionPath, size, resolved);
+    const session = this.launch(agent, resolved.companionPath, size);
     this.attachTo(connection, session, size);
   }
 
@@ -404,7 +396,6 @@ export class TerminalRegistry {
     agent: TerminalAgent,
     companionPath: string,
     size: { cols: number; rows: number },
-    extras: { agentArgs?: string[]; notice?: string } = {},
   ): Session {
     const env: Record<string, string> = {};
     for (const [key, value] of Object.entries(this.options.env ?? process.env)) {
@@ -422,7 +413,6 @@ export class TerminalRegistry {
       "--companion",
       "--yes",
       ...(this.options.noGit ? ["--no-git"] : []),
-      ...(extras.agentArgs ?? []),
     ];
 
     const session = {
@@ -437,7 +427,6 @@ export class TerminalRegistry {
       ending: null,
       exited: false,
     } as Omit<Session, "process"> as Session;
-    if (extras.notice) session.ring.push(new TextEncoder().encode(`${extras.notice}\r\n`));
     session.process = this.spawn({
       argv,
       cwd: companionPath,

package/src/lib/install.ts

@@ -228,6 +228,9 @@ export async function runInstallPlan(
 ): Promise<{ ok: boolean; results: InstallRequirementResult[] }> {
   const results: InstallRequirementResult[] = [];
   let ok = true;
+  await Promise.all(
+    plan.requirements.map((item) => (item.satisfied ? item.update?.().catch(() => {}) : undefined)),
+  );
   for (const item of plan.requirements) {
     options.onStart?.(item);
     if (item.satisfied) {

package/src/lib/orchestrator/types.ts

@@ -120,11 +120,6 @@ export interface PluginDeclaration {
   config?: unknown;
 }
 
-export interface StudioTerminalConfig {
-  /** Persona selected with `--agent` when Studio's terminal starts a provider. */
-  agent?: string;
-}
-
 export interface FrameworkConfig {
   type?: FrameworkType;
   git?: GitModeProfile;
@@ -136,7 +131,6 @@ export interface FrameworkConfig {
   cliTools?: CliToolConfig[];
   packageManagers?: string[];
   engines?: EngineConstraints;
-  studio?: { terminal?: StudioTerminalConfig };
 }
 
 export interface CompanionRegistryConfig {

package/src/templates/mate-skills/agents/mate-domain-modeling/SKILL.md

@@ -2,12 +2,15 @@
 name: mate-domain-modeling
 description: Build a project domain model using Mate context-map scope and Companion Repository artifacts.
 disable-model-invocation: true
+metadata:
+  credits:
+    skill: domain-modeling
+    author: Matt Pocock
+    url: "https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/SKILL.md"
 ---
 
 # Mate Domain Modeling
 
-> Inspired by [Matt Pocock's domain-modeling skill](https://github.com/mattpocock/skills/tree/main/skills/engineering/domain-modeling) and adapted here as a Mate process-driven skill.
-
 Actively sharpen project terminology and durable domain decisions. Reading a
 context for vocabulary is not enough: challenge fuzzy terms, test boundaries
 with concrete scenarios, and ask the user to confirm each proposed definition

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

@@ -2,12 +2,15 @@
 name: mate-grill-me
 description: Stress-test a plan or idea through dependency-ordered conversational design-tree rounds.
 disable-model-invocation: true
+metadata:
+  credits:
+    skill: grill-me
+    author: Matt Pocock
+    url: "https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md"
 ---
 
 # Mate Grill Me
 
-> Inspired by [Matt Pocock's grill-me skill](https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me) and adapted here as a Mate process-driven skill.
-
 Start `/mate-grilling`.
 
 The session is conversational-only. It does not create or modify code, context

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

@@ -2,12 +2,15 @@
 name: mate-grill-with-docs
 description: Sharpen a design conversationally and record confirmed domain decisions on the Companion Repository artifact plane.
 disable-model-invocation: true
+metadata:
+  credits:
+    skill: grill-with-docs
+    author: Matt Pocock
+    url: "https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md"
 ---
 
 # Mate Grill With Docs
 
-> Inspired by [Matt Pocock's grill-with-docs skill](https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs) and adapted here as a Mate process-driven skill.
-
 First invoke `/mate-grilling` and wait for explicit decisions. Then invoke
 `/mate-domain-modeling` only for confirmed project terminology or durable
 decisions.

package/src/templates/mate-skills/agents/mate-grilling/SKILL.md

@@ -2,12 +2,15 @@
 name: mate-grilling
 description: Relentlessly sharpen a plan through dependency-ordered design-tree rounds.
 disable-model-invocation: true
+metadata:
+  credits:
+    skill: grilling
+    author: Matt Pocock
+    url: "https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md"
 ---
 
 # Mate Grilling
 
-> Inspired by [Matt Pocock's grilling skill](https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling) and adapted here as a Mate process-driven skill.
-
 Stress-test the current plan or idea as a design tree. This is a conversation,
 not an implementation or documentation session: do not create or modify code,
 context files, ADRs, OpenSpec artifacts, or other files.

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

@@ -2,12 +2,15 @@
 name: mate-interview-me
 description: Clarify intent through a focused, one-question-at-a-time conversation before planning.
 disable-model-invocation: true
+metadata:
+  credits:
+    skill: interview-me
+    author: Addy Osmani
+    url: "https://github.com/addyosmani/agent-skills/blob/main/skills/interview-me/SKILL.md"
 ---
 
 # 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

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

@@ -8,12 +8,15 @@ compatibility: Requires the mate CLI and the openspec capability enabled.
 metadata:
   author: mate
   version: "1.0"
+  credits:
+    skill: show-me
+    author: Dex Horthy
+    organisation: Humanlayer
+    url: "https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md"
 ---
 
 # 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

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

@@ -2,12 +2,15 @@
 name: mate-simplify-code
 description: Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity.
 disable-model-invocation: true
+metadata:
+  credits:
+    skill: code-simplification
+    author: Addy Osmani
+    url: "https://github.com/addyosmani/agent-skills/blob/main/skills/code-simplification/SKILL.md"
 ---
 
 # Mate Simplify Code
 
-> Inspired by [Addy Osmani's code-simplification skill](https://github.com/addyosmani/agent-skills/tree/main/skills/code-simplification) and adapted here as a Mate process-driven skill.
-
 ## Overview
 
 Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"

package/src/templates/mate-skills/claude/mate-domain-modeling/SKILL.md

@@ -2,12 +2,15 @@
 name: mate-domain-modeling
 description: Build a project domain model using Mate context-map scope and Companion Repository artifacts.
 disable-model-invocation: true
+metadata:
+  credits:
+    skill: domain-modeling
+    author: Matt Pocock
+    url: "https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/SKILL.md"
 ---
 
 # Mate Domain Modeling
 
-> Inspired by [Matt Pocock's domain-modeling skill](https://github.com/mattpocock/skills/tree/main/skills/engineering/domain-modeling) and adapted here as a Mate process-driven skill.
-
 Actively sharpen project terminology and durable domain decisions. Reading a
 context for vocabulary is not enough: challenge fuzzy terms, test boundaries
 with concrete scenarios, and ask the user to confirm each proposed definition

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

@@ -2,12 +2,15 @@
 name: mate-grill-me
 description: Stress-test a plan or idea through dependency-ordered conversational design-tree rounds.
 disable-model-invocation: true
+metadata:
+  credits:
+    skill: grill-me
+    author: Matt Pocock
+    url: "https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md"
 ---
 
 # Mate Grill Me
 
-> Inspired by [Matt Pocock's grill-me skill](https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me) and adapted here as a Mate process-driven skill.
-
 Start `/mate-grilling`.
 
 The session is conversational-only. It does not create or modify code, context

package/src/templates/mate-skills/claude/mate-grill-with-docs/SKILL.md

@@ -2,12 +2,15 @@
 name: mate-grill-with-docs
 description: Sharpen a design conversationally and record confirmed domain decisions on the Companion Repository artifact plane.
 disable-model-invocation: true
+metadata:
+  credits:
+    skill: grill-with-docs
+    author: Matt Pocock
+    url: "https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md"
 ---
 
 # Mate Grill With Docs
 
-> Inspired by [Matt Pocock's grill-with-docs skill](https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs) and adapted here as a Mate process-driven skill.
-
 First invoke `/mate-grilling` and wait for explicit decisions. Then invoke
 `/mate-domain-modeling` only for confirmed project terminology or durable
 decisions.

package/src/templates/mate-skills/claude/mate-grilling/SKILL.md

@@ -2,12 +2,15 @@
 name: mate-grilling
 description: Relentlessly sharpen a plan through dependency-ordered design-tree rounds.
 disable-model-invocation: true
+metadata:
+  credits:
+    skill: grilling
+    author: Matt Pocock
+    url: "https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md"
 ---
 
 # Mate Grilling
 
-> Inspired by [Matt Pocock's grilling skill](https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling) and adapted here as a Mate process-driven skill.
-
 Stress-test the current plan or idea as a design tree. This is a conversation,
 not an implementation or documentation session: do not create or modify code,
 context files, ADRs, OpenSpec artifacts, or other files.

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

@@ -2,12 +2,15 @@
 name: mate-interview-me
 description: Clarify intent through a focused, one-question-at-a-time conversation before planning.
 disable-model-invocation: true
+metadata:
+  credits:
+    skill: interview-me
+    author: Addy Osmani
+    url: "https://github.com/addyosmani/agent-skills/blob/main/skills/interview-me/SKILL.md"
 ---
 
 # 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

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

@@ -8,12 +8,15 @@ compatibility: Requires the mate CLI and the openspec capability enabled.
 metadata:
   author: mate
   version: "1.0"
+  credits:
+    skill: show-me
+    author: Dex Horthy
+    organisation: Humanlayer
+    url: "https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md"
 ---
 
 # 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

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

@@ -2,12 +2,15 @@
 name: mate-simplify-code
 description: Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity.
 disable-model-invocation: true
+metadata:
+  credits:
+    skill: code-simplification
+    author: Addy Osmani
+    url: "https://github.com/addyosmani/agent-skills/blob/main/skills/code-simplification/SKILL.md"
 ---
 
 # Mate Simplify Code
 
-> Inspired by [Addy Osmani's code-simplification skill](https://github.com/addyosmani/agent-skills/tree/main/skills/code-simplification) and adapted here as a Mate process-driven skill.
-
 ## Overview
 
 Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"