$research — Codebase Exploration (Codex Tailoring)

This override captures the Codex-native execution model for research tasks.

Codex-Native Flow

Step 1: Setup

ao codex ensure-start 2>/dev/null || true
mkdir -p .agents/research

Step 2: Check Prior Art

ao lookup --query "<topic>" --limit 5 2>/dev/null || true
ao search "<topic>" 2>/dev/null || true

Search all local knowledge directories by content:

for dir in research learnings knowledge patterns retros plans brainstorm; do
  grep -r -l -i "<topic>" .agents/${dir}/ 2>/dev/null
done

Read matched files before proceeding to avoid redundant investigation.

Step 3: Explore the Codebase

Use spawn_agent(agent_type="explorer", ...) for parallel exploration branches. Each explorer gets a focused sub-question:

spawn_agent(
  agent_type="explorer",
  prompt="Investigate: <sub-question>. Search in <directory>. Report file:line citations."
)

For inline exploration (no sub-agents), use iterative retrieval:

1. Start broad with grep -r and find scoped to specific directories
2. Score results by relevance (0-1)
3. Extract new search terms from high-relevance files
4. Repeat for up to 3 refinement cycles

Discovery tiers (execute in order):

• Code-Map: read docs/code-map/README.md → find category → read feature file
• Scoped Search: grep -r "<topic>" <specific-dir>/ — always scope to a directory
• Source Code: Read files identified by prior tiers
• Prior Knowledge: Search .agents/ directories
• External Docs: Web search as last resort

Step 4: Synthesize Findings

Write to .agents/research/YYYY-MM-DD-<topic-slug>.md:

---
id: research-YYYY-MM-DD-<topic-slug>
type: research
date: YYYY-MM-DD
---

# Research: <Topic>

**Scope:** <what was investigated>

## Summary
<2-3 sentence overview>

## Key Files
| File | Purpose |
|------|---------|
| path/to/file | Description |

## Findings
<detailed findings with file:line citations>

## Recommendations
<next steps or actions>

Step 5: Report Completion

Tell the user what was found, where it's saved, and suggest /plan as the next step.

Constraints

1. Always scope searches to specific directories — never grep the full repo unscoped.
2. Cite specific file:line references for all claims.
3. Use spawn_agent(agent_type="explorer") for parallel exploration; otherwise explore inline.
4. Write output to .agents/research/ — research must produce a file artifact.