@wazir-dev/cli 1.0.0 → 1.2.0

package/skills/executing-plans/SKILL.md

@@ -5,9 +5,22 @@ 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, report when complete.
+Load plan, review critically, execute all tasks with per-task review checkpoints, report when complete.
 
 **Announce at start:** "I'm using the executing-plans skill to implement this plan."
 
@@ -27,7 +40,18 @@ For each task:
 1. Mark as in_progress
 2. Follow each step exactly (plan has bite-sized steps)
 3. Run verifications as specified
-4. Mark as completed
+4. Review BEFORE marking complete (per-task review, 5 task-execution dimensions):
+   - Run task-review loop with `--mode task-review`
+   - Use `codex review --uncommitted` for uncommitted changes, or `codex review --base <sha>` if already committed
+   - Codex error handling: if codex exits non-zero, log the error, mark the pass as codex-unavailable, and use self-review findings only. Do not treat a Codex failure as a clean pass.
+   - Resolve all findings before proceeding
+   - Log to: `.wazir/runs/latest/reviews/execute-task-<NNN>-review-pass-<N>.md`
+   - Cap tracking: `wazir capture loop-check --task-id <NNN>`
+   - This is NOT the final scored review -- it is a per-task gate using 5 task-execution dimensions
+   - See `docs/reference/review-loop-pattern.md` for the full review loop contract
+5. Only after review passes: mark as completed, commit
+
+**Standalone mode:** When no `.wazir/runs/latest/` exists, review logs go to `docs/plans/` alongside the artifact. The loop runs for `pass_counts[depth]` passes with no cap guard.
 
 ### Step 3: Complete Development
 
@@ -58,9 +82,11 @@ After all tasks complete and verified:
 - Review plan critically first
 - Follow plan steps exactly
 - Don't skip verifications
+- Don't skip per-task review -- it catches issues before they cascade to later tasks
 - Reference skills when plan says to
 - Stop when blocked, don't guess
 - Never start implementation on main/master branch without explicit user consent
+- Review loop pattern: see `docs/reference/review-loop-pattern.md`
 
 ## Integration
 

package/skills/executor/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: wz:executor
+description: Run the execution phase — implement the approved plan with TDD, quality gates, and verification.
+---
+
+# Executor
+
+## Model Annotation
+When multi-model mode is enabled, the executor phase uses:
+- **Sonnet** for per-task implementation (write-implementation)
+- **Sonnet** for per-task review (task-review)
+- **Sonnet** for test execution (run-tests)
+- **Opus** for orchestration decisions
+
+## 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`
+
+Run the Executor phase — implement the approved plan, then verify all claims.
+
+## Phase Prerequisites (Hard Gate)
+
+Before proceeding, verify these artifacts exist. Check each file. If ANY file is missing, **STOP immediately** and report:
+
+> **Cannot start Executor phase: missing prerequisite artifacts.**
+>
+> Missing:
+> - [list missing files]
+>
+> Run `/wazir:clarifier` to produce the missing artifacts.
+
+Required artifacts:
+- [ ] `.wazir/runs/latest/clarified/clarification.md`
+- [ ] `.wazir/runs/latest/clarified/spec-hardened.md`
+- [ ] `.wazir/runs/latest/clarified/design.md`
+- [ ] `.wazir/runs/latest/clarified/execution-plan.md`
+
+**This is a hard gate. Do NOT proceed without all artifacts. Do NOT rationalize that the input is "clear enough" to skip phases. The existence of detailed input does NOT replace the pipeline's clarification, specification, design, and planning phases.**
+
+**Standalone mode exception:** If `.wazir/runs/latest/` does not exist at all, operate in standalone mode (skip this check).
+
+## Prerequisites
+
+1. Read the execution plan from `.wazir/runs/latest/clarified/execution-plan.md`.
+2. Read `.wazir/state/config.json` for depth settings.
+
+## Pre-Execution Validation
+
+Run these checks before implementing:
+- `wazir validate manifest` — confirm manifest schema is valid
+- `wazir validate hooks` — confirm hook contracts are intact
+
+If either fails, surface the failure and do NOT proceed until resolved.
+
+## Execute (execute workflow)
+
+Implement tasks in the order defined by the execution plan.
+
+For each task:
+
+1. **Read** the task from the execution plan
+2. **Implement** using TDD (write test first, make it pass, refactor)
+3. **Verify locally** — run tests, type checks, linting as appropriate
+4. **Review BEFORE commit** (per-task review, NOT final review):
+   - Reviewer runs task-review loop with `--mode task-review` using 5 task-execution dimensions (correctness, tests, wiring, drift, quality)
+   - Reads Codex model from config: `CODEX_MODEL=$(jq -r '.multi_tool.codex.model // empty' .wazir/state/config.json 2>/dev/null); CODEX_MODEL=${CODEX_MODEL:-gpt-5.4}`
+   - Uses `codex review -c model="$CODEX_MODEL" --uncommitted` for the current task's changes
+   - Codex error handling: if codex exits non-zero, log error, mark pass as `codex-unavailable`, use self-review only for that pass. Do NOT skip. Next pass still attempts Codex.
+   - Executor resolves findings, reviewer re-reviews
+   - Loop runs for `pass_counts[depth]` passes (quick=3, standard=5, deep=7). No extension.
+   - Review logs: `.wazir/runs/latest/reviews/execute-task-<NNN>-review-pass-<N>.md`
+   - Loop cap tracking: `wazir capture loop-check --task-id <NNN>`
+   - See `docs/reference/review-loop-pattern.md` for full protocol
+   - NOTE: this is the per-task review (5 dims), not the final scored review (7 dims) which runs in Phase 4
+5. **Commit** — only after review passes, commit with conventional commit format: `<type>(<scope>): <description>`
+6. **CHANGELOG** — if user-facing change, update `CHANGELOG.md` under `[Unreleased]` using keepachangelog types: Added, Changed, Fixed, Removed, Deprecated, Security.
+7. **Record** evidence at `.wazir/runs/latest/artifacts/task-NNN/`
+
+Review loops follow `docs/reference/review-loop-pattern.md`. Code review scoping: review uncommitted changes before commit. If changes are committed, use `--base <pre-task-sha>`.
+
+Tasks always run sequentially.
+
+**Standalone mode:** When no `.wazir/runs/latest/` exists, review logs go to `docs/plans/`.
+
+## Verify (verify workflow)
+
+After all tasks are complete, run deterministic verification:
+
+1. Run the full test suite
+2. Run type checks (if applicable)
+3. Run linters
+4. Verify all acceptance criteria from the spec have evidence
+5. Produce verification proof at `.wazir/runs/latest/artifacts/verification-proof.md`
+
+This is NOT a review loop — it produces proof, not findings. If verification fails, report which criteria lack evidence and offer to fix.
+
+## Context Retrieval
+
+- Use `wazir index search-symbols <query>` to locate relevant code before reading
+- Read full files directly when editing or verifying
+- Use `wazir recall file <path> --tier L1` for files you need to understand but not modify
+- When dispatching subagents, include: "Use wazir index search-symbols before direct file reads."
+
+## Escalation
+
+Pause and ask the user when:
+- The plan is blocked or contradictory
+- Implementation would require unapproved scope change
+- A task's acceptance criteria can't be met
+
+## Done
+
+When all tasks are complete and verified:
+
+> **Executor phase complete.**
+>
+> - Tasks: [completed]/[total] implemented
+> - Verification: proof at `.wazir/runs/latest/artifacts/verification-proof.md`
+>
+> **Next:** Run `/reviewer --mode final` to review against the original input.

package/skills/finishing-a-development-branch/SKILL.md

@@ -5,6 +5,19 @@ description: Use when implementation is complete, all tests pass, and you need t
 
 # Finishing a Development Branch
 
+## 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
 
 Guide completion of development work by presenting clear options and handling chosen workflow.

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.