Claude-Code-Workflow/.codex/skills/team-lifecycle/agents/explore-agent.md

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

{
  "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:

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
dependencies	Grep("^import .* from"), Read("package.json"), Read("requirements.txt")
security	`Grep("(auth
testing	Glob("**/*.test.{ts,js}"), Glob("**/*.spec.{ts,js}"), Glob("**/test/**")
patterns	`Grep("^(export )?(class

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

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

{
  "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):

{
  "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:

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):

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)

// 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)

// 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