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

package/src/tools/setup/__snapshots__/runtime-surface-golden.test.ts.snap

@@ -70,6 +70,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -277,6 +278,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
 ,
   },
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -505,6 +507,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
 ,
   },
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -841,6 +844,7 @@ exports[`runtime surface golden fixtures setup tokensave × claude 1`] = `
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -1054,6 +1058,7 @@ exports[`runtime surface golden fixtures setup tokensave × opencode 1`] = `
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -1304,6 +1309,7 @@ exports[`runtime surface golden fixtures setup tokensave × claude+opencode 1`]
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -1621,6 +1627,7 @@ exports[`runtime surface golden fixtures setup context-mode × claude 1`] = `
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -1805,6 +1812,7 @@ Canonical Mate policy and any more specific tool-routing instructions remain aut
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -1979,6 +1987,7 @@ Canonical Mate policy and any more specific tool-routing instructions remain aut
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -2276,6 +2285,7 @@ exports[`runtime surface golden fixtures setup react-doctor × claude 1`] = `
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -2448,11 +2458,12 @@ exports[`runtime surface golden fixtures setup react-doctor × opencode 1`] = `
     },
   },
   "opencodePlugins": {},
-  "opencodeSkills": {
+  "opencodeSkills": {},
+  "opencodeTui": null,
+  "sharedSkills": {
     "react-doctor/SKILL.md": "df58b3490543",
     "react-doctor/references/explain.md": "2382ea820f20",
   },
-  "opencodeTui": null,
 }
 `;
 
@@ -2647,11 +2658,12 @@ exports[`runtime surface golden fixtures setup react-doctor × claude+opencode 1
     },
   },
   "opencodePlugins": {},
-  "opencodeSkills": {
+  "opencodeSkills": {},
+  "opencodeTui": null,
+  "sharedSkills": {
     "react-doctor/SKILL.md": "df58b3490543",
     "react-doctor/references/explain.md": "2382ea820f20",
   },
-  "opencodeTui": null,
 }
 `;
 
@@ -2930,16 +2942,16 @@ exports[`runtime surface golden fixtures setup openspec × claude 1`] = `
     "mate-artifact-publish/SKILL.md": "9ae069fc6d0d",
     "mate-artifact-publish/references/openspec.md": "b5c986ed9bdc",
     "mate-create-report/SKILL.md": "4dda64fab7b7",
-    "mate-domain-modeling/SKILL.md": "22f1d92b65ce",
+    "mate-domain-modeling/SKILL.md": "e9b812c5b70f",
     "mate-domain-modeling/references/ADR-FORMAT.md": "824b87e87d9b",
     "mate-domain-modeling/references/CONTEXT-FORMAT.md": "172622594277",
-    "mate-grill-me/SKILL.md": "bbccd2654f71",
-    "mate-grill-with-docs/SKILL.md": "d79278237d49",
-    "mate-grilling/SKILL.md": "9fa3fb50cc73",
-    "mate-interview-me/SKILL.md": "ad5d76230917",
+    "mate-grill-me/SKILL.md": "c6e7bba6ec12",
+    "mate-grill-with-docs/SKILL.md": "2e4dbb346e51",
+    "mate-grilling/SKILL.md": "168a259e69ae",
+    "mate-interview-me/SKILL.md": "79f21214a92d",
     "mate-openspec-backfill/SKILL.md": "fa73daee9951",
-    "mate-show-me/SKILL.md": "3ecf5d44eb45",
-    "mate-simplify-code/SKILL.md": "5dd2abc9571b",
+    "mate-show-me/SKILL.md": "7ccd84f967cf",
+    "mate-simplify-code/SKILL.md": "6fff7fff920c",
     "openspec-apply-change/SKILL.md": "b023edd228ab",
     "openspec-archive-change/SKILL.md": "890bada99035",
     "openspec-explore/SKILL.md": "477fdec2cdb0",
@@ -2949,6 +2961,7 @@ exports[`runtime surface golden fixtures setup openspec × claude 1`] = `
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -3136,26 +3149,28 @@ exports[`runtime surface golden fixtures setup openspec × opencode 1`] = `
     },
   },
   "opencodePlugins": {},
-  "opencodeSkills": {
+  "opencodeSkills": {},
+  "opencodeTui": null,
+  "sharedSkills": {
+    ".openspec-target": "38700dfad571",
     "mate-artifact-publish/SKILL.md": "9ae069fc6d0d",
     "mate-artifact-publish/references/openspec.md": "b5c986ed9bdc",
     "mate-create-report/SKILL.md": "4dda64fab7b7",
-    "mate-domain-modeling/SKILL.md": "22f1d92b65ce",
+    "mate-domain-modeling/SKILL.md": "e9b812c5b70f",
     "mate-domain-modeling/references/ADR-FORMAT.md": "824b87e87d9b",
     "mate-domain-modeling/references/CONTEXT-FORMAT.md": "172622594277",
-    "mate-grill-me/SKILL.md": "bbccd2654f71",
-    "mate-grill-with-docs/SKILL.md": "d79278237d49",
-    "mate-grilling/SKILL.md": "9fa3fb50cc73",
-    "mate-interview-me/SKILL.md": "ad5d76230917",
+    "mate-grill-me/SKILL.md": "c6e7bba6ec12",
+    "mate-grill-with-docs/SKILL.md": "2e4dbb346e51",
+    "mate-grilling/SKILL.md": "168a259e69ae",
+    "mate-interview-me/SKILL.md": "79f21214a92d",
     "mate-openspec-backfill/SKILL.md": "fa73daee9951",
-    "mate-show-me/SKILL.md": "3ecf5d44eb45",
-    "mate-simplify-code/SKILL.md": "5dd2abc9571b",
-    "openspec-apply-change/SKILL.md": "cb6e43b175c8",
-    "openspec-archive-change/SKILL.md": "920c4cc68edf",
-    "openspec-explore/SKILL.md": "87d1237e5ffa",
-    "openspec-propose/SKILL.md": "3618b84ce74c",
+    "mate-show-me/SKILL.md": "7ccd84f967cf",
+    "mate-simplify-code/SKILL.md": "6fff7fff920c",
+    "openspec-apply-change/SKILL.md": "c657f1b4e9eb",
+    "openspec-archive-change/SKILL.md": "ad2463670c0f",
+    "openspec-explore/SKILL.md": "214bba092ffa",
+    "openspec-propose/SKILL.md": "c09159964f8e",
   },
-  "opencodeTui": null,
 }
 `;
 
@@ -3317,16 +3332,16 @@ exports[`runtime surface golden fixtures setup openspec × claude+opencode 1`] =
     "mate-artifact-publish/SKILL.md": "9ae069fc6d0d",
     "mate-artifact-publish/references/openspec.md": "b5c986ed9bdc",
     "mate-create-report/SKILL.md": "4dda64fab7b7",
-    "mate-domain-modeling/SKILL.md": "22f1d92b65ce",
+    "mate-domain-modeling/SKILL.md": "e9b812c5b70f",
     "mate-domain-modeling/references/ADR-FORMAT.md": "824b87e87d9b",
     "mate-domain-modeling/references/CONTEXT-FORMAT.md": "172622594277",
-    "mate-grill-me/SKILL.md": "bbccd2654f71",
-    "mate-grill-with-docs/SKILL.md": "d79278237d49",
-    "mate-grilling/SKILL.md": "9fa3fb50cc73",
-    "mate-interview-me/SKILL.md": "ad5d76230917",
+    "mate-grill-me/SKILL.md": "c6e7bba6ec12",
+    "mate-grill-with-docs/SKILL.md": "2e4dbb346e51",
+    "mate-grilling/SKILL.md": "168a259e69ae",
+    "mate-interview-me/SKILL.md": "79f21214a92d",
     "mate-openspec-backfill/SKILL.md": "fa73daee9951",
-    "mate-show-me/SKILL.md": "3ecf5d44eb45",
-    "mate-simplify-code/SKILL.md": "5dd2abc9571b",
+    "mate-show-me/SKILL.md": "7ccd84f967cf",
+    "mate-simplify-code/SKILL.md": "6fff7fff920c",
     "openspec-apply-change/SKILL.md": "b023edd228ab",
     "openspec-archive-change/SKILL.md": "890bada99035",
     "openspec-explore/SKILL.md": "477fdec2cdb0",
@@ -3353,26 +3368,28 @@ exports[`runtime surface golden fixtures setup openspec × claude+opencode 1`] =
     },
   },
   "opencodePlugins": {},
-  "opencodeSkills": {
+  "opencodeSkills": {},
+  "opencodeTui": null,
+  "sharedSkills": {
+    ".openspec-target": "38700dfad571",
     "mate-artifact-publish/SKILL.md": "9ae069fc6d0d",
     "mate-artifact-publish/references/openspec.md": "b5c986ed9bdc",
     "mate-create-report/SKILL.md": "4dda64fab7b7",
-    "mate-domain-modeling/SKILL.md": "22f1d92b65ce",
+    "mate-domain-modeling/SKILL.md": "e9b812c5b70f",
     "mate-domain-modeling/references/ADR-FORMAT.md": "824b87e87d9b",
     "mate-domain-modeling/references/CONTEXT-FORMAT.md": "172622594277",
-    "mate-grill-me/SKILL.md": "bbccd2654f71",
-    "mate-grill-with-docs/SKILL.md": "d79278237d49",
-    "mate-grilling/SKILL.md": "9fa3fb50cc73",
-    "mate-interview-me/SKILL.md": "ad5d76230917",
+    "mate-grill-me/SKILL.md": "c6e7bba6ec12",
+    "mate-grill-with-docs/SKILL.md": "2e4dbb346e51",
+    "mate-grilling/SKILL.md": "168a259e69ae",
+    "mate-interview-me/SKILL.md": "79f21214a92d",
     "mate-openspec-backfill/SKILL.md": "fa73daee9951",
-    "mate-show-me/SKILL.md": "3ecf5d44eb45",
-    "mate-simplify-code/SKILL.md": "5dd2abc9571b",
-    "openspec-apply-change/SKILL.md": "cb6e43b175c8",
-    "openspec-archive-change/SKILL.md": "920c4cc68edf",
-    "openspec-explore/SKILL.md": "87d1237e5ffa",
-    "openspec-propose/SKILL.md": "3618b84ce74c",
+    "mate-show-me/SKILL.md": "7ccd84f967cf",
+    "mate-simplify-code/SKILL.md": "6fff7fff920c",
+    "openspec-apply-change/SKILL.md": "c657f1b4e9eb",
+    "openspec-archive-change/SKILL.md": "ad2463670c0f",
+    "openspec-explore/SKILL.md": "214bba092ffa",
+    "openspec-propose/SKILL.md": "c09159964f8e",
   },
-  "opencodeTui": null,
 }
 `;
 
@@ -3782,16 +3799,16 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
     "mate-artifact-publish/SKILL.md": "9ae069fc6d0d",
     "mate-artifact-publish/references/openspec.md": "b5c986ed9bdc",
     "mate-create-report/SKILL.md": "4dda64fab7b7",
-    "mate-domain-modeling/SKILL.md": "22f1d92b65ce",
+    "mate-domain-modeling/SKILL.md": "e9b812c5b70f",
     "mate-domain-modeling/references/ADR-FORMAT.md": "824b87e87d9b",
     "mate-domain-modeling/references/CONTEXT-FORMAT.md": "172622594277",
-    "mate-grill-me/SKILL.md": "bbccd2654f71",
-    "mate-grill-with-docs/SKILL.md": "d79278237d49",
-    "mate-grilling/SKILL.md": "9fa3fb50cc73",
-    "mate-interview-me/SKILL.md": "ad5d76230917",
+    "mate-grill-me/SKILL.md": "c6e7bba6ec12",
+    "mate-grill-with-docs/SKILL.md": "2e4dbb346e51",
+    "mate-grilling/SKILL.md": "168a259e69ae",
+    "mate-interview-me/SKILL.md": "79f21214a92d",
     "mate-openspec-backfill/SKILL.md": "fa73daee9951",
-    "mate-show-me/SKILL.md": "3ecf5d44eb45",
-    "mate-simplify-code/SKILL.md": "5dd2abc9571b",
+    "mate-show-me/SKILL.md": "7ccd84f967cf",
+    "mate-simplify-code/SKILL.md": "6fff7fff920c",
     "openspec-apply-change/SKILL.md": "b023edd228ab",
     "openspec-archive-change/SKILL.md": "890bada99035",
     "openspec-explore/SKILL.md": "477fdec2cdb0",
@@ -3854,27 +3871,30 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
 "Outputs land in $GRAPHIFY_OUT by default.
 "
 ,
+  },
+  "opencodeTui": null,
+  "sharedSkills": {
+    ".openspec-target": "38700dfad571",
     "mate-artifact-publish/SKILL.md": "9ae069fc6d0d",
     "mate-artifact-publish/references/openspec.md": "b5c986ed9bdc",
     "mate-create-report/SKILL.md": "4dda64fab7b7",
-    "mate-domain-modeling/SKILL.md": "22f1d92b65ce",
+    "mate-domain-modeling/SKILL.md": "e9b812c5b70f",
     "mate-domain-modeling/references/ADR-FORMAT.md": "824b87e87d9b",
     "mate-domain-modeling/references/CONTEXT-FORMAT.md": "172622594277",
-    "mate-grill-me/SKILL.md": "bbccd2654f71",
-    "mate-grill-with-docs/SKILL.md": "d79278237d49",
-    "mate-grilling/SKILL.md": "9fa3fb50cc73",
-    "mate-interview-me/SKILL.md": "ad5d76230917",
+    "mate-grill-me/SKILL.md": "c6e7bba6ec12",
+    "mate-grill-with-docs/SKILL.md": "2e4dbb346e51",
+    "mate-grilling/SKILL.md": "168a259e69ae",
+    "mate-interview-me/SKILL.md": "79f21214a92d",
     "mate-openspec-backfill/SKILL.md": "fa73daee9951",
-    "mate-show-me/SKILL.md": "3ecf5d44eb45",
-    "mate-simplify-code/SKILL.md": "5dd2abc9571b",
-    "openspec-apply-change/SKILL.md": "cb6e43b175c8",
-    "openspec-archive-change/SKILL.md": "920c4cc68edf",
-    "openspec-explore/SKILL.md": "87d1237e5ffa",
-    "openspec-propose/SKILL.md": "3618b84ce74c",
+    "mate-show-me/SKILL.md": "7ccd84f967cf",
+    "mate-simplify-code/SKILL.md": "6fff7fff920c",
+    "openspec-apply-change/SKILL.md": "c657f1b4e9eb",
+    "openspec-archive-change/SKILL.md": "ad2463670c0f",
+    "openspec-explore/SKILL.md": "214bba092ffa",
+    "openspec-propose/SKILL.md": "c09159964f8e",
     "react-doctor/SKILL.md": "df58b3490543",
     "react-doctor/references/explain.md": "2382ea820f20",
   },
-  "opencodeTui": null,
 }
 `;
 
@@ -4246,6 +4266,7 @@ exports[`runtime surface golden fixtures teardown graphify × claude+opencode 1`
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -4305,6 +4326,7 @@ exports[`runtime surface golden fixtures teardown tokensave × claude+opencode 1
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -4365,6 +4387,7 @@ exports[`runtime surface golden fixtures teardown context-mode × claude+opencod
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -4424,6 +4447,7 @@ exports[`runtime surface golden fixtures teardown react-doctor × claude+opencod
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -4483,6 +4507,7 @@ exports[`runtime surface golden fixtures teardown openspec × claude+opencode 1`
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -4556,6 +4581,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;
 
@@ -4693,5 +4719,6 @@ exports[`working repo golden fixtures hub roots set up providers only without co
   "opencodePlugins": {},
   "opencodeSkills": {},
   "opencodeTui": null,
+  "sharedSkills": {},
 }
 `;

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

@@ -19,7 +19,13 @@ import {
   runCommand,
   runCommandSilently,
 } from "../utils";
-import { applyMateSkills, teardownMateSkills } from "../mate";
+import { applyMateSkills, MANAGED_MATE_SKILL_NAMES, teardownMateSkills } from "../mate";
+import {
+  getSharedSkillsDir,
+  isSharedSkillRootActive,
+  removeLegacyOpenCodeSkills,
+  removeSharedSkills,
+} from "../providers/agents-skill-root";
 
 export { MATE_ARTIFACT_SKILLS, MATE_SKILLS } from "../mate";
 
@@ -30,10 +36,15 @@ export const OPENSPEC_SKILLS = [
   "openspec-propose",
   "openspec-apply-change",
   "openspec-archive-change",
+  "openspec-sync-specs",
+  "openspec-update-change",
 ] as const;
 
-// Mate-authored skills (not generated by the openspec CLI) are sourced from the
-// shared Mate skill tree and installed per active provider while OpenSpec is enabled.
+/** Written by the OpenSpec `agents` tool beside its skills in the shared root. */
+const OPENSPEC_AGENTS_MARKER = ".openspec-target";
+
+/** Skill names the capability owns in any skill root. */
+const MANAGED_SKILL_NAMES = [...OPENSPEC_SKILLS, ...MANAGED_MATE_SKILL_NAMES];
 
 /** Every Mate-owned schema is installed for availability; only one is ever activated as the companion default. */
 const MATE_SCHEMA_NAMES = ["mate-v1", "mate-minimal"] as const;
@@ -44,14 +55,19 @@ const MATE_SCHEMA_SOURCE_ROOT = path.join(
 );
 const MATE_CONVENTIONS_SOURCE = path.join(MATE_SCHEMA_SOURCE_ROOT, "openspec-conventions.yaml");
 
-const OPENSPEC_TOOL_DIRS = {
-  claude: ".claude",
-  opencode: ".opencode",
+/**
+ * Runtime → OpenSpec CLI tools. OpenCode reads workflow skills from the shared
+ * `agents` root; its own tool only contributes the `/opsx-*` commands.
+ */
+const OPENSPEC_TOOLS_BY_RUNTIME = {
+  claude: ["claude"],
+  opencode: ["agents", "opencode"],
 } as const;
 
 const OPENSPEC_INSTALL_COMMAND = "npm install -g @fission-ai/openspec@latest";
 
-type OpenSpecTool = keyof typeof OPENSPEC_TOOL_DIRS;
+type OpenSpecTool =
+  (typeof OPENSPEC_TOOLS_BY_RUNTIME)[keyof typeof OPENSPEC_TOOLS_BY_RUNTIME][number];
 type OpenSpecRunCommand = typeof runCommandSilently;
 
 export interface OpenSpecPluginDeps {
@@ -66,8 +82,6 @@ export interface OpenSpecPluginDeps {
   isPinnedDeployment?: () => boolean;
 }
 
-const OPEN_SPEC_SUPPORTED_TOOLS = Object.keys(OPENSPEC_TOOL_DIRS) as OpenSpecTool[];
-
 async function defaultGetInstalledVersion(pathValue: string): Promise<string | undefined> {
   const bin = resolveCommandOnPath("openspec", pathValue);
   if (!bin) return undefined;
@@ -89,11 +103,14 @@ async function defaultFetchLatestVersion(): Promise<string | undefined> {
 }
 
 export function deriveOpenSpecTools(activeProviders: string[]): OpenSpecTool[] {
-  return OPEN_SPEC_SUPPORTED_TOOLS.filter((tool) => activeProviders.includes(tool));
+  const active = new Set(activeProviders);
+  return Object.entries(OPENSPEC_TOOLS_BY_RUNTIME).flatMap(([runtime, tools]) =>
+    active.has(runtime) ? tools : [],
+  );
 }
 
-function getSkillsDir(companionPath: string, tool: OpenSpecTool): string {
-  return path.join(companionPath, OPENSPEC_TOOL_DIRS[tool], "skills");
+function getClaudeSkillsDir(companionPath: string): string {
+  return path.join(companionPath, ".claude", "skills");
 }
 
 function getOpenSpecConfigPath(companionPath: string): string {
@@ -108,7 +125,8 @@ function getMateConventionsPath(companionPath: string): string {
   return path.join(companionPath, "openspec", "mate-conventions.yaml");
 }
 
-async function teardownOpenspecSkills(skillsDir: string, companionPath: string): Promise<void> {
+async function teardownClaudeSkillRoot(companionPath: string): Promise<void> {
+  const skillsDir = getClaudeSkillsDir(companionPath);
   for (const skill of OPENSPEC_SKILLS) {
     try {
       await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
@@ -120,17 +138,24 @@ async function teardownOpenspecSkills(skillsDir: string, companionPath: string):
   await pruneEmptyAncestors(skillsDir, companionPath);
 }
 
-async function teardownToolRuntime(companionPath: string, tool: OpenSpecTool): Promise<void> {
-  await teardownOpenspecSkills(getSkillsDir(companionPath, tool), companionPath);
+async function teardownSharedSkillRoot(companionPath: string): Promise<void> {
+  await removeSharedSkills(companionPath, [...MANAGED_SKILL_NAMES, OPENSPEC_AGENTS_MARKER]);
+}
+
+/** Converges earlier layouts and drops the `opencode` tool's duplicate workflow skills. */
+async function removeLegacyOpenCodeCopies(companionPath: string): Promise<void> {
+  await removeLegacyOpenCodeSkills(companionPath, MANAGED_SKILL_NAMES);
 }
 
 async function applyMateOpenspecSkills(
   companionPath: string,
-  tools: OpenSpecTool[],
+  activeProviders: string[],
 ): Promise<void> {
-  for (const tool of tools) {
-    const skillsDir = getSkillsDir(companionPath, tool);
-    await applyMateSkills(skillsDir, tool);
+  if (activeProviders.includes("claude")) {
+    await applyMateSkills(getClaudeSkillsDir(companionPath), "claude");
+  }
+  if (isSharedSkillRootActive(activeProviders)) {
+    await applyMateSkills(getSharedSkillsDir(companionPath), "agents");
   }
 }
 
@@ -158,9 +183,8 @@ async function reconcileOpenSpecTools(
     cwd: ctx.companionPath,
   });
 
-  // The openspec CLI generates its own workflow skills above; layer the
-  // mate-authored skills on top for the same active providers.
-  await applyMateOpenspecSkills(ctx.companionPath, tools);
+  await removeLegacyOpenCodeCopies(ctx.companionPath);
+  await applyMateOpenspecSkills(ctx.companionPath, ctx.activeProviders);
 }
 
 async function updateOpenSpecIfOutdated(
@@ -393,12 +417,13 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
           }
         }
       }
+      await removeLegacyOpenCodeCopies(ctx.companionPath);
       await reconcileOpenSpecSchema(ctx);
     },
     async teardown(ctx) {
-      for (const tool of OPEN_SPEC_SUPPORTED_TOOLS) {
-        await teardownToolRuntime(ctx.companionPath, tool);
-      }
+      await teardownClaudeSkillRoot(ctx.companionPath);
+      await teardownSharedSkillRoot(ctx.companionPath);
+      await removeLegacyOpenCodeCopies(ctx.companionPath);
       await teardownOpenSpecSchema(ctx.companionPath);
     },
     forProvider: {
@@ -407,13 +432,16 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
         // contributes no archive-triggered Claude hook and no hook state.
         async apply() {},
         async teardown(ctx: SetupContext) {
-          await teardownToolRuntime(ctx.companionPath, "claude");
+          await teardownClaudeSkillRoot(ctx.companionPath);
         },
       },
       opencode: {
         async apply() {},
         async teardown(ctx: SetupContext) {
-          await teardownToolRuntime(ctx.companionPath, "opencode");
+          if (!isSharedSkillRootActive(ctx.activeProviders)) {
+            await teardownSharedSkillRoot(ctx.companionPath);
+          }
+          await removeLegacyOpenCodeCopies(ctx.companionPath);
         },
       },
     },

package/src/tools/setup/capabilities/react-doctor.ts

@@ -2,8 +2,11 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 import type { CapabilityPlugin, RuntimeContributionsByRuntime, SetupContext } from "../plugin";
+import { removeLegacyOpenCodeSkills } from "../providers/agents-skill-root";
 import { pruneEmptyAncestors } from "../utils";
 
+const SKILL_NAME = "react-doctor";
+
 const SKILL_SRC = path.join(
   import.meta.dirname,
   "../../../templates/capabilities/react-doctor/skill",
@@ -27,7 +30,7 @@ export function createReactDoctorPlugin(): CapabilityPlugin {
     // format the surface owns).
     getRuntimeContributions(ctx: SetupContext): RuntimeContributionsByRuntime {
       const hookCommand = `sh "${ctx.companionPath}/.claude/hooks/react-doctor.sh"`;
-      const skillTrees = [{ name: "react-doctor", sourceDir: SKILL_SRC }];
+      const skillTrees = [{ name: SKILL_NAME, sourceDir: SKILL_SRC }];
       return {
         claude: {
           hookGroups: [
@@ -57,22 +60,11 @@ export function createReactDoctorPlugin(): CapabilityPlugin {
       };
     },
     async apply(ctx: SetupContext) {
-      // Migrate: remove legacy shared .agents/skills/react-doctor/ from previous installs.
-      try {
-        await fs.rm(path.join(ctx.companionPath, ".agents", "skills", "react-doctor"), {
-          recursive: true,
-          force: true,
-        });
-      } catch {
-        /* not present */
-      }
-      await pruneEmptyAncestors(
-        path.join(ctx.companionPath, ".agents", "skills"),
-        ctx.companionPath,
-      );
-      await pruneEmptyAncestors(path.join(ctx.companionPath, ".agents"), ctx.companionPath);
+      await removeLegacyOpenCodeSkills(ctx.companionPath, [SKILL_NAME]);
+    },
+    async teardown(ctx: SetupContext) {
+      await removeLegacyOpenCodeSkills(ctx.companionPath, [SKILL_NAME]);
     },
-    async teardown() {},
     forProvider: {
       claude: {
         async apply(ctx: SetupContext) {

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

@@ -446,6 +446,7 @@ export function createTokensavePlugin(): CapabilityPlugin {
             await plan.run();
           },
           verify: () => tokensaveDeps.run(["--version"], process.cwd()).ok,
+          update: () => upgradeTokensave(process.cwd()),
         },
         ...(config.allowedAgents ?? [])
           .filter((agent) => TOKENSAVE_SUPPORTED_AGENTS.has(agent))

package/src/tools/setup/dynamic-plugins/frozen.ts

@@ -5,8 +5,14 @@ import path from "node:path";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
 import type { NpmInstallRunner, PluginInstallResult } from "./install";
 import { dynamicPluginsWorkspaceRoot } from "./paths";
-
-/** Raised before anything is installed: manifest or lockfile inputs are unusable. */
+import {
+  disallowedPluginMessage,
+  isPluginAllowed,
+  PluginPolicyError,
+  readPluginPolicy,
+} from "./policy";
+
+/** Raised before anything is installed: policy, manifest or lockfile inputs are unusable. */
 export class FrozenInstallError extends Error {}
 
 export interface FrozenInstallDeps {
@@ -106,7 +112,8 @@ async function treeMismatches(workspaceRoot: string, lock: Lockfile): Promise<st
 
 /**
  * Deployment restore: installs exactly what the committed lockfile records.
- * Inputs are validated before npm runs — the workspace manifest against the declarations, and the lockfile against the
+ * Inputs are validated before npm runs — the appliance allowlist, the
+ * workspace manifest against the declarations, and the lockfile against the
  * manifest — and neither tracked file is ever rewritten. An installed tree is
  * reused only when it matches the lockfile's versions and integrity.
  */
@@ -120,6 +127,20 @@ export async function installDeclaredPluginsFrozen(
   const desired: Record<string, string> = {};
   for (const declaration of sorted) desired[declaration.package] = declaration.version;
 
+  let policy: ReturnType<typeof readPluginPolicy>;
+  try {
+    policy = readPluginPolicy(deps.env ?? process.env);
+  } catch (error) {
+    if (error instanceof PluginPolicyError) throw new FrozenInstallError(error.message);
+    throw error;
+  }
+  const refused = sorted.filter((declaration) => !isPluginAllowed(policy, declaration.package));
+  if (refused.length > 0) {
+    throw new FrozenInstallError(
+      refused.map((declaration) => disallowedPluginMessage(declaration.package)).join("\n"),
+    );
+  }
+
   const manifestFile = path.join(workspaceRoot, "package.json");
   const lockFile = path.join(workspaceRoot, "package-lock.json");
   const [manifestText, lockText] = await Promise.all([readText(manifestFile), readText(lockFile)]);