@uniqbit/mate-core 0.18.4 → 1.0.0-canary.0

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

@@ -1,35 +1,28 @@
-import { execFile as execFileCb } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { promisify } from "node:util";
 
-import { getOpenSpecSchemaSelection } from "../../../lib/orchestrator/setup-compatibilities";
+import { Document, isMap, isScalar, isSeq, parseDocument, type YAMLMap, type YAMLSeq } from "yaml";
+
+import {
+  locateOpenSpec,
+  runOpenSpec,
+  type OpenSpecLocation,
+  type RunOpenSpec,
+} from "../../../lib/openspec-cli";
 import { getWrapperBinPath } from "../../../lib/package-paths";
-import { fetchPublicPackageVersion } from "../../../lib/public-npm";
-import { isNewer, isPinnedDeployment } from "../../../lib/update-checker";
 import { FRAMEWORK_NAME } from "../../../framework";
-import { confirm } from "../../../cli/confirm";
-import type { CapabilityPlugin, RuntimeContributionsByRuntime, SetupContext } from "../plugin";
-import type { InstallRequirement } from "../install-contract";
-import {
-  isCommandOnPath,
-  mergeDir,
-  pruneEmptyAncestors,
-  resolveCommandOnPath,
-  runCommand,
-  runCommandSilently,
-} from "../utils";
-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";
-
-const execFileAsync = promisify(execFileCb);
+import { removeRecorded } from "../managed-output";
+import type {
+  CapabilityPlugin,
+  ManagedOutputRecorder,
+  RuntimeContributionsByRuntime,
+  SetupContext,
+} from "../plugin";
+import { mergeDir, pruneEmptyAncestors } from "../utils";
+import { applyMateSkills, MATE_SKILLS, readSkillAuthor, teardownMateSkills } from "../mate";
+import { getSharedSkillsDir, isSharedSkillRootActive } from "../providers/agents-skill-root";
+
+export { MATE_SKILLS } from "../mate";
 
 export const OPENSPEC_SKILLS = [
   "openspec-explore",
@@ -40,11 +33,30 @@ export const OPENSPEC_SKILLS = [
   "openspec-update-change",
 ] as const;
 
+/** Mate skills without a pre-seeded `Skill(...)` permission. */
+const UNPERMITTED_MATE_SKILLS: ReadonlySet<string> = new Set(["mate-create-report"]);
+
 /** 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];
+/** Command ids the OpenSpec CLI writes as `.claude/commands/opsx/<id>.md` and `.opencode/commands/opsx-<id>.md`. */
+const OPENSPEC_COMMAND_IDS = [
+  "explore",
+  "new",
+  "continue",
+  "apply",
+  "update",
+  "ff",
+  "sync",
+  "archive",
+  "bulk-archive",
+  "verify",
+  "onboard",
+  "propose",
+] as const;
+
+/** Skill roots earlier Mate versions let the OpenSpec CLI generate workflow skills into. */
+const GENERATED_SKILL_ROOTS = [".claude", ".agents", ".opencode"] as const;
 
 /** 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;
@@ -56,15 +68,26 @@ const MATE_SCHEMA_SOURCE_ROOT = path.join(
 const MATE_CONVENTIONS_SOURCE = path.join(MATE_SCHEMA_SOURCE_ROOT, "openspec-conventions.yaml");
 
 /**
- * Runtime → OpenSpec CLI tools. OpenCode reads workflow skills from the shared
- * `agents` root; its own tool only contributes the `/opsx-*` commands.
+ * Identifies Mate's own `rules.specs` entry, so a later release can replace its
+ * text instead of adding a second entry.
  */
-const OPENSPEC_TOOLS_BY_RUNTIME = {
-  claude: ["claude"],
-  opencode: ["agents", "opencode"],
-} as const;
+export const MATE_SPECS_RULE_MARKER = "[mate] ";
+
+/**
+ * Delivered through `rules.specs`, the one config hook OpenSpec's archive and
+ * sync workflows read when writing main specs. Propose reads it for delta specs
+ * too, so the text binds main specs only.
+ */
+export const MATE_SPECS_RULE = `${MATE_SPECS_RULE_MARKER}A main spec at openspec/specs/<capability>/spec.md MUST begin with flat frontmatter: type: spec, capability: <capability>, repository: <org/repository> (one scalar), areas: [<area>, ...] (a flat list in the delta's scope order), and tags: [openspec/spec]. Project repository and areas from the delta's paired scopes; never copy scopes, change, or delta tags onto a main spec. Delta specs under openspec/changes/<name>/specs/ keep their \`mate:delta\` comment. Full rules: openspec/mate-conventions.yaml.`;
+
+/** What Mate writes besides its entry; anything beyond the two is user content. */
+const MANAGED_CONFIG_SCHEMA_ONLY = "schema: mate-v1";
+
+/** The schema a fresh `openspec init` writes into config.yaml. */
+const OPENSPEC_INIT_SCHEMA = "spec-driven";
 
-const OPENSPEC_INSTALL_COMMAND = "npm install -g @fission-ai/openspec@latest";
+/** Unfolded output keeps the Mate entry on one line and user scalars unwrapped. */
+const CONFIG_TO_STRING = { lineWidth: 0 } as const;
 
 /**
  * Store metadata `openspec store register` writes beside the companion. Its id
@@ -73,47 +96,10 @@ const OPENSPEC_INSTALL_COMMAND = "npm install -g @fission-ai/openspec@latest";
  */
 const OPENSPEC_GITIGNORE_ENTRIES = [".openspec-store/"];
 
-type OpenSpecTool =
-  (typeof OPENSPEC_TOOLS_BY_RUNTIME)[keyof typeof OPENSPEC_TOOLS_BY_RUNTIME][number];
-type OpenSpecRunCommand = typeof runCommandSilently;
-
 export interface OpenSpecPluginDeps {
-  runCommand?: OpenSpecRunCommand;
-  installCommand?: typeof runCommand;
-  isCommandOnPath?: typeof isCommandOnPath;
-  confirm?: typeof confirm;
-  pathValue?: () => string;
+  runOpenSpec?: RunOpenSpec;
+  locateOpenSpec?: () => OpenSpecLocation;
   wrapperBinPath?: () => string;
-  getInstalledVersion?: (pathValue: string) => Promise<string | undefined>;
-  fetchLatestVersion?: () => Promise<string | undefined>;
-  isPinnedDeployment?: () => boolean;
-}
-
-async function defaultGetInstalledVersion(pathValue: string): Promise<string | undefined> {
-  const bin = resolveCommandOnPath("openspec", pathValue);
-  if (!bin) return undefined;
-
-  try {
-    const { stdout } = await execFileAsync(bin, ["--version"], { timeout: 10_000 });
-    return stdout.match(/\d+\.\d+\.\d+/)?.[0];
-  } catch {
-    return undefined;
-  }
-}
-
-async function defaultFetchLatestVersion(): Promise<string | undefined> {
-  try {
-    return await fetchPublicPackageVersion("@fission-ai/openspec");
-  } catch {
-    return undefined;
-  }
-}
-
-export function deriveOpenSpecTools(activeProviders: string[]): OpenSpecTool[] {
-  const active = new Set(activeProviders);
-  return Object.entries(OPENSPEC_TOOLS_BY_RUNTIME).flatMap(([runtime, tools]) =>
-    active.has(runtime) ? tools : [],
-  );
 }
 
 function getClaudeSkillsDir(companionPath: string): string {
@@ -132,179 +118,241 @@ function getMateConventionsPath(companionPath: string): string {
   return path.join(companionPath, "openspec", "mate-conventions.yaml");
 }
 
-async function teardownClaudeSkillRoot(companionPath: string): Promise<void> {
+async function teardownClaudeSkillRoot(
+  companionPath: string,
+  recorder?: ManagedOutputRecorder,
+): Promise<void> {
   const skillsDir = getClaudeSkillsDir(companionPath);
   for (const skill of OPENSPEC_SKILLS) {
     try {
-      await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
+      await removeRecorded(path.join(skillsDir, skill), "openspec", recorder);
     } catch {
       /* not present */
     }
   }
-  await teardownMateSkills(skillsDir, companionPath);
+  await teardownMateSkills(skillsDir, companionPath, recorder);
   await pruneEmptyAncestors(skillsDir, 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(
+async function teardownSharedSkillRoot(
   companionPath: string,
-  activeProviders: string[],
+  recorder?: ManagedOutputRecorder,
 ): Promise<void> {
-  if (activeProviders.includes("claude")) {
-    await applyMateSkills(getClaudeSkillsDir(companionPath), "claude");
-  }
-  if (isSharedSkillRootActive(activeProviders)) {
-    await applyMateSkills(getSharedSkillsDir(companionPath), "agents");
+  const skillsDir = getSharedSkillsDir(companionPath);
+  await teardownMateSkills(skillsDir, companionPath, recorder);
+  for (const name of [...OPENSPEC_SKILLS, OPENSPEC_AGENTS_MARKER]) {
+    await removeRecorded(path.join(skillsDir, name), "openspec", recorder);
   }
+  await pruneEmptyAncestors(skillsDir, companionPath);
 }
 
-async function reconcileOpenSpecTools(
-  ctx: SetupContext,
-  runCommand: OpenSpecRunCommand,
+/** Converges the earlier layout that deployed Mate skills into `.opencode/skills`. */
+async function removeLegacyOpenCodeCopies(
+  companionPath: string,
+  recorder?: ManagedOutputRecorder,
 ): 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,
-  });
-  await runCommand("openspec", ["update", "--force", ctx.companionPath], {
-    cwd: ctx.companionPath,
-  });
+  await teardownMateSkills(
+    path.join(companionPath, ".opencode", "skills"),
+    companionPath,
+    recorder,
+  );
+}
 
-  await removeLegacyOpenCodeCopies(ctx.companionPath);
-  await applyMateOpenspecSkills(ctx.companionPath, ctx.activeProviders);
+/** The `openspec-*` skills in `skillsDir` OpenSpec wrote: the known names, or `author: openspec`. */
+async function generatedOpenSpecSkills(skillsDir: string): Promise<string[]> {
+  const names = (await fs.readdir(skillsDir).catch(() => [])).filter((name) =>
+    name.startsWith("openspec-"),
+  );
+  const generated = await Promise.all(
+    names.map(async (name) => {
+      const dir = path.join(skillsDir, name);
+      const known = (OPENSPEC_SKILLS as readonly string[]).includes(name);
+      return known || (await readSkillAuthor(dir)) === "openspec" ? [dir] : [];
+    }),
+  );
+  return generated.flat();
 }
 
-async function updateOpenSpecIfOutdated(
-  ctx: SetupContext,
-  deps: Required<
-    Pick<
-      OpenSpecPluginDeps,
-      | "installCommand"
-      | "pathValue"
-      | "getInstalledVersion"
-      | "fetchLatestVersion"
-      | "isPinnedDeployment"
-    >
-  >,
+/** Removes OpenSpec-generated output by name or authorship; user and third-party entries stay. */
+async function removeGeneratedOpenSpecOutput(
+  companionPath: string,
+  recorder?: ManagedOutputRecorder,
 ): Promise<void> {
-  /** Pinned artifacts change tool versions by replacement, never reconciliation. */
-  if (deps.isPinnedDeployment()) return;
+  const skills = await Promise.all(
+    GENERATED_SKILL_ROOTS.map((root) =>
+      generatedOpenSpecSkills(path.join(companionPath, root, "skills")),
+    ),
+  );
+  const targets = [
+    ...skills.flat(),
+    path.join(getSharedSkillsDir(companionPath), OPENSPEC_AGENTS_MARKER),
+    ...OPENSPEC_COMMAND_IDS.flatMap((id) => [
+      path.join(companionPath, ".claude", "commands", "opsx", `${id}.md`),
+      path.join(companionPath, ".opencode", "commands", `opsx-${id}.md`),
+    ]),
+  ];
+  await Promise.all(targets.map((target) => removeRecorded(target, "openspec", recorder)));
+  // Sequential: the parent directories share ancestors.
+  for (const dir of new Set(targets.map((target) => path.dirname(target)))) {
+    // oxlint-disable-next-line no-await-in-loop
+    await pruneEmptyAncestors(dir, companionPath);
+  }
+}
 
-  const installed = await deps.getInstalledVersion(deps.pathValue());
-  if (!installed) return;
+async function applyMateOpenspecSkills(ctx: SetupContext): Promise<void> {
+  if (ctx.activeProviders.includes("claude")) {
+    await applyMateSkills(getClaudeSkillsDir(ctx.companionPath), "claude", ctx.managedOutput);
+  }
+  if (isSharedSkillRootActive(ctx.activeProviders)) {
+    await applyMateSkills(getSharedSkillsDir(ctx.companionPath), "agents", ctx.managedOutput);
+  }
+}
 
-  const latest = await deps.fetchLatestVersion();
-  if (!latest || !isNewer(latest, installed)) return;
+/**
+ * Initializes OpenSpec without tool output, so it writes only its `openspec/`
+ * scaffolding: Mate carries the workflow text in its own skills.
+ */
+async function initializeOpenSpec(ctx: SetupContext, run: RunOpenSpec): Promise<void> {
+  const args = ["init", "--tools", "none", "--force", ctx.companionPath];
+  const result = await run(args, { cwd: ctx.companionPath });
+  if (result.code !== 0) {
+    // A missing bundled CLI answers its reinstall message as stderr.
+    const detail = result.stderr.trim() || result.stdout.trim();
+    throw new Error(`openspec ${args.join(" ")} exited with code ${result.code}: ${detail}`);
+  }
+  await removeGeneratedOpenSpecOutput(ctx.companionPath, ctx.managedOutput);
+}
 
-  process.stdout.write(
-    `openspec: installed version ${installed} is outdated (latest ${latest}). Updating now:\n  ${OPENSPEC_INSTALL_COMMAND}\n`,
+function isMateSpecsRule(item: unknown): boolean {
+  return (
+    isScalar(item) &&
+    typeof item.value === "string" &&
+    item.value.startsWith(MATE_SPECS_RULE_MARKER)
   );
+}
 
-  try {
-    await deps.installCommand("npm", ["install", "-g", "@fission-ai/openspec@latest"], {
-      cwd: ctx.companionPath,
-    });
-  } catch {
-    process.stderr.write("openspec: upgrade failed - continuing with the installed version\n");
-  }
+/** The config's `rules.specs` sequence, `null` when absent, or `undefined` when a shape is foreign. */
+function readSpecsRules(doc: Document): YAMLSeq | null | undefined {
+  if (doc.contents !== null && !isMap(doc.contents)) return undefined;
+  const rules = doc.get("rules", true);
+  if (rules === undefined || rules === null) return null;
+  if (!isMap(rules)) return undefined;
+  const specs = rules.get("specs", true);
+  if (specs === undefined || specs === null) return null;
+  return isSeq(specs) ? specs : undefined;
+}
+
+/**
+ * Removes Mate's `rules.specs` entry and any `rules.specs` list or `rules` map
+ * that leaves empty. Returns whether the document changed.
+ */
+function removeMateSpecsRule(doc: Document): boolean {
+  const specs = readSpecsRules(doc);
+  if (!specs) return false;
+  const before = specs.items.length;
+  specs.items = specs.items.filter((item) => !isMateSpecsRule(item));
+  if (specs.items.length === before) return false;
+  if (specs.items.length === 0) doc.deleteIn(["rules", "specs"]);
+  const rules = doc.get("rules", true);
+  if (isMap(rules) && rules.items.length === 0) doc.delete("rules");
+  return true;
 }
 
-async function ensureOpenSpecInstalled(
-  ctx: SetupContext,
-  deps: Required<
-    Pick<
-      OpenSpecPluginDeps,
-      | "installCommand"
-      | "isCommandOnPath"
-      | "confirm"
-      | "pathValue"
-      | "getInstalledVersion"
-      | "fetchLatestVersion"
-      | "isPinnedDeployment"
-    >
-  >,
-): Promise<boolean> {
-  if (deps.isCommandOnPath("openspec", deps.pathValue())) {
-    await updateOpenSpecIfOutdated(ctx, deps);
+/**
+ * Ensures exactly one current Mate entry in `rules.specs`: appended when
+ * missing, replaced in place when outdated. Returns whether the document changed.
+ */
+function upsertMateSpecsRule(doc: Document): boolean {
+  if (doc.contents === null) doc.contents = doc.createNode({}) as YAMLMap;
+  const specs = readSpecsRules(doc);
+  if (specs === null) {
+    doc.setIn(["rules", "specs"], doc.createNode([MATE_SPECS_RULE]));
     return true;
   }
+  if (!specs) return false;
 
-  if (ctx.mode !== "setup") {
-    process.stderr.write(
-      `openspec binary not found. Install it manually with \`${OPENSPEC_INSTALL_COMMAND}\`\n`,
-    );
-    return false;
+  const index = specs.items.findIndex(isMateSpecsRule);
+  if (index === -1) {
+    specs.add(doc.createNode(MATE_SPECS_RULE));
+    return true;
   }
-
-  if (!deps.isCommandOnPath("npm", deps.pathValue())) {
-    process.stderr.write(
-      `openspec binary not found and npm is not available on PATH. Install it manually with \`${OPENSPEC_INSTALL_COMMAND}\`\n`,
-    );
-    return false;
+  let changed = false;
+  const current = specs.items[index];
+  if (isScalar(current) && current.value !== MATE_SPECS_RULE) {
+    current.value = MATE_SPECS_RULE;
+    changed = true;
   }
-
-  process.stdout.write(`openspec binary not found. To install:\n  ${OPENSPEC_INSTALL_COMMAND}\n`);
-  const ok = await deps.confirm("Run this install command now?");
-  if (!ok) {
-    process.stderr.write(
-      `openspec: install skipped - install manually with \`${OPENSPEC_INSTALL_COMMAND}\`\n`,
-    );
-    return false;
+  const deduplicated = specs.items.filter((item, i) => i === index || !isMateSpecsRule(item));
+  if (deduplicated.length !== specs.items.length) {
+    specs.items = deduplicated;
+    changed = true;
   }
+  return changed;
+}
 
+/**
+ * Removes Mate's own config content: its `rules.specs` entry always, and the
+ * file only when what remains is exactly what Mate writes. User content stays.
+ */
+async function removeManagedOpenSpecConfig(companionPath: string): Promise<void> {
+  const configPath = getOpenSpecConfigPath(companionPath);
+  let content: string;
   try {
-    await deps.installCommand("npm", ["install", "-g", "@fission-ai/openspec@latest"], {
-      cwd: ctx.companionPath,
-    });
+    content = await fs.readFile(configPath, "utf8");
   } catch {
-    process.stderr.write(
-      `openspec: install failed - install manually with \`${OPENSPEC_INSTALL_COMMAND}\`\n`,
-    );
-    return false;
+    return;
   }
 
-  if (!deps.isCommandOnPath("openspec", deps.pathValue())) {
-    process.stderr.write(
-      "openspec install completed but the binary is still not available on PATH\n",
-    );
-    return false;
+  let remaining = content;
+  if (content.trim() !== MANAGED_CONFIG_SCHEMA_ONLY) {
+    const doc = parseDocument(content);
+    if (doc.errors.length > 0 || !removeMateSpecsRule(doc)) return;
+    remaining = doc.toString(CONFIG_TO_STRING);
   }
 
-  return true;
+  if (remaining.trim() === MANAGED_CONFIG_SCHEMA_ONLY) {
+    await fs.rm(configPath, { force: true });
+    await pruneEmptyAncestors(path.dirname(configPath), companionPath);
+  } else {
+    await fs.writeFile(configPath, remaining, "utf8");
+  }
 }
 
-/** Only the config Mate itself wrote is removed; a user-edited config.yaml is left alone. */
-async function removeManagedOpenSpecConfig(companionPath: string): Promise<void> {
+/** Writes a fresh Mate config, or merges Mate's entry into an existing one; writes only on change. */
+async function ensureManagedOpenSpecConfig(companionPath: string): Promise<void> {
   const configPath = getOpenSpecConfigPath(companionPath);
+  let content: string | undefined;
   try {
-    const content = await fs.readFile(configPath, "utf8");
-    if (content.trim() === "schema: mate-v1") {
-      await fs.rm(configPath, { force: true });
-      await pruneEmptyAncestors(path.dirname(configPath), companionPath);
-    }
+    content = await fs.readFile(configPath, "utf8");
   } catch {
-    /* no managed config present */
+    /* no config yet */
   }
+
+  if (content === undefined) {
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    const fresh = new Document({ schema: "mate-v1", rules: { specs: [MATE_SPECS_RULE] } });
+    await fs.writeFile(configPath, fresh.toString(CONFIG_TO_STRING), "utf8");
+    return;
+  }
+
+  // config.yaml is user-editable once created; only Mate's entry and a default `schema` are touched.
+  const doc = parseDocument(content);
+  if (doc.errors.length > 0) {
+    process.stderr.write(
+      `openspec: left openspec/config.yaml unchanged, it is not valid YAML: ${doc.errors[0].message.split("\n")[0]}\n`,
+    );
+    return;
+  }
+  const ruleChanged = upsertMateSpecsRule(doc);
+  // Mate's `mate-v1` replaces a missing schema or the one `openspec init` writes; any other is a user choice.
+  const current = isMap(doc.contents) ? doc.get("schema") : undefined;
+  const schemaChanged =
+    isMap(doc.contents) &&
+    (current === undefined || current === null || current === OPENSPEC_INIT_SCHEMA);
+  if (schemaChanged) doc.set("schema", "mate-v1");
+  if (!schemaChanged && !ruleChanged) return;
+  const merged = doc.toString(CONFIG_TO_STRING);
+  if (merged !== content) await fs.writeFile(configPath, merged, "utf8");
 }
 
 async function teardownOpenSpecSchema(companionPath: string): Promise<void> {
@@ -333,37 +381,14 @@ async function reconcileOpenSpecSchema(ctx: SetupContext): Promise<void> {
   );
   await fs.copyFile(MATE_CONVENTIONS_SOURCE, getMateConventionsPath(ctx.companionPath));
 
-  // Availability is unconditional so any change may select a Mate schema;
-  // activation stays opt-in through the companion-level setup selection.
-  if (getOpenSpecSchemaSelection(ctx.config.capabilities ?? []) !== "mate-v1") {
-    await removeManagedOpenSpecConfig(ctx.companionPath);
-    return;
-  }
-
-  const configPath = getOpenSpecConfigPath(ctx.companionPath);
-  await fs.mkdir(path.dirname(configPath), { recursive: true });
-
-  // config.yaml is user-editable once created; never overwrite it on re-sync.
-  const configExists = await fs
-    .access(configPath)
-    .then(() => true)
-    .catch(() => false);
-  if (configExists) return;
-
-  await fs.writeFile(configPath, "schema: mate-v1\n", "utf8");
+  await ensureManagedOpenSpecConfig(ctx.companionPath);
 }
 
 export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityPlugin {
   const depsWithDefaults = {
-    runCommand: deps.runCommand ?? runCommandSilently,
-    installCommand: deps.installCommand ?? runCommand,
-    isCommandOnPath: deps.isCommandOnPath ?? isCommandOnPath,
-    confirm: deps.confirm ?? confirm,
-    pathValue: deps.pathValue ?? (() => process.env.PATH ?? ""),
+    runOpenSpec: deps.runOpenSpec ?? runOpenSpec,
+    locateOpenSpec: deps.locateOpenSpec ?? locateOpenSpec,
     wrapperBinPath: deps.wrapperBinPath ?? getWrapperBinPath,
-    getInstalledVersion: deps.getInstalledVersion ?? defaultGetInstalledVersion,
-    fetchLatestVersion: deps.fetchLatestVersion ?? defaultFetchLatestVersion,
-    isPinnedDeployment: deps.isPinnedDeployment ?? (() => isPinnedDeployment()),
   };
 
   return {
@@ -381,19 +406,9 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
       return {
         claude: {
           permissionEntries: [
-            "Skill(openspec-explore)",
-            "Skill(openspec-propose)",
-            "Skill(openspec-apply-change)",
-            "Skill(openspec-archive-change)",
-            "Skill(mate-artifact-publish)",
-            "Skill(mate-openspec-backfill)",
-            "Skill(mate-interview-me)",
-            "Skill(mate-grill-me)",
-            "Skill(mate-grilling)",
-            "Skill(mate-grill-with-docs)",
-            "Skill(mate-domain-modeling)",
-            "Skill(mate-show-me)",
-            "Skill(mate-simplify-code)",
+            ...MATE_SKILLS.filter((skill) => !UNPERMITTED_MATE_SKILLS.has(skill)).map(
+              (skill) => `Skill(${skill})`,
+            ),
             "Bash(openspec:*)",
             `Bash(${FRAMEWORK_NAME} cap graphify:*)`,
             `Bash(${path.join(depsWithDefaults.wrapperBinPath(), "openspec")}:*)`,
@@ -403,54 +418,42 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
     },
     gitignoreEntries: () => OPENSPEC_GITIGNORE_ENTRIES,
     persistGitignoreEntries: true,
-    getInstallRequirements: (): InstallRequirement[] => [
-      {
-        id: "capability:openspec",
-        label: "OpenSpec CLI",
-        group: "companion",
-        source: "OpenSpec capability",
-        command: OPENSPEC_INSTALL_COMMAND,
-        fingerprint: `openspec:${OPENSPEC_INSTALL_COMMAND}`,
-        detect: () => depsWithDefaults.isCommandOnPath("openspec", depsWithDefaults.pathValue()),
-        install: () =>
-          depsWithDefaults.installCommand("npm", ["install", "-g", "@fission-ai/openspec@latest"]),
-        verify: () => depsWithDefaults.isCommandOnPath("openspec", depsWithDefaults.pathValue()),
-      },
-    ],
     async apply(ctx) {
-      const tools = deriveOpenSpecTools(ctx.activeProviders);
-      if (ctx.mode === "setup" || tools.length > 0) {
-        if (await ensureOpenSpecInstalled(ctx, depsWithDefaults)) {
-          if (tools.length > 0) {
-            await reconcileOpenSpecTools(ctx, depsWithDefaults.runCommand);
-          }
-        }
+      // OpenSpec output is committed in the companion, so only setup and
+      // `mate companion update` touch it; a launch must leave it alone.
+      if (ctx.mode === "setup" || ctx.regenerateOpenSpec === true) {
+        await initializeOpenSpec(ctx, depsWithDefaults.runOpenSpec);
+      } else {
+        const location = depsWithDefaults.locateOpenSpec();
+        if ("missing" in location) process.stderr.write(`openspec: ${location.missing}\n`);
       }
-      await removeLegacyOpenCodeCopies(ctx.companionPath);
+      await applyMateOpenspecSkills(ctx);
+      await removeLegacyOpenCodeCopies(ctx.companionPath, ctx.managedOutput);
       await reconcileOpenSpecSchema(ctx);
     },
     async teardown(ctx) {
-      await teardownClaudeSkillRoot(ctx.companionPath);
-      await teardownSharedSkillRoot(ctx.companionPath);
-      await removeLegacyOpenCodeCopies(ctx.companionPath);
+      await teardownClaudeSkillRoot(ctx.companionPath, ctx.managedOutput);
+      await teardownSharedSkillRoot(ctx.companionPath, ctx.managedOutput);
+      await removeLegacyOpenCodeCopies(ctx.companionPath, ctx.managedOutput);
+      await removeGeneratedOpenSpecOutput(ctx.companionPath, ctx.managedOutput);
       await teardownOpenSpecSchema(ctx.companionPath);
     },
     forProvider: {
       claude: {
-        // Publication is explicit (`mate-artifact-publish`), so openspec
+        // Publication is explicit (`mate-publish-artifact`), so openspec
         // contributes no archive-triggered Claude hook and no hook state.
         async apply() {},
         async teardown(ctx: SetupContext) {
-          await teardownClaudeSkillRoot(ctx.companionPath);
+          await teardownClaudeSkillRoot(ctx.companionPath, ctx.managedOutput);
         },
       },
       opencode: {
         async apply() {},
         async teardown(ctx: SetupContext) {
           if (!isSharedSkillRootActive(ctx.activeProviders)) {
-            await teardownSharedSkillRoot(ctx.companionPath);
+            await teardownSharedSkillRoot(ctx.companionPath, ctx.managedOutput);
           }
-          await removeLegacyOpenCodeCopies(ctx.companionPath);
+          await removeLegacyOpenCodeCopies(ctx.companionPath, ctx.managedOutput);
         },
       },
     },