english/.opencode/skills/scout/references/internal-scouting.md

Internal Scouting with Explore Subagents

Use Explore subagents when SCALE >= 6 or external tools unavailable.

How It Works

Spawn multiple Explore subagents via Task tool to search codebase in parallel.

Task Tool Configuration

subagent_type: "Explore"

Prompt Template

Quickly scout {DIRECTORY} for files related to: {USER_PROMPT}

Instructions:
- Search for relevant files matching the task
- Use Glob/Grep for file discovery
- List files with brief descriptions
- Timeout: 3 minutes max
- Skip if timeout reached

Report format:
## Found Files
- `path/file.ext` - description

## Patterns
- Key patterns observed

Spawning Strategy

Directory Division

Split codebase logically:

• src/ - Source code
• lib/ - Libraries
• tests/ - Test files
• config/ - Configuration
• api/ - API routes

Parallel Execution

• Spawn all agents in single Task tool call
• Each agent gets distinct directory scope
• No overlap between agents

Example

User prompt: "Find authentication-related files"

Agent 1: Scout src/auth/, src/middleware/ for auth files
Agent 2: Scout src/api/, src/routes/ for auth endpoints
Agent 3: Scout tests/ for auth tests
Agent 4: Scout lib/, utils/ for auth utilities
Agent 5: Scout config/ for auth configuration
Agent 6: Scout types/, interfaces/ for auth types

Timeout Handling

• Set 3-minute timeout per agent
• Skip non-responding agents
• Don't restart timed-out agents
• Aggregate available results

Reading File Content

When needing to read file content, use chunking to stay within context limits (<150K tokens safe zone).

Step 1: Get Line Counts

wc -l path/to/file1.ts path/to/file2.ts path/to/file3.ts

Step 2: Calculate Chunks

• Target: ~500 lines per chunk (safe for most files)
• Max files per agent: 3-5 small files OR 1 large file chunked

Chunking formula:

chunks = ceil(total_lines / 500)
lines_per_chunk = ceil(total_lines / chunks)

Step 3: Spawn Parallel Bash Agents

Small files (<500 lines each):

Task 1: subagent_type="Bash", prompt="cat file1.ts file2.ts"
Task 2: subagent_type="Bash", prompt="cat file3.ts file4.ts"

Large file (>500 lines) - use sed for ranges:

Task 1: subagent_type="Bash", prompt="sed -n '1,500p' large-file.ts"
Task 2: subagent_type="Bash", prompt="sed -n '501,1000p' large-file.ts"
Task 3: subagent_type="Bash", prompt="sed -n '1001,1500p' large-file.ts"

Chunking Decision Tree

File < 500 lines     → Read entire file
File 500-1500 lines  → Split into 2-3 chunks
File > 1500 lines    → Split into ceil(lines/500) chunks

Spawn all in single message for parallel execution.

Result Aggregation

Combine results from all agents:

1. Deduplicate file paths
2. Merge descriptions
3. Note any gaps/timeouts
4. List unresolved questions