AGENTS.md

1# Caliber
2 
3`@rely-ai/caliber` — AI context infrastructure CLI. Scores, generates, and syncs agent configs.
4 
5## Commands
6 
7```bash
8npm run build        # tsup → dist/
9npm run dev          # watch mode
10npm run test         # vitest run
11npm run lint         # eslint src/
12npx tsc --noEmit     # type check
13```
14 
15## Architecture
16 
17**Entry**: `src/bin.ts` → `src/cli.ts` · **Build**: `tsup.config.ts` · **Test**: `vitest.config.ts` · **Lint**: `eslint.config.js`
18 
19**Commands** (`src/commands/`): `init.ts` · `score.ts` · `refresh.ts` · `regenerate.ts` · `config.ts` · `hooks.ts` · `learn.ts` · `recommend.ts` · `sources.ts` · `undo.ts` · `status.ts` · `setup-files.ts`
20 
21**LLM** (`src/llm/`): `anthropic.ts` · `vertex.ts` · `openai-compat.ts` · `cursor-acp.ts` · `claude-cli.ts` · `types.ts` · `config.ts` · `model-recovery.ts`
22 
23**AI** (`src/ai/`): `generate.ts` · `refine.ts` · `refresh.ts` · `detect.ts` · `learn.ts` · `score-refine.ts` · `prompts.ts`
24 
25**Fingerprint** (`src/fingerprint/`): `index.ts` · `file-tree.ts` · `code-analysis.ts` · `sources.ts` · `cache.ts`
26 
27**Scoring** (`src/scoring/`): `index.ts` · `constants.ts` · `display.ts` · Checks: `checks/existence.ts` · `checks/quality.ts` · `checks/grounding.ts` · `checks/accuracy.ts` · `checks/freshness.ts` · `checks/bonus.ts`
28 
29**Writers** (`src/writers/`): `index.ts` · `claude/index.ts` · `cursor/index.ts` · `codex/index.ts` · `github-copilot/index.ts` · `staging.ts` · `manifest.ts` · `backup.ts`
30 
31**Lib** (`src/lib/`): `hooks.ts` · `state.ts` · `resolve-caliber.ts` · `builtin-skills.ts` · `sanitize.ts` · `git-diff.ts`
32 
33**Other**: `src/constants.ts` · `src/test/setup.ts` · `github-action/` · `packages/mcp-server/` · `packages/shared/` · `apps/`
34 
35## Conventions
36 
37- ESM with `.js` extensions · Tests in `__tests__/` dirs · `unknown` over `any`
38- Conventional commits (`feat:`, `fix:`, `refactor:`) · Dev: `next`, Stable: `master`
39- Providers implement `LLMProvider` from `src/llm/types.ts`
40- Writers in `src/writers/claude/index.ts` · `src/writers/codex/index.ts` return `string[]`
41- Scoring checks in `src/scoring/checks/` return `Check[]`
42- No hardcoded mappings — LLM-driven via `src/ai/detect.ts`
43- `collectFingerprint()` async with LLM enrichment (`src/fingerprint/index.ts`)
44- MCP server workspace: `packages/mcp-server/`
45 
46<!-- caliber:managed:pre-commit -->
47## Before Committing
48 
49**IMPORTANT:** Before every git commit, you MUST ensure Caliber syncs agent configs with the latest code changes.
50 
51First, check if the pre-commit hook is already installed:
52```bash
53grep -q &quot;caliber&quot; .git/hooks/pre-commit 2&gt;/dev/null && echo &quot;hook-active&quot; || echo &quot;no-hook&quot;
54```
55 
56- If **hook-active**: the hook handles sync automatically — just commit normally. Tell the user: "Caliber will sync your agent configs automatically via the pre-commit hook."
57- If **no-hook**: run Caliber manually before committing:
58  1. Tell the user: "Caliber: Syncing agent configs with your latest changes..."
59  2. Run: `caliber refresh && git add CLAUDE.md .claude/ .cursor/ .cursorrules .github/copilot-instructions.md .github/instructions/ AGENTS.md CALIBER_LEARNINGS.md 2>/dev/null`
60  3. After it completes, briefly tell the user what Caliber updated. Then proceed with the commit.
61 
62If `caliber` is not found, tell the user: "This project uses Caliber for agent config sync. Run /setup-caliber to get set up."
63<!-- /caliber:managed:pre-commit -->
64 
65<!-- caliber:managed:learnings -->
66## Session Learnings
67 
68Read `CALIBER_LEARNINGS.md` for patterns and anti-patterns learned from previous sessions.
69These are auto-extracted from real tool usage — treat them as project-specific rules.
70<!-- /caliber:managed:learnings -->
71