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

package/package.json

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

package/src/cli/commands/doctor.ts

@@ -127,10 +127,10 @@ function getSelectedToolChecks(config: {
     checks.push({ name: "tokensave", command: "tokensave", source: "capability" });
   }
   if (selectedCapabilities.has("headroom")) {
-    checks.push(
-      { name: "headroom", command: "headroom", source: "capability" },
-      { name: "rtk", command: "rtk", source: "headroom dependency" },
-    );
+    checks.push({ name: "headroom", command: "headroom", source: "capability" });
+  }
+  if (selectedCapabilities.has("rtk")) {
+    checks.push({ name: "rtk", command: "rtk", source: "capability" });
   }
   if (selectedCapabilities.has("graphify")) {
     checks.push({ name: "graphify", command: "graphify", source: "capability" });

package/src/cli/commands/report/index.ts

@@ -74,6 +74,7 @@ export async function runReportCommand(
 
   const tokensaveEnabled = enabledCapabilities.includes("tokensave");
   const headroomEnabled = enabledCapabilities.includes("headroom");
+  const rtkEnabled = enabledCapabilities.includes("rtk");
 
   // Collect spending via ccusage (covers all agents: Claude, OpenCode, Codex, etc.)
   const ccusageResult = await collectCcusageSpending(options.days, deps);
@@ -92,7 +93,7 @@ export async function runReportCommand(
   };
   let rtkResult: Awaited<ReturnType<typeof collectRTKSavings>> = {
     entry: null,
-    status: { name: "rtk", enabled: false, status: "not installed" },
+    status: { name: "rtk", enabled: false, status: "not enabled" },
   };
   let headroomResult: Awaited<ReturnType<typeof collectHeadroomSavings>> = {
     entry: null,
@@ -106,8 +107,9 @@ export async function runReportCommand(
     ]);
   }
 
-  // RTK savings
-  rtkResult = await collectRTKSavings(workingRepoPath, deps);
+  if (rtkEnabled) {
+    rtkResult = await collectRTKSavings(workingRepoPath, deps);
+  }
 
   if (headroomEnabled) {
     headroomResult = await collectHeadroomSavings(options.days, deps);

package/src/lib/orchestrator/config-store.ts

@@ -5,6 +5,8 @@ import { getDefaultSetupSelections } from "./setup-compatibilities";
 import { YamlFileStore } from "./yaml-file-store";
 import { type FrameworkConfig } from "./types";
 
+export const RTK_CAPABILITY_SPLIT_MIGRATION = "rtk-capability-split-v1";
+
 function defaultConfigPath(): string {
   return `.${frameworkConfig.name}/config/framework.yaml`;
 }
@@ -38,17 +40,35 @@ export function mergeWithDefaults(existing: FrameworkConfig): FrameworkConfig {
   };
 }
 
+export function migrateRtkCapabilitySplit(config: FrameworkConfig): FrameworkConfig {
+  const migrations = config.migrations ?? [];
+  if (migrations.includes(RTK_CAPABILITY_SPLIT_MIGRATION)) return config;
+
+  const capabilities = config.capabilities ?? [];
+  const hasHeadroom = capabilities.some((capability) => capability.name === "headroom");
+  const hasRtk = capabilities.some((capability) => capability.name === "rtk");
+  return {
+    ...config,
+    capabilities: hasHeadroom && !hasRtk ? [...capabilities, { name: "rtk" }] : capabilities,
+    migrations: [...migrations, RTK_CAPABILITY_SPLIT_MIGRATION],
+  };
+}
+
 export class ConfigStore extends YamlFileStore<FrameworkConfig> {
   constructor(configPath = process.env.MATE_CONFIG ?? defaultConfigPath()) {
     super(path.resolve(configPath));
   }
 
   override async load(): Promise<FrameworkConfig> {
-    return mergeWithDefaults(await super.load());
+    const merged = mergeWithDefaults(await super.load());
+    const needsMigration = !(merged.migrations ?? []).includes(RTK_CAPABILITY_SPLIT_MIGRATION);
+    const config = migrateRtkCapabilitySplit(merged);
+    if (needsMigration) await this.save(config);
+    return config;
   }
 
   protected async onMissing(): Promise<FrameworkConfig> {
-    const config = defaultConfig();
+    const config = migrateRtkCapabilitySplit(defaultConfig());
     await this.save(config);
     return config;
   }

package/src/lib/orchestrator/setup-compatibilities.ts

@@ -193,6 +193,14 @@ export const BUILTIN_SETUP_COMPATIBILITIES: SetupCompatibility[] = [
     description: "Wrap supported agent launches through Headroom when the binary is installed.",
     defaultSelected: false,
   },
+  {
+    id: "rtk",
+    kind: "capability",
+    capability: { name: "rtk" },
+    label: "RTK",
+    description: "Patch supported agent providers with RTK independently from Headroom.",
+    defaultSelected: false,
+  },
   {
     id: "graphify",
     kind: "capability",

package/src/lib/orchestrator/types.ts

@@ -86,6 +86,7 @@ export interface FrameworkConfig {
   git?: GitModeProfile;
   profiles: Record<string, PolicyProfile>;
   capabilities?: CapabilityConfig[];
+  migrations?: string[];
   cliTools?: CliToolConfig[];
   packageManagers?: string[];
   engines?: EngineConstraints;

package/src/opencode/companion-hooks.ts

@@ -211,7 +211,7 @@ function appendOpenSpecFinishNudge(
   const nudges = uniqueChanges.map(
     (change) =>
       `ACTION REQUIRED: An openspec change (${change}) was just archived. ` +
-      `Immediately invoke the mate-openspec-artifact-finish skill to complete the finish pipeline ` +
+      `Immediately invoke the mate-artifact-finish skill to complete the finish pipeline ` +
       "(invoke the CLI as `mate`, never through a companion-local wrapper path or as `" +
       "$MATE_COMPANION_BIN_PATH/mate`). " +
       "`mate artifact finish` resumes from the already-archived change and completes the commit, dated tag, and push itself — " +

package/src/plugins.ts

@@ -12,5 +12,6 @@ export { createOpenspecPlugin } from "./tools/setup/capabilities/openspec";
 export { createReactDoctorPlugin } from "./tools/setup/capabilities/react-doctor";
 export { createTokensavePlugin } from "./tools/setup/capabilities/tokensave";
 export { createHeadroomPlugin } from "./tools/setup/capabilities/headroom";
+export { createRtkPlugin } from "./tools/setup/capabilities/rtk";
 export { createGraphifyPlugin } from "./tools/setup/capabilities/graphify";
 export { createGitignorePlugin } from "./tools/setup/plugins/gitignore";

package/src/templates/capabilities/openspec-cap/claude/hooks/mate-artifact-finish.sh

@@ -0,0 +1,120 @@
+#!/bin/sh
+set -u
+
+input_file=$(mktemp "${TMPDIR:-/tmp}/mate-artifact-finish.XXXXXX")
+trap 'rm -f "$input_file"' EXIT
+cat >"$input_file"
+
+node -e '
+const fs = require("node:fs");
+
+const inputFile = process.argv[1];
+const archivePathPattern = /(?:^|[\s\/"\x27`,(])openspec\/changes\/archive\/(\d{4}-\d{2}-\d{2}-[^\/\s"\x27`,)]+)/;
+
+function shellSplit(command) {
+  const parts = [];
+  const singleQuote = String.fromCharCode(39);
+  let current = "";
+  let quote = null;
+  let escaping = false;
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+    if (char === "\\" && quote !== singleQuote) {
+      const next = command[index + 1] || "";
+      if (next === "\\" || /\s/.test(next) || next === singleQuote || next === String.fromCharCode(34)) {
+        escaping = true;
+        continue;
+      }
+    }
+    if ((char === singleQuote || char === String.fromCharCode(34)) && !quote) {
+      quote = char;
+      continue;
+    }
+    if (quote === char) {
+      quote = null;
+      continue;
+    }
+    if (!quote && /\s/.test(char)) {
+      if (current) parts.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current) parts.push(current);
+  return parts;
+}
+
+function extractChangeFromPath(value) {
+  const match = value.replace(/\\/g, "/").match(archivePathPattern);
+  return match ? match[1].replace(/^\d{4}-\d{2}-\d{2}-/, "") : null;
+}
+
+function extractArchiveCommand(command) {
+  const parts = shellSplit(command);
+  const index = parts.findIndex((part, position) =>
+    part === "archive" && position > 0 &&
+    (parts[position - 1] === "openspec" || parts[position - 1].endsWith("/openspec")));
+  if (index < 0) return null;
+  for (let position = index + 1; position < parts.length; position += 1) {
+    const part = parts[position];
+    if (!part || part === "--") continue;
+    if (part.startsWith("-")) {
+      if (part === "--store") position += 1;
+      continue;
+    }
+    return part;
+  }
+  return null;
+}
+
+function extractMoveCommand(command) {
+  const parts = shellSplit(command);
+  const moveCommands = new Set([
+    "mv", "move", "move-item", "cmd", "cmd.exe", "powershell", "powershell.exe", "pwsh", "pwsh.exe",
+  ]);
+  const isPython = (part) => /^python(?:\d(?:\.\d+)*)?(?:\.exe)?$/i.test(part.split(/[\\/]/).pop() || part);
+  for (let index = 0; index < parts.length; index += 1) {
+    if (moveCommands.has(parts[index].toLowerCase())) {
+      for (const part of parts.slice(index + 1)) {
+        const change = extractChangeFromPath(part);
+        if (change) return change;
+      }
+    }
+    if (isPython(parts[index]) && /(?:shutil\.move|os\.rename|\.rename\s*\()/.test(command)) {
+      return extractChangeFromPath(command);
+    }
+  }
+  return null;
+}
+
+let input = {};
+try {
+  input = JSON.parse(fs.readFileSync(inputFile, "utf8") || "{}");
+} catch {}
+
+if (input.hook_event_name !== "PreToolUse" || input.tool_name !== "Bash") process.exit(0);
+const command = input.tool_input && typeof input.tool_input.command === "string"
+  ? input.tool_input.command
+  : "";
+const change = extractArchiveCommand(command) || extractMoveCommand(command);
+if (!change) process.exit(0);
+
+const reason =
+  "Standalone archival for OpenSpec change " + change + " is blocked. Invoke the " +
+  "mate-artifact-finish skill, then run `mate artifact finish \"" + change + "\" --json`. " +
+  "The finish command performs the normal OpenSpec archive and completes commit, tag, and push.";
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "deny",
+    permissionDecisionReason: reason,
+  },
+}));
+' "$input_file"
+exit 0

package/src/templates/capabilities/openspec-cap/mate-skills/{mate-openspec-artifact-finish → mate-artifact-finish}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: mate-openspec-artifact-finish
+name: mate-artifact-finish
 description: Finish a completed artifact in one step via `mate artifact finish`. Use when the user wants to finish, ship, or archive-and-push a completed artifact and anchor it with a dated revert tag.
 allowed-tools: Bash(mate:*), Bash(git:*), Bash(openspec:*)
 license: MIT

package/src/templates/capabilities/openspec-cap/mate-skills/{mate-openspec-artifact-finish → mate-artifact-finish}/references/openspec.md

@@ -1,6 +1,6 @@
 # OpenSpec Finish Reference
 
-Use this reference when you need the OpenSpec-specific parts of `mate-openspec-artifact-finish`: change lookup, resumable archive behavior, JSON field meanings, and conflict recovery.
+Use this reference when you need the OpenSpec-specific parts of `mate-artifact-finish`: change lookup, resumable archive behavior, JSON field meanings, and conflict recovery.
 
 ## OpenSpec Input Rules
 

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/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:*)",
@@ -267,31 +267,17 @@ function buildManagedClaudeSettings(
     ...(hooks.SessionStart ?? []),
   ];
   if (openspecEnabled) {
-    hooks.PostToolUse = [
+    hooks.PreToolUse = [
       {
         matcher: "Bash",
         hooks: [
           {
             type: "command",
-            command: `sh "${companionPath}/.claude/hooks/mate-openspec-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,
+            command: `sh "${companionPath}/.claude/hooks/mate-artifact-finish.sh"`,
           },
         ],
       },
-      ...(hooks.Stop ?? []),
+      ...(hooks.PreToolUse ?? []),
     ];
   }
   if (reactDoctorEnabled) {

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");

package/src/templates/capabilities/openspec-cap/claude/hooks/mate-openspec-artifact-finish.sh

@@ -1,236 +0,0 @@
-#!/bin/sh
-set -u
-
-input_file=$(mktemp "${TMPDIR:-/tmp}/mate-openspec-artifact-finish.XXXXXX")
-trap 'rm -f "$input_file"' EXIT
-cat >"$input_file"
-
-script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd)
-companion_path=${MATE_ARTIFACT_PATH:-}
-if [ -z "$companion_path" ]; then
-  companion_path=$(CDPATH= cd "$script_dir/../.." && pwd)
-fi
-
-archive_dir="$companion_path/openspec/changes/archive"
-state_dir="$companion_path/.claude/state"
-
-node -e '
-const fs = require("node:fs");
-const path = require("node:path");
-
-const archiveDir = process.argv[1];
-const stateDir = process.argv[2];
-const inputFile = process.argv[3];
-const archiveEntryPattern = /^\d{4}-\d{2}-\d{2}-.+$/;
-const archivePathPattern = /(?:^|[\s\/"\x27`,(])openspec\/changes\/archive\/(\d{4}-\d{2}-\d{2}-[^\/\s"\x27`,)]+)/;
-
-function readArchiveEntries() {
-  try {
-    return fs.readdirSync(archiveDir, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory() && archiveEntryPattern.test(entry.name))
-      .map((entry) => entry.name)
-      .sort();
-  } catch {
-    return [];
-  }
-}
-
-function shellSplit(command) {
-  const parts = [];
-  const singleQuote = String.fromCharCode(39);
-  let current = "";
-  let quote = null;
-  let escaping = false;
-  for (let index = 0; index < command.length; index += 1) {
-    const char = command[index];
-    if (escaping) {
-      current += char;
-      escaping = false;
-      continue;
-    }
-    if (char === "\\" && quote !== singleQuote) {
-      const next = command[index + 1] || "";
-      if (next === "\\" || /\s/.test(next) || next === singleQuote || next === String.fromCharCode(34)) {
-        escaping = true;
-        continue;
-      }
-    }
-    if ((char === singleQuote || char === String.fromCharCode(34)) && !quote) {
-      quote = char;
-      continue;
-    }
-    if (quote === char) {
-      quote = null;
-      continue;
-    }
-    if (!quote && /\s/.test(char)) {
-      if (current) parts.push(current);
-      current = "";
-      continue;
-    }
-    current += char;
-  }
-  if (current) parts.push(current);
-  return parts;
-}
-
-function extractChangeFromPath(value) {
-  const match = value.replace(/\\/g, "/").match(archivePathPattern);
-  return match ? match[1].replace(/^\d{4}-\d{2}-\d{2}-/, "") : null;
-}
-
-function extractArchiveCommand(command) {
-  const parts = shellSplit(command);
-  const index = parts.findIndex((part, position) =>
-    part === "archive" && position > 0 &&
-    (parts[position - 1] === "openspec" || parts[position - 1].endsWith("/openspec")));
-  if (index < 0) return null;
-  for (let position = index + 1; position < parts.length; position += 1) {
-    const part = parts[position];
-    if (!part || part === "--") continue;
-    if (part.startsWith("-")) {
-      if (part === "--store") position += 1;
-      continue;
-    }
-    return part;
-  }
-  return null;
-}
-
-function extractMoveCommand(command) {
-  const parts = shellSplit(command);
-  const moveCommands = new Set([
-    "mv", "move", "move-item", "cmd", "cmd.exe", "powershell", "powershell.exe", "pwsh", "pwsh.exe",
-  ]);
-  const isPython = (part) => /^python(?:\d(?:\.\d+)*)?(?:\.exe)?$/i.test(part.split(/[\\/]/).pop() || part);
-  for (let index = 0; index < parts.length; index += 1) {
-    if (moveCommands.has(parts[index].toLowerCase())) {
-      for (const part of parts.slice(index + 1)) {
-        const change = extractChangeFromPath(part);
-        if (change) return change;
-      }
-    }
-    if (isPython(parts[index]) && /(?:shutil\.move|os\.rename|\.rename\s*\()/.test(command)) {
-      return extractChangeFromPath(command);
-    }
-  }
-  return null;
-}
-
-function extractFinishCommand(command) {
-  const parts = shellSplit(command);
-  return parts.some((part, position) =>
-    part === "finish" && position > 1 && parts[position - 1] === "artifact" &&
-    (parts[position - 2] === "mate" || parts[position - 2].endsWith("/mate")));
-}
-
-function commandSucceeded(value) {
-  if (!value || typeof value !== "object") return true;
-  const candidates = [value, value.result, value.output, value.tool_output, value.tool_response];
-  for (const candidate of candidates) {
-    if (!candidate || typeof candidate !== "object") continue;
-    if (typeof candidate.success === "boolean") return candidate.success;
-    for (const key of ["exitCode", "exit_code", "status", "statusCode", "status_code"]) {
-      const status = candidate[key];
-      if (typeof status === "number") return status === 0;
-      if (typeof status === "string" && status.trim()) return Number(status) === 0;
-    }
-  }
-  return true;
-}
-
-function bashCommands(input) {
-  if (!input || typeof input !== "object") return [];
-  const toolName = String(input.tool_name || input.toolName || input.tool || "");
-  if (toolName !== "Bash") return [];
-  return [
-    input.command,
-    input.args?.command,
-    input.tool_input?.command,
-  ].filter((command) => typeof command === "string");
-}
-
-function commandArchive(input) {
-  if (!commandSucceeded(input)) return null;
-  for (const command of bashCommands(input)) {
-    const change = extractArchiveCommand(command) || extractMoveCommand(command);
-    if (change) return change;
-  }
-  return null;
-}
-
-// `mate artifact finish` archives as part of its own pipeline; new archive entries it
-// creates are already being finished and must not trigger a nudge (its JSON result
-// already tells the agent how to resume after a failure).
-function commandFinish(input) {
-  return bashCommands(input).some((command) => extractFinishCommand(command));
-}
-
-let input = {};
-try {
-  input = JSON.parse(fs.readFileSync(inputFile, "utf8") || "{}");
-} catch {}
-
-const sessionId = typeof input.session_id === "string" && input.session_id ? input.session_id : null;
-const stateFile = sessionId
-  ? path.join(stateDir, "mate-openspec-artifact-finish." + sessionId.replace(/[^a-zA-Z0-9_-]/g, "_") + ".json")
-  : path.join(stateDir, "mate-openspec-artifact-finish.archive-snapshot.json");
-
-const currentEntries = readArchiveEntries();
-let previousEntries;
-let validState = false;
-try {
-  const state = JSON.parse(fs.readFileSync(stateFile, "utf8"));
-  if (state && state.version === 1 && Array.isArray(state.entries) &&
-      state.entries.every((entry) => typeof entry === "string" && archiveEntryPattern.test(entry))) {
-    previousEntries = new Set(state.entries);
-    validState = true;
-  }
-} catch {}
-
-try {
-  fs.mkdirSync(path.dirname(stateFile), { recursive: true });
-  fs.writeFileSync(stateFile, JSON.stringify({ version: 1, entries: currentEntries }) + "\n");
-} catch {
-  process.exit(0);
-}
-
-function nudgeFor(change) {
-  return (
-    "An openspec change (" + change + ") was just archived but not finished. Invoke the " +
-    "mate-openspec-artifact-finish skill now to finish it (invoke the CLI as `mate`, never through a companion-local wrapper path or as `$MATE_COMPANION_BIN_PATH/mate`). " +
-    "`mate artifact finish` resumes from the already-archived change and completes the commit, dated tag, and push itself — " +
-    "do not hand-commit, do not hand-tag, and do not re-apply delta specs manually. " +
-    "Follow the skill guardrails, including confirming with the user in chat before pushing."
-  );
-}
-
-const eventName = typeof input.hook_event_name === "string" && input.hook_event_name
-  ? input.hook_event_name
-  : "PostToolUse";
-
-function emit(message) {
-  if (eventName === "Stop") {
-    // Stop hooks deliver instructions via a block decision, not additionalContext.
-    process.stdout.write(JSON.stringify({ decision: "block", reason: message }));
-  } else {
-    process.stdout.write(JSON.stringify({
-      hookSpecificOutput: { hookEventName: eventName, additionalContext: message },
-    }));
-  }
-  process.exit(0);
-}
-
-// A finish run archives and finishes in one pipeline: absorb its entries silently.
-if (commandFinish(input)) process.exit(0);
-
-const commandChange = commandArchive(input);
-if (commandChange) emit(nudgeFor(commandChange));
-
-if (!validState) process.exit(0);
-const newlyArchived = currentEntries.filter((entry) => !previousEntries.has(entry));
-if (newlyArchived.length === 0) process.exit(0);
-
-emit(newlyArchived.map((entry) => nudgeFor(entry.slice("YYYY-MM-DD-".length))).join("\n\n"));
-' "$archive_dir" "$state_dir" "$input_file"
-exit 0