hapo-inspect

name	hapo:inspect
description	Fast codebase discovery using parallel agents. Use for file discovery, task context gathering, quick searches across directories. Supports internal (Explore) and external (Gemini) agents.
user-invocable	true
when_to_use	Invoke for fast parallel codebase discovery and file location.
category	discovery
keywords	["discovery","search","explore","context"]
argument-hint	[search-target] [ext]
metadata	{"author":"haposoft","version":"2.0.0"}

Inspect

Fast, token-efficient codebase discovery using parallel agents to find files needed for tasks.

Arguments

• Default: Inspect using built-in Explore subagents in parallel (./references/internal-inspection.md)
• ext: Inspect using external Gemini CLI tool in parallel (./references/external-gemini-inspection.md)

When to Use

• Beginning work on feature spanning multiple directories
• User mentions needing to "find", "locate", or "search for" files
• Starting debugging session requiring file relationships understanding
• User asks about project structure or where functionality lives
• Before changes that might affect multiple codebase parts
• Before review/debug/impact analysis when affected files are unclear

Preflight Scope Gate (MANDATORY - All Modes)

Before scanning with ANY mode (internal or external):

1. Detect repo-root or root-wide scans such as ., /, ./, **/*, **/*.ts, or similar broad patterns without a scoped directory.
2. Apply the built-in no-scan lists below.
3. Prefer file-type or glob hints whenever possible.

When scope is too broad:

Instead of rejecting, use a 2-phase approach: first run a lightweight Structure Scout to understand the real layout, then divide work among parallel agents based on actual findings.

Phase 1 — Structure Scout (Single Agent, Run First)

Spawn one dedicated scout agent to map the top-level structure before any work is divided:

1. Discover top-level layout - Use Glob or Bash ls to list immediate children of the scope root:
   • Top-level directories (src/, apps/, backend/, frontend/, packages/, etc.)
   • Key config files (README.md, package.json, tsconfig.json, pyproject.toml, go.mod, etc.)
   • Monorepo markers (packages/, apps/, lerna.json, pnpm-workspace.yaml, turbo.json)
2. Estimate sub-scope sizes - For each discovered directory, do a rough file count (no deep read needed)
3. Return a division plan - Scout outputs a structured list of logical sub-scopes (1-6), each with:
   • Path or glob pattern
   • Estimated file count
   • Suggested focus area description

Wait for Scout to complete before proceeding to Phase 2.

Phase 2 — Parallel Explore Agents (Based on Scout Results)

Use the Scout's division plan to spawn parallel agents — one per sub-scope:

1. Auto-divide into sub-scopes - Follow Scout's plan, adjusted for:
   • Merging sub-scopes that are too small (< 10 files)
   • Splitting sub-scopes that are too large (> 100 files)
2. Spawn parallel Explore agents - One agent per sub-scope (SCALE 3-6 recommended)
3. Aggregate findings - Collect results from all agents into unified report
4. Suggest next steps - Based on findings, ask if user wants deeper investigation of specific areas

Example flow:

User: "scan entire ~/Desktop/project"

Phase 1 — Scout discovers:
  - README.md, package.json, turbo.json  → monorepo root
  - packages/  → 3 sub-packages (~40 files each)
  - apps/web/  → React frontend (~120 files)
  - apps/api/  → NestJS backend (~80 files)

Scout outputs division plan:
  - Scope A: root config files (README.md, package.json, turbo.json)
  - Scope B: packages/* (shared libs)
  - Scope C: apps/web/ (frontend)
  - Scope D: apps/api/ (backend)

Phase 2 — 4 agents run in parallel on Scope A–D

Result: "This is a monorepo with 2 apps, NestJS backend, React frontend, 3 shared packages..."
Follow-up: "Want to investigate deeper? Choose: backend API | frontend components | shared packages"

Fallback to AskUserQuestion:

• If Scout result is ambiguous (flat structure, no obvious divisions, < 3 distinguishable areas)
• Use AskUserQuestion with 2-4 concrete scope suggestions derived from Scout findings
• After user selects, re-invoke inspect with chosen scope

Built-in No-Scan Guidance

NO_SCAN_PATHS

• .git/
• node_modules/
• dist/
• build/
• .next/
• coverage/
• tmp/
• temp/
• vendor/
• artifacts/
• secrets/
• private/

NO_SCAN_CONTENT_HINTS

• private keys
• token dumps
• credential exports
• .env secrets
• generated bundles
• binary blobs

Configuration

Read from .claude/runtime.json:

{
  "gemini": {
    "model": "gemma-4-31b-it"
  }
}

Default model: gemma-4-31b-it

Note: This file is automatically installed when you run npx @haposoft/cafekit.

Workflow

1. Analyze Task

• Parse user prompt for search targets
• Identify key directories, patterns, file types, lines of code
• Determine optimal SCALE value of subagents to spawn

SCALE Calculation:

SCALE = ceil(estimated_files_to_scan / 50)

Where:

• estimated_files_to_scan = rough count of files matching scope
• Minimum SCALE = 1 (single agent)
• Maximum SCALE = 10 (practical limit for coordination overhead)

SCALE Thresholds:

• SCALE 1-2: Simple, focused searches (< 100 files)
• SCALE 3-5: Medium scope, suitable for external Gemini CLI
• SCALE 6-10: Large scope, requires internal Explore agents

2. Divide and Conquer

• Split codebase into logical segments per agent
• Assign each agent specific directories or patterns
• Ensure no overlap, maximize coverage

3. Register Inspect Tasks

• Skip if: Agent count ≤ 2 (overhead exceeds benefit)
• TaskList first — check for existing inspect tasks in session
• If not found, TaskCreate per agent with scope metadata
• See ./references/internal-inspection.md for patterns and examples

4. Choose Mode

Decision table:

• No ext argument → Use internal Explore agents
• ext argument + SCALE ≤ 5 → Use Gemini CLI (if scope gate passed and Gemini available)
• ext argument + SCALE ≥ 6 → Use internal Explore agents (external not suitable for large scale)
• Gemini unavailable or fails → Fallback to internal Explore agents

Load appropriate reference:

• Internal (Default): ./references/internal-inspection.md (Explore subagents)
• External: ./references/external-gemini-inspection.md (Gemini CLI)

5. Spawn Parallel Agents

Notes:

• TaskUpdate each task to in_progress before spawning its agent
• Prompt detailed instructions for each subagent with exact directories or files it should read
• Remember that each subagent has less than 200K tokens of context window
• Amount of subagents to-be-spawned depends on the current system resources available and amount of files to be scanned
• Each subagent must return a detailed summary report to a main agent

6. Collect Results

• Timeout: 3 minutes per agent (skip non-responders)
• TaskUpdate completed tasks; log timed-out agents in report
• Aggregate findings into single report
• List unresolved questions at end

Report Format

# Inspect Report

## Relevant Files
- `path/to/file.ts` - Brief description
- ...

## Patterns
- Key patterns observed

## Unresolved Questions
- Any gaps in findings

Rules

• Keep scope narrow. Do not use hapo:inspect as a runtime policy engine.
• Prefer listing files first, then reading only the shortlisted files.
• Never encourage scanning ignored/generated/sensitive areas from the no-scan list.
• Keep reports concise and actionable.
• Ensure no overlap between agent scopes.
• Skip non-responding agents, do not retry.

References

• ./references/internal-inspection.md - Using Explore subagents
• ./references/external-gemini-inspection.md - Using Gemini CLI