explore-codebase

What this skill does

**User request**: $ARGUMENTS

Orchestrate codebase exploration agents to find all files relevant to a query, then synthesize into a unified reading list.

**Loop**: Determine thoroughness → [Quick/Medium: single agent → return] | [Thorough+: Create orchestration file → Decompose → Launch Wave 1 → Collect findings → Cross-reference → Evaluate gaps → [Gap-fill if needed] → Refresh context → Synthesize → Output]

**Orchestration file** (thorough+ only): `/tmp/explore-orchestration-{topic-slug}-{YYYYMMDD-HHMMSS}.md`

**You do NOT read source files** - you orchestrate agents and synthesize their findings into a unified reading list. The main agent reads the files after you return.

---

## Thoroughness Level

**FIRST**: Determine thoroughness before exploring. Parse from natural language or auto-select.

**Auto-selection**:
- Single entity lookup ("where is X?") → quick
- Single bounded feature/bug → medium
- Multi-area feature, interaction queries → thorough
- "comprehensive"/"all"/"architecture"/"audit" → very-thorough

| Level | Exploration Strategy |
|-------|---------------------|
| **quick** | Single agent, no orchestration file, return agent output directly |
| **medium** | Single agent, no orchestration file, return agent output directly |
| **thorough** | Orchestration file, orthogonal agents (2-3), cross-reference, optional gap-fill |
| **very-thorough** | Orchestration file, orthogonal agents (3-4), cross-reference, gap-fill wave |

**Topic-slug format**: Extract 2-4 key terms, lowercase, replace spaces with hyphens. Example: "authentication flow" → `authentication-flow`

State: `**Thoroughness**: [level] — [reason]` then proceed.

---

## Quick / Medium Flow

### 1. Launch single agent

Launch a `vibe-extras:codebase-explorer` agent with: "$ARGUMENTS"

### 2. Return agent output directly

When agent returns, its output becomes your output. No synthesis needed.

---

## Thorough / Very-Thorough Flow

### Phase 1: Initial Setup

#### 1.1 Get timestamp & create todo list

Run: `date +%Y%m%d-%H%M%S` → for filename and timestamps

**Starter todos** (seeds - list grows during decomposition):

```
- [ ] Create orchestration file; done when file created
- [ ] Topic decomposition→log; done when angles identified
- [ ] (expand: agent assignments as decomposition reveals)
- [ ] Launch Wave 1 agents; done when all agents spawned
- [ ] Collect Agent 1→log; done when findings written
- [ ] Collect Agent 2→log; done when findings written
- [ ] (expand: more agents as needed)
- [ ] Cross-reference→log; done when duplicates/conflicts resolved
- [ ] Evaluate gaps→log; done when gaps classified
- [ ] (expand: gap-fill if continuing)
- [ ] Refresh: read full orchestration file
- [ ] Synthesize→unified reading list; done when all files deduplicated + prioritized
```

**Critical todos** (never skip):
- `→log` after EACH agent completion
- `Refresh:` ALWAYS before synthesis

#### 1.2 Create orchestration file

Path: `/tmp/explore-orchestration-{topic-slug}-{YYYYMMDD-HHMMSS}.md`

```markdown
# Codebase Exploration Orchestration: {topic}
Timestamp: {YYYYMMDD-HHMMSS}
Thoroughness: {level}

## Exploration Query
{Original query}

## Topic Decomposition
- Core topic: {main thing to find}
- Angles to explore: (populated in Phase 2)
- Expected agent count: {based on level}

## Agent Assignments
(populated in Phase 2)

## Agent Status
(updated as agents complete)

## Collected Findings
(populated as agents return - includes OVERVIEW and FILES TO READ from each)

## Cross-Reference Analysis
(populated after all agents return)

## Gap Evaluation
(populated after cross-reference)

## Unified Reading List
(populated in synthesis)
```

### Phase 2: Decompose & Assign

#### 2.1 Decompose into orthogonal angles

**Standard angles for codebase exploration:**

| Angle | Focus | Example Scope |
|-------|-------|---------------|
| **Implementation** | Core logic files | "Files that implement {topic} behavior" |
| **Usage** | Callers, integration points | "Files that call/use {topic}" |
| **Tests** | Test files, fixtures | "Test files for {topic}" |
| **Config** | Configuration, environment | "Config files affecting {topic}" |

**Decomposition rules:**
- thorough: 2-3 angles (usually Implementation + Usage + Tests)
- very-thorough: 3-4 angles (all four)
- Each angle gets explicit boundaries to prevent overlap

**Orthogonality check**: Before assigning agents, verify no two angles would naturally search the same files.

#### 2.2 Plan agent assignments with boundaries

| Angle | Focus | Explicitly EXCLUDE |
|-------|-------|-------------------|
| Implementation | Core {topic} files | callers, tests, config |
| Usage | Files that call {topic} | core implementation, tests, config |
| Tests | Test files for {topic} | implementation, callers, config |
| Config | Config affecting {topic} | implementation, callers, tests |

#### 2.3 Expand todos for each agent

```
- [x] Topic decomposition→log; angles identified
- [ ] Agent 1: implementation angle; done when core files found
- [ ] Agent 2: usage angle; done when callers identified
- [ ] Agent 3: tests angle; done when test files found
- [ ] Launch Wave 1 agents (parallel); done when all spawned
- [ ] Collect Agent 1→log; done when findings written
- [ ] Collect Agent 2→log; done when findings written
- [ ] Collect Agent 3→log; done when findings written
- [ ] Cross-reference→log; done when duplicates/conflicts resolved
...
```

#### 2.4 Update orchestration file

```markdown
## Topic Decomposition
- Core topic: {topic}
- Angles identified:
  1. Implementation: {what this covers}
  2. Usage: {what this covers}
  3. Tests: {what this covers}

## Agent Assignments
| Agent | Angle | Prompt | Status |
|-------|-------|--------|--------|
| 1 | Implementation | "{prompt}" | Pending |
| 2 | Usage | "{prompt}" | Pending |
| 3 | Tests | "{prompt}" | Pending |
```

### Phase 3: Launch Parallel Agents

#### 3.1 Launch agents in single message

Launch `vibe-extras:codebase-explorer` agents for each angle. **Launch all agents in parallel** (single message with multiple agent invocations).

**Agent prompt template:**
```
{Specific exploration focus for this angle}

YOUR ASSIGNED SCOPE:
- {what to explore}
- {specific patterns or areas}

DO NOT EXPLORE (other agents cover these):
- {angles assigned to other agents}

Thoroughness within scope: medium
```

**Example for "authentication" query (thorough):**

Agent 1 (Implementation):
```
Find core authentication implementation files.

YOUR ASSIGNED SCOPE:
- Auth service/module files
- Token generation, validation logic
- Session management implementation
- Password hashing, credential verification

DO NOT EXPLORE (other agents cover these):
- Files that CALL auth (usage patterns)
- Test files
- Config files

Thoroughness within scope: medium
```

Agent 2 (Usage):
```
Find files that use/call authentication.

YOUR ASSIGNED SCOPE:
- Route handlers that require auth
- Middleware that checks auth
- Services that depend on auth context
- Integration points with auth

DO NOT EXPLORE (other agents cover these):
- Core auth implementation files
- Test files
- Config files

Thoroughness within scope: medium
```

Agent 3 (Tests):
```
Find authentication test files.

YOUR ASSIGNED SCOPE:
- Unit tests for auth
- Integration tests for auth flows
- Test fixtures and mocks for auth
- E2E tests involving authentication

DO NOT EXPLORE (other agents cover these):
- Core auth implementation
- Files that use auth
- Config files

Thoroughness within scope: medium
```

#### 3.2 Update orchestration file after EACH agent completes

**After EACH agent returns**, immediately write findings:

```markdown
## Collected Findings

### Agent 1: Implementation
**Status**: Complete
**Files Found**: {count}

#### OVERVIEW (from agent)
{paste agent's overview}

#### FILES TO READ (from agent)
MUST READ:
- {paste agent's must-read list}

SHOULD READ:
- {paste agent's should-read list}

REFERENCE:
- {paste agent's reference list}

#### OUT OF S