@yugabytedb/meko-mcp 2.0.0 → 2.2.0

package/lib/clients/kiro.mjs

@@ -0,0 +1,705 @@
+import {
+  existsSync,
+  lstatSync,
+  readlinkSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  rmSync,
+  chmodSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+import {
+  getKiroMcpPath,
+  getKiroSkillsDir,
+  getKiroSteeringPath,
+  getKiroHooksDir,
+  getKiroManagedAgentPath,
+  getKiroCliSettingsPath,
+  readJsonFile,
+  writeJsonFile,
+} from "../config.mjs";
+import {
+  MEKO_MCP_USER_AGENT,
+  getInstallerVersion,
+  installStableTree,
+  isDanglingSymlink,
+  isPackagedInstall,
+  markerIsStale,
+  readInstallerMarker,
+  resolveHooksRoot,
+  resolveSkillSource,
+  removePath,
+  symlinkOrCopy,
+  writeInstallerMarker,
+} from "./common.mjs";
+
+const SKILLS = [{ name: "meko-mcp-tools" }];
+const MANAGED_AGENT_NAME = "meko-default";
+const MANAGED_MARKER = "Managed by meko installer";
+const STANDALONE_HOOKS = [
+  { file: "meko-session-start.json", trigger: "SessionStart", event: "SessionStart", timeout: 15 },
+  { file: "meko-user-prompt-submit.json", trigger: "UserPromptSubmit", event: "UserPromptSubmit", timeout: 5 },
+  { file: "meko-stop.json", trigger: "Stop", event: "Stop", timeout: 2 },
+];
+
+/**
+ * Adapter for Kiro (AWS) — covers both the Kiro IDE and `kiro-cli`, which read
+ * the same `mcpServers` config files and the same skills directories.
+ *
+ * Kiro accepts the remote `{ url, headers }` MCP shape natively, so — unlike
+ * Claude Desktop — Meko registers the endpoint directly with an
+ * `Authorization: Bearer` header. That matters for more than tidiness: routing
+ * Kiro through the `mcp-remote` stdio bridge never presents the API key at all
+ * (the bridge forwards only headers passed explicitly via `--header`), so it
+ * connects unauthenticated, takes a 401, and falls through to OAuth dynamic
+ * client registration. Both the IDE and `kiro-cli` then die on an opaque HTML
+ * 403: each registers a loopback callback, and the Cloud WAF's SSRF ruleset
+ * refuses internal hosts (localhost, 127.0.0.1, RFC1918, link-local) in a
+ * redirect_uri regardless of scheme. Header auth sidesteps OAuth entirely.
+ *
+ * Kiro 2.18.1 contains two hook generations. CLI 2.x reads lowercase inline
+ * hooks from the selected custom agent; CLI 3.x and IDE 1.x read standalone
+ * PascalCase hook files. The installer writes both and routes them through one
+ * durable event journal. Duplicate delivery is expected; when one format omits
+ * `session_id`, the handler correlates it with the other format by host PID and
+ * cwd before deduplicating the turn and starting Capture v2.
+ *
+ * Steering remains as a safety net. The handler injects a
+ * MEKO_CAPTURE_SESSION_STARTED marker when hooks run; without that marker the
+ * user may be in an untrusted IDE workspace, have hooks disabled, or have
+ * selected a different CLI 2.x agent. In those cases steering asks the agent to
+ * use proactive memory writes instead of assuming capture is active.
+ *
+ * @returns {object}
+ */
+export function createKiroAdapter(customPaths = {}) {
+  const resolveHooksRootPath = customPaths.resolveHooksRoot ?? resolveHooksRoot;
+  const resolveSkillSourcePath = customPaths.resolveSkillSource ?? resolveSkillSource;
+  const packagedInstallDetector = customPaths.isPackagedInstall ?? isPackagedInstall;
+  const platform = customPaths.platform ?? process.platform;
+  const paths = {
+    getMcpPath: customPaths.getMcpPath ?? getKiroMcpPath,
+    getSkillsDir: customPaths.getSkillsDir ?? getKiroSkillsDir,
+    getSteeringPath: customPaths.getSteeringPath ?? getKiroSteeringPath,
+    getHooksDir: customPaths.getHooksDir ?? getKiroHooksDir,
+    getManagedAgentPath:
+      customPaths.getManagedAgentPath ?? getKiroManagedAgentPath,
+    getCliSettingsPath:
+      customPaths.getCliSettingsPath ?? getKiroCliSettingsPath,
+  };
+
+  return {
+    id: "kiro",
+    displayName: "Kiro",
+    settingsPath() {
+      return "";
+    },
+    async detectPrerequisites() {
+      // Config-mode install: nothing is shelled out to, so there is no CLI to
+      // probe. Kiro reads mcp.json on save/launch.
+    },
+    /**
+     * Is Kiro actually installed? Both the IDE and `kiro-cli` create the global
+     * config tree on first run, so its existence means Kiro has run at least
+     * once here. $KIRO_HOME is honored because Kiro resolves every global
+     * surface against it. A user who installed Kiro but never opened it is a
+     * false negative — acceptable; they'd pass --client kiro explicitly.
+     */
+    isInstalled() {
+      return existsSync(process.env.KIRO_HOME || join(homedir(), ".kiro"));
+    },
+    detectExisting(name, { scope, projectRoot }) {
+      const path = paths.getMcpPath(scope, projectRoot);
+      const cfg = readJsonFile(path);
+      const entry = cfg?.mcpServers?.[name];
+      const found = Boolean(entry);
+      return {
+        found,
+        status: found ? "Configured" : "",
+        ...(typeof entry?.url === "string" ? { url: entry.url } : {}),
+      };
+    },
+    removeRegistration(name, { scope, projectRoot }) {
+      const mcpPath = paths.getMcpPath(scope, projectRoot);
+      const cfg = readJsonFile(mcpPath);
+      if (!cfg?.mcpServers?.[name]) return;
+      delete cfg.mcpServers[name];
+      writePrivateKiroConfig(mcpPath, cfg);
+    },
+    registerServer({ name, url, apiKey, dryRun, log, scope, projectRoot }) {
+      const mcpPath = paths.getMcpPath(scope, projectRoot);
+      if (dryRun) {
+        log.dim(`  Would update ${mcpPath}:`);
+        log.dim(`    mcpServers.${name}.url = ${url}`);
+        log.dim(`    mcpServers.${name}.headers.User-Agent = ${MEKO_MCP_USER_AGENT}`);
+        if (apiKey) {
+          log.dim("    mcpServers.<name>.headers.Authorization = <set>");
+        }
+        return;
+      }
+
+      const cfg = readJsonFile(mcpPath);
+      if (!cfg.mcpServers || typeof cfg.mcpServers !== "object") {
+        cfg.mcpServers = {};
+      }
+      const server = { url, headers: { "User-Agent": MEKO_MCP_USER_AGENT } };
+      if (apiKey) {
+        server.headers.Authorization = `Bearer ${apiKey}`;
+      }
+      cfg.mcpServers[name] = server;
+      writePrivateKiroConfig(mcpPath, cfg);
+    },
+    setHookEnvironment({ url, apiKey, name = "meko", dryRun, log, scope, projectRoot }) {
+      const handlersRoot = getKiroHooksInstallRoot(paths, scope, projectRoot);
+      const hooksDir = paths.getHooksDir(scope, projectRoot);
+      const agentPath = paths.getManagedAgentPath(scope, projectRoot);
+      const cliSettingsPath = paths.getCliSettingsPath(scope, projectRoot);
+      if (dryRun) {
+        log.dim(`  Would install Kiro capture assets into ${handlersRoot}`);
+        log.dim(`  Would write standalone SessionStart/UserPromptSubmit/Stop hooks into ${hooksDir}`);
+        log.dim(`  Would write managed CLI 2.x agent ${agentPath}`);
+        log.dim(`  Would activate ${MANAGED_AGENT_NAME} in ${cliSettingsPath}`);
+        log.dim("  Would write hook environment with MEKO_MCP_URL and redacted credentials (mode 0600)");
+        return;
+      }
+
+      const priorInstallState = readJsonFile(join(handlersRoot, "kiro-install-state.json"));
+      if (existsSync(handlersRoot) && !readInstallerMarker(handlersRoot)) {
+        log.dim(`  Skipping Kiro capture install: ${handlersRoot} is user-managed.`);
+        return;
+      }
+      installStableTree(resolveHooksRootPath(), handlersRoot);
+      writeInstallerMarker(handlersRoot);
+      writeKiroHookEnvironment(handlersRoot, { url, apiKey });
+      if (isKiroInstallState(priorInstallState)) {
+        // installStableTree replaces the runtime directory. Preserve the only
+        // copy of the original default even if an edited managed-agent file is
+        // now treated as a user-owned collision and cannot be reactivated.
+        writePrivateJson(join(handlersRoot, "kiro-install-state.json"), priorInstallState);
+      }
+      installStandaloneKiroHooks({ hooksDir, handlersRoot, log, platform });
+      const agentInstalled = installManagedKiroAgent({
+        agentPath,
+        handlersRoot,
+        log,
+        name,
+        platform,
+      });
+      if (agentInstalled) {
+        activateManagedKiroAgent({
+          cliSettingsPath,
+          handlersRoot,
+          priorInstallState,
+        });
+      }
+    },
+    installSkills({ dryRun, log, scope, projectRoot, name }) {
+      const skillDir = paths.getSkillsDir(scope, projectRoot);
+      const steeringPath = paths.getSteeringPath(scope, projectRoot);
+      const currentVersion = getInstallerVersion();
+      if (dryRun) {
+        log.dim(`  Would install skills into ${skillDir}`);
+        log.dim(`  Would write .meko-installer marker (version=${currentVersion})`);
+        log.dim(`  Would write steering file ${steeringPath}`);
+        return { marketplace: "skipped", skills: "dry-run" };
+      }
+
+      mkdirSync(skillDir, { recursive: true });
+      for (const skill of SKILLS) {
+        const source = resolveSkillSourcePath(skill.name);
+        const destination = join(skillDir, skill.name);
+
+        if (existsSync(destination)) {
+          // A symlink into our own source tree is already live content.
+          if (isOwnSymlink(destination, source)) continue;
+
+          const marker = readInstallerMarker(destination);
+          if (!marker) {
+            // Not ours: a user-authored skill or a pre-marker install. Leave it
+            // rather than clobber local edits.
+            log.dim(
+              `  Skipping ${destination}: no .meko-installer marker (user-managed).`,
+            );
+            continue;
+          }
+          if (markerIsStale(destination, currentVersion)) {
+            const from = marker.version ?? "pre-1.0.9";
+            log.dim(`  Upgrading kiro skill from ${from} -> ${currentVersion}`);
+            removePath(destination);
+          } else {
+            continue;
+          }
+        } else if (isDanglingSymlink(destination)) {
+          // Left by an earlier install whose target (e.g. a deleted worktree)
+          // is gone. existsSync is false for these, so the branch above misses
+          // them; clear it so the fresh-install path can replace it.
+          log.dim?.(
+            `  Replacing dangling symlink at ${destination} (target missing).`,
+          );
+          removePath(destination);
+        }
+
+        const strategy = symlinkOrCopy(source, destination, {
+          preferCopy: packagedInstallDetector(),
+        });
+        // Only stamp a marker on a real copy — writing into a symlinked source
+        // would mutate the shipped asset tree.
+        if (strategy === "copy") {
+          writeInstallerMarker(destination);
+        }
+      }
+
+      // Counterweight to the skill's hooks-assume-capture doctrine. Written
+      // last so a skill-copy failure doesn't leave steering claiming a skill
+      // that isn't there.
+      const existingSteering = existsSync(steeringPath)
+        ? readFileSync(steeringPath, "utf8")
+        : "";
+      if (existingSteering && !existingSteering.includes(MANAGED_MARKER)) {
+        log.dim(`  Skipping ${steeringPath}: user-managed steering collision.`);
+      } else {
+        mkdirSync(dirname(steeringPath), { recursive: true });
+        writeFileSync(
+          steeringPath,
+          renderSteeringDoc(currentVersion, name ?? "meko"),
+          "utf8",
+        );
+      }
+
+      return { marketplace: "skipped", skills: "ok" };
+    },
+    uninstall({ name, scope, projectRoot }) {
+      const results = [];
+      try {
+        this.removeRegistration(name, { scope, projectRoot });
+        results.push({
+          key: "mcp",
+          ok: true,
+          message: `Kiro MCP server "${name}" removed.`,
+        });
+      } catch (err) {
+        results.push({
+          key: "mcp",
+          ok: false,
+          message: `Could not remove Kiro MCP server: ${err.message}`,
+        });
+      }
+
+      try {
+        uninstallKiroCapture({ scope, projectRoot, paths, resolveHooksRootPath });
+        results.push({
+          key: "hooks",
+          ok: true,
+          message: "Kiro hook configuration and managed agent cleaned up.",
+        });
+      } catch (err) {
+        results.push({
+          key: "hooks",
+          ok: false,
+          message: `Could not clean Kiro hooks: ${err.message}`,
+        });
+      }
+
+      try {
+        uninstallKiroSkills({ scope, projectRoot, paths, resolveSkillSourcePath });
+        results.push({ key: "skills", ok: true, message: "Kiro skills cleaned up." });
+      } catch (err) {
+        results.push({
+          key: "skills",
+          ok: false,
+          message: `Could not remove Kiro skills: ${err.message}`,
+        });
+      }
+
+      try {
+        removeKiroSteering(paths.getSteeringPath(scope, projectRoot));
+        results.push({
+          key: "steering",
+          ok: true,
+          message: "Kiro steering file cleaned up.",
+        });
+      } catch (err) {
+        results.push({
+          key: "steering",
+          ok: false,
+          message: `Could not remove Kiro steering file: ${err.message}`,
+        });
+      }
+
+      return results;
+    },
+    async validateConfig({ serverName, scope, projectRoot }) {
+      const mcpPath = paths.getMcpPath(scope, projectRoot);
+      const cfg = readJsonFile(mcpPath);
+      const entry = cfg?.mcpServers?.[serverName];
+      if (!entry) {
+        return { ok: false, message: `Server "${serverName}" not found in ${mcpPath}.` };
+      }
+      const hasUserAgent = Object.keys(entry.headers ?? {}).some(
+        (key) => key.toLowerCase() === "user-agent",
+      );
+      if (!hasUserAgent) {
+        return {
+          ok: false,
+          message: `Server "${serverName}" in ${mcpPath} is missing the User-Agent header required by the Cloud WAF.`,
+        };
+      }
+      return { ok: true, message: `Server "${serverName}" is registered in ${mcpPath}.` };
+    },
+  };
+}
+
+function shellQuote(value, platform = process.platform) {
+  if (platform === "win32") {
+    return `"${String(value).replace(/"/g, '\\"')}"`;
+  }
+  return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
+function getKiroHooksInstallRoot(paths, scope, projectRoot) {
+  return join(paths.getHooksDir(scope, projectRoot), "meko-hooks", "hooks-handlers");
+}
+
+function buildKiroHookCommand(handlersRoot, event, platform) {
+  return `node ${shellQuote(join(handlersRoot, "lib", "kiro-handler.js"), platform)} ${shellQuote(event, platform)}`;
+}
+
+function writePrivateJson(filePath, value) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  chmodSync(filePath, 0o600);
+}
+
+function writePrivateKiroConfig(filePath, value) {
+  writeJsonFile(filePath, value);
+  chmodSync(filePath, 0o600);
+}
+
+function writeKiroHookEnvironment(handlersRoot, { url, apiKey }) {
+  writePrivateJson(join(handlersRoot, "kiro-hook-env.json"), {
+    MEKO_MCP_URL: url,
+    MEKO_API_KEY: apiKey || "",
+    MEKO_HOOK_CLIENT: "kiro",
+  });
+}
+
+function isManagedHookFile(filePath) {
+  const cfg = readJsonFile(filePath);
+  return Boolean(
+    Array.isArray(cfg?.hooks) &&
+      cfg.hooks.some(
+        (hook) =>
+          typeof hook?.description === "string" &&
+          hook.description.includes(MANAGED_MARKER) &&
+          hook?.action?.command?.includes("kiro-handler.js"),
+      ),
+  );
+}
+
+function installStandaloneKiroHooks({ hooksDir, handlersRoot, log, platform }) {
+  mkdirSync(hooksDir, { recursive: true });
+  for (const hook of STANDALONE_HOOKS) {
+    const filePath = join(hooksDir, hook.file);
+    if (existsSync(filePath) && !isManagedHookFile(filePath)) {
+      log.dim(`  Skipping ${filePath}: user-managed hook collision.`);
+      continue;
+    }
+    writeJsonFile(filePath, {
+      version: "v1",
+      hooks: [
+        {
+          name: `Meko ${hook.trigger}`,
+          description: `${MANAGED_MARKER}; durable Meko Capture v2 lifecycle hook.`,
+          enabled: true,
+          trigger: hook.trigger,
+          action: {
+            type: "command",
+            command: buildKiroHookCommand(handlersRoot, hook.event, platform),
+          },
+          timeout: hook.timeout,
+        },
+      ],
+    });
+  }
+}
+
+function isManagedAgentFile(agentPath) {
+  const cfg = readJsonFile(agentPath);
+  return Boolean(
+    cfg?.name === MANAGED_AGENT_NAME &&
+      typeof cfg?.description === "string" &&
+      cfg.description.includes(MANAGED_MARKER),
+  );
+}
+
+function installManagedKiroAgent({ agentPath, handlersRoot, log, name, platform }) {
+  if (existsSync(agentPath) && !isManagedAgentFile(agentPath)) {
+    log.dim(`  Skipping ${agentPath}: user-managed agent collision.`);
+    return false;
+  }
+  writeJsonFile(agentPath, {
+    name: MANAGED_AGENT_NAME,
+    description: `Default-like Kiro CLI 2.x agent with durable Meko capture. ${MANAGED_MARKER}.`,
+    prompt: null,
+    mcpServers: {},
+    tools: [
+      `@${name}`,
+      "read",
+      "write",
+      "shell",
+      "aws",
+      "report",
+      "introspect",
+      "knowledge",
+      "thinking",
+      "todo",
+      "delegate",
+      "grep",
+      "glob",
+    ],
+    toolAliases: {},
+    allowedTools: [],
+    resources: [],
+    toolsSettings: {},
+    includeMcpJson: true,
+    model: null,
+    hooks: {
+      agentSpawn: [{
+        command: buildKiroHookCommand(handlersRoot, "agentSpawn", platform),
+      }],
+      userPromptSubmit: [{
+        command: buildKiroHookCommand(handlersRoot, "userPromptSubmit", platform),
+      }],
+      stop: [{
+        command: buildKiroHookCommand(handlersRoot, "stop", platform),
+      }],
+    },
+  });
+  return true;
+}
+
+function isKiroInstallState(value) {
+  return Boolean(
+    value?.schema_version === 1 && value?.managed_agent === MANAGED_AGENT_NAME,
+  );
+}
+
+function activateManagedKiroAgent({
+  cliSettingsPath,
+  handlersRoot,
+  priorInstallState,
+}) {
+  const cfg = readJsonFile(cliSettingsPath);
+  const hasDefault = Object.prototype.hasOwnProperty.call(cfg, "chat.defaultAgent");
+  const currentDefault = cfg["chat.defaultAgent"];
+  let state;
+  if (isKiroInstallState(priorInstallState)) {
+    state = priorInstallState;
+  } else {
+    state = {
+      schema_version: 1,
+      managed_agent: MANAGED_AGENT_NAME,
+      had_previous_default: hasDefault && currentDefault !== MANAGED_AGENT_NAME,
+      previous_default:
+        hasDefault && currentDefault !== MANAGED_AGENT_NAME ? currentDefault : null,
+    };
+  }
+  cfg["chat.defaultAgent"] = MANAGED_AGENT_NAME;
+  writeJsonFile(cliSettingsPath, cfg);
+  writePrivateJson(join(handlersRoot, "kiro-install-state.json"), state);
+}
+
+function restoreKiroDefaultAgent(cliSettingsPath, state) {
+  if (!state || state.managed_agent !== MANAGED_AGENT_NAME) return;
+  const cfg = readJsonFile(cliSettingsPath);
+  if (cfg["chat.defaultAgent"] !== MANAGED_AGENT_NAME) return;
+  if (state.had_previous_default) {
+    cfg["chat.defaultAgent"] = state.previous_default;
+  } else {
+    delete cfg["chat.defaultAgent"];
+  }
+  writeJsonFile(cliSettingsPath, cfg);
+}
+
+function configReferencesKiroRuntime(filePath, handlersRoot) {
+  if (!existsSync(filePath)) return false;
+  try {
+    const handlerPath = join(handlersRoot, "lib", "kiro-handler.js");
+    const cfg = readJsonFile(filePath);
+    const commands = Array.isArray(cfg?.hooks)
+      ? cfg.hooks.map((hook) => hook?.action?.command)
+      : Object.values(cfg?.hooks ?? {}).flatMap((hooks) =>
+          (Array.isArray(hooks) ? hooks : [hooks]).map((hook) => hook?.command),
+        );
+    return commands.some(
+      (command) => typeof command === "string" && command.includes(handlerPath),
+    );
+  } catch {
+    return false;
+  }
+}
+
+function uninstallKiroCapture({ scope, projectRoot, paths }) {
+  const hooksDir = paths.getHooksDir(scope, projectRoot);
+  const handlersRoot = getKiroHooksInstallRoot(paths, scope, projectRoot);
+  const runtimeOwned = Boolean(readInstallerMarker(handlersRoot));
+  const state = readJsonFile(join(handlersRoot, "kiro-install-state.json"));
+  restoreKiroDefaultAgent(paths.getCliSettingsPath(scope, projectRoot), state);
+
+  for (const hook of STANDALONE_HOOKS) {
+    const filePath = join(hooksDir, hook.file);
+    if (existsSync(filePath) && isManagedHookFile(filePath)) {
+      rmSync(filePath, { force: true });
+    }
+  }
+
+  const agentPath = paths.getManagedAgentPath(scope, projectRoot);
+  if (existsSync(agentPath) && isManagedAgentFile(agentPath)) {
+    rmSync(agentPath, { force: true });
+  }
+
+  const remainingHookDependsOnRuntime = STANDALONE_HOOKS.some((hook) =>
+    configReferencesKiroRuntime(join(hooksDir, hook.file), handlersRoot),
+  );
+  const remainingAgentDependsOnRuntime = configReferencesKiroRuntime(
+    agentPath,
+    handlersRoot,
+  );
+
+  // The runtime may survive when a user-edited hook or agent still points at
+  // it, but installer credentials must not. Remove the private environment
+  // file independently before deciding whether the handler tree is retained.
+  if (runtimeOwned) {
+    rmSync(join(handlersRoot, "kiro-hook-env.json"), { force: true });
+  }
+
+  // Preserve a still-referenced runtime when the user edited an installer hook
+  // or agent enough to take ownership of it. Otherwise uninstall would leave a
+  // surviving Kiro command pointing at a deleted handler. The event journal and
+  // Capture v2 watermark/outbox live elsewhere and are always retained.
+  if (
+    runtimeOwned &&
+    !remainingHookDependsOnRuntime &&
+    !remainingAgentDependsOnRuntime
+  ) {
+    removePath(handlersRoot);
+  }
+}
+
+/**
+ * Steering text Kiro loads on every interaction.
+ *
+ * This makes the skill's capture assumption conditional. Kiro normally has
+ * hooks, but workspace trust, disabled hooks, or a different selected CLI 2.x
+ * agent can prevent them from running. The session-start marker distinguishes
+ * normal hook capture from that fallback without causing duplicate writes.
+ *
+ * Keep this short. Steering is prepended to every interaction, so it competes
+ * with the user's own context budget; the skill still owns tool-by-tool detail.
+ *
+ * @param {string} version - installer version, stamped so a re-run can tell staleness
+ * @param {string} name - MCP server name, which prefixes the tool names
+ * @returns {string}
+ */
+export function renderSteeringDoc(version, name) {
+  const toolPrefix = `mcp__${name}__`;
+  return [
+    "---",
+    "inclusion: always",
+    "---",
+    "",
+    `<!-- Managed by meko installer v${version}. Re-running the installer overwrites this file. -->`,
+    "",
+    "# Meko memory",
+    "",
+    `You have a persistent memory store through the \`${name}\` MCP server.`,
+    "",
+    "Kiro normally starts durable hook capture and injects the marker",
+    "`MEKO_CAPTURE_SESSION_STARTED` into session context.",
+    "",
+    "- If that marker is present, follow the `meko-mcp-tools` hook-capture rules.",
+    "  Do not duplicate conversational facts with proactive memory writes.",
+    "- If that marker is absent, hooks are disabled, the IDE workspace may be",
+    "  untrusted, or a different CLI 2.x agent is selected. In that fallback",
+    "  mode, save durable facts proactively as described below.",
+    "",
+    "Follow these rules:",
+    "",
+    `- Search before you answer. Call \`${toolPrefix}memory_search\` at the start of a`,
+    "  conversation, and again whenever the user asks what you know about something.",
+    `- In fallback mode, call \`${toolPrefix}memory_add\` when the user`,
+    "  states something worth remembering later: their role, preferences, team",
+    "  conventions, tools, or a decision and its rationale. Prefer saving to asking.",
+    "- Skip the ephemeral. Don't store one-off task instructions, transient state,",
+    "  or anything already in the repository.",
+    `- Correct, don't duplicate. When the user contradicts a stored fact, find it with`,
+    `  \`${toolPrefix}memory_search\` and fix it with \`${toolPrefix}memory_update\` or`,
+    `  \`${toolPrefix}memory_delete_by_id\` — memory is additive, so a stale entry survives`,
+    "  until you remove it.",
+    "",
+    "For tool arguments, `agent_id` conventions, and datapack selection, see the",
+    "`meko-mcp-tools` skill.",
+    "",
+  ].join("\n");
+}
+
+/**
+ * True when `destination` is a symlink resolving to `expectedSource` — an
+ * in-place symlink install whose content is already current.
+ */
+function isOwnSymlink(destination, expectedSource) {
+  try {
+    const stat = lstatSync(destination);
+    if (!stat.isSymbolicLink()) return false;
+    const linkTarget = readlinkSync(destination);
+    return resolve(dirname(destination), linkTarget) === expectedSource;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove the steering file, but only if we wrote it.
+ *
+ * We own the `meko.md` filename, yet a user could still have created one by
+ * hand. The managed marker comment is the discriminator — no marker, no delete.
+ */
+function removeKiroSteering(steeringPath) {
+  if (!existsSync(steeringPath)) return;
+  const raw = readFileSync(steeringPath, "utf8");
+  if (!raw.includes("Managed by meko installer")) return;
+  rmSync(steeringPath, { force: true });
+}
+
+function uninstallKiroSkills({ scope, projectRoot, paths, resolveSkillSourcePath }) {
+  const skillsDir = paths.getSkillsDir(scope, projectRoot);
+
+  for (const skill of SKILLS) {
+    const dest = join(skillsDir, skill.name);
+    if (!existsSync(dest)) continue;
+
+    // A marker means we materialized this copy, so it is ours to delete.
+    if (existsSync(join(dest, ".meko-installer"))) {
+      removePath(dest);
+      continue;
+    }
+
+    // Otherwise only remove it if it is a symlink we created into our own
+    // asset tree — never touch a user-authored skill of the same name.
+    try {
+      if (!lstatSync(dest).isSymbolicLink()) continue;
+      const resolvedTarget = resolve(dirname(dest), readlinkSync(dest));
+      if (resolvedTarget === resolveSkillSourcePath(skill.name)) {
+        removePath(dest);
+      }
+    } catch {
+      // no-op
+    }
+  }
+}