@wazir-dev/cli 1.1.0 → 1.3.0

package/skills/claude-cli/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: wz:claude-cli
+description: How to use Claude Code CLI programmatically for reviews, automation, and non-interactive operations within Wazir pipelines.
+---
+
+# Claude Code 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 Claude Code CLI (Anthropic's official CLI for Claude) in Wazir pipelines. Claude Code is an agentic coding tool that operates in your terminal with access to tools like file operations, search, and bash execution.
+
+## Commands
+
+### claude (interactive)
+
+Launch the interactive TUI for ad-hoc work.
+
+```bash
+claude
+claude "Fix the failing test in src/auth.ts"
+```
+
+### Print Mode (non-interactive)
+
+The `-p` (or `--print`) flag is the primary mode for Wazir automation. It runs Claude Code non-interactively, outputs the result to stdout, and exits.
+
+```bash
+# Basic non-interactive prompt
+claude -p "Explain the architecture of this project"
+
+# Pipe data from stdin (avoids command-line length limits)
+git diff main | claude -p "Review this diff for bugs"
+
+# Chain with other tools
+claude -p "List all exported functions" --output-format json | jq '.result'
+
+# Save output to file
+claude -p "Summarize the test coverage" > summary.md
+```
+
+**Key flags (all work with `-p`):**
+
+| Flag | Description |
+|------|-------------|
+| `-p, --print` | Run non-interactively; print response to stdout and exit |
+| `--model <MODEL>` | Select model: `opus`, `sonnet`, `haiku`, or full name (e.g., `claude-opus-4-6`) |
+| `--fallback-model <MODEL>` | Fallback model when the primary is overloaded (print mode) |
+| `--output-format <FORMAT>` | Output format: `text` (default), `json`, `stream-json` |
+| `--json-schema <SCHEMA>` | Enforce structured output conforming to a JSON schema (requires `--output-format json`) |
+| `--allowedTools <TOOLS...>` | Pre-approve specific tools without prompting (space-separated) |
+| `--disallowedTools <TOOLS...>` | Block specific tools from being used |
+| `--max-turns <N>` | Limit agentic turns in a session |
+| `--append-system-prompt <TEXT>` | Add custom instructions while keeping default capabilities (safe choice) |
+| `--system-prompt <TEXT>` | Replace the entire system prompt (removes all defaults; use with caution) |
+| `--dangerously-skip-permissions` | Bypass all permission barriers (CI/CD and dev containers only) |
+| `--verbose` | Enable verbose output for debugging |
+| `--input-format <FORMAT>` | Input format: `text` (default) |
+
+### Session Management
+
+```bash
+# Continue most recent session in current directory
+claude -c
+
+# Resume a specific session by ID
+claude -r <SESSION_ID>
+
+# Resume from a PR
+claude --from-pr <NUMBER>
+
+# Fork a session into a new thread
+claude --fork-session <SESSION_ID>
+
+# Set a custom session ID
+claude --session-id <ID>
+```
+
+### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `claude mcp add` | Add an MCP server (`--transport http\|stdio`, `-s` for scope, `-e` for env vars) |
+| `claude mcp serve` | Expose Claude Code itself as an MCP server |
+| `claude agents` | List all configured agents |
+| `claude config` | Manage configuration settings |
+| `claude remote-control` | Serve your local environment for external builds |
+
+## Model Selection
+
+| Model | Best For | Notes |
+|-------|----------|-------|
+| `opus` / `claude-opus-4-6` | Complex reasoning, architecture, multi-step tasks | Most capable, highest cost |
+| `sonnet` / `claude-sonnet-4-6` | Daily coding, balanced performance | Recommended default |
+| `haiku` / `claude-haiku-4-5` | Quick tasks, fast responses, high volume | Lowest cost, fastest |
+
+**Select via:**
+- CLI flag: `--model opus` or `--model claude-opus-4-6`
+- Interactive: `/model` slash command
+- Environment variable: `CLAUDE_MODEL`
+- Settings: `.claude/settings.json`
+
+**Fallback:** Use `--fallback-model haiku` with `-p` to auto-switch when the primary model is overloaded.
+
+## Permission Management
+
+### allowedTools
+
+Pre-approve tools to avoid interactive permission prompts. Critical for non-interactive automation.
+
+```bash
+# Allow specific tools
+claude -p --allowedTools "Read" "Grep" "Glob" "Bash(npm run test:*)" \
+  "Review the test suite"
+
+# Allow all tools (equivalent to dangerously-skip-permissions but scoped)
+claude -p --allowedTools "Read" "Write" "Edit" "Bash" "Grep" "Glob" \
+  "Fix the bug in auth.ts"
+```
+
+**Tool name patterns:**
+- Exact: `"Read"`, `"Write"`, `"Edit"`, `"Bash"`, `"Grep"`, `"Glob"`
+- Scoped: `"Bash(npm run test:*)"` allows only matching bash commands
+- MCP tools: `"mcp__servername__toolname"`
+
+### disallowedTools
+
+Block specific tools:
+
+```bash
+claude -p --disallowedTools "Write" "Edit" "Bash" \
+  "Analyze this codebase for security issues"
+```
+
+### Project permissions
+
+Store permanent permissions in `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allowedTools": ["Read", "Grep", "Glob"],
+    "deny": ["Bash(rm *)"]
+  }
+}
+```
+
+## Non-Interactive Usage
+
+### Piping data
+
+```bash
+# Pipe a diff for review
+git diff main | claude -p "Review this diff for correctness"
+
+# Pipe file content
+cat src/auth.ts | claude -p "Find potential bugs"
+
+# Pipe combined context
+{ echo "## Spec"; cat spec.md; echo "## Code"; cat src/main.ts; } | \
+  claude -p "Does the code match the spec?"
+```
+
+### Structured output
+
+```bash
+# JSON output with full metadata (tool calls, token usage)
+claude -p --output-format json "List all API endpoints"
+
+# Streaming JSONL (real-time events)
+claude -p --output-format stream-json "Analyze the codebase"
+
+# Schema-enforced structured output
+claude -p --output-format json --json-schema '{"type":"object","properties":{"findings":{"type":"array"},"summary":{"type":"string"}}}' \
+  "Review this code and return findings"
+```
+
+### System prompt customization
+
+```bash
+# Append instructions (keeps default Claude Code capabilities)
+claude -p --append-system-prompt "You are a security auditor. Focus only on vulnerabilities." \
+  "Review src/auth.ts"
+
+# Full override (removes all defaults; use when you need a clean slate)
+claude -p --system-prompt "You are a JSON-only responder. Return only valid JSON." \
+  --output-format json "List all functions in this file"
+```
+
+## MCP Server Integration
+
+Claude Code supports MCP (Model Context Protocol) servers for extended capabilities.
+
+### Adding MCP servers
+
+```bash
+# stdio transport
+claude mcp add github -- npx -y @modelcontextprotocol/server-github
+
+# HTTP transport
+claude mcp add api --transport http https://api.example.com
+
+# With scope (project vs user)
+claude mcp add myserver -s project -- node server.js
+
+# With environment variables
+claude mcp add myserver -e API_KEY=xxx -- node server.js
+```
+
+### Using MCP tools in automation
+
+```bash
+# Allow specific MCP tools in print mode
+claude -p --allowedTools "mcp__github__create_pull_request" "mcp__github__list_issues" \
+  "Create a PR for the current changes"
+```
+
+### Claude Code as MCP server
+
+```bash
+# Expose Claude Code as an MCP server for other tools
+claude mcp serve
+```
+
+**Tool Search (lazy loading):** Since early 2026, Claude Code uses Tool Search for MCP tools by default, loading tool schemas on demand rather than all at once. This reduces context usage by ~95%.
+
+## Built-in Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/model` | Switch model |
+| `/cost` | Show token usage and cost |
+| `/clear` | Clear conversation context |
+| `/compact` | Compress conversation to save tokens |
+| `/help` | Display available commands |
+| `/review` | Review current changes |
+| `/debug` | Debug a failing test or error |
+| `/effort` | Set reasoning effort level |
+
+## Wazir Integration Patterns
+
+### Secondary Review (used by wz:reviewer)
+
+```bash
+CLAUDE_MODEL=$(jq -r '.multi_tool.claude.model // empty' .wazir/state/config.json 2>/dev/null)
+CLAUDE_MODEL=${CLAUDE_MODEL:-sonnet}
+
+# Review uncommitted changes
+git diff | claude -p --model "$CLAUDE_MODEL" \
+  --allowedTools "Read" "Grep" "Glob" \
+  "Review this diff against these acceptance criteria: <criteria>" \
+  2>&1 | tee .wazir/runs/latest/reviews/claude-review.md
+
+# Review a spec or design artifact
+cat artifact.md | claude -p --model "$CLAUDE_MODEL" \
+  "Review this spec against these criteria: <criteria>" \
+  2>&1 | tee .wazir/runs/latest/reviews/claude-review.md
+```
+
+### Structured Review Output
+
+```bash
+claude -p --model "$CLAUDE_MODEL" --output-format json \
+  --json-schema '{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string"},"description":{"type":"string"},"location":{"type":"string"}}}},"summary":{"type":"string"}}}' \
+  "Review the changes in src/auth/" \
+  > .wazir/runs/latest/reviews/claude-review.json
+```
+
+### Parallel Execution as External Validator
+
+```bash
+# Run Claude review in background
+git diff main | claude -p --model haiku \
+  --allowedTools "Read" "Grep" \
+  "Quick security scan of this diff" \
+  > .wazir/runs/latest/reviews/claude-security.md 2>&1 &
+```
+
+### Multi-Turn Programmatic Sessions
+
+For complex automation requiring multiple turns:
+
+```bash
+# Limit turns to prevent runaway sessions
+claude -p --max-turns 5 --allowedTools "Read" "Grep" "Bash(npm test)" \
+  "Run the tests, analyze any failures, and suggest fixes"
+```
+
+## Error Handling
+
+| Error | Handling |
+|-------|----------|
+| **Non-zero exit** (auth/rate-limit/transport) | Log full stderr, mark pass as `claude-unavailable`, use self-review only. Next pass re-attempts. |
+| **Timeout** | Wrap with `timeout 120 claude -p ...`. Treat timeout as `claude-unavailable`. |
+| **Model overloaded** | `--fallback-model haiku` auto-switches. Without it, retry after backoff. |
+| **Permission denied** | Add required tools to `--allowedTools` or use `--dangerously-skip-permissions` in CI. |
+| **Max turns reached** | Increase `--max-turns` or break the task into smaller prompts. |
+
+## Configuration
+
+Claude Code reads configuration from (highest to lowest precedence):
+1. CLI flags (`--model`, `--allowedTools`, etc.)
+2. Environment variables (`CLAUDE_MODEL`, `ANTHROPIC_API_KEY`)
+3. `.claude/settings.json` (project-level)
+4. `~/.claude/settings.json` (user-level)
+5. `.claude/rules/` directory (modular rule files)
+6. `CLAUDE.md` (project instructions)
+7. Auto Memory (persisted learnings)
+
+Key config fields in `settings.json`: `model`, `maxTokens`, `permissions.allowedTools`, `permissions.deny`, `env`.

package/skills/codex-cli/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: wz:codex-cli
+description: How to use Codex CLI programmatically for reviews, execution, and sandbox operations within Wazir pipelines.
+---
+
+# Codex 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 OpenAI Codex CLI in Wazir pipelines. Codex is a terminal-based coding agent that reads your codebase, suggests or implements changes, and executes commands with OS-level sandboxing.
+
+## Commands
+
+### codex (interactive)
+
+Launch the interactive TUI. Default mode for ad-hoc work.
+
+```bash
+codex "Fix the failing test in src/auth.ts"
+```
+
+### codex exec
+
+Run Codex non-interactively (alias: `codex e`). Streams results to stdout or JSONL. This is the primary command for Wazir automation.
+
+```bash
+# Basic non-interactive run
+codex exec "Refactor the auth module to use async/await"
+
+# Pipe a long prompt from stdin
+cat prompt.md | codex exec -
+
+# JSON event stream for programmatic consumption
+codex exec --json "Add error handling to all API routes"
+
+# Write final assistant message to a file
+codex exec --output-file result.md "Summarize the codebase architecture"
+
+# Enforce structured output with a JSON schema
+codex exec --output-schema schema.json "List all exported functions"
+
+# Ephemeral run (no session files persisted)
+codex exec --ephemeral "Quick check: does this file import lodash?"
+```
+
+**Key flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--model <MODEL>` | Override the configured model (e.g., `gpt-5.4`, `gpt-5.4-mini`) |
+| `--json` | Emit newline-delimited JSON events (JSONL) instead of formatted text |
+| `--output-file <PATH>` | Write the final assistant message to a file |
+| `--output-schema <PATH>` | Enforce structured output conforming to a JSON schema |
+| `--ephemeral` | Run without persisting session rollout files |
+| `--full-auto` | Apply the low-friction automation preset (`workspace-write` sandbox + `on-request` approvals) |
+| `--dangerously-bypass-approvals-and-sandbox` / `--yolo` | Bypass all approval prompts and sandboxing (use only inside isolated runners) |
+| `-c key=value` | Set a config override (e.g., `-c model=gpt-5.4`) |
+
+**JSONL event types:** `thread.started`, `turn.started`, `turn.completed`, `turn.failed`, `item.message`, `item.command`, `item.file_change`, `item.mcp_tool_call`.
+
+### codex review
+
+Dedicated code review command. This is what Wazir uses for secondary review in the reviewer skill.
+
+```bash
+# Review uncommitted changes (staged + unstaged + untracked)
+codex review --uncommitted
+
+# Review changes against a base branch
+codex review --base main
+
+# Review a specific commit
+codex review --commit d5853d9
+
+# Review with custom instructions
+codex review --uncommitted "Check for security vulnerabilities and missing error handling"
+
+# Review with model override
+codex review --model gpt-5.4 --base main "Review against these acceptance criteria: ..."
+```
+
+**Key flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--uncommitted` | Review staged, unstaged, and untracked changes |
+| `--base <BRANCH>` | Review changes against a given base branch |
+| `--commit <SHA>` | Review the changes introduced by a specific commit |
+| `--model <MODEL>` | Override the model for this review |
+| `[PROMPT]` | Optional custom review instructions (positional argument) |
+
+### codex resume
+
+Resume a previous interactive session.
+
+```bash
+# Open session picker
+codex resume
+
+# Resume most recent session in current directory
+codex resume --last
+
+# Resume most recent session from any directory
+codex resume --last --all
+
+# Resume a specific session by ID
+codex resume <SESSION_ID>
+```
+
+### codex fork
+
+Fork a previous session into a new thread, preserving the original transcript. Useful for exploring alternative approaches in parallel.
+
+### codex cloud
+
+Browse or execute Codex Cloud tasks from the terminal without opening the TUI.
+
+### codex execpolicy
+
+Evaluate execpolicy rule files and check whether a command would be allowed, prompted, or blocked.
+
+### codex auth
+
+Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.
+
+### codex completion
+
+Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.
+
+## Sandbox Modes
+
+Codex provides OS-level sandboxing to protect your system.
+
+| Sandbox Mode | Description |
+|-------------|-------------|
+| `read-only` | Codex can only read files, no writes or commands |
+| `workspace-write` | Codex can write files in the workspace but external commands are sandboxed |
+| `danger-full-access` | Full system access with no restrictions (use only in VMs/containers) |
+
+## Approval Policies
+
+| Policy | Description |
+|--------|-------------|
+| `suggest` | Default. Every action requires explicit approval before execution |
+| `auto-edit` | Auto-approves file edits but still requires approval for shell commands |
+| `full-auto` | Autonomous mode; executes everything without confirmation |
+
+**Preset shortcut:** `--full-auto` sets `sandbox_mode=workspace-write` + `approval_policy=on-request`.
+
+**Granular control:** Set `approval_policy` to `"on-request"`, `"untrusted"`, or `"never"` in config. You can also define per-command allow/reject rules.
+
+## Model Selection
+
+| Model | Best For | Notes |
+|-------|----------|-------|
+| `gpt-5.4` | Complex coding, reasoning, professional workflows | Recommended default |
+| `gpt-5.4-mini` | Faster, lower-cost tasks, subagents | Uses ~30% of gpt-5.4 quota |
+| `gpt-5.3-codex-spark` | Near-instant real-time coding iteration | Research preview, Pro subscribers |
+
+Select via `--model <model>` flag or `-c model=<model>` config override.
+
+## Non-Interactive Usage
+
+### Piping prompts
+
+```bash
+# Pipe from stdin
+cat prompt.md | codex exec -
+
+# Pipe a diff for review
+git diff main | codex exec - "Review this diff for bugs"
+```
+
+### Structured output
+
+```bash
+# JSONL event stream
+codex exec --json "Analyze the test coverage"
+
+# Schema-enforced output
+codex exec --output-schema schema.json "List all API endpoints"
+```
+
+### Capturing output
+
+```bash
+# Write final message to file
+codex exec --output-file result.md "Summarize changes since v2.0"
+
+# Tee for both display and capture
+codex exec "Review this code" 2>&1 | tee review-output.md
+```
+
+## Wazir Integration Patterns
+
+### Secondary Review (used by wz:reviewer)
+
+```bash
+CODEX_MODEL=$(jq -r '.multi_tool.codex.model // empty' .wazir/state/config.json 2>/dev/null)
+CODEX_MODEL=${CODEX_MODEL:-gpt-5.4}
+
+# Review uncommitted changes
+codex review -c model="$CODEX_MODEL" --uncommitted \
+  "Review against these acceptance criteria: <criteria>" \
+  2>&1 | tee .wazir/runs/latest/reviews/codex-review.md
+
+# Review committed changes against a base branch
+codex review -c model="$CODEX_MODEL" --base main \
+  "Review against these acceptance criteria: <criteria>" \
+  2>&1 | tee .wazir/runs/latest/reviews/codex-review.md
+```
+
+### Non-Code Artifact Review
+
+For reviewing specs, designs, and plans (not code diffs):
+
+```bash
+cat artifact.md | codex exec -c model="$CODEX_MODEL" - \
+  "Review this spec against these criteria: <criteria>" \
+  2>&1 | tee .wazir/runs/latest/reviews/codex-review.md
+```
+
+### Parallel Execution
+
+Use Codex as an external validator alongside the primary Wazir review:
+
+```bash
+# Run Codex review in background, merge findings later
+codex review --uncommitted "Check for security issues" \
+  > .wazir/runs/latest/reviews/codex-security.md 2>&1 &
+```
+
+## Error Handling
+
+| Error | Handling |
+|-------|----------|
+| **Non-zero exit** (auth/rate-limit/transport) | Log full stderr, mark pass as `codex-unavailable`, use self-review only for that pass. Next pass re-attempts Codex (transient failures may recover). |
+| **Timeout** | Set reasonable timeouts via shell (`timeout 120 codex review ...`). If exceeded, treat as `codex-unavailable`. |
+| **Model unavailable** | Fall back to `gpt-5.4-mini` if primary model is overloaded. |
+| **Rate limiting** | Respect retry-after headers. Space sequential calls by at least 5 seconds. |
+
+## Configuration
+
+Codex CLI reads configuration from:
+- `~/.codex/config.yaml` or `~/.codex/config.json` (global)
+- `.codex/config.yaml` in the project root (project-level)
+- Command-line flags and `-c key=value` overrides (highest precedence)
+
+Key config fields: `model`, `approval_policy`, `sandbox_mode`, `providers`.

package/skills/debugging/SKILL.md

@@ -5,6 +5,19 @@ description: Use when behavior is wrong or verification fails. Follow an observe
 
 # Debugging
 
+## 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`
+
 > **Note:** This skill uses Wazir CLI commands for symbol-first code
 > exploration. If the CLI index is unavailable, fall back to direct file reads —
 > the generic OBSERVE methodology (read files, inspect state, gather evidence)

package/skills/design/SKILL.md

@@ -7,6 +7,19 @@ description: Guide the designer role through open-pencil MCP workflow to produce
 
 Use open-pencil MCP tools to create visual designs from the approved spec.
 
+## 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`
+
 ## Prerequisites
 
 - open-pencil MCP server running (`openpencil-mcp` or `openpencil-mcp-http`)

package/skills/dispatching-parallel-agents/SKILL.md

@@ -5,6 +5,19 @@ description: Use when facing 2+ independent tasks that can be worked on without
 
 # Dispatching Parallel Agents
 
+## 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
 
 You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

package/skills/executing-plans/SKILL.md

@@ -5,6 +5,19 @@ description: Use when you have a written implementation plan to execute in a sep
 
 # Executing Plans
 
+## 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
 
 Load plan, review critically, execute all tasks with per-task review checkpoints, report when complete.