repo-intel

Repo Intel Skill

Build and maintain a cached repo-intel artifact using the agent-analyzer binary. Covers git history, AST symbols, project metadata, doc-code sync, and (after enrich) LLM-generated per-file descriptors and a 3-depth narrative summary.

Parse Arguments

const allArgs = '$ARGUMENTS'.split(' ').filter(Boolean);
const positional = allArgs.filter(a => !a.startsWith('--'));
const action = positional[0] || 'status';
const queryType = action === 'query' ? positional[1] : null;
const queryArg = action === 'query' ? positional[2] || null : null;

Primary Responsibilities

1. Initialize artifact on demand (/repo-intel init) - full scan
2. Update incrementally (/repo-intel update) - only new commits since last run
3. Enrich with LLM signals (/repo-intel enrich) - spawn the repo-intel-summarizer and repo-intel-weighter Haiku subagents to populate the artifact's summary (3 depths) and fileDescriptors (top-500 most-active files). The Rust binary itself never calls an LLM - this orchestration runs in JS and pipes the agent JSON back through set-summary / set-descriptors.
4. Check status (/repo-intel status)
5. Run queries against the cached artifact (/repo-intel query <type>)

Binary Integration

const pluginRoot = '$CLAUDE_PLUGIN_ROOT';
const binary = require(`${pluginRoot}/lib/binary`);
const repoIntel = require(`${pluginRoot}/lib/repo-intel`);

The binary is resolved and auto-downloaded if needed via binary.ensureBinary(). The binary module is bundled with this plugin - no external dependency required.

Core Data Contract

Artifact is stored in the platform state directory:

• Claude Code: .claude/repo-intel.json
• OpenCode: .opencode/repo-intel.json
• Codex CLI: .codex/repo-intel.json

Available Queries

All queries delegate to agent-analyzer repo-intel query <type>.

Git History (Phase 1)

Query	Description
hotspots	Recency-weighted most-changed files
coldspots	Least-changed files with no recent activity
bugspots	Files with highest bug-fix density (fix/change ratio)
coupling <file>	Files that change together with <file>
ownership <path>	Who owns a directory or file
bus-factor	Detailed bus factor with critical owners and at-risk areas
norms	Commit message conventions detected from history
areas	Directory-level health overview
contributors	Contributors sorted by commit count with staleness
release-info	Release cadence and last release
health	Repository health summary
file-history <file>	Detailed history for a specific file
conventions	Commit message style, prefixes, scope usage
test-gaps	Hot source files with no co-changing test file
diff-risk <files>	Score changed files by composite risk
doc-drift	Doc files with low code coupling (likely stale)
onboard	Newcomer-oriented repo summary
can-i-help	Contributor guidance matching skills to areas needing work
entry-points	Every place execution can start (binaries, main functions, npm scripts)

AST Symbols (Phase 2)

Query	Description
painspots	Files ranked by hotspot x (1 + bug_rate) x (1 + complexity/30)
symbols <file>	AST exports, imports, and definitions for a file
dependents <symbol>	Files that import a given symbol (reverse dependency)

Doc-Code Sync (Phase 4)

Query	Description
stale-docs	Doc files with stale references to source symbols

LLM-Augmented Signals (Phase 6, requires /repo-intel enrich first)

Query	Description
find <concept>	Concept-to-file search. Replaces grep -r <concept> with a ranked list and a one-line why per result. Without descriptors, scores from path/symbol/import/doc-header substring matches; with descriptors (populated by enrich), also catches semantic synonyms (worker ↔ executor) by matching against the per-file LLM descriptor.
summary [--depth 1|3|10]	Cached 3-depth narrative description of the repo. depth1 = one sentence, depth3 = one paragraph, depth10 = one-page technical overview. Generated by the repo-intel-summarizer Haiku agent at enrich time.

Slop Targeting (Phase 7, fed to /deslop)

Query	Description
slop-fixes	Pinpoint structured fix actions for Haiku-tier execution: tracked artifacts, stale CI configs, duplicate tooling, orphan exports, empty catches, tautological tests. Each finding has a file + line range + action so the agent applies it without further research.
slop-targets	Ranked targets for Sonnet (file-level) and Opus (cross-file) scans. Sonnet: defensive cargo cult, bot-authored, could-be-shorter. Opus: cliché clusters, wrapper towers, single-impl traits, high-bug communities. With the embedder installed, also: stylistic outliers, semantic duplicates.

Embedder Actions (Phase 7, opt-in)

Action	Description
embed status	Show whether the embedder is installed, which variant + detail level, sidecar size and last-update time.
embed update	Delta re-embed only files whose content hash differs from the existing sidecar. Falls back to full scan if no sidecar exists. Pipes JSON to set-embeddings.
embed reset	Clear the cached embedder preference so the next /repo-intel enrich re-prompts. Does not delete the sidecar or downloaded model — use this when changing model variant or detail level.

Post-Init Enrichment

Two Haiku-backed Task subagents fire when /repo-intel enrich runs:

• repo-intel-weighter reads the top-500 most-active files in batches of 30, returns 1-2 sentence concrete descriptors per file as JSON between marker blocks. The skill parses the markers and pipes the JSON to agent-analyzer repo-intel set-descriptors --input -.
• repo-intel-summarizer reads README + manifests + top-10 hotspot file headers, returns {depth1, depth3, depth10, inputHash} as JSON between marker blocks. The skill parses and pipes to set-summary --input -.

The Rust binary itself never makes LLM calls. All orchestration lives here.

Embedder (opt-in)

enrich also runs agent-analyzer-embed when the user has opted in. The choice is captured by two AskUserQuestion prompts on first use, persisted in <stateDir>/sources/preference.json:

1. embedder — none (default), small (BGE-small Q8 ~30 MB), or big (EmbeddingGemma-300M Q4 ~195 MB)
2. embedderDetail — compact (per-file × 128 dim), balanced (per-function × 256 dim, recommended), maximum (per-function × 768 dim)

Subsequent enrich runs read the cached preference and proceed silently. The embed binary downloads the model file on first use (cached next to the binary in ~/.agent-sh/bin/); model files are not bundled in the binary.

Embeddings live in a sidecar file <map_stem>.embeddings.bin next to the JSON artifact (packed fp16, deterministic). The main JSON stays diffable; the sidecar is opaque binary.

When the embedder is not installed, all queries that benefit from embeddings (find, slop-targets) work in their AST/graph-only mode — same shape, weaker signals.

Behavior Rules

• Never call the binary without binary.ensureBinary() first
• Always cache results after a successful init or update
• Prefer incremental update unless artifact is missing
• Return structured data - let the command layer format output

Recency and Staleness

• Recency window: 90 days relative to the repo's lastCommitDate (not wall clock)
• Stale contributor: lastSeen > 90 days before lastCommitDate
• Hotspot score: (recentChanges * 2 + totalChanges) / (totalChanges + 1)
• Area health: "healthy" / "needs-attention" / "at-risk"

Output Expectations

• init/update: commit count, files analyzed, last commit, duration
• status: age, staleness, commits behind HEAD
• query: ranked list with scores, truncated to --limit (default 10)