---
name: explore
description: Read-only codebase investigation through the Explore agent, including zooming out on an unfamiliar region. Triggers "how does X work", "where is X", "understand X", "where does this fit".
context: fork
agent: explore
---

# Codebase Exploration

Delegates to the Explore agent for fast, read-only investigation of the codebase.

## Standalone Codex

Claude frontmatter does not enforce a fork or tool restriction in standalone
Codex. Keep this workflow read-only yourself, or use `spawn_agent` with an
`explore` agent and a read-only prompt. Gather current state by explicitly
running `pwd`, `basename "$PWD"`, `ls package.json Cargo.toml go.mod
pyproject.toml`, and `git rev-parse --show-toplevel`; the `!command` lines below
are Claude interpolation only.

Codex does not receive TLDR from this package. In broad mode use `rg --files`,
`rg -n` exact searches, direct import searches, and focused file reads. In
upward-zoom mode search the symbol definition and all call sites with `rg -n`,
then trace imports and callers one layer up. Never claim a TLDR MCP ran.

## Claude current state
- Directory: !`pwd 2>/dev/null`
- Project: !`basename "$(pwd)" 2>/dev/null`
- Stack: !`ls package.json Cargo.toml go.mod pyproject.toml 2>/dev/null || echo "unknown"`
- Git root: !`git rev-parse --show-toplevel 2>/dev/null || echo "not a git repo"`

## Two modes — pick by what the user asked

### Broad investigation mode (default)
Use when the user is asking "how does X work" / "where is X" / "what handles Y" — finding code without a known starting point.

1. **Start broad** - In Claude use `tldr semantic` or `Glob`; in standalone Codex use the native searches above
2. **Narrow down** - Read specific files to understand implementation
3. **Trace connections** - In Claude use `tldr impact`; in standalone Codex trace callers and imports with `rg`
4. **Summarize findings** - Return clear, actionable summary

### Upward-zoom mode
Use when the user is staring at a known function or module and needs to know **how it fits** — triggers like "zoom out", "bigger picture", "where does this fit", onboarding unfamiliar code.

1. Follow [../context-doc/DOMAIN-AWARENESS.md](../context-doc/DOMAIN-AWARENESS.md) — read `CONTEXT.md` and any relevant ADRs first if they exist.
2. Identify the symbol or file the user is asking about.
3. In Claude, use TLDR for the structural answer:

   ```bash
   tldr context <symbol> --depth 3 --project .
   tldr impact <symbol> --project .
   ```

4. Synthesize a map: list immediate callers, the modules they live in, and where this area sits in the system. Use `CONTEXT.md` vocabulary when naming concepts.
5. Stop at one layer up. The user can ask for another zoom-out if they need it.

Upward-zoom output shape:

```
{Symbol/file in question}
  ↑ called by: {module A}, {module B}
  ↓ depends on: {module C}, {module D}

Where this fits:
{1–2 sentence narrative using CONTEXT.md terms}

Related ADRs:
- ADR-NNNN ({title}) — relevant because…
```

The point is orientation, not exhaustive coverage.

## Output Format (broad mode)

Return a concise summary:
- **Location**: Key files and their paths
- **How it works**: Brief explanation of the flow
- **Key functions/components**: Entry points
- **Dependencies**: What it relies on
- **Suggestions**: If the user needs to modify something

## Remember

- You are READ-ONLY - do not modify files
- Return summaries, not raw file contents
- Be specific with file paths and line numbers