cairn-ai 0.1.2

package/README.pt.md

@@ -0,0 +1,130 @@
+# Cairn
+
+Cairn e um plugin de harness multiagente eficiente em tokens para Codex, Claude Code e Antigravity.
+
+[English](README.md)
+
+A ideia central e manter comportamentos uteis de agent harness: hooks, estado persistente, planejamento explicito, delegacao focada e guardas no momento de parada. Cairn nao torna loops repetidos de verificacao TDD o padrao. Em vez disso, divide o trabalho em pequenos module slices e prova cada slice com dois verification gates.
+
+1. Module acceptance verification: prova o contrato do modulo alterado.
+2. Surface integration verification: prova o comportamento por uma superficie real, como CLI, HTTP, navegador ou artefatos de arquivo.
+
+Antes que um slice altere estado externo, Cairn registra e executa o dry-run ou check mode mais proximo disponivel. A verificacao e limitada: cada slice recebe duas verification passes por padrao; depois, o agente registra um blocker ou divide o slice em vez de continuar um loop aberto.
+
+Cairn tambem trata tool readiness como parte do trabalho. LSP, typecheck, lint, dry-run e verification tools sao verificados contra o stack do repositorio. Se uma ferramenta obrigatoria estiver ausente, Cairn tenta uma instalacao project-local ou repository-native antes de aceitar um fallback.
+
+## LazyCodex Attribution
+
+Cairn e influenciado pelo LazyCodex (`https://github.com/code-yeongyu/lazycodex`). As ideias aproveitadas sao o formato de agent harness instalavel, Codex hook trust/setup handling, project memory, planning skills, executable workflow commands, diagnostics e skill/agent packaging entre local agent surfaces.
+
+Cairn diverge intencionalmente do LazyCodex na execution policy. Ele nao adota o role-chain execution model nem open-ended completion loops do LazyCodex. Cairn usa Light/Heavy Path triage, delegacao limitada `explorer`/`worker`, dois verification gates e explicit stop conditions.
+
+## Complexity Triage
+
+Cada implementation task passa primeiro por complexity triage, antes de aplicar agent, plugin ou delegated workflow guidance. O triage e decidido a partir da exploracao do repositorio, do escopo esperado da mudanca e de sinais de risco, sem perguntar ao usuario por fatos descobriveis.
+
+- Light Path: mudancas estreitas dentro de existing architecture layers. E o padrao. Implemente diretamente ou use um `worker` limitado, depois mantenha o verification gate.
+- Heavy Path: new directory/module/layer, new domain model/service/abstraction, security/session/auth, external API/message queue/payment, DB schema/migration, concurrency/transaction/cache changes, cross-domain refactor ou explicit extra-care request.
+
+O path escolhido e sua justificativa sao registrados em `docs/plan/<topic>.md` quando houver um plan artifact. Mesmo no Light Path, os dois verification gates permanecem.
+
+## Tool Readiness
+
+`cairn toolcheck` inspeciona o repositorio atual para stacks JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go e Rust, depois verifica os LSP e verification tools correspondentes.
+
+```sh
+cairn toolcheck
+cairn toolcheck --install
+```
+
+- `toolcheck` informa detected stacks e missing tools.
+- `toolcheck --install` tenta o caminho de instalacao project-local ou repository-native mais proximo, como dev dependencies do package manager, dev dependencies do Composer, `uv`, Java LSP bootstrap, `go install` ou `rustup component add`.
+- Os planos Cairn registram detected stack, required tools, install commands e blockers.
+- Um LSP server ausente nao e motivo valido para pular precise codebase exploration antes de tentar installation ou um fallback symbol-aware equivalente.
+
+## Dry-Run And Loop Policy
+
+- Migrations e database changes usam `--pretend`, dry-run, schema diff, rollback feasibility checks ou o equivalente repository-native mais proximo antes de write/apply commands.
+- Package, release, infrastructure, deployment, code generation e formatting work usam check, plan, diff, validate ou dry-run modes antes de alterar estado quando disponiveis.
+- Se nao houver dry-run, o plan registra esse fato e escolhe o menor command reversivel ou test artifact disponivel.
+- Se um verification gate falhar, Cairn diagnostica uma vez, reduz ou divide o slice e executa novamente os dois gates.
+- Depois de duas verification passes falhas para o mesmo slice, Cairn registra o blocker em `docs/plan/<topic>.md` em vez de continuar um loop repetido.
+
+## Model Guidance
+
+Cairn aplica model-specific adjustment apenas a modelos Claude-family e Codex-family.
+
+- Claude-family: util para long context, policy interpretation e plan/evidence review.
+- Codex-family: util para small implementation slices, explicit file edits, command-based verification e bounded `worker` tasks.
+
+A orientacao detalhada fica em `docs/model-guidance/README.md`, `docs/model-guidance/claude.md` e `docs/model-guidance/codex.md`.
+
+## Repository Artifacts
+
+O harness cria e mantem estes arquivos na raiz do repositorio alvo.
+
+- `MEMORY.md`: indice curto de persistent domain knowledge.
+- `docs/memory/*.md`: conhecimento detalhado por dominio.
+- `docs/model-guidance/*.md`: Claude and Codex model adjustment guidance.
+- `PLAN.md`: indice curto de active and completed work topics.
+- `docs/plan/*.md`: detailed execution plans.
+
+Arquivos raiz ficam curtos e os detalhes vao para `docs/`, para que agentes leiam apenas o contexto necessario.
+
+## Commands
+
+O pacote publicado pode ser executado com `bunx` ou comandos `cairn` instalados globalmente.
+
+```sh
+bunx cairn-ai@latest install
+bunx cairn-ai@latest upgrade
+bunx cairn-ai@latest doctor
+bunx cairn-ai@latest uninstall
+bunx cairn-ai@latest toolcheck
+```
+
+Apos a instalacao global, comandos curtos tambem ficam disponiveis.
+
+```sh
+bun add -g cairn-ai
+cairn install
+cairn upgrade
+cairn doctor
+cairn uninstall
+cairn toolcheck
+```
+
+- `cairn install`: instala o plugin no Codex marketplace cache e configura hook trust state, Claude Code mirror files e Antigravity skills/workflows.
+- `cairn upgrade`: atualiza installation, hook trust state, Claude Code mirror files e Antigravity skills/workflows a partir da source atual.
+- `cairn doctor`: diagnostica Codex settings, installation, hook trust state, Claude Code mirror files e Antigravity mirror files.
+- `cairn uninstall`: remove Codex settings, cache, Claude Code mirror files e Antigravity mirror files adicionados pelo Cairn.
+- `cairn toolcheck`: detecta repository stacks e verifica ou instala required LSP e verification tools.
+- `cairn-memory`: explora domain knowledge e atualiza `MEMORY.md`.
+- `cairn-plan`: cria um decision-complete plan em `docs/plan/`.
+- `cairn-work`: executa o proximo module slice no `PLAN.md` atual com dois verification gates.
+- `cairn-review`: revisa completed slices contra plan, memory e evidence.
+
+`install` e `upgrade` criam backups `*.cairn-backup-*` antes de modificar `~/.codex/config.toml`. O source plugin manifest permanece validator-friendly; apenas a installed cache copy recebe um campo `hooks` para ativar Codex hooks.
+
+Codex usa `skills/` e `commands/`. Claude Code usa comandos espelhados e agent definitions em `.claude/`. Antigravity usa `.agents/workflows` e global skills mirrors.
+
+## Antigravity Compatibility
+
+Antigravity suporta Agent Skills e Workflows baseados em `SKILL.md` chamados como `/workflow-name`. Cairn instala estes paths para essa superficie.
+
+- Antigravity IDE: `~/.agents/skills/cairn-*`, `~/.agents/workflows/cairn-*.md`.
+- Antigravity CLI: `~/.gemini/antigravity-cli/skills/cairn-*`, `~/.gemini/antigravity-cli/workflows/cairn-*.md`.
+
+Codex-only hooks nao sao portados para Antigravity. Em vez disso, os mesmos procedimentos de planning, memory, complexity triage e two-gate verification rodam por Skills e Workflows. Defina `ANTIGRAVITY_HOME` ou `ANTIGRAVITY_CLI_HOME` para sobrescrever paths.
+
+## Locale Policy
+
+As instrucoes reutilizaveis do Cairn sao escritas em English para global use. User-visible output deve seguir o OS locale configurado, a menos que o usuario peca explicitamente outro idioma. A CLI localiza mensagens comuns para `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` e `pt`, e volta para English em unsupported locales. O texto `statusMessage` dos Codex hooks permanece static English, enquanto hook command output e English ou Korean.
+
+## Delegation
+
+- `explorer`: lida com read-only codebase discovery, impact analysis, pattern searches e read-only verification quando disponivel.
+- `worker`: lida com bounded implementation ou verification tasks com file ownership claro.
+- Main session: mantem urgent blocking work local quando o proximo passo depende imediatamente do resultado.
+
+Todo delegation prompt usa seis sections: TASK, EXPECTED OUTCOME, REQUIRED TOOLS, MUST DO, MUST NOT DO, CONTEXT.

package/README.zh.md

@@ -0,0 +1,130 @@
+# Cairn
+
+Cairn 是面向 Codex、Claude Code 和 Antigravity 的高 token 效率 multi-agent harness plugin。
+
+[English](README.md)
+
+Cairn 的核心思路是保留有用的 agent harness 行为：hooks、persistent state、explicit planning、focused delegation 和 stop-time guards。Cairn 不把重复的 TDD verification loops 作为默认流程，而是把工作拆成小的 module slices，并用两个 verification gates 证明每个 slice。
+
+1. Module acceptance verification: 证明被修改的 module contract。
+2. Surface integration verification: 通过 CLI、HTTP、browser 或 file artifacts 等真实 surface 证明行为。
+
+在 slice 修改外部状态之前，Cairn 会记录并运行最接近的 dry-run 或 check mode。verification 是有边界的：默认每个 slice 有两次 verification pass，然后 agent 会记录 blocker 或拆分 slice，而不是继续开放式循环。
+
+Cairn 也把 tool readiness 视为工作的一部分。它会根据 repository stack 检查 LSP、typecheck、lint、dry-run 和 verification tools。如果缺少必要工具，Cairn 会先尝试 project-local 或 repository-native installation，再接受 fallback。
+
+## LazyCodex Attribution
+
+Cairn 受到 LazyCodex（`https://github.com/code-yeongyu/lazycodex`）影响。受影响的部分包括 installable agent-harness shape、Codex hook trust/setup handling、project memory、planning skills、executable workflow commands、diagnostics，以及跨 local agent surfaces 的 skill/agent packaging。
+
+Cairn 在 execution policy 上刻意不同于 LazyCodex。它不采用 LazyCodex 的 role-chain execution model 或 open-ended completion loop。Cairn 使用 Light/Heavy Path triage、bounded `explorer`/`worker` delegation、两个 verification gates 和 explicit stop conditions。
+
+## Complexity Triage
+
+每个 implementation task 都先经过 complexity triage，然后才应用 agent、plugin 或 delegated workflow guidance。triage 根据 repository exploration、expected change scope 和 risk signals 判断，不向用户询问可发现的信息。
+
+- Light Path: existing architecture layers 内的窄范围修改。这是默认路径。可以直接实现，或使用一个 bounded `worker`，然后保留 verification gate。
+- Heavy Path: new directory/module/layer、new domain model/service/abstraction、security/session/auth、external API/message queue/payment、DB schema/migration、concurrency/transaction/cache changes、cross-domain refactor，或明确的 extra-care request。
+
+选中的 path 和理由会在存在 plan artifact 时记录在 `docs/plan/<topic>.md`。即使是 Light Path，也保留两个 verification gates。
+
+## Tool Readiness
+
+`cairn toolcheck` 会检查当前 repository 中的 JavaScript、TypeScript、Python、PHP、Java、Kotlin、Swift、Go 和 Rust stacks，然后检查匹配的 LSP 和 verification tools。
+
+```sh
+cairn toolcheck
+cairn toolcheck --install
+```
+
+- `toolcheck` 报告 detected stacks 和 missing tools。
+- `toolcheck --install` 尝试最接近的 project-local 或 repository-native install path，例如 package-manager dev dependencies、Composer dev dependencies、`uv`、Java LSP bootstrap、`go install` 或 `rustup component add`。
+- Cairn plans 会记录 detected stack、required tools、install commands 和 blockers。
+- 缺少 LSP server 不能作为跳过 precise codebase exploration 的理由，除非已尝试 installation 或等价的 symbol-aware fallback。
+
+## Dry-Run And Loop Policy
+
+- Migrations 和 database changes 在 write/apply commands 前使用 `--pretend`、dry-run、schema diff、rollback feasibility checks 或最接近的 repository-native equivalent。
+- Package、release、infrastructure、deployment、code generation 和 formatting work 在可用时，先使用 check、plan、diff、validate 或 dry-run modes，再修改状态。
+- 如果没有 dry-run，plan 会记录该事实，并选择最小且可逆的 command 或 test artifact。
+- 如果 verification gate 失败，Cairn 会诊断一次，缩小或拆分 slice，然后重新运行两个 gates。
+- 同一 slice 两次 verification pass 失败后，Cairn 会在 `docs/plan/<topic>.md` 中记录 blocker，而不是继续重复循环。
+
+## Model Guidance
+
+Cairn 只对 Claude-family 和 Codex-family models 应用 model-specific adjustment。
+
+- Claude-family: 适合 long context、policy interpretation 和 plan/evidence review。
+- Codex-family: 适合 small implementation slices、explicit file edits、command-based verification 和 bounded `worker` tasks。
+
+详细指南位于 `docs/model-guidance/README.md`、`docs/model-guidance/claude.md` 和 `docs/model-guidance/codex.md`。
+
+## Repository Artifacts
+
+harness 会在目标 repository root 创建并维护这些文件。
+
+- `MEMORY.md`: persistent domain knowledge 的短索引。
+- `docs/memory/*.md`: 按 domain 记录的详细 knowledge。
+- `docs/model-guidance/*.md`: Claude 和 Codex model adjustment guidance。
+- `PLAN.md`: active 和 completed work topics 的短索引。
+- `docs/plan/*.md`: detailed execution plans。
+
+root files 保持简短，细节移到 `docs/` 下，让 agents 只读取当前任务需要的 context。
+
+## Commands
+
+发布后的 package 可以通过 `bunx` 或全局安装的 `cairn` commands 执行。
+
+```sh
+bunx cairn-ai@latest install
+bunx cairn-ai@latest upgrade
+bunx cairn-ai@latest doctor
+bunx cairn-ai@latest uninstall
+bunx cairn-ai@latest toolcheck
+```
+
+全局安装后也可以使用短命令。
+
+```sh
+bun add -g cairn-ai
+cairn install
+cairn upgrade
+cairn doctor
+cairn uninstall
+cairn toolcheck
+```
+
+- `cairn install`: 将 plugin 安装到 Codex marketplace cache，并配置 hook trust state、Claude Code mirror files 和 Antigravity skills/workflows。
+- `cairn upgrade`: 从当前 source 更新 installation、hook trust state、Claude Code mirror files 和 Antigravity skills/workflows。
+- `cairn doctor`: 诊断 Codex settings、installation、hook trust state、Claude Code mirror files 和 Antigravity mirror files。
+- `cairn uninstall`: 移除 Cairn 添加的 Codex settings、cache、Claude Code mirror files 和 Antigravity mirror files。
+- `cairn toolcheck`: 检测 repository stacks，并检查或安装 required LSP 和 verification tools。
+- `cairn-memory`: 探索 domain knowledge 并更新 `MEMORY.md`。
+- `cairn-plan`: 在 `docs/plan/` 下创建 decision-complete plan。
+- `cairn-work`: 执行当前 `PLAN.md` 中的下一个 module slice，并收集两个 verification gates。
+- `cairn-review`: 根据 plan、memory 和 evidence review completed slices。
+
+`install` 和 `upgrade` 在修改 `~/.codex/config.toml` 前会创建 `*.cairn-backup-*` backups。source plugin manifest 保持 validator-friendly；只有 installed cache copy 会添加启用 Codex hooks 的 `hooks` field。
+
+Codex 使用 `skills/` 和 `commands/`。Claude Code 使用 `.claude/` 下的 mirrored commands 和 agent definitions。Antigravity 使用 `.agents/workflows` 和 global skills mirrors。
+
+## Antigravity Compatibility
+
+Antigravity 支持通过 `/workflow-name` 调用的 `SKILL.md` based Agent Skills and Workflows。Cairn 会为该 surface 安装这些 paths。
+
+- Antigravity IDE: `~/.agents/skills/cairn-*`, `~/.agents/workflows/cairn-*.md`.
+- Antigravity CLI: `~/.gemini/antigravity-cli/skills/cairn-*`, `~/.gemini/antigravity-cli/workflows/cairn-*.md`.
+
+Codex-only hooks 不会移植到 Antigravity。相同的 planning、memory、complexity triage 和 two-gate verification procedures 会通过 Skills 和 Workflows 运行。设置 `ANTIGRAVITY_HOME` 或 `ANTIGRAVITY_CLI_HOME` 可以覆盖 paths。
+
+## Locale Policy
+
+Cairn 的 reusable instructions 为了 global use 使用英文编写。除非用户明确要求其他语言，user-visible output 应遵循 configured OS locale。CLI 会本地化 `en`、`ko`、`ja`、`zh`、`es`、`fr`、`de` 和 `pt` 的 common messages，不支持的 locales fallback 到 English。Codex hook `statusMessage` text 保持 static English，而 hook command output 为 English 或 Korean。
+
+## Delegation
+
+- `explorer`: 可用时处理 read-only codebase discovery、impact analysis、pattern search 和 read-only verification。
+- `worker`: 处理具有明确 file ownership 的 bounded implementation 或 verification task。
+- Main session: 当下一步立即依赖结果时，本地处理 urgent blocking work。
+
+每个 delegation prompt 都使用六个 sections: TASK、EXPECTED OUTCOME、REQUIRED TOOLS、MUST DO、MUST NOT DO、CONTEXT。

package/agents/explorer.md

@@ -0,0 +1,31 @@
+---
+name: explorer
+description: Read-only discovery agent for codebase questions, impact analysis, pattern search, and verification.
+model: sonnet
+tools: Read, Grep, Glob, Bash
+---
+
+# explorer
+
+Handle read-only discovery and verification tasks.
+
+Use for:
+
+- Codebase questions.
+- Impact analysis.
+- Pattern searches.
+- Exact file and symbol discovery.
+- Read-only verification that can run independently.
+
+Do not edit files. Do not ask the user before exhausting repository evidence. Preserve proper nouns exactly as written. Report only important paths, commands, and outputs accurately.
+
+Use this prompt format:
+
+```text
+TASK:
+EXPECTED OUTCOME:
+REQUIRED TOOLS:
+MUST DO:
+MUST NOT DO:
+CONTEXT:
+```

package/agents/worker.md

@@ -0,0 +1,32 @@
+---
+name: worker
+description: Focused execution agent for repository search, small edits, command checks, and QA artifacts.
+model: sonnet
+tools: Read, Grep, Glob, Bash, Write, Edit, MultiEdit
+---
+
+# worker
+
+Handle narrow, focused tasks.
+
+Use for:
+
+- Finding exact files and symbols.
+- Checking and bootstrapping LSP, typecheck, lint, dry-run, and verification tools.
+- Small mechanical edits.
+- Checking command availability.
+- Capturing evidence artifacts.
+- Cleanup verification.
+
+Do not make architecture decisions. Do not ask the user. Do not treat a missing tool as unavailable until install or bootstrap has been attempted. Report only important paths, commands, and outputs accurately.
+
+Use this prompt format:
+
+```text
+TASK:
+EXPECTED OUTCOME:
+REQUIRED TOOLS:
+MUST DO:
+MUST NOT DO:
+CONTEXT:
+```

package/commands/cairn-doctor.md

@@ -0,0 +1,27 @@
+# cairn-doctor
+
+Goal: diagnose Cairn installation status.
+
+Run:
+
+```sh
+scripts/cairn doctor
+```
+
+With the published package:
+
+```sh
+bunx cairn-ai@latest doctor
+```
+
+Checks:
+
+- Source plugin manifest.
+- Codex cached installation.
+- Marketplace file.
+- Hook manifest link in the installed copy.
+- `features.plugins`, `features.plugin_hooks`.
+- `cairn@cairn` plugin enabled.
+- hook trust state.
+- Claude Code commands and agents mirror files.
+- Antigravity IDE/CLI skills and workflows mirror files.

package/commands/cairn-install.md

@@ -0,0 +1,24 @@
+# cairn-install
+
+Goal: install Cairn into Codex, Claude Code, and Antigravity.
+
+Run:
+
+```sh
+scripts/cairn install
+```
+
+With the published package:
+
+```sh
+bunx cairn-ai@latest install
+```
+
+Actions:
+
+- Copy the Cairn installation into the Codex marketplace cache.
+- Add the `hooks/hooks.json` link to the installed manifest.
+- Register marketplace, plugin, and hook trust state in `~/.codex/config.toml`.
+- Install `cairn-*` commands and agents mirror files for Claude Code.
+- Install `cairn-*` skills and workflows mirror files for Antigravity IDE/CLI.
+- Create `*.cairn-backup-*` backups before changing settings.

package/commands/cairn-memory.md

@@ -0,0 +1,17 @@
+# cairn-memory
+
+Use the `cairn-memory` skill.
+
+Prerequisite: if `scripts/cairn doctor` fails, restore installation with `scripts/cairn install` or `scripts/cairn upgrade`.
+
+Goal: create or update repository memory without asking the user for discoverable facts.
+
+Procedure:
+
+1. Run the plugin state initialization script.
+2. Read `MEMORY.md`.
+3. Explore repository facts with focused tools.
+4. Use `explorer` for read-only domain discovery and contradiction checks when available; use `worker` for exact references, command checks, and bounded evidence capture.
+5. Write details to `docs/memory/<domain>.md`.
+6. Keep `MEMORY.md` as a short index.
+7. Use the OS locale for user-visible output unless the user asks for another language.

package/commands/cairn-plan.md

@@ -0,0 +1,23 @@
+# cairn-plan
+
+Use the `cairn-plan` skill.
+
+Prerequisite: if `scripts/cairn doctor` fails, restore installation with `scripts/cairn install` or `scripts/cairn upgrade`.
+
+Goal: leave a decision-complete plan for the current task in files.
+
+Procedure:
+
+1. Read `MEMORY.md` and relevant `docs/memory/*.md`.
+2. If the active or assigned model is Claude-family, read `docs/model-guidance/claude.md`; if Codex-family, read `docs/model-guidance/codex.md`.
+3. Run `scripts/cairn toolcheck` when available.
+4. If required LSP/check tools are missing, run `scripts/cairn toolcheck --install` or a repository-native install command before accepting a fallback.
+5. Explore before asking the user.
+6. Run complexity triage before applying agent, plugin, or delegated workflow guidance.
+7. Use Light Path by default unless a Heavy Path condition clearly applies.
+8. Use `explorer` for independent read-only discovery, impact analysis, pattern search, and read-only verification when available.
+9. Use `worker` for bounded implementation or verification tasks with clear file ownership. Keep urgent blocking work local.
+10. Write `docs/plan/<topic>.md`.
+11. Add the topic link and status to `PLAN.md`.
+12. Put tool readiness, module acceptance verification, and surface integration verification on every module slice.
+13. Use the OS locale for user-visible output unless the user asks for another language.

package/commands/cairn-review.md

@@ -0,0 +1,16 @@
+# cairn-review
+
+Use the `cairn-review` skill.
+
+Prerequisite: if `scripts/cairn doctor` fails, restore installation with `scripts/cairn install` or `scripts/cairn upgrade`.
+
+Goal: review completed work against plan, memory, policy, and evidence.
+
+Procedure:
+
+1. Read the plan slice and memory inputs.
+2. Check changed files, tool readiness evidence, and verification evidence.
+3. Delegate independent read-only review to `explorer` when it materially improves speed or quality; use `worker` only for scoped verification reruns or QA artifacts.
+4. Report findings first, ordered by severity, with file and line references. If no issues are found, say so clearly and mention remaining test gaps or residual risk.
+5. Record review evidence in `docs/plan/<topic>.md`.
+6. Use the OS locale for user-visible output unless the user asks for another language.

package/commands/cairn-toolcheck.md

@@ -0,0 +1,19 @@
+# cairn-toolcheck
+
+Goal: detect repository stacks and check required LSP, typecheck, lint, dry-run, and verification tools.
+
+From a globally installed package:
+
+```sh
+bunx cairn-ai@latest toolcheck
+bunx cairn-ai@latest toolcheck --install
+```
+
+From this repository:
+
+```sh
+scripts/cairn toolcheck
+scripts/cairn toolcheck --install
+```
+
+Use `--install` when a required tool is missing. Record detected stacks, missing tools, install attempts, and blockers in the related `docs/plan/<topic>.md`.

package/commands/cairn-uninstall.md

@@ -0,0 +1,24 @@
+# cairn-uninstall
+
+Goal: remove the Codex, Claude Code, and Antigravity entries installed by Cairn.
+
+Run:
+
+```sh
+scripts/cairn uninstall
+```
+
+With the published package:
+
+```sh
+bunx cairn-ai@latest uninstall
+```
+
+Removed items:
+
+- Cairn marketplace, plugin, and hook trust state blocks in `~/.codex/config.toml`.
+- `~/.codex/plugins/cache/cairn`.
+- Claude Code `cairn-*` commands and agents mirror files.
+- Antigravity IDE/CLI `cairn-*` skills and workflows mirror files.
+
+The source work folder is not deleted.

package/commands/cairn-upgrade.md

@@ -0,0 +1,23 @@
+# cairn-upgrade
+
+Goal: update the Cairn installation from the current source.
+
+Run:
+
+```sh
+scripts/cairn upgrade
+```
+
+With the published package:
+
+```sh
+bunx cairn-ai@latest upgrade
+```
+
+Actions:
+
+- Replace the Cairn installation in the Codex cache.
+- Recompute hook trust state and update settings.
+- Overwrite Claude Code mirror files with the latest content.
+- Overwrite Antigravity IDE/CLI skills and workflows mirror files with the latest content.
+- Create `*.cairn-backup-*` backups before changing settings.

package/commands/cairn-work.md

@@ -0,0 +1,22 @@
+# cairn-work
+
+Use the `cairn-work` skill.
+
+Prerequisite: if `scripts/cairn doctor` fails, restore installation with `scripts/cairn install` or `scripts/cairn upgrade`.
+
+Goal: execute the next incomplete module slice in `PLAN.md`.
+
+Procedure:
+
+1. Read `PLAN.md`, the detailed plan, `MEMORY.md`, and relevant memory notes.
+2. Read the Codex or Claude model guidance recorded in the plan.
+3. Select one small module slice.
+4. Confirm required tool readiness. If a required LSP/check tool is missing, run `scripts/cairn toolcheck --install` or a repository-native install command before accepting a fallback.
+5. Confirm the complexity triage and selected Light/Heavy Path recorded in the plan.
+6. For Light Path, implement directly or use one bounded `worker`, then run focused verification.
+7. For Heavy Path, follow the plan's staged implementation and review gates without role-mapping shortcuts.
+8. When delegating implementation to `worker`, state the file ownership clearly and tell the worker not to revert others' edits.
+9. Re-run module acceptance verification.
+10. Re-run surface integration verification.
+11. Record tool readiness and verification evidence in `docs/plan/<topic>.md` and update `PLAN.md`.
+12. Use the OS locale for user-visible output unless the user asks for another language.

package/docs/model-guidance/README.md

@@ -0,0 +1,31 @@
+# Model Guidance
+
+Cairn only applies model-specific adjustment to Claude-family and Codex-family models.
+
+The goal is not to make prompts long by model. The goal is to stabilize the same `MEMORY.md`/`PLAN.md` flow according to model strengths.
+
+## Application Order
+
+1. Identify the active model name. If the model name is not directly exposed, infer it from the user's default model setting and agent role frontmatter.
+2. For Claude-family models, apply `docs/model-guidance/claude.md`.
+3. For Codex-family models, apply `docs/model-guidance/codex.md`.
+4. If the model is not clearly classified, apply only the common rules and skip model-specific adjustment.
+
+## Common Rules
+
+- Keep root `MEMORY.md` and `PLAN.md` as indexes only.
+- Keep detailed judgment in `docs/memory/`, `docs/plan/`, and `docs/model-guidance/`.
+- Preserve proper nouns, file names, variable names, service names, alert names, MCP tool names, and agent names exactly as written.
+- Select Light Path or Heavy Path before implementation.
+- Detect required LSP, typecheck, lint, dry-run, and verification tools before implementation.
+- Missing required tools must trigger a project-local, repository-native, or ephemeral install attempt before they can be treated as unavailable.
+- Every implementation slice must pass module acceptance verification and surface integration verification.
+- Before mutating external state, run the closest available dry-run, check, plan, diff, validate, or equivalent command.
+- Limit each slice to two verification passes by default. After two failed passes, record the blocker or split the slice instead of continuing a repeated loop.
+- User-visible output must follow the OS locale unless the user asks for another language.
+
+## Delegation Defaults
+
+- `explorer`: use for read-only codebase discovery, impact analysis, pattern searches, and read-only verification when available.
+- `worker`: use for bounded implementation or verification tasks with clear file ownership.
+- Main session: keep urgent blocking work local when the next step depends immediately on the result.

package/docs/model-guidance/claude.md

@@ -0,0 +1,46 @@
+# Claude Model Guidance
+
+Claude-family models are strong at long-context retention, policy interpretation, and plan consistency review. In Cairn, use those strengths for planning, policy interpretation, and evidence review.
+
+## Use Strengths
+
+- Read policies across multiple documents and summarize conflicts.
+- Judge domain boundaries, risk, rollback ability, and user impact.
+- Check whether required LSP, typecheck, lint, dry-run, and verification tools were discovered and bootstrapped.
+- Check whether `docs/plan/<topic>.md` is decision-complete.
+- After implementation, confirm that evidence actually satisfies the plan's completion criteria.
+
+## Adjustment Rules
+
+- Do not bloat plans with long explanations. Keep decisions, rationale, and evidence.
+- Preserve frequency words such as "all", "each", and "required". Do not handle only the first item and stop.
+- Do not accept "tool missing" as a reason to skip precise codebase exploration until install or bootstrap has been attempted.
+- Do not skip the two verification gates even on Light Path.
+- Do not approve a plan that lacks dry-run or check evidence for external-state-changing work.
+- Do not allow open-ended verification loops. Require a blocker or slice split after two failed passes.
+- On Heavy Path, check plan gaps before implementation.
+- Before asking the user, use repository evidence and available `explorer`/`worker` delegation when it materially improves speed or quality.
+- Write user-visible output in the OS locale unless the user asks for another language.
+
+## Path Guidance
+
+### Policy And Risk
+
+- Summarize domain boundaries and risk from repository evidence.
+- If policy is unclear, propose candidates to record in `docs/memory/<domain>.md`.
+- Clearly name risk signals that require Heavy Path.
+
+### Planning
+
+- Keep the plan short and executable.
+- Always record complexity triage and the selected Light/Heavy Path.
+- Always record tool readiness and blockers.
+- Each module slice must include files, contract, dry-run or check command when applicable, module acceptance verification, and surface integration verification.
+
+### Review
+
+- Lead with findings.
+- Do not approve without evidence.
+- Check that missing tools have install-attempt evidence before approving a fallback.
+- Check that dry-run or check evidence exists when external state could change.
+- Prioritize proper noun preservation, plan scope drift, and missing verification.