@wazir-dev/cli 1.1.0 → 1.3.0

package/skills/executor/SKILL.md

@@ -5,13 +5,53 @@ description: Run the execution phase — implement the approved plan with TDD, q
 
 # Executor
 
-Run Phase 2 (Execute) for the current project.
+## 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. Check `.wazir/runs/latest/clarified/execution-plan.md` exists. If not, tell the user to run `/wazir:clarifier` first.
-2. Read the execution plan and task specs from `.wazir/runs/latest/tasks/`.
-3. Read `.wazir/state/config.json` for team_mode and depth settings.
+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
 
@@ -21,41 +61,93 @@ Run these checks before implementing:
 
 If either fails, surface the failure and do NOT proceed until resolved.
 
-## Execution
+> **Output to the user** before execution begins:
+> Each task is implemented with TDD (test first, then code) and reviewed before commit. This catches correctness bugs, missing tests, wiring errors, and spec drift at the task level — before they compound across tasks and become expensive to fix.
+
+## Security Awareness
+
+Before implementing each task, check if the task touches security-sensitive areas. Run `detectSecurityPatterns` (from `tooling/src/checks/security-sensitivity.js`) mentally against the planned changes. If security patterns are detected (auth, token, password, session, SQL, fetch, upload, secret, env, API key, cookie, CORS, CSRF, JWT, OAuth, encrypt, decrypt, hash, salt):
+
+- Load security expertise from the composition map for the relevant concern
+- Apply defense-in-depth: validate inputs, parameterize queries, escape outputs, use secure defaults
+- The per-task reviewer will automatically add security dimensions when patterns are detected — expect and address security findings
+
+## Execute (execute workflow)
 
 Implement tasks in the order defined by the execution plan.
 
 For each task:
 
-1. **Read** the task spec at `.wazir/runs/latest/tasks/task-NNN/spec.md`
+**Before starting each task, output to the user:**
+
+> **Implementing Task [NNN]: [task title]** — This enables [what downstream tasks or user-facing features depend on this task].
+>
+> **Looking for:** [Key technical concerns for this specific task — e.g., "correct API contract", "database migration safety", "backwards compatibility"]
+
+1. **Read** the task from the execution plan
 2. **Implement** using TDD (write test first, make it pass, refactor)
-3. **Verify** — run tests, type checks, linting as appropriate
+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 the 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}`
+   - 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 treat a Codex failure as a clean review. Do NOT skip the pass. The next pass still attempts Codex (transient failures may recover).
+   - 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>` (each task has its own cap counter)
+   - 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 later in `/wazir:reviewer --mode final`
+   - 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 the change is user-facing (new feature, behavior change, bug fix visible to users), update `CHANGELOG.md` `[Unreleased]` section. If not user-facing (refactor, internal tooling, tests), skip.
+   - **HARD RULE: One task = one commit.** Commit after EACH task completes its review. Never batch multiple tasks into a single commit. If the reviewer detects multi-task batching, the commit is REJECTED.
+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 the pattern in `docs/reference/review-loop-pattern.md`. Code review scoping: review uncommitted changes before commit. If changes are already committed (subagent workflow), use `codex review -c model="$CODEX_MODEL" --base <pre-task-sha>`.
+**After completing each task, output to the user:**
 
-If `team_mode: parallel` in config, spawn Agent Teams for independent tasks. Otherwise, tasks run sequentially.
+> **Completed Task [NNN]: [task title].**
+>
+> **Changed:** [List of files created/modified, tests added, key implementation decisions]
+>
+> **Without this task:** [Concrete risk — e.g., "no auth middleware means all routes are publicly accessible", "no migration means schema change would require manual DB intervention"]
+>
+> **Review result:** [N] findings in [N] review passes, [N] fixed before commit
+
+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/`.
+
+> **Output to the user** before verification:
+> Verification produces deterministic proof — actual command output, not claims. It confirms that tests pass, types check, linters are clean, and every acceptance criterion has evidence. This is the evidence gate that separates "I think it works" from "here is proof it works."
 
-**Standalone mode:** When no `.wazir/runs/latest/` exists, review logs go to `docs/plans/` alongside the artifact.
+## 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."
+
+## Interaction Mode Awareness
+
+Read `interaction_mode` from run-config at the start of execution:
+
+- **`auto`:** Skip user checkpoints. On escalation, write reason to `.wazir/runs/<id>/escalations/` and STOP (do not proceed without user). Gating agent evaluates phase reports.
+- **`guided`:** Standard behavior — ask user on escalation, show per-task completion summaries.
+- **`interactive`:** Before implementing each task, briefly describe the approach and ask: "About to implement [task] using [approach] — sound right?" Show more detail in per-task summaries.
 
 ## Escalation
 
@@ -64,13 +156,41 @@ Pause and ask the user when:
 - Implementation would require unapproved scope change
 - A task's acceptance criteria can't be met
 
+When escalating, use this pattern:
+
+Ask the user via AskUserQuestion:
+- **Question:** "[Describe the specific blocker or conflict]"
+- **Options:**
+  1. "Adjust the plan to work around the blocker" *(Recommended)*
+  2. "Expand scope to handle the new requirement"
+  3. "Skip this task and continue with the rest"
+  4. "Abort the run"
+
+Wait for the user's selection before continuing.
+
+## Reasoning Output
+
+Throughout the executor phase, produce reasoning at two layers:
+
+**Conversation (Layer 1):** Before each task, explain what you're about to implement and why. After each task, state what would have gone wrong without this task.
+
+**File (Layer 2):** Write `.wazir/runs/<id>/reasoning/phase-executor-reasoning.md` with structured entries per implementation decision:
+- **Trigger** — what prompted the decision (e.g., "task spec requires auth middleware")
+- **Options considered** — implementation alternatives
+- **Chosen** — selected approach
+- **Reasoning** — why this approach over alternatives
+- **Confidence** — high/medium/low
+- **Counterfactual** — what would break without this decision
+
+Key executor reasoning moments: architecture choices, library selections, API design decisions, test strategy decisions, and any deviation from the plan.
+
 ## Done
 
-When all tasks are complete, present:
+When all tasks are complete and verified:
 
-> **Execution complete.**
+> **Executor phase complete.**
 >
 > - Tasks: [completed]/[total] implemented
-> - Artifacts: `.wazir/runs/latest/artifacts/`
+> - Verification: proof at `.wazir/runs/latest/artifacts/verification-proof.md`
 >
-> **Next:** Run `/wazir:reviewer --mode final` to review the changes, or `/wazir` for the full pipeline.
+> **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.