cairn-ai 0.1.2

package/scripts/cairn-state.sh

@@ -0,0 +1,104 @@
+#!/bin/sh
+set -eu
+
+event="${1:-manual}"
+root="${HARNESS_REPO_ROOT:-$(pwd)}"
+locale="${LC_ALL:-${LC_MESSAGES:-${LANG:-en}}}"
+
+mkdir -p "$root/docs/memory" "$root/docs/plan"
+
+memory="$root/MEMORY.md"
+plan="$root/PLAN.md"
+
+if [ ! -f "$memory" ]; then
+  cat > "$memory" <<'EOF'
+# 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.
+EOF
+fi
+
+if [ ! -f "$plan" ]; then
+  cat > "$plan" <<'EOF'
+# 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
+
+- Plans must be decision-complete before implementation.
+- 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`.
+EOF
+fi
+
+is_ko() {
+  case "$locale" in
+    ko*|KO*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+case "$event" in
+  session-start|user-prompt-submit)
+    if is_ko; then
+      printf '%s\n' "Cairn 컨텍스트: 먼저 MEMORY.md와 PLAN.md를 읽고, 필요한 경우 toolcheck로 LSP/check 도구 준비 상태를 확인하세요."
+    else
+      printf '%s\n' "Cairn context: read MEMORY.md and PLAN.md first, then run toolcheck when LSP/check tool readiness is needed."
+    fi
+    ;;
+  post-tool-use)
+    if is_ko; then
+      printf '%s\n' "Cairn 점검: 외부 상태 변경에는 dry-run/check 증거가 필요하고, 동작이 바뀌었다면 docs/plan 증거를 갱신하세요."
+    else
+      printf '%s\n' "Cairn check: external-state changes need dry-run/check evidence; if behavior changed, update docs/plan evidence."
+    fi
+    ;;
+  stop|subagent-stop)
+    if is_ko; then
+      printf '%s\n' "Cairn 종료 게이트: 완료에는 docs/plan의 dry-run/check, 모듈 수용, 표면 통합 증거가 필요합니다."
+    else
+      printf '%s\n' "Cairn stop gate: completion requires dry-run/check, module acceptance, and surface integration evidence in docs/plan."
+    fi
+    ;;
+  *)
+    if is_ko; then
+      printf '%s\n' "Cairn이 MEMORY.md, PLAN.md, docs/memory, docs/plan을 초기화했습니다."
+    else
+      printf '%s\n' "Cairn initialized MEMORY.md, PLAN.md, docs/memory, and docs/plan."
+    fi
+    ;;
+esac

package/scripts/cairn-toolcheck.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+if (isCliEntry()) {
+  const root = process.cwd();
+  const install = process.argv.includes("--install");
+  const json = process.argv.includes("--json");
+  const report = await createReport({ root, install });
+
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(`Cairn toolcheck: ${report.root}`);
+    console.log(`Detected stacks: ${report.detected.length > 0 ? report.detected.join(", ") : "none"}`);
+    for (const result of report.results) {
+      const prefix = result.ok ? "OK" : "MISSING";
+      const installedText = result.installed ? " installed" : "";
+      console.log(`${prefix}${installedText} ${result.name} - ${result.reason}`);
+      if (!result.ok && result.installCommand) console.log(`  install: ${result.installCommand}`);
+    }
+  }
+
+  if (report.results.some((result) => !result.ok)) process.exitCode = 1;
+}
+
+export async function createReport({ root = process.cwd(), install = false, runner = run } = {}) {
+  const entries = await collectEntries(root);
+  const detected = detectStacks(entries);
+  const requirements = buildRequirements(detected, entries, (command, args) => commandOk(command, args, root, runner));
+  const results = [];
+
+  for (const requirement of requirements) {
+    let ok = commandOk(requirement.command, requirement.args, root, runner);
+    let installed = false;
+    let installResult = null;
+    if (!ok && install && requirement.install) {
+      installResult = runner(requirement.install.command, requirement.install.args);
+      installed = installResult.status === 0;
+      ok = commandOk(requirement.command, requirement.args, root, runner);
+    }
+    results.push({
+      name: requirement.name,
+      reason: requirement.reason,
+      ok,
+      installed,
+      installCommand: requirement.install ? [requirement.install.command, ...requirement.install.args].join(" ") : null,
+      installStatus: installResult?.status ?? null,
+    });
+  }
+
+  return { root, detected, results };
+}
+
+export async function collectEntries(base) {
+  const output = [];
+  async function walk(dir) {
+    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);
+      if (relativePath === "test/fixtures" || relativePath.startsWith("test/fixtures/")) continue;
+      const info = await stat(path);
+      if (info.isDirectory()) await walk(path);
+      else output.push(relativePath);
+    }
+  }
+  await walk(base);
+  return output;
+}
+
+export function detectStacks(paths) {
+  const stacks = new Set();
+  if (paths.some((path) => path === "package.json")) stacks.add("javascript");
+  if (paths.some((path) => path === "tsconfig.json" || path.endsWith(".ts") || path.endsWith(".tsx"))) stacks.add("typescript");
+  if (paths.some((path) => path === "pyproject.toml" || path.endsWith(".py"))) stacks.add("python");
+  if (paths.some((path) => path === "composer.json" || path.endsWith(".php"))) stacks.add("php");
+  if (paths.some((path) => path === "pom.xml" || path === "build.gradle" || path.endsWith(".java"))) stacks.add("java");
+  if (paths.some((path) => path.endsWith(".kt") || path.endsWith(".kts"))) stacks.add("kotlin");
+  if (paths.some((path) => path === "Package.swift" || path.endsWith(".xcodeproj") || path.endsWith(".xcworkspace") || path.endsWith(".swift"))) stacks.add("swift");
+  if (paths.some((path) => path === "go.mod" || path.endsWith(".go"))) stacks.add("go");
+  if (paths.some((path) => path === "Cargo.toml" || path.endsWith(".rs"))) stacks.add("rust");
+  return [...stacks];
+}
+
+export function buildRequirements(stacks, entries = [], commandAvailable = commandOk) {
+  const requirements = [];
+  if (stacks.includes("javascript")) {
+    requirements.push(req("node", ["--version"], "JavaScript runtime for package scripts and CLI checks"));
+  }
+  if (stacks.includes("typescript")) {
+    const pm = packageManager(entries);
+    requirements.push(req("typescript-language-server", ["--version"], "TypeScript LSP server", installDev(pm, ["typescript", "typescript-language-server"])));
+    requirements.push(req("tsc", ["--version"], "TypeScript compiler verification", installDev(pm, ["typescript"])));
+  }
+  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");
+    requirements.push(req("basedpyright", ["--version"], "Python LSP/type checker", basedpyrightInstall));
+    requirements.push(req("ruff", ["--version"], "Python lint and format checker", ruffInstall));
+  }
+  if (stacks.includes("php")) {
+    const composerProject = entries.includes("composer.json");
+    const composerTools = ["phpactor/phpactor", "phpstan/phpstan", "friendsofphp/php-cs-fixer"];
+    requirements.push(req("php", ["--version"], "PHP runtime for Composer scripts and CLI checks"));
+    if (composerProject) requirements.push(req("composer", ["--version"], "PHP package manager for project-local tool installation"));
+    requirements.push(req("phpactor", ["--version"], "PHP LSP server", composerProject ? composerInstall(composerTools) : null));
+    requirements.push(req("phpstan", ["--version"], "PHP static analysis verification", composerProject ? composerInstall(composerTools) : null));
+    requirements.push(req("php-cs-fixer", ["--version"], "PHP formatting verification", composerProject ? composerInstall(composerTools) : null));
+  }
+  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"] }));
+    addJvmBuildToolRequirements(requirements, entries);
+  }
+  if (stacks.includes("kotlin")) {
+    addJvmRequirements(requirements);
+    requirements.push(req("kotlin-lsp.sh", ["--help"], "Kotlin LSP server"));
+    requirements.push(req("kotlinc", ["-version"], "Kotlin compiler verification"));
+    addJvmBuildToolRequirements(requirements, entries);
+  }
+  if (stacks.includes("swift")) {
+    requirements.push(req("swift", ["--version"], "Swift toolchain for build and test commands"));
+    requirements.push(req("sourcekit-lsp", ["--version"], "Swift LSP server"));
+    if (entries.some((path) => path.endsWith(".xcodeproj") || path.endsWith(".xcworkspace"))) {
+      requirements.push(req("xcodebuild", ["-version"], "Xcode build verification"));
+    }
+  }
+  if (stacks.includes("go")) {
+    requirements.push(req("gopls", ["version"], "Go LSP server", { command: "go", args: ["install", "golang.org/x/tools/gopls@latest"] }));
+    requirements.push(req("golangci-lint", ["--version"], "Go lint verification", { command: "go", args: ["install", "github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest"] }));
+  }
+  if (stacks.includes("rust")) {
+    requirements.push(req("rust-analyzer", ["--version"], "Rust LSP server", { command: "rustup", args: ["component", "add", "rust-analyzer"] }));
+    requirements.push(req("cargo", ["clippy", "--version"], "Rust clippy verification", { command: "rustup", args: ["component", "add", "clippy"] }));
+  }
+  return requirements;
+}
+
+export function addJvmRequirements(requirements) {
+  if (!requirements.some((requirement) => requirement.name === "java")) {
+    requirements.push(req("java", ["--version"], "JVM runtime for build and test commands"));
+  }
+  if (!requirements.some((requirement) => requirement.name === "javac")) {
+    requirements.push(req("javac", ["--version"], "JVM compiler verification"));
+  }
+}
+
+export function addJvmBuildToolRequirements(requirements, entries = []) {
+  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"));
+  else if (entries.includes("pom.xml")) pushUnique(requirements, req("mvn", ["--version"], "Maven availability"));
+}
+
+export function pushUnique(requirements, requirement) {
+  if (!requirements.some((candidate) => candidate.name === requirement.name)) requirements.push(requirement);
+}
+
+export function composerInstall(packages) {
+  return { command: "composer", args: ["require", "--dev", ...packages] };
+}
+
+export function pythonInstall(uv, project, tool) {
+  if (uv && project) return { command: "uv", args: ["add", "--dev", tool] };
+  if (uv) return { command: "uv", args: ["tool", "install", tool] };
+  return { command: "python3", args: ["-m", "pip", "install", "--user", tool] };
+}
+
+export function req(command, args, reason, installCommand = null) {
+  return { name: command, command, args, reason, install: installCommand };
+}
+
+export function packageManager(entries = []) {
+  if (entries.includes("bun.lockb") || entries.includes("bun.lock")) return "bun";
+  if (entries.includes("pnpm-lock.yaml")) return "pnpm";
+  if (entries.includes("yarn.lock")) return "yarn";
+  return "npm";
+}
+
+export function installDev(pm, packages) {
+  if (pm === "bun") return { command: "bun", args: ["add", "-d", ...packages] };
+  if (pm === "pnpm") return { command: "pnpm", args: ["add", "-D", ...packages] };
+  if (pm === "yarn") return { command: "yarn", args: ["add", "-D", ...packages] };
+  return { command: "npm", args: ["install", "--save-dev", ...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;
+}
+
+export function run(command, args) {
+  return spawnSync(command, args, { stdio: "ignore", encoding: "utf8" });
+}
+
+function isCliEntry() {
+  return process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+}

package/skills/cairn-memory/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: cairn-memory
+description: Create and maintain repository MEMORY.md and docs/memory domain notes for token-efficient Codex, Claude Code, and Antigravity agent work.
+---
+
+# Cairn Memory
+
+Use this when domain knowledge, repository policy, or pre-plan context compression is needed.
+
+## Purpose
+
+The root `MEMORY.md` is an index, not detailed knowledge. Record details in `docs/memory/<domain>.md`.
+
+## Procedure
+
+1. Run `scripts/cairn-state.sh 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.
+   - `worker`: exact file paths, commands, schemas, references, and bounded evidence capture.
+4. Write detailed facts to `docs/memory/<domain>.md`.
+5. Keep only one-line links and summaries in `MEMORY.md`.
+6. Write user-visible output in the OS locale unless the user asks for another language.
+
+## Delegation Prompt Format
+
+```text
+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 NOT DO: Edit files. Ask the user. Guess missing names.
+CONTEXT: Current task, repository root, existing MEMORY.md entries.
+```
+
+## Completion Criteria
+
+- `MEMORY.md` links to detailed notes.
+- Detailed notes have clear scope and sources, and are shorter than reading the original files wholesale.
+- Long explanations are not duplicated in the root index.

package/skills/cairn-plan/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: cairn-plan
+description: Create decision-complete PLAN.md and docs/plan plans through agent delegation instead of user questions.
+---
+
+# Cairn Plan
+
+Use this when planning implementation, refactoring, migrations, debugging, or repository automation.
+
+## Purpose
+
+Plans must reduce execution tokens. Do not leave long plans only in chat. Store the topic in `PLAN.md` and details in `docs/plan/<topic>.md`.
+
+## Procedure
+
+1. Run `scripts/cairn-state.sh manual` if it exists. Otherwise ensure `MEMORY.md`, `PLAN.md`, `docs/memory`, and `docs/plan` directly.
+2. Read only `MEMORY.md` and relevant `docs/memory/*.md` files.
+3. Based on the active or assigned model, read `docs/model-guidance/README.md` and only the relevant model guidance.
+4. Run `scripts/cairn toolcheck` when available, or `scripts/cairn-toolcheck.mjs` directly, to identify repository stacks and required tools.
+5. If LSP, typecheck, lint, dry-run, or verification tools are missing, run `scripts/cairn toolcheck --install` or the closest repository-native install command before treating the tool as unavailable.
+6. Explore the repository with focused search and LSP/symbol tools after tool readiness is confirmed.
+7. Identify the closest available dry-run or check mode for every slice that can mutate external state.
+8. Run complexity triage before applying workflow guidance from agents, plugins, or delegated roles.
+9. Delegate according to the selected path and model guidance instead of asking the user.
+   - Use `explorer` for independent read-only codebase discovery, impact analysis, pattern searches, and read-only verification that can run in parallel when the current tool list supports it.
+   - Use `worker` for bounded implementation slices with clear file ownership, disjoint write scope, or verification tasks that can run while the main session continues.
+   - Keep urgent blocking work local when the next step depends immediately on the result.
+   - Tell workers they are not alone in the codebase and must not revert others' edits.
+10. Create `docs/plan/<topic>.md` from `templates/work-plan.md`.
+11. Add a short index entry to `PLAN.md`.
+12. Write user-visible output in the OS locale unless the user asks for another language.
+
+## Complexity Triage
+
+Decide triage from repository evidence without asking the user.
+
+This decision takes priority over plugin, agent, or delegated workflow guidance unless higher-priority system or developer instructions say otherwise. The default is Light Path; use Heavy Path only when a Heavy Path condition clearly applies.
+
+### Light Path
+
+Use Light Path for narrow changes inside existing architecture layers. Skip planning/review agents and implement directly or with one `worker`, but keep the verification gate.
+
+Light Path conditions:
+
+- The change stays inside existing architecture layers.
+- No new domain model, service class, or abstraction is introduced.
+- No security, authentication, authorization, session, external API, message queue, payment, DB schema, migration, concurrency, transaction-boundary, or cache-invalidation change is involved.
+
+Light Path examples:
+
+- One new API endpoint within existing layers.
+- Add or modify a controller or service method.
+- Strengthen validation rules.
+- Adjust query logic.
+- Change copy text or constants.
+- Fix one clearly scoped bug.
+
+Light Path flow: direct edit or single `worker` -> focused verification by the main agent or a scoped verification `worker` -> report. If there is no plan artifact, use the original user request and the diff as the verification baseline.
+
+### Heavy Path
+
+Use Heavy Path when the request clearly needs the full planning and review pipeline.
+
+Heavy Path conditions:
+
+- Creating a new directory, module, or architecture layer.
+- Introducing a new domain model, service class, or abstraction.
+- Changing security, authentication, authorization, or sessions.
+- Integrating an external API, message queue, or payment flow.
+- Changing DB schema or migrations.
+- Changing concurrency, transaction boundaries, or cache invalidation.
+- Refactoring across multiple domains.
+- The user signals extra care, such as "신중하게", "검토 받고", "설계부터", or "꼼꼼히".
+
+Heavy Path flow: plan -> pre-implementation review -> bounded `worker` implementation -> verification worker or read-only review.
+
+### Route Record
+
+`docs/plan/<topic>.md` must record:
+
+- Selected path.
+- Selection rationale.
+- Heavy Path conditions found, if any.
+- Roles or delegation omitted in Light Path and why.
+- Pre-implementation decisions that review must resolve in Heavy Path.
+
+## Planning Rules
+
+- Every plan must be decision-complete.
+- Every plan must include complexity triage and the selected path.
+- Every plan must include applied model guidance and rationale.
+- Every plan must include tool readiness results: detected stack, required LSP/check tools, installed tools, and blockers.
+- Every implementation slice must be small enough to verify with two checks.
+- The default checks are module acceptance verification and surface integration verification.
+- Every risky or external-state-changing slice must include the closest available dry-run or check command before the write/apply command.
+- Verification can expand for risk, but the reason must be recorded.
+- The default loop budget is two verification passes per slice. 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` instead of continuing an open-ended loop.
+- Ask the user only when agents, repository evidence, or local verification cannot answer the decision.
+- User-visible text must follow the OS locale unless the user asks for another language.
+
+## Tool Readiness Policy
+
+Do not skip LSP, typecheck, lint, dry-run, or verification because the tool is missing.
+
+- Detect the codebase stack from repository files before choosing tools.
+- Prefer repository-local installation through the existing package manager and lockfile.
+- Use ephemeral tool runners only when project-local installation is not appropriate.
+- Run the tool after installation and record the command result.
+- If installation is impossible, record the command tried, failure output summary, and blocker in `docs/plan/<topic>.md`.
+- Treat "LSP server not installed" as an unresolved blocker until installation or an equivalent symbol-aware fallback has been attempted.
+
+## Dry-Run Policy
+
+Prefer repository-native dry-run and check modes before mutating external state.
+
+- Migrations and database changes: `--pretend`, dry-run, schema diff, rollback feasibility check, or equivalent.
+- Package and release work: `npm pack --dry-run`, publish dry-run, build check, or equivalent.
+- Infrastructure and deployment: plan, diff, validate, check, or equivalent.
+- Code generation and formatting: check mode before write mode when available.
+- If no dry-run mode exists, record that fact and select the smallest reversible command or test artifact available.
+
+## Delegation Prompt Format
+
+```text
+TASK: Produce <role> input needed for the <topic> plan.
+EXPECTED OUTCOME: Return concrete decisions, file paths, dependencies, risks, and evidence requirements.
+REQUIRED TOOLS: Read-only repository exploration, tool readiness checks, LSP/symbol tools, local command checks.
+MUST DO: Preserve proper nouns exactly. Prefer repository evidence. Install or bootstrap missing required tools before declaring them unavailable. Identify assumptions. Use `explorer` for read-only discovery and `worker` for bounded implementation or verification when available and useful. Tell workers they are not alone in the codebase and must not revert others' edits. Use the OS locale for user-visible text.
+MUST NOT DO: Edit production code. Ask the user. Expand scope.
+CONTEXT: User request, MEMORY.md, relevant docs/memory notes, applied model guidance, repository root.
+```
+
+## Completion Criteria
+
+- `PLAN.md` references the plan topic.
+- `docs/plan/<topic>.md` includes goal, memory inputs, model guidance, tool readiness, complexity triage, selected path, agent assignments, module slices, and two checks per slice.
+- The next implementation task can run without making planning decisions.

package/skills/cairn-review/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: cairn-review
+description: Review completed Cairn slices against MEMORY.md, PLAN.md, domain policy, and two-gate evidence.
+---
+
+# Cairn Review
+
+Use this after meaningful implementation with Cairn.
+
+## Purpose
+
+Review is not another implementation loop. Confirm that the completed slice satisfies the plan and that memory and plan artifacts are useful to the next agent.
+
+## Procedure
+
+1. Read the completed slice in `docs/plan/<topic>.md`.
+2. Read `MEMORY.md` and relevant `docs/memory/*.md`.
+3. Check changed files, tool readiness evidence, and evidence paths.
+4. Delegate independent review when it materially improves speed or quality and the current tool policy allows it.
+   - Use `explorer` for read-only impact analysis, pattern checks, and independent diff inspection.
+   - Use `worker` for scoped verification command re-runs or QA artifact capture.
+   - Keep blocking review work local when the next step depends immediately on the result.
+5. Report findings first, ordered by severity, with file and line references. If there are no issues, say so clearly and record remaining test gaps or residual risk.
+6. Write user-visible output in the OS locale unless the user asks for another language.
+
+## Reviewer Prompt Format
+
+```text
+TASK: Review correctness, scope, and evidence for slice <slice-id>.
+EXPECTED OUTCOME: Findings ordered by severity with file and line references, or an explicit no-issue result with residual risk.
+REQUIRED TOOLS: Read-only diff inspection, tool readiness checks, verification command execution, plan/memory reading.
+MUST DO: Check tool readiness and install-attempt evidence. Check dry-run or check evidence when external state could change. Check both module evidence and surface evidence. Preserve proper nouns exactly. Use the OS locale for user-visible text.
+MUST NOT DO: Edit files. Ask the user. Approve skipped LSP/typecheck/lint without install evidence. Approve missing evidence or open-ended verification loops.
+CONTEXT: docs/plan/<topic>.md, MEMORY.md, relevant docs/memory notes, changed files.
+```
+
+## Completion Criteria
+
+- Findings are resolved or recorded as residual risk.
+- Tool readiness evidence is present for required LSP/check/verification tools.
+- Dry-run or check evidence is present when required, or the plan records why no dry-run exists.
+- Failed gates followed the bounded loop policy and did not continue past two verification passes without a recorded blocker.
+- Review evidence exists in `docs/plan/<topic>.md`.
+- The next agent can understand verification without rereading the full conversation.

package/skills/cairn-work/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: cairn-work
+description: Execute docs/plan module slices through bounded worker delegation and two verification gates.
+---
+
+# Cairn Work
+
+Use this to implement a plan created by `cairn-plan`.
+
+## Purpose
+
+Execute only one module slice at a time. Instead of a repeated red-green loop, prove a small slice with two strong verification gates.
+
+## Procedure
+
+1. Read `PLAN.md`, the selected `docs/plan/<topic>.md`, `MEMORY.md`, and relevant memory notes.
+2. Read the `docs/model-guidance/*.md` inputs recorded in the plan.
+3. Select the first incomplete module slice.
+4. Confirm that required LSP, typecheck, lint, dry-run, and verification tools are available from the plan's tool readiness section.
+5. If a required tool is missing, run `scripts/cairn toolcheck --install` or the closest repository-native install command, then rerun the tool before continuing.
+6. Confirm the selected Light Path or Heavy Path in the plan.
+7. For Light Path, implement directly or delegate to one bounded `worker`; keep the verification gate.
+8. For Heavy Path, follow the full planning and review pipeline recorded in the plan. Run pre-implementation review before mutation and read-only review after evidence exists.
+9. Delegate implementation to `worker` with exact files, ownership, constraints, and model-specific adjustment rules. Use `explorer` for parallel read-only discovery or verification when available and useful.
+10. Before mutating external state, run the slice dry-run or check command when one is recorded. If none exists, record the absence and continue with the smallest reversible command available.
+11. `worker` must return changed files, tool readiness result, dry-run or check result when applicable, module acceptance command and result, surface integration command or QA artifact, and cleanup notes.
+12. Re-run both verification gates directly.
+13. Apply the bounded loop policy when a gate fails.
+14. Record evidence in the plan file before marking the slice complete.
+15. Write user-visible output in the OS locale unless the user asks for another language.
+
+## Builder Prompt Format
+
+```text
+TASK: Implement slice <slice-id> for <topic>.
+EXPECTED OUTCOME: Minimal code or documentation change satisfying the slice contract.
+REQUIRED TOOLS: Scoped file editing, tool readiness checks, existing test/build commands, surface QA commands.
+MUST DO: Follow MEMORY.md policy. Stay within the listed file scope and ownership. Assume you are not alone in the codebase; do not revert others' edits. Install or bootstrap missing required tools before declaring them unavailable. Run dry-run or check mode before external-state mutation when available. Provide module evidence and surface evidence. Use the OS locale for user-visible text.
+MUST NOT DO: Ask the user. Skip LSP/typecheck/lint because a tool is missing without attempting installation. Refactor unrelated code. Continue an open-ended verification loop. Claim completion without evidence. Modify files outside the assigned ownership.
+CONTEXT: docs/plan/<topic>.md slice, relevant docs/memory notes, applied model guidance, exact files, verification commands.
+```
+
+## Tool Readiness Policy
+
+- Run the repository tool readiness command recorded in the plan before implementation.
+- If no command is recorded, run `scripts/cairn toolcheck` when available.
+- Missing LSP, typecheck, lint, dry-run, or verification tools must trigger a project-local or repository-native install attempt.
+- After installation, rerun the exact tool command and record evidence.
+- If installation fails, stop the slice and record the blocker rather than silently falling back to less precise exploration.
+
+## Two Verification Gates
+
+- Module acceptance: targeted unit, typecheck, lint, parser, schema, or command that proves the module contract.
+- Surface integration: HTTP, browser, CLI, tmux, desktop, or parsed artifact evidence proving behavior through the real surface.
+
+## Dry-Run Policy
+
+Run the closest available dry-run or check mode before commands that mutate external state.
+
+- Migrations and database changes: `--pretend`, dry-run, schema diff, rollback feasibility check, or equivalent.
+- Package and release work: `npm pack --dry-run`, publish dry-run, build check, or equivalent.
+- Infrastructure and deployment: plan, diff, validate, check, or equivalent.
+- Code generation and formatting: check mode before write mode when available.
+- If no dry-run mode exists, record that fact in `docs/plan/<topic>.md` before continuing.
+
+## Bounded Loop Policy
+
+- Run at most two verification passes per slice by default.
+- If a gate fails, diagnose the cause once, shrink or split the slice, then rerun both gates.
+- After two failed passes, stop implementation for the slice and record the blocker in `docs/plan/<topic>.md`.
+- Do not imitate repeated red-green loops unless the plan explicitly records a risk-based reason.
+
+## Completion Criteria
+
+- Both verification gates passed in the current turn.
+- Required LSP/check/verification tools were available, installed, or recorded as blockers with attempted commands.
+- Dry-run or check evidence exists when the slice could mutate external state, or the plan records why no dry-run exists.
+- The required Light Path or Heavy Path flow was followed.
+- The model guidance recorded in the plan was applied.
+- Evidence was recorded in `docs/plan/<topic>.md`.
+- `PLAN.md` status was updated only after evidence existed.

package/templates/MEMORY.md

@@ -0,0 +1,14 @@
+# MEMORY
+
+Short index of persistent repository knowledge. Link detailed notes under `docs/memory/`.
+
+## Domain Knowledge
+
+- `docs/memory/<domain>.md`: short description.
+
+## Policy
+
+- Preserve proper nouns exactly as written.
+- Prefer repository evidence over assumptions.
+- Read only the detailed memory needed for the current task.
+- Write user-visible output in the OS locale unless the user asks for another language.

package/templates/PLAN.md

@@ -0,0 +1,17 @@
+# PLAN
+
+Short index of work plans. Link detailed plans under `docs/plan/`.
+
+## Planning Rules
+
+- Detect repository stack and required LSP/check tools before implementation.
+- Install or bootstrap missing required tools before declaring them unavailable.
+- Record tool readiness, dry-run/check evidence, module acceptance evidence, and surface integration evidence in detailed plans.
+
+## Active Plans
+
+- `docs/plan/<topic>.md`: short status.
+
+## Completed Plans
+
+- `docs/plan/<topic>.md`: evidence summary.