---
name: agents
description: Always-loaded project anchor. Contains project identity, non-negotiables, key conventions, commands, and navigation pointer. This file survives context compaction — put critical rules here.
last_updated: 2026-04-07
---

# CAI — Coherence AI

## What This Is
A CLI and MCP server that keeps `.cai/` scaffold files in sync with the actual codebase — deterministic drift detection, back-pressure verification, correction learning, and a global pattern library for Claude Code, Cursor, Copilot, and OpenCode.

## Non-Negotiables
- Drift detection must stay deterministic — no AI calls, no network, millisecond-level runtime.
- Never overwrite user content outside of `<!-- cai:start -->` / `<!-- cai:end -->` markers.
- All auto-fix operations must be idempotent — running twice produces the same result.
- Strict TypeScript (`strict: true`) — no `any` in core logic, no implicit coercion.
- ESM only — no CommonJS fallbacks. Node >=20 required.

## Key Conventions
- All relative imports use `.js` extension (`import { foo } from "./bar.js"`).
- New checkers must be registered in both `AVAILABLE_DRIFT_CHECKERS` (array) AND `createDriftRegistry()` in `src/drift/registry.ts`.
- New `IssueCode` values go in the union in `src/types.ts` — never declared inline.
- `npm test` must pass before any release.

## Commands
- Build: `npm run build` (tsup)
- Dev: `npm run dev` (tsup --watch)
- Test: `npm test` (vitest run)
- Typecheck: `npm run typecheck` (tsc --noEmit)

## After Every Task
After completing any task: update `.cai/ROUTER.md` project state and any `.cai/` context files that are now out of date. If no pattern existed for this task type, create one in `.cai/patterns/`.

## Compact Instructions
Preserve across compaction: all Non-Negotiables, all Key Conventions, all Commands, and the navigation pointer to `.cai/ROUTER.md`.

## Navigation
Read `.cai/ROUTER.md` at the start of every session before doing anything else.