cairn-ai 0.1.2 → 0.1.5

package/scripts/cairn

@@ -1,10 +1,6 @@
 #!/bin/sh
 set -eu
 
-cmd="${1:-help}"
-shift || true
-locale="${LC_ALL:-${LC_MESSAGES:-${LANG:-en}}}"
-
 script_path="$0"
 link_target="$(readlink "$script_path" 2>/dev/null || true)"
 if [ -n "$link_target" ]; then
@@ -15,101 +11,4 @@ if [ -n "$link_target" ]; then
 fi
 script_dir="$(cd "$(dirname "$script_path")" && pwd)"
 
-locale_family() {
-  case "$locale" in
-    ko*|KO*) printf '%s\n' ko ;;
-    ja*|JA*) printf '%s\n' ja ;;
-    zh*|ZH*) printf '%s\n' zh ;;
-    es*|ES*) printf '%s\n' es ;;
-    fr*|FR*) printf '%s\n' fr ;;
-    de*|DE*) printf '%s\n' de ;;
-    pt*|PT*) printf '%s\n' pt ;;
-    *) printf '%s\n' en ;;
-  esac
-}
-
-say() {
-  key="$1"
-  family="$(locale_family)"
-  case "$family:$key" in
-    ko:memory) printf '%s\n' "cairn-memory 스킬을 사용하세요. MEMORY.md는 짧은 색인으로, 상세 내용은 docs/memory/<domain>.md에 기록합니다." ;;
-    ko:plan) printf '%s\n' "cairn-plan 스킬을 사용하세요. PLAN.md는 색인으로, 상세 계획은 docs/plan/<topic>.md에 기록합니다." ;;
-    ko:work) printf '%s\n' "cairn-work 스킬을 사용하세요. 하나의 모듈 조각을 실행하고 모듈 증거와 표면 증거를 확보합니다." ;;
-    ko:review) printf '%s\n' "cairn-review 스킬을 사용하세요. PLAN.md와 MEMORY.md 기준으로 증거를 비교합니다." ;;
-    ko:toolcheck) printf '%s\n' "저장소 도구를 점검하려면 cairn toolcheck 를 실행하세요. 누락 도구 설치까지 시도하려면 cairn toolcheck --install 을 사용합니다." ;;
-    ko:usage) printf '%s\n' "사용법: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
-    ja:memory) printf '%s\n' "cairn-memory スキルを使用してください。MEMORY.md は短い索引にし、詳細は docs/memory/<domain>.md に記録します。" ;;
-    ja:plan) printf '%s\n' "cairn-plan スキルを使用してください。PLAN.md は索引にし、詳細計画は docs/plan/<topic>.md に記録します。" ;;
-    ja:work) printf '%s\n' "cairn-work スキルを使用してください。1つのモジュールスライスを実行し、モジュール証拠と表面証拠を取得します。" ;;
-    ja:review) printf '%s\n' "cairn-review スキルを使用してください。PLAN.md と MEMORY.md に照らして証拠を比較します。" ;;
-    ja:toolcheck) printf '%s\n' "リポジトリツールを確認するには cairn toolcheck を実行してください。不足ツールのインストールも試すには cairn toolcheck --install を使用します。" ;;
-    ja:usage) printf '%s\n' "使い方: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
-    zh:memory) printf '%s\n' "使用 cairn-memory skill。将 MEMORY.md 保持为简短索引，并将详细内容写入 docs/memory/<domain>.md。" ;;
-    zh:plan) printf '%s\n' "使用 cairn-plan skill。将 PLAN.md 保持为索引，并将详细计划写入 docs/plan/<topic>.md。" ;;
-    zh:work) printf '%s\n' "使用 cairn-work skill。执行一个模块切片，并收集模块证据和表面证据。" ;;
-    zh:review) printf '%s\n' "使用 cairn-review skill。根据 PLAN.md 和 MEMORY.md 对比证据。" ;;
-    zh:toolcheck) printf '%s\n' "运行 cairn toolcheck 检查仓库工具。使用 cairn toolcheck --install 尝试安装缺失工具。" ;;
-    zh:usage) printf '%s\n' "用法: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
-    es:memory) printf '%s\n' "Usa la skill cairn-memory. Mantén MEMORY.md como un índice breve y escribe los detalles en docs/memory/<domain>.md." ;;
-    es:plan) printf '%s\n' "Usa la skill cairn-plan. Mantén PLAN.md como índice y escribe los planes detallados en docs/plan/<topic>.md." ;;
-    es:work) printf '%s\n' "Usa la skill cairn-work. Ejecuta un solo segmento de módulo y captura evidencia de módulo y de superficie." ;;
-    es:review) printf '%s\n' "Usa la skill cairn-review. Compara la evidencia con PLAN.md y MEMORY.md." ;;
-    es:toolcheck) printf '%s\n' "Ejecuta cairn toolcheck para revisar herramientas del repositorio. Usa cairn toolcheck --install para intentar instalar herramientas faltantes." ;;
-    es:usage) printf '%s\n' "Uso: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
-    fr:memory) printf '%s\n' "Utilisez la skill cairn-memory. Gardez MEMORY.md comme index court et écrivez les détails dans docs/memory/<domain>.md." ;;
-    fr:plan) printf '%s\n' "Utilisez la skill cairn-plan. Gardez PLAN.md comme index et écrivez les plans détaillés dans docs/plan/<topic>.md." ;;
-    fr:work) printf '%s\n' "Utilisez la skill cairn-work. Exécutez une tranche de module et capturez les preuves de module et de surface." ;;
-    fr:review) printf '%s\n' "Utilisez la skill cairn-review. Comparez les preuves avec PLAN.md et MEMORY.md." ;;
-    fr:toolcheck) printf '%s\n' "Exécutez cairn toolcheck pour vérifier les outils du dépôt. Utilisez cairn toolcheck --install pour tenter d'installer les outils manquants." ;;
-    fr:usage) printf '%s\n' "Utilisation: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
-    de:memory) printf '%s\n' "Verwenden Sie die Skill cairn-memory. Halten Sie MEMORY.md als kurzen Index und schreiben Sie Details nach docs/memory/<domain>.md." ;;
-    de:plan) printf '%s\n' "Verwenden Sie die Skill cairn-plan. Halten Sie PLAN.md als Index und schreiben Sie Detailpläne nach docs/plan/<topic>.md." ;;
-    de:work) printf '%s\n' "Verwenden Sie die Skill cairn-work. Führen Sie einen Modulabschnitt aus und erfassen Sie Modul- und Oberflächenbelege." ;;
-    de:review) printf '%s\n' "Verwenden Sie die Skill cairn-review. Vergleichen Sie Belege mit PLAN.md und MEMORY.md." ;;
-    de:toolcheck) printf '%s\n' "Führen Sie cairn toolcheck aus, um Repository-Tools zu prüfen. Verwenden Sie cairn toolcheck --install, um fehlende Tools zu installieren." ;;
-    de:usage) printf '%s\n' "Verwendung: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
-    pt:memory) printf '%s\n' "Use a skill cairn-memory. Mantenha MEMORY.md como um índice curto e escreva detalhes em docs/memory/<domain>.md." ;;
-    pt:plan) printf '%s\n' "Use a skill cairn-plan. Mantenha PLAN.md como índice e escreva planos detalhados em docs/plan/<topic>.md." ;;
-    pt:work) printf '%s\n' "Use a skill cairn-work. Execute uma fatia de módulo e capture evidências de módulo e de superfície." ;;
-    pt:review) printf '%s\n' "Use a skill cairn-review. Compare evidências com PLAN.md e MEMORY.md." ;;
-    pt:toolcheck) printf '%s\n' "Execute cairn toolcheck para verificar ferramentas do repositório. Use cairn toolcheck --install para tentar instalar ferramentas ausentes." ;;
-    pt:usage) printf '%s\n' "Uso: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
-    *)
-      case "$key" in
-        memory) printf '%s\n' "Use the cairn-memory skill. Keep MEMORY.md as a short index and write details to docs/memory/<domain>.md." ;;
-        plan) printf '%s\n' "Use the cairn-plan skill. Keep PLAN.md as an index and write detailed plans to docs/plan/<topic>.md." ;;
-        work) printf '%s\n' "Use the cairn-work skill. Execute one module slice and capture module and surface evidence." ;;
-        review) printf '%s\n' "Use the cairn-review skill. Compare evidence against PLAN.md and MEMORY.md." ;;
-        toolcheck) printf '%s\n' "Run cairn toolcheck to inspect repository tools. Use cairn toolcheck --install to attempt missing tool installation." ;;
-        usage) printf '%s\n' "Usage: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
-      esac
-      ;;
-  esac
-}
-
-case "$cmd" in
-  install|upgrade|doctor|uninstall)
-    node "$script_dir/cairn-lifecycle.mjs" "$cmd" "$@"
-    ;;
-  init)
-    sh "$script_dir/cairn-state.sh" manual
-    ;;
-  memory)
-    say memory
-    ;;
-  plan)
-    say plan
-    ;;
-  work)
-    say work
-    ;;
-  review)
-    say review
-    ;;
-  toolcheck)
-    node "$script_dir/cairn-toolcheck.mjs" "$@"
-    ;;
-  *)
-    say usage
-    ;;
-esac
+exec node "$script_dir/cairn.mjs" "$@"

package/scripts/cairn-lifecycle.mjs

@@ -2,14 +2,16 @@
 import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const codexHome = resolve(process.env.CODEX_HOME ?? join(process.env.HOME ?? ".", ".codex"));
-const claudeHome = resolve(process.env.CLAUDE_HOME ?? join(process.env.HOME ?? ".", ".claude"));
-const antigravityHome = resolve(process.env.ANTIGRAVITY_HOME ?? join(process.env.HOME ?? ".", ".agents"));
-const antigravityCliHome = resolve(process.env.ANTIGRAVITY_CLI_HOME ?? join(process.env.HOME ?? ".", ".gemini", "antigravity-cli"));
+const homeRoot = process.env.HOME ?? process.env.USERPROFILE ?? homedir() ?? ".";
+const codexHome = resolve(process.env.CODEX_HOME ?? join(homeRoot, ".codex"));
+const claudeHome = resolve(process.env.CLAUDE_HOME ?? join(homeRoot, ".claude"));
+const antigravityHome = resolve(process.env.ANTIGRAVITY_HOME ?? join(homeRoot, ".agents"));
+const antigravityCliHome = resolve(process.env.ANTIGRAVITY_CLI_HOME ?? join(homeRoot, ".gemini", "antigravity-cli"));
 const configPath = process.env.CODEX_CONFIG_PATH ?? join(codexHome, "config.toml");
 const marketplaceName = "cairn";
 const pluginName = "cairn";
@@ -87,7 +89,7 @@ async function copyPlugin() {
   await mkdir(dirname(installedPluginRoot), { recursive: true });
   await cp(pluginRoot, installedPluginRoot, {
     recursive: true,
-    filter: (source) => !source.includes(`${pluginRoot}/.git`) && !source.includes(`${pluginRoot}/node_modules`),
+    filter: (source) => !pathHasSegment(relative(pluginRoot, source), ".git") && !pathHasSegment(relative(pluginRoot, source), "node_modules"),
   });
   const manifestPath = join(installedPluginRoot, ".codex-plugin", "plugin.json");
   const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
@@ -257,6 +259,10 @@ function append(config, block) {
   return `${config.trimEnd()}${config.trimEnd().length === 0 ? "" : "\n\n"}${block.trimEnd()}\n`;
 }
 
+export function pathHasSegment(path, segment) {
+  return path.split(/[\\/]+/).includes(segment);
+}
+
 export function commandNames() {
   return ["install", "upgrade", "doctor", "uninstall", "memory", "plan", "work", "review", "toolcheck"];
 }

package/scripts/cairn-state.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const memoryTemplate = `# MEMORY
+
+This file is a short index of persistent repository knowledge.
+
+## Domain Knowledge
+
+- Link detailed notes under \`docs/memory/\`.
+
+## Policy
+
+- Prefer precise repository exploration before implementation.
+- Preserve proper nouns, file names, variable names, service names, alert names, MCP tool names, and agent names exactly as written.
+- Read only the detailed memory files needed for the current task.
+- Write user-visible responses and artifacts in the OS locale unless the user asks for another language.
+
+## Update Rules
+
+- Keep root files short.
+- Move detailed domain knowledge to \`docs/memory/<domain>.md\`.
+- Record facts with source paths, commands, and observed behavior.
+`;
+
+const planTemplate = `# PLAN
+
+This file is a short index of active and completed work plans.
+
+## Active Plans
+
+- Link detailed plans under \`docs/plan/\`.
+
+## Completed Plans
+
+- Move completed topics here with evidence links.
+
+## Planning Rules
+
+- Every agent must start assigned work by reading the project-root \`MEMORY.md\` for domain knowledge and repository policy.
+- Plans must be decision-complete before implementation.
+- Run complexity triage before applying agent, plugin, or delegated workflow guidance.
+- Record the selected Light Path or Heavy Path and the checked Heavy Path signals in \`docs/plan/<topic>.md\`.
+- Split implementation into small module slices.
+- Detect repository stack and required LSP/check tools before implementation.
+- Install or bootstrap missing required tools before declaring them unavailable.
+- Each slice normally passes exactly two gates.
+  - Module acceptance verification.
+  - Surface integration verification.
+- Run dry-run or check mode before external-state mutation when available.
+- Use at most two verification passes per slice by default.
+- If a gate fails, diagnose once, shrink or split the slice, and rerun both gates.
+- After two failed passes, record the blocker in \`docs/plan/<topic>.md\`.
+`;
+
+if (isCliEntry()) {
+  const event = process.argv[2] ?? "manual";
+  console.log(await runState(event));
+}
+
+export async function runState(event = "manual", { root = process.env.HARNESS_REPO_ROOT ?? process.cwd(), locale = localeValue() } = {}) {
+  const resolvedRoot = resolve(root);
+  await mkdir(join(resolvedRoot, "docs", "memory"), { recursive: true });
+  await mkdir(join(resolvedRoot, "docs", "plan"), { recursive: true });
+  await writeIfMissing(join(resolvedRoot, "MEMORY.md"), memoryTemplate);
+  await writeIfMissing(join(resolvedRoot, "PLAN.md"), planTemplate);
+
+  const ko = locale.toLowerCase().startsWith("ko");
+  if (event === "session-start" || event === "user-prompt-submit") {
+    return ko
+      ? "Cairn 컨텍스트: 모든 에이전트는 작업 시작 시 도메인 지식과 정책 색인인 프로젝트 루트 MEMORY.md를 먼저 읽어야 합니다."
+      : "Cairn context: every agent must start by reading the project-root MEMORY.md for domain knowledge and repository policy.";
+  }
+  if (event === "post-tool-use") {
+    return ko
+      ? "Cairn 점검: 외부 상태 변경에는 dry-run/check 증거가 필요하고, 동작이 바뀌었다면 docs/plan 증거를 갱신하세요."
+      : "Cairn check: external-state changes need dry-run/check evidence; if behavior changed, update docs/plan evidence.";
+  }
+  if (event === "stop" || event === "subagent-stop") {
+    return ko
+      ? "Cairn 종료 게이트: 완료에는 docs/plan의 dry-run/check, 모듈 수용, 표면 통합 증거가 필요합니다."
+      : "Cairn stop gate: completion requires dry-run/check, module acceptance, and surface integration evidence in docs/plan.";
+  }
+  return ko
+    ? "Cairn이 MEMORY.md, PLAN.md, docs/memory, docs/plan을 초기화했습니다."
+    : "Cairn initialized MEMORY.md, PLAN.md, docs/memory, and docs/plan.";
+}
+
+async function writeIfMissing(path, content) {
+  try {
+    await readFile(path, "utf8");
+  } catch {
+    await writeFile(path, content);
+  }
+}
+
+function localeValue() {
+  return [process.env.LC_ALL, process.env.LC_MESSAGES, process.env.LANG]
+    .find((value) => typeof value === "string" && value.length > 0) ?? Intl.DateTimeFormat().resolvedOptions().locale;
+}
+
+function isCliEntry() {
+  return process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+}

package/scripts/cairn-state.sh

@@ -51,6 +51,7 @@ This file is a short index of active and completed work plans.
 
 ## Planning Rules
 
+- Every agent must start assigned work by reading the project-root `MEMORY.md` for domain knowledge and repository policy.
 - Plans must be decision-complete before implementation.
 - Split implementation into small module slices.
 - Detect repository stack and required LSP/check tools before implementation.
@@ -75,9 +76,9 @@ is_ko() {
 case "$event" in
   session-start|user-prompt-submit)
     if is_ko; then
-      printf '%s\n' "Cairn 컨텍스트: 먼저 MEMORY.md와 PLAN.md를 읽고, 필요한 경우 toolcheck로 LSP/check 도구 준비 상태를 확인하세요."
+      printf '%s\n' "Cairn 컨텍스트: 모든 에이전트는 작업 시작 시 도메인 지식과 정책 색인인 프로젝트 루트 MEMORY.md를 먼저 읽어야 합니다."
     else
-      printf '%s\n' "Cairn context: read MEMORY.md and PLAN.md first, then run toolcheck when LSP/check tool readiness is needed."
+      printf '%s\n' "Cairn context: every agent must start by reading the project-root MEMORY.md for domain knowledge and repository policy."
     fi
     ;;
   post-tool-use)

package/scripts/cairn-toolcheck.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readdir, stat } from "node:fs/promises";
-import { join } from "node:path";
+import { join, relative, sep } from "node:path";
 import { spawnSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 
@@ -60,7 +60,7 @@ export async function collectEntries(base) {
     for (const entry of await readdir(dir)) {
       if ([".git", ".cairn", "node_modules", "vendor", "target", ".venv", "__pycache__"].includes(entry)) continue;
       const path = join(dir, entry);
-      const relativePath = path.slice(base.length + 1);
+      const relativePath = normalizePath(relative(base, path));
       if (relativePath === "test/fixtures" || relativePath.startsWith("test/fixtures/")) continue;
       const info = await stat(path);
       if (info.isDirectory()) await walk(path);
@@ -85,7 +85,7 @@ export function detectStacks(paths) {
   return [...stacks];
 }
 
-export function buildRequirements(stacks, entries = [], commandAvailable = commandOk) {
+export function buildRequirements(stacks, entries = [], commandAvailable = commandOk, platform = process.platform) {
   const requirements = [];
   if (stacks.includes("javascript")) {
     requirements.push(req("node", ["--version"], "JavaScript runtime for package scripts and CLI checks"));
@@ -98,8 +98,8 @@ export function buildRequirements(stacks, entries = [], commandAvailable = comma
   if (stacks.includes("python")) {
     const uv = commandAvailable("uv", ["--version"]);
     const project = entries.includes("pyproject.toml");
-    const basedpyrightInstall = pythonInstall(uv, project, "basedpyright");
-    const ruffInstall = pythonInstall(uv, project, "ruff");
+    const basedpyrightInstall = pythonInstall(uv, project, "basedpyright", platform);
+    const ruffInstall = pythonInstall(uv, project, "ruff", platform);
     requirements.push(req("basedpyright", ["--version"], "Python LSP/type checker", basedpyrightInstall));
     requirements.push(req("ruff", ["--version"], "Python lint and format checker", ruffInstall));
   }
@@ -114,7 +114,7 @@ export function buildRequirements(stacks, entries = [], commandAvailable = comma
   }
   if (stacks.includes("java")) {
     addJvmRequirements(requirements);
-    requirements.push(req("jdtls", ["--version"], "Java LSP server", { command: "bash", args: ["-lc", "mkdir -p .cairn/tools && curl -L https://download.eclipse.org/jdtls/milestones/latest/jdt-language-server-latest.tar.gz | tar -xz -C .cairn/tools"] }));
+    requirements.push(req("jdtls", ["--version"], "Java LSP server", jdtlsInstall(platform)));
     addJvmBuildToolRequirements(requirements, entries);
   }
   if (stacks.includes("kotlin")) {
@@ -151,9 +151,12 @@ export function addJvmRequirements(requirements) {
 }
 
 export function addJvmBuildToolRequirements(requirements, entries = []) {
-  if (entries.includes("gradlew")) pushUnique(requirements, req("./gradlew", ["--version"], "Gradle wrapper availability"));
+  if (entries.includes("gradlew.bat")) pushUnique(requirements, req("gradlew.bat", ["--version"], "Gradle wrapper availability"));
+  else if (entries.includes("gradlew")) pushUnique(requirements, req("./gradlew", ["--version"], "Gradle wrapper availability"));
   else if (entries.includes("build.gradle") || entries.includes("build.gradle.kts")) pushUnique(requirements, req("gradle", ["--version"], "Gradle availability"));
-  if (entries.includes("mvnw")) pushUnique(requirements, req("./mvnw", ["--version"], "Maven wrapper availability"));
+  if (entries.includes("mvnw.cmd")) pushUnique(requirements, req("mvnw.cmd", ["--version"], "Maven wrapper availability"));
+  else if (entries.includes("mvnw.bat")) pushUnique(requirements, req("mvnw.bat", ["--version"], "Maven wrapper availability"));
+  else if (entries.includes("mvnw")) pushUnique(requirements, req("./mvnw", ["--version"], "Maven wrapper availability"));
   else if (entries.includes("pom.xml")) pushUnique(requirements, req("mvn", ["--version"], "Maven availability"));
 }
 
@@ -165,12 +168,24 @@ export function composerInstall(packages) {
   return { command: "composer", args: ["require", "--dev", ...packages] };
 }
 
-export function pythonInstall(uv, project, tool) {
+export function pythonInstall(uv, project, tool, platform = process.platform) {
   if (uv && project) return { command: "uv", args: ["add", "--dev", tool] };
   if (uv) return { command: "uv", args: ["tool", "install", tool] };
+  if (platform === "win32") return { command: "py", args: ["-3", "-m", "pip", "install", "--user", tool] };
   return { command: "python3", args: ["-m", "pip", "install", "--user", tool] };
 }
 
+export function jdtlsInstall(platform = process.platform) {
+  const url = "https://download.eclipse.org/jdtls/milestones/latest/jdt-language-server-latest.tar.gz";
+  if (platform === "win32") {
+    return {
+      command: "powershell",
+      args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", `New-Item -ItemType Directory -Force .cairn/tools | Out-Null; Invoke-WebRequest -Uri ${url} -OutFile .cairn/tools/jdtls.tar.gz; tar -xzf .cairn/tools/jdtls.tar.gz -C .cairn/tools`],
+    };
+  }
+  return { command: "bash", args: ["-lc", `mkdir -p .cairn/tools && curl -L ${url} | tar -xz -C .cairn/tools`] };
+}
+
 export function req(command, args, reason, installCommand = null) {
   return { name: command, command, args, reason, install: installCommand };
 }
@@ -190,16 +205,41 @@ export function installDev(pm, packages) {
 }
 
 export function commandOk(command, args, root = process.cwd(), runner = run) {
-  if (runner(command, args).status === 0) return true;
-  if (runner(join(root, "node_modules", ".bin", command), args).status === 0) return true;
-  if (runner(join(root, "vendor", "bin", command), args).status === 0) return true;
-  return runner(join(root, ".cairn", "tools", "bin", command), args).status === 0;
+  return commandCandidates(command, root).some((candidate) => runner(candidate, args).status === 0);
+}
+
+export function commandCandidates(command, root = process.cwd(), platform = process.platform) {
+  const candidates = [
+    command,
+    join(root, "node_modules", ".bin", command),
+    join(root, "vendor", "bin", command),
+    join(root, ".cairn", "tools", "bin", command),
+  ];
+  if (platform !== "win32") return candidates;
+  const extensions = [".cmd", ".bat", ".exe"];
+  return candidates.flatMap((candidate) => hasWindowsExecutableExtension(candidate) ? [candidate] : [candidate, ...extensions.map((extension) => `${candidate}${extension}`)]);
 }
 
 export function run(command, args) {
-  return spawnSync(command, args, { stdio: "ignore", encoding: "utf8" });
+  return spawnSync(command, args, {
+    stdio: "ignore",
+    encoding: "utf8",
+    shell: shouldUseShell(command),
+  });
+}
+
+export function shouldUseShell(command, platform = process.platform) {
+  return platform === "win32" && /\.(cmd|bat)$/i.test(command);
 }
 
 function isCliEntry() {
   return process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 }
+
+function normalizePath(path) {
+  return path.split(sep).join("/");
+}
+
+function hasWindowsExecutableExtension(command) {
+  return /\.(cmd|bat|exe)$/i.test(command);
+}

package/scripts/cairn.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+import { runState } from "./cairn-state.mjs";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+
+export async function main(command = "help", args = [], { runner = spawnSync } = {}) {
+  if (["install", "upgrade", "doctor", "uninstall"].includes(command)) {
+    const result = runner(process.execPath, [join(scriptDir, "cairn-lifecycle.mjs"), command, ...args], { stdio: "inherit" });
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+  if (command === "init") {
+    console.log(await runState("manual"));
+    return;
+  }
+  if (command === "toolcheck") {
+    const result = runner(process.execPath, [join(scriptDir, "cairn-toolcheck.mjs"), ...args], { stdio: "inherit" });
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+  if (["memory", "plan", "work", "review"].includes(command)) {
+    console.log(message(command));
+    return;
+  }
+  console.log(message("usage"));
+}
+
+export function message(key, locale = localeValue()) {
+  const family = localeFamily(locale);
+  return messages[family]?.[key] ?? messages.en[key];
+}
+
+export function localeFamily(locale = localeValue()) {
+  const normalized = locale.toLowerCase();
+  for (const family of ["ko", "ja", "zh", "es", "fr", "de", "pt"]) {
+    if (normalized.startsWith(family)) return family;
+  }
+  return "en";
+}
+
+function localeValue() {
+  return [process.env.LC_ALL, process.env.LC_MESSAGES, process.env.LANG]
+    .find((value) => typeof value === "string" && value.length > 0) ?? Intl.DateTimeFormat().resolvedOptions().locale;
+}
+
+function isCliEntry() {
+  return process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+}
+
+const messages = {
+  en: {
+    memory: "Use the cairn-memory skill. Keep MEMORY.md as a short index and write details to docs/memory/<domain>.md.",
+    plan: "Use the cairn-plan skill before non-trivial implementation. Every agent must first read the project-root MEMORY.md for domain knowledge and repository policy. Keep PLAN.md as an index, write detailed plans to docs/plan/<topic>.md, and record Light/Heavy Path triage before any mutation.",
+    work: "Use the cairn-work skill only after a plan exists. Every agent must first read the project-root MEMORY.md for domain knowledge and repository policy. Execute one module slice using the recorded Light/Heavy Path route, and capture dry-run/check, module, and surface evidence.",
+    review: "Use the cairn-review skill. Compare evidence against PLAN.md and MEMORY.md.",
+    usage: "Usage: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck",
+  },
+  ko: {
+    memory: "cairn-memory 스킬을 사용하세요. MEMORY.md는 짧은 색인으로, 상세 내용은 docs/memory/<domain>.md에 기록합니다.",
+    plan: "중요 구현 전에는 cairn-plan 스킬을 사용하세요. 모든 에이전트는 도메인 지식과 저장소 정책을 위해 프로젝트 루트 MEMORY.md를 먼저 읽어야 합니다. PLAN.md는 색인으로, 상세 계획은 docs/plan/<topic>.md에 기록하며 파일 변경 전 Light/Heavy Path 트리아지를 남깁니다.",
+    work: "계획이 있을 때만 cairn-work 스킬을 사용하세요. 모든 에이전트는 도메인 지식과 저장소 정책을 위해 프로젝트 루트 MEMORY.md를 먼저 읽어야 합니다. 기록된 Light/Heavy Path 경로로 하나의 모듈 조각을 실행하며 dry-run/check, 모듈, 표면 증거를 확보합니다.",
+    review: "cairn-review 스킬을 사용하세요. PLAN.md와 MEMORY.md 기준으로 증거를 비교합니다.",
+    usage: "사용법: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck",
+  },
+  ja: {
+    memory: "cairn-memory スキルを使用してください。MEMORY.md は短い索引にし、詳細は docs/memory/<domain>.md に記録します。",
+    plan: "cairn-plan スキルを使用してください。PLAN.md は索引にし、詳細計画は docs/plan/<topic>.md に記録します。",
+    work: "cairn-work スキルを使用してください。1つのモジュールスライスを実行し、モジュール証拠と表面証拠を取得します。",
+    review: "cairn-review スキルを使用してください。PLAN.md と MEMORY.md に照らして証拠を比較します。",
+    usage: "使い方: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck",
+  },
+  zh: {
+    memory: "使用 cairn-memory skill。将 MEMORY.md 保持为简短索引，并将详细内容写入 docs/memory/<domain>.md。",
+    plan: "使用 cairn-plan skill。将 PLAN.md 保持为索引，并将详细计划写入 docs/plan/<topic>.md。",
+    work: "使用 cairn-work skill。执行一个模块切片，并收集模块证据。",
+    review: "使用 cairn-review skill。根据 PLAN.md 和 MEMORY.md 对比证据。",
+    usage: "用法: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck",
+  },
+  es: {
+    memory: "Usa la skill cairn-memory. Mantén MEMORY.md como un índice breve y escribe los detalles en docs/memory/<domain>.md.",
+    plan: "Usa la skill cairn-plan. Mantén PLAN.md como índice y escribe los planes detallados en docs/plan/<topic>.md.",
+    work: "Usa la skill cairn-work. Ejecuta un solo segmento de módulo y captura evidencia de módulo y de superficie.",
+    review: "Usa la skill cairn-review. Compara la evidencia con PLAN.md y MEMORY.md.",
+    usage: "Uso: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck",
+  },
+  fr: {
+    memory: "Utilisez la skill cairn-memory. Gardez MEMORY.md comme index court et écrivez les détails dans docs/memory/<domain>.md.",
+    plan: "Utilisez la skill cairn-plan. Gardez MEMORY.md comme index et écrivez les plans détaillés dans docs/plan/<topic>.md.",
+    work: "Utilisez la skill cairn-work. Exécutez une tranche de module et capturez les preuves de module et de surface.",
+    review: "Utilisez la skill cairn-review. Comparez les preuves avec PLAN.md et MEMORY.md.",
+    usage: "Utilisation: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck",
+  },
+  de: {
+    memory: "Verwenden Sie die Skill cairn-memory. Halten Sie MEMORY.md als kurzen Index und schreiben Sie Details nach docs/memory/<domain>.md.",
+    plan: "Verwenden Sie die Skill cairn-plan. Halten Sie MEMORY.md als Index und schreiben Sie Detailpläne nach docs/plan/<topic>.md.",
+    work: "Verwenden Sie die Skill cairn-work. Führen Sie einen Modulabschnitt aus und erfassen Sie Modul- und Oberflächenbelege.",
+    review: "Verwenden Sie die Skill cairn-review. Vergleichen Sie Belege mit PLAN.md und MEMORY.md.",
+    usage: "Verwendung: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck",
+  },
+  pt: {
+    memory: "Use a skill cairn-memory. Mantenha MEMORY.md como um índice curto e escreva detalhes em docs/memory/<domain>.md.",
+    plan: "Use a skill cairn-plan. Mantenha MEMORY.md como índice e escreva planos detalhados em docs/plan/<topic>.md.",
+    work: "Use a skill cairn-work. Execute uma fatia de módulo e capture evidências de módulo e de superfície.",
+    review: "Use a skill cairn-review. Compare evidências com PLAN.md e MEMORY.md.",
+    usage: "Uso: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck",
+  },
+};
+
+if (isCliEntry()) {
+  const [command = "help", ...args] = process.argv.slice(2);
+  await main(command, args);
+}

package/skills/cairn-memory/SKILL.md

@@ -11,9 +11,11 @@ Use this when domain knowledge, repository policy, or pre-plan context compressi
 
 The root `MEMORY.md` is an index, not detailed knowledge. Record details in `docs/memory/<domain>.md`.
 
+Every delegated agent must read the project-root `MEMORY.md` before doing its assigned discovery, evidence, or update task.
+
 ## Procedure
 
-1. Run `scripts/cairn-state.sh manual` if it exists. Otherwise ensure `MEMORY.md`, `PLAN.md`, `docs/memory`, and `docs/plan` directly.
+1. Run `node scripts/cairn-state.mjs manual` if it exists. Otherwise ensure `MEMORY.md`, `PLAN.md`, `docs/memory`, and `docs/plan` directly.
 2. Explore the repository before asking the user.
 3. Delegate when it materially improves speed or quality instead of asking the user.
    - `explorer`: read-only domain discovery, boundaries, invariants, policies, contradictions, and stale facts when available.
@@ -28,7 +30,7 @@ The root `MEMORY.md` is an index, not detailed knowledge. Record details in `doc
 TASK: Explore persistent domain knowledge for <domain>.
 EXPECTED OUTCOME: Return facts, source paths, and proof commands concisely.
 REQUIRED TOOLS: Read-only file search, LSP/symbol tools, command checks.
-MUST DO: Preserve proper nouns exactly. Cite local paths. Separate facts from inference. Use the OS locale for user-visible text.
+MUST DO: Read the project-root `MEMORY.md` before doing assigned work. Preserve proper nouns exactly. Cite local paths. Separate facts from inference. Use the OS locale for user-visible text.
 MUST NOT DO: Edit files. Ask the user. Guess missing names.
 CONTEXT: Current task, repository root, existing MEMORY.md entries.
 ```