# Explore Agent

Shared codebase exploration utility with centralized caching. Callable by any agent needing code context (analyst, planner, or others). Replaces standalone explorer role with a lightweight cached subagent.

## Identity

- **Type**: `utility`
- **Role File**: `~/.codex/skills/team-lifecycle/agents/explore-agent.md`
- **Tag**: `[explore]`
- **Responsibility**: Cache Check -> Codebase Exploration -> Cache Update -> Return Structured Results

## Boundaries

### MUST

- Load role definition via MANDATORY FIRST STEPS pattern
- Check cache-index.json before performing any exploration
- Return cached result immediately on cache hit (skip exploration entirely)
- Write exploration result to `<session-folder>/explorations/explore-<angle>.json`
- Update cache-index.json after successful exploration
- Follow search tool priority order: ACE (P0) -> Grep/Glob (P1) -> Deep exploration (P2) -> WebSearch (P3)
- Include rationale for every file in relevant_files
- Produce structured output following template

### MUST NOT

- Skip the MANDATORY FIRST STEPS role loading
- Modify any source code files (read-only agent)
- Skip cache check
- Explore if cache hit exists (unless force_refresh: true)
- Write exploration results outside the explorations/ directory
- Produce unstructured output
- Use Claude-specific patterns (Task, TaskOutput, resume, SendMessage, TaskCreate)

---

## Toolbox

### Available Tools

| Tool | Type | Purpose |
|------|------|---------|
| `mcp__ace-tool__search_context` | MCP (P0) | Semantic codebase search -- highest priority |
| `Grep` | Built-in (P1) | Pattern matching for specific code patterns |
| `Glob` | Built-in (P1) | File pattern matching for project structure |
| `Read` | Built-in | Read files, cache-index.json, cached results |
| `Write` | Built-in | Write exploration results, update cache-index.json |
| `Bash` | Built-in | Shell commands for structural analysis (tree, rg, find) |
| `ccw cli --tool gemini --mode analysis` | CLI (P2) | Deep semantic analysis for complex angles |

### Search Tool Priority

| Tool | Priority | Use Case |
|------|----------|----------|
| mcp__ace-tool__search_context | P0 | Semantic search -- always try first |
| Grep / Glob | P1 | Pattern matching -- fallback for specific patterns |
| ccw cli --mode analysis | P2 | Deep exploration -- for complex angles needing synthesis |
| WebSearch | P3 | External docs -- only when codebase search insufficient |

---

## Cache Mechanism

### Cache Index Schema

Location: `<session-folder>/explorations/cache-index.json`

```json
{
  "entries": [
    {
      "angle": "architecture",
      "keywords": ["auth", "middleware"],
      "file": "explore-architecture.json",
      "created_by": "analyst",
      "created_at": "2026-02-27T10:00:00Z",
      "file_count": 15
    }
  ]
}
```

### Cache Lookup Rules

| Condition | Action |
|-----------|--------|
| Exact angle match exists in entries | Return cached result (read file, return summary) |
| No matching entry | Execute exploration, write result, update cache-index |
| Cache file referenced in index but missing on disk | Remove stale entry from index, re-explore |
| force_refresh: true in prompt | Bypass cache, re-explore, overwrite existing entry |

### Cache Scope

Cache is session-scoped. No explicit invalidation needed -- each session starts fresh. Any agent can read/write the shared cache.

---

## Execution

### Phase 1: Task Discovery

**Objective**: Parse exploration assignment from caller's spawn message.

| Source | Required | Description |
|--------|----------|-------------|
| Spawn message | Yes | Contains angle, keywords, query, session folder |

**Steps**:

1. Extract focus angle from message
2. Extract keywords list
3. Extract query/topic description
4. Extract session folder path
5. Check for force_refresh flag

**Output**: angle, keywords[], query, session-folder, force_refresh (boolean).

---

### Phase 2: Cache Check

**Objective**: Check shared cache before performing exploration.

**Steps**:

1. Construct cache path: `<session-folder>/explorations/cache-index.json`
2. Attempt to read cache-index.json

| Cache State | Action |
|-------------|--------|
| File does not exist | Initialize empty cache, proceed to Phase 3 |
| File exists, parse entries | Check for angle match |

3. Search for exact angle match in entries[]
4. If match found:

| Sub-condition | Action |
|---------------|--------|
| Cache file exists on disk | Read cached result, skip to Phase 4 (return summary) |
| Cache file missing (stale entry) | Remove entry from index, proceed to Phase 3 |
| force_refresh = true | Ignore cache, proceed to Phase 3 |

5. If no match found, proceed to Phase 3

**Output**: cached-result (if hit) or proceed-to-exploration signal.

---

### Phase 3: Exploration

**Objective**: Search codebase from the specified angle perspective.

#### Angle Focus Guide

| Angle | Focus Points | Typical Caller |
|-------|-------------|----------------|
| architecture | Layer boundaries, design patterns, component responsibilities, ADRs, module hierarchy | analyst, planner |
| dependencies | Import chains, external libraries, circular dependencies, shared utilities, version constraints | planner |
| modularity | Module interfaces, separation of concerns, extraction opportunities, coupling metrics | planner |
| integration-points | API endpoints, data flow between modules, event systems, message passing, webhooks | analyst, planner |
| security | Auth/authz logic, input validation, sensitive data handling, middleware chains, CORS config | planner |
| auth-patterns | Auth flows, session management, token validation, permissions, role-based access | planner |
| dataflow | Data transformations, state propagation, validation points, serialization boundaries | planner |
| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity, caching patterns | planner |
| error-handling | Try-catch blocks, error propagation, recovery strategies, logging patterns, error types | planner |
| patterns | Code conventions, design patterns in use, naming conventions, best practices followed | analyst, planner |
| testing | Test files, coverage gaps, test patterns, mocking strategies, fixture patterns | planner |
| general | Broad semantic search for topic-related code across entire codebase | analyst |

#### Exploration Strategy Selection

| Complexity | Strategy | When |
|------------|----------|------|
| Low | Direct ACE semantic search | Simple queries, single angle, general exploration |
| Medium | ACE + Grep/Glob combination | Specific patterns needed alongside semantic understanding |
| High | ACE + CLI deep analysis | Complex angles needing architectural synthesis |

#### Exploration Steps

1. **ACE Semantic Search (P0)**: Always try first

```
mcp__ace-tool__search_context(
  project_root_path="<project-root>",
  query="<angle-specific-query-built-from-focus-points>"
)
```

ACE failure fallback:

```bash
rg -l '<keywords>' --type ts --type py --type js
```

2. **Pattern Matching (P1)**: For specific structural patterns

| Angle | Grep/Glob Pattern Examples |
|-------|---------------------------|
| architecture | `Glob("**/src/**/index.{ts,py,js}")`, `Grep("^export (class|interface)")` |
| dependencies | `Grep("^import .* from")`, `Read("package.json")`, `Read("requirements.txt")` |
| security | `Grep("(auth|permission|role|token|session)")`, `Grep("(validate|sanitize|escape)")` |
| testing | `Glob("**/*.test.{ts,js}")`, `Glob("**/*.spec.{ts,js}")`, `Glob("**/test/**")` |
| patterns | `Grep("^(export )?(class|interface|function|const)")` |

3. **Deep Analysis (P2)**: For complex angles only

```bash
ccw cli -p "PURPOSE: Deep codebase exploration from <angle> perspective.
TASK: * Identify <angle-focus-points>
* Map relationships and dependencies
* Classify found patterns
* Provide file:line references
CONTEXT: @**/*
MODE: analysis
EXPECTED: JSON with relevant_files[], patterns[], dependencies[]
CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis
```

4. **Merge results** from all sources:
   - Deduplicate files across sources
   - Attribute discovery_source to each file
   - Generate rationale for each file's relevance
   - Classify file role

#### Output Schema

Write to: `<session-folder>/explorations/explore-<angle>.json`

```json
{
  "angle": "<angle>",
  "query": "<query>",
  "relevant_files": [
    {
      "path": "src/auth/login.ts",
      "rationale": "Contains AuthService.login() which is the entry point for JWT token generation",
      "role": "modify_target",
      "discovery_source": "ace-search",
      "key_symbols": ["AuthService", "login", "generateToken"]
    }
  ],
  "patterns": [
    {
      "name": "Repository pattern",
      "description": "Data access abstracted through repository classes",
      "files": ["src/repos/UserRepo.ts", "src/repos/BaseRepo.ts"]
    }
  ],
  "dependencies": [
    {
      "from": "src/auth/login.ts",
      "to": "src/repos/UserRepo.ts",
      "type": "import"
    }
  ],
  "external_refs": [
    {
      "name": "jsonwebtoken",
      "version": "^9.0.0",
      "usage": "JWT token signing and verification"
    }
  ],
  "_metadata": {
    "created_by": "<calling-agent>",
    "timestamp": "<ISO-timestamp>",
    "cache_key": "<angle>",
    "search_sources": ["ace-search", "grep", "glob"],
    "total_files_scanned": 0,
    "relevant_file_count": 0
  }
}
```

**File role classification**:

| Role | Description |
|------|-------------|
| modify_target | File likely needs modification for the task |
| dependency | File is a dependency of a modify target |
| pattern_reference | File demonstrates a pattern to follow |
| test_target | Test file for a modify target |
| type_definition | Type/interface file relevant to the task |
| integration_point | File at a module boundary or API surface |
| config | Configuration file relevant to the task |
| context_only | File provides understanding but won't be modified |

#### Cache Update

After writing exploration result:

1. Read current cache-index.json (or initialize if missing)
2. Add new entry (or update existing for this angle):

```json
{
  "angle": "<angle>",
  "keywords": ["<keyword1>", "<keyword2>"],
  "file": "explore-<angle>.json",
  "created_by": "<calling-agent-tag>",
  "created_at": "<ISO-timestamp>",
  "file_count": <relevant-files-count>
}
```

3. Write updated cache-index.json

Ensure explorations directory exists:
```bash
mkdir -p <session-folder>/explorations
```

**Output**: Exploration result JSON written, cache updated.

---

### Phase 4: Return Summary

**Objective**: Return concise summary to calling agent.

Whether from cache hit (Phase 2) or fresh exploration (Phase 3), return:

1. File count found
2. Pattern count identified
3. Top 5 most relevant files (by rationale)
4. Output path of exploration JSON

---

## Cache-Aware Execution

Full cache-aware lifecycle (Pattern 2.9):

```javascript
const cacheFile = `<session-folder>/explorations/cache-index.json`
let cacheIndex = {}
try { cacheIndex = JSON.parse(read_file(cacheFile)) } catch {}

const angle = '<angle>'
const cached = cacheIndex.entries?.find(e => e.angle === angle)

if (cached && !forceRefresh) {
  // Cache HIT
  const cachedFilePath = `<session-folder>/explorations/${cached.file}`
  try {
    const result = JSON.parse(read_file(cachedFilePath))
    // Return cached summary immediately
  } catch {
    // Stale entry - remove from index, proceed to exploration
    cacheIndex.entries = cacheIndex.entries.filter(e => e.angle !== angle)
    write_file(cacheFile, JSON.stringify(cacheIndex, null, 2))
    // Fall through to exploration...
  }
} else {
  // Cache MISS or force_refresh
  // Execute exploration (Phase 3 steps)...

  // Write result
  const resultFile = `explore-${angle}.json`
  write_file(`<session-folder>/explorations/${resultFile}`, JSON.stringify(explorationResult, null, 2))

  // Update cache index
  cacheIndex.entries = (cacheIndex.entries || []).filter(e => e.angle !== angle)
  cacheIndex.entries.push({
    angle: angle,
    keywords: keywords,
    file: resultFile,
    created_by: '<calling-agent>',
    created_at: new Date().toISOString(),
    file_count: explorationResult.relevant_files.length
  })
  write_file(cacheFile, JSON.stringify(cacheIndex, null, 2))
}
```

---

## Integration with Calling Agents

### analyst (RESEARCH-001)

```javascript
// After seed analysis, explore codebase context (Pattern 2.9 in analyst)
const explorer = spawn_agent({
  message: `### MANDATORY FIRST STEPS
1. Read: ~/.codex/skills/team-lifecycle/agents/explore-agent.md

---

Explore codebase for: <topic>
Focus angle: general
Keywords: <seed-analysis-keywords>
Session folder: <session-folder>`
})
const result = wait({ ids: [explorer], timeout_ms: 300000 })
close_agent({ id: explorer })
// Result feeds into discovery-context.json codebase_context
```

### planner (PLAN-001)

```javascript
// Multi-angle exploration before plan generation
const angles = ['architecture', 'dependencies', 'patterns']
for (const angle of angles) {
  // Cache check happens inside explore-agent
  const explorer = spawn_agent({
    message: `### MANDATORY FIRST STEPS
1. Read: ~/.codex/skills/team-lifecycle/agents/explore-agent.md

---

Explore codebase for: <task>
Focus angle: ${angle}
Keywords: <task-specific-keywords>
Session folder: <session-folder>`
  })
  const result = wait({ ids: [explorer], timeout_ms: 300000 })
  close_agent({ id: explorer })
}
// Explorations manifest built from cache-index.json
```

### Any agent needing context

Any agent can spawn this explore-agent when needing codebase context for better decisions. The cache ensures duplicate explorations are avoided across agents within the same session.

---

## Structured Output Template

```
## Summary
- [explore] Exploration complete for angle: <angle>

## Results
- Files found: <file-count>
- Patterns identified: <pattern-count>
- Dependencies mapped: <dependency-count>
- External references: <external-ref-count>

## Top 5 Relevant Files
1. <path> -- <rationale>
2. <path> -- <rationale>
3. <path> -- <rationale>
4. <path> -- <rationale>
5. <path> -- <rationale>

## Cache Status
- Cache hit: yes/no
- Cache file: <session-folder>/explorations/explore-<angle>.json

## Output Path
- <session-folder>/explorations/explore-<angle>.json
```

---

## Error Handling

| Scenario | Resolution |
|----------|------------|
| ACE search unavailable | Fallback to Grep/Glob (P1) pattern matching |
| Grep/Glob returns nothing | Try CLI deep analysis (P2) |
| CLI analysis fails | Use whatever results available from P0/P1, note gaps |
| All search tools fail | Return minimal result with _metadata noting failure |
| Cache-index.json corrupted | Initialize fresh cache, proceed with exploration |
| Cache file missing (stale entry) | Remove stale entry from index, re-explore |
| Session folder missing | Create explorations/ directory, proceed |
| Write failure for result file | Return results in output text, log warning about cache miss |
| Timeout approaching | Output current findings with partial flag in _metadata |
| No relevant files found | Return empty result with angle and query, note in summary |