@wazir-dev/cli 1.0.0

package/skills/executing-plans/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: wz:executing-plans
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+---
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute all tasks, report when complete.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+**Note:** Wazir works best with subagent support. The quality of work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use wz:subagent-driven-development instead of this skill.
+
+## The Process
+
+### Step 1: Load and Review Plan
+1. Read plan file
+2. Review critically - identify any questions or concerns about the plan
+3. If concerns: Raise them with the user before starting
+4. If no concerns: Create TodoWrite and proceed
+
+### Step 2: Execute Tasks
+
+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
+
+### Step 3: Complete Development
+
+After all tasks complete and verified:
+- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use wz:finishing-a-development-branch
+- Follow that skill to verify tests, present options, execute choice
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Hit a blocker (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing starting
+- You don't understand an instruction
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## When to Revisit Earlier Steps
+
+**Return to Review (Step 1) when:**
+- User updates the plan based on your feedback
+- Fundamental approach needs rethinking
+
+**Don't force through blockers** - stop and ask.
+
+## Remember
+- Review plan critically first
+- Follow plan steps exactly
+- Don't skip verifications
+- Reference skills when plan says to
+- Stop when blocked, don't guess
+- Never start implementation on main/master branch without explicit user consent
+
+## Integration
+
+**Required workflow skills:**
+- **wz:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+- **wz:writing-plans** - Creates the plan this skill executes
+- **wz:finishing-a-development-branch** - Complete development after all tasks

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

@@ -0,0 +1,169 @@
+---
+name: wz:finishing-a-development-branch
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+Guide completion of development work by presenting clear options and handling chosen workflow.
+
+**Core principle:** Verify tests -> Present options -> Execute choice -> Clean up.
+
+**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
+
+## The Process
+
+### Step 1: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:**
+```
+Tests failing ( failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Don't proceed to Step 2.
+
+**If tests pass:** Continue to Step 2.
+
+### Step 2: Determine Base Branch
+
+```bash
+# Try common base branches
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+Or ask: "This branch split from main - is that correct?"
+
+### Step 3: Present Options
+
+Present exactly these 4 options:
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+Which option?
+```
+
+**Don't add explanation** - keep options concise.
+
+### Step 4: Execute Choice
+
+#### Option 1: Merge Locally
+
+```bash
+# Switch to base branch
+git checkout <base>
+
+# Pull latest
+git pull
+
+# Merge feature branch
+git merge <feature-branch>
+
+# Verify tests on merged result
+
+# If tests pass
+git branch -d <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 2: Push and Create PR
+
+```bash
+# Push branch
+git push -u origin <feature-branch>
+
+# Create PR
+gh pr create --title "<title>" --body "<description>"
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+
+**Don't cleanup worktree.**
+
+#### Option 4: Discard
+
+**Confirm first:**
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <count>
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for exact confirmation.
+
+If confirmed:
+```bash
+git checkout <base>
+git branch -D <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+### Step 5: Cleanup Worktree
+
+**For Options 1, 2, 4:**
+
+Check if in worktree:
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+If yes:
+```bash
+git worktree remove <path>
+```
+
+**For Option 3:** Keep worktree.
+
+## Quick Reference
+
+| Option | Merge | Push | Keep Worktree | Cleanup Branch |
+|--------|-------|------|---------------|----------------|
+| 1. Merge locally | Y | - | - | Y |
+| 2. Create PR | - | Y | Y | - |
+| 3. Keep as-is | - | - | Y | - |
+| 4. Discard | - | - | - | Y (force) |
+
+## Common Mistakes
+
+**Skipping test verification**
+- **Problem:** Merge broken code, create failing PR
+- **Fix:** Always verify tests before offering options
+
+**Open-ended questions**
+- **Problem:** "What should I do next?" -> ambiguous
+- **Fix:** Present exactly 4 structured options
+
+**Automatic worktree cleanup**
+- **Problem:** Remove worktree when might need it (Option 2, 3)
+- **Fix:** Only cleanup for Options 1 and 4
+
+**No confirmation for discard**
+- **Problem:** Accidentally delete work
+- **Fix:** Require typed "discard" confirmation

package/skills/humanize/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: wz:humanize
+description: Use when reviewing or editing any text artifact (specs, plans, code comments, commit messages, content, documentation) to detect and remove AI writing patterns. Runs a 4-phase pipeline -- Scan for AI vocabulary and structural patterns, Identify severity and domain, Rewrite problematic sections, Verify meaning preservation. Invoke on existing text that needs corrective humanization. For preventive humanization, the composition engine loads domain-specific rules automatically.
+---
+
+# Humanize
+
+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.
+
+## Phase 1: Scan
+
+Detect the domain and scan for AI patterns.
+
+### Domain detection
+
+Determine which domain rules apply:
+
+1. **Code domain** -- if the text is a commit message, code comment, PR description, or CHANGELOG entry, load `expertise/humanize/domain-rules-code.md`
+2. **Content domain** -- if the text is microcopy, glossary, notification template, i18n value, or seed content, load `expertise/humanize/domain-rules-content.md`
+3. **Technical-docs domain** -- if the text is a spec, plan, architecture doc, API doc, review finding, or learning artifact, load `expertise/humanize/domain-rules-technical-docs.md`
+4. **Default** -- if the domain is unclear, use technical-docs rules
+
+### Pattern scan
+
+1. Scan all prose text against `expertise/humanize/vocabulary-blacklist.md`. Record each match with its location and category.
+2. Scan for structural patterns from `expertise/humanize/sentence-patterns.md`. Record pattern type and count per section.
+3. Estimate sentence length distribution for prose sections. Calculate approximate CV (standard deviation / mean of sentence word counts).
+4. Check paragraph openers against the banned openers list.
+
+### What to skip
+
+Do not scan or modify:
+- Code blocks (fenced or indented)
+- URLs and file paths
+- Proper nouns, product names, and code identifiers
+- YAML frontmatter, JSON, and other machine-readable formats
+- Inline code (backtick-wrapped text)
+- Quoted text (blockquotes reproducing someone else's words)
+
+## Phase 2: Identify
+
+Classify each finding by severity and group for rewriting.
+
+### Severity classification
+
+- **High** -- blacklisted vocabulary in a non-exception context, introduction/conclusion boilerplate, promotional language, generic superlatives. These are the strongest AI signals.
+- **Medium** -- copula avoidance, em dash overuse, synonym cycling, excessive hedging, banned paragraph openers, vague attributions. These signal AI when clustered.
+- **Low** -- rule of three, negative parallelisms, boldface overuse, title case, curly quotes, false ranges. These are minor tells.
+- **Burstiness** -- CV below 0.4 in prose sections longer than 10 sentences. Address after vocabulary and structural fixes.
+
+### Grouping
+
+Group findings by section so rewrites can be done in context rather than word-by-word.
+
+### When to stop early
+
+If the scan finds fewer than 3 findings total and all are low severity, report "no changes needed" and skip Phases 3-4. Do not force rewrites on already-clean text.
+
+## Phase 3: Rewrite
+
+Apply fixes, starting with high-severity findings.
+
+### Vocabulary replacement
+
+Replace blacklisted words with suggested alternatives from `expertise/humanize/vocabulary-blacklist.md`. Check the domain exceptions column first -- if the word is legitimate in this context, keep it and note the exception.
+
+### Structural fixes
+
+- Remove or compress introduction and conclusion boilerplate
+- Replace conjunctive phrase padding with direct transitions
+- Convert copula avoidance ("serves as") to direct verbs ("is")
+- Replace vague attributions with specific citations or cut them
+- Break synonym cycling by picking the clearest term and repeating it
+
+### Burstiness adjustment
+
+After vocabulary and structural fixes:
+- Check if prose sections now meet the CV > 0.4 target
+- If not, split long uniform sentences or combine short choppy ones
+- Place short sentences after complex ones for natural rhythm
+- Do not mechanically alternate short-long -- vary the pattern
+
+### Domain-specific voice
+
+Apply the voice rules from the detected domain's rules file:
+- Technical docs: imperative mood, name specifics, no metaphors
+- Code: brevity, no idioms, format preservation
+- Content: conversational tone, translatable phrasing, editorial standards baseline
+
+### Fallback rules
+
+- **Legitimate domain use of a blacklisted word:** Keep it. Note the exception in your output. "Robust" in a statistical context is precise, not an AI tell.
+- **Precision vs. style conflict:** Preserve precision. If replacing a word would reduce technical accuracy, keep the original word.
+- **Already-clean text:** Do not force rewrites. If a section passes the scan with no high or medium findings, leave it unchanged.
+- **Format preservation:** Never modify conventional commit prefixes, YAML frontmatter, JSON structures, code blocks, or inline code. These formats have exact syntax requirements.
+
+## Phase 4: Verify
+
+Run the two-pass self-audit from `expertise/humanize/self-audit-checklist.md`.
+
+### Pass 1: Pattern re-scan
+
+Re-scan the rewritten text to confirm:
+- All high-severity findings are resolved
+- Medium-severity findings are resolved or documented as acceptable
+- No new AI patterns were introduced during rewriting
+
+### Pass 2: Meaning preservation
+
+Re-read every changed sentence and confirm:
+- The rewritten version conveys the same information
+- No specific names, numbers, versions, or commands were lost
+- Acceptance criteria remain testable (specs)
+- Task descriptions remain actionable (plans)
+- Structured formats are intact
+
+### Output
+
+Report:
+- Number of findings before and after rewriting
+- Summary of changes made, grouped by severity
+- Any domain exceptions that were preserved
+- Confirmation that meaning was preserved (Pass 2 result)

package/skills/init-pipeline/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: wz:init-pipeline
+description: Initialize the Wazir pipeline with interactive setup. Creates project directories, selects mode, and configures the pipeline.
+---
+
+# Initialize Pipeline
+
+Set up the Wazir pipeline for this project. All questions use numbered interactive options — one question at a time.
+
+## Step 0: Check Wazir CLI
+
+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?**
+>
+> 1. **npm** (Recommended) — `npm install -g wazir`
+> 2. **Local link** — `npm link` from the Wazir project root
+> 3. **Skip** — Continue without the CLI (some features will be unavailable)
+
+If the user picks 1, run `npm install -g wazir` 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.
+
+**If installed**, run `wazir doctor --json` to verify repo health and continue.
+
+## Step 1: Create Project Directories
+
+```bash
+mkdir -p .wazir/input .wazir/state .wazir/runs
+```
+
+## Step 2: Choose Pipeline Mode
+
+Present this question:
+
+> **How should Wazir run in this project?**
+>
+> 1. **Claude only** (Recommended) — Everything runs in Claude Code. Single model, slash commands only.
+> 2. **Multi-model** — Still Claude Code, but routes tasks by complexity (Haiku for micro, Sonnet for standard, Opus for complex).
+> 3. **Multi-tool** — Claude Code + 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?**
+>
+> 1. **Codex** — 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 4: Write Config
+
+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"]`)
+
+Example for claude-only:
+```json
+{
+  "model_mode": "claude-only"
+}
+```
+
+Example for multi-tool with codex:
+```json
+{
+  "model_mode": "multi-tool",
+  "multi_tool": {
+    "tools": ["codex"]
+  }
+}
+```
+
+## Step 5: 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
+
+  ## 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.
+
+- If **both**: Create both files.
+
+## Step 6: Confirm
+
+List all files created and show the selected mode. Then present:
+
+> **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)
+
+## Interaction Rules
+
+- **One question at a time** — never combine questions
+- **Numbered options** — always present choices as numbered lists
+- **Mark defaults** — always show "(Recommended)" on the suggested option
+- **Wait for answer** — never proceed past a question until the user responds
+- **No open-ended questions** — every question has concrete options to pick from

package/skills/prepare-next/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: prepare-next
+description: Use after a run or execution slice completes to produce a clean next-run handoff without auto-applying stale context.
+---
+
+# Prepare Next
+
+Create a next-run handoff that captures:
+
+- current status
+- completed work
+- unresolved blockers
+- required approvals
+- explicitly accepted learnings only
+
+Rules:
+
+- 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

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

@@ -0,0 +1,123 @@
+---
+name: wz:receiving-code-review
+description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
+---
+
+# Code Review Reception
+
+## Overview
+
+Code review requires technical evaluation, not emotional performance.
+
+**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+```
+WHEN receiving code review feedback:
+
+1. READ: Complete feedback without reacting
+2. UNDERSTAND: Restate requirement in own words (or ask)
+3. VERIFY: Check against codebase reality
+4. EVALUATE: Technically sound for THIS codebase?
+5. RESPOND: Technical acknowledgment or reasoned pushback
+6. IMPLEMENT: One item at a time, test each
+```
+
+## Forbidden Responses
+
+**NEVER:**
+- "You're absolutely right!" (explicit CLAUDE.md violation)
+- "Great point!" / "Excellent feedback!" (performative)
+- "Let me implement that now" (before verification)
+
+**INSTEAD:**
+- Restate the technical requirement
+- Ask clarifying questions
+- Push back with technical reasoning if wrong
+- Just start working (actions > words)
+
+## Handling Unclear Feedback
+
+```
+IF any item is unclear:
+  STOP - do not implement anything yet
+  ASK for clarification on unclear items
+
+WHY: Items may be related. Partial understanding = wrong implementation.
+```
+
+**Example:**
+```
+the user: "Fix 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+
+WRONG: Implement 1,2,3,6 now, ask about 4,5 later
+RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+```
+
+## Source-Specific Handling
+
+### From the user
+- **Trusted** - implement after understanding
+- **Still ask** if scope unclear
+- **No performative agreement**
+- **Skip to action** or technical acknowledgment
+
+### From External Reviewers
+```
+BEFORE implementing:
+  1. Check: Technically correct for THIS codebase?
+  2. Check: Breaks existing functionality?
+  3. Check: Reason for current implementation?
+  4. Check: Works on all platforms/versions?
+  5. Check: Does reviewer understand full context?
+
+IF suggestion seems wrong:
+  Push back with technical reasoning
+
+IF can't easily verify:
+  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+
+IF conflicts with the user's prior decisions:
+  Stop and discuss with the user first
+```
+
+**Rule:** External feedback - be skeptical, but check carefully.
+
+## YAGNI Check for "Professional" Features
+
+```
+IF reviewer suggests "implementing properly":
+  grep codebase for actual usage
+
+  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
+  IF used: Then implement properly
+```
+
+**Rule:** If we don't need this feature, don't add it.
+
+## Implementation Order
+
+```
+FOR multi-item feedback:
+  1. Clarify anything unclear FIRST
+  2. Then implement in this order:
+     - Blocking issues (breaks, security)
+     - Functional issues (wrong behavior)
+     - Quality improvements (structure, naming)
+     - Nice-to-haves (if time permits)
+  3. Test after each change
+  4. Report what you changed and why
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Clear feedback, technically sound | Implement, test, report |
+| Feedback unclear | Ask for clarification before touching code |
+| Feedback technically wrong | Push back with reasoning |
+| Feedback contradicts user's decisions | Stop, discuss with user |
+| "Implement properly" suggestion | YAGNI check first |
+| Multiple items, some unclear | Clarify ALL unclear items before implementing ANY |