@haposoft/cafekit 0.14.1 → 0.14.2

package/src/claude/skills/inspect/SKILL.md

@@ -20,12 +20,9 @@ Fast, token-efficient codebase discovery using parallel agents to find files nee
 
 ## 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
+- Feature spanning multiple directories; user wants to find/locate/search files
+- Debugging that needs file relationships; project structure questions
+- Before multi-area changes, review, debug, or impact analysis
 
 ## Preflight Scope Gate (MANDATORY - All Modes)
 
@@ -34,87 +31,34 @@ Before scanning with ANY mode (internal or external):
 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.
+**When scope is too broad:** use a **2-phase approach** — lightweight Structure Scout first, then parallel agents on real sub-scopes.
 
 ### 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
+Spawn **one scout** to map top-level layout before dividing work:
+1. List immediate children of the scope root (dirs + key config; monorepo markers)
+2. Rough file count per discovered directory
+3. Return a division plan of 1–6 logical sub-scopes (path/glob, est. files, focus)
 
-> Wait for Scout to complete before proceeding to Phase 2.
+Wait for Scout before 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)
+1. Follow Scout's plan; merge scopes < 10 files; split scopes > 100 files
+2. Spawn parallel Explore agents (SCALE 3–6 recommended), one per sub-scope
+3. Aggregate into the Inspect Report; offer deeper follow-up on specific areas
 
-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
+**Fallback to AskUserQuestion:** if Scout is ambiguous (flat layout, < 3 areas), offer 2–4 concrete scopes from findings, then re-invoke with the chosen scope.
 
 ## Built-in No-Scan Guidance
 
 ### `NO_SCAN_PATHS`
-- `.git/`
-- `node_modules/`
-- `dist/`
-- `build/`
-- `.next/`
-- `coverage/`
-- `tmp/`
-- `temp/`
-- `vendor/`
-- `artifacts/`
-- `secrets/`
-- `private/`
+- `.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
+- private keys, token dumps, credential exports, `.env` secrets
+- generated bundles, binary blobs
 
 ## Configuration
 
@@ -127,69 +71,54 @@ Read from `.claude/runtime.json`:
 }
 ```
 
-Default model: `gemma-4-31b-it`
-
-**Note:** This file is automatically installed when you run `npx @haposoft/cafekit`.
+Default model: `gemma-4-31b-it` (installed with `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
+- Parse search targets; identify directories, patterns, file types
+- Determine SCALE of subagents
 
 **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
+- Min SCALE = 1; Max SCALE = 10
+- SCALE 1-2: focused (< 100 files)
+- SCALE 3-5: medium (suitable for external Gemini CLI)
+- SCALE 6-10: large (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
+- Split into logical segments; assign distinct directories/patterns; no overlap
 
 ### 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
+- **Skip if:** Agent count ≤ 2
+- `TaskList` first; if none, `TaskCreate` per agent with scope metadata
+- See `./references/internal-inspection.md` for patterns
 
 ### 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
+| Condition | Mode |
+|---|---|
+| No `ext` argument | Internal Explore agents |
+| `ext` + SCALE ≤ 5 | Gemini CLI (if available + scope gate passed) |
+| `ext` + SCALE ≥ 6 | Internal Explore agents |
+| Gemini unavailable/fails | Fallback to internal Explore |
 
-Load appropriate reference:
-- **Internal (Default):** `./references/internal-inspection.md` (Explore subagents)
-- **External:** `./references/external-gemini-inspection.md` (Gemini CLI)
+Load: **Internal** `./references/internal-inspection.md` or **External** `./references/external-gemini-inspection.md`.
 
 ### 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
+**Internal mode:** dispatch native Explore agents with breadth medium/very-thorough + the Scope Gate above. Details: `./references/internal-inspection.md`.
+
+- `TaskUpdate` each task to `in_progress` before spawn
+- Prompt each subagent with exact directories/files; each has < 200K context
+- Agent count follows resources + file volume; each returns a summary to the 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
+- Timeout: 3 minutes per agent (skip non-responders; log in report)
+- `TaskUpdate` completed tasks; aggregate; list unresolved questions at end
 
 ## Report Format
 

package/src/claude/skills/inspect/references/internal-inspection.md

@@ -1,10 +1,6 @@
 # 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.
+Dispatch native Explore agents with breadth medium/very-thorough + the Scope Gate in `SKILL.md`. Use when SCALE ≥ 6 or external tools are unavailable.
 
 ## Agent Tool Configuration
 
@@ -18,156 +14,41 @@ subagent_type: "Explore"
 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
+- Search for relevant files matching the task (Glob/Grep)
+- List files with brief descriptions; timeout 3 minutes; skip if timed out
 
 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
+Split by logical dirs (`src/`, `lib/`, `tests/`, `config/`, `api/`, `types/`). Spawn all in one call; distinct scopes; no overlap.
 
-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
-```
+**Example** (auth): A1 `src/auth/, middleware/`; A2 `api/, routes/`; A3 `tests/`; A4 `lib/, utils/`; A5 `config/`; A6 `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 inspect 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
+| Agents | Create Tasks? |
+|--------|--------------|
+| ≤ 2    | No (overhead) |
+| ≥ 3    | Yes |
 
-```
-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
+`TaskList` → reuse or `TaskCreate` per agent (`agentType: Explore`, scope, scale, agentIndex, totalAgents, toolMode: internal). Lifecycle: pending → in_progress before spawn → completed on return (timeout: keep in_progress + error metadata).
 
-**Small files (<500 lines each):**
-- Read entire file with Read tool
+## Timeout, Aggregation, Reading
 
-**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
+- 3 min/agent; skip non-responders; do not restart; dedupe paths; note gaps in Unresolved Questions
+- Stay under ~150K tokens; ~500 lines/chunk; max 3–5 small files or 1 large file chunked (`chunks = ceil(total_lines / 500)`); Read with offset/limit
 
 ## Scope Discipline
 
-- Start from concrete directories, not repo root
-- Prefer scope like `packages/spec/src/claude/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
+Start from concrete directories (not repo root); prefer scoped globs; skip `NO_SCAN_PATHS` / `NO_SCAN_CONTENT_HINTS` from SKILL.md; if still broad, narrow first.
 
 ## Output Contract
 
-Return:
-- file paths
-- brief description per file
-- notable relationships or repeated patterns
-- unresolved questions
+Return: file paths, brief description per file, notable relationships/patterns, unresolved questions.
+