cairn-ai 0.1.2

package/README.fr.md

@@ -0,0 +1,130 @@
+# Cairn
+
+Cairn est un plugin de harness multi-agent économe en tokens pour Codex, Claude Code et Antigravity.
+
+[English](README.md)
+
+L'idée centrale est de conserver des comportements utiles d'agent harness : hooks, état persistant, planification explicite, délégation ciblée et gardes au moment de l'arrêt. Cairn ne fait pas des boucles répétées de vérification TDD le comportement par défaut. Il découpe plutôt le travail en petits module slices et prouve chaque slice avec deux verification gates.
+
+1. Module acceptance verification : prouve le contrat du module modifié.
+2. Surface integration verification : prouve le comportement via une surface réelle, comme CLI, HTTP, navigateur ou artefacts de fichiers.
+
+Avant qu'un slice ne modifie un état externe, Cairn enregistre et exécute le dry-run ou check mode disponible le plus proche. La vérification est bornée : chaque slice reçoit deux verification passes par défaut, puis l'agent enregistre un blocker ou divise le slice au lieu de continuer une boucle ouverte.
+
+Cairn traite aussi la préparation des outils comme une partie du travail. LSP, typecheck, lint, dry-run et verification tools sont vérifiés par rapport au stack du repository. Si un outil requis manque, Cairn tente une installation project-local ou repository-native avant d'accepter un fallback.
+
+## LazyCodex Attribution
+
+Cairn est influencé par LazyCodex (`https://github.com/code-yeongyu/lazycodex`). Les idées reprises sont la forme d'agent harness installable, la gestion Codex hook trust/setup, project memory, planning skills, executable workflow commands, diagnostics et le skill/agent packaging entre local agent surfaces.
+
+Cairn diverge volontairement de LazyCodex dans l'execution policy. Il n'adopte pas le role-chain execution model ni les open-ended completion loops de LazyCodex. Cairn utilise Light/Heavy Path triage, une délégation bornée `explorer`/`worker`, deux verification gates et des explicit stop conditions.
+
+## Complexity Triage
+
+Chaque implementation task passe d'abord par complexity triage, avant d'appliquer agent, plugin ou delegated workflow guidance. Le triage est décidé à partir de l'exploration du repository, de la portée attendue du changement et des signaux de risque, sans demander à l'utilisateur les faits découvrables.
+
+- Light Path : changements étroits dans les existing architecture layers. C'est le comportement par défaut. Implémentez directement ou utilisez un `worker` borné, puis conservez le 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.
+
+Le path choisi et sa justification sont enregistrés dans `docs/plan/<topic>.md` quand un plan artifact existe. Même en Light Path, les deux verification gates restent.
+
+## Tool Readiness
+
+`cairn toolcheck` inspecte le repository courant pour les stacks JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go et Rust, puis vérifie les LSP et verification tools correspondants.
+
+```sh
+cairn toolcheck
+cairn toolcheck --install
+```
+
+- `toolcheck` signale les detected stacks et missing tools.
+- `toolcheck --install` tente le chemin d'installation project-local ou repository-native le plus proche, comme les dev dependencies du package manager, les dev dependencies Composer, `uv`, Java LSP bootstrap, `go install` ou `rustup component add`.
+- Les plans Cairn enregistrent detected stack, required tools, install commands et blockers.
+- Un LSP server manquant n'est pas une raison valable pour ignorer precise codebase exploration tant qu'une installation ou un fallback symbol-aware équivalent n'a pas été tenté.
+
+## Dry-Run And Loop Policy
+
+- Migrations et database changes utilisent `--pretend`, dry-run, schema diff, rollback feasibility checks ou l'équivalent repository-native le plus proche avant les commandes write/apply.
+- Package, release, infrastructure, deployment, code generation et formatting work utilisent check, plan, diff, validate ou dry-run modes avant de modifier l'état quand c'est disponible.
+- Si aucun dry-run n'existe, le plan l'enregistre et choisit la plus petite commande réversible ou le test artifact disponible.
+- Si une verification gate échoue, Cairn diagnostique une fois, réduit ou divise le slice, puis relance les deux gates.
+- Après deux verification passes échouées pour le même slice, Cairn enregistre le blocker dans `docs/plan/<topic>.md` au lieu de continuer une boucle répétée.
+
+## Model Guidance
+
+Cairn applique des ajustements spécifiques uniquement aux modèles Claude-family et Codex-family.
+
+- Claude-family : utile pour long context, policy interpretation et plan/evidence review.
+- Codex-family : utile pour small implementation slices, explicit file edits, command-based verification et bounded `worker` tasks.
+
+Les détails se trouvent dans `docs/model-guidance/README.md`, `docs/model-guidance/claude.md` et `docs/model-guidance/codex.md`.
+
+## Repository Artifacts
+
+Le harness crée et maintient ces fichiers à la racine du repository cible.
+
+- `MEMORY.md` : index court de persistent domain knowledge.
+- `docs/memory/*.md` : connaissances détaillées par domaine.
+- `docs/model-guidance/*.md` : guidance d'ajustement pour les modèles Claude et Codex.
+- `PLAN.md` : index court des sujets actifs et terminés.
+- `docs/plan/*.md` : detailed execution plans.
+
+Les fichiers racine restent courts et les détails vont sous `docs/`, afin que les agents ne lisent que le contexte nécessaire.
+
+## Commands
+
+Le package publié peut être exécuté avec `bunx` ou avec des commandes `cairn` installées globalement.
+
+```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
+```
+
+Après une installation globale, des commandes courtes sont aussi disponibles.
+
+```sh
+bun add -g cairn-ai
+cairn install
+cairn upgrade
+cairn doctor
+cairn uninstall
+cairn toolcheck
+```
+
+- `cairn install` : installe le plugin dans le Codex marketplace cache et configure hook trust state, Claude Code mirror files et Antigravity skills/workflows.
+- `cairn upgrade` : met à jour installation, hook trust state, Claude Code mirror files et Antigravity skills/workflows depuis la source actuelle.
+- `cairn doctor` : diagnostique Codex settings, installation, hook trust state, Claude Code mirror files et Antigravity mirror files.
+- `cairn uninstall` : supprime Codex settings, cache, Claude Code mirror files et Antigravity mirror files ajoutés par Cairn.
+- `cairn toolcheck` : détecte repository stacks et vérifie ou installe required LSP et verification tools.
+- `cairn-memory` : explore domain knowledge et met à jour `MEMORY.md`.
+- `cairn-plan` : crée un decision-complete plan sous `docs/plan/`.
+- `cairn-work` : exécute le prochain module slice du `PLAN.md` courant avec deux verification gates.
+- `cairn-review` : relit completed slices par rapport au plan, memory et evidence.
+
+`install` et `upgrade` créent des backups `*.cairn-backup-*` avant de modifier `~/.codex/config.toml`. Le source plugin manifest reste validator-friendly ; seule la copie installée en cache reçoit un champ `hooks` pour activer les Codex hooks.
+
+Codex utilise `skills/` et `commands/`. Claude Code utilise les commandes miroir et définitions d'agents sous `.claude/`. Antigravity utilise `.agents/workflows` et les global skills mirrors.
+
+## Antigravity Compatibility
+
+Antigravity prend en charge les Agent Skills et Workflows basés sur `SKILL.md`, invoqués comme `/workflow-name`. Cairn installe ces paths pour cette surface.
+
+- Antigravity IDE : `~/.agents/skills/cairn-*`, `~/.agents/workflows/cairn-*.md`.
+- Antigravity CLI : `~/.gemini/antigravity-cli/skills/cairn-*`, `~/.gemini/antigravity-cli/workflows/cairn-*.md`.
+
+Les hooks propres à Codex ne sont pas portés vers Antigravity. À la place, les mêmes procédures planning, memory, complexity triage et two-gate verification s'exécutent via Skills et Workflows. Définissez `ANTIGRAVITY_HOME` ou `ANTIGRAVITY_CLI_HOME` pour remplacer les paths.
+
+## Locale Policy
+
+Les instructions réutilisables de Cairn sont écrites en anglais pour un usage global. La sortie visible par l'utilisateur doit suivre l'OS locale configurée, sauf si l'utilisateur demande explicitement une autre langue. La CLI localise les messages communs pour `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` et `pt`, puis revient à English pour les locales non prises en charge. Le texte `statusMessage` des Codex hooks reste en anglais statique, tandis que hook command output est English ou Korean.
+
+## Delegation
+
+- `explorer` : gère read-only codebase discovery, impact analysis, pattern searches et read-only verification quand disponible.
+- `worker` : gère des bounded implementation ou verification tasks avec file ownership clair.
+- Main session : garde local l'urgent blocking work quand l'étape suivante dépend immédiatement du résultat.
+
+Chaque delegation prompt utilise six sections : TASK, EXPECTED OUTCOME, REQUIRED TOOLS, MUST DO, MUST NOT DO, CONTEXT.

package/README.ja.md

@@ -0,0 +1,130 @@
+# Cairn
+
+Cairn は Codex、Claude Code、Antigravity のためのトークン効率の高いマルチエージェント harness plugin です。
+
+[English](README.md)
+
+Cairn の基本方針は、hooks、永続状態、明示的な planning、focused delegation、stop-time guards といった有用な agent harness の動作を残すことです。Cairn は反復的な TDD verification loop を既定にしません。代わりに作業を小さな module slice に分け、2 つの verification gate で証明します。
+
+1. Module acceptance verification: 変更された module contract を証明します。
+2. Surface integration verification: CLI、HTTP、browser、file artifacts など実際の surface を通して動作を証明します。
+
+slice が外部状態を変更する前に、Cairn は最も近い dry-run または check mode を記録して実行します。verification は制限されます。既定では各 slice は 2 回の verification pass を持ち、その後は反復 loop を続けず blocker を記録するか slice を分割します。
+
+Cairn は tool readiness も作業の一部として扱います。LSP、typecheck、lint、dry-run、verification tools を repository stack に照らして確認します。必要な tool がない場合、fallback を受け入れる前に project-local または repository-native installation を試みます。
+
+## 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 は採用しません。代わりに Light/Heavy Path triage、bounded `explorer`/`worker` delegation、2 つの verification gates、明示的な stop conditions を使います。
+
+## Complexity Triage
+
+すべての implementation task は、agent、plugin、delegated workflow guidance を適用する前に complexity triage を通ります。triage は user に質問せず、repository exploration、想定される変更範囲、risk signals から決定します。
+
+- Light Path: 既存 architecture layer 内の狭い変更です。既定値であり、直接実装するか 1 つの 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 でも 2 つの verification gate は維持されます。
+
+## 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` は package-manager dev dependencies、Composer dev dependencies、`uv`、Java LSP bootstrap、`go install`、`rustup component add` など、最も近い project-local または repository-native install path を試みます。
+- 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 はその事実を記録し、最小で reversible な command または test artifact を選びます。
+- verification gate が失敗した場合、Cairn は一度診断し、slice を縮小または分割して両方の gate を再実行します。
+- 同じ slice で 2 回の verification pass が失敗した場合、反復 loop を続けず `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 に次の files を作成して維持します。
+
+- `MEMORY.md`: persistent domain knowledge の短い index。
+- `docs/memory/*.md`: domain ごとの詳細 knowledge。
+- `docs/model-guidance/*.md`: Claude と Codex model adjustment guidance。
+- `PLAN.md`: active/completed work topics の短い index。
+- `docs/plan/*.md`: detailed execution plans。
+
+root files は短く保ち、詳細は `docs/` に移すことで、agents が必要な context だけを読めるようにします。
+
+## Commands
+
+published package は `bunx` または global install された `cairn` command で実行できます。
+
+```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
+```
+
+global installation 後は short commands も使えます。
+
+```sh
+bun add -g cairn-ai
+cairn install
+cairn upgrade
+cairn doctor
+cairn uninstall
+cairn toolcheck
+```
+
+- `cairn install`: Codex marketplace cache に plugin を install し、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 を確認または install します。
+- `cairn-memory`: domain knowledge を探索し `MEMORY.md` を更新します。
+- `cairn-plan`: `docs/plan/` に decision-complete plan を作成します。
+- `cairn-work`: 現在の `PLAN.md` の次の module slice を実行し、2 つの verification gates を取得します。
+- `cairn-review`: plan、memory、evidence に照らして completed slices を review します。
+
+`install` と `upgrade` は `~/.codex/config.toml` を変更する前に `*.cairn-backup-*` backups を作ります。source plugin manifest は validator-friendly のままにし、Codex hooks を有効化する `hooks` field は installed cache copy にだけ追加されます。
+
+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 を install します。
+
+- 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 へ port されません。代わりに同じ planning、memory、complexity triage、two-gate verification procedures が Skills と Workflows を通して実行されます。paths を上書きするには `ANTIGRAVITY_HOME` または `ANTIGRAVITY_CLI_HOME` を設定してください。
+
+## Locale Policy
+
+Cairn の reusable instructions は global use のため英語で書かれています。user-visible output は user が別の language を指定しない限り configured OS locale に従います。CLI は `en`、`ko`、`ja`、`zh`、`es`、`fr`、`de`、`pt` の common messages を localize し、unsupported locales は English に fallback します。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: 次の step が結果に即座に依存する urgent blocking work を local で処理します。
+
+すべての delegation prompt は TASK、EXPECTED OUTCOME、REQUIRED TOOLS、MUST DO、MUST NOT DO、CONTEXT の 6 sections を使います。

package/README.ko.md

@@ -0,0 +1,130 @@
+# Cairn
+
+Cairn은 Codex, Claude Code, Antigravity를 위한 토큰 효율적인 멀티에이전트 하네스 플러그인입니다.
+
+[English](README.md)
+
+핵심 아이디어는 hooks, 지속 상태, 명시적 계획, 집중 위임, 종료 시점 가드 같은 유용한 에이전트 하네스 동작을 유지하는 것입니다. Cairn은 반복적인 TDD 검증 루프를 기본값으로 삼지 않습니다. 대신 작업을 작은 모듈 조각으로 나누고 두 가지 검증 게이트로 증명합니다.
+
+1. 모듈 수용 검증: 변경된 모듈 계약을 증명합니다.
+2. 표면 통합 검증: CLI, HTTP, 브라우저, 파일 산출물 같은 실제 표면을 통해 동작을 증명합니다.
+
+외부 상태를 변경할 수 있는 조각은 실행 전에 가장 가까운 dry-run 또는 check 모드를 기록하고 실행합니다. 검증은 제한됩니다. 기본적으로 각 조각은 두 번의 검증 패스를 가지며, 이후에는 반복 루프를 계속하지 않고 blocker를 기록하거나 조각을 더 작게 나눕니다.
+
+Cairn은 도구 준비 상태도 작업의 일부로 다룹니다. LSP, typecheck, lint, dry-run, 검증 도구를 저장소 스택 기준으로 확인하고, 필수 도구가 없으면 fallback을 받아들이기 전에 프로젝트 로컬 또는 저장소 네이티브 설치를 시도합니다.
+
+## LazyCodex Attribution
+
+Cairn은 LazyCodex(`https://github.com/code-yeongyu/lazycodex`)의 영향을 받았습니다. 영향을 받은 부분은 설치 가능한 에이전트 하네스 구조, Codex hook trust/setup 처리, project memory, planning skills, 실행 가능한 workflow commands, diagnostics, 그리고 local agent surfaces 전반의 skill/agent packaging입니다.
+
+Cairn은 실행 정책에서는 LazyCodex와 다릅니다. LazyCodex의 role-chain execution model이나 open-ended completion loop는 채택하지 않습니다. 대신 Light/Heavy Path triage, 제한된 `explorer`/`worker` 위임, 두 검증 게이트, 명시적 stop condition을 사용합니다.
+
+## Complexity Triage
+
+모든 구현 작업은 agent, plugin, delegated workflow 지침을 적용하기 전에 먼저 complexity triage를 거칩니다. triage는 사용자에게 묻지 않고 저장소 탐색, 예상 변경 범위, 위험 신호를 기준으로 결정합니다.
+
+- Light Path: 기존 아키텍처 레이어 안의 좁은 변경입니다. 기본값이며, 직접 구현하거나 하나의 제한된 `worker`를 사용한 뒤 검증 게이트를 유지합니다.
+- Heavy Path: 새 디렉터리/모듈/레이어, 새 도메인 모델/서비스/추상화, 보안/세션/인증, 외부 API/message queue/payment, DB schema/migration, concurrency/transaction/cache 변경, 여러 도메인 리팩터링, 또는 사용자의 extra-care 요청입니다.
+
+선택된 path와 근거는 계획 산출물이 있을 때 `docs/plan/<topic>.md`에 기록합니다. Light Path에서도 두 검증 게이트는 유지됩니다.
+
+## Tool Readiness
+
+`cairn toolcheck`는 현재 저장소에서 JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go, Rust 스택을 감지하고, 해당 LSP와 검증 도구를 확인합니다.
+
+```sh
+cairn toolcheck
+cairn toolcheck --install
+```
+
+- `toolcheck`는 감지된 스택과 누락 도구를 보고합니다.
+- `toolcheck --install`은 package manager dev dependency, Composer dev dependency, `uv`, Java LSP bootstrap, `go install`, `rustup component add` 같은 가장 가까운 프로젝트 로컬 또는 저장소 네이티브 설치 경로를 시도합니다.
+- Cairn 계획은 감지된 스택, 필요한 도구, 설치 명령, blocker를 기록합니다.
+- LSP server가 없다는 사실만으로 정밀한 코드베이스 탐색을 건너뛸 수 없습니다. 설치 또는 동등한 symbol-aware fallback을 먼저 시도해야 합니다.
+
+## Dry-Run And Loop Policy
+
+- 마이그레이션과 데이터베이스 변경은 write/apply 명령 전에 `--pretend`, dry-run, schema diff, rollback 가능성 검사, 또는 가장 가까운 저장소 네이티브 방식을 사용합니다.
+- 패키지, 릴리스, 인프라, 배포, 코드 생성, 포매팅 작업은 가능한 경우 상태 변경 전에 check, plan, diff, validate, dry-run 모드를 사용합니다.
+- dry-run이 없으면 계획에 그 사실을 기록하고 가장 작고 되돌릴 수 있는 명령 또는 테스트 산출물을 선택합니다.
+- 검증 게이트가 실패하면 Cairn은 한 번 진단하고 조각을 줄이거나 나눈 뒤 두 게이트를 다시 실행합니다.
+- 같은 조각에서 두 번의 검증 패스가 실패하면 반복 루프를 계속하지 않고 `docs/plan/<topic>.md`에 blocker를 기록합니다.
+
+## Model Guidance
+
+Cairn은 Claude-family와 Codex-family 모델에만 모델별 조정을 적용합니다.
+
+- Claude-family: 긴 컨텍스트, 정책 해석, 계획/증거 검토에 유용합니다.
+- Codex-family: 작은 구현 조각, 명시적 파일 편집, command 기반 검증, 제한된 `worker` 작업에 유용합니다.
+
+자세한 가이드는 `docs/model-guidance/README.md`, `docs/model-guidance/claude.md`, `docs/model-guidance/codex.md`에 있습니다.
+
+## Repository Artifacts
+
+하네스는 대상 저장소 루트에 다음 파일을 생성하고 유지합니다.
+
+- `MEMORY.md`: 지속 도메인 지식의 짧은 색인.
+- `docs/memory/*.md`: 도메인별 상세 지식.
+- `docs/model-guidance/*.md`: Claude와 Codex 모델 조정 가이드.
+- `PLAN.md`: 활성/완료 작업 주제의 짧은 색인.
+- `docs/plan/*.md`: 상세 실행 계획.
+
+루트 파일은 짧게 유지하고 상세 내용은 `docs/` 아래로 이동해, 에이전트가 필요한 컨텍스트만 읽도록 합니다.
+
+## Commands
+
+게시된 패키지는 `bunx` 또는 전역 설치된 `cairn` 명령으로 실행할 수 있습니다.
+
+```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`: Codex marketplace cache에 플러그인을 설치하고 hook trust state, Claude Code mirror 파일, Antigravity skills/workflows를 설정합니다.
+- `cairn upgrade`: 현재 소스에서 설치, hook trust state, Claude Code mirror 파일, Antigravity skills/workflows를 갱신합니다.
+- `cairn doctor`: Codex 설정, 설치, hook trust state, Claude Code mirror 파일, Antigravity mirror 파일을 진단합니다.
+- `cairn uninstall`: Cairn이 추가한 Codex 설정, cache, Claude Code mirror 파일, Antigravity mirror 파일을 제거합니다.
+- `cairn toolcheck`: 저장소 스택을 감지하고 필요한 LSP와 검증 도구를 확인하거나 설치합니다.
+- `cairn-memory`: 도메인 지식을 탐색하고 `MEMORY.md`를 갱신합니다.
+- `cairn-plan`: `docs/plan/` 아래에 decision-complete plan을 만듭니다.
+- `cairn-work`: 현재 `PLAN.md`의 다음 모듈 조각을 실행하고 두 검증 게이트를 확보합니다.
+- `cairn-review`: 계획, memory, 증거를 기준으로 완료된 조각을 검토합니다.
+
+`install`과 `upgrade`는 `~/.codex/config.toml`을 수정하기 전에 `*.cairn-backup-*` 백업을 만듭니다. 소스 플러그인 manifest는 validator-friendly 상태를 유지하고, 설치된 cache copy에만 Codex hook 활성화를 위한 `hooks` field가 추가됩니다.
+
+Codex는 `skills/`와 `commands/`를 사용합니다. Claude Code는 `.claude/` 아래의 mirror command와 agent definition을 사용합니다. Antigravity는 `.agents/workflows`와 global skills mirror를 사용합니다.
+
+## Antigravity Compatibility
+
+Antigravity는 `/workflow-name`으로 호출되는 `SKILL.md` 기반 Agent Skills와 Workflows를 지원합니다. Cairn은 해당 표면에 다음 경로를 설치합니다.
+
+- Antigravity IDE: `~/.agents/skills/cairn-*`, `~/.agents/workflows/cairn-*.md`.
+- Antigravity CLI: `~/.gemini/antigravity-cli/skills/cairn-*`, `~/.gemini/antigravity-cli/workflows/cairn-*.md`.
+
+Codex 전용 hooks는 Antigravity로 포팅하지 않습니다. 대신 같은 planning, memory, complexity triage, two-gate verification 절차가 Skills와 Workflows를 통해 실행됩니다. 경로를 바꾸려면 `ANTIGRAVITY_HOME` 또는 `ANTIGRAVITY_CLI_HOME`을 설정하세요.
+
+## Locale Policy
+
+Cairn의 재사용 지침은 전역 사용을 위해 영어로 작성됩니다. 사용자에게 보이는 출력은 사용자가 다른 언어를 명시하지 않는 한 설정된 OS locale을 따릅니다. CLI는 `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de`, `pt`의 일반 메시지를 현지화하고, 지원하지 않는 locale은 영어로 fallback합니다. Codex hook `statusMessage` 텍스트는 정적 영어로 유지하고, hook command output은 영어 또는 한국어입니다.
+
+## Delegation
+
+- `explorer`: 가능한 경우 read-only codebase discovery, impact analysis, pattern search, read-only verification을 처리합니다.
+- `worker`: 명확한 file ownership이 있는 제한된 implementation 또는 verification task를 처리합니다.
+- Main session: 다음 단계가 즉시 결과에 의존하는 urgent blocking work를 로컬에서 처리합니다.
+
+모든 delegation prompt는 TASK, EXPECTED OUTCOME, REQUIRED TOOLS, MUST DO, MUST NOT DO, CONTEXT 여섯 섹션을 사용합니다.

package/README.md

@@ -0,0 +1,138 @@
+# Cairn
+
+Cairn is a token-efficient multi-agent harness plugin for Codex, Claude Code, and Antigravity.
+
+## Translations
+
+- [한국어](README.ko.md)
+- [日本語](README.ja.md)
+- [中文](README.zh.md)
+- [Español](README.es.md)
+- [Français](README.fr.md)
+- [Deutsch](README.de.md)
+- [Português](README.pt.md)
+
+The core idea is to keep useful agent-harness behavior: hooks, persistent state, explicit planning, focused delegation, and stop-time guards. Cairn does not make repeated TDD verification loops the default. Instead, it splits work into small module slices and proves each slice with two verification gates.
+
+1. Module acceptance verification: proves the changed module contract.
+2. Surface integration verification: proves behavior through the real surface, such as CLI, HTTP, browser, or file artifacts.
+
+Before a slice mutates external state, Cairn records and runs the closest available dry-run or check mode. Verification is bounded: each slice gets two verification passes by default, then the agent records a blocker or splits the slice instead of continuing an open-ended loop.
+
+Cairn also treats tool readiness as part of the work. LSP, typecheck, lint, dry-run, and verification tools are checked against the repository stack. If a required tool is missing, Cairn attempts project-local or repository-native installation before accepting a fallback.
+
+## LazyCodex Attribution
+
+Cairn is influenced by LazyCodex (`https://github.com/code-yeongyu/lazycodex`). The borrowed ideas are the installable agent-harness shape, Codex hook trust/setup handling, project memory, planning skills, executable workflow commands, diagnostics, and skill/agent packaging across local agent surfaces.
+
+Cairn intentionally diverges from LazyCodex in the execution policy. It does not adopt LazyCodex's role-chain execution model or open-ended completion loops. Cairn uses Light/Heavy Path triage, bounded `explorer`/`worker` delegation, two verification gates, and explicit stop conditions instead.
+
+## Complexity Triage
+
+Every implementation task passes complexity triage first, before agent, plugin, or delegated workflow guidance. Triage is decided from repository exploration, expected change scope, and risk signals without asking the user.
+
+- Light Path: narrow changes inside existing architecture layers. This is the default. Implement directly or use one bounded `worker`, then keep the 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, or explicit extra-care request.
+
+The selected path and rationale are recorded in `docs/plan/<topic>.md` when a plan artifact exists. Even on Light Path, the two verification gates remain.
+
+## Tool Readiness
+
+`cairn toolcheck` inspects the current repository for JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go, and Rust stacks, then checks the matching LSP and verification tools.
+
+```sh
+cairn toolcheck
+cairn toolcheck --install
+```
+
+- `toolcheck` reports detected stacks and missing tools.
+- `toolcheck --install` attempts the closest project-local or repository-native install path, such as package-manager dev dependencies, Composer dev dependencies, `uv`, Java LSP bootstrap, `go install`, or `rustup component add`.
+- Cairn plans record detected stack, required tools, install commands, and blockers.
+- A missing LSP server is not a valid reason to skip precise codebase exploration until installation or an equivalent symbol-aware fallback has been attempted.
+
+## Dry-Run And Loop Policy
+
+- Migrations and database changes use `--pretend`, dry-run, schema diff, rollback feasibility checks, or the closest repository-native equivalent before write/apply commands.
+- Package, release, infrastructure, deployment, code generation, and formatting work use check, plan, diff, validate, or dry-run modes before mutating state when available.
+- If no dry-run exists, the plan records that fact and selects the smallest reversible command or test artifact available.
+- If a verification gate fails, Cairn diagnoses once, shrinks or splits the slice, and reruns both gates.
+- After two failed verification passes for the same slice, Cairn records the blocker in `docs/plan/<topic>.md` instead of continuing a repeated loop.
+
+## Model Guidance
+
+Cairn only applies model-specific adjustment to Claude-family and Codex-family models.
+
+- Claude-family: useful for long context, policy interpretation, and plan/evidence review.
+- Codex-family: useful for small implementation slices, explicit file edits, command-based verification, and bounded `worker` tasks.
+
+Detailed guidance lives in `docs/model-guidance/README.md`, `docs/model-guidance/claude.md`, and `docs/model-guidance/codex.md`.
+
+## Repository Artifacts
+
+The harness creates and maintains these files at the target repository root.
+
+- `MEMORY.md`: short index of persistent domain knowledge.
+- `docs/memory/*.md`: detailed knowledge by domain.
+- `docs/model-guidance/*.md`: Claude and Codex model adjustment guidance.
+- `PLAN.md`: short index of active and completed work topics.
+- `docs/plan/*.md`: detailed execution plans.
+
+Root files stay short and details move under `docs/`, so agents only read the context they need.
+
+## Commands
+
+The published package can be executed with `bunx` or globally installed `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
+```
+
+After global installation, short commands are also available.
+
+```sh
+bun add -g cairn-ai
+cairn install
+cairn upgrade
+cairn doctor
+cairn uninstall
+cairn toolcheck
+```
+
+- `cairn install`: installs the plugin into the Codex marketplace cache and configures hook trust state, Claude Code mirror files, and Antigravity skills/workflows.
+- `cairn upgrade`: updates the installation, hook trust state, Claude Code mirror files, and Antigravity skills/workflows from the current source.
+- `cairn doctor`: diagnoses Codex settings, installation, hook trust state, Claude Code mirror files, and Antigravity mirror files.
+- `cairn uninstall`: removes Cairn-added Codex settings, cache, Claude Code mirror files, and Antigravity mirror files.
+- `cairn toolcheck`: detects repository stacks and checks or installs required LSP and verification tools.
+- `cairn-memory`: explores domain knowledge and updates `MEMORY.md`.
+- `cairn-plan`: creates a decision-complete plan under `docs/plan/`.
+- `cairn-work`: executes the next module slice in the current `PLAN.md` with two verification gates.
+- `cairn-review`: reviews completed slices against plan, memory, and evidence.
+
+Install and upgrade create `*.cairn-backup-*` backups before modifying `~/.codex/config.toml`. The source plugin manifest stays validator-friendly; only the installed cache copy gets a `hooks` field to activate Codex hooks.
+
+Codex uses `skills/` and `commands/`. Claude Code uses mirrored commands and agent definitions under `.claude/`. Antigravity uses `.agents/workflows` and global skills mirrors.
+
+## Antigravity Compatibility
+
+Antigravity supports `SKILL.md`-based Agent Skills and Workflows invoked as `/workflow-name`. Cairn installs these paths for that surface.
+
+- 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 are not ported to Antigravity. Instead, the same planning, memory, complexity triage, and two-gate verification procedures run through Skills and Workflows. Set `ANTIGRAVITY_HOME` or `ANTIGRAVITY_CLI_HOME` to override paths.
+
+## Locale Policy
+
+Cairn's reusable instructions are written in English for global use. User-visible output should follow the configured OS locale unless the user explicitly asks for another language. The CLI localizes common messages for `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de`, and `pt`, and falls back to English for unsupported locales. Codex hook `statusMessage` text remains static English, while hook command output is English or Korean.
+
+## Delegation
+
+- `explorer`: handles read-only codebase discovery, impact analysis, pattern searches, and read-only verification when available.
+- `worker`: handles bounded implementation or verification tasks with clear file ownership.
+- Main session: keeps urgent blocking work local when the next step depends immediately on the result.
+
+Every delegation prompt uses six sections: TASK, EXPECTED OUTCOME, REQUIRED TOOLS, MUST DO, MUST NOT DO, CONTEXT.