@haposoft/cafekit 0.14.0 → 0.14.2

package/src/claude/skills/delegate/references/grok-delegation.md

@@ -0,0 +1,84 @@
+# Delegating to Grok CLI (Grok Build)
+
+Verified against grok 0.2.101 (2026-07). Re-check `grok --help` if flags fail.
+
+## Preflight
+
+```bash
+which grok && grok --version
+grok models          # available model IDs
+```
+
+## Non-interactive dispatch
+
+Two forms:
+
+```bash
+# single-turn from a brief file (preferred for delegation)
+grok --prompt-file plans/<slug>-task.md \
+     --worktree=<slug> \
+     --check \
+     --permission-mode acceptEdits \
+     --allow "Bash(npm:*)" --allow "Bash(node:*)" \
+     --output-format plain
+
+# short single-turn prompt
+grok -p "<prompt>"
+```
+
+Run in a background shell and poll the output.
+
+### Key flags
+
+| Flag | Notes |
+|---|---|
+| `--prompt-file <path>` | single-turn prompt from file |
+| `-p, --single <prompt>` | single-turn inline prompt |
+| `--worktree=<name>` | built-in git worktree isolation (grok-managed; see pitfalls) |
+| `--check` | appends a self-verification loop (headless only) — use it |
+| `--permission-mode <mode>` | `default` \| `acceptEdits` \| `auto` \| `dontAsk` \| `bypassPermissions` \| `plan` |
+| `--allow "<RULE>"` / `--deny "<RULE>"` | permission rules, Claude Code syntax: `Bash(npm:*)`, `Write`, `Edit` |
+| `-m <model>` / `--reasoning-effort` | model + effort overrides |
+| `--max-turns <N>` | hard cap on agent turns |
+| `--json-schema '<schema>'` | structured final output |
+| `--output-format plain\|json\|streaming-json` | headless output format |
+| `--resume <SESSION_ID>` | continue a session (context preserved) |
+| `--best-of-n <N>` | run task N ways in parallel, pick best (headless) |
+
+## Permission model — the #1 pitfall
+
+`--permission-mode acceptEdits` **does not reliably unblock file writes in headless runs**; grok may report "Write tool blocked" and quietly degrade to a **design-only** response that reads like progress. It still exits 0.
+
+Mitigations:
+- Add explicit allow rules for write tools on the first dispatch: `--allow "Write" --allow "Edit" --allow "StrReplace"` alongside `--allow "Bash(npm:*)" --allow "Bash(node:*)"`.
+- After ~30s, grep the output for `blocked`/`chặn` — catch degradation early.
+- If the run finished design-only: **resume the same session** with widened allows and an explicit apply instruction; grok picks up its own design and implements without re-exploring:
+
+```bash
+grok --resume <SESSION_ID> --no-plan \
+     --permission-mode acceptEdits \
+     --allow "Write" --allow "Edit" --allow "StrReplace" \
+     --allow "Bash(npm:*)" --allow "Bash(node:*)" \
+     --check -p "Continue: apply the designed changes, run tests, report results."
+```
+
+Even with allows granted, shell may still be policy-restricted (runs finish with "npm test BLOCKED — shell not pre-approved"). That's fine: **you run the Evidence commands yourself during verification** — do not loosen to `bypassPermissions` just to make the agent self-verify.
+
+## Worktree pitfalls
+
+- `--worktree=<name>` worktrees are **grok-managed**: they may not appear in the target repo's `git worktree list` and `grok worktree list` may still say "No worktrees found". **Do not trust either listing** — after the run, check `git status` in the main repo to find where changes actually landed. In practice (0.2.101, resumed sessions) grok can write **directly into the main working tree** despite the flag.
+- Consequence: always take a stash-backup snapshot before dispatch (`git stash push -u -m "backup: ..." && git stash apply -q`), and treat the main tree as potentially modified.
+
+## Session management
+
+```bash
+grok sessions list                      # ids + summaries
+grok --resume <SESSION_ID> [flags] -p "..."   # continue with same context
+grok export <SESSION_ID>                # transcript as Markdown
+```
+
+## Quirks
+
+- Grok reads the target repo's `CLAUDE.md` and obeys it (including tone rules) — repo constraints apply automatically, but so do repo-wide bans; account for that in the brief.
+- `--check` produces a self-verification section in the final report — useful signal, **not** a substitute for your independent verification.
+- Exit code 0 means the CLI ran, not that the task succeeded. Judge by diff + your own Evidence runs.

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

@@ -5,7 +5,7 @@ user-invocable: true
 when_to_use: "Invoke to implement specs and tasks end-to-end after scope is clear."
 category: utilities
 keywords: [implementation, specs, build, orchestration]
-argument-hint: "[feature-name|specs-directory-path] [task-file] [--flash] [--no-notes]"
+argument-hint: "[feature-name|specs-directory-path] [task-file] [--flash] [--parallel [N]] [--no-notes]"
 metadata:
   author: haposoft
   version: "1.0.0"
@@ -48,6 +48,27 @@ Triggered by `/hapo:develop <feature>` or `/hapo:develop specs/<feature>`.
 - STOP the overall run on the first blocked task, unresolved gate failure, or missing proof.
 - In `--flash` mode, missing full test proof does not stop the loop; record `FLASH_UNVERIFIED` and continue to the next unblocked task.
 
+### 2b. Parallel Wave Mode (opt-in)
+Triggered by adding `--parallel [N]` to Full-Spec mode. Load `references/parallel-waves.md` and follow it exactly — it is the operating procedure (wave planning, dispatch, merge, cleanup).
+
+Contracts: WAVE_CONFIG
+
+<!-- contract:WAVE_CONFIG -->
+```jsonc
+// .claude/runtime.json — develop parallel toggle (missing key = allowed)
+"develop": {
+  "parallel": true   // false = --parallel refused, sequential run + notice
+}
+// Flag: /hapo:develop <feature> --parallel [N]   (N = wave cap, 1..5, default 3)
+```
+
+- Preconditions first: if `runtime.json` sets `develop.parallel: false`, refuse `--parallel`, name the key, and run the sequential loop. If the work context is not a git repository or worktree isolation is unavailable, state the reason and fall back sequential (see parallel-waves.md §1).
+- Waves are computed from `task_registry.dependencies` with the single-writer-per-file rule; wave cap = N (1..5, default 3).
+- Dispatch one `god-developer` per wave task — worktree isolation, background, self-contained prompt per `rules/orchestrator.md`, plus the mandatory lines in parallel-waves.md §3 (commit mandate; never edit `spec.json`/`tasks/*.md`; never touch files outside the task's `Related Files`).
+- Quality gate (Stage A+B, unchanged) runs inside each task's worktree BEFORE merge; merge = sequential `git cherry-pick` of agent commits with explicit worktree/branch cleanup (spike-verified — see parallel-waves.md §5); post-merge integration check gates the next wave.
+- The orchestrator is the single writer of spec state: registry/task-md/receipts update after each cherry-pick, exactly as in sequential mode.
+- Without `--parallel`, nothing in this section applies — the sequential Full-Spec loop below is unchanged.
+
 ### 3. Flash Mode
 Triggered by adding `--flash` to either specific-task or full-spec mode.
 
@@ -76,7 +97,7 @@ DO NOT write implementation code until an approved spec exists.
 
 <DEFINITION-OF-DONE>
 A task is NOT done because code compiles or a placeholder renders.
-A task is done only when the task file's Completion Criteria AND Evidence section are satisfied with real execution proof. Existing specs may use `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence`; treat those as the same contract.
+A task is done only when the task file's Completion Criteria AND `## Evidence` (legacy heading aliases still parse) are satisfied with real execution proof.
 `--flash` is the only exception: it records fast implementation closeout with `FLASH_UNVERIFIED`, not full Definition of Done.
 </DEFINITION-OF-DONE>
 
@@ -95,7 +116,7 @@ You MUST implement all scoped behavior for the active task, MUST NOT add out-of-
 | Thought (Excuse) | Reality (Rule) |
 |-------------------|----------------|
 | "No need to scout first" | Coding without knowing the architecture is blind. ALWAYS call the `inspector` agent to scan files. |
-| "Review process is too tedious, let me just finish it myself" | The system needs an audit trail through agents. ALWAYS delegate via `Task` tool. |
+| "Review process is too tedious, let me just finish it myself" | The system needs an audit trail through agents. ALWAYS delegate via the `Agent` tool. |
 
 ## Absolute Workflow
 
@@ -132,7 +153,7 @@ flowchart TD
   - Objective + Constraints
   - Related Files
   - Completion Criteria
-  - Evidence (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`)
+  - `## Evidence` (legacy heading aliases still parse)
   - Exact executable verification commands named in the task
   - Requirement IDs referenced by the task
   - Named technologies, frameworks, protocols, and data stores that the task/spec explicitly requires
@@ -192,7 +213,7 @@ The moment you finish coding, DO NOT proceed further. Switch to `references/qual
 If `--flash` is active, use **Step 4F: Flash Gate** instead of the full automatic review loop.
 
 - Passing Step 4 requires ALL of the following:
-  1. Automated verification passes, including preflight compile/typecheck/build health and every exact command named in the task's `Evidence` section (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`)
+  1. Automated verification passes, including preflight compile/typecheck/build health and every exact command named in the task's `## Evidence` (legacy heading aliases still parse)
   2. Spec compliance review passes: every scoped requirement and active task criterion is implemented, with no extras and no omissions
   3. Code quality review passes
   4. Task evidence passes (artifacts/runtime surfaces/reachability/negative-path checks from the task file are proven)

package/src/claude/skills/develop/references/parallel-waves.md

@@ -0,0 +1,112 @@
+# Parallel Waves — hapo:develop `--parallel` operating procedure
+
+Normative protocol for executing independent spec tasks concurrently. Loaded by
+`develop/SKILL.md` when Full-Spec mode runs with `--parallel [N]`. Verified against
+live worktree-subagent behavior (spec `develop-parallel-wave`,
+`reports/worktree-spike.md`, 2026-07-19).
+
+## 1. Preconditions (check before anything else)
+
+1. `.claude/runtime.json` → `develop.parallel` is not `false` (escape hatch; missing
+   key = allowed). If `false`: refuse `--parallel`, tell the user the hatch is active
+   and which key controls it, then run the standard sequential loop.
+2. The work context is a git repository and worktree isolation is available.
+   Otherwise: state the reason ("not a git repo" / "isolation unavailable") and run
+   the standard **sequential fallback**.
+3. `--parallel N`: **wave cap** = N clamped to 1..5; default 3. Never exceed 5 —
+   each subagent carries a ~200K context budget (orchestrator.md resource rule).
+
+## 2. Wave planning (normative)
+
+```
+ready(t) = t.status == "pending" AND every dep in task_registry[t].dependencies
+           has status == "done"
+candidates = ready tasks in task_registry order
+wave = first ≤cap candidates, EXCLUDING any task that shares a Create or Modify
+       path (exact normalized string match over its Related Files table) with an
+       earlier task already in the wave — the excluded task returns to the pool
+```
+
+**Single writer per file per wave** is absolute. `Read` rows never conflict.
+If the wave is empty but pending tasks remain, dependencies are unsatisfiable in
+parallel — finish them with the sequential loop and say so.
+
+### Worked example
+
+Registry: A (deps: –), B (deps: –), C (deps: A), D (deps: – but shares
+`src/api/users.ts` Modify with B). Cap 3.
+
+- Wave 1 = A, B (D excluded: path collision with B; C excluded: dep on A)
+- Wave 2 = C, D (A done unblocks C; B done releases D's path)
+
+## 3. Dispatch (one god-developer per wave task)
+
+Every dispatch uses worktree isolation + background execution and a
+self-contained prompt per `rules/orchestrator.md` (task file content, design and
+requirements excerpts, work-context/specs/docs paths, acceptance criteria) plus
+these mandatory lines:
+
+1. "You are in an isolated git worktree. Implement ONLY this task."
+2. "Do NOT edit `spec.json` or any `tasks/*.md` — the orchestrator owns spec state."
+3. "Do NOT touch files outside this task's `Related Files`."
+4. "When done, `git add` your changes and `git commit -m \"task(<id>): <title>\"` —
+   an uncommitted worktree cannot be merged."
+5. End with the standard `Status: DONE|CONCERNS|BLOCKED|NEEDS_INFO` block, plus
+   your worktree path, branch, and commit hash(es).
+
+The Agent result returns `worktreePath` and `worktreeBranch` — record both per task.
+
+## 4. Quality gate — inside the worktree, before merge
+
+Run the unchanged Stage A + Stage B gate (`references/quality-gate.md`) per task
+**with the task's worktree as working directory**. Gate evidence from that run
+feeds the task receipt. 3 failed rounds → COLLAPSE protocol for that task only;
+sibling tasks in the wave keep running.
+
+## 5. Merge protocol (spike-verified — do not improvise)
+
+⚠️ Spike finding: worktree branches are based on **`origin/<default-branch>`**
+(`worktree.baseRef: "fresh"` default), NOT the session HEAD. On repos whose origin
+default diverges, `git merge <agent-branch>` explodes into unrelated conflicts.
+
+Therefore, for each gate-passed task, **sequentially** (one at a time, registry order):
+
+```bash
+git cherry-pick <agent-commit>       # base-agnostic: applies only the agent's diff
+# conflict? → git cherry-pick --abort
+#   → task_registry[task].status = "blocked", blocker = one-line conflict summary
+#   → continue with the next passed task
+git worktree remove --force .claude/worktrees/agent-<id>   # NOT auto-cleaned —
+git branch -D worktree-agent-<id>                          # explicit cleanup, always
+```
+
+Cleanup runs for unchanged/failed worktrees too (spike: even a read-only run
+leaves its worktree and branch behind). Optionally set `worktree.baseRef: "head"`
+in settings; cherry-pick remains the recipe regardless.
+
+## 6. Post-merge integration check (per wave)
+
+After the wave's last cherry-pick: run the project build or the affected test
+subset (never the full suite mid-flight — that runs once at develop completion).
+Failure = fix before computing the next wave. This is the wave gate of
+`quality-gate.md`.
+
+## 7. State sync — orchestrator is the single writer
+
+Only the orchestrator writes `spec.json` and task markdown, after each task's
+cherry-pick: registry `status`/`completed_at`/`last_updated_at`, task-md `Status`,
+checkbox ticks, and a verification receipt citing the worktree gate evidence plus
+the post-merge check result. The Stop completion gate (`spec-gate.cjs`) applies
+unchanged — a receipt-less done blocks the turn. After syncing the wave, recompute
+§2 and continue until no pending tasks remain.
+
+## 8. Failure summary
+
+| Event | Action |
+|---|---|
+| Escape hatch on / not a git repo / no isolation | Sequential fallback + stated reason |
+| Same-wave path collision | Defer the later task to next wave (§2) |
+| Gate fails 3× for a task | COLLAPSE for that task; wave continues |
+| Cherry-pick conflict | Abort pick; task `blocked` + conflict blocker; wave continues |
+| Post-merge check fails | No next wave until fixed |
+| Empty wave, tasks pending | Sequential loop for the remainder + notice |

package/src/claude/skills/develop/references/quality-gate.md

@@ -12,7 +12,7 @@ Green tests are NOT enough. The gate requires four proofs:
 
 ## Automation Semantics
 
-- If the task names exact commands in `Evidence` (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`), those exact commands are mandatory and must run before any fallback repo defaults.
+- If the task names exact commands in `## Evidence` (legacy heading aliases still parse), those exact commands are mandatory and must run before any fallback repo defaults.
 - Preflight compile/typecheck/build health is mandatory. If compile/typecheck/build fails before tests are meaningful, the gate result is `PRECHECK_FAIL`, not `NO_TESTS`.
 - `NO_TESTS` is never an automatic PASS.
 - `NO_TESTS` is acceptable only when the task does **not** require a dedicated test suite command and every other required automated command/evidence item passes.
@@ -55,7 +55,7 @@ Variable: retry_count = 0
 
 Before START_LOOP:
   - Read the active task file(s)
-  - Extract Related Files, Completion Criteria, Evidence (or Task Test Plan & Verification Evidence / legacy Verification & Evidence)
+  - Extract Related Files, Completion Criteria, `## Evidence` (legacy heading aliases still parse)
   - Extract the exact executable verification commands in declaration order
   - Extract relevant design contracts/invariants for the touched area
   - Extract scope_lock, requirement IDs, runtime entrypoints/callers, and reachability proof obligations
@@ -129,3 +129,11 @@ Must log the Quality Gate result to the terminal for user visibility:
 - **Preflight Fail:** `[x] Step 4 Quality Gate: PRECHECK_FAIL → compile/typecheck/build failed before tests mattered`
 - **Fix Needed:** `[~] Step 4 Quality Gate: Tests/spec/evidence failed → returned to god-developer`
 - **Awaiting Rescue:** `[!] Step 4 Quality Gate: Failed 3 rounds! Awaiting user intervention...`
+
+## Working directory (parallel mode)
+
+When `hapo:develop` runs in Parallel Wave Mode (`references/parallel-waves.md`), every Stage A and Stage B command for a task executes **with that task's worktree as the working directory**. Gate evidence recorded from the worktree run feeds the task's verification receipt. Thresholds, retry counter, and the COLLAPSE protocol are identical to sequential mode. A COLLAPSE of one task does not cancel other in-flight tasks of the wave.
+
+## Post-merge integration check (per wave)
+
+After the orchestrator cherry-picks the last gate-passed task of a wave: run the project build **or** the affected test subset (never the full suite mid-flight — it runs once at develop completion). While this check fails, the next wave MUST NOT start.

package/src/claude/skills/hotfix/references/parallel-patterns.md

@@ -1,6 +1,6 @@
 # Parallel Patterns & Task Coordination
 
-How to effectively leverage multiple subagents and native Task tools during fix workflows.
+How to effectively leverage multiple subagents (the `Agent` tool) and native task tracking (`TaskCreate`/`TaskUpdate`) during fix workflows.
 
 ## When to Go Parallel
 

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