shared/guidelines/code-index

Source: shared/guidelines/code-index.md

shared/guidelines/code-index.md — using the repo-level code index from any skill

Loaded by /adk-implement (TDD sub-flow), /adk-investigate, /adk-document (runbook / ADR / migration), and /adk-review (light path) when those skills want repo-symbol context.

What this is

scripts/lib/code_index/ is the shared code-index library. It’s the chunker + embedder + LanceDB + SCIP + grep stack that /adk-pr-review already uses, with the wiring extracted so other skills can consume the same data.

Storage:

1$ADK_DATA_HOME/repos/<repo>/                    clone (default branch)2$ADK_DATA_HOME/repos/.indices/<repo>/           adk-owned index3  repo-meta.json                                  indexed_oid, indexed_at, default_branch4  code-index/5    chunks.jsonl  chunks.lance/  scip/  meta.json

Built by adk repo add <git-url> and refreshed by adk repo update <name>. PR-review seeds from this when present and falls back to a full reindex when not.

Public surface — what skills may rely on

1from scripts.lib.code_index.query import (2    open_index, similar, by_symbol, defs, callers, feature_flag,3    Hit, Index,4    IndexNotBuilt, IndexStale, ModelMismatch,5)

Every other name in the module is internal and may change without notice.

open_index(target, *, kind="repo", max_staleness_days=None, require_fresh=False, require_model=None, skill="...", _log=True) -> Index

Resolves the on-disk index. Two roots:

• kind="repo": target is a repo name; resolves to $ADK_DATA_HOME/repos/.indices/<target>/code-index/.
• kind="task": target is a task-dir path; resolves to <target>/code-index/. PR-review uses this internally.

Errors:

Sensible defaults: require_fresh=False, require_model=None. Most consumers should warn on staleness, not refuse.

similar(idx, query, *, top_k=8, mode="hybrid", file_glob=None) -> list[Hit]

Hybrid (vector + BM25) by default. mode is one of "hybrid", "vector", "bm25". file_glob like "src/auth/**" is server-side filtered against the file column. Empty / whitespace query returns [].

by_symbol(idx, symbol, *, limit=20) -> list[Hit]

Exact-match on the chunk’s parent_symbol column.

defs(idx, symbol) -> list[Hit]

Definition sites. Today: same as by_symbol. SCIP-backed lookup on the roadmap.

callers(idx, symbol, *, limit=50) -> list[Hit]

Code locations that call symbol. Uses ripgrep (or grep fallback) over idx.worktree. Empty when no worktree is available.

feature_flag(idx, key) -> list[Hit]

Code sites referencing a feature-flag / experiment key. Grep over the worktree. Statsig MCP correlation is the caller’s job.

Hit (frozen dataclass)

Stable fields: path, line_start, line_end, score, snippet, symbol, source. New fields go in extras: dict — never inline.

Index

Carries repo, code_index_dir, embed_model, dim, rows, indexed_sha, last_refreshed, kind, worktree. The age_days property returns float days since last_refreshed (None for kind="task").

Worked examples

/adk-implement TDD sub-flow — “related code patterns”

1from scripts.lib.code_index.query import open_index, similar, callers, IndexNotBuilt, IndexStale23try:4    idx = open_index("ecomm-ssr")5except IndexNotBuilt:6    log.info("repo not indexed yet; skipping related-code section")7    related_section = ""8else:9    if idx.age_days and idx.age_days > 7:10        log.warning("base index is %.1f days old — relations may be stale", idx.age_days)11    hits = []12    for bullet in tdd.requirement_bullets:13        hits.extend(similar(idx, bullet, top_k=3))14    # De-dupe by path:line.15    seen = set()16    for h in hits:17        key = (h.path, h.line_start)18        if key in seen: continue19        seen.add(key)20        related_section += f"- `{h.path}:{h.line_start}-{h.line_end}` — {h.symbol or h.path}\n"

/adk-investigate — symptom → candidate code paths

1idx = open_index(repo_for_service(service))   # may raise IndexNotBuilt2hits = similar(idx, symptom_text, top_k=6, mode="hybrid")3# Confidence: medium when ≥2 of the top-3 hits land in the same module;4# low otherwise. Always anchor next to the DD trace evidence.

/adk-document (migration) — enumerate API surface

1idx = open_index(repo)2api_callers = callers(idx, deprecated_fn)3api_defs    = defs(idx, deprecated_fn)

Rules

1. Pin the embed model. When you care about cross-comparable scores, pass require_model=. Mixing nomic-embed-text and bge-m3 returns nonsense — ModelMismatch is a hard fail by design.
2. Surface staleness. Every consumer prints indexed_sha, age_days, and embed_model somewhere in its output. /adk-document puts it at the top of an ADR; /adk-investigate puts it in the report’s “Evidence” section.
3. Fail open. If the index isn’t built, the consumer skill MUST still complete — just without the semantic-search section. Never block a skill on the index.
4. Don’t write through the API. This surface is read-only. Building / refreshing is the job of adk repo add and adk repo update. Each skill’s --rebuild is for its own task-dir, not the base.
5. No PII queries. Don’t pass user IDs, emails, message bodies, or PR review comments as query. The query embedding is sent to a local ollama process today, but the rule keeps us safe when we move to a hosted model.
6. Cap top_k. Default 8. Crank to 15 only when the consumer is genuinely scanning for everything (e.g. a migration enumeration). Bigger top_k ≠ better — the precis is for the model, and 20 hits dilute the signal.

Configuration

Defaults ship in scripts/lib/code_index/defaults.yaml. User overrides go in $ADK_CONFIG_HOME/code-index.yaml — same shape, deep merged:

1embed:2  default_model: nomic-embed-text   # change to bge-m3 if you want higher quality everywhere3retrieval:4  hybrid: true5  vector_weight: 0.66  fts_weight: 0.47base_index:8  max_staleness_days: 7              # how old before consumers warn

Failure modes the caller must handle