# Integrate CLAUDART with your agent (AI-native install) **You are an AI coding agent** (Claude Code, Codex, or similar) and your user linked this file because they want to **adopt or upgrade CLAUDART** in the current project. CLAUDART is a plain-Markdown operating layer for commands or skills, layered memory, persistent work, project knowledge, and specialized agents. Source of truth: (branch `main`). This file is a **protocol, not an installer**. Follow it top to bottom. It exists because a fresh-copy installer cannot safely reconcile custom instructions, live state, tasks, specifications, or project knowledge. > **Version-agnostic delta rule.** Never assume which CLAUDART release, feature set, or file layout the downstream project started from. Derive the delta during this run from current upstream, the current downstream tree, and upstream history only where history is actually needed. > > **Golden rule — read freely, write only what is approved.** NEVER overwrite, delete, or relocate user-authored content without showing the proposed change and receiving explicit approval. Default to preserving the user's work. > > **"Customized" means user-authored content, not every local difference.** A CLAUDART-shipped file whose local copy merely matches an older upstream state is stale, not custom. Upgrade stale template content; preserve and deliberately re-apply real project-specific additions. Never keep an older upstream value, such as a narrower permission or default, as a presumed customization or for safety; a difference is custom only when evidence shows the project authored it. > > **Mechanical verification first; semantic maintenance only when justified.** Every integration gets a bounded, read-only verification pass. Do not run doctor or tidy merely because files were installed or upgraded. Doctor is conditional and diagnostic; tidy rewrites live docs and state and runs only on a separate user request. > > **Integration validation precedence.** Step 4 governs this integration run. Generic first-run suggestions elsewhere do not make doctor or tidy mandatory here. --- ## Step 0 — Diagnose first, then fetch proportionally 1. Work from the project root. Run `git status --short` when Git is available, record unrelated work, and do not disturb it. 2. Inventory the shared project state and relevant AI paths: `.claudart/`, `.claude/`, `.codex/`, `.agents/skills/`, root or nested `CLAUDE.md`, root `AGENTS.md`, and any overlapping custom commands, agents, rules, memory, tasks, specs, knowledge, or documentation routes in the requested scope. 3. Resolve the target layers and optional modules: - explicit user choice wins; - otherwise default to the runtime already present; - if neither exists and the active agent runtime makes the choice obvious, state that assumption in the plan instead of asking unnecessarily; - if both are selected, classify each adapter independently and the shared state once; - record explicit module choices or exclusions. A general integration or update request permits recommending relevant modules in Step 2; it does not silently select them for installation, update, or removal. 4. Classify each selected layer: - **A — Clean adopt:** no meaningful AI operating layer exists yet; a bare loader file is allowed. - **B — Merge into an existing workflow:** the project already has its own agents, commands, rules, memory, or work conventions. - **C — Upgrade an existing CLAUDART install:** recognizable CLAUDART files are already present. 5. Read `.claudart/VERSION` when present. Each line names the upstream commit its layer was installed or last reconciled from; a missing line or `unknown` means that layer has no recorded base. 6. Get current upstream into a new, empty directory that belongs to this run alone: the host's session scratch directory when it provides one, otherwise a directory made with `mktemp -d`. Integrations in other projects may run at the same time, so never use a fixed shared path. Below, `` stands for that directory's literal absolute path; write the path itself in every command rather than a shell variable. For Scenario A, or the initial pass for Scenario B: ```bash git clone --depth 1 --branch main https://github.com/vankhaivn/Claudart ``` For Scenario C, or whenever a recorded base exists, clone full history. For Scenario B, deepen only when a real collision needs stale-vs-custom evidence: ```bash git clone --branch main https://github.com/vankhaivn/Claudart # Or, after a shallow clone: git -C fetch --unshallow ``` When the user names an upstream commit, clone full history and check it out with `git -C checkout --detach `; stop if `git -C merge-base --is-ancestor origin/main` fails. That commit is then the current upstream for every step below. If cloning is unavailable, fetch current raw files on demand from `https://raw.githubusercontent.com/vankhaivn/Claudart/
/`. Without history, preserve ambiguous differences and show the exact uncertainty instead of guessing. 7. Inspect the current `modules/` inventory and brief module descriptions. Recommend a module when the request or observed project gives it a concrete purpose; for example, existing discovery material or competing documentation owners can make Project Docs relevant. Respect an explicit core-only scope or module exclusion. This does not require a full docs audit or loading every module's detailed references. 8. Enumerate the actual selected core-layer and proposed optional-module payload from current upstream. Read `install.sh` as a payload and relocation reference, plus the loaders and every file in the proposed dependency closure. README, workflow, and contributing docs are orientation only; read them only when a real ambiguity requires them. 9. Treat `install.sh` as a payload reference, not a merge tool. Do not execute it during Scenario B or C, do not use `--force`, and do not run any write-capable maintenance workflow before approval. ## What CLAUDART contains This map is orientation only; the current source tree and its references are authoritative. **Shared project state** (`.claudart/`, required in every installation): - `OWNER.md`, `CONTEXT.md`, append-only `JOURNAL.md`, and the optional single-use `HANDOFF.md`; - `knowledge/INDEX.md` plus project-owned maps and topics; - `tasks/` and `specs/`, with indexes, complete workspaces, archives and artifacts; - `VERSION`, install metadata with one `: ` line per installed payload (`claude`, `codex`, `project-docs/claude`, `project-docs/codex`). Only the installer and this protocol write it. Only empty seeds are distributed. Existing state is project-owned and preserved even during a forced adapter refresh. Never install a handoff or upstream work record. The state directory is not auto-imported; startup reads bounded indexes and metadata, with details on demand. **Claude adapter** (root `CLAUDE.md` + `.claude/`): - `.claude/CLAUDE.md` is the source template for the canonical downstream root `CLAUDE.md`; do not install a duplicate under `.claude/`; - `.claude/skills/` (one folder per workflow, with any bundled scripts or references), `.claude/agents/`, path-scoped `.claude/rules/`, conditional `.claude/references/`, and read-only checker helpers under `.claude/scripts/`. **Codex adapter** (`.codex/` + `.agents/skills/`): - native skills under `.agents/skills/cda-*`, including referenced support files; - `.codex/guidelines/`, `.codex/references/`, `.codex/scripts/`, `.codex/agents/`, and `.codex/config.toml`; - `.codex/AGENTS.md` as the source template for the canonical downstream root `AGENTS.md`. **Optional modules:** install only when selected. Project Docs lives under `modules/project-docs/` in upstream; overlay its `.claude/` and/or `.agents/` payload at the downstream root for the selected runtimes. This adds `.claude/skills/cda-project-docs/` or `.agents/skills/cda-project-docs/` with their references and templates. Do not copy the module's source wrapper or packaging README into the project. It supplies documentation-lifecycle guidance; it does not install a documentation tree or own a project's existing documentation by default. Include the selected module's output templates and filled examples in its resource closure, retaining their module-relative paths. They are reusable authoring resources, not live project docs: do not instantiate templates or apply the example snippets during integration. Preserve custom resource edits under the same reconciliation rules as other instructions. When integrating both adapters, preserve intent parity without forcing byte identity where tool mechanics differ. Both loaders use `.claudart/` as the single state authority and the actual host's tools for execution. Switching adapters preserves task/spec scope, approval, evidence and review gates; provenance metadata does not select a store. No fallback store or automatic multi-writer synchronization is installed. Task workspaces use `.claudart/tasks/YYYY-MM-DD-NNN-/TASK.md` and `.claudart/tasks/done//TASK.md`. `TASK.md` is the only required file; `artifacts/` is created only for a concrete task need. Install only empty task seeds, never live upstream tasks or test fixtures. Preserve downstream workspace contents and storage/Git policies; do not bulk-read, extract, or normalize attachments during integration. The current upstream format is the standard: Claude uses root `CLAUDE.md` downstream, with `.claude/CLAUDE.md` retained only as the upstream source template. No compatibility layer or migration framework is installed; downstream projects adapt existing work to the current format deliberately. Report format mismatches and preserve the original files; any requested relocation still requires the explicit, path-specific approval below. Merely upgrading commands does not authorize moving or deleting task history. ## Step 1 — Derive the current delta Before proposing writes, distinguish: - **template-owned protocol:** commands, skills, rules, guidelines, agents, scripts, config, and other files intended to track current upstream; - **merge-owned indexes:** loaders and indexes whose project routes and ordering must be preserved; - **live state:** shared `.claudart/OWNER.md`, `.claudart/CONTEXT.md`, `.claudart/JOURNAL.md`, handoffs, task workspaces and attachments, spec bodies and mission folders, knowledge topics/maps, and equivalent project-owned state; - **project-owned custom content:** instructions or workflows authored specifically for this project. Treat an optional module as a selected dependency closure, separate from the core layer. Classify existing discovery commands and references using the stale-vs-custom test below. List any proposed retirement in the reconciliation plan, identifying its replacement or the chosen core-only outcome. Generated discovery output, `docs/project/`, and other project documentation are live project-owned content; retiring a template command does not authorize deleting its output. ### Scenario A — Clean adopt Copy the current shared seeds once, selected adapter payload, and approved optional-module payload. Splice CLAUDART routes into any existing canonical or overlapping loader; never replace project-authored loader content. For missing live-state files, create only the current empty seed/header. For Claude, place the source template `.claude/CLAUDE.md` at the canonical downstream root `CLAUDE.md`; treat an existing downstream `.claude/CLAUDE.md` as a legacy same-concept/different-file collision that must be reconciled or explicitly retired, not left as a competing loader. For Codex, place `.codex/AGENTS.md` at root `AGENTS.md` and avoid competing loaders. Scenario A is the fast path: do not inspect full history and do not schedule doctor or tidy when Step 4 verification can prove the installation mechanically. ### Scenario B — Merge into an existing workflow For each current CLAUDART concept: - **Upstream-only path** → propose adding it and explain its role. - **Same concept, different file** → do not overwrite; propose keeping one, merging responsibilities, or keeping both under distinct names and triggers. - **Same filename** → merge sections, preserving project-authored content and ordering. - **Competing memory or work system** → map responsibilities and let the user choose one authority; never silently leave two systems owning the same job. - **Project-only path** → preserve it unless retirement or relocation is explicitly approved. Derive the complete dependency closure for each accepted core concept and selected module from current upstream. Include every selected-layer file that defines, routes, invokes, validates, installs, or mirrors it. Preserve unselected module paths and unrelated legacy discovery or documentation content. ### Scenario C — Reconcile an existing CLAUDART install Diff the actual installed state against current upstream; do not assume all local files came from one revision. Classify every relevant core path and selected module path: - **Equivalent** → keep and record `unchanged`. - **Upstream-only** → inspect references and, when needed, history to distinguish an addition from a rename, move, split, consolidation, or replacement. - **Stale template copy** → local content matches an earlier upstream state and has no user-authored additions; propose replacing it with current upstream verbatim. - **Genuinely diverged** → use current upstream as the base and deliberately re-apply or relocate the exact project-authored additions. - **Downstream-only** → preserve project-authored paths; for former template paths, propose an explicit relocation or retirement and identify the current owner. - **Live state** → preserve its body; reconcile only its current contract or routing through the workflow that owns it. When the layer has a recorded base, compare three versions of each template-owned path: the base (`git -C show :`), the local file, and current upstream. Map each installed path to its upstream source, for example root `CLAUDE.md` to `.claude/CLAUDE.md` and Project Docs files to `modules/project-docs/`. - Local equals base → stale; propose current upstream verbatim. - Local differs from base → only that difference is project content; carry it onto current upstream (for example with `git merge-file`) and show any conflict. - For every path upstream changed, cite the reason from `git -C log --format='%h %s%n%b' ..HEAD -- ` in the plan. Without a recorded base, apply the stale-vs-custom test narrowly: 1. Never call a file custom merely because it differs from current upstream. 2. Point to the exact local lines believed to be user-authored. 3. Use history only for the relevant path or phrase, for example: ```bash git -C log --all --follow -- git -C log -S'' --all -- ``` 4. If local content matches a past upstream state and contains no project-specific addition, it is stale. 5. If evidence remains ambiguous, show the specific lines with the upstream commit that introduced the current value and ask about those lines, not the entire file. Never resolve the ambiguity by keeping the older value. Produce a reconciliation report covering unchanged, upstream-only, stale replacements, genuine custom merges, moves or consolidations, retirement candidates, preserved downstream-only paths, untouched live state, and review-needed ambiguities. Preserve every live knowledge topic, map, project-specific route, and unselected module. Do not retire customized legacy discovery or `docs/project/` content merely because current upstream no longer ships it; inspect it only when that retirement is in scope and identify its replacement owner. ## Step 2 — Present the plan and wait Before writing, classify the planned result under these actions: - `add`; - `replace verbatim`; - `merge`; - `relocate`; - `retire`; - `preserve unchanged`; - `skip`; - `review-needed`. List the selected layers and optional modules, then exact paths for every write, merge, relocation, retirement, or ambiguity. Unchanged paths may be grouped by tree and count. For a collision-free Scenario A tree copied verbatim, you may report it as one grouped add with a generated file count instead of explaining every file; still list loader placement and live-state seeds separately. Any collision or non-verbatim action must be path-specific. Separate requested module changes from optional recommendations. For each recommendation, state the project-specific reason, runtime files it would add or change, and whether later `adopt` work would be useful. Ask the user to include or exclude it when approving the plan; an already explicit choice needs no repeat confirmation. Only modules included in the approved plan may change. Installing Project Docs does not itself authorize generating, moving, or compacting live docs or knowledge. For each merge, identify what current upstream content will be introduced and what downstream content will be preserved or relocated. For each retirement, identify the replacement or current owner. Mark live-state files explicitly as preserved. Also state the validation profile: mandatory fast verification, any already-justified targeted semantic review, whether a full doctor trigger exists, and that tidy will not run as part of integration. Say that the verified writes will become one local commit, so the user can ask to review the diff first instead. Wait for explicit approval before writing. Approval for this plan does not pre-approve additional normalization discovered later. ## Step 3 — Apply only the approved change - Re-check `git status --short` and protect unrelated or parallel work. - Apply the approved dependency closure atomically per concept where practical. - Do not add, remove, or update an optional module unless that module was explicitly selected in the approved plan. - Keep template-owned files verbatim unless an explicit merge was approved. - Prefer relocating project-specific additions to project-owned rules, guidelines, knowledge, or loader sections so core protocol files can track upstream cleanly. - Splice loaders and indexes; never wholesale-replace project routing or ordering. - Never overwrite existing `OWNER.md`, `CONTEXT.md`, or `JOURNAL.md`; never import, overwrite, or create `HANDOFF.md`; never replace task workspaces or attachments, spec mission folders, knowledge topics, or maps with template content. - The one exception is a state file's header, the instructions before its first entry. When the header of `OWNER.md`, `CONTEXT.md`, or `JOURNAL.md` differs from the current seed and is not project-authored, list replacing only that header in the plan; every entry stays byte-identical. - Create only missing seeds, indexes, or placeholders that were listed and approved. - Set `.claudart/VERSION` to the upstream commit used (`git -C rev-parse HEAD`) for each layer fully reconciled to current upstream, keeping every other line. A selected layer whose payload upstream did not change since its recorded base is fully reconciled too. Leave a partially reconciled layer's line unchanged. List this write in the plan. - Do not touch `.env`, secrets, ignored private files, or unrelated project files. - If an unplanned conflict or required write appears, stop before that write and present an amended path-level plan. - Do not commit during the writes; Step 4.4 commits after verification. Never push or merge. ## Step 4 — Validate and hand off ### 4.1 Mandatory fast verification — read-only Run bounded mechanical checks against the selected layers and changed dependency closure. Validation may write inside `` or another directory this run created, but it must not mutate the project tree. 1. Check scope and patch integrity: ```bash git status --short git diff --name-status git diff --check ``` Skip Git-specific checks only outside a Git repository. Confirm every changed path was approved and unrelated changes remain untouched. 2. Confirm every approved add, replacement, merge, relocation, and retirement reached its intended final path. 3. Compare every supposedly verbatim template-owned file with current upstream using `cmp`, checksums, or `git diff --no-index`, accounting only for approved relocation. Any unexplained drift fails verification. 4. For merged loaders and indexes, confirm both the required current CLAUDART routes and the project-authored sections identified in the plan remain present. Resolve actual Claude `@` imports relative to each importing file, including nested targets: `@.claude/rules/ai-behavior.md` is relative to the installed root `CLAUDE.md`. Preserve conditional plain routes and narrow rule scopes; do not make every workflow global or require an automatic import for every rule. An intentionally empty task/spec seed may have no glob matches. Verify core and selected module references are included in the dependency closure and installed at the paths used by their entrypoints. 5. Confirm referenced commands, skills, rules, guidelines, agents, scripts, indexes, and config paths exist; no loader, rule, or guideline auto-loads `JOURNAL.md` or `HANDOFF.md`; existing live-state bodies were not replaced, and an approved header replacement changed nothing below that header; changed shell scripts pass `bash -n`; changed command/skill/agent/rule/guideline frontmatter still satisfies the current upstream contract; and mirrored contracts remain consistent when both layers changed. 6. Run the current upstream read-only `doctor-check.sh` for each selected layer. This provides the mechanical structure, metadata, local-reference, and size baseline, and invokes the existing knowledge checker once. Do not run knowledge validation separately afterward. With the current interface: ```bash bash /.claude/scripts/doctor-check.sh \ --root "$PWD" --layer claude bash /.codex/scripts/doctor-check.sh \ --root "$PWD" --layer codex ``` Run only selected layers. Keep the trusted source scripts and their adjacent helpers together; do not execute an unreviewed downstream checker copy. If current upstream `--help` differs, follow it instead. Exit `1` means findings; exit `2` means incomplete verification or a runtime/usage failure. Exit `0` covers the declared mechanical checks, not semantic correctness. Use the report for checks it covers above, and inspect only the remaining patch-specific obligations; do not duplicate its scan. Additional project Markdown is opt-in with `--include`, and is not required merely because integration occurred. A mechanical failure may be fixed immediately only when its fix is already inside the approved plan. Any additional write requires a new proposed diff and explicit approval. ### 4.2 Semantic review and doctor are conditional Do **not** run doctor solely because integration occurred. If fast verification passes and none of the triggers below exists, stop after the fast verification. Scenario A defaults to this fast path; Scenario B and C also use it for purely mechanical additions, verbatim stale-template replacements, and approved relocations that do not change semantic ownership. When semantic judgment is needed, first review only the changed files and their dependency closure. Run the selected layer's full read-only doctor once only when at least one trigger exists: - competing instructions, routing, memory, or work systems were merged; - project-authored content moved between rules/guidelines, knowledge, state, tasks, specs, or loaders; - rule scope, agent responsibility, task/spec lifecycle, or knowledge ownership changed semantically; - history left a material `review-needed` ambiguity; - deterministic verification found a problem that cannot be decided mechanically; - the affected contract is repository-wide; - the user explicitly requested a full health audit. When triggered, run `/cda-doctor` for Claude or `$cda-doctor` for Codex. Doctor is diagnostic only. Report findings; do not turn them into automatic writes. ### 4.3 Tidy is a separate request Never run `/cda-tidy` or `$cda-tidy` as part of integration. Integration preserves live state and project docs; cleaning them is a separate request the user makes after the integration is committed, in a new session so the updated instructions are loaded. When doctor findings or the user's goals point to that cleanup, say so in the report. ### 4.4 Report the result Summarize the scenario, selected layers and modules, paths added/replaced/merged/relocated/retired/preserved/skipped/review-needed, verification commands and results, why doctor was or was not run, and any normalization still awaiting approval. When verification passes and the project is a Git repository, commit only the approved integration paths as one local commit in the repository's message convention, unless the repository's Git policy or the user's instructions forbid it or the user asked to review the diff first. Report the commit, or why the integration stays uncommitted. This protocol is idempotent: a later run derives a fresh delta from the then-current upstream and downstream state. ## Cleanup After all comparisons and validation are complete, remove `` and any other directory this run created, by their literal paths. Never remove a directory this run did not create.