@haposoft/cafekit 0.4.0 → 0.5.0

package/bin/install.js

@@ -17,6 +17,7 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const { execSync } = require('child_process');
 const packageJson = require('../package.json');
 
 function validateManifestV2(manifest) {
@@ -487,8 +488,8 @@ function copyPlatformFiles(platformKey, results, options = {}) {
     if (platformKey === 'claude') {
       requiredSkills = CLAUDE_MIGRATION_MANIFEST?.skills?.required || [];
     } else if (platformKey === 'antigravity') {
-      // Antigravity also needs impact-analysis skill
-      requiredSkills = ['impact-analysis'];
+      // Antigravity also needs shared investigation and impact-analysis skills
+      requiredSkills = ['impact-analysis', 'debug'];
     }
 
     requiredSkills
@@ -768,6 +769,120 @@ function mergeClaudeSettings(platformKey, results, options = {}) {
   fs.writeFileSync(targetPath, JSON.stringify(mergedSettings, null, 2), 'utf8');
 }
 
+// ═══════════════════════════════════════════════════════════
+// GEMINI CLI SETUP
+// ═══════════════════════════════════════════════════════════
+
+function checkGeminiCLI() {
+  try {
+    execSync('which gemini', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function installGeminiCLI() {
+  console.log('\n⚙ Installing gemini-cli...');
+  try {
+    execSync('npm install -g @google/generative-ai-cli', { stdio: 'inherit' });
+    console.log('  ✓ gemini-cli installed successfully');
+    return true;
+  } catch (error) {
+    console.log('  ✗ Failed to install gemini-cli automatically');
+    console.log('  Please run manually: npm install -g @google/generative-ai-cli');
+    return false;
+  }
+}
+
+async function promptInstallGemini() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  console.log('\n📦 Optional: Gemini CLI Installation');
+  console.log('  hapo:inspect with ext mode requires gemini-cli');
+  console.log('  • Install now: Auto-install and configure API key');
+  console.log('  • Skip: You can still use hapo:inspect in internal mode');
+  console.log();
+
+  return new Promise((resolve) => {
+    rl.question('Install gemini-cli? (Y/n): ', (answer) => {
+      rl.close();
+      const response = answer.trim().toLowerCase();
+      resolve(response === '' || response === 'y' || response === 'yes');
+    });
+  });
+}
+
+async function promptGeminiAPIKey() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  console.log('\n📝 Gemini API Key Configuration');
+  console.log('  Get your API key: https://aistudio.google.com/apikey');
+  console.log();
+
+  return new Promise((resolve) => {
+    rl.question('Enter your Gemini API key (or press Enter to skip): ', (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function configureGeminiKey(apiKey) {
+  try {
+    execSync(`gemini config set-key ${apiKey}`, { stdio: 'inherit' });
+    console.log('  ✓ Gemini API key configured successfully');
+    return true;
+  } catch (error) {
+    console.log('  ✗ Failed to configure Gemini API key');
+    console.log('  Please run manually: gemini config set-key YOUR_API_KEY');
+    return false;
+  }
+}
+
+async function setupGeminiCLI() {
+  const hasGemini = checkGeminiCLI();
+
+  if (hasGemini) {
+    console.log('  ✓ gemini-cli already installed');
+    return;
+  }
+
+  const shouldInstall = await promptInstallGemini();
+
+  if (!shouldInstall) {
+    console.log('\n  ℹ Skipped gemini-cli installation');
+    console.log('  • hapo:inspect will work in internal mode (default)');
+    console.log('  • To install later: npm install -g @google/generative-ai-cli');
+    return;
+  }
+
+  console.log('\n⚙ Installing gemini-cli...');
+  const installed = installGeminiCLI();
+
+  if (installed) {
+    const apiKey = await promptGeminiAPIKey();
+
+    if (apiKey) {
+      configureGeminiKey(apiKey);
+    } else {
+      console.log('\n📝 Skipped API key configuration');
+      console.log('  Configure later with: gemini config set-key YOUR_API_KEY');
+    }
+  } else {
+    console.log('\n📝 Manual installation steps:');
+    console.log('  1. npm install -g @google/generative-ai-cli');
+    console.log('  2. Get API key: https://aistudio.google.com/apikey');
+    console.log('  3. gemini config set-key YOUR_API_KEY');
+  }
+}
+
 // ═══════════════════════════════════════════════════════════
 // MAIN
 // ═══════════════════════════════════════════════════════════
@@ -850,6 +965,9 @@ async function main() {
       console.log();
     }
 
+    // Setup Gemini CLI for hapo:inspect ext mode
+    setupGeminiCLI();
+
     // Note: CLAUDE.md and docs/ are generated via /docs init command
 
     // Summary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Spec-Driven Development workflow for AI coding assistants. Supports Claude Code and Antigravity with spec-first workflows plus Claude Code hapo: skills.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/agents/code-reviewer.md

@@ -1,11 +1,11 @@
 ---
 name: code-reviewer
-description: "Comprehensive code review with scout-based edge case detection. Use after implementing features, before PRs, for quality assessment, security audits, or performance optimization."
+description: "Comprehensive code review with inspect-based edge case detection. Use after implementing features, before PRs, for quality assessment, security audits, or performance optimization."
 ---
 
 Senior software engineer specializing in code quality assessment. Expertise in TypeScript, JavaScript, Dart (Flutter), security, and performance.
 
-**IMPORTANT**: Ensure token efficiency. Use `scout` and `code-review` skills for protocols.
+**IMPORTANT**: Ensure token efficiency. Use `hapo:inspector` and `code-review` protocols for edge-case discovery before review.
 
 ## Core Responsibilities
 
@@ -18,36 +18,37 @@ Senior software engineer specializing in code quality assessment. Expertise in T
 
 ## Review Process
 
-### 1. Edge Case Scouting (NEW - Do First)
+### 1. Edge Case Inspection (NEW - Do First)
 
-Before reviewing, scout for edge cases the diff doesn't show:
+Before reviewing, inspect for edge cases the diff doesn't show:
 
 ```bash
 git diff --name-only HEAD~1  # Get changed files
 ```
 
-Use `/scout` with edge-case-focused prompt:
+Use `/hapo:inspector` with an edge-case-focused prompt:
 ```
-Scout edge cases for recent changes.
+Inspect edge cases for recent changes.
+Scope: {directories around changed files}
 Changed: {files}
 Find: affected dependents, data flow risks, boundary conditions, async races, state mutations
 ```
 
-Document scout findings for inclusion in review.
+Document inspect findings for inclusion in review.
 
 ### 2. Initial Analysis
 
 - Read `.specs/<feature>/tasks.md` and related changed files
 - Focus on recently changed files (use `git diff`)
 - For full codebase: use `repomix` to compact, then analyze
-- Wait for scout results before proceeding
+- Wait for inspect results before proceeding
 
 ### 3. Systematic Review
 
 | Area | Focus |
 |------|-------|
 | Structure | Organization, modularity |
-| Logic | Correctness, edge cases from scout |
+| Logic | Correctness, edge cases from inspect |
 | Types | Safety, error handling |
 | Performance | Bottlenecks, inefficiencies |
 | Security | Vulnerabilities, data exposure |
@@ -79,7 +80,7 @@ Mark reviewed task status and add next steps in workflow handoff.
 - Files: [list]
 - LOC: [count]
 - Focus: [recent/specific/full]
-- Scout findings: [edge cases discovered]
+- Inspect findings: [edge cases discovered]
 
 ### Overall Assessment
 [Brief quality overview]
@@ -96,8 +97,8 @@ Mark reviewed task status and add next steps in workflow handoff.
 ### Low Priority
 [Style, minor opts]
 
-### Edge Cases Found by Scout
-[List issues from scouting phase]
+### Edge Cases Found by Inspect
+[List issues from inspection phase]
 
 ### Positive Observations
 [Good practices noted]
@@ -122,7 +123,7 @@ Mark reviewed task status and add next steps in workflow handoff.
 - No AI attribution in code/commits
 - Security best practices priority
 - **Verify spec task checklist completion**
-- **Scout edge cases BEFORE reviewing**
+- **Inspect edge cases BEFORE reviewing**
 
 ## Report Output
 

package/src/claude/agents/debugger.md

@@ -41,7 +41,7 @@ When investigating issues, you will:
    - **When you need to understand the project structure:** 
      - Read `docs/codebase-summary.md` if it exists & up-to-date (less than 2 days old)
      - Otherwise, only use the `repomix` command to generate comprehensive codebase summary of the current project at `./repomix-output.xml` and create/update a codebase summary file at `./codebase-summary.md`
-     - **IMPORTANT**: ONLY process this following step `codebase-summary.md` doesn't contain what you need: use `/scout:ext` (preferred) or `/scout` (fallback) slash command to search the codebase for files needed to complete the task
+     - **IMPORTANT**: ONLY process this following step `codebase-summary.md` doesn't contain what you need: use `/hapo:inspector ext` for scoped Gemini discovery or `/hapo:inspector` for scoped internal discovery to inspect only the relevant codebase scopes and find the files needed to complete the task
    - When you are given a Github repository URL, use `repomix --remote <github-repo-url>` bash command to generate a fresh codebase summary:
       ```bash
       # usage: repomix --remote <github-repo-url>

package/src/claude/commands/review/codebase/parallel.md

@@ -13,7 +13,7 @@ argument-hint: [scope-or-prompt]
 
 Main agent deeply analyzes the scope to LIST all potential edge cases FIRST:
 - Read `codebase-summary.md` for context
-- Use `/scout:ext` to find relevant files
+- Use `/hapo:inspector ext` for scoped Gemini discovery; if external mode is unavailable or not appropriate, fall back to `/hapo:inspector` for scoped internal discovery
 - **Think exhaustively** about what could go wrong:
   - Null/undefined scenarios
   - Boundary conditions (off-by-one, empty, max values)

package/src/claude/commands/review/codebase.md

@@ -24,7 +24,7 @@ Think harder to scan the codebase and analyze it follow the Orchestration Protoc
 
 * Use 2 `researcher` subagents in parallel to search up to max 5 sources for the user's request, idea validation, best practices, challenges, and find the best possible solutions.
 * Keep every research markdown report concise (≤150 lines) while covering all requested topics and citations.
-* Use `/scout:ext` (preferred) or `/scout` (fallback) slash command to search the codebase for files needed to complete the task
+* Use `/hapo:inspector ext` for scoped Gemini discovery or `/hapo:inspector` for scoped internal discovery to search the codebase for files needed to complete the task
 
 ### Code Review
 
@@ -34,7 +34,7 @@ Think harder to scan the codebase and analyze it follow the Orchestration Protoc
 * **IMPORTANT:** Sacrifice grammar for the sake of concision when writing outputs.
 
 ### Plan
-* Use `planner` subagent to analyze reports from `researcher` and `scout` subagents to create an improvement plan following the progressive disclosure structure:
+* Use `planner` subagent to analyze reports from `researcher` and `hapo:inspector` discovery runs to create an improvement plan following the progressive disclosure structure:
   - Create a directory using naming pattern from `## Naming` section.
   - Save the overview access point at `plan.md`, keep it generic, under 80 lines, and list each phase with status/progress and links.
   - For each phase, add `phase-XX-phase-name.md` files containing sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).

package/src/claude/migration-manifest.json

@@ -21,6 +21,7 @@
     "required": [
       "specs",
       "impact-analysis",
+      "inspector",
       "spec-init",
       "spec-requirements",
       "spec-design",
@@ -46,6 +47,7 @@
   },
   "runtime": {
     "files": [
+      "runtime.json",
       "status.cjs",
       "hooks/session.cjs",
       "hooks/agent.cjs",

package/src/claude/runtime.json

@@ -0,0 +1,5 @@
+{
+  "gemini": {
+    "model": "gemini-3-flash-preview"
+  }
+}

package/src/common/skills/impact-analysis/SKILL.md

@@ -59,7 +59,7 @@ Load `references/change-detection.md` to:
 - Classify changes (backend/frontend/database)
 - Assess risk level
 
-### 2. Scout Dependencies
+### 2. Inspect Dependencies
 
 Load `references/dependency-scouting.md` to:
 - Find files that import/use modified code

package/src/common/skills/impact-analysis/references/dependency-scouting.md

@@ -1,8 +1,8 @@
-# Dependency Scouting - Finding Affected Files
+# Dependency Inspection - Finding Affected Files
 
 Methods for finding and analyzing dependencies to determine impact scope.
 
-## Scouting Strategies
+## Inspection Strategies
 
 ### 1. Import Analysis (Direct Dependencies)
 
@@ -132,12 +132,17 @@ grep -r "as User" src/
 # src/components/UserCard.tsx:  props: { user: User }
 ```
 
-## Using /ck:scout for Parallel Scouting
+## Using /hapo:inspector for Dependency Inspection
 
-When multiple files change, use `/ck:scout` for parallel search:
+When multiple files change, use `/hapo:inspector` for scoped discovery first:
 
 ```
-/ck:scout Scout dependencies for changes.
+/hapo:inspector Inspect dependencies for these changes.
+
+Scope:
+- src/api/
+- src/utils/
+- prisma/
 
 Changed files:
 - src/api/auth.ts (authentication logic)
@@ -152,11 +157,7 @@ Find:
 5. Frontend components calling changed APIs
 6. Test files covering changed code
 
-Focus on:
-- Direct imports (import/require statements)
-- Function calls (grep for function names)
-- Type usage (TypeScript interfaces)
-- Integration points (API calls, DB queries)
+Keep scope narrow. Do not scan repo root.
 ```
 
 ## Dependency Graph
@@ -236,15 +237,15 @@ grep -r "useContext.*{Context}" src/
 grep -r "use{Store}" src/
 ```
 
-## Automated Scouting Script
+## Automated Inspection Script
 
 ```bash
 #!/bin/bash
-# scout-dependencies.sh
+# inspect-dependencies.sh
 
 CHANGED_FILE=$1
 
-echo "=== Scouting Dependencies for: $CHANGED_FILE ==="
+echo "=== Dependency inspection for: $CHANGED_FILE ==="
 echo ""
 
 # Extract module name
@@ -325,13 +326,13 @@ done
 ## Best Practices
 
 1. **Start with direct imports** - Easiest to find
-2. **Use parallel scouting** - For multiple files
+2. **Use parallel inspection** - For multiple files
 3. **Check integration points** - APIs, events, state
 4. **Verify test coverage** - Find test files
 5. **Document findings** - For test scenario generation
 
 ## Next Steps
 
-After scouting, proceed to:
+After inspection, proceed to:
 1. **Edge Case Identification** - Analyze risks in affected files
 2. **Test Scenario Generation** - Create tests for affected components

package/src/common/skills/inspector/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: hapo:inspector
+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."
+version: 2.0.0
+argument-hint: "[search-target] [ext]"
+---
+
+# Inspector
+
+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. Reject repo-root or root-wide scans such as `.`, `/`, `./`, `**/*`, `**/*.ts`, or similar broad patterns without a scoped directory.
+2. Require at least one concrete scope root such as `src/auth/`, `packages/spec/src/claude/`, or `tests/`.
+3. Prefer file-type or glob hints whenever possible.
+4. Apply the built-in no-scan lists below.
+5. If the request is still too broad, stop and return 2-4 narrower suggestions.
+
+## 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`:
+```json
+{
+  "gemini": {
+    "model": "gemini-3-flash-preview"
+  }
+}
+```
+
+Default model: `gemini-3-flash-preview`
+
+**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 inspector 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
+
+```markdown
+# Inspector 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:inspector` 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

package/src/common/skills/inspector/references/external-gemini-inspection.md

@@ -0,0 +1,169 @@
+# External Discovery with Gemini
+
+Use external Gemini CLI for faster searches with large context windows (1M+ tokens) when SCALE ≤ 5.
+
+## Tool Selection
+
+```
+SCALE ≤ 5   → gemini CLI
+SCALE ≥ 6   → Use internal discovery instead
+```
+
+## Configuration
+
+Read from `.claude/runtime.json`:
+```json
+{
+  "gemini": {
+    "model": "gemini-3-flash-preview"
+  }
+}
+```
+
+Default model: `gemini-3-flash-preview`
+
+**Note:** This file is automatically installed when you run `npx @haposoft/cafekit`.
+
+## When External Mode is Allowed
+
+External Gemini inspection requires:
+
+**Gemini-Specific Requirements:**
+1. The prompt explicitly includes `ext` argument
+2. SCALE ≤ 5 (calculated from estimated file count)
+
+**General Preflight Gate (applies to all modes):**
+3. At least one concrete directory scope is present
+4. The request is not a repo-root or root-wide scan
+5. The built-in no-scan guidance has been applied
+
+If any condition fails, use internal discovery instead.
+
+## Gemini CLI
+
+### Command
+```bash
+gemini -y -m <model> "[prompt]"
+```
+
+### Example
+```bash
+gemini -y -m gemini-3-flash-preview "Search src/ for authentication files. List paths with brief descriptions."
+```
+
+## Installation Check
+
+Before using, verify Gemini CLI is installed:
+```bash
+which gemini
+```
+
+If not installed, ask user:
+1. **Yes** - Provide installation instructions (may need manual auth steps)
+2. **No** - Fall back to internal discovery (`internal-inspection.md`)
+
+## Spawning Parallel Bash Agents
+
+Use `Agent` tool with `subagent_type: "Bash"` to spawn parallel agents:
+
+```
+Agent 1: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3-flash-preview '[prompt1]'"
+Agent 2: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3-flash-preview '[prompt2]'"
+Agent 3: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3-flash-preview '[prompt3]'"
+```
+
+Spawn all in single message for parallel execution.
+
+## Prompt Guidelines
+
+- Be specific about directories to search
+- Request file paths with descriptions
+- Set clear scope boundaries
+- Ask for patterns/relationships if relevant
+- Do not include no-scan paths
+- Do not request secret material or generated bundles
+
+## Prompt Template
+
+```text
+Inspect these scoped directories only:
+- {dir-1}
+- {dir-2}
+
+Goal:
+- {what to find}
+
+Return:
+1. relevant file paths
+2. one-line description per file
+3. notable patterns or relationships
+4. unresolved questions
+
+Do not inspect repo root, generated directories, or sensitive content.
+Do not expand beyond the provided scope.
+```
+
+## Example Workflow
+
+User: "Find database migration files" with `ext`
+
+Spawn 3 parallel Bash agents via Agent tool:
+```
+Agent 1 (Bash): "Run: gemini -y -m gemini-3-flash-preview 'Search db/, migrations/ for migration files'"
+Agent 2 (Bash): "Run: gemini -y -m gemini-3-flash-preview 'Search lib/, src/ for database schema files'"
+Agent 3 (Bash): "Run: gemini -y -m gemini-3-flash-preview 'Search config/ for database configuration'"
+```
+
+## 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
+Use Read tool to check file size before reading.
+
+### 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: Read Strategy
+
+**Small files (<500 lines each):**
+- Read entire file with Read tool
+
+**Large file (>500 lines):**
+- Use Read tool with offset/limit parameters
+- Read in 500-line chunks
+
+### 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
+```
+
+## Timeout and Error Handling
+
+- Set 3-minute timeout per bash call
+- Skip timed-out agents
+- Don't restart failed agents
+- On persistent failures, fall back to internal discovery
+
+## Fallback Behavior
+
+If Gemini is unavailable, misconfigured, or errors out:
+1. Stop external mode
+2. Continue with internal discovery
+3. Note the fallback in the final report
+
+## Expected Outcome
+
+- Scoped Gemini discovery
+- Concise file list with descriptions
+- Patterns and relationships
+- Fallback to internal mode if Gemini cannot run

package/src/common/skills/inspector/references/internal-inspection.md

@@ -0,0 +1,173 @@
+# Internal Discovery with Explore Subagents
+
+Use Explore subagents when SCALE >= 6 or external tools unavailable.
+
+## How It Works
+
+Spawn multiple `Explore` subagents via `Agent` tool to search codebase in parallel.
+
+## Agent Tool Configuration
+
+```
+subagent_type: "Explore"
+```
+
+## Prompt Template
+
+```
+Quickly search {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
+- `types/` - Type definitions
+
+### Parallel Execution
+- Spawn all agents in single `Agent` tool call
+- Each agent gets distinct directory scope
+- No overlap between agents
+
+## Example
+
+User prompt: "Find authentication-related files"
+
+```
+Agent 1: Inspect src/auth/, src/middleware/ for auth files
+Agent 2: Inspect src/api/, src/routes/ for auth endpoints
+Agent 3: Inspect tests/ for auth tests
+Agent 4: Inspect lib/, utils/ for auth utilities
+Agent 5: Inspect config/ for auth configuration
+Agent 6: Inspect types/, interfaces/ for auth types
+```
+
+## Task Registration (Optional)
+
+### When to Register Tasks
+
+| Agents | Create Tasks? | Rationale |
+|--------|--------------|-----------|
+| ≤ 2    | No           | Overhead exceeds benefit, finishes quickly |
+| ≥ 3    | Yes          | Meaningful coordination, progress monitoring |
+
+### Task Registration Flow
+
+```
+TaskList()                          // Check for existing inspector tasks
+  → Found tasks?  → Skip creation, reuse existing
+  → Empty?        → TaskCreate per agent
+```
+
+### Task Metadata Pattern
+
+```
+TaskCreate(
+  subject: "Inspect {directory} for {target}",
+  activeForm: "Searching {directory}",
+  description: "Search {directories} for {patterns}",
+  metadata: {
+    agentType: "Explore",
+    scope: "src/auth/,src/middleware/",
+    scale: 6,
+    agentIndex: 1,
+    totalAgents: 6,
+    toolMode: "internal",
+    priority: "P2",
+    effort: "3m"
+  }
+)
+```
+
+### Task Lifecycle
+
+```
+Step 3: TaskCreate per agent     → status: pending
+Step 4: Before spawning agent    → TaskUpdate → status: in_progress
+Step 5: Agent returns report     → TaskUpdate → status: completed
+Step 5: Agent times out (3m)     → Keep in_progress, add error metadata
+```
+
+## Timeout Handling
+
+- Set 3-minute timeout per agent
+- Skip non-responding agents
+- Don't restart timed-out agents
+- Aggregate available results
+- Log timeouts in final report's "Unresolved Questions" section
+
+## 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
+Use Read tool with limit/offset or check file size before reading.
+
+### 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: Read Strategy
+
+**Small files (<500 lines each):**
+- Read entire file with Read tool
+
+**Large file (>500 lines):**
+- Use Read tool with offset/limit parameters
+- Read in 500-line chunks
+
+### 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
+```
+
+## Result Aggregation
+
+Combine results from all agents:
+1. Deduplicate file paths
+2. Merge descriptions
+3. Note any gaps/timeouts
+4. List unresolved questions
+
+## Scope Discipline
+
+- Start from concrete directories, not repo root
+- Prefer scope like `packages/spec/src/common/skills/**/*.md` over `**/*.md`
+- Skip `NO_SCAN_PATHS` from SKILL.md
+- Avoid content matching `NO_SCAN_CONTENT_HINTS`
+- If request still broad, stop and narrow before continuing
+
+## Output Contract
+
+Return:
+- file paths
+- brief description per file
+- notable relationships or repeated patterns
+- unresolved questions