cokit-cli 1.2.7 → 1.3.0

package/skills/project-management/references/reporting-patterns.md

@@ -0,0 +1,94 @@
+# Reporting Patterns
+
+## Report Types
+
+### 1. Session Status Report
+
+Quick summary of work done in current session.
+
+```markdown
+## Session Report: [Date]
+
+### Work Completed
+- [x] [Task/feature description]
+- [x] [Task/feature description]
+
+### In Progress
+- [ ] [Task description] — [% complete, blocker if any]
+
+### Tasks Created
+- [N] tasks hydrated from [plan]
+- [M] completed, [K] remaining
+
+### Next Session
+1. [Priority item]
+2. [Follow-up item]
+```
+
+### 2. Plan Completion Report
+
+Comprehensive summary when a plan reaches completion.
+
+```markdown
+## Plan Complete: [Plan Name]
+
+### Summary
+- **Duration:** [start] → [end]
+- **Phases:** [N] completed
+- **Files changed:** [count]
+- **Tests:** [pass/total]
+
+### Achievements
+- [Feature/capability delivered]
+
+### Known Limitations
+- [Any caveats or future work needed]
+
+### Documentation Updates
+- [Which docs were updated]
+```
+
+### 3. Progress Report (Multi-Plan)
+
+Overview across all active plans.
+
+```markdown
+## Project Progress: [Date]
+
+| Plan | Status | Progress | Priority | Next Action |
+|------|--------|----------|----------|-------------|
+| [name] | [status] | [%] | P[N] | [action] |
+
+### Highlights
+- [Key achievement or milestone]
+
+### Risks
+- [Risk] — [Mitigation]
+
+### Blockers
+- [Blocker] — [Resolution path]
+```
+
+## Report Naming
+
+Use pattern from `## Naming` section injected by hooks:
+`{reports-path}/pm-{date}-{time}-{slug}.md`
+
+Example: `plans/reports/pm-260205-2221-auth-progress.md`
+
+## Report Generation Workflow
+
+1. `TaskList()` → gather all task statuses
+2. Glob `./plans/*/plan.md` → scan active plans
+3. Read phase files → count checkboxes
+4. Compile metrics into report template
+5. Write to reports directory
+6. Highlight: achievements, blockers, risks, next steps
+
+## Concision Rules
+
+- Sacrifice grammar for brevity
+- Use tables over paragraphs where possible
+- List unresolved questions at end
+- Metrics > prose (use numbers, percentages)
+- Skip obvious context; focus on actionable insights

package/skills/project-management/references/task-operations.md

@@ -0,0 +1,87 @@
+# Task Operations Reference
+
+Copilot provides 4 native tools for session-scoped task management.
+
+**Tool Availability:** `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList` are **CLI-only** — disabled in VSCode extension (`isTTY` check). If these tools error, fall back to `TodoWrite` for progress tracking. Plan file sync-back works identically without Task tools.
+
+## TaskCreate
+
+Create structured tasks with metadata and dependencies.
+
+```
+TaskCreate(
+  subject: "Implement JWT auth middleware",
+  description: "Add JWT validation to API routes. Verify tokens, extract claims, attach to context.",
+  activeForm: "Implementing JWT auth middleware",
+  metadata: { feature: "auth", phase: 2, priority: "P1", effort: "2h",
+              planDir: "plans/260205-auth/", phaseFile: "phase-02-api.md" }
+)
+```
+
+**Parameters:**
+- `subject` (required): Imperative title, <60 chars ("Implement X", "Add Y", "Fix Z")
+- `description` (required): Detailed requirements + acceptance criteria
+- `activeForm` (optional): Present-continuous shown in spinner ("Implementing X")
+- `metadata` (optional): Arbitrary key-value pairs for tracking
+
+**Required metadata fields:** `phase`, `priority` (P1/P2/P3), `effort`, `planDir`, `phaseFile`
+**Optional metadata:** `step`, `critical`, `riskLevel`, `dependencies`, `feature`, `owner`
+
+## TaskUpdate
+
+Manage state transitions and dependency chains.
+
+```
+TaskUpdate(
+  taskId: "task-123",
+  status: "in_progress",
+  addBlockedBy: ["task-122"]
+)
+```
+
+**Status lifecycle:** `pending` → `in_progress` → `completed`
+
+**Dependency fields:**
+- `addBlockedBy`: "I cannot start until these tasks complete"
+- `addBlocks`: "These tasks cannot start until I complete"
+- `owner`: Assign to specific agent
+
+When a blocking task completes, dependent tasks auto-unblock.
+
+## TaskGet & TaskList
+
+- `TaskGet(taskId)` → Full task details including dependencies
+- `TaskList()` → All tasks with status, owner, blockedBy
+
+**Task is "available" when:** status=`pending`, no owner, blockedBy list empty.
+
+## Dependency Patterns
+
+```
+Phase 1 (no blockers)              ← start here
+Phase 2 (addBlockedBy: [P1-id])    ← auto-unblocked when P1 completes
+Phase 3 (addBlockedBy: [P2-id])
+Step 3.4 (addBlockedBy: [P2-id])   ← critical steps share phase dependency
+```
+
+## When to Use Tasks
+
+| Scenario | Tasks? | Why |
+|----------|--------|-----|
+| Multi-phase feature (3+) | Yes | Track progress, enable parallel |
+| Complex dependencies | Yes | Automatic unblocking |
+| Parallel agent work | Yes | Shared progress tracking |
+| Single-phase quick fix | No | Overhead exceeds benefit |
+| <3 related steps | No | Just do them directly |
+
+**3-Task Rule:** <3 tasks → skip creation, overhead not worth it.
+
+## Parallel Agent Coordination
+
+1. Create tasks with scoped ownership per agent
+2. Each agent works in designated directories only
+3. When Agent A completes a task → `TaskUpdate(status: "completed")`
+4. Tasks blocked by completed work auto-unblock
+5. Agent B (or A) claims newly available work
+
+**Key:** Assign `owner` field to prevent agents from claiming same task.

package/skills/repomix/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: repomix
 description: Pack repositories into AI-friendly files with Repomix (XML, Markdown, plain text). Use for codebase snapshots, LLM context preparation, security audits, third-party library analysis.
+argument-hint: "[path] [--style xml|markdown|plain|json]"
 ---
 
 # Repomix Skill
 
-Repomix packs entire repositories into single, AI-friendly files. Perfect for feeding codebases to LLMs like ChatGPT, Gemini, and others.
+Repomix packs entire repositories into single, AI-friendly files. Perfect for feeding codebases to LLMs like Copilot, ChatGPT, and Gemini.
 
 ## When to Use
 
@@ -153,7 +154,7 @@ repomix --init  # creates repomix.config.json
 Repomix automatically counts tokens for individual files, total repository, and per-format output.
 
 Typical LLM context limits:
-- Model (Medium): ~200K tokens
+- Copilot: ~200K tokens
 - GPT-4: ~128K tokens
 - GPT-3.5: ~16K tokens
 

package/skills/repomix/references/usage-patterns.md

@@ -144,9 +144,9 @@ repomix --include "$(cat staged-files.txt | tr '\n' ',')" -o .context/latest.xml
 {"version": "2.0.0", "tasks": [{"label": "Package for AI", "type": "shell", "command": "repomix --include 'src/**' --remove-comments --copy"}]}
 ```
 
-### AI Coding Agent
+### Copilot
 ```bash
-repomix --style markdown --copy  # Then paste into the AI agent
+repomix --style markdown --copy  # Then paste into Copilot chat
 ```
 
 ## Language-Specific Patterns

package/skills/repomix/scripts/README.md

@@ -88,7 +88,7 @@ Loads .env files in order of precedence:
 1. Process environment (highest priority)
 2. `./repomix/.env` (skill-specific)
 3. `./skills/.env` (skills directory)
-4. `$HOME/.copilot/.env` (lowest priority)
+4. `project .env` (lowest priority)
 
 ### Command Line Options
 

package/skills/repomix/scripts/repomix_batch.py

@@ -36,7 +36,7 @@ class EnvLoader:
         """
         Load environment variables from .env files in order of precedence.
 
-        Order: process.env > skill/.env > skills/.env > .copilot/.env
+        Order: process.env > skill/.env > skills/.env > project .env
 
         Returns:
             Dictionary of environment variables
@@ -46,7 +46,7 @@ class EnvLoader:
 
         # Define search paths in reverse order (lowest to highest priority)
         search_paths = [
-            script_dir.parent.parent.parent / ".env",  # .copilot/.env
+            script_dir.parent.parent.parent / ".env",  # project .env
             script_dir.parent.parent / ".env",          # skills/.env
             script_dir.parent / ".env",                 # skill/.env (repomix/.env)
         ]

package/skills/research/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: research
-description: Research technical solutions, analyze architectures, gather requirements thoroughly. Use for technology evaluation, best practices research, solution design, scalability/security/maintainability analysis.
+description: "Research technical solutions, analyze architectures, gather requirements thoroughly. Use for technology evaluation, best practices research, solution design, scalability/security/maintainability analysis."
+license: MIT
+argument-hint: "[topic]"
 ---
 
 # Research
@@ -23,8 +25,8 @@ First, you will clearly define the research scope by:
 You will employ a multi-source research strategy:
 
 1. **Search Strategy**:
-   - **Gemini Toggle**: Check `$HOME/.copilot/.ck.json` (or `~/.copilot/.ck.json`) for `skills.research.useGemini` (default: `true`). If `false`, skip Gemini and use WebSearch.
-   - **Gemini Model**: Read from `$HOME/.copilot/.ck.json`: `gemini.model` (default: `gemini-3-flash-preview`)
+   - **Gemini Toggle**: Check `.ck.json` (or `.ck.json`) for `skills.research.useGemini` (default: `true`). If `false`, skip Gemini and use WebSearch.
+   - **Gemini Model**: Read from `.ck.json`: `gemini.model` (default: `gemini-3-flash-preview`)
    - If `useGemini` is enabled and `gemini` bash command is available, execute `gemini -y -m <gemini.model> "...your search prompt..."` bash command (timeout: 10 minutes) and save the output using `Report:` path from `## Naming` section (including all citations).
    - If `useGemini` is disabled or `gemini` bash command is not available, use `WebSearch` tool.
    - Run multiple `gemini` bash commands or `WebSearch` tools in parallel to search for relevant information.
@@ -154,6 +156,7 @@ You will ensure all research meets these criteria:
 - Always note deprecation warnings and migration paths for older technologies
 
 ## Output Requirements
+**IMPORTANT:** Invoke "/ck-project-organization" skill to organize the outputs.
 
 Your final report must:
 1. Be saved using the `Report:` path from `## Naming` section with a descriptive filename
@@ -166,4 +169,4 @@ Your final report must:
 **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
 **IMPORTANT:** In reports, list any unresolved questions at the end, if any.
 
-**Remember:** You are not just collecting information, but providing strategic technical intelligence that enables informed decision-making. Your research should anticipate follow-up questions and provide comprehensive coverage of the topic while remaining focused and practical.
+**Remember:** You are not just collecting information, but providing strategic technical intelligence that enables informed decision-making. Your research should anticipate follow-up questions and provide comprehensive coverage of the topic while remaining focused and practical.

package/skills/scout/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: scout
-description: Fast codebase scouting using parallel agents. Use for file discovery, task context gathering, quick searches across directories. Supports internal and external search agents.
+description: "Fast codebase scouting using parallel agents. Use for file discovery, task context gathering, quick searches across directories. Supports internal (Explore) and external (Gemini/OpenCode) agents."
+argument-hint: "[search-target] [ext]"
 ---
 
 # Scout
@@ -8,7 +9,7 @@ description: Fast codebase scouting using parallel agents. Use for file discover
 Fast, token-efficient codebase scouting using parallel agents to find files needed for tasks.
 
 ## Arguments
-- Default: Scout using built-in search agents in parallel (`./references/internal-scouting.md`)
+- Default: Scout using built-in Explore subagents in parallel (`./references/internal-scouting.md`)
 - `ext`: Scout using external Gemini/OpenCode CLI tools in parallel (`./references/external-scouting.md`)
 
 ## When to Use
@@ -28,7 +29,7 @@ Fast, token-efficient codebase scouting using parallel agents to find files need
 
 ## Configuration
 
-Read from `$HOME/.copilot/.ck.json`:
+Read from `.ck.json`:
 - `gemini.model` - Gemini model (default: `gemini-3-flash-preview`)
 
 ## Workflow
@@ -36,7 +37,7 @@ Read from `$HOME/.copilot/.ck.json`:
 ### 1. Analyze Task
 - Parse user prompt for search targets
 - Identify key directories, patterns, file types, lines of code
-- Determine optimal SCALE value of agents to spawn
+- Determine optimal SCALE value of subagents to spawn
 
 ### 2. Divide and Conquer
 - Split codebase into logical segments per agent
@@ -44,32 +45,31 @@ Read from `$HOME/.copilot/.ck.json`:
 - Ensure no overlap, maximize coverage
 
 ### 3. Register Scout Tasks
-
-**Skip this step if agent count <= 2.**
-
-- Check for existing scout tasks in the current session to avoid duplicates.
-- Create a markdown checklist — one entry per agent — including scope metadata (directories, patterns assigned).
-- Example checklist entry: `- [ ] Agent 1: src/api/*, src/models/* — searching for auth-related files`
-- Reference: `references/task-management-scouting.md` for checklist format and metadata fields.
+- **Skip if:** Agent count ≤ 2 (overhead exceeds benefit)
+- **Skip if:** Task tools unavailable (VSCode extension) — use `TodoWrite` instead
+- `TaskList` first — check for existing scout tasks in session
+- If not found, `TaskCreate` per agent with scope metadata
+- See `references/task-management-scouting.md` for patterns and examples
 
 ### 4. Spawn Parallel Agents
-
 Load appropriate reference based on decision tree:
-- **Internal (Default):** `references/internal-scouting.md` (search agents)
+- **Internal (Default):** `references/internal-scouting.md` (Explore subagents)
 - **External:** `references/external-scouting.md` (Gemini/OpenCode)
 
 **Notes:**
-- Update each task to in_progress before spawning its agent.
-- Prompt detailed instructions for each agent with exact directories or files it should read.
-- Remember that each agent has less than 200K tokens of context window.
-- Amount of agents to-be-spawned depends on the current system resources available and amount of files to be scanned.
-- Each agent must return a detailed summary report to a main agent.
+- `TaskUpdate` each task to `in_progress` before spawning its agent (skip if Task tools unavailable)
+- 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
 
 ### 5. Collect Results
-- Timeout: 3 minutes per agent (skip non-responders).
-- Update completed tasks to done; log timed-out agents in the report under "Unresolved Questions".
-- Aggregate findings into single report.
-- List unresolved questions at end.
+**IMPORTANT:** Invoke "/ck-project-organization" skill to organize the outputs.
+
+- Timeout: 3 minutes per agent (skip non-responders)
+- `TaskUpdate` completed tasks; log timed-out agents in report (skip if Task tools unavailable)
+- Aggregate findings into single report
+- List unresolved questions at end
 
 ## Report Format
 
@@ -86,6 +86,6 @@ Load appropriate reference based on decision tree:
 
 ## References
 
-- `references/internal-scouting.md` - Using search agents
+- `references/internal-scouting.md` - Using Explore subagents
 - `references/external-scouting.md` - Using Gemini/OpenCode CLI
-- `references/task-management-scouting.md` - Checklist format and scope metadata for scout tasks
+- `references/task-management-scouting.md` - Task patterns for scout coordination

package/skills/scout/references/external-scouting.md

@@ -12,16 +12,16 @@ SCALE >= 6  → Use internal scouting instead
 
 ## Configuration
 
-Read from `$HOME/.copilot/.ck.json`:
+Read from `.ck.json`:
 ```json
 {
   "gemini": {
-    "model": "gemini-3.0-flash"
+    "model": "gemini-3-flash-preview"
   }
 }
 ```
 
-Default model: `gemini-3.0-flash`
+Default model: `gemini-3-flash-preview`
 
 ## Gemini CLI (SCALE <= 3)
 
@@ -32,7 +32,7 @@ gemini -y -m <model> "[prompt]"
 
 ### Example
 ```bash
-gemini -y -m gemini-3.0-flash "Search src/ for authentication files. List paths with brief descriptions."
+gemini -y -m gemini-3-flash-preview "Search src/ for authentication files. List paths with brief descriptions."
 ```
 
 ## OpenCode CLI (SCALE 4-5)
@@ -57,16 +57,16 @@ which opencode
 
 If not installed, ask user:
 1. **Yes** - Provide installation instructions (may need manual auth steps)
-2. **No** - Fall back to Explore agents (`internal-scouting.md`)
+2. **No** - Fall back to Explore subagents (`internal-scouting.md`)
 
 ## Spawning Parallel Bash Agents
 
-Use `Task` tool with `type: "Bash"` to spawn parallel agents:
+Use `Task` tool with `subagent_type: "Bash"` to spawn parallel agents:
 
 ```
-Task 1: type="Bash", prompt="Run: gemini -y -m gemini-3.0-flash '[prompt1]'"
-Task 2: type="Bash", prompt="Run: gemini -y -m gemini-3.0-flash '[prompt2]'"
-Task 3: type="Bash", prompt="Run: gemini -y -m gemini-3.0-flash '[prompt3]'"
+Task 1: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3-flash-preview '[prompt1]'"
+Task 2: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3-flash-preview '[prompt2]'"
+Task 3: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3-flash-preview '[prompt3]'"
 ```
 
 Spawn all in single message for parallel execution.
@@ -84,9 +84,9 @@ User: "Find database migration files"
 
 Spawn 3 parallel Bash agents via Task tool:
 ```
-Task 1 (Bash): "Run: gemini -y -m gemini-3.0-flash 'Search db/, migrations/ for migration files'"
-Task 2 (Bash): "Run: gemini -y -m gemini-3.0-flash 'Search lib/, src/ for database schema files'"
-Task 3 (Bash): "Run: gemini -y -m gemini-3.0-flash 'Search config/ for database configuration'"
+Task 1 (Bash): "Run: gemini -y -m gemini-3-flash-preview 'Search db/, migrations/ for migration files'"
+Task 2 (Bash): "Run: gemini -y -m gemini-3-flash-preview 'Search lib/, src/ for database schema files'"
+Task 3 (Bash): "Run: gemini -y -m gemini-3-flash-preview 'Search config/ for database configuration'"
 ```
 
 ## Reading File Content
@@ -112,15 +112,15 @@ lines_per_chunk = ceil(total_lines / chunks)
 
 **Small files (<500 lines each):**
 ```
-Task 1: type="Bash", prompt="cat file1.ts file2.ts"
-Task 2: type="Bash", prompt="cat file3.ts file4.ts"
+Task 1: subagent_type="Bash", prompt="cat file1.ts file2.ts"
+Task 2: subagent_type="Bash", prompt="cat file3.ts file4.ts"
 ```
 
 **Large file (>500 lines) - use sed for ranges:**
 ```
-Task 1: type="Bash", prompt="sed -n '1,500p' large-file.ts"
-Task 2: type="Bash", prompt="sed -n '501,1000p' large-file.ts"
-Task 3: type="Bash", prompt="sed -n '1001,1500p' large-file.ts"
+Task 1: subagent_type="Bash", prompt="sed -n '1,500p' large-file.ts"
+Task 2: subagent_type="Bash", prompt="sed -n '501,1000p' large-file.ts"
+Task 3: subagent_type="Bash", prompt="sed -n '1001,1500p' large-file.ts"
 ```
 
 ### Chunking Decision Tree

package/skills/scout/references/internal-scouting.md

@@ -1,15 +1,15 @@
-# Internal Scouting with Explore Agents
+# Internal Scouting with Explore Subagents
 
-Use Explore agents when SCALE >= 6 or external tools unavailable.
+Use Explore subagents when SCALE >= 6 or external tools unavailable.
 
 ## How It Works
 
-Spawn multiple `Explore` agents via `Task` tool to search codebase in parallel.
+Spawn multiple `Explore` subagents via `Task` tool to search codebase in parallel.
 
 ## Task Tool Configuration
 
 ```
-type: "Explore"
+subagent_type: "Explore"
 ```
 
 ## Prompt Template
@@ -90,15 +90,15 @@ lines_per_chunk = ceil(total_lines / chunks)
 
 **Small files (<500 lines each):**
 ```
-Task 1: type="Bash", prompt="cat file1.ts file2.ts"
-Task 2: type="Bash", prompt="cat file3.ts file4.ts"
+Task 1: subagent_type="Bash", prompt="cat file1.ts file2.ts"
+Task 2: subagent_type="Bash", prompt="cat file3.ts file4.ts"
 ```
 
 **Large file (>500 lines) - use sed for ranges:**
 ```
-Task 1: type="Bash", prompt="sed -n '1,500p' large-file.ts"
-Task 2: type="Bash", prompt="sed -n '501,1000p' large-file.ts"
-Task 3: type="Bash", prompt="sed -n '1001,1500p' large-file.ts"
+Task 1: subagent_type="Bash", prompt="sed -n '1,500p' large-file.ts"
+Task 2: subagent_type="Bash", prompt="sed -n '501,1000p' large-file.ts"
+Task 3: subagent_type="Bash", prompt="sed -n '1001,1500p' large-file.ts"
 ```
 
 ### Chunking Decision Tree

package/skills/scout/references/task-management-scouting.md

@@ -0,0 +1,125 @@
+# Scout Task Management Patterns
+
+Track parallel scout agent execution via Native Tasks (TaskCreate, TaskUpdate, TaskList).
+
+## When to Create 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 scout tasks
+  → Found tasks?  → Skip creation, reuse existing
+  → Empty?        → TaskCreate per agent (see schema below)
+```
+
+## Metadata Schema
+
+```
+TaskCreate(
+  subject: "Scout {directory} for {target}",
+  activeForm: "Scouting {directory}",
+  description: "Search {directories} for {patterns}",
+  metadata: {
+    agentType: "Explore",        // "Explore" (internal) or "Bash" (external)
+    scope: "src/auth/,src/middleware/",
+    scale: 6,
+    agentIndex: 1,               // 1-indexed position
+    totalAgents: 6,
+    toolMode: "internal",        // "internal" or "external"
+    priority: "P2",              // Always P2 for scout coordination
+    effort: "3m"                 // Fixed timeout per agent
+  }
+)
+```
+
+### Required Fields
+
+- `agentType` — Subagent type: `"Explore"` for internal, `"Bash"` for external
+- `scope` — Comma-separated directory boundaries for this agent
+- `scale` — Total SCALE value determined in Step 1
+- `agentIndex` / `totalAgents` — Position tracking (e.g., 3 of 6)
+- `toolMode` — `"internal"` or `"external"`
+- `priority` — Always `"P2"` (scout = coordination, not primary work)
+- `effort` — Always `"3m"` (fixed timeout)
+
+### Optional Fields
+
+- `searchPatterns` — Key patterns searched (aids debugging)
+- `externalTool` — If external: `"gemini"` or `"opencode"`
+
+## 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
+
+```
+TaskUpdate(taskId, {
+  metadata: { ...existing, error: "timeout" }
+})
+// Task stays in_progress — distinguishes timeout from incomplete
+// Log in final report's "Unresolved Questions" section
+```
+
+## Examples
+
+### Internal Scouting (SCALE=6)
+
+```
+// Step 3: Register 6 tasks
+TaskCreate(subject: "Scout src/auth/ for auth files",
+  activeForm: "Scouting src/auth/",
+  metadata: { agentType: "Explore", scope: "src/auth/", scale: 6,
+              agentIndex: 1, totalAgents: 6, toolMode: "internal",
+              priority: "P2", effort: "3m" })  // → taskId1
+
+// Repeat for agents 2-6 with different scopes
+
+// Step 4: Spawn agents
+TaskUpdate(taskId1, { status: "in_progress" })
+// ... spawn all Explore subagents in single Task tool call
+
+// Step 5: Collect
+TaskUpdate(taskId1, { status: "completed" })  // report received
+TaskUpdate(taskId3, { metadata: { error: "timeout" } })  // timed out
+```
+
+### External Scouting (SCALE=3, gemini)
+
+```
+TaskCreate(subject: "Scout db/ for migrations via gemini",
+  activeForm: "Scouting db/ via gemini",
+  metadata: { agentType: "Bash", scope: "db/,migrations/", scale: 3,
+              agentIndex: 1, totalAgents: 3, toolMode: "external",
+              externalTool: "gemini", priority: "P2", effort: "3m" })
+```
+
+## Integration with Cook/Planning
+
+Scout tasks are **independent** from cook/planning phase tasks — NOT parent-child.
+
+**Rationale:** Different lifecycle. Scout completes before cook continues. Mixing creates confusion in TaskList.
+
+**Sequence when cook spawns scout:**
+1. Cook Step 2 → spawns planner → planner spawns scout
+2. Scout registers its own tasks (Step 3), executes (Step 4-5)
+3. Scout returns aggregated report → planner continues
+4. Cook Step 3 hydrates phase tasks (separate from scout tasks)
+
+## Quality Check Output
+
+After registration: `✓ Registered [N] scout tasks ([internal|external] mode, SCALE={scale})`
+
+## Error Handling
+
+If `TaskCreate` fails: log warning, continue without task tracking. Scout remains fully functional — tasks add observability, not functionality.