@uniqbit/mate-core 0.15.0 → 0.15.1-canary.1

package/src/tools/setup/capabilities/context-mode.ts

@@ -0,0 +1,197 @@
+// oxlint-disable no-await-in-loop -- config files are reconciled sequentially with shared ownership state
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  CONTEXT_MODE_PACKAGE_NAME,
+  getContextModeInstallDir,
+  getContextModePackageReference,
+  installContextModePackage,
+  isContextModePackageReference,
+  validateContextModePackage,
+} from "../../../lib/context-mode-package";
+import { warmOpenCodePackageCache } from "../../../lib/opencode-plugin-package";
+import type { CapabilityPlugin, LaunchPreflightContext, SetupContext } from "../plugin";
+import { pruneEmptyAncestors } from "../utils";
+
+type Config = Record<string, unknown>;
+interface ContextModePluginDeps {
+  installPackage?: typeof installContextModePackage;
+  validatePackage?: typeof validateContextModePackage;
+  warmOpenCodePackage?: typeof warmOpenCodePackageCache;
+}
+interface OwnershipState {
+  opencodeConfigs: string[];
+}
+
+export const CONTEXT_MODE_OPENCODE_GUIDANCE = `## Context Mode
+
+Use Context Mode tools for commands or tool calls whose output may be large, for sandboxed analysis of large files or structured data, and when indexing large fetched content.
+
+Canonical Mate policy and any more specific tool-routing instructions remain authoritative. In particular, follow explicit requirements to use TokenSave for codebase exploration, Context7 for library documentation, and specialized tools for their assigned operations; Context Mode complements rather than replaces them.`;
+
+function getOwnershipPath(companionPath: string): string {
+  return path.join(companionPath, ".mate", "state", "context-mode.json");
+}
+
+async function readOwnership(companionPath: string): Promise<OwnershipState> {
+  try {
+    return JSON.parse(await fs.readFile(getOwnershipPath(companionPath), "utf8")) as OwnershipState;
+  } catch {
+    return { opencodeConfigs: [] };
+  }
+}
+
+async function writeOwnership(companionPath: string, state: OwnershipState): Promise<void> {
+  const statePath = getOwnershipPath(companionPath);
+  if (state.opencodeConfigs.length === 0) {
+    await fs.rm(statePath, { force: true });
+    return;
+  }
+  await fs.mkdir(path.dirname(statePath), { recursive: true });
+  await fs.writeFile(statePath, JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+
+function isRecord(value: unknown): value is Config {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function readConfig(filePath: string): Promise<Config> {
+  try {
+    const parsed = JSON.parse(await fs.readFile(filePath, "utf8")) as unknown;
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function hasContextModeMcp(config: Config): boolean {
+  const servers = isRecord(config.mcpServers)
+    ? config.mcpServers
+    : isRecord(config.mcp)
+      ? config.mcp
+      : {};
+  return Object.entries(servers).some(
+    ([name, value]) =>
+      name.toLowerCase().includes("context-mode") || JSON.stringify(value).includes("context-mode"),
+  );
+}
+
+async function assertNoMcpConflict(ctx: SetupContext, provider: "claude" | "opencode") {
+  const configPath =
+    provider === "claude"
+      ? path.join(ctx.companionPath, ".mcp.json")
+      : path.join(ctx.companionPath, ".opencode", "opencode.json");
+  if (hasContextModeMcp(await readConfig(configPath))) {
+    throw new Error(
+      `Cannot enable context-mode for ${provider}: ${configPath} already contains a context-mode MCP registration. Remove the duplicate registration or deselect the context-mode capability; Mate did not modify it.`,
+    );
+  }
+}
+
+async function updateOpenCodeConfig(ctx: SetupContext, enabled: boolean): Promise<void> {
+  const reference = getContextModePackageReference();
+  const ownership = await readOwnership(ctx.companionPath);
+  for (const name of ["opencode.json", "tui.json"]) {
+    const configPath = path.join(ctx.companionPath, ".opencode", name);
+    const owned = ownership.opencodeConfigs.includes(name);
+    if (!enabled && !owned) continue;
+    const config = await readConfig(configPath);
+    const plugins = Array.isArray(config.plugin) ? config.plugin : [];
+    const contextModeReferences = plugins.filter(isContextModePackageReference);
+    if (enabled && contextModeReferences.some((entry) => entry !== reference)) {
+      throw new Error(
+        `Cannot enable ${reference}: ${configPath} contains user-owned context-mode reference ${contextModeReferences.join(", ")}. Mate did not modify it.`,
+      );
+    }
+    const preserved = plugins.filter((entry) => !(entry === reference && owned));
+    if (enabled) {
+      if (!contextModeReferences.includes(reference)) {
+        config.plugin = [...plugins, reference];
+        ownership.opencodeConfigs.push(name);
+      }
+    } else if (preserved.length > 0) {
+      config.plugin = preserved;
+    } else {
+      delete config.plugin;
+    }
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+  }
+  if (!enabled) ownership.opencodeConfigs = [];
+  await writeOwnership(ctx.companionPath, ownership);
+}
+
+async function validateOpenCodeReferences(ctx: LaunchPreflightContext): Promise<string[]> {
+  const expected = getContextModePackageReference();
+  const diagnostics: string[] = [];
+  for (const name of ["opencode.json", "tui.json"]) {
+    const configPath = path.join(ctx.companionPath, ".opencode", name);
+    const config = await readConfig(configPath);
+    const plugins = Array.isArray(config.plugin) ? config.plugin : [];
+    if (!plugins.includes(expected)) {
+      diagnostics.push(
+        `Missing or stale context-mode package reference in ${configPath}; expected ${expected}.`,
+      );
+    }
+  }
+  return diagnostics;
+}
+
+export function createContextModePlugin(deps: ContextModePluginDeps = {}): CapabilityPlugin {
+  const installPackage = deps.installPackage ?? installContextModePackage;
+  const validatePackage = deps.validatePackage ?? validateContextModePackage;
+  const warmOpenCodePackage = deps.warmOpenCodePackage ?? warmOpenCodePackageCache;
+  return {
+    id: "context-mode",
+    kind: "capability",
+    label: "Context Mode",
+    description: "Protect context windows with pinned native Claude and OpenCode plugins.",
+    defaultSelected: false,
+    isEnabled: (config) =>
+      (config.capabilities ?? []).some((capability) => capability.name === "context-mode"),
+    async apply(ctx) {
+      if (ctx.mode === "setup") {
+        await installPackage(ctx.companionPath);
+      } else {
+        await validatePackage(ctx.companionPath);
+      }
+      await ctx.instructions?.append(CONTEXT_MODE_OPENCODE_GUIDANCE, {
+        providers: ["opencode"],
+      });
+    },
+    async teardown(ctx) {
+      await fs.rm(getContextModeInstallDir(ctx.companionPath), { recursive: true, force: true });
+      await pruneEmptyAncestors(getContextModeInstallDir(ctx.companionPath), ctx.companionPath);
+    },
+    forProvider: {
+      claude: {
+        async apply(ctx) {
+          await assertNoMcpConflict(ctx, "claude");
+        },
+        async teardown() {},
+      },
+      opencode: {
+        preflight: validateOpenCodeReferences,
+        async apply(ctx) {
+          await assertNoMcpConflict(ctx, "opencode");
+          await updateOpenCodeConfig(ctx, true);
+          if (ctx.mode === "setup") {
+            const result = await warmOpenCodePackage(
+              CONTEXT_MODE_PACKAGE_NAME,
+              getContextModePackageReference(),
+            );
+            if (!result.ok) {
+              process.stderr.write(
+                `mate: could not pre-fetch ${getContextModePackageReference()} for OpenCode: ${result.detail ?? "unknown error"}\n`,
+              );
+            }
+          }
+        },
+        async teardown(ctx) {
+          await updateOpenCodeConfig(ctx, false);
+        },
+      },
+    },
+  };
+}

package/src/tools/setup/capabilities/graphify.ts

@@ -72,7 +72,7 @@ const CLAUDE_MANAGED_HOOK_COMMAND_SUFFIXES = new Set([
   "/.claude/hooks/validate-artifact-path",
   "/.claude/hooks/mate-session-banner",
   "/.claude/hooks/react-doctor.sh",
-  "/.claude/hooks/mate-openspec-artifact-finish.sh",
+  "/.claude/hooks/mate-artifact-finish.sh",
 ]);
 
 export function deriveGraphifyProviders(activeProviders: string[]): string[] {

package/src/tools/setup/capabilities/headroom.ts

@@ -1,6 +1,6 @@
-import type { CapabilityPlugin, SetupContext } from "../plugin";
+import type { CapabilityPlugin } from "../plugin";
 import type { InstallRequirement } from "../install-contract";
-import { isCommandOnPath, runShellCommand, runShellCommandSilently } from "../utils";
+import { isCommandOnPath, runShellCommand } from "../utils";
 import { confirm } from "../../../cli/confirm";
 import { isInstalledViaUvTool } from "../package-managers/uv";
 
@@ -8,55 +8,16 @@ const HEADROOM_GITIGNORE_ENTRIES = ["# headroom", ".headroom/"];
 
 const HEADROOM_INSTALL_CMD = `uv tool install --python ">=3.13" "headroom-ai[all]"`;
 
-const RTK_INSTALL_CMD_BREW = "brew install rtk-ai/tap/rtk";
-const RTK_INSTALL_CMD_FALLBACK = "curl -fsSL https://rtk.ai/install | bash";
-
-function defaultIsRtkOnPath(): boolean {
-  const pathValue = process.env.PATH ?? "";
-  return isCommandOnPath("rtk", pathValue);
-}
-
-function defaultIsBrewAvailable(): boolean {
-  const pathValue = process.env.PATH ?? "";
-  return isCommandOnPath("brew", pathValue);
-}
-
-const RTK_INIT_COMMANDS: Record<string, string> = {
-  claude: "rtk init -g --auto-patch",
-  opencode: "rtk init -g --opencode --auto-patch",
-};
-
-const RTK_UNINSTALL_COMMANDS: Record<string, string> = {
-  claude: "rtk init -g --uninstall",
-  opencode: "rtk init -g --uninstall --opencode",
-};
-
 type HeadroomDeps = {
   confirm?: typeof confirm;
   isCommandOnPath?: typeof isCommandOnPath;
   isInstalledViaUvTool?: (pkgName: string) => boolean;
-  isRtkOnPath?: () => boolean;
-  isBrewAvailable?: () => boolean;
-  runRtkInstallCmd?: (cmd: string) => Promise<void>;
-  runShellCommandSilently?: (cmd: string) => Promise<void>;
 };
 
 export function createHeadroomPlugin(deps: HeadroomDeps = {}): CapabilityPlugin {
   const askConfirm = deps.confirm ?? confirm;
   const checkPath = deps.isCommandOnPath ?? isCommandOnPath;
   const checkUvTool = deps.isInstalledViaUvTool ?? isInstalledViaUvTool;
-  const checkRtkPath = deps.isRtkOnPath ?? defaultIsRtkOnPath;
-  const checkBrew = deps.isBrewAvailable ?? defaultIsBrewAvailable;
-  const runRtkInstall = deps.runRtkInstallCmd ?? runShellCommand;
-  const runSilently = deps.runRtkInstallCmd ?? runShellCommandSilently;
-
-  const hasOtherActiveRtkProvider = (
-    currentProviderId: string,
-    activeProviders: string[],
-  ): boolean =>
-    Object.keys(RTK_INIT_COMMANDS).some(
-      (pid) => pid !== currentProviderId && activeProviders.includes(pid),
-    );
 
   return {
     id: "headroom",
@@ -78,75 +39,19 @@ export function createHeadroomPlugin(deps: HeadroomDeps = {}): CapabilityPlugin
         install: () => runShellCommand(HEADROOM_INSTALL_CMD),
         verify: () => checkPath("headroom", process.env.PATH ?? "") || checkUvTool("headroom-ai"),
       },
-      {
-        id: "capability:rtk",
-        label: "RTK CLI",
-        group: "companion",
-        source: "Headroom capability",
-        command: checkBrew() ? RTK_INSTALL_CMD_BREW : RTK_INSTALL_CMD_FALLBACK,
-        fingerprint: `rtk:${checkBrew() ? RTK_INSTALL_CMD_BREW : RTK_INSTALL_CMD_FALLBACK}`,
-        detect: checkRtkPath,
-        install: () => runRtkInstall(checkBrew() ? RTK_INSTALL_CMD_BREW : RTK_INSTALL_CMD_FALLBACK),
-        verify: checkRtkPath,
-      },
     ],
     async apply(ctx) {
       const pathValue = process.env.PATH ?? "";
-      let isHeadroomInstalled = checkPath("headroom", pathValue) || checkUvTool("headroom-ai");
+      const isHeadroomInstalled = checkPath("headroom", pathValue) || checkUvTool("headroom-ai");
 
       if (!isHeadroomInstalled && ctx.mode === "setup") {
         process.stdout.write(`headroom binary not found. To install:\n  ${HEADROOM_INSTALL_CMD}\n`);
         const ok = await askConfirm("Run this install command now?");
         if (ok) {
           await runShellCommand(HEADROOM_INSTALL_CMD);
-          isHeadroomInstalled = true;
-        }
-      }
-
-      if (!isHeadroomInstalled) {
-        return;
-      }
-
-      let isRtkInstalled = checkRtkPath();
-      if (!isRtkInstalled && ctx.mode === "setup") {
-        const useBrew = checkBrew();
-        const rtkCmd = useBrew ? RTK_INSTALL_CMD_BREW : RTK_INSTALL_CMD_FALLBACK;
-        process.stdout.write(`rtk binary not found. To install:\n  ${rtkCmd}\n`);
-        const ok = await askConfirm("Run this install command now?");
-        if (ok) {
-          await runRtkInstall(rtkCmd);
-          isRtkInstalled = true;
         }
       }
     },
     async teardown(_ctx) {},
-    forProvider: {
-      claude: {
-        async apply(ctx: SetupContext) {
-          if (checkRtkPath()) {
-            const exec = ctx.mode === "sync" ? runSilently : runRtkInstall;
-            await exec(RTK_INIT_COMMANDS.claude);
-          }
-        },
-        async teardown(ctx: SetupContext) {
-          if (checkRtkPath() && !hasOtherActiveRtkProvider("claude", ctx.activeProviders)) {
-            await runRtkInstall(RTK_UNINSTALL_COMMANDS.claude);
-          }
-        },
-      },
-      opencode: {
-        async apply(ctx: SetupContext) {
-          if (checkRtkPath()) {
-            const exec = ctx.mode === "sync" ? runSilently : runRtkInstall;
-            await exec(RTK_INIT_COMMANDS.opencode);
-          }
-        },
-        async teardown(ctx: SetupContext) {
-          if (checkRtkPath() && !hasOtherActiveRtkProvider("opencode", ctx.activeProviders)) {
-            await runRtkInstall(RTK_UNINSTALL_COMMANDS.opencode);
-          }
-        },
-      },
-    },
   };
 }

package/src/tools/setup/capabilities/openspec.ts

@@ -29,7 +29,8 @@ export const OPENSPEC_SKILLS = [
 
 // Mate-authored skills (not generated by the openspec CLI) that ship alongside the
 // openspec workflow skills and are installed per active provider.
-export const MATE_OPENSPEC_SKILLS = ["mate-openspec-artifact-finish"] as const;
+export const MATE_ARTIFACT_SKILLS = ["mate-artifact-finish"] as const;
+const LEGACY_CLAUDE_STATE_PATTERN = /^mate-artifact-finish\..+\.json$/;
 
 const MATE_SKILLS_SOURCE = path.join(
   import.meta.dirname,
@@ -43,7 +44,7 @@ const MATE_V1_SCHEMA_SOURCE = path.join(
 
 const CLAUDE_HOOK_SOURCE = path.join(
   import.meta.dirname,
-  "../../../templates/capabilities/openspec-cap/claude/hooks/mate-openspec-artifact-finish.sh",
+  "../../../templates/capabilities/openspec-cap/claude/hooks/mate-artifact-finish.sh",
 );
 
 const OPENSPEC_TOOL_DIRS = {
@@ -108,7 +109,7 @@ export async function teardownOpenspecSkills(
   skillsDir: string,
   companionPath: string,
 ): Promise<void> {
-  for (const skill of [...OPENSPEC_SKILLS, ...MATE_OPENSPEC_SKILLS]) {
+  for (const skill of [...OPENSPEC_SKILLS, ...MATE_ARTIFACT_SKILLS]) {
     try {
       await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
     } catch {
@@ -119,7 +120,7 @@ export async function teardownOpenspecSkills(
 }
 
 async function teardownMateOpenspecSkills(skillsDir: string, companionPath: string): Promise<void> {
-  for (const skill of MATE_OPENSPEC_SKILLS) {
+  for (const skill of MATE_ARTIFACT_SKILLS) {
     try {
       await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
     } catch {
@@ -139,7 +140,7 @@ async function applyMateOpenspecSkills(
 ): Promise<void> {
   for (const tool of tools) {
     const skillsDir = getSkillsDir(companionPath, tool);
-    for (const skill of MATE_OPENSPEC_SKILLS) {
+    for (const skill of MATE_ARTIFACT_SKILLS) {
       await mergeDir(path.join(MATE_SKILLS_SOURCE, skill), path.join(skillsDir, skill));
     }
   }
@@ -365,16 +366,28 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
             ctx.companionPath,
             ".claude",
             "hooks",
-            "mate-openspec-artifact-finish.sh",
+            "mate-artifact-finish.sh",
           );
           await fs.mkdir(path.dirname(hookDest), { recursive: true });
           await fs.copyFile(CLAUDE_HOOK_SOURCE, hookDest);
           await fs.chmod(hookDest, 0o755);
+          const stateDir = path.join(ctx.companionPath, ".claude", "state");
+          try {
+            const entries = await fs.readdir(stateDir);
+            await Promise.all(
+              entries
+                .filter((entry) => LEGACY_CLAUDE_STATE_PATTERN.test(entry))
+                .map((entry) => fs.unlink(path.join(stateDir, entry))),
+            );
+            await pruneEmptyAncestors(stateDir, ctx.companionPath);
+          } catch {
+            /* no legacy state */
+          }
         },
         async teardown(ctx: SetupContext) {
           try {
             await fs.unlink(
-              path.join(ctx.companionPath, ".claude", "hooks", "mate-openspec-artifact-finish.sh"),
+              path.join(ctx.companionPath, ".claude", "hooks", "mate-artifact-finish.sh"),
             );
           } catch {
             /* not present */

package/src/tools/setup/capabilities/rtk.ts

@@ -0,0 +1,107 @@
+import type { CapabilityPlugin, SetupContext } from "../plugin";
+import type { InstallRequirement } from "../install-contract";
+import { isCommandOnPath, runShellCommand, runShellCommandSilently } from "../utils";
+import { confirm } from "../../../cli/confirm";
+
+export const RTK_INSTALL_CMD_BREW = "brew install rtk-ai/tap/rtk";
+export const RTK_INSTALL_CMD_FALLBACK = "curl -fsSL https://rtk.ai/install | bash";
+
+const RTK_INIT_COMMANDS: Record<string, string> = {
+  claude: "rtk init -g --auto-patch",
+  opencode: "rtk init -g --opencode --auto-patch",
+};
+
+const RTK_UNINSTALL_COMMANDS: Record<string, string> = {
+  claude: "rtk init -g --uninstall",
+  opencode: "rtk init -g --uninstall --opencode",
+};
+
+function defaultIsRtkOnPath(): boolean {
+  return isCommandOnPath("rtk", process.env.PATH ?? "");
+}
+
+function defaultIsBrewAvailable(): boolean {
+  return isCommandOnPath("brew", process.env.PATH ?? "");
+}
+
+export type RtkDeps = {
+  confirm?: typeof confirm;
+  isRtkOnPath?: () => boolean;
+  isBrewAvailable?: () => boolean;
+  runRtkInstallCmd?: (cmd: string) => Promise<void>;
+  runRtkCommandSilently?: (cmd: string) => Promise<void>;
+};
+
+export function createRtkPlugin(deps: RtkDeps = {}): CapabilityPlugin {
+  const askConfirm = deps.confirm ?? confirm;
+  const checkRtkPath = deps.isRtkOnPath ?? defaultIsRtkOnPath;
+  const checkBrew = deps.isBrewAvailable ?? defaultIsBrewAvailable;
+  const runRtkInstall = deps.runRtkInstallCmd ?? runShellCommand;
+  const runSilently = deps.runRtkCommandSilently ?? runShellCommandSilently;
+  const hasOtherActiveRtkProvider = (currentProviderId: string, activeProviders: string[]) =>
+    Object.keys(RTK_INIT_COMMANDS).some(
+      (providerId) => providerId !== currentProviderId && activeProviders.includes(providerId),
+    );
+
+  return {
+    id: "rtk",
+    kind: "capability",
+    label: "RTK",
+    description: "Patch supported agent providers with RTK when selected.",
+    defaultSelected: false,
+    isEnabled: (config) =>
+      (config.capabilities ?? []).some((capability) => capability.name === "rtk"),
+    getInstallRequirements: (): InstallRequirement[] => {
+      const command = checkBrew() ? RTK_INSTALL_CMD_BREW : RTK_INSTALL_CMD_FALLBACK;
+      return [
+        {
+          id: "capability:rtk",
+          label: "RTK CLI",
+          group: "companion",
+          source: "RTK capability",
+          command,
+          fingerprint: `rtk:${command}`,
+          detect: checkRtkPath,
+          install: () => runRtkInstall(command),
+          verify: checkRtkPath,
+        },
+      ];
+    },
+    async apply(ctx) {
+      if (checkRtkPath() || ctx.mode !== "setup") return;
+
+      const command = checkBrew() ? RTK_INSTALL_CMD_BREW : RTK_INSTALL_CMD_FALLBACK;
+      process.stdout.write(`rtk binary not found. To install:\n  ${command}\n`);
+      if (await askConfirm("Run this install command now?")) {
+        await runRtkInstall(command);
+      }
+    },
+    async teardown(_ctx) {},
+    forProvider: {
+      claude: {
+        async apply(ctx: SetupContext) {
+          if (!checkRtkPath()) return;
+          const run = ctx.mode === "sync" ? runSilently : runRtkInstall;
+          await run(RTK_INIT_COMMANDS.claude);
+        },
+        async teardown(ctx: SetupContext) {
+          if (checkRtkPath() && !hasOtherActiveRtkProvider("claude", ctx.activeProviders)) {
+            await runRtkInstall(RTK_UNINSTALL_COMMANDS.claude);
+          }
+        },
+      },
+      opencode: {
+        async apply(ctx: SetupContext) {
+          if (!checkRtkPath()) return;
+          const run = ctx.mode === "sync" ? runSilently : runRtkInstall;
+          await run(RTK_INIT_COMMANDS.opencode);
+        },
+        async teardown(ctx: SetupContext) {
+          if (checkRtkPath() && !hasOtherActiveRtkProvider("opencode", ctx.activeProviders)) {
+            await runRtkInstall(RTK_UNINSTALL_COMMANDS.opencode);
+          }
+        },
+      },
+    },
+  };
+}

package/src/tools/setup/context-services.ts

@@ -234,8 +234,12 @@ export class ContextServiceMediator {
     };
 
     const instructions: InstructionsService = {
-      append: async (content: string) => {
-        const hosts = hostingProviders.filter((provider) => provider.hosting.instructions);
+      append: async (content: string, options) => {
+        const hosts = hostingProviders.filter(
+          (provider) =>
+            provider.hosting.instructions &&
+            (options?.providers === undefined || options.providers.includes(provider.id)),
+        );
         if (hosts.length === 0) {
           warn(`${pluginId}: no active provider hosts instruction injection; skipping append`);
           return;

package/src/tools/setup/plugin.ts

@@ -1,4 +1,4 @@
-import type { FrameworkConfig } from "../../lib/orchestrator/types";
+import type { FrameworkConfig, LinkedRepository } from "../../lib/orchestrator/types";
 import type { InstallRequirement, InstallRequirementContext } from "./install-contract";
 
 export interface SetupContext {
@@ -18,6 +18,13 @@ export interface SetupContext {
   templates?: TemplatesService;
 }
 
+export interface LaunchPreflightContext {
+  companionPath: string;
+  config: FrameworkConfig;
+  repository: LinkedRepository;
+  providerId: string;
+}
+
 /** Provider-agnostic description of an MCP server to register. */
 export interface McpServerDescriptor {
   name: string;
@@ -32,7 +39,7 @@ export interface McpService {
 }
 
 export interface InstructionsService {
-  append(content: string): Promise<void>;
+  append(content: string, options?: { providers?: string[] }): Promise<void>;
 }
 
 export interface TemplatesService {
@@ -113,6 +120,7 @@ export interface CapabilityPlugin extends Plugin {
     {
       apply(ctx: SetupContext): Promise<void>;
       teardown(ctx: SetupContext): Promise<void>;
+      preflight?(ctx: LaunchPreflightContext): Promise<string[]>;
     }
   >;
 }

package/src/tools/setup/providers/claude.ts

@@ -46,7 +46,7 @@ const MANAGED_HOOK_MARKERS = [
   "validate-artifact-path",
   "mate-session-banner",
   "react-doctor.sh",
-  "mate-openspec-artifact-finish.sh",
+  "mate-artifact-finish.sh",
   "tokensave",
 ];
 
@@ -71,12 +71,12 @@ function getCapabilityPermissionEntries(): Record<string, string[]> {
       "Skill(openspec-propose)",
       "Skill(openspec-apply-change)",
       "Skill(openspec-archive-change)",
-      "Skill(mate-openspec-artifact-finish)",
+      "Skill(mate-artifact-finish)",
       "Bash(openspec:*)",
       "Bash(mate cap graphify:*)",
       `Bash(${path.join(wrapperBinPath, "openspec")}:*)`,
     ],
-    headroom: ["Bash(rtk:*)"],
+    rtk: ["Bash(rtk:*)"],
     graphify: [
       "Skill(graphify)",
       "Bash(graphify:*)",
@@ -273,26 +273,12 @@ function buildManagedClaudeSettings(
         hooks: [
           {
             type: "command",
-            command: `sh "${companionPath}/.claude/hooks/mate-openspec-artifact-finish.sh"`,
+            command: `sh "${companionPath}/.claude/hooks/mate-artifact-finish.sh"`,
           },
         ],
       },
       ...(hooks.PostToolUse ?? []),
     ];
-    // End-of-turn catch-all: an archive created by anything other than a matched Bash
-    // command (or as the last action of a turn) still gets a finish nudge on Stop.
-    hooks.Stop = [
-      {
-        hooks: [
-          {
-            type: "command",
-            command: `sh "${companionPath}/.claude/hooks/mate-openspec-artifact-finish.sh"`,
-            timeout: 10,
-          },
-        ],
-      },
-      ...(hooks.Stop ?? []),
-    ];
   }
   if (reactDoctorEnabled) {
     // Record edits cheaply, then scan once when the edited turn finishes.

package/src/tools/setup.ts

@@ -121,7 +121,7 @@ function mateFolderReadme(): string {
     `Edit \`.${n}/config/framework.yaml\` to configure:`,
     ``,
     `- **profiles** — per-profile allowed agents list`,
-    `- **capabilities** — skill and CLI tool capabilities (e.g. react-doctor, openspec, tokensave, headroom)`,
+    `- **capabilities** — skill and CLI tool capabilities (e.g. react-doctor, openspec, tokensave, headroom, rtk)`,
     `- **git** — set to \`auto\` to synchronize the companion before agent launches`,
     ``,
   ].join("\n");