# Generated Multi-CLI Adapters (Pillar 5 — portability lock)

Everything in this directory **except this README** is generated by:

```
node tools/build/generate-adapters.js
```

from the root `registry.yaml` (`targets.adapters[]` + pack declarations) plus
the hand-authored sections in `tools/build/adapters.config.js`.

## ADOPTED — the root files are now generated too

Since v0.11.0 the generated adapters are **load-bearing**: the live repo-root
`AGENTS.md` (spine), `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/bmad-plus.mdc`,
`.codex/AGENTS.md`, `.opencode/AGENTS.md` and `CONVENTIONS.md` are written by

```
node tools/build/generate-adapters.js --adopt
```

and drift-gated by

```
node tools/build/generate-adapters.js --check --adopt
```

(also enforced by `tests/unit/generate-adapters.test.js`). This directory
remains as a PREVIEW target so you can inspect what a registry/config change
produces before adopting it (`git diff` on this dir vs the root files).

## Where content comes from

- **Derived facts** (product/version, pack list, every count) — `registry.yaml`.
  No human ever types a count, so adapters cannot drift or lie.
- **Hand-authored project instructions** (agent roster, skills paths, project
  structure, communication, commit rules, README i18n rule, Karpathy memory
  protocol) — `tools/build/adapters.config.js`. The pre-adoption root
  CLAUDE.md/GEMINI.md/AGENTS.md content was folded there verbatim (union of
  all three, nothing dropped).
- **Tool notes** — `TOOL_NOTES` in `tools/build/generate-adapters.js`.

## How to change the root configs

1. Edit `tools/build/adapters.config.js` (instructions) or `registry.yaml`
   (facts/targets) — NEVER the generated files themselves.
2. Regenerate: `node tools/build/generate-adapters.js --adopt` (previews:
   run without `--adopt`).
3. `node tools/build/generate-adapters.js --check --adopt` must pass.

A safety guard refuses `--adopt` over a root file that lacks the
`AUTO-GENERATED` marker (i.e. hand-written content that was never folded in);
override only with `--force` after folding the content into the config.

## What each file is

One generated file per unique `targets.adapters[].file` entry, plus the spine
(`targets.spine`). Tools that share a file (e.g. `gemini-cli` + `antigravity`
→ `GEMINI.md`) are grouped into a single adapter with one "Tool notes" block
per tool. Every adapter:

- points the tool at the **spine** (`targets.spine`, currently `AGENTS.md`) as
  the single source of truth,
- adds tool-specific invocation notes,
- inlines the full hand-authored project instructions (most tools auto-load
  only their own file, so a thin pointer would silently lose behavior),
- lists pack/agent facts **computed** from `registry.yaml`.

## Drift check

```
node tools/build/generate-adapters.js --check          # this preview dir
node tools/build/generate-adapters.js --check --adopt  # the live root files
```

Each exits 1 if any file no longer matches what the registry + config generate
(same contract as `tools/build/generate.js --check` for `packs.js`). Both are
suitable for CI. Comparisons are EOL-insensitive so Windows checkouts do not
false-positive.