explore-codebase

**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 SCOPE (from agent) - {paste any out-of-scope discoveries} --- ### Agent 2: Usage ... ``` **Mark the write-to-log todo complete after each write.** ### Phase 4: Cross-Reference & Evaluate Gaps #### 4.1 Analyze findings across agents After ALL agents complete, analyze for: - **Duplicates**: Same file in multiple agents' lists - **Overlapping ranges**: Same file with different line ranges - **Out-of-scope discoveries**: Items agents noted but didn't pursue - **Coverage gaps**: Obvious areas no agent covered - **Priority conflicts**: Same file at different priority levels #### 4.2 Update orchestration file with cross-reference ```markdown ## Cross-Reference Analysis ### Duplicates Found - {file}: appeared in Agent 1 (MUST READ) and Agent 3 (SHOULD READ) → keep MUST READ - {file}: appeared in Agent 1 (:50-100) and Agent 2 (:80-150) → merge to :50-150 ### Out-of-Scope Discoveries (need follow-up?) - Agent 1 noted: {discovery} → excluded because: {reason} - Agent 2 noted: {discovery} → excluded because: {reason} ### Coverage Check - [ ] Core entry points covered? - [ ] Error handling paths covered? - [ ] Configuration dependencies identified? - [ ] Test coverage visible? ### Gaps Identified - {Gap 1}: {why it's a gap} - {Gap 2}: {why it's a gap} ``` #### 4.3 Evaluate gaps ```markdown ## Gap Evaluation ### Gaps Requiring Follow-up - [ ] {Gap}: {specific - e.g., "No agent explored error handling paths"} ### Gaps to Note (don't pursue) - {Gap}: {why minor - e.g., "Logging files not critical for understanding topic"} ### Decision - Gaps requiring follow-up: {count} - **Action**: {LAUNCH GAP-FILL | PROCEED TO SYNTHESIS} ``` **Gap-fill rules:** - thorough: only for obvious critical gaps (missing core area) - very-thorough: for any identified gaps - Maximum 1-2 gap-fill agents #### 4.4 Launch gap-fill (if needed) **Gap-fill prompt:** ``` Fill exploration gap: {specific gap} Context from initial exploration: - Already found: {summary of files from initial agents} - Gap identified: {what's missing} Focus narrowly on this gap. Don't re-explore already-covered areas. Thoroughness: medium ``` After gap-fill agents return, write findings to orchestration file and update cross-reference. ### Phase 5: Synthesize Unified Reading List #### 5.1 Refresh context (MANDATORY) **CRITICAL**: Read the FULL orchestration file to restore ALL agent findings into context. ``` - [x] Refresh context: read full orchestration file ← Must complete BEFORE synthesis - [ ] Synthesize unified reading list ``` **Why this matters**: By this point, findings from multiple agents have been written to the file. Context degradation means details may have faded. Reading the full file brings all findings into recent context. #### 5.2 Generate unified reading list **Only after completing 5.1** - synthesize all agent findings: ```markdown ## OVERVIEW [Merged overview combining insights from all agents. 150-400 words. Describe: file organization, relationships between areas, entry points, data flow. Synthesize structural knowledge from all angles explored.] ## FILES TO READ MUST READ: - path/file.ext:lines - [reason] ... SHOULD READ: - path/file.ext:lines - [reason] ... REFERENCE: - path/file.ext - [reason] ... ## EXPLORATION SUMMARY | Angle | Agent | Files Found | Key Discovery | |-------|-------|-------------|---------------| | Implementation | 1 | N | {1-liner} | | Usage | 2 | N | {1-liner} | | Tests | 3 | N | {1-liner} | | Gap-fill | 4 | N | {1-liner} | **Gaps noted but not explored**: {list or "none"} --- Orchestration file: {path} ``` **Deduplication rules:** - Same file from multiple agents → keep highest priority, note "(multiple agents)" - Overlapping line ranges → merge into single range (union) - Conflicting priorities → use higher priority (MUST > SHOULD > REFERENCE) #### 5.3 Mark all todos complete --- ## Key Principles | Principle | Rule | |-----------|------| | Thoroughness first | Determine level before any exploration | | Write after each agent | Write to orchestration file after EACH agent | | Todos with write-to-log | Each agent collection gets a write-to-orchestration-file todo | | Parallel launch | All initial agents in single message |