@haposoft/cafekit 0.14.1 → 0.15.0

package/src/claude/scripts/generate-skill-catalog.cjs

@@ -37,9 +37,14 @@ function parseArgs(argv) {
 }
 
 function defaultSkillsRoot() {
-  const installed = path.resolve(process.cwd(), '.claude', 'skills');
-  if (fs.existsSync(installed)) return installed;
-  return path.resolve(__dirname, '..', 'skills');
+  const candidates = [
+    path.resolve(process.cwd(), '.claude', 'skills'),
+    path.resolve(process.cwd(), '.agents', 'skills'),
+    path.resolve(process.cwd(), '.opencode', 'skills'),
+    path.resolve(__dirname, '..', 'skills'),
+    path.resolve(__dirname, '..', '..', '.agents', 'skills')
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];
 }
 
 function readText(filePath) {

package/src/claude/scripts/validate-spec-output.cjs

@@ -113,6 +113,7 @@ function validateTaskSections(taskPath, content, errors) {
     hasHeading(content, 'Requirements') || /_Requirements:\s*[^_\n]+_/i.test(content);
   const hasRelatedFiles = hasHeading(content, 'Related Files');
   const hasCompletionCriteria = hasHeading(content, 'Completion Criteria');
+  // legacy heading aliases: read-compat only, no longer advertised
   const hasEvidence =
     hasHeading(content, 'Evidence') ||
     hasHeading(content, 'Task Test Plan & Verification Evidence') ||
@@ -365,6 +366,11 @@ function validateSpec(specDir) {
   const contractDefs = fs.existsSync(designPath)
     ? extractContractDefs(fs.readFileSync(designPath, 'utf8'))
     : new Map();
+  if (taskFiles.length >= 5 && contractDefs.size === 0) {
+    warnings.push(
+      'design.md declares no contract blocks; specs spanning BE/FE must declare shared shapes (<!-- contract:NAME -->)',
+    );
+  }
   for (const taskFile of taskFiles) {
     const fullPath = path.join(specDir, taskFile);
     const content = fs.readFileSync(fullPath, 'utf8');

package/src/claude/skills/code-review/references/spec-compliance-review.md

@@ -24,7 +24,7 @@ Do not attempt a standard text-based review if the project includes Visual Specs
 3. If NO (Markdown Spec only): Read the spec directly and extract:
    - requirement bullets
    - task `Completion Criteria`
-   - task `Evidence` (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`)
+   - task `## Evidence` (legacy heading aliases still parse)
    - canonical contracts/invariants from `design.md`
    Then verify the changed files against those concrete obligations.
 

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