@wazir-dev/cli 1.1.0 → 1.2.0

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.

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,54 @@ Run these checks before implementing:
 
 If either fails, surface the failure and do NOT proceed until resolved.
 
-## Execution
+## 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`
+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.
+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>`.
+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:
 
-If `team_mode: parallel` in config, spawn Agent Teams for independent tasks. Otherwise, tasks run sequentially.
+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`
 
-**Standalone mode:** When no `.wazir/runs/latest/` exists, review logs go to `docs/plans/` alongside the artifact.
+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
 
@@ -66,11 +119,11 @@ Pause and ask the user when:
 
 ## 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.