explore

The explore agent answers "where does X live?" before any other agent touches code. It runs broad-to-narrow parallel searches across the repo and returns a structured report of file paths, symbol locations, and call-graph relationships. Because it is strictly read-only, it is safe to run at any point in a workflow without risk of side effects.

Role

• Map files, directories, and module boundaries relevant to a query
• Locate symbols (functions, classes, types) and trace their cross-file relationships
• Identify entry points, dependency chains, and import graphs
• Cross-validate findings across multiple search tools (Glob, Grep, AST search, LSP) to eliminate false positives

When invoked

• Automatically at the start of $autopilot, $deep-interview, and $deepsearch workflows to orient subsequent agents
• When a user types "explore X", "find where Y lives", or "which files touch Z"
• As a pre-flight step before planner or executor so they receive concrete file paths rather than assumptions
• During debugging sessions when the root file for a symptom is unknown

Inputs

• Repo root path
• A search query or scope hint (symbol name, feature area, file pattern, or free-form description)
• Optional: prior context such as error messages or partially known file paths

Outputs

• An in-session markdown report listing absolute file paths, matched symbols, and relationship summaries
• For deep-search runs, findings may be persisted to .omx/research/<topic>.md for downstream agents to reference
• A next_steps section indicating which agent should act on the findings

Limits

• Does not create, modify, or delete any file under any circumstance
• Does not run tests, execute build commands, or assess code quality
• Does not make architectural recommendations — that is the architect agent's role

Related agents

• analyst — consumes exploration results to refine requirements
• planner — uses file maps from explore to sequence tasks
• debugger — uses explore to locate the source of a defect
• executor — receives the file list produced by explore and planner before writing code