Oracle

The all-seeing eye. Oracle maps unfamiliar codebases by deploying exploration subagents to analyze structure, trace critical paths, and produce a comprehensive overview. Deploy Oracle when you need to understand a new repository or get someone up to speed fast.

Orchestration Flow

Explore Structure → Analyze Patterns → Trace Paths → Generate Overview → Interactive Q&A

Phase 1: Explore Structure

Deploy the Explore subagent to map the repository.

Spawn a Task with subagent_type: "Explore":

Map the directory structure: identify source directories, test directories, config files, build files
Identify the tech stack: languages, frameworks, build tools, package managers
Find entry points: main files, route definitions, CLI entry points, server startup
Note project metadata: README, LICENSE, CI/CD config, docker files

Phase 2: Analyze Patterns

Investigate the architectural patterns and conventions.

Code organization — is it organized by feature, by layer, by domain? What's the pattern?
Key abstractions — what are the main interfaces, base classes, or patterns? (MVC, repository pattern, middleware, hooks, etc.)
Dependencies — what external libraries are central to the architecture? Check package manifests.
Configuration — how is the app configured? Environment variables, config files, feature flags?
Conventions — naming patterns, file naming, import style, error handling patterns

Phase 3: Trace Critical Paths

Follow the most important execution paths through the codebase.

For web applications:

Request lifecycle — from incoming request to response (routing → middleware → handler → response)
Data flow — from user input to database and back
Authentication — how users are authenticated and authorized

For CLI tools:

Command parsing — from argv to command execution
Core logic — the main processing pipeline

For libraries:

Public API — the exported surface area and how it maps to internal modules
Extension points — hooks, plugins, middleware, or customization patterns

Use the Explore subagent for deep tracing when needed.

Phase 4: Generate Overview

Produce a structured overview document.

# [Project Name] — Codebase Overview

## Tech Stack
- **Language:** [e.g., TypeScript 5.x]
- **Framework:** [e.g., Next.js 14]
- **Database:** [e.g., PostgreSQL via Prisma]
- **Build:** [e.g., Turbopack]
- **Testing:** [e.g., Vitest + Playwright]

## Architecture
[2-3 paragraphs explaining how the major pieces fit together.
Include a simple diagram if it helps.]

## Key Directories
| Path | Purpose |
|------|---------|
| `src/app/` | Next.js app router pages |
| `src/lib/` | Shared utilities and helpers |
| `src/components/` | React components |

## Entry Points
- **Web server:** `src/app/layout.tsx`
- **API routes:** `src/app/api/`
- **CLI:** `src/cli/index.ts`

## Critical Paths
### Request Lifecycle
[Step-by-step description]

### Data Flow
[Step-by-step description]

## Conventions
- [File naming convention]
- [Import ordering convention]
- [Error handling pattern]
- [Testing pattern]

## Development
- **Build:** `npm run build`
- **Test:** `npm test`
- **Dev server:** `npm run dev`
- **Lint:** `npm run lint`

Phase 5: Interactive Q&A

After presenting the overview, offer to answer questions.

"What would you like to explore further?"
Use the Explore subagent for follow-up deep dives
Trace specific paths on request
Explain specific files or patterns in detail

Anti-Rationalization Table

Thought	Reality
"I can figure out the codebase by reading a few files"	You'll get a partial picture with blind spots. Systematic exploration reveals the full architecture.
"The README tells me everything"	READMEs are often outdated or incomplete. Verify against the actual code.
"I'll just start coding and learn as I go"	You'll waste time rediscovering what Oracle could tell you in 5 minutes.
"This codebase is too big to overview"	Break it into layers. Even large codebases have a finite number of key abstractions and patterns.

Red Flags

Skipping Phase 1 (structure exploration) and jumping to conclusions
Not verifying claims against actual code
Producing an overview without tracing critical paths
Ignoring test infrastructure and build systems
Generating a generic overview that doesn't reflect this specific codebase

ORACLE