cairn-ai 0.1.2

package/.agents/workflows/cairn-doctor.md

@@ -0,0 +1,22 @@
+# cairn-doctor
+
+Goal: diagnose Cairn installation status.
+
+Run:
+
+```sh
+bunx cairn-ai@latest doctor
+```
+
+When running from local source:
+
+```sh
+scripts/cairn doctor
+```
+
+Checks:
+
+- Codex plugin, marketplace, hook trust state.
+- Claude Code commands and agents mirror files.
+- Antigravity skills and workflows mirror files.
+- Antigravity CLI skills and workflows mirror files.

package/.agents/workflows/cairn-install.md

@@ -0,0 +1,17 @@
+# cairn-install
+
+Goal: install Cairn into Codex, Claude Code, and Antigravity.
+
+Run:
+
+```sh
+bunx cairn-ai@latest install
+```
+
+When running from local source:
+
+```sh
+scripts/cairn install
+```
+
+After installation, check status with the `cairn-doctor` workflow.

package/.agents/workflows/cairn-memory.md

@@ -0,0 +1,15 @@
+# cairn-memory
+
+Use the `cairn-memory` skill.
+
+Goal: create or update repository memory without asking the user for discoverable facts.
+
+Procedure:
+
+1. Ensure `MEMORY.md`, `PLAN.md`, `docs/memory`, and `docs/plan`.
+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/.agents/workflows/cairn-plan.md

@@ -0,0 +1,21 @@
+# cairn-plan
+
+Use the `cairn-plan` skill.
+
+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/.agents/workflows/cairn-review.md

@@ -0,0 +1,14 @@
+# cairn-review
+
+Use the `cairn-review` skill.
+
+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/.agents/workflows/cairn-toolcheck.md

@@ -0,0 +1,17 @@
+# cairn-toolcheck
+
+Goal: detect repository stacks and check required LSP, typecheck, lint, dry-run, and verification tools.
+
+Run the local command first:
+
+```sh
+scripts/cairn toolcheck
+```
+
+If required tools are missing, attempt repository-native installation:
+
+```sh
+scripts/cairn toolcheck --install
+```
+
+Record detected stacks, missing tools, install attempts, and blockers in the related `docs/plan/<topic>.md`.

package/.agents/workflows/cairn-uninstall.md

@@ -0,0 +1,17 @@
+# cairn-uninstall
+
+Goal: remove the Codex, Claude Code, and Antigravity entries installed by Cairn.
+
+Run:
+
+```sh
+bunx cairn-ai@latest uninstall
+```
+
+When running from local source:
+
+```sh
+scripts/cairn uninstall
+```
+
+The source work folder and user-created `MEMORY.md`, `PLAN.md`, `docs/memory`, and `docs/plan` files are not deleted.

package/.agents/workflows/cairn-upgrade.md

@@ -0,0 +1,17 @@
+# cairn-upgrade
+
+Goal: update the current Cairn installation from the latest source.
+
+Run:
+
+```sh
+bunx cairn-ai@latest upgrade
+```
+
+When running from local source:
+
+```sh
+scripts/cairn upgrade
+```
+
+After upgrade, check status with the `cairn-doctor` workflow.

package/.agents/workflows/cairn-work.md

@@ -0,0 +1,20 @@
+# cairn-work
+
+Use the `cairn-work` skill.
+
+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/.claude/agents/explorer.md

@@ -0,0 +1,5 @@
+# explorer
+
+Read-only discovery agent for codebase questions, impact analysis, pattern search, and verification.
+
+Refer to `agents/explorer.md`.

package/.claude/agents/worker.md

@@ -0,0 +1,5 @@
+# worker
+
+Focused execution agent for search, small edits, command checks, and QA artifacts.
+
+Refer to `agents/worker.md`.

package/.claude/commands/cairn-doctor.md

@@ -0,0 +1,13 @@
+# cairn-doctor
+
+Diagnose Cairn installation status.
+
+```sh
+scripts/cairn doctor
+```
+
+Published package:
+
+```sh
+bunx cairn-ai@latest doctor
+```

package/.claude/commands/cairn-install.md

@@ -0,0 +1,13 @@
+# cairn-install
+
+Install Cairn into Codex, Claude Code, and Antigravity.
+
+```sh
+scripts/cairn install
+```
+
+Published package:
+
+```sh
+bunx cairn-ai@latest install
+```

package/.claude/commands/cairn-memory.md

@@ -0,0 +1,5 @@
+# cairn-memory
+
+Create or update `MEMORY.md` and `docs/memory/<domain>.md`.
+
+Follow plugin command `commands/cairn-memory.md`.

package/.claude/commands/cairn-plan.md

@@ -0,0 +1,5 @@
+# cairn-plan
+
+Create or update `PLAN.md` and `docs/plan/<topic>.md`, including tool readiness.
+
+Follow plugin command `commands/cairn-plan.md`.

package/.claude/commands/cairn-review.md

@@ -0,0 +1,5 @@
+# cairn-review
+
+Review completed slices against memory, plan, policy, tool readiness, and evidence.
+
+Follow plugin command `commands/cairn-review.md`.

package/.claude/commands/cairn-toolcheck.md

@@ -0,0 +1,10 @@
+# cairn-toolcheck
+
+Detect repository stacks and check required LSP, typecheck, lint, dry-run, and verification tools.
+
+```sh
+scripts/cairn toolcheck
+scripts/cairn toolcheck --install
+```
+
+Use `--install` before accepting a missing required tool as unavailable.

package/.claude/commands/cairn-uninstall.md

@@ -0,0 +1,13 @@
+# cairn-uninstall
+
+Remove the Codex, Claude Code, and Antigravity entries installed by Cairn.
+
+```sh
+scripts/cairn uninstall
+```
+
+Published package:
+
+```sh
+bunx cairn-ai@latest uninstall
+```

package/.claude/commands/cairn-upgrade.md

@@ -0,0 +1,13 @@
+# cairn-upgrade
+
+Update the Cairn installation from the current source.
+
+```sh
+scripts/cairn upgrade
+```
+
+Published package:
+
+```sh
+bunx cairn-ai@latest upgrade
+```

package/.claude/commands/cairn-work.md

@@ -0,0 +1,5 @@
+# cairn-work
+
+Execute the next incomplete module slice with tool readiness, module acceptance verification, and surface integration verification.
+
+Follow plugin command `commands/cairn-work.md`.

package/.codex-plugin/plugin.json

@@ -0,0 +1,30 @@
+{
+  "name": "cairn",
+  "version": "0.1.1",
+  "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity.",
+  "author": {
+    "name": "WkNam"
+  },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Cairn",
+    "shortDescription": "Memory, planning, tool readiness, and two-gate verification harness for agent teams.",
+    "longDescription": "Cairn brings a LazyCodex-inspired flow to Codex, Claude Code, and Antigravity while reducing token use through repository-local MEMORY.md, PLAN.md, domain notes, tool readiness checks, module-slice execution, and two-gate verification.",
+    "developerName": "WkNam",
+    "category": "Productivity",
+    "capabilities": [
+      "Hooks",
+      "Skills",
+      "Agent Workflow",
+      "Context Management",
+      "Planning",
+      "Tool Readiness"
+    ],
+    "defaultPrompt": [
+      "Use Cairn to create MEMORY.md and PLAN.md for this repository.",
+      "Run cairn-toolcheck before planning implementation work.",
+      "Run cairn-plan for this task without asking me for discoverable facts.",
+      "Run cairn-work from the current PLAN.md and pass both verification gates."
+    ]
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WkNam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.de.md

@@ -0,0 +1,130 @@
+# Cairn
+
+Cairn ist ein token-effizientes Multi-Agent-Harness-Plugin für Codex, Claude Code und Antigravity.
+
+[English](README.md)
+
+Die Grundidee ist, nützliches agent-harness-Verhalten beizubehalten: hooks, persistent state, explicit planning, focused delegation und stop-time guards. Cairn macht wiederholte TDD verification loops nicht zum Standard. Stattdessen teilt es Arbeit in kleine module slices und belegt jeden slice mit zwei verification gates.
+
+1. Module acceptance verification: belegt den geänderten module contract.
+2. Surface integration verification: belegt Verhalten über die echte surface, etwa CLI, HTTP, browser oder file artifacts.
+
+Bevor ein slice externen Zustand verändert, zeichnet Cairn den nächstliegenden dry-run oder check mode auf und führt ihn aus. Verification ist begrenzt: Jeder slice erhält standardmäßig zwei verification passes; danach zeichnet der agent einen blocker auf oder teilt den slice, statt eine offene Schleife fortzusetzen.
+
+Cairn behandelt tool readiness ebenfalls als Teil der Arbeit. LSP, typecheck, lint, dry-run und verification tools werden gegen den repository stack geprüft. Fehlt ein erforderliches tool, versucht Cairn eine project-local oder repository-native installation, bevor ein fallback akzeptiert wird.
+
+## LazyCodex Attribution
+
+Cairn ist von LazyCodex (`https://github.com/code-yeongyu/lazycodex`) beeinflusst. Übernommene Ideen sind die installierbare agent-harness-Form, Codex hook trust/setup handling, project memory, planning skills, executable workflow commands, diagnostics und skill/agent packaging über local agent surfaces hinweg.
+
+Cairn weicht in der execution policy bewusst von LazyCodex ab. Es übernimmt nicht das role-chain execution model oder die open-ended completion loops von LazyCodex. Cairn verwendet Light/Heavy Path triage, begrenzte `explorer`/`worker` delegation, zwei verification gates und explicit stop conditions.
+
+## Complexity Triage
+
+Jede implementation task durchläuft zuerst complexity triage, bevor agent, plugin oder delegated workflow guidance angewendet werden. Triage wird aus repository exploration, erwartetem Änderungsumfang und risk signals entschieden, ohne den user nach auffindbaren Fakten zu fragen.
+
+- Light Path: schmale Änderungen innerhalb existing architecture layers. Das ist der Standard. Direkt implementieren oder einen begrenzten `worker` verwenden, danach bleibt das verification gate bestehen.
+- 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 oder explicit extra-care request.
+
+Der gewählte path und die Begründung werden in `docs/plan/<topic>.md` festgehalten, wenn ein plan artifact existiert. Auch auf Light Path bleiben die zwei verification gates bestehen.
+
+## Tool Readiness
+
+`cairn toolcheck` untersucht das aktuelle repository auf JavaScript-, TypeScript-, Python-, PHP-, Java-, Kotlin-, Swift-, Go- und Rust-stacks und prüft die passenden LSP- und verification tools.
+
+```sh
+cairn toolcheck
+cairn toolcheck --install
+```
+
+- `toolcheck` meldet detected stacks und missing tools.
+- `toolcheck --install` versucht den nächstliegenden project-local oder repository-native install path, etwa package-manager dev dependencies, Composer dev dependencies, `uv`, Java LSP bootstrap, `go install` oder `rustup component add`.
+- Cairn plans erfassen detected stack, required tools, install commands und blockers.
+- Ein fehlender LSP server ist kein gültiger Grund, precise codebase exploration zu überspringen, bevor installation oder ein gleichwertiger symbol-aware fallback versucht wurde.
+
+## Dry-Run And Loop Policy
+
+- Migrations und database changes verwenden vor write/apply commands `--pretend`, dry-run, schema diff, rollback feasibility checks oder das nächstliegende repository-native equivalent.
+- Package, release, infrastructure, deployment, code generation und formatting work verwenden, wenn verfügbar, check, plan, diff, validate oder dry-run modes, bevor Zustand verändert wird.
+- Wenn kein dry-run existiert, hält der plan dies fest und wählt den kleinsten reversiblen command oder test artifact.
+- Wenn ein verification gate fehlschlägt, diagnostiziert Cairn einmal, verkleinert oder teilt den slice und führt beide gates erneut aus.
+- Nach zwei fehlgeschlagenen verification passes für denselben slice zeichnet Cairn den blocker in `docs/plan/<topic>.md` auf, statt eine wiederholte Schleife fortzusetzen.
+
+## Model Guidance
+
+Cairn wendet model-specific adjustment nur auf Claude-family und Codex-family models an.
+
+- Claude-family: geeignet für long context, policy interpretation und plan/evidence review.
+- Codex-family: geeignet für small implementation slices, explicit file edits, command-based verification und bounded `worker` tasks.
+
+Details stehen in `docs/model-guidance/README.md`, `docs/model-guidance/claude.md` und `docs/model-guidance/codex.md`.
+
+## Repository Artifacts
+
+Das harness erstellt und pflegt diese files im Ziel-repository root.
+
+- `MEMORY.md`: kurzer Index persistent domain knowledge.
+- `docs/memory/*.md`: detailliertes Wissen je domain.
+- `docs/model-guidance/*.md`: Claude- und Codex-model adjustment guidance.
+- `PLAN.md`: kurzer Index aktiver und abgeschlossener work topics.
+- `docs/plan/*.md`: detailed execution plans.
+
+Root files bleiben kurz, Details wandern unter `docs/`, damit agents nur den benötigten context lesen.
+
+## Commands
+
+Das veröffentlichte package kann mit `bunx` oder global installierten `cairn` commands ausgeführt werden.
+
+```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
+```
+
+Nach globaler installation sind auch kurze commands verfügbar.
+
+```sh
+bun add -g cairn-ai
+cairn install
+cairn upgrade
+cairn doctor
+cairn uninstall
+cairn toolcheck
+```
+
+- `cairn install`: installiert das plugin in den Codex marketplace cache und konfiguriert hook trust state, Claude Code mirror files und Antigravity skills/workflows.
+- `cairn upgrade`: aktualisiert installation, hook trust state, Claude Code mirror files und Antigravity skills/workflows aus der aktuellen source.
+- `cairn doctor`: diagnostiziert Codex settings, installation, hook trust state, Claude Code mirror files und Antigravity mirror files.
+- `cairn uninstall`: entfernt von Cairn hinzugefügte Codex settings, cache, Claude Code mirror files und Antigravity mirror files.
+- `cairn toolcheck`: erkennt repository stacks und prüft oder installiert required LSP und verification tools.
+- `cairn-memory`: erkundet domain knowledge und aktualisiert `MEMORY.md`.
+- `cairn-plan`: erstellt einen decision-complete plan unter `docs/plan/`.
+- `cairn-work`: führt den nächsten module slice im aktuellen `PLAN.md` mit zwei verification gates aus.
+- `cairn-review`: prüft completed slices gegen plan, memory und evidence.
+
+`install` und `upgrade` erstellen `*.cairn-backup-*` backups, bevor `~/.codex/config.toml` verändert wird. Das source plugin manifest bleibt validator-friendly; nur die installed cache copy erhält ein `hooks` field zur Aktivierung von Codex hooks.
+
+Codex verwendet `skills/` und `commands/`. Claude Code verwendet gespiegelte commands und agent definitions unter `.claude/`. Antigravity verwendet `.agents/workflows` und globale skills mirrors.
+
+## Antigravity Compatibility
+
+Antigravity unterstützt `SKILL.md`-basierte Agent Skills und Workflows, die als `/workflow-name` aufgerufen werden. Cairn installiert für diese Oberfläche die folgenden 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 werden nicht nach Antigravity portiert. Stattdessen laufen dieselben planning-, memory-, complexity triage- und two-gate verification procedures über Skills und Workflows. Setze `ANTIGRAVITY_HOME` oder `ANTIGRAVITY_CLI_HOME`, um paths zu überschreiben.
+
+## Locale Policy
+
+Cairns reusable instructions sind für global use auf Englisch geschrieben. User-visible output folgt der konfigurierten OS locale, sofern der user nicht ausdrücklich eine andere Sprache verlangt. Die CLI lokalisiert common messages für `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` und `pt` und fällt bei unsupported locales auf English zurück. Codex hook `statusMessage` text bleibt static English, während hook command output English oder Korean ist.
+
+## Delegation
+
+- `explorer`: erledigt read-only codebase discovery, impact analysis, pattern searches und read-only verification, wenn verfügbar.
+- `worker`: erledigt bounded implementation oder verification tasks mit klarem file ownership.
+- Main session: hält urgent blocking work lokal, wenn der nächste Schritt sofort vom Ergebnis abhängt.
+
+Jeder delegation prompt verwendet sechs sections: TASK, EXPECTED OUTCOME, REQUIRED TOOLS, MUST DO, MUST NOT DO, CONTEXT.

package/README.es.md

@@ -0,0 +1,130 @@
+# Cairn
+
+Cairn es un plugin de harness multi-agente eficiente en tokens para Codex, Claude Code y Antigravity.
+
+[English](README.md)
+
+La idea central es conservar comportamientos útiles de agent harness: hooks, estado persistente, planificación explícita, delegación enfocada y guardas al detenerse. Cairn no hace que los bucles repetidos de verificación TDD sean el comportamiento predeterminado. En su lugar, divide el trabajo en pequeños module slices y prueba cada slice con dos verification gates.
+
+1. Module acceptance verification: prueba el contrato del módulo modificado.
+2. Surface integration verification: prueba el comportamiento a través de una superficie real, como CLI, HTTP, navegador o artefactos de archivo.
+
+Antes de que un slice modifique estado externo, Cairn registra y ejecuta el dry-run o check mode más cercano disponible. La verificación está acotada: cada slice tiene dos verification passes por defecto; después, el agente registra un blocker o divide el slice en lugar de continuar un bucle abierto.
+
+Cairn también trata la preparación de herramientas como parte del trabajo. LSP, typecheck, lint, dry-run y verification tools se revisan contra el stack del repositorio. Si falta una herramienta requerida, Cairn intenta una instalación project-local o repository-native antes de aceptar un fallback.
+
+## LazyCodex Attribution
+
+Cairn está influido por LazyCodex (`https://github.com/code-yeongyu/lazycodex`). Las ideas tomadas son la forma de agent harness instalable, el manejo de Codex hook trust/setup, project memory, planning skills, executable workflow commands, diagnostics y skill/agent packaging entre local agent surfaces.
+
+Cairn diverge intencionalmente de LazyCodex en la execution policy. No adopta el role-chain execution model ni los open-ended completion loops de LazyCodex. Cairn usa Light/Heavy Path triage, delegación acotada con `explorer`/`worker`, dos verification gates y explicit stop conditions.
+
+## Complexity Triage
+
+Cada implementation task pasa primero por complexity triage, antes de aplicar agent, plugin o delegated workflow guidance. El triage se decide a partir de la exploración del repositorio, el alcance esperado del cambio y señales de riesgo, sin preguntar al usuario por hechos que se puedan descubrir.
+
+- Light Path: cambios estrechos dentro de existing architecture layers. Es el valor predeterminado. Implementa directamente o usa un `worker` acotado, y conserva el 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 o una explicit extra-care request.
+
+El path seleccionado y su justificación se registran en `docs/plan/<topic>.md` cuando existe un plan artifact. Incluso en Light Path, se mantienen los dos verification gates.
+
+## Tool Readiness
+
+`cairn toolcheck` inspecciona el repositorio actual para stacks JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go y Rust, y luego revisa los LSP y verification tools correspondientes.
+
+```sh
+cairn toolcheck
+cairn toolcheck --install
+```
+
+- `toolcheck` reporta detected stacks y missing tools.
+- `toolcheck --install` intenta la ruta de instalación project-local o repository-native más cercana, como dev dependencies del package manager, dev dependencies de Composer, `uv`, Java LSP bootstrap, `go install` o `rustup component add`.
+- Los planes de Cairn registran detected stack, required tools, install commands y blockers.
+- Que falte un LSP server no es razón válida para saltarse precise codebase exploration hasta intentar installation o un fallback symbol-aware equivalente.
+
+## Dry-Run And Loop Policy
+
+- Migrations y database changes usan `--pretend`, dry-run, schema diff, rollback feasibility checks o el equivalente repository-native más cercano antes de comandos write/apply.
+- Package, release, infrastructure, deployment, code generation y formatting work usan check, plan, diff, validate o dry-run modes antes de mutar estado cuando están disponibles.
+- Si no existe dry-run, el plan registra ese hecho y elige el comando reversible más pequeño o el artefacto de prueba disponible.
+- Si falla un verification gate, Cairn diagnostica una vez, reduce o divide el slice y vuelve a ejecutar ambos gates.
+- Después de dos verification passes fallidos para el mismo slice, Cairn registra el blocker en `docs/plan/<topic>.md` en lugar de continuar un bucle repetido.
+
+## Model Guidance
+
+Cairn solo aplica ajustes específicos de modelo a modelos Claude-family y Codex-family.
+
+- Claude-family: útil para long context, policy interpretation y plan/evidence review.
+- Codex-family: útil para small implementation slices, explicit file edits, command-based verification y bounded `worker` tasks.
+
+La guía detallada vive en `docs/model-guidance/README.md`, `docs/model-guidance/claude.md` y `docs/model-guidance/codex.md`.
+
+## Repository Artifacts
+
+El harness crea y mantiene estos archivos en la raíz del repositorio objetivo.
+
+- `MEMORY.md`: índice corto de conocimiento persistente del dominio.
+- `docs/memory/*.md`: conocimiento detallado por dominio.
+- `docs/model-guidance/*.md`: guía de ajuste de modelos Claude y Codex.
+- `PLAN.md`: índice corto de temas activos y completados.
+- `docs/plan/*.md`: planes de ejecución detallados.
+
+Los archivos raíz se mantienen cortos y los detalles pasan a `docs/`, para que los agentes lean solo el contexto que necesitan.
+
+## Commands
+
+El paquete publicado puede ejecutarse con `bunx` o con 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
+```
+
+Después de una instalación global, también están disponibles comandos cortos.
+
+```sh
+bun add -g cairn-ai
+cairn install
+cairn upgrade
+cairn doctor
+cairn uninstall
+cairn toolcheck
+```
+
+- `cairn install`: instala el plugin en el Codex marketplace cache y configura hook trust state, mirror files de Claude Code y skills/workflows de Antigravity.
+- `cairn upgrade`: actualiza la instalación, hook trust state, mirror files de Claude Code y skills/workflows de Antigravity desde la fuente actual.
+- `cairn doctor`: diagnostica Codex settings, installation, hook trust state, mirror files de Claude Code y mirror files de Antigravity.
+- `cairn uninstall`: elimina Codex settings, cache, mirror files de Claude Code y mirror files de Antigravity agregados por Cairn.
+- `cairn toolcheck`: detecta repository stacks y revisa o instala required LSP y verification tools.
+- `cairn-memory`: explora domain knowledge y actualiza `MEMORY.md`.
+- `cairn-plan`: crea un decision-complete plan bajo `docs/plan/`.
+- `cairn-work`: ejecuta el siguiente module slice del `PLAN.md` actual con dos verification gates.
+- `cairn-review`: revisa completed slices contra plan, memory y evidence.
+
+`install` y `upgrade` crean backups `*.cairn-backup-*` antes de modificar `~/.codex/config.toml`. El source plugin manifest permanece validator-friendly; solo la copia instalada en cache recibe un campo `hooks` para activar Codex hooks.
+
+Codex usa `skills/` y `commands/`. Claude Code usa comandos reflejados y definiciones de agentes bajo `.claude/`. Antigravity usa `.agents/workflows` y mirrors globales de skills.
+
+## Antigravity Compatibility
+
+Antigravity soporta Agent Skills y Workflows basados en `SKILL.md` invocados como `/workflow-name`. Cairn instala estas rutas para esa superficie.
+
+- Antigravity IDE: `~/.agents/skills/cairn-*`, `~/.agents/workflows/cairn-*.md`.
+- Antigravity CLI: `~/.gemini/antigravity-cli/skills/cairn-*`, `~/.gemini/antigravity-cli/workflows/cairn-*.md`.
+
+Los hooks exclusivos de Codex no se portan a Antigravity. En su lugar, los mismos procedimientos de planning, memory, complexity triage y two-gate verification se ejecutan mediante Skills y Workflows. Define `ANTIGRAVITY_HOME` o `ANTIGRAVITY_CLI_HOME` para sobrescribir las rutas.
+
+## Locale Policy
+
+Las instrucciones reutilizables de Cairn están escritas en inglés para uso global. El output visible para el usuario debe seguir el OS locale configurado, salvo que el usuario pida otro idioma explícitamente. La CLI localiza mensajes comunes para `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` y `pt`, y vuelve a English para locales no soportados. El texto `statusMessage` de Codex hooks permanece en inglés estático, mientras que hook command output es English o Korean.
+
+## Delegation
+
+- `explorer`: maneja read-only codebase discovery, impact analysis, pattern searches y read-only verification cuando está disponible.
+- `worker`: maneja bounded implementation o verification tasks con file ownership claro.
+- Main session: mantiene local el urgent blocking work cuando el siguiente paso depende inmediatamente del resultado.
+
+Cada delegation prompt usa seis secciones: TASK, EXPECTED OUTCOME, REQUIRED TOOLS, MUST DO, MUST NOT DO, CONTEXT.