explore-repo

Analyze this repo. Use parallel tool calls aggressively. Argument (subsystem focus if given): $ARGUMENTS

Step 0: Detect mode from $ARGUMENTS

• If args start with f , flow , or equal f/flow → set FLOW_MODE=true, strip the prefix before processing
• Otherwise FLOW_MODE=false

Step 0.5: Detect graph backend (priority order)

[PRIORITY 1] .graph-agent local SQLite index Check if .graph-agent/index.db exists in the repo root (run: test -f .graph-agent/index.db && echo EXISTS):

• If EXISTS → use sqlite3 .graph-agent/index.db for all dep tracing. Schema:
  • files(id, path, language, checksum) — all indexed source files
  • symbols(id, file_id, name, kind, line_start, line_end, parent) — kind: function|method|struct|class|interface
  • edges(id, kind, src_file_id, src_symbol, dst_file_path, dst_symbol, line) — kind: CALLS|IMPORTS
  • meta(key, value) — e.g. repo_root key

Use these SQL patterns:

-- Get repo root
SELECT value FROM meta WHERE key='repo_root';

-- Find entrypoint files
SELECT path, language FROM files
WHERE path LIKE '%main%' OR path LIKE '%index%' OR path LIKE '%app%'
ORDER BY length(path) ASC LIMIT 15;

-- Get all symbols in a file
SELECT name, kind, line_start, parent FROM symbols s
JOIN files f ON s.file_id = f.id
WHERE f.path = '<relative/path>';

-- Trace callers of a symbol (who calls X?)
SELECT e.src_symbol, f.path AS src_file, e.line
FROM edges e JOIN files f ON e.src_file_id = f.id
WHERE e.dst_symbol = '<symbol_name>' AND e.kind = 'CALLS'
LIMIT 10;

-- Trace callees of a symbol (what does X call?)
SELECT e.dst_symbol, e.dst_file_path, e.line
FROM edges e JOIN files f ON e.src_file_id = f.id
WHERE e.src_symbol = '<symbol_name>' AND e.kind = 'CALLS'
LIMIT 10;

-- Trace imports of a file
SELECT e.dst_file_path FROM edges e
JOIN files f ON e.src_file_id = f.id
WHERE f.path = '<relative/path>' AND e.kind = 'IMPORTS'
LIMIT 20;

-- Find files by subsystem/path prefix (for scoped analysis)
SELECT path, language FROM files WHERE path LIKE '<subsystem>%';

-- Critical dep chain: top-called symbols
SELECT dst_symbol, count(*) AS call_count FROM edges
WHERE kind='CALLS' GROUP BY dst_symbol ORDER BY call_count DESC LIMIT 10;

Run queries in parallel. Use results instead of Grep/Glob for symbol and dep tracing.

[PRIORITY 2] MCP code-graph If .graph-agent/index.db does NOT exist, check if mcp__code-graph__list_projects is available:

• If YES → use graph tools:
  • mcp__code-graph__list_projects → find current repo
  • mcp__code-graph__get_file_symbols on entrypoints instead of Grep
  • mcp__code-graph__get_callers / mcp__code-graph__get_callees to trace critical paths
  • mcp__code-graph__get_file_imports instead of grepping imports
  • If repo not indexed yet → call mcp__code-graph__reindex_repo first

[PRIORITY 3] Fallback — Glob/Grep sequence (no graph available):

1. Glob root for: package.json, go.mod, Cargo.toml, pyproject.toml, requirements*.txt, Makefile, Dockerfile, *.yaml, *.toml — identify stack
2. Read root configs. Locate entrypoints: main.*, index.*, app.*, cmd/, src/, bin/
3. Grep import|require|from on entrypoints to trace 2–3 critical dep paths
4. Find env: .env*, config/, settings.*, *secret* — list key vars only
5. Extract commands from scripts, Makefile, CI files (.github/workflows/, ci.yml)

Output (always):

STACK:    <lang + runtime + version>
ENTRY:    <file:line — main execution path>
BUILD:    <command>
RUN:      <command>
TEST:     <command>
ENV:      <KEY=source, KEY=source>
DEP FLOW: <A → B → C> (critical path only, 2–3 chains)
GOTCHAS:  <non-obvious config, ordering requirements, known traps>

If FLOW_MODE=true — append a Mermaid diagram after the output block:

Rules for the diagram:

• Use graph LR (left→right) for service/data flow; use graph TD for call hierarchies
• Group by layer: Browser / FE / API Routes / Backend Services / External / DB
• Show only the critical request paths (3–5 flows max) — not every file
• Label edges with the protocol or data type: -->|REST / JWT|, -->|SSE stream|, -->|SQL|
• Use subgraphs to cluster services that run in the same process/container
• Keep node names short (≤20 chars), use IDs for linking

Example shape:

graph LR
  subgraph Browser
    UI[Next.js UI]
  end
  subgraph FE Container :3000
    API[API Routes]
  end
  subgraph BE Container :8080
    GIN[Gin Server]
    GORM[GORM]
  end
  DB[(PostgreSQL)]
  EXT[Azure OpenAI]

  UI -->|fetch| API
  API -->|stream SSE| UI
  API -->|REST + JWT| GIN
  API -->|AZURE SDK| EXT
  GIN --> GORM
  GORM -->|SQL| DB

No prose. No section headers outside the blocks. If $ARGUMENTS (after stripping f/flow prefix) targets a subsystem, scope all steps to that path.