query-code— agent skill

<objective>

Query codemap structural index for import-graph analysis, symbol-level source extraction, function-level call graph traversal. Python projects only — index covers .py files; queries on non-Python projects return empty or error. scan-query on PATH (installed by codemap plugin).

Module-level queries (import graph):

• central [--top N] — most-imported modules (highest blast radius, default top 10)
• coupled [--top N] — modules with most imports (highest coupling, default top 10)
• deps <module> — what module imports
• rdeps <module> — what imports module
• path <from> <to> — shortest import path between two modules

Symbol-level queries (use instead of reading full files — ~70–94% token reduction (single known-name lookup on large file)):

• symbol <name> [--with-imports] — get source of function/class/method by name; returns stale: bool per result; add --with-imports to include module-level import block alongside source
• symbols <module> — list all symbols in module (no file I/O)
• find-symbol <pattern> — regex search across all symbol names in index

Function-level call graph queries (v3 index — requires /codemap:scan-codebase with call graph):

• fn-deps <qname> — what does function/method call? (outgoing edges)
• fn-rdeps <qname> — what functions call this one? (incoming edges)
• fn-central [--top N] — most-called functions globally (default top 10)
• fn-blast <qname> — transitive reverse-call BFS with depth levels

Use module::function format for qname, e.g. mypackage.auth::validate_token. Requires v3 index — v2 returns clear upgrade prompt.

NOT for: explicit/large or monorepo (--root) rebuilds (use /codemap:scan-codebase); writing symbol output to project files (Write is in allowed-tools for output routing only — never use it to modify project source); listing all files in a directory or getting a file inventory (use Read/Glob — symbols <module> lists symbols within a module, not directory contents); renaming symbols (use /codemap:rename-refs); function-blast tracing that requires rename-aware blast radius (use /codemap:rename-refs). All query subcommands are read-only on project source — they never modify .py files. The skill DOES auto-materialize/refresh its own derived index cache (.cache/codemap/, fully regenerable) as a Step 0 pre-flight; that is the one permitted write. File injection into skills/agents belongs to /codemap:integration. Ambiguous prompts like "show me the call graph" that imply read → query-code is correct; "update the call graph" → scan-codebase. If subcommand roster expands significantly, run /foundry:calibrate routing (requires foundry plugin) to verify no routing collisions.

</objective>

<workflow>

Step 0: Ensure index present + fresh (once per task)

Run this pre-flight once per task, before the first query. Skip entirely if Step 0 already ran earlier this turn.

First, parse $ARGUMENTS for an explicit --index override:

# timeout: 5000
_CM_PROJ=$(git rev-parse --show-toplevel 2>/dev/null | xargs basename 2>/dev/null || echo "cm")
INDEX_OVERRIDE=$(echo "$ARGUMENTS" | sed -n 's/.*--index \([^ ]*\).*/\1/p')
printf '%s' "$INDEX_OVERRIDE" > "${TMPDIR:-/tmp}/codemap-${_CM_PROJ}-index-override"

If INDEX_OVERRIDE is non-empty (read from ${TMPDIR:-/tmp}/codemap-${_CM_PROJ}-index-override), skip default-index resolution AND skip the present branch incremental refresh (refreshing the default index when an explicit override is given would update the wrong index). Proceed directly to Step 1, skipping the present/missing/unresolved branch entirely.

Otherwise, resolve the default index path (same helper /codemap:integration uses):

# timeout: 5000
_CM_PROJ=$(git rev-parse --show-toplevel 2>/dev/null | xargs basename 2>/dev/null || echo "cm")
INDEX_OVERRIDE=$(cat "${TMPDIR:-/tmp}/codemap-${_CM_PROJ}-index-override" 2>/dev/null || echo "")
if [ -n "$INDEX_OVERRIDE" ]; then
    printf '%s' "$INDEX_OVERRIDE" > "${TMPDIR:-/tmp}/codemap-${_CM_PROJ}-resolve-index"
    echo "present" > "${TMPDIR:-/tmp}/codemap-${_CM_PROJ}-index-state"
else
    python "${CLAUDE_PLUGIN_ROOT:-plugins/codemap}/bin/resolve_index_env.py" \
        --output-prefix "codemap-${_CM_PROJ}" 2>/dev/null
    INDEX=$(cat "${TMPDIR:-/tmp}/codemap-${_CM_PROJ}-resolve-index" 2>/dev/null || echo "")
    [ -n "$INDEX" ] && { [ -f "$INDEX" ] && STATE="present" || STATE="missing"; } || STATE="unresolved"
    echo "$STATE" > "${TMPDIR:-/tmp}/codemap-${_CM_PROJ}-index-state"
fi

Read INDEX_STATE from $(cat "${TMPDIR:-/tmp}/codemap-${_CM_PROJ}-index-state") in subsequent steps, then branch:

• `missing` — build before querying. The index is created only by scan-index; call the builder skill (explicit Skill() works despite its disable-model-invocation):

  Skill(skill="codemap:scan-codebase")

After the skill returns, re-read INDEX from tmpfile (shell variable is gone after Skill() boundary):

  # timeout: 5000
  _CM_PROJ=$(git rev-parse --show-toplevel 2>/dev/null | xargs basename 2>/dev/null || echo "cm")
  INDEX=$(cat "${TMPDIR:-/tmp}/codemap-${_CM_PROJ}-resolve-index" 2>/dev/null || echo "")
  [ -f "$INDEX" ] || { echo "⚠ Index build failed — stopping. Re-run /codemap:scan-codebase to investigate."; exit 1; }

• `present` — refresh only SHA-changed files (cheap; re-parses just what changed since last scan):

  "${CLAUDE_PLUGIN_ROOT:-plugins/codemap}/bin/scan-index" --incremental  # timeout: 5000 — ~0.5s flat

• `unresolved` — resolve_index_env.py could not resolve (no git root / python missing); surface the error and stop:

  # timeout: 5000
  echo "⚠ Could not resolve index path — check that git is available and CLAUDE_PLUGIN_ROOT is set."
  exit 1

Full scan (scan-index without --incremental) is only needed after large structural moves — the missing branch already runs a full build via /codemap:scan-codebase.

Step 1: Run the query

deps vs rdeps — choose before calling:

Common mistake — direction matters: "which modules need updating if X changes?" = rdeps (callers), NOT deps. deps returns wrong direction — 0% recall.

Unsupported flag check — after all supported flags extracted, scan $ARGUMENTS for remaining --<token> tokens. If found: print ! Unknown flag(s): \--<token>\. Supported: \--top\, \--exclude-tests\, \--limit\, \--index\, \--exhaustive\; \--with-imports\ applies to \symbol\ subcommand only. then invoke AskUserQuestion — (a) Abort (stop, re-invoke with correct flags) · (b) Continue ignoring (skip unknown flags, proceed). On Abort: stop.

Symbol staleness contract: every symbol result includes "stale": bool. When stale: true AND source empty:

• Do NOT use source — it may be wrong (function moved since last scan)
• stale_reason explains why: "file deleted", "line range past EOF", "symbol name not in slice header"
• Fall back: Read(<result["path"]>) — path is still valid even when content is stale
• Fix: run scan-index --incremental then retry

When source is empty and stale: false (broken index, not stale): render [source not available — re-run /codemap:scan-codebase] — do not attempt Read fallback.

Symbol vs Read — access pattern decision:

Qualified names reduce ambiguity: symbol MyClass.method returns one result; bare symbol authenticate may return N matches across modules. Prefer qualified form when module path known.

Index freshness is handled by Step 0 — do not re-run scan-index here.

Missing binary: if scan-query not found on PATH, use locate_scan_query.py three-tier fallback (same as /codemap:integration check):

SQ=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/codemap}/bin/locate_scan_query.py" 2>/dev/null || echo "scan-query")

Then invoke via $SQ instead of bare scan-query. If still not found: print ! scan-query not found — install codemap plugin: claude plugin install codemap@borda-ai-rig and stop.

Run scan-query via Bash, assembling arguments from the table below. Example forms — always use quoted module names/qnames:

# module-level query example
scan-query rdeps "mypackage.auth"  # timeout: 5000
# function-level query example
scan-query fn-rdeps "mypackage.auth::validate_token"  # timeout: 5000
# fn-blast example
scan-query fn-blast "mypackage.auth::validate_token"  # timeout: 5000

Replace subcommand and arguments per task:

scan-query on PATH via locate_scan_query.py fallback (see above). Do not fall through to grep/bash fallback.

Symbol names accept: bare name (authenticate), qualified name (MyClass.authenticate), or case-insensitive substring fallback. Function qnames use module::function format (e.g. mypackage.auth::validate_token). Step 0 keeps the index current; if a stale warning still appears, files changed mid-task — re-run scan-index --incremental and retry.

find-symbol pattern is a Python regex applied against the full qualified name — auth matches any symbol containing "auth" as a substring; ^Auth.*Handler$ matches only symbols starting with "Auth" and ending with "Handler". For exact match use anchors: ^MyClass\.method$ (escape . to \. for a literal dot — unescaped . matches any character, e.g. ^MyClass.method$ would also match MyClassXmethod). Bare substring (no anchors) = broad match — prefer anchored patterns for precision. Pattern is a Python regex — use auth.* not auth* for prefix search; auth* means zero-or-more h characters.

Budget and stop rules

Query budget:

• Default: max 3 calls per task. Stop after 3 even if not exhaustive — report what found.
• Exhaustive mode: when user explicitly requests exhaustive traversal, budget extends to 6 calls. Best declared before first call so budget applies from the start — if declared mid-task, apply remaining budget up to 6 total from that point.
• path or fn-blast with --exhaustive flag: budget extends to 6 calls (same as exhaustive mode). These subcommands traverse the graph internally; --exhaustive is the explicit signal to allow deeper exploration.
• Budget counts `scan-query` subcommand invocations only — Step 0 resolve calls and scan-index --incremental calls do not count toward the budget.

Truncation check (prerequisite of STOP rule): when result count equals the default limit (20) and --limit 0 was not passed, the list may be truncated even if exhaustive: true — re-run once with --limit 0 to confirm count. The truncation-check re-run consumes one budget slot. After the --limit 0 re-run (or if original result count was below 20): THEN apply STOP rule.

exhaustive: true — STOP ALL TOOL CALLS: When rdeps, deps, or fn-rdeps result has result["index"]["exhaustive"] == true AND truncation check above is satisfied (either count < 20 on original run, or --limit 0 re-run has been done), list is complete and authoritative for the unfiltered index. Check the index.exhaustive field specifically (not any top-level field). Note: if --exclude-tests used, exhaustive reflects unfiltered coverage — filtered results may omit callers; state caveat if relevant. Write answer immediately. Do NOT call codemap again. Do NOT run grep, bash, or Glob passes to verify or extend. In the response, explicitly note: "Result is complete and authoritative for the unfiltered index." If --exclude-tests was used, add: "Note: filtered results may omit some callers — unfiltered list is complete."

fn-blast budget: fn-blast is a single call that internally traverses the full graph — the budget extension to 6 applies to the total number of subcommand invocations across the task, not to fn-blast itself (it cannot be re-called to "go deeper"). The STOP rule (exhaustive: true) does not apply to fn-blast results — fn-blast always returns all reachable callers in one call. Treat the fn-blast result as complete regardless of exhaustive field value.

Non-exhaustive result — convergence rule: after budget calls still non-exhaustive, stop and report what found. Do NOT switch to grep/bash — index covers what it covers.

`--exclude-tests` + exhaustive: when --exclude-tests is used and index.exhaustive == true, the exhaustive flag reflects unfiltered coverage (the index was fully searched). The STOP rule still applies — do NOT make additional calls. The caveat is informational: filtered results may omit callers that are in test files. State the caveat in the response but do not make additional non-filtered calls to compensate.

Step 2: Parse JSON output and format

scan-query always emits JSON object — parse before rendering. Stale-index detection has two channels: (1) stderr: if contains [stale] or ⚠ codemap index stale — surface warning; (2) JSON field index.stale (boolean) — check result.index.stale; if true, the index went stale after Step 0 (files changed mid-task) — re-run scan-index --incremental and retry rather than telling the user to build manually. Check index.degraded in result; if > 0, caveat that some modules unparsable — for path queries, note that intermediate nodes may be missing and the path result may be incomplete.

Coverage metadata — every result includes index.method and optional index.not_covered, index.hint, index.confidence, index.scope. Use to scope your response accurately:

Codemap is the primary codebase navigation tool. Do NOT fall through to grep/bash to re-verify what codemap already returned. Authoritative (no re-verify) when: exhaustive=true, stale=false, not_covered empty. When not_covered non-empty and task requires completeness (find ALL callers, full blast-radius before a breaking edit): the codemap result is correct-for-what-it-found but not complete — run the index.hint grep as an explicit escalation, label it as "residual-risk verification", surface to user.

When `index.not_covered` is non-empty: (1) append scope caveat to response — e.g. "Note: callers via dynamic dispatch, hook callbacks, or string dispatch are not included in this list."; (2) append gap record to .cache/codemap/gaps.jsonl so the coverage gap is collected for index improvements. Use python3 for JSON-safe value insertion to avoid JSONL corruption on special characters in target/hint:

# timeout: 5000
python3 -c "
import json, sys, datetime, os
record = {
    'ts': datetime.datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'),
    'cmd': sys.argv[1], 'target': sys.argv[2],
    'not_covered': json.loads(sys.argv[3]), 'hint': sys.argv[4]
}
os.makedirs('.cache/codemap', exist_ok=True)
with open('.cache/codemap/gaps.jsonl', 'a') as f:
    f.write(json.dumps(record) + '\n')
" "<subcommand>" "<target>" '<not_covered_json>' "<hint_or_empty>" 2>/dev/null || true

(3) Continue to achieve goal — do NOT abandon the task because of a structural gap.

When `index.hint` is present: include it as a suggestion if the user needs to find the missing callers: "To find hook-registered callers: grep -rn "fn_name" ..."

When `index.confidence == "exact"`: result is authoritative — skip verification caveats.

When `index.confidence == "partial"` and `index.truncated == true`: result was cut by --limit. Surface: "Showing N of index.total_available matches — rerun with --limit 0 for complete list." Do not treat truncated output as complete.

When codemap cannot answer at all (error or empty, not a coverage gap): log the uncovered query type using python3 for JSON-safe output:

# timeout: 5000
python3 -c "
import json, sys, datetime, os
record = {'ts': datetime.datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'),
          'type': 'uncovered-query', 'query': sys.argv[1], 'reason': sys.argv[2]}
os.makedirs('.cache/codemap', exist_ok=True)
with open('.cache/codemap/gaps.jsonl', 'a') as f:
    f.write(json.dumps(record) + '\n')
" "<query>" "<reason>" 2>/dev/null || true

Then use the best available alternative (Read, grep) and note in your response what codemap couldn't cover.

{"error": "..."}: surface error. A residual Index not found here means Step 0's auto-build failed — report the build failure plainly (do not just suggest a manual rebuild). Other errors (unknown module, bad regex) surface as-is.

Partial JSON handling: if output is truncated (does not parse as complete JSON object — e.g., ends mid-value or missing closing }), log ⚠ partial JSON response — results may be incomplete. Attempt recovery using jq with --stream mode when jq is available; if jq is absent, use python3 -c "import sys,json; ..." as fallback — do not fall back to line-matching (structural keys like imported_by, stale would surface as false module names). Surface whatever was recovered; do not silently discard partial results. If recovery produces zero items, report ⚠ could not recover partial results — re-run the query and stop.

Output routing — if result count ≥ 5 items: derive BRANCH first, then write full rendered output to .temp/output-codemap-query-<branch>-<YYYY-MM-DD>.md via Write tool:

BRANCH=$(git branch --show-current 2>/dev/null | tr '/' '-' || echo 'main')  # timeout: 3000

Output file must begin with YAML header block:

---
Title:      codemap-query-code — <subcommand> <module-or-qname>
Date:       <YYYY-MM-DD>
Scope:      <project name>
Focus:      structural index query
Agents:     codemap:query-code
Outcome:    <N results returned | exhaustive -> true/false>
Confidence: <exhaustive|partial|stale|unknown>
Next steps: /codemap:query-code <follow-up subcommand> or /codemap:rename-refs if renaming
Path:       → .temp/output-codemap-query-<branch>-<YYYY-MM-DD>.md
---

Then print terminal summary (YAML header + path + top-5 items). Skip file write for ≤ 4 items — terminal only. Applies to: rdeps, deps, central, coupled, fn-rdeps, fn-central, fn-deps, fn-blast, list. For fn-blast with ≥ 5 entries, always route to file — print file path and top-5 callers only to terminal to avoid burying the follow-up gate.

Evidence block — append to every response body (terminal or file), after rendered results:

## Evidence
query: scan-query <subcommand> "<target>"      # one line per query; list all calls this task
method: <index-lookup|static-ast|import-graph|ast-flags>   # from index.method
completeness: <exhaustive|partial|stale|unknown>
result_count: <N>
not_covered: <list from index.not_covered, or omit if empty>
limitations: degraded=<N> star_skips=<N> tests_excluded=<true|false>

completeness derived from result.index fields — not model-counted:

• exhaustive — index.exhaustive=true AND !stale AND degraded=0 (safe to skip re-query)
• partial — index.exhaustive=false OR degraded>0 (caller truncation or parse failures)
• stale — index.stale=true (index predates recent file changes)
• unknown — index field absent (old index format)

limitations: from result.index: degraded (unparsed modules), star_import_modules count (star-import skips), tests_excluded=true when --exclude-tests used. Omit line when all values are 0/false.

Completeness: in YAML header = same value. Agents may skip re-querying only when completeness: exhaustive.

Follow-up gate (after output routing): invoke AskUserQuestion — (a) Run another query (specify subcommand), (b) Done. Skip when invoked from inside another skill's pipeline.

Flags available on multiple commands (--exclude-tests, --limit, --index):

• --exclude-tests — drop test modules from results; applies to: rdeps, central, coupled, symbol, find-symbol, fn-rdeps, fn-central; not supported on `path` — if user passes path ... --exclude-tests, print ! --exclude-tests is not supported for path queries then invoke AskUserQuestion — (a) Abort (stop, re-invoke without --exclude-tests) · (b) Continue ignoring (proceed without the flag); consistent with other unsupported-flag handling pattern
• --limit N (default 20, use 0 for all) — caps results on symbol, find-symbol, rdeps, deps, fn-rdeps, and other list-type commands; always pass `--limit 0` when counting or ranking to avoid silent truncation at 20 items; output-routing count check and exhaustive assertions should be made only after --limit 0 or confirmed item count is below 20
• --index <path> — explicit index file path (bypasses auto-discovery; useful for monorepos or comparing two indexes)

</workflow>