Use run_in_background: true for ALL explore agents.

This enables true parallel execution:

• All agents start immediately
• Main conversation continues without blocking
• Results collected asynchronously with TaskOutput

Pattern from oh-my-opencode: Default to background + parallel for exploratory work.

Based on .claude/SPEC.md, spawn 3-5 agents with different focuses:

# PARALLEL + BACKGROUND: All Task calls in ONE message

Task(
    subagent_type="Explore",
    description="Find similar features",
    run_in_background=true,
    prompt="""
Explore the codebase for [FEATURE AREA].

Focus: Find similar features to [SPEC REQUIREMENT]

Use ast-grep for semantic search:
- sg -p 'function_name($$$)' --lang [language]
- sg -p 'class $NAME { $$$ }' --lang [language]

Tasks:
- Trace execution paths from entry point to data storage
- Find similar implementations to follow
- Identify patterns used
- Return 5-10 key files with line numbers

Context from SPEC.md:
[paste relevant requirements]
""")

Task(
    subagent_type="Explore",
    description="Map architecture layers",
    run_in_background=true,
    prompt="""
Explore the codebase for [FEATURE AREA].

Focus: Map architecture and abstractions for [AREA]

Use ast-grep for semantic search:
- sg -p 'class $NAME($BASE):' --lang [language]
- sg -p 'interface $NAME { $$$ }' --lang [language]

Tasks:
- Identify abstraction layers
- Find cross-cutting concerns (logging, auth, errors)
- Map module dependencies
- Return 5-10 key files with line numbers

Context from SPEC.md:
[paste relevant requirements]
""")

Task(
    subagent_type="Explore",
    description="Find test infrastructure",
    run_in_background=true,
    prompt="""
Explore the codebase for [FEATURE AREA].

Focus: Test infrastructure and patterns

Use ast-grep for test discovery:
- sg -p 'def test_$NAME($$$):' --lang python
- sg -p 'it($DESC, $$$)' --lang javascript
- sg -p '@pytest.fixture' --lang python

Tasks:
- Find test directory and framework
- Identify existing test patterns
- Check for fixtures, mocks, helpers
- Return 5-10 key test files with line numbers

Context from SPEC.md:
[paste relevant requirements]
""")

After launching all agents in parallel:

• Continue immediately to other work (don't wait)
• Check agent status with /tasks command
• Collect results when ready with TaskOutput tool

1b. Collect Background Results

Once agents complete, collect their findings:

# Check running tasks
/tasks

# Get results from completed agents
TaskOutput(task_id="task-abc123", block=true, timeout=30000)
TaskOutput(task_id="task-def456", block=true, timeout=30000)
TaskOutput(task_id="task-ghi789", block=true, timeout=30000)

Stop Conditions (from oh-my-opencode):

• Enough context to proceed confidently
• Same info appearing across multiple agents
• 2 search iterations yielded nothing new
• Direct answer found

DO NOT over-explore. Time is precious.

2. Consolidate Key Files

After all agents return, consolidate their key files lists:

• Remove duplicates
• Prioritize by relevance to requirements
• Create master list of 10-15 files

3. Read All Key Files

CRITICAL: Main chat must read every file on the key files list.

Read(file_path="src/auth/login.ts")
Read(file_path="src/services/session.ts")
...

This builds deep understanding before asking clarifying questions.

4. Document Findings

Write exploration summary (can be verbal or in .claude/EXPLORATION.md):

• Patterns discovered
• Architecture insights
• Dependencies identified
• Questions raised for clarify phase

Code Search Tools

Prefer semantic search over text search when exploring code.

Use ast-grep (sg) for precise AST-based pattern matching and ripgrep-all (rga) for searching non-code files.

For detailed patterns and usage, see: references/ast-grep-patterns.md

Test Infrastructure Discovery

# Find test directories across common locations
ls -d tests/ test/ spec/ __tests__/ 2>/dev/null

# Find test frameworks in build configuration
cat meson.build 2>/dev/null | grep -i test

# Find test frameworks in Node package manifest
cat package.json 2>/dev/null | grep -E "(test|jest|mocha|vitest)"

# Find pytest configuration in Python projects
cat pyproject.toml 2>/dev/null | grep -i pytest

# Find dev dependencies in Rust projects
cat Cargo.toml 2>/dev/null | grep -i "\[dev-dependencies\]"

# Find and list existing test files
find . -name "*test*" -type f | head -20

# Check for desktop automation tools
which ydotool grim dbus-send 2>/dev/null

# List available D-Bus services for desktop app automation
dbus-send --session --print-reply --dest=org.freedesktop.DBus \
  /org/freedesktop/DBus org.freedesktop.DBus.ListNames 2>/dev/null | grep -i appname

## Key Files to Read

| Priority | File:Line | Purpose |
|----------|-----------|---------|
| 1 | `src/auth/login.ts:45` | Entry point for auth flow |
| 2 | `src/services/session.ts:12` | Session management |
| 3 | `src/middleware/auth.ts:78` | Auth middleware |
| 4 | `src/types/user.ts:1` | User type definitions |
| 5 | `tests/auth/login.test.ts:1` | Existing test patterns |

Skill(skill="workflows:dev-clarify")