feat: add init command for AI agent adoption (#34)

## Why

codebase-intelligence has the data (architecture, impact, risk metrics)
— but AI coding agents default to grep/read instead of querying it.
`init` closes that adoption gap. Native TypeScript, zero new runtime
deps, no LLM.

## What

`codebase-intelligence init [path]` writes an **idempotent, marked**
instruction block ("query CI before grep/read") into each agent's repo
file, and installs a portable skill:

| Layer | Target |
|---|---|
| Repo instructions | `AGENTS.md`, `CLAUDE.md`,
`.cursor/rules/codebase-intelligence.mdc`,
`.github/copilot-instructions.md`, `GEMINI.md`, `CONVENTIONS.md` |
| Portable skill | `~/.claude/skills/codebase-intelligence/SKILL.md` |
| Registry | `skills/codebase-intelligence/SKILL.md` → `ags install` /
`npx skills add` |

Flags: `--agents <list>` (subset), `--no-skill`, `--json`.

## Safety / correctness

- `upsertManagedBlock()` is pure + idempotent. Only content between
`<!-- codebase-intelligence:start -->` / `:end` is ever touched —
**existing user content is preserved**.
- Single source of truth: one `renderBlock()`/`renderSkill()`; 6 agents
are a thin path+preamble table.
- Drift-guard test ties the committed `SKILL.md` to `renderSkill()`.

## Tests / gates

- 18 new tests (real fs, temp dirs — no mocks): create / append /
replace / idempotent / preserve-outside / subset /
merge-without-clobber.
- Full suite: **310 passed**. lint / typecheck / build all green.

## Docs

README (Agent Adoption section + TOC + Features),
`docs/cli-reference.md`, `docs/architecture.md`, `llms.txt`,
`llms-full.txt`, and a new `CHANGELOG.md`.

## Follow-up (manual)

skills.sh **directory listing** needs a logged-in web submit at
agentskill.sh; the `SKILL.md` is spec-valid so `npx skills add
github.com/bntvllnt/codebase-intelligence` works once merged.

Author: bntvllnt

CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **`init` command** — agent adoption layer. `codebase-intelligence init [path]` writes
+  an idempotent, marked instruction block ("query CI before grep/read") into each
+  agent's repo file (`AGENTS.md`, `CLAUDE.md`,
+  `.cursor/rules/codebase-intelligence.mdc`, `.github/copilot-instructions.md`,
+  `GEMINI.md`, `CONVENTIONS.md`) and installs a portable skill to
+  `~/.claude/skills/codebase-intelligence/SKILL.md`.
+  - `--agents <list>` to target a subset of agents (default: all).
+  - `--no-skill` to skip the global skill install.
+  - `--json` for machine-readable output.
+  - Writes are idempotent — only content between the
+    `codebase-intelligence:start`/`:end` markers is ever touched; existing user content
+    is preserved.
+- **`src/install/` module** — managed-block upsert engine, per-agent target registry,
+  and shared block/skill content (single source of truth).
+- **Registry skill** — `skills/codebase-intelligence/SKILL.md`, installable via
+  `ags install codebase-intelligence` or `npx skills add`.
+
+### Changed
+
+- Docs updated for the new command: `README.md`, `docs/cli-reference.md`,
+  `docs/architecture.md`, `llms.txt`, `llms-full.txt`.
+
+## [2.3.0] - 2026
+
+Baseline for this changelog. For release history prior to and including 2.3.0, see the
+[git tags](https://github.com/bntvllnt/codebase-intelligence/tags) and commit history.
+
+[Unreleased]: https://github.com/bntvllnt/codebase-intelligence/compare/v2.3.0...HEAD
+[2.3.0]: https://github.com/bntvllnt/codebase-intelligence/releases/tag/v2.3.0

CLAUDE.md

@@ -20,6 +20,7 @@ src/
   process/index.ts    <- Entry point detection + call chain tracing
   community/index.ts  <- Louvain clustering
   persistence/index.ts <- Graph export/import to .code-visualizer/
+  install/index.ts    <- Agent adoption: managed-block engine + per-agent files + skill (init)
   cli.ts              <- CLI entry point (commander)
 docs/
   architecture.md     <- Pipeline, module map, data flow, design decisions

README.md

@@ -42,6 +42,7 @@ claude mcp add -s user -t stdio codebase-intelligence -- npx -y codebase-intelli
 - [Features](#features)
 - [Installation](#installation)
 - [CLI Usage](#cli-usage)
+- [Agent Adoption](#agent-adoption)
 - [MCP Integration (Secondary)](#mcp-integration-secondary)
 - [Metrics](#metrics)
 - [Architecture](#architecture)
@@ -54,14 +55,15 @@ claude mcp add -s user -t stdio codebase-intelligence -- npx -y codebase-intelli
 
 ## Features
 
-- **15 CLI commands** for architecture analysis, dependency impact, dead code detection, and search
+- **16 CLI commands** for architecture analysis, dependency impact, dead code detection, search, and agent setup
 - **Machine-readable JSON output** (`--json`) for automation and CI pipelines
 - **Auto-cached index** in `.code-visualizer/` for fast repeat queries
 - **11 architectural metrics** — PageRank, betweenness, coupling, cohesion, tension, churn, complexity, blast radius, dead exports, test coverage, escape velocity
 - **Symbol-level analysis** — callers/callees, symbol importance, impact blast radius
 - **BM25 search** — ranked keyword search across files and symbols
 - **Process tracing** — detect entry points and execution flows through the call graph
 - **Community detection** — Louvain clustering for natural file groupings
+- **Agent adoption** — `init` writes per-agent instruction files + installs a skill so AI agents query CI before grep/read
 - **MCP parity (secondary)** — same analysis available as 15 MCP tools, 2 prompts, and 3 resources
 
 ## Installation
@@ -104,6 +106,7 @@ codebase-intelligence <command> <path> [options]
 | `rename` | Reference discovery for rename planning |
 | `processes` | Entry-point execution flow tracing |
 | `clusters` | Community-detected file clusters |
+| `init` | Make AI agents use CI — writes per-agent instruction files + installs the skill |
 
 ### Useful flags
 
@@ -116,6 +119,39 @@ codebase-intelligence <command> <path> [options]
 
 For full command details, see [docs/cli-reference.md](docs/cli-reference.md).
 
+## Agent Adoption
+
+codebase-intelligence has the data — but AI agents only benefit if they actually
+*query* it instead of defaulting to grep/read. `init` closes that gap.
+
+```bash
+codebase-intelligence init        # current repo, all agents + skill
+codebase-intelligence init ./repo --agents claude,agents
+codebase-intelligence init --no-skill
+```
+
+It writes an idempotent, marked instruction block ("query CI before grep/read") into
+each agent's native file, and installs a portable skill:
+
+| Layer | Target |
+|---|---|
+| Repo instructions | `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/codebase-intelligence.mdc`, `.github/copilot-instructions.md`, `GEMINI.md`, `CONVENTIONS.md` (Aider) |
+| Portable skill | `~/.claude/skills/codebase-intelligence/SKILL.md` |
+
+Writes are idempotent — only content between the
+`<!-- codebase-intelligence:start -->` / `:end` markers is ever touched, so re-running
+is safe and your own edits are preserved.
+
+### Install the skill directly
+
+The skill is also published to the [skills.sh](https://www.skills.sh/) registry:
+
+```bash
+ags install codebase-intelligence
+# or
+npx skills add github.com/bntvllnt/codebase-intelligence
+```
+
 ## MCP Integration (Secondary)
 
 Running without a subcommand starts the MCP stdio server (backward compatible):
@@ -208,7 +244,8 @@ codebase-intelligence <command> <path>
 
 ## Release
 
-Publishing is automated through GitHub Actions.
+Publishing is automated through GitHub Actions. See [CHANGELOG.md](CHANGELOG.md) for
+release notes.
 
 ### Normal CI (before release)
 

docs/architecture.md

@@ -42,6 +42,7 @@ src/
   process/index.ts     <- Entry point detection + call chain tracing
   community/index.ts   <- Louvain clustering
   persistence/index.ts <- Graph export/import to .code-visualizer/
+  install/index.ts     <- Agent adoption: managed-block engine + per-agent file targets + skill
   server/graph-store.ts <- Global graph state (shared by CLI + MCP)
   cli.ts               <- Entry point, CLI commands + MCP fallback
 ```

docs/cli-reference.md

@@ -1,6 +1,6 @@
 # CLI Reference
 
-15 commands for terminal and CI use. Full parity with MCP tools. All commands auto-cache the index to `.code-visualizer/`.
+16 commands for terminal and CI use. The 15 analysis commands have full parity with MCP tools and auto-cache the index to `.code-visualizer/`; `init` sets up agent adoption.
 
 ## Commands
 
@@ -156,6 +156,20 @@ codebase-intelligence clusters <path> [--min-files <n>] [--json] [--force]
 
 **Output:** clusters with files, file count, cohesion.
 
+### init
+
+Make AI agents use codebase-intelligence: write a managed instruction block into each
+agent's repo file (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/codebase-intelligence.mdc`,
+`.github/copilot-instructions.md`, `GEMINI.md`, `CONVENTIONS.md`) and install the
+portable skill to `~/.claude/skills/`. Idempotent — only content between the
+`codebase-intelligence:start`/`:end` markers is touched.
+
+```bash
+codebase-intelligence init [path] [--agents <list>] [--no-skill] [--json]
+```
+
+**Output:** per-file actions (created / updated / unchanged) and skill install status.
+
 ## Flags
 
 | Flag | Available On | Description |
@@ -173,6 +187,8 @@ codebase-intelligence clusters <path> [--min-files <n>] [--json] [--force]
 | `--entry <name>` | processes | Filter by entry point name |
 | `--min-files <n>` | clusters | Min files per cluster |
 | `--no-dry-run` | rename | Actually perform the rename (default: dry run) |
+| `--agents <list>` | init | Comma-separated agents (default: all) |
+| `--no-skill` | init | Skip installing the global Claude skill |
 
 ## Behavior
 

llms-full.txt

@@ -283,7 +283,7 @@ Community-detected file clusters. Input: `{ minFiles?: number }`. Returns: clust
 
 # CLI Reference
 
-15 commands — full parity with MCP tools.
+16 commands — 15 analysis commands (full parity with MCP tools) plus `init` for agent adoption.
 
 ## Commands
 
@@ -377,6 +377,18 @@ codebase-intelligence clusters <path> [--min-files <n>] [--json] [--force]
 ```
 Community-detected file clusters (Louvain algorithm).
 
+### init
+```bash
+codebase-intelligence init [path] [--agents <list>] [--no-skill] [--json]
+```
+Make AI agents actually use codebase-intelligence. Writes an idempotent, marked
+instruction block ("query CI before grep/read") into each agent's repo file —
+`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/codebase-intelligence.mdc`,
+`.github/copilot-instructions.md`, `GEMINI.md`, `CONVENTIONS.md` — and installs the
+portable skill to `~/.claude/skills/codebase-intelligence/SKILL.md`. Only content
+between the `codebase-intelligence:start`/`:end` markers is ever touched, so re-running
+is safe. `--agents` limits targets (default: all); `--no-skill` skips the skill.
+
 ## Global Behavior
 
 - **Auto-caching**: First run parses and saves index to `.code-visualizer/`. Subsequent runs use cache if HEAD unchanged.

llms.txt

@@ -17,7 +17,7 @@ MCP mode (AI agents):
 codebase-intelligence ./path/to/project
 ```
 
-CLI mode (humans/CI) — 15 commands, full MCP parity:
+CLI mode (humans/CI) — 16 commands (15 analysis with MCP parity + `init` for agent adoption):
 ```bash
 codebase-intelligence overview ./src
 codebase-intelligence hotspots ./src --metric coupling
@@ -34,6 +34,7 @@ codebase-intelligence impact ./src getUserById
 codebase-intelligence rename ./src oldName newName
 codebase-intelligence processes ./src --entry main
 codebase-intelligence clusters ./src --min-files 3
+codebase-intelligence init .                         # make AI agents use CI
 ```
 
 ## Optional

skills/codebase-intelligence/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: codebase-intelligence
+description: Query the codebase-intelligence CLI to understand TypeScript architecture, dependencies, blast radius, and risk before reading files. Use for any "how is this structured", "what breaks if I change X", "where is the complexity" question.
+---
+
+# Codebase Intelligence
+
+`codebase-intelligence` turns a TypeScript codebase into a queryable graph of
+architecture, dependencies, and risk metrics. **Prefer it over grep/read** when the
+task is about structure, impact, or risk — it is faster and more accurate than
+scanning files one by one.
+
+## When to use
+
+| Goal | Command |
+|------|---------|
+| First look / architecture | `codebase-intelligence overview <path>` |
+| Risk & complexity ranking | `codebase-intelligence hotspots <path>` |
+| Impact of changing a symbol | `codebase-intelligence impact <path> <symbol>` |
+| File-level blast radius | `codebase-intelligence dependents <path> <file>` |
+| Unused exports | `codebase-intelligence dead-exports <path>` |
+| Keyword search | `codebase-intelligence search <path> <query>` |
+| Rename planning | `codebase-intelligence rename <path> <old> <new>` |
+| Module structure | `codebase-intelligence modules <path>` |
+
+## Rules
+
+- Run `overview` first to orient, then drill down (hotspots → file/symbol → impact).
+- Always pass `--json` in automation/subagents for structured output.
+- Use `impact`/`dependents` BEFORE editing to gauge blast radius.
+- No global install? Prefix any command with `npx codebase-intelligence@latest`.
+- Full reference: `codebase-intelligence --help`.

specs/history.log

@@ -4,3 +4,4 @@
 2026-03-11 | shipped | fix-error-handling | 1h→0.5h | 1d | Consistent impact_analysis error handling, LOC off-by-one fix, empty file guard. 17 regression tests.
 2026-03-11 | shipped | fix-metrics-test-files | 2h→1.5h | 1d | Exclude test files from coverage/coupling metrics, isTestFile detection, coupling formula fix. 19 regression tests.
 2026-03-11 | shipped | feat-metric-quality | 3h→2h | 1d | LEAF verdict for single-file modules, tension suppression for type hubs/entry points, file_context path normalization. 20 regression tests.
+2026-05-30 | shipped | feat-agent-adoption-init | 3h→1h | 1d | `init` command: idempotent managed-block instructions for 6 agents + portable skill + registry SKILL.md. 18 tests, docs + CHANGELOG. PR #34.

specs/shipped/2026-05-30-feat-agent-adoption-init.md

@@ -0,0 +1,82 @@
+# Spec: Agent Adoption — `init` command
+
+## Problem
+
+codebase-intelligence has the data (architecture, impact, risk metrics) but AI coding
+agents don't *use* it. They default to grep/read. Missing layer: durable, in-repo
+instructions + a portable skill that tell agents "query CI first."
+
+This is the adoption/distribution layer — persistent agent instructions + an installable
+skill — implemented natively in TypeScript. No new runtime deps, no LLM, no Python.
+
+## Goal
+
+One command — `codebase-intelligence init [path]` — that:
+1. Writes a managed instruction block into per-agent repo files (6 agents).
+2. Installs a portable Claude skill (`~/.claude/skills/`).
+3. (Maintainer side) ship a registry-ready SKILL.md for skills.sh / `ags install`.
+
+## Design
+
+```
+init [path]
+  ├── installRepoFiles(repoRoot, targets)   → Layer 1 (committed, team-wide)
+  └── installGlobalSkill(homeDir)           → Layer 2 (per-dev Claude skill)
+
+renderBlock()  ── single source of truth ──► upsertManagedBlock() ──► each target file
+renderSkill()  ── single source of truth ──► SKILL.md (global + registry)
+```
+
+### Managed-block engine (correctness core)
+
+`upsertManagedBlock(existing, block, markers) -> string` — pure, fs-free.
+
+- no markers in `existing` → append block (preserve original).
+- markers present → replace between (preserve content before & after).
+- empty `existing` → block only.
+- idempotent: f(f(x)) == f(x).
+
+Markers (HTML comments, work in all markdown/.mdc):
+```
+<!-- codebase-intelligence:start (auto-generated — edits here are overwritten) -->
+<!-- codebase-intelligence:end -->
+```
+
+### Agent target table (single source, adapters differ by path/preamble)
+
+| id | repo file | preamble |
+|----|-----------|----------|
+| agents | `AGENTS.md` | — (cross-agent std; covers Codex) |
+| claude | `CLAUDE.md` | — |
+| cursor | `.cursor/rules/codebase-intelligence.mdc` | mdc frontmatter |
+| copilot | `.github/copilot-instructions.md` | — |
+| gemini | `GEMINI.md` | — |
+| aider | `CONVENTIONS.md` | — |
+
+### Instruction block content
+
+Discovery-first mandate ("use BEFORE grep/read for architecture/impact/risk") +
+command cheatsheet table + `--json` note + MCP pointer.
+
+### Global skill / registry
+
+- `installGlobalSkill` → `~/.claude/skills/codebase-intelligence/SKILL.md` (skill = Claude concept).
+- Registry: commit `skills/codebase-intelligence/SKILL.md` + README `ags install` / `npx skills add` docs.
+  skills.sh directory submission = manual web/PR step (flagged, can't automate).
+
+## State Machine
+
+N/A — Stateless. Each `init` run is an idempotent upsert (input files → output files).
+No transitions; re-runnable to convergence.
+
+## Test Plan (real fs, temp dirs — no mocks)
+
+- upsertManagedBlock: empty / append / replace / idempotent / preserve-outside.
+- installRepoFiles: creates all targets, merges into pre-existing CLAUDE.md without clobber.
+- renderBlock/renderSkill: contain mandate keywords + command names.
+
+## Out of Scope
+
+- Auto-indexing on init (block tells agent to run overview).
+- Non-Claude global skill dirs (other agents covered by repo files + ags distribution).
+- Visualization / narrative report / multimodal outputs (separate, future work).