@wazir-dev/cli 1.1.0 → 1.2.0

package/skills/gemini-cli/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: wz:gemini-cli
+description: How to use Gemini CLI programmatically for headless reviews, automation, and sandbox operations within Wazir pipelines.
+---
+
+# Gemini CLI Integration
+
+## Command Routing
+Follow the Canonical Command Matrix in `hooks/routing-matrix.json`.
+- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
+- Small commands (git status, ls, pwd, wazir CLI) → native Bash
+- If context-mode unavailable, fall back to native Bash with warning
+
+## Codebase Exploration
+1. Query `wazir index search-symbols <query>` first
+2. Use `wazir recall file <path> --tier L1` for targeted reads
+3. Fall back to direct file reads ONLY for files identified by index queries
+4. Maximum 10 direct file reads without a justifying index query
+5. If no index exists: `wazir index build && wazir index summarize --tier all`
+
+Reference for using the Google Gemini CLI in Wazir pipelines. Gemini CLI is an open-source AI agent that uses a ReAct (reason and act) loop with built-in tools and MCP servers to complete tasks directly in your terminal.
+
+## Commands
+
+### gemini (interactive)
+
+Launch the interactive TUI for ad-hoc work.
+
+```bash
+gemini
+```
+
+### Headless Mode (non-interactive)
+
+Headless mode is the primary mode for Wazir automation. It is triggered when providing a prompt with the `-p` (or `--prompt`) flag, or when the CLI runs in a non-TTY environment.
+
+```bash
+# Basic headless prompt
+gemini -p "Explain the architecture of this project"
+
+# Pipe data from stdin
+git diff main | gemini -p "Review this diff for bugs and security issues"
+
+# Chain with other tools
+gemini -p "List all exported functions" | jq '.response'
+
+# Save output to file
+gemini -p "Summarize the test coverage" > summary.md
+```
+
+**Key flags:**
+
+| Flag | Description |
+|------|-------------|
+| `-p, --prompt <PROMPT>` | Run in headless mode; print response to stdout and exit |
+| `-m, --model <MODEL>` | Specify the model to use (alias or full name) |
+| `--output-format json` | Output a single structured JSON object with the complete result |
+| `--output-format stream-json` | Stream real-time JSONL events as they occur |
+| `-s, --sandbox` | Enable sandboxed execution for shell commands and file modifications |
+| `-y, --yolo` | Auto-approve all operations (enables sandbox by default) |
+| `--approval-mode <MODE>` | Set approval mode: `default`, `auto_edit`, `plan`, `yolo` |
+| `--checkpoint` | Enable checkpoint mode for long-running tasks |
+
+**Headless mode limitations:**
+- No follow-up questions or continued conversation
+- Cannot authorize tools (including WriteFile) or run shell commands unless `--yolo` is used
+- For tool-using automation, combine `-p` with `--yolo` or `--approval-mode auto_edit`
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/model` | Switch model (Pro, Flash, Auto, or Manual selection) |
+| `/yolo` | Toggle YOLO mode (auto-approve all tool calls) |
+| `/stats` | Show token usage and session statistics |
+| `/export` | Export conversation to Markdown or JSON |
+| `/help` | Display available commands |
+| `/settings` | Open settings editor |
+
+## Approval Modes
+
+| Mode | Description |
+|------|-------------|
+| `default` | Prompts for approval on every tool use |
+| `auto_edit` | Auto-approves file reads/writes, still prompts for shell commands |
+| `plan` | Read-only mode; no writes or commands executed |
+| `yolo` | Auto-approves everything; enables sandbox by default |
+
+**Enable YOLO mode:**
+- CLI flag: `--yolo` or `-y`
+- Interactive toggle: `Ctrl+Y`
+- Slash command: `/yolo`
+- Environment variable: `GEMINI_YOLO=1`
+
+**Granular command auto-approval:** Configure specific commands to run without prompts:
+```json
+{
+  "tools": {
+    "shell": {
+      "autoApprove": ["git ", "npm test", "ls "]
+    }
+  }
+}
+```
+
+## Sandbox Mode
+
+Sandboxing isolates shell commands and file modifications from your host system. Disabled by default except when using YOLO mode.
+
+**Enable sandbox:**
+- CLI flag: `--sandbox` or `-s`
+- Environment variable: `GEMINI_SANDBOX=1`
+- Automatic with `--yolo` or `--approval-mode=yolo`
+
+Sandbox uses a pre-built `gemini-cli-sandbox` Docker image for isolation.
+
+**Safety configuration:** Set `requireApprovals: true` in settings to disallow YOLO mode and "Always allow" options entirely.
+
+## Model Selection
+
+| Model | Best For | Notes |
+|-------|----------|-------|
+| `gemini-3-pro` | Complex reasoning, coding, multi-step tasks | Latest Pro model |
+| `gemini-3-flash` | Fast responses, lighter tasks | Lower latency |
+| `gemini-3.1-pro-preview` | Cutting-edge features | Rolling preview access |
+| `gemini-2.5-pro` | Legacy stable | Still available |
+| `gemini-2.5-flash` | Legacy fast | Still available |
+| `auto` | Recommended; CLI picks best model per task | Default with Google login |
+
+**Select via:**
+- CLI flag: `-m <model>` or `--model <model>`
+- Environment variable: `export GEMINI_MODEL="gemini-3-pro"`
+- Interactive: `/model` slash command
+- Config: `settings.json` model field
+
+**Note:** With a Google login (not API key), the CLI may auto-blend Pro and Flash models based on task complexity and system capacity.
+
+## Non-Interactive Usage
+
+### Piping data
+
+```bash
+# Pipe a diff for review
+git diff main | gemini -p "Review this diff for correctness and security"
+
+# Pipe file content
+cat src/auth.ts | gemini -p "Find potential bugs in this code"
+
+# Multi-file context
+cat src/types.ts src/auth.ts | gemini -p "Are these types used correctly in auth?"
+```
+
+### Structured output
+
+```bash
+# JSON output (single object)
+gemini -p "List all API endpoints" --output-format json | jq '.response'
+
+# Streaming JSONL (real-time events)
+gemini -p "Analyze codebase" --output-format stream-json
+```
+
+### Output in scripts
+
+```bash
+# Capture to variable
+RESULT=$(gemini -p "What does this function do?" --output-format json | jq -r '.response')
+
+# Save to file
+gemini -p "Generate a test plan" > test-plan.md
+```
+
+## MCP Server Integration
+
+Gemini CLI supports MCP servers for extended tool capabilities.
+
+**Configuration in `settings.json`:**
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "@my-org/mcp-server"],
+      "env": { "API_KEY": "..." }
+    }
+  }
+}
+```
+
+**Extensions:** Gemini CLI extensions package prompts, MCP servers, and custom commands into installable bundles via `gemini-extension.json`. Extensions use a secure tool-merge approach where exclusions are combined and inclusions are intersected (most restrictive policy wins).
+
+**Tool control:**
+- `includeTools` / `excludeTools` in extension or settings config
+- MCP tools appear alongside built-in tools once configured
+
+## Built-in Tools
+
+Gemini CLI includes these tools out of the box:
+- **Google Search grounding** (web search)
+- **File operations** (read, write, list)
+- **Shell commands** (subject to approval mode)
+- **Web fetching** (retrieve URL content)
+
+## Wazir Integration Patterns
+
+### Secondary Review (used by wz:reviewer)
+
+```bash
+GEMINI_MODEL=$(jq -r '.multi_tool.gemini.model // empty' .wazir/state/config.json 2>/dev/null)
+GEMINI_MODEL=${GEMINI_MODEL:-gemini-3-pro}
+
+# Review uncommitted changes
+git diff | gemini -m "$GEMINI_MODEL" -p \
+  "Review this diff against these acceptance criteria: <criteria>" \
+  2>&1 | tee .wazir/runs/latest/reviews/gemini-review.md
+
+# Review a spec or design artifact
+cat artifact.md | gemini -m "$GEMINI_MODEL" -p \
+  "Review this spec against these criteria: <criteria>" \
+  2>&1 | tee .wazir/runs/latest/reviews/gemini-review.md
+```
+
+### Automation with Tool Access
+
+When the review needs tool access (e.g., reading additional files for context):
+
+```bash
+gemini -m "$GEMINI_MODEL" --yolo -p \
+  "Review the changes in src/auth/ for security issues. Read related test files for context." \
+  2>&1 | tee .wazir/runs/latest/reviews/gemini-review.md
+```
+
+### Structured Review Output
+
+```bash
+gemini -m "$GEMINI_MODEL" -p \
+  "Review this code and return JSON with fields: findings (array), severity, summary" \
+  --output-format json | jq '.response' \
+  > .wazir/runs/latest/reviews/gemini-review.json
+```
+
+## Error Handling
+
+| Error | Handling |
+|-------|----------|
+| **Non-zero exit** (auth/quota/transport) | Log full stderr, mark pass as `gemini-unavailable`, use self-review only. Next pass re-attempts. |
+| **Timeout** | Wrap with `timeout 120 gemini -p ...`. Treat timeout as `gemini-unavailable`. |
+| **Model unavailable** | Fall back to `gemini-3-flash` if Pro model is overloaded. |
+| **Rate limiting** | Respect backoff. Free-tier users share capacity; API key users have dedicated quota. |
+| **Headless tool denial** | If a headless prompt needs tool access, re-run with `--yolo` or `--approval-mode auto_edit`. |
+
+## Configuration
+
+Gemini CLI reads configuration from:
+- `~/.gemini/settings.json` (global)
+- `.gemini/settings.json` in the project root (project-level)
+- Environment variables (`GEMINI_MODEL`, `GEMINI_SANDBOX`, `GEMINI_YOLO`, `GOOGLE_API_KEY`)
+- CLI flags (highest precedence)
+
+Key config fields: `model`, `approvalMode`, `sandbox`, `mcpServers`, `tools`, `requireApprovals`.

package/skills/humanize/SKILL.md

@@ -7,6 +7,19 @@ description: Use when reviewing or editing any text artifact (specs, plans, code
 
 Remove AI writing patterns from text artifacts using a 4-phase corrective pipeline. This skill operates on text that has already been generated. For rules that prevent AI patterns during generation, the composition engine loads expertise modules from `expertise/humanize/` into role context automatically.
 
+## Command Routing
+Follow the Canonical Command Matrix in `hooks/routing-matrix.json`.
+- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
+- Small commands (git status, ls, pwd, wazir CLI) → native Bash
+- If context-mode unavailable, fall back to native Bash with warning
+
+## Codebase Exploration
+1. Query `wazir index search-symbols <query>` first
+2. Use `wazir recall file <path> --tier L1` for targeted reads
+3. Fall back to direct file reads ONLY for files identified by index queries
+4. Maximum 10 direct file reads without a justifying index query
+5. If no index exists: `wazir index build && wazir index summarize --tier all`
+
 ## Phase 1: Scan
 
 Detect the domain and scan for AI patterns.

package/skills/init-pipeline/SKILL.md

@@ -1,208 +1,117 @@
 ---
 name: wz:init-pipeline
-description: Initialize the Wazir pipeline with interactive setup. Creates project directories, selects mode, and configures the pipeline.
+description: Initialize the Wazir pipeline — zero-config by default, auto-detects host and project stack. No mandatory questions.
 ---
 
 # Initialize Pipeline
 
-Set up the Wazir pipeline for this project.
+Set up the Wazir pipeline for this project. **Zero-config by default** — everything is auto-detected and sensibly defaulted. No questions unless the user explicitly asks for interactive mode.
 
-## Step 0: Check Wazir CLI
+## Command Routing
+Follow the Canonical Command Matrix in `hooks/routing-matrix.json`.
+- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
+- Small commands (git status, ls, pwd, wazir CLI) → native Bash
+- If context-mode unavailable, fall back to native Bash with warning
 
-Run `which wazir` to check if the CLI is installed.
+## Codebase Exploration
+1. Query `wazir index search-symbols <query>` first
+2. Use `wazir recall file <path> --tier L1` for targeted reads
+3. Fall back to direct file reads ONLY for files identified by index queries
+4. Maximum 10 direct file reads without a justifying index query
+5. If no index exists: `wazir index build && wazir index summarize --tier all`
+
+## Zero-Config Flow (Default)
+
+### Step 1: Check Wazir CLI
 
-**If installed** — run `wazir init` and let it handle the interactive setup (arrow-key selection). If the pipeline was already initialized, use `wazir init --force` to reinitialize. Once it completes, skip to Step 9 (Confirm).
+Run `which wazir` to check if the CLI is installed.
 
 **If not installed**, present:
 
-> **The Wazir CLI is not installed. It's required for event capture, validation, and indexing.**
->
-> **How would you like to install it?**
+> **The Wazir CLI is not installed. Install with:**
 >
 > 1. **npm** (Recommended) — `npm install -g @wazir-dev/cli`
 > 2. **Local link** — `npm link` from the Wazir project root
-> 3. **Skip** — Continue without the CLI (some features will be unavailable)
-
-Wait for the user to answer before continuing.
 
-If the user picks 1, run `npm install -g @wazir-dev/cli` and verify with `wazir --version`.
-If the user picks 2, run `npm link` from the project root and verify.
-If the user picks 3, warn that `wazir capture`, `wazir validate`, and `wazir index` commands will not work, then continue to the manual steps below.
+### Step 2: Auto-Initialize
 
-After installing, run `wazir init` and let it handle the rest. Skip to Step 9.
+Run `wazir init` (default: auto mode). This automatically:
 
----
-
-**The steps below are the manual fallback — only used when the CLI is not installed and the user chose to skip installation.**
-
-## Step 1: Create Project Directories
+1. **Creates directories:** `.wazir/input/`, `.wazir/state/`, `.wazir/runs/`
+2. **Detects host:** Claude Code / Codex / Gemini / Cursor from environment variables and file markers
+3. **Detects project stack:** Language, framework, and stack from package files
+4. **Detects context-mode MCP:** Checks for core tools (`execute`, `fetch_and_index`, `search`)
+5. **Writes config** with sensible defaults:
+   - `model_mode: "claude-only"` (override: `wazir config set model_mode multi-model`)
+   - `default_depth: "standard"` (override per-run: `/wazir deep ...`)
+   - `default_intent: "feature"` (inferred per-run from request text)
+   - `team_mode: "sequential"` (always)
+6. **Auto-exports** for the detected host
 
-```bash
-mkdir -p .wazir/input .wazir/state .wazir/runs
-```
+**No questions asked.** The pipeline is ready to use immediately.
 
-## Step 2: Choose Pipeline Mode
+### Step 3: Confirm
 
-Present this question:
-
-> **How should Wazir run in this project?**
+> **Wazir initialized.**
 >
-> 1. **Single model** (Recommended) — Everything runs in the current model. Single model, slash commands only.
-> 2. **Multi-model** — Still the current model, but routes tasks by complexity (Haiku for micro, Sonnet for standard, Opus for complex).
-> 3. **Multi-tool** — Current model + external tools for reviews.
-
-Wait for the user to answer before continuing.
-
-## Step 3: If Multi-Tool, Choose Tools
-
-Only ask this if the user selected option 3:
-
-> **Which external tools should Wazir use for reviews?**
+> Host: [detected host] | Stack: [detected language/framework]
 >
-> 1. **Codex** (Recommended) — Send reviews to OpenAI Codex
-> 2. **Gemini** — Send reviews to Google Gemini
-> 3. **Both** — Use Codex and Gemini as secondary reviewers
-
-Wait for the user to answer before continuing.
-
-## Step 3.5: Codex Model (conditional)
-
-Only ask this if Codex was selected in Step 3:
+> Next: `/wazir <what you want to build>`
 
-> **Which Codex model should Wazir use?**
->
-> 1. **gpt-5.3-codex-spark** (Recommended) — Fast, good for review loops and grounder work
-> 2. **gpt-5.4** — Slower, deeper analysis for complex reviews
->
-> *You can change this later in `.wazir/state/config.json` under `multi_tool.codex.model`.*
+---
 
-Wait for the user to answer before continuing.
+## Interactive Flow (Power Users)
 
-## Step 4: Default Depth
+Triggered by `wazir init --interactive`. For users who want manual control.
 
-> **What default depth should runs use?**
->
-> 1. **Quick** — Minimal research, single-pass review, fast execution. Good for small fixes and config changes.
-> 2. **Standard** (Recommended) — Balanced research, multi-pass hardening, full review. Good for most features.
-> 3. **Deep** — Extended research, thorough hardening, strict review thresholds. Good for complex or security-critical work.
->
-> *This sets the project default. Individual runs can override via inline modifiers (e.g. `/wazir quick ...`).*
+### Pipeline Mode
 
-Wait for the user to answer before continuing.
-
-## Step 5: Default Intent
-
-> **What kind of work does this project mostly involve?**
->
-> 1. **Feature** (Recommended) — New functionality or enhancement
-> 2. **Bugfix** — Fix broken behavior
-> 3. **Refactor** — Restructure without changing behavior
-> 4. **Docs** — Documentation only
-> 5. **Spike** — Research and exploration, no production code
+> **How should Wazir run in this project?**
 >
-> *This sets the project default. Individual runs can override via inline modifiers or when intent is obvious from the request.*
+> 1. **Single model** (Recommended) — slash commands only
+> 2. **Multi-model** — routes sub-tasks to cheapest capable model (Haiku/Sonnet/Opus)
+> 3. **Multi-tool** — current model + external tools for reviews
 
-Wait for the user to answer before continuing.
+**If multi-model selected:** The model router (`tooling/src/adapters/model-router.js`) assigns automatically:
+- **Haiku** for mechanical tasks (URL fetching, file ops, compression)
+- **Sonnet** for comprehension tasks (implementation, reviews, learning extraction)
+- **Opus** for judgment tasks (orchestration, design, spec hardening, final review)
 
-## Step 6: Agent Teams (conditional)
+Override via `model_overrides` in config.
 
-Only ask this if ALL of these are true:
-- The host is Claude Code (not Codex/Gemini/Cursor)
-- Default depth is `standard` or `deep`
-- Default intent is `feature` or `refactor` (not bugfix/docs/spike)
+### External Tools (if multi-tool)
 
-> **Would you like to use Agent Teams for parallel execution?**
->
-> 1. **No** (Recommended) — Tasks run sequentially. Predictable, lower cost.
-> 2. **Yes** — Spawns parallel teammates for independent tasks. Potentially faster and richer output.
+> **Which external tools for reviews?**
 >
-> *Agent Teams is experimental from Claude's side. Requires Opus model. Higher token consumption.*
-
-If the conditions above are NOT met, silently default to `team_mode: sequential`.
-
-If the user selects **Yes**, enable the Agent Teams experimental feature:
-
-```bash
-claude config set env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 1
-```
-
-Then inform the user they need to restart their Claude Code session for it to take effect.
-
-Wait for the user to answer before continuing.
-
-## Step 7: Write Config
+> 1. **Codex** (Recommended)
+> 2. **Gemini**
+> 3. **Both**
 
-Create/update `.wazir/state/config.json`:
-
-- Set `model_mode` to the selected mode (`claude-only`, `multi-model`, or `multi-tool`)
-- If `multi-tool`, set `multi_tool.tools` to the selected tools (e.g. `["codex"]`, `["gemini"]`, or `["codex", "gemini"]`)
-- Set `default_depth` to the selected depth (`quick`, `standard`, or `deep`)
-- Set `default_intent` to the selected intent (`feature`, `bugfix`, `refactor`, `docs`, or `spike`)
-- Set `team_mode` to the selected mode (`sequential` or `parallel`)
-- If `team_mode` is `parallel`, set `parallel_backend` to `claude_teams`
-- If Codex selected, set `multi_tool.codex.model` to the chosen model
-
-Example for claude-only with defaults:
-```json
-{
-  "model_mode": "claude-only",
-  "default_depth": "standard",
-  "default_intent": "feature",
-  "team_mode": "sequential",
-  "parallel_backend": "none"
-}
-```
-
-Example for multi-tool with teams enabled:
-```json
-{
-  "model_mode": "multi-tool",
-  "multi_tool": {
-    "tools": ["codex"],
-    "codex": {
-      "model": "gpt-5.3-codex-spark"
-    }
-  },
-  "default_depth": "deep",
-  "default_intent": "feature",
-  "team_mode": "parallel",
-  "parallel_backend": "claude_teams"
-}
-```
-
-## Step 8: Runtime-Specific Setup
-
-Based on `multi_tool.tools`:
-
-- If **codex** is selected: Create `AGENTS.md` in project root:
-  ```
-  # Wazir Pipeline
-
-  Agent protocols are at `~/.claude/agents/` (global).
-
-  ## Running the Pipeline
-  1. Clarifier: read and follow `~/.claude/agents/clarifier.md` — tasks are in `.wazir/input/`
-  2. Orchestrator: read and follow `~/.claude/agents/orchestrator.md` — start from task 1
-  3. Opus Reviewer: read and follow `~/.claude/agents/opus-reviewer.md` — run all phases
+If Codex selected:
+> **Codex model?**
+>
+> 1. **gpt-5.3-codex-spark** (Recommended) — Fast review loops
+> 2. **gpt-5.4** — Deeper analysis
 
-  ## Review Mode
-  This project uses Codex as a secondary reviewer. Review artifacts are in `.wazir/reviews/`.
-  ```
+---
 
-- If **gemini** is selected: Create `GEMINI.md` in project root with the same content adapted for Gemini.
+## Install Paths
 
-- If **both**: Create both files.
+| Path | Command | Who |
+|------|---------|-----|
+| Plugin marketplace | `/plugin install wazir` | Claude Code users |
+| npx (zero install) | `npx @wazir-dev/cli` | Any Node project |
+| Global install | `npm i -g @wazir-dev/cli` | Power users |
+| Clone + link | `git clone && npm link` | Contributors |
 
-## Step 9: Confirm
+## Deep When You Need It
 
-List all files created and show the selected mode. Then present:
+- `wazir config set <key> <value>` — override any default
+- `wazir doctor` — see what's configured
+- `wazir stats` — see what Wazir saved you
+- `wazir init --interactive` — full manual setup
 
-> **Pipeline initialized. You can now use:**
->
-> - `/wazir <your request>` — Run the full pipeline end-to-end
-> - `/clarifier` — Run Phase 0 + Phase 1 only (research, clarify, plan)
-> - `/executor` — Run Phase 2 only (autonomous execution)
-> - `/reviewer` — Run Phase 3 only (final review and scoring)
+**Principle:** Like git — `git init` is one command, `git config` is deep. Instant start, deep when you need it.
 
 ## Interaction Rules
 

package/skills/prepare-next/SKILL.md

@@ -5,16 +5,87 @@ description: Use after a run or execution slice completes to produce a clean nex
 
 # Prepare Next
 
-Create a next-run handoff that captures:
+## Model Annotation
+When multi-model mode is enabled:
+- **Haiku** for file operations (write-handoff, compress-archive)
+- **Sonnet** for learning extraction (extract-learnings)
 
-- current status
-- completed work
-- unresolved blockers
-- required approvals
-- explicitly accepted learnings only
+## Command Routing
+Follow the Canonical Command Matrix in `hooks/routing-matrix.json`.
+- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
+- Small commands (git status, ls, pwd, wazir CLI) → native Bash
+- If context-mode unavailable, fall back to native Bash with warning
 
-Rules:
+## Codebase Exploration
+1. Query `wazir index search-symbols <query>` first
+2. Use `wazir recall file <path> --tier L1` for targeted reads
+3. Fall back to direct file reads ONLY for files identified by index queries
+4. Maximum 10 direct file reads without a justifying index query
+5. If no index exists: `wazir index build && wazir index summarize --tier all`
 
-- do not mutate `input/`
-- do not auto-load proposed or unreviewed learnings into the next run
-- write the handoff using the `templates/artifacts/next-run-handoff.md` structure
+Create a next-run handoff that captures the run outcome and sets up the next session.
+
+## When to Run
+
+One of:
+
+1. **Full completion** — All 4 phases are done, review is accepted, learnings are proposed. Prepare the next feature's starting point.
+2. **Partial completion** — The session is ending before the pipeline finishes. Prepare a mid-pipeline handoff so the next session can resume.
+3. **Slice boundary** — The approved plan is being executed in multiple slices. Prepare the handoff between slices.
+
+## Step 1: Gather Run State
+
+Read from the current run directory:
+
+- `run-config.yaml` — run identity, intent, depth
+- `reviews/review.md` — final review verdict and score (if complete)
+- `reviews/` — all review pass logs
+- `artifacts/` — task completion evidence
+- `clarified/` — spec, design, plan artifacts
+- Git log since branch creation: `git log --oneline main..HEAD`
+
+## Step 2: Write Handoff
+
+Write to `.wazir/runs/<run-id>/handoff.md` using this structure:
+
+```markdown
+# Handoff — <run-id>
+
+**Status:** [Completed | Partial | Slice N of M]
+**Branch:** <branch-name>
+**Date:** YYYY-MM-DD
+
+## What Was Done
+[List of completed tasks with commit hashes]
+
+## Commits
+[git log --oneline of all commits in this run]
+
+## Test Results
+[Test count, pass/fail, validator status]
+
+## Review Score
+[Verdict, score, key findings if applicable]
+
+## What's Next
+[Pending items, deferred work, follow-up tasks]
+
+## Open Bugs
+[Any known issues discovered during this run]
+
+## Learnings From This Run
+[Key insights — what worked, what didn't]
+```
+
+## Step 3: Run Summary
+
+```bash
+wazir capture summary --run <run-id>
+```
+
+## Rules
+
+- Do NOT mutate `input/` — it belongs to the user
+- Do NOT auto-load proposed or unreviewed learnings into the next run
+- Do NOT carry forward stale context — each new run reads fresh state
+- Do NOT compress or delete files the user might need — only archive verbose intermediate logs

package/skills/receiving-code-review/SKILL.md

@@ -5,6 +5,19 @@ description: Use when receiving code review feedback, before implementing sugges
 
 # Code Review Reception
 
+## Command Routing
+Follow the Canonical Command Matrix in `hooks/routing-matrix.json`.
+- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
+- Small commands (git status, ls, pwd, wazir CLI) → native Bash
+- If context-mode unavailable, fall back to native Bash with warning
+
+## Codebase Exploration
+1. Query `wazir index search-symbols <query>` first
+2. Use `wazir recall file <path> --tier L1` for targeted reads
+3. Fall back to direct file reads ONLY for files identified by index queries
+4. Maximum 10 direct file reads without a justifying index query
+5. If no index exists: `wazir index build && wazir index summarize --tier all`
+
 ## Overview
 
 Code review requires technical evaluation, not emotional performance.