@uniqbit/mate-core 0.15.4-canary.11 → 0.15.4-canary.12

package/package.json

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

package/src/hooks/artifact-finish-nudge.ts

@@ -79,6 +79,36 @@ function extractChangeFromPath(value: string): string | null {
   return match ? match[1].replace(/^\d{4}-\d{2}-\d{2}-/, "") : null;
 }
 
+// Best-effort shell variable substitution, NOT a shell interpreter: a change
+// name is often built up through variables (DEST="...archive/$TARGET"; mv a
+// "$DEST") rather than appearing as a literal path next to mv/archive. This
+// resolves $NAME/${NAME} references against preceding literal NAME=value
+// assignment tokens in the same command string; unresolved references are
+// left as-is, which keeps prior (silent) behavior for anything it can't follow.
+const ASSIGNMENT_PATTERN = /^([A-Za-z_][A-Za-z0-9_]*)=([\s\S]*)$/;
+const VARIABLE_REFERENCE_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+
+function substituteVariables(value: string, vars: Map<string, string>): string {
+  return value.replace(VARIABLE_REFERENCE_PATTERN, (match, braced: string, bare: string) => {
+    const name = braced ?? bare;
+    return vars.has(name) ? vars.get(name)! : match;
+  });
+}
+
+// Assignments are collected in left-to-right token order so a later
+// assignment (e.g. DEST) can reference an earlier one (e.g. TARGET) the same
+// way the shell would resolve it at that point in the script.
+function collectVariableAssignments(parts: string[]): Map<string, string> {
+  const vars = new Map<string, string>();
+  for (const part of parts) {
+    const match = part.match(ASSIGNMENT_PATTERN);
+    if (!match) continue;
+    const [, name, rawValue] = match;
+    vars.set(name, substituteVariables(rawValue, vars));
+  }
+  return vars;
+}
+
 // Shell syntax tokens are never change-name positionals: separators end the
 // archive invocation, redirections are skipped (a bare operator also consumes
 // its target token).
@@ -95,6 +125,7 @@ export function extractArchiveCommand(command: string): string | null {
       (parts[position - 1] === "openspec" || parts[position - 1].endsWith("/openspec")),
   );
   if (index < 0) return null;
+  const vars = collectVariableAssignments(parts);
   for (let position = index + 1; position < parts.length; position += 1) {
     const part = parts[position];
     if (!part || part === "--") continue;
@@ -107,7 +138,7 @@ export function extractArchiveCommand(command: string): string | null {
       if (part === "--store") position += 1;
       continue;
     }
-    return part;
+    return substituteVariables(part, vars);
   }
   return null;
 }
@@ -130,15 +161,16 @@ function isPython(part: string): boolean {
 
 export function extractMoveCommand(command: string): string | null {
   const parts = shellSplit(command);
+  const vars = collectVariableAssignments(parts);
   for (let index = 0; index < parts.length; index += 1) {
     if (MOVE_COMMANDS.has(parts[index].toLowerCase())) {
       for (const part of parts.slice(index + 1)) {
-        const change = extractChangeFromPath(part);
+        const change = extractChangeFromPath(substituteVariables(part, vars));
         if (change) return change;
       }
     }
     if (isPython(parts[index]) && /(?:shutil\.move|os\.rename|\.rename\s*\()/.test(command)) {
-      return extractChangeFromPath(command);
+      return extractChangeFromPath(substituteVariables(command, vars));
     }
   }
   return null;

package/src/lib/orchestrator/companion-git-sync.ts

@@ -9,6 +9,9 @@ import { LaunchPreflightError } from "./types";
 
 const execFile = promisify(execFileCallback);
 
+/** Bounded but far above any diagnostic output; default 1 MiB kills git mid-merge on large trees. */
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+
 export interface GitCommandResult {
   status: number;
   stdout: string;
@@ -26,22 +29,30 @@ export interface CompanionGitSyncResult {
 export class CompanionGitSyncError extends LaunchPreflightError {
   readonly companionPath: string;
   readonly conflictingPaths: string[];
+  readonly reason: string;
+  readonly recovery: string;
+  readonly stashRef: string | undefined;
 
   constructor(
     companionPath: string,
     reason: string,
     conflictingPaths: string[] = [],
     recovery = "Resolve or abort the Git operation, then retry the launch.",
+    stashRef?: string,
   ) {
     const conflicts = conflictingPaths.length
       ? `\n  Conflicting paths:\n${conflictingPaths.map((entry) => `    - ${entry}`).join("\n")}`
       : "";
+    const stash = stashRef
+      ? `  Local changes were stashed as ${stashRef}. Recover with \`git stash apply ${stashRef}\` in the companion.`
+      : "";
     super(
       [
         "mate: companion Git synchronization failed.",
         `  Companion: ${companionPath}`,
         `  ${reason}`,
         conflicts,
+        stash,
         `  ${recovery}`,
         "  Bypass: `mate claude -- --no-git` or `mate opencode -- --no-git`.",
       ]
@@ -51,6 +62,9 @@ export class CompanionGitSyncError extends LaunchPreflightError {
     this.name = "CompanionGitSyncError";
     this.companionPath = companionPath;
     this.conflictingPaths = conflictingPaths;
+    this.reason = reason;
+    this.recovery = recovery;
+    this.stashRef = stashRef;
   }
 }
 
@@ -68,6 +82,7 @@ export const companionGitSyncDeps: { runGit: GitRunner } = {
         cwd,
         encoding: "utf8",
         env: gitEnv,
+        maxBuffer: GIT_MAX_BUFFER,
       });
       return { status: 0, stdout: String(result.stdout), stderr: String(result.stderr) };
     } catch (error) {
@@ -106,6 +121,21 @@ function outputLines(stdout: string): string[] {
     .filter(Boolean);
 }
 
+/** Matches Git progress-meter lines such as `Updating files:  76% (11340/14790)` or `..., done.` */
+const GIT_PROGRESS_LINE = /^\S.*?: +\d+% \(\d+\/\d+\)(?:, done\.)?$/;
+
+function stripGitProgress(text: string): string {
+  return text
+    .split(/\r\n|\r|\n/)
+    .filter((line) => !GIT_PROGRESS_LINE.test(line.trim()))
+    .join("\n")
+    .trim();
+}
+
+export function describeGitFailure(result: GitCommandResult): string {
+  return stripGitProgress(result.stderr) || stripGitProgress(result.stdout) || "unknown Git error";
+}
+
 export class CompanionGitSync {
   constructor(private readonly runGit: GitRunner = companionGitSyncDeps.runGit) {}
 
@@ -160,7 +190,42 @@ export class CompanionGitSync {
       stashRef = ref.stdout.trim();
     }
 
-    const merge = await this.command(companionPath, ["merge", target.ref, "--no-edit"]);
+    const headBefore = await this.command(companionPath, ["rev-parse", "HEAD"]);
+    try {
+      await this.mergeAndRestore(companionPath, target, stashRef);
+    } catch (error) {
+      if (stashRef && error instanceof CompanionGitSyncError && !error.stashRef) {
+        throw new CompanionGitSyncError(
+          error.companionPath,
+          error.reason,
+          error.conflictingPaths,
+          error.recovery,
+          stashRef,
+        );
+      }
+      throw error;
+    }
+
+    const headAfter = await this.command(companionPath, ["rev-parse", "HEAD"]);
+    return {
+      skipped: false,
+      changed: headBefore.stdout.trim() !== headAfter.stdout.trim(),
+      companionPath,
+    };
+  }
+
+  private async mergeAndRestore(
+    companionPath: string,
+    target: SyncTarget,
+    stashRef: string | undefined,
+  ): Promise<void> {
+    const merge = await this.command(companionPath, [
+      "merge",
+      target.ref,
+      "--no-stat",
+      "--no-progress",
+      "--no-edit",
+    ]);
     if (merge.status !== 0) {
       await this.resolveManagedConflicts(companionPath, target.ref);
       const conflicts = await this.unresolvedPaths(companionPath);
@@ -220,12 +285,6 @@ export class CompanionGitSync {
       // Keep the stash if dropping it fails; it remains a recoverable backup.
       await this.command(companionPath, ["stash", "drop", stashRef]);
     }
-
-    return {
-      skipped: false,
-      changed: merge.status === 0 && merge.stdout.trim() !== "",
-      companionPath,
-    };
   }
 
   private async assertSafeCompanionRoot(
@@ -410,7 +469,7 @@ export class CompanionGitSync {
   }
 
   private detail(result: GitCommandResult): string {
-    return (result.stderr || result.stdout || "unknown Git error").trim();
+    return describeGitFailure(result);
   }
 
   private failure(

package/src/opencode/companion-hooks.ts

@@ -179,15 +179,12 @@ function detectCommandArchive(input: unknown, output: unknown): string | null {
 
 function detectNewlyArchivedChanges(archiveDir: string, snapshot: Set<string>): string[] {
   const current = readArchiveEntries(archiveDir);
-  const newlyArchived = [...current].filter((entry) => !snapshot.has(entry)).toSorted();
-  snapshot.clear();
-  for (const entry of current) snapshot.add(entry);
-  return newlyArchived;
+  return [...current].filter((entry) => !snapshot.has(entry)).toSorted();
 }
 
 function appendOpenSpecFinishNudge(
   context: CompanionContext,
-  archiveSnapshot: Set<string>,
+  archiveSnapshot: Set<string> | undefined,
   nudgedCommandChanges: Set<string>,
   input: { tool?: unknown },
   output: { output?: string },
@@ -196,8 +193,10 @@ function appendOpenSpecFinishNudge(
 
   const archiveDir = path.join(context.companionPath, "openspec", "changes", "archive");
   const changes: string[] = [];
-  for (const entry of detectNewlyArchivedChanges(archiveDir, archiveSnapshot)) {
-    changes.push(entry.slice("YYYY-MM-DD-".length));
+  if (archiveSnapshot) {
+    for (const entry of detectNewlyArchivedChanges(archiveDir, archiveSnapshot)) {
+      changes.push(entry.slice("YYYY-MM-DD-".length));
+    }
   }
   const commandChange =
     String(input.tool ?? "").toLowerCase() === "bash" ? detectCommandArchive(input, output) : null;
@@ -313,22 +312,36 @@ async function runReactDoctorScan(
 }
 
 type PluginEventInput = Parameters<NonNullable<Hooks["event"]>>[0];
+type ToolBeforeInput = Parameters<NonNullable<Hooks["tool.execute.before"]>>[0];
+type ToolBeforeOutput = Parameters<NonNullable<Hooks["tool.execute.before"]>>[1];
 type ToolAfterInput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[0];
 type ToolAfterOutput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[1];
 
+interface ArchiveCallSnapshot {
+  sessionID: string;
+  entries: Set<string>;
+}
+
 export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInput) => {
   const { client, $ } = pluginInput;
   const context = readContext(process.env.MATE_ARTIFACT_PATH ?? "");
   if (!context.companionPath || !context.repositoryPath) return {};
 
   const archiveDir = path.join(context.companionPath, "openspec", "changes", "archive");
-  const archiveSnapshot = readArchiveEntries(archiveDir);
+  const archiveCallSnapshots = new Map<string, ArchiveCallSnapshot>();
   const nudgedCommandChanges = new Set<string>();
   const dirtyReactDoctorSessions = new Set<string>();
   const reactDoctorScansInFlight = new Set<string>();
 
   return {
     event: async ({ event }: PluginEventInput) => {
+      if (event.type === "session.deleted") {
+        const sessionID = event.properties.info.id;
+        for (const [callID, snapshot] of archiveCallSnapshots) {
+          if (snapshot.sessionID === sessionID) archiveCallSnapshots.delete(callID);
+        }
+        return;
+      }
       if (event.type !== "session.idle") return;
       const sessionID = event.properties.sessionID;
       if (
@@ -340,10 +353,7 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
       }
       await runReactDoctorScan(context, client, $, sessionID, reactDoctorScansInFlight);
     },
-    "tool.execute.before": async (
-      input: { tool: unknown },
-      output: { args: { filePath?: unknown; patchText?: unknown } | undefined },
-    ) => {
+    "tool.execute.before": async (input: ToolBeforeInput, output: ToolBeforeOutput) => {
       const toolName = String(input.tool ?? "");
       const args = output.args ?? {};
       if (["write", "edit"].includes(toolName)) {
@@ -359,13 +369,24 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
           }
         }
       }
+      if (context.gitAutoModeEnabled) {
+        archiveCallSnapshots.set(input.callID, {
+          sessionID: input.sessionID,
+          entries: readArchiveEntries(archiveDir),
+        });
+      }
     },
     "tool.execute.after": async (input: ToolAfterInput, output: ToolAfterOutput) => {
       if (context.reactDoctorEnabled && REACT_DOCTOR_EDIT_TOOLS.has(input.tool)) {
         dirtyReactDoctorSessions.add(input.sessionID);
       }
+      const archiveSnapshot = archiveCallSnapshots.get(input.callID)?.entries;
+      archiveCallSnapshots.delete(input.callID);
       appendOpenSpecFinishNudge(context, archiveSnapshot, nudgedCommandChanges, input, output);
     },
+    dispose: async () => {
+      archiveCallSnapshots.clear();
+    },
   };
 };
 

package/src/playbooks/companion-guidance.ts

@@ -103,7 +103,7 @@ export function buildCompanionPolicyXml(
 
   if (hasOpenspecCapability(context.capabilities)) {
     lines.push(
-      `    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: ${FRAMEWORK_NAME} artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>`,
+      `    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes by archiving them: the archive triggers a nudge directing you to run ${FRAMEWORK_NAME} artifact finish "<name>" --json — if no nudge arrives, invoke that command yourself. It is the only sanctioned completion; never hand-commit or hand-tag a finish. Finishing a still-active change archives it and applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>`,
     );
   }
 

package/src/templates/capabilities/openspec-cap/mate-skills/agents/mate-openspec-backfill/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: mate-openspec-backfill
+description: Reverse-engineer an OpenSpec spec for one existing feature and emit a ready-to-finish backfill change. Use when the user wants to backfill, document, or spec existing or legacy behavior that has no spec yet.
+allowed-tools: Bash(openspec:*), Bash(mate:*)
+license: MIT
+compatibility: Requires the mate CLI and the openspec capability enabled.
+metadata:
+  author: mate
+  version: "1.0"
+---
+
+Create a spec for one feature that already exists in the working repository. The run ends with a standard ready-to-finish change — it never edits main specs and never finishes.
+
+## Scope rules
+
+- **One named feature per run.** Refuse Area-wide or repository-wide sweeps; ask the user to name a single feature and run the skill once per feature.
+- **Interactive by design.** Every ambiguity and every suspected bug becomes a user question. Do not run this skill unattended.
+
+## Steps
+
+1. **Scope.** Map the named feature to code: entry points, callees, tests. Use whatever exploration tooling this project has enabled (code-graph or index tools when present, otherwise search and targeted reading) — assume no specific capability is installed. Then check `openspec/specs/` for an existing capability covering this domain — prefer extending it (`MODIFIED`/`ADDED` deltas) over minting a new capability id.
+
+2. **Sweep.** Extract candidate behaviors and tag each finding:
+   - `[test-backed]` — an existing test verifies it (strongest; scenarios translate almost directly from tests)
+   - `[code-only]` — observable in code but untested
+   - `[inferred]` — assumed intent without direct evidence
+
+   Every candidate requirement needs at least one citation: a test name or `file:line`. Docs and comments corroborate but never stand alone. `[inferred]` findings are not requirements — they become questions for step 3.
+
+3. **Ask.** Batch the open questions to the user:
+   - Behavior that looks unintended → the user rules **spec the actual behavior** or **spec the intent** (with a follow-up fix change). Suspected bugs never silently become requirements.
+   - `[inferred]` findings → confirm, demote to out-of-scope, or convert to a question the emitted proposal records as open.
+
+4. **Emit.** Create the change and build its artifacts in dependency order:
+
+   ```bash
+   openspec new change "backfill-spec-<capability>"
+   openspec status --change "backfill-spec-<capability>" --json
+   openspec instructions <artifact-id> --change "backfill-spec-<capability>" --json
+   ```
+
+   The artifact set comes from the active schema (`schemaName` in the status JSON) — never assume a fixed artifact list. Follow each artifact's returned instructions and template, and state the active schema in the proposal so reviewers know which workflow produced the change. Map the backfill roles onto whatever artifacts the schema defines:
+
+   | Backfill role                                                                                  | Typical artifact (mate-v1 example) |
+   | ---------------------------------------------------------------------------------------------- | ---------------------------------- |
+   | Scope decisions and rulings from step 3                                                        | explore-brief.md                   |
+   | "Documents existing behavior, no code changes" + open questions                                | proposal.md                        |
+   | `ADDED`/`MODIFIED` requirements, behavior only, one citation each                              | specs/                             |
+   | As-built evidence dossier: entry points, test inventory, `file:line` citations per requirement | design.md                          |
+   | Verification checklist: one task per requirement, "confirm behavior at <citation>"             | tasks.md                           |
+
+   The verification task artifact MUST open with this rule, verbatim, so the applying agent sees it without knowing this skill: "These are verification tasks for a docs-only backfill change. If a requirement fails verification, update the delta spec (reword, drop, or re-cite the requirement) — never modify code in this change. A real bug found here becomes a separate fix change."
+
+   Requirements state observable contracts, never implementation detail ("propagates the child exit code", not "uses spawnSync").
+
+5. **Stop.** Report the change as ready-to-finish and hand off:
+   - Verify: `openspec-apply-change` works through tasks.md, checking each requirement against the code.
+   - Finish: `mate-artifact-finish` applies the deltas to main specs and anchors the change.
+
+## Guardrails
+
+- Never write files under `openspec/specs/` — main specs change only through finished changes.
+- Never invoke any finish flow (`mate artifact finish`, `openspec archive`); stop at ready-to-finish.
+- Never emit a requirement without a citation, and never spec a suspected bug without the user's ruling.
+- Keep capability ids opaque kebab-case; extend existing capabilities before creating new ones.

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

@@ -194,7 +194,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -230,7 +230,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }
@@ -407,7 +407,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -443,7 +443,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }
@@ -793,7 +793,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
       },
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -808,7 +808,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }
@@ -1009,7 +1009,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       },
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -1024,7 +1024,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }
@@ -1312,7 +1312,7 @@ Canonical Mate policy and any more specific tool-routing instructions remain aut
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
       "context-mode@1.0.169",
     ],
     "references": {
@@ -1328,7 +1328,7 @@ Canonical Mate policy and any more specific tool-routing instructions remain aut
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
       "context-mode@1.0.169",
     ],
   },
@@ -1472,7 +1472,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
       "context-mode@1.0.169",
     ],
     "references": {
@@ -1488,7 +1488,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
       "context-mode@1.0.169",
     ],
   },
@@ -1784,7 +1784,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -1802,7 +1802,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }
@@ -1968,7 +1968,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -1986,7 +1986,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }
@@ -2155,6 +2155,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
         "Edit(<root>/companion/**)",
         "Read(<root>/companion/**)",
         "Skill(mate-artifact-finish)",
+        "Skill(mate-openspec-backfill)",
         "Skill(openspec-apply-change)",
         "Skill(openspec-archive-change)",
         "Skill(openspec-explore)",
@@ -2206,7 +2207,7 @@ exports[`runtime surface golden fixtures setup openspec × claude 2`] = `
     <rule id="local-artifact-exception" severity="critical">Only write artifacts in <root>/working when the exact path is gitignored AND intentionally local-only; otherwise use <root>/companion.</rule>
     <rule id="guardrail" severity="critical">Bad artifact writes to <root>/working are rejected. Classify correctly first.</rule>
     <rule id="wrapper-only-cli-execution" severity="critical">For every CLI declared in cli-tools, invoke the exact path in its invokeAs attribute. Correct: <wrapper-bin>/openspec status ... . Incorrect: openspec status ... . Do not run bare openspec or graphify commands and do not rely on PATH, aliases, or shell functions. If the exact wrapper path is unavailable, stop and report it.</rule>
-    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: mate artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>
+    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes by archiving them: the archive triggers a nudge directing you to run mate artifact finish "<name>" --json — if no nudge arrives, invoke that command yourself. It is the only sanctioned completion; never hand-commit or hand-tag a finish. Finishing a still-active change archives it and applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>
   </mandatory-rules>
 </companion-policy>"
 ,
@@ -2260,7 +2261,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -2280,7 +2281,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }
@@ -2319,7 +2320,7 @@ exports[`runtime surface golden fixtures setup openspec × opencode 2`] = `
     <rule id="local-artifact-exception" severity="critical">Only write artifacts in $MATE_REPO_PATH when the exact path is gitignored AND intentionally local-only; otherwise use $MATE_ARTIFACT_PATH.</rule>
     <rule id="guardrail" severity="critical">Bad artifact writes to $MATE_REPO_PATH are rejected. Classify correctly first.</rule>
     <rule id="wrapper-only-cli-execution" severity="critical">For every CLI declared in cli-tools, invoke the exact path in its invokeAs attribute. Correct: $MATE_WRAPPER_BIN_PATH/openspec status ... . Incorrect: openspec status ... . Do not run bare openspec or graphify commands and do not rely on PATH, aliases, or shell functions. If the exact wrapper path is unavailable, stop and report it.</rule>
-    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: mate artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>
+    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes by archiving them: the archive triggers a nudge directing you to run mate artifact finish "<name>" --json — if no nudge arrives, invoke that command yourself. It is the only sanctioned completion; never hand-commit or hand-tag a finish. Finishing a still-active change archives it and applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>
   </mandatory-rules>
 </companion-policy>"
 ,
@@ -2406,6 +2407,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
         "Edit(<root>/companion/**)",
         "Read(<root>/companion/**)",
         "Skill(mate-artifact-finish)",
+        "Skill(mate-openspec-backfill)",
         "Skill(openspec-apply-change)",
         "Skill(openspec-archive-change)",
         "Skill(openspec-explore)",
@@ -2427,7 +2429,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -2447,7 +2449,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }
@@ -2484,7 +2486,7 @@ exports[`runtime surface golden fixtures setup openspec × claude+opencode 2`] =
     <rule id="local-artifact-exception" severity="critical">Only write artifacts in <root>/working when the exact path is gitignored AND intentionally local-only; otherwise use <root>/companion.</rule>
     <rule id="guardrail" severity="critical">Bad artifact writes to <root>/working are rejected. Classify correctly first.</rule>
     <rule id="wrapper-only-cli-execution" severity="critical">For every CLI declared in cli-tools, invoke the exact path in its invokeAs attribute. Correct: <wrapper-bin>/openspec status ... . Incorrect: openspec status ... . Do not run bare openspec or graphify commands and do not rely on PATH, aliases, or shell functions. If the exact wrapper path is unavailable, stop and report it.</rule>
-    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: mate artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>
+    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes by archiving them: the archive triggers a nudge directing you to run mate artifact finish "<name>" --json — if no nudge arrives, invoke that command yourself. It is the only sanctioned completion; never hand-commit or hand-tag a finish. Finishing a still-active change archives it and applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>
   </mandatory-rules>
 </companion-policy>"
 ,
@@ -2531,7 +2533,7 @@ exports[`runtime surface golden fixtures setup openspec × claude+opencode 2`] =
     <rule id="local-artifact-exception" severity="critical">Only write artifacts in $MATE_REPO_PATH when the exact path is gitignored AND intentionally local-only; otherwise use $MATE_ARTIFACT_PATH.</rule>
     <rule id="guardrail" severity="critical">Bad artifact writes to $MATE_REPO_PATH are rejected. Classify correctly first.</rule>
     <rule id="wrapper-only-cli-execution" severity="critical">For every CLI declared in cli-tools, invoke the exact path in its invokeAs attribute. Correct: $MATE_WRAPPER_BIN_PATH/openspec status ... . Incorrect: openspec status ... . Do not run bare openspec or graphify commands and do not rely on PATH, aliases, or shell functions. If the exact wrapper path is unavailable, stop and report it.</rule>
-    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: mate artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>
+    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes by archiving them: the archive triggers a nudge directing you to run mate artifact finish "<name>" --json — if no nudge arrives, invoke that command yourself. It is the only sanctioned completion; never hand-commit or hand-tag a finish. Finishing a still-active change archives it and applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>
   </mandatory-rules>
 </companion-policy>"
 ,
@@ -2714,6 +2716,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
         "Skill(context-mode:context-mode)",
         "Skill(graphify)",
         "Skill(mate-artifact-finish)",
+        "Skill(mate-openspec-backfill)",
         "Skill(openspec-apply-change)",
         "Skill(openspec-archive-change)",
         "Skill(openspec-explore)",
@@ -2765,7 +2768,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
       },
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
       "context-mode@1.0.169",
     ],
     "references": {
@@ -2808,7 +2811,7 @@ Write chunks to $GRAPHIFY_OUT and read $GRAPHIFY_OUT later.
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
       "context-mode@1.0.169",
     ],
   },
@@ -2846,7 +2849,7 @@ exports[`runtime surface golden fixtures setup all capabilities × claude+openco
     <rule id="local-artifact-exception" severity="critical">Only write artifacts in <root>/working when the exact path is gitignored AND intentionally local-only; otherwise use <root>/companion.</rule>
     <rule id="guardrail" severity="critical">Bad artifact writes to <root>/working are rejected. Classify correctly first.</rule>
     <rule id="wrapper-only-cli-execution" severity="critical">For every CLI declared in cli-tools, invoke the exact path in its invokeAs attribute. Correct: <wrapper-bin>/openspec status ... . Incorrect: openspec status ... . Do not run bare openspec or graphify commands and do not rely on PATH, aliases, or shell functions. If the exact wrapper path is unavailable, stop and report it.</rule>
-    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: mate artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>
+    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes by archiving them: the archive triggers a nudge directing you to run mate artifact finish "<name>" --json — if no nudge arrives, invoke that command yourself. It is the only sanctioned completion; never hand-commit or hand-tag a finish. Finishing a still-active change archives it and applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>
   </mandatory-rules>
 </companion-policy>
 
@@ -2917,7 +2920,7 @@ exports[`runtime surface golden fixtures setup all capabilities × claude+openco
     <rule id="local-artifact-exception" severity="critical">Only write artifacts in $MATE_REPO_PATH when the exact path is gitignored AND intentionally local-only; otherwise use $MATE_ARTIFACT_PATH.</rule>
     <rule id="guardrail" severity="critical">Bad artifact writes to $MATE_REPO_PATH are rejected. Classify correctly first.</rule>
     <rule id="wrapper-only-cli-execution" severity="critical">For every CLI declared in cli-tools, invoke the exact path in its invokeAs attribute. Correct: $MATE_WRAPPER_BIN_PATH/openspec status ... . Incorrect: openspec status ... . Do not run bare openspec or graphify commands and do not rely on PATH, aliases, or shell functions. If the exact wrapper path is unavailable, stop and report it.</rule>
-    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: mate artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>
+    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes by archiving them: the archive triggers a nudge directing you to run mate artifact finish "<name>" --json — if no nudge arrives, invoke that command yourself. It is the only sanctioned completion; never hand-commit or hand-tag a finish. Finishing a still-active change archives it and applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>
   </mandatory-rules>
 </companion-policy>"
 ,
@@ -3012,7 +3015,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -3027,7 +3030,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }
@@ -3100,7 +3103,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -3115,7 +3118,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }
@@ -3189,7 +3192,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -3204,7 +3207,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }
@@ -3277,7 +3280,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -3292,7 +3295,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }
@@ -3365,7 +3368,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
       "reserved": 15000,
     },
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
     "references": {
       "mate": "..",
@@ -3380,7 +3383,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
   "opencodeTui": {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
-      "@uniqbit/mate-opencode-plugin@0.15.4-canary.10",
+      "@uniqbit/mate-opencode-plugin@0.15.4-canary.11",
     ],
   },
 }

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

@@ -334,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/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";
@@ -200,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

@@ -157,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
@@ -169,6 +185,7 @@ export interface RuntimeContributions {
   guidanceSections?: GuidanceSectionContribution[];
   skillTrees?: SkillTreeContribution[];
   pluginReferences?: PluginReferenceContribution[];
+  agentDefinitions?: AgentDefinitionContribution[];
 }
 
 /**
@@ -197,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/providers/claude.ts

@@ -348,6 +348,7 @@ export async function reconcileClaudeContributions(
 
   if (ctx.scope === "hub") {
     await reconcileClaudeMcpContributions(ctx, inputs);
+    await reconcileClaudeAgentDefinitionContributions(ctx, inputs);
     return;
   }
 
@@ -359,6 +360,7 @@ export async function reconcileClaudeContributions(
   }
 
   await reconcileClaudeMcpContributions(ctx, inputs);
+  await reconcileClaudeAgentDefinitionContributions(ctx, inputs);
 
   for (const input of inputs) {
     // Guidance sections are managed blocks in CLAUDE.md. Current sections are
@@ -404,6 +406,30 @@ async function reconcileClaudeMcpContributions(
   }
 }
 
+/**
+ * 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

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

@@ -428,10 +428,12 @@ export async function reconcileOpenCodeContributions(
 
   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 ?? []) {
@@ -494,6 +496,31 @@ async function reconcileOpenCodeMcpContributions(
   }
 }
 
+/**
+ * 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",