@uniqbit/mate-core 0.15.4-canary.9 → 0.15.4

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

@@ -38,6 +38,12 @@ function getLegacyOwnershipPath(companionPath: string): string {
   return path.join(companionPath, ".mate", "state", "context-mode.json");
 }
 
+// Legacy install location from before the relocate-distribution-deps-to-plugins-local
+// change; self-heals on every apply the same way the ownership sidecar above does.
+function getLegacyInstallDir(companionPath: string): string {
+  return path.join(companionPath, ".mate", "dependencies", CONTEXT_MODE_PACKAGE_NAME);
+}
+
 function hasContextModeMcp(servers: Record<string, unknown>): boolean {
   return Object.entries(servers).some(
     ([name, value]) =>
@@ -117,6 +123,9 @@ export function createContextModePlugin(deps: ContextModePluginDeps = {}): Capab
       };
     },
     async apply(ctx) {
+      const legacyInstallDir = getLegacyInstallDir(ctx.companionPath);
+      await fs.rm(legacyInstallDir, { recursive: true, force: true });
+      await pruneEmptyAncestors(path.dirname(legacyInstallDir), ctx.companionPath);
       if (ctx.mode === "setup") {
         await installPackage(ctx.companionPath);
       } else {

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

@@ -134,6 +134,16 @@ async function reconcileOpenSpecTools(
 ): Promise<void> {
   const tools = deriveOpenSpecTools(ctx.activeProviders);
   if (tools.length === 0) return;
+  /** Best-effort: `config reset` is missing on older openspec releases. */
+  try {
+    await runCommand("openspec", ["config", "reset", "--all", "-y"], {
+      cwd: ctx.companionPath,
+    });
+  } catch (error) {
+    process.stderr.write(
+      `openspec config reset skipped: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+  }
 
   await runCommand("openspec", ["init", "--tools", tools.join(","), "--force", ctx.companionPath], {
     cwd: ctx.companionPath,
@@ -324,6 +334,7 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
             "Skill(openspec-apply-change)",
             "Skill(openspec-archive-change)",
             "Skill(mate-artifact-finish)",
+            "Skill(mate-openspec-backfill)",
             "Bash(openspec:*)",
             `Bash(${FRAMEWORK_NAME} cap graphify:*)`,
             `Bash(${path.join(getWrapperBinPath(), "openspec")}:*)`,

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

@@ -9,6 +9,7 @@ import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver"
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
 import { PLUGIN_DECLARATION_POLICIES } from "../../../lib/orchestrator/config-store";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import type { Plugin } from "../plugin";
 import type { PluginRegistry } from "../registry";
 import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
 
@@ -89,6 +90,16 @@ function validateDeclaration(entry: unknown): { declaration?: PluginDeclaration;
   return { declaration: entry as unknown as PluginDeclaration };
 }
 
+/**
+ * A framework declaration is the activation switch for a dynamic plugin.
+ * Own-property override rather than a spread: class-instance plugins keep
+ * their prototype members.
+ */
+function activateDeclaredPlugin(plugin: Plugin): Plugin {
+  plugin.isEnabled = () => true;
+  return plugin;
+}
+
 /**
  * Registers the companion's declared plugins into the active registry —
  * compiled-in plugins first (they are already registered), declared order
@@ -135,7 +146,10 @@ export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}
         );
       }
 
-      registry.register({ plugin: result.plugin, policy: declaration.policy ?? "optional" });
+      registry.register({
+        plugin: activateDeclaredPlugin(result.plugin),
+        policy: declaration.policy ?? "optional",
+      });
       hydratedPackages.add(declaration.package);
     }
   } catch (error) {

package/src/tools/setup/engine.ts

@@ -1,3 +1,4 @@
+// oxlint-disable no-await-in-loop
 import { getActiveDistribution } from "../../distribution";
 import { FRAMEWORK_NAME } from "../../framework";
 import type { FrameworkConfig } from "../../lib/orchestrator/types";
@@ -125,6 +126,8 @@ export async function executeSetupInstallationPlan(
   });
 
   for (const action of plan.actions) {
+    if (ctx.scope === "hub" && action.phase !== "provider") continue;
+
     const plugin = pluginById.get(action.pluginId);
     if (!plugin) {
       continue;
@@ -198,7 +201,7 @@ async function reconcileCapabilityContributions(
     const capability = plugin as CapabilityPlugin;
     if (!capability.getRuntimeContributions) continue;
     const enabled = enabledByPluginId.get(capability.id) ?? false;
-    const byRuntime = capability.getRuntimeContributions(ctx);
+    const byRuntime = await capability.getRuntimeContributions(ctx);
     for (const [runtimeId, contributions] of Object.entries(byRuntime)) {
       if (!contributions) continue;
       // Inactive runtimes still reconcile — with everything disabled — so a

package/src/tools/setup/mate.ts

@@ -4,7 +4,12 @@ import path from "node:path";
 import { pruneEmptyAncestors } from "./utils";
 
 export const MATE_ARTIFACT_SKILLS = ["mate-artifact-finish"] as const;
-export const MATE_SKILLS = ["mate-artifact-finish", "mate-create-report"] as const;
+export const MATE_SKILLS = [
+  "mate-artifact-finish",
+  "mate-create-report",
+  "mate-openspec-backfill",
+] as const;
+const LEGACY_MATE_SKILLS = ["mate-openspec-artifact-finish"] as const;
 
 const MATE_SKILLS_SOURCE = path.join(
   import.meta.dirname,
@@ -98,6 +103,9 @@ async function resolveMateSkillSource(skill: string, tool: string): Promise<stri
 }
 
 export async function applyMateSkills(skillsDir: string, tool: string): Promise<void> {
+  for (const skill of LEGACY_MATE_SKILLS) {
+    await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
+  }
   for (const skill of MATE_SKILLS) {
     const destination = path.join(skillsDir, skill);
     if (skill === "mate-create-report") {
@@ -110,7 +118,7 @@ export async function applyMateSkills(skillsDir: string, tool: string): Promise<
 }
 
 export async function teardownMateSkills(skillsDir: string, companionPath: string): Promise<void> {
-  for (const skill of MATE_SKILLS) {
+  for (const skill of [...MATE_SKILLS, ...LEGACY_MATE_SKILLS]) {
     try {
       await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
     } catch {

package/src/tools/setup/plugin.ts

@@ -2,11 +2,15 @@ import type { FrameworkConfig, LinkedRepository } from "../../lib/orchestrator/t
 import type { InstallRequirement, InstallRequirementContext } from "./install-contract";
 import type { ClaudeHookGroup } from "./providers/claude-format";
 
+export type SetupScope = "companion" | "hub";
+
 export interface SetupContext {
   companionPath: string;
   config: FrameworkConfig;
   mode: "setup" | "sync";
   activeProviders: string[];
+  /** Hub setup runs providers but excludes companion-only surfaces. */
+  scope?: SetupScope;
   /** Working repository path when syncing from a linked repo (e.g. during launch). */
   repoPath?: string;
   /**
@@ -153,6 +157,22 @@ export interface PluginReferenceContribution {
   configFiles?: string[];
 }
 
+/**
+ * A real, provider-native agent definition file, written to
+ * `<runtime dir>/agents/<name>.md` and selectable via `--agent <name>`.
+ * Unlike a guidance section, the whole file is managed content (no merge with
+ * unmanaged text) — the Capability pre-renders `content` per runtime, since
+ * frontmatter shape (Claude's `name`/`hidden`, OpenCode's `mode`) differs.
+ * Reconciled in both companion and hub scope: an agent definition is exactly
+ * the kind of artifact a repo-less hub needs.
+ */
+export interface AgentDefinitionContribution {
+  /** Agent name; the file is written to `<runtime dir>/agents/<name>.md`. */
+  name: string;
+  /** Full file content, including frontmatter, ready to write as-is. */
+  content: string;
+}
+
 /**
  * Declarative Agent Runtime contributions of one Capability for one runtime.
  * The runtime's Runtime Surface reconciles these symmetrically: applied while
@@ -165,6 +185,7 @@ export interface RuntimeContributions {
   guidanceSections?: GuidanceSectionContribution[];
   skillTrees?: SkillTreeContribution[];
   pluginReferences?: PluginReferenceContribution[];
+  agentDefinitions?: AgentDefinitionContribution[];
 }
 
 /**
@@ -193,9 +214,12 @@ export interface CapabilityPlugin extends Plugin {
    * Declare Agent Runtime contributions as data. Called on every setup/sync
    * pass for all registered Capabilities — enabled ones contribute their
    * entries, disabled ones only widen the managed strip set so their previous
-   * entries are removed.
+   * entries are removed. May be async (e.g. reading a companion-local
+   * override file) — the engine always awaits the result.
    */
-  getRuntimeContributions?(ctx: SetupContext): RuntimeContributionsByRuntime;
+  getRuntimeContributions?(
+    ctx: SetupContext,
+  ): RuntimeContributionsByRuntime | Promise<RuntimeContributionsByRuntime>;
   forProvider?: Record<
     string,
     {

package/src/tools/setup/plugins/gitignore.ts

@@ -61,12 +61,15 @@ export async function writeManagedGitignoreBlock(
 
 export function collectManagedGitignoreEntries(ctx: SetupContext, plugins: Plugin[]): string[] {
   // Baseline for every companion: node_modules never versions wherever a tool
-  // materializes it, and everything directly under the dependencies tree
-  // (context-mode, future consumers) is regenerated by setup/install —
-  // version pins live in .mate/config and in code, never in the tree itself.
+  // materializes it, and the machine-local distribution-dependencies workspace
+  // (.mate/plugins/.local/ — context-mode, future consumers) is regenerated by
+  // setup/install in full — version pins live in .mate/config and in code,
+  // never in the tree itself. This is distinct from the committed dynamic-
+  // plugins workspace at .mate/plugins/, whose package.json and lockfile stay
+  // trackable.
   const entries = [
     "node_modules/",
-    `.${FRAMEWORK_NAME}/dependencies/*`,
+    `.${FRAMEWORK_NAME}/plugins/.local/`,
     ".mcp.json*",
     ...plugins
       .filter((p) => p.kind !== "root" && (p.isEnabled(ctx.config) || p.persistGitignoreEntries))

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

@@ -346,6 +346,12 @@ export async function reconcileClaudeContributions(
 ): Promise<void> {
   const { companionPath, config } = ctx;
 
+  if (ctx.scope === "hub") {
+    await reconcileClaudeMcpContributions(ctx, inputs);
+    await reconcileClaudeAgentDefinitionContributions(ctx, inputs);
+    return;
+  }
+
   // The settings sync (re)creates the managed settings document, so it only
   // runs while the Claude runtime is active; a deactivated runtime's pass is
   // teardown-only and must not resurrect files the provider teardown removed.
@@ -353,15 +359,10 @@ export async function reconcileClaudeContributions(
     await syncCompanionClaudeSettings(companionPath, config, inputs);
   }
 
-  for (const input of inputs) {
-    for (const descriptor of input.contributions.mcpServers ?? []) {
-      await updateClaudeMcpServer(
-        getCompanionClaudeMcpConfigPath(companionPath),
-        descriptor.name,
-        input.enabled ? toClaudeMcpEntry(descriptor) : null,
-      );
-    }
+  await reconcileClaudeMcpContributions(ctx, inputs);
+  await reconcileClaudeAgentDefinitionContributions(ctx, inputs);
 
+  for (const input of inputs) {
     // Guidance sections are managed blocks in CLAUDE.md. Current sections are
     // upserted, then stale keys (content changes, disabled capability) are
     // swept. CLAUDE.md is Claude-exclusive, so no shared-file guard applies.
@@ -389,6 +390,46 @@ export async function reconcileClaudeContributions(
   }
 }
 
+/** Reconcile only MCP entries without touching Claude settings or guidance. */
+async function reconcileClaudeMcpContributions(
+  ctx: SetupContext,
+  inputs: CapabilityContributionInput[],
+): Promise<void> {
+  for (const input of inputs) {
+    for (const descriptor of input.contributions.mcpServers ?? []) {
+      await updateClaudeMcpServer(
+        getCompanionClaudeMcpConfigPath(ctx.companionPath),
+        descriptor.name,
+        input.enabled ? toClaudeMcpEntry(descriptor) : null,
+      );
+    }
+  }
+}
+
+/**
+ * Reconcile declared agent definition files under `.claude/agents/`. Runs in
+ * both companion and hub scope — an agent definition is fully self-contained
+ * (no shared-file merge), so it needs no companion-only surface.
+ */
+async function reconcileClaudeAgentDefinitionContributions(
+  ctx: SetupContext,
+  inputs: CapabilityContributionInput[],
+): Promise<void> {
+  const agentsDir = path.join(ctx.companionPath, ".claude", "agents");
+  for (const input of inputs) {
+    for (const agent of input.contributions.agentDefinitions ?? []) {
+      const agentPath = path.join(agentsDir, `${agent.name}.md`);
+      if (input.enabled) {
+        await fs.mkdir(agentsDir, { recursive: true });
+        await fs.writeFile(agentPath, agent.content, "utf8");
+      } else {
+        await fs.rm(agentPath, { force: true });
+        await pruneEmptyAncestors(agentsDir, ctx.companionPath);
+      }
+    }
+  }
+}
+
 // Maintain the companion `.mcp.json` shell. Managed MCP servers are reconciled
 // from declared Capability contributions (and legacy `ctx.mcp` hosting); this
 // only guarantees the file exists with an `mcpServers` map. Loaded at launch
@@ -688,6 +729,10 @@ export function createClaudePlugin(): ProviderPlugin {
       },
     },
     async apply(ctx) {
+      if (ctx.scope === "hub") {
+        await syncCompanionClaudeSettings(ctx.companionPath, ctx.config);
+        return;
+      }
       await configureClaude(ctx.companionPath);
       await configureClaudeGuidance(ctx.companionPath);
       await teardownLegacyClaudeBin(ctx.companionPath);

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

@@ -426,15 +426,16 @@ export async function reconcileOpenCodeContributions(
 ): Promise<void> {
   const { companionPath } = ctx;
 
-  for (const input of inputs) {
-    for (const descriptor of input.contributions.mcpServers ?? []) {
-      await updateOpenCodeMcpServer(
-        getCompanionOpenCodeConfigPath(companionPath),
-        descriptor.name,
-        input.enabled ? toOpenCodeMcpEntry(descriptor) : null,
-      );
-    }
+  if (ctx.scope === "hub") {
+    await reconcileOpenCodeMcpContributions(ctx, inputs);
+    await reconcileOpenCodeAgentDefinitionContributions(ctx, inputs);
+    return;
+  }
+
+  await reconcileOpenCodeMcpContributions(ctx, inputs);
+  await reconcileOpenCodeAgentDefinitionContributions(ctx, inputs);
 
+  for (const input of inputs) {
     for (const pluginReference of input.contributions.pluginReferences ?? []) {
       const configFiles = pluginReference.configFiles ?? OPENCODE_CONTRIBUTION_CONFIG_FILES;
       for (const name of configFiles) {
@@ -479,6 +480,47 @@ export async function reconcileOpenCodeContributions(
   }
 }
 
+/** Reconcile only MCP entries without touching OpenCode plugins or guidance. */
+async function reconcileOpenCodeMcpContributions(
+  ctx: SetupContext,
+  inputs: CapabilityContributionInput[],
+): Promise<void> {
+  for (const input of inputs) {
+    for (const descriptor of input.contributions.mcpServers ?? []) {
+      await updateOpenCodeMcpServer(
+        getCompanionOpenCodeConfigPath(ctx.companionPath),
+        descriptor.name,
+        input.enabled ? toOpenCodeMcpEntry(descriptor) : null,
+      );
+    }
+  }
+}
+
+/**
+ * Reconcile declared agent definition files under `.opencode/agents/`. Runs
+ * in both companion and hub scope — an agent definition is fully
+ * self-contained (no shared-file merge), so it needs no companion-only
+ * surface.
+ */
+async function reconcileOpenCodeAgentDefinitionContributions(
+  ctx: SetupContext,
+  inputs: CapabilityContributionInput[],
+): Promise<void> {
+  const agentsDir = path.join(ctx.companionPath, ".opencode", "agents");
+  for (const input of inputs) {
+    for (const agent of input.contributions.agentDefinitions ?? []) {
+      const agentPath = path.join(agentsDir, `${agent.name}.md`);
+      if (input.enabled) {
+        await fs.mkdir(agentsDir, { recursive: true });
+        await fs.writeFile(agentPath, agent.content, "utf8");
+      } else {
+        await fs.rm(agentPath, { force: true });
+        await pruneEmptyAncestors(agentsDir, ctx.companionPath);
+      }
+    }
+  }
+}
+
 export function createOpenCodePlugin(): ProviderPlugin {
   return {
     id: "opencode",
@@ -509,6 +551,7 @@ export function createOpenCodePlugin(): ProviderPlugin {
       },
     },
     async apply(ctx: SetupContext) {
+      if (ctx.scope === "hub") return;
       await syncOpenCodeRuntimeFiles(
         path.join(getSetupProvidersRoot(), "opencode"),
         ctx.companionPath,

package/src/tools/setup.ts

@@ -1,5 +1,4 @@
 // oxlint-disable no-await-in-loop
-import fs from "node:fs/promises";
 import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../framework";
@@ -25,7 +24,7 @@ import {
   collectManagedGitignoreEntries,
   writeManagedGitignoreBlock,
 } from "./setup/plugins/gitignore";
-import type { PluginRegistration, SetupContext } from "./setup/plugin";
+import type { PluginRegistration, SetupContext, SetupScope } from "./setup/plugin";
 import { getActiveDistribution } from "../distribution";
 import { createUvPlugin } from "./setup/package-managers/uv";
 import type { PackageManagerSetupDeps } from "./setup/package-managers/uv";
@@ -60,10 +59,11 @@ export async function applySetupCompatibilities(
   mode: "setup" | "sync",
   plugins: PluginRegistration[] = getActiveDistribution().registry.getEntries(),
   repoPath?: string,
+  scope: SetupScope = config.type === "hub" ? "hub" : "companion",
 ): Promise<SetupInstallationOutcome> {
   const plan = buildSetupInstallationPlan(config, plugins);
   const activeProviders = plan.activeProviders;
-  const ctx: SetupContext = { companionPath, config, mode, activeProviders, repoPath };
+  const ctx: SetupContext = { companionPath, config, mode, activeProviders, repoPath, scope };
   return executeSetupInstallationPlan(ctx, plugins, plan);
 }
 
@@ -91,48 +91,6 @@ export async function syncCompanionFiles(
   );
 }
 
-export function mateFolderReadme(): string {
-  const n = FRAMEWORK_NAME;
-  const packageName =
-    getActiveDistribution().config.update?.packageName ?? `@uniqbit/${FRAMEWORK_NAME}`;
-  return [
-    `# .${FRAMEWORK_NAME}`,
-    ``,
-    `This directory is managed by the **${FRAMEWORK_NAME}** companion framework (\`${packageName}\`).`,
-    ``,
-    `The ${FRAMEWORK_NAME} framework keeps your AI agent's companion artifacts separate from the code it works on.`,
-    `Specs, notes, and agent config live here; code stays in the linked working repository.`,
-    ``,
-    `## Common commands`,
-    ``,
-    `| Command | Description |`,
-    `|---|---|`,
-    `| \`${n} companion setup\` | Initialize or re-configure this companion |`,
-    `| \`${n} companion link\` | Link a working repository to a companion |`,
-    `| \`${n} companion list\` | List linked repositories for the active working repo context |`,
-    `| \`${n} companion open\` | Inject the resolved companion into the current editor window |`,
-    `| \`${n} claude\` / \`${n} opencode\` | Launch an allowed agent from a linked working repository |`,
-    `| \`${n} doctor\` | Check current link state, installed tools, and active capabilities |`,
-    ``,
-    `Run \`${n} claude\` or \`${n} opencode\` from any linked working repository directory.`,
-    ``,
-    `## Configuration`,
-    ``,
-    `Edit \`.${FRAMEWORK_NAME}/config/framework.yaml\` to configure:`,
-    ``,
-    `- **allowedAgents** — agents permitted to launch from linked repositories`,
-    `- **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");
-}
-
-async function writeMateReadme(companionPath: string): Promise<void> {
-  const readmePath = path.join(companionPath, `.${FRAMEWORK_NAME}`, "README.md");
-  await fs.mkdir(path.dirname(readmePath), { recursive: true });
-  await fs.writeFile(readmePath, mateFolderReadme(), "utf8");
-}
-
 export const setupToolDeps = {
   executeSetup: (input: SetupInput) => executeSetup(input),
 };
@@ -160,14 +118,6 @@ export async function executeSetup(
     deps.configStore ??
     new ConfigStore(path.join(cwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"));
   const config = mergeWithDefaults(await configStore.load());
-  // Hubs are never companions: no setup entry path (CLI, wizard, or the
-  // setup framework tool) may write agent guidance into a hub root.
-  if (config.type === "hub") {
-    throw new ConfigError(
-      `A companion hub cannot be set up as a companion: ${cwd}. Use \`${FRAMEWORK_NAME} hub\` commands to manage the hub.`,
-    );
-  }
-
   if (input.allowedAgents !== undefined) {
     config.allowedAgents = [...new Set(input.allowedAgents)];
   }
@@ -202,12 +152,13 @@ export async function executeSetup(
     await hydrateDynamicPlugins({ companionPath });
   }
   await applySetupCompatibilities(companionPath, config, "setup");
-  await invalidateInstallState({ kind: "companion", companionPath });
+  await invalidateInstallState({
+    kind: config.type === "hub" ? "hub" : "companion",
+    companionPath,
+  });
 
   await globalConfigStore.register(companionPath);
 
-  await writeMateReadme(companionPath);
-
   // Setup no longer fans out to linked repos: capabilities that touch a working repo
   // (companion files on launch, the tokensave/graphify graph via `mate cap index`)
   // are applied in that repo's own context, not eagerly from here.