@wazir-dev/cli 1.0.0

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

@@ -0,0 +1,105 @@
+---
+name: wz:requesting-code-review
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
+---
+
+# Requesting Code Review
+
+Dispatch wz:code-reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
+
+**Core principle:** Review early, review often.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-driven development
+- After completing major feature
+- Before merge to main
+
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## How to Request
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Dispatch code-reviewer subagent:**
+
+Use Task tool with wz:code-reviewer type, fill template at `./code-reviewer.md`
+
+**Placeholders:**
+- `{WHAT_WAS_IMPLEMENTED}` - What you just built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` - Brief summary
+
+**3. Act on feedback:**
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
+
+## Example
+
+```
+[Just completed Task 2: Add verification function]
+
+You: Let me request code review before proceeding.
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[Dispatch wz:code-reviewer subagent]
+  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
+
+You: [Fix progress indicators]
+[Continue to Task 3]
+```
+
+## Integration with Workflows
+
+**Subagent-Driven Development:**
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
+
+**Executing Plans:**
+- Review after each batch (3 tasks)
+- Get feedback, apply, continue
+
+**Ad-Hoc Development:**
+- Review before merge
+- Review when stuck
+
+## Red Flags
+
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
+
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification
+
+See template at: ./code-reviewer.md

package/skills/requesting-code-review/code-reviewer.md

@@ -0,0 +1,108 @@
+# Code Review Agent
+
+You are reviewing code changes for production readiness.
+
+**Your task:**
+1. Review {WHAT_WAS_IMPLEMENTED}
+2. Compare against {PLAN_OR_REQUIREMENTS}
+3. Check code quality, architecture, testing
+4. Categorize issues by severity
+5. Assess production readiness
+
+## What Was Implemented
+
+{DESCRIPTION}
+
+## Requirements/Plan
+
+{PLAN_OR_REQUIREMENTS}
+
+## Git Range to Review
+
+**Base:** {BASE_SHA}
+**Head:** {HEAD_SHA}
+
+```bash
+git diff --stat {BASE_SHA}..{HEAD_SHA}
+git diff {BASE_SHA}..{HEAD_SHA}
+```
+
+## Review Checklist
+
+**Code Quality:**
+- Clean separation of concerns?
+- Proper error handling?
+- Type safety (if applicable)?
+- DRY principle followed?
+- Edge cases handled?
+
+**Architecture:**
+- Sound design decisions?
+- Scalability considerations?
+- Performance implications?
+- Security concerns?
+
+**Testing:**
+- Tests actually test logic (not mocks)?
+- Edge cases covered?
+- Integration tests where needed?
+- All tests passing?
+
+**Requirements:**
+- All plan requirements met?
+- Implementation matches spec?
+- No scope creep?
+- Breaking changes documented?
+
+**Production Readiness:**
+- Migration strategy (if schema changes)?
+- Backward compatibility considered?
+- Documentation complete?
+- No obvious bugs?
+
+## Output Format
+
+### Strengths
+[What's well done? Be specific.]
+
+### Issues
+
+#### Critical (Must Fix)
+[Bugs, security issues, data loss risks, broken functionality]
+
+#### Important (Should Fix)
+[Architecture problems, missing features, poor error handling, test gaps]
+
+#### Minor (Nice to Have)
+[Code style, optimization opportunities, documentation improvements]
+
+**For each issue:**
+- File:line reference
+- What's wrong
+- Why it matters
+- How to fix (if not obvious)
+
+### Recommendations
+[Improvements for code quality, architecture, or process]
+
+### Assessment
+
+**Ready to merge?** [Yes/No/With fixes]
+
+**Reasoning:** [Technical assessment in 1-2 sentences]
+
+## Critical Rules
+
+**DO:**
+- Categorize by actual severity (not everything is Critical)
+- Be specific (file:line, not vague)
+- Explain WHY issues matter
+- Acknowledge strengths
+- Give clear verdict
+
+**DON'T:**
+- Say "looks good" without checking
+- Mark nitpicks as Critical
+- Give feedback on code you didn't review
+- Be vague ("improve error handling")
+- Avoid giving a clear verdict

package/skills/run-audit/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: run-audit
+description: Run a structured audit on your codebase — security, code quality, architecture, performance, dependencies, or custom. Produces a report or actionable plan.
+---
+
+# Run Audit — Structured Codebase Audit Pipeline
+
+## Overview
+
+This skill runs a structured audit on your codebase. It collects three parameters interactively (audit type, scope, output mode), then feeds them through the pipeline: Research → Audit → Report or Plan.
+
+The audit uses the existing `researcher` role composed with audit-specific expertise modules. No new canonical role is introduced.
+
+## Pre-Flight Checks
+
+Before starting, verify:
+
+1. **Git repository exists** — the project must be a git repo. If not, STOP and report.
+2. **Git repository is clean or changes are committed** — warn the user if there are uncommitted changes that might affect audit accuracy.
+
+## Step 1: Collect Audit Type
+
+Present this prompt and wait for the user's response:
+
+> **What would you like to audit?**
+> 1. **Security** — vulnerabilities, secrets, OWASP, dependency risks
+> 2. **Code Quality** — complexity, duplication, dead code, naming
+> 3. **Architecture** — coupling, layering, design doc adherence
+> 4. **Performance** — bottlenecks, memory, inefficient patterns
+> 5. **Dependencies** — outdated, vulnerable, unused packages
+> 6. **Custom** — describe your own audit focus
+>
+> Enter 1-6 (or type your own):
+
+Map selection: `1` → `security`, `2` → `code-quality`, `3` → `architecture`, `4` → `performance`, `5` → `dependencies`, `6` → `custom`.
+
+If `custom`: ask the user to describe what they want to audit. Save their description as `custom_description`.
+
+## Step 2: Collect Scope
+
+Present this prompt and wait for the user's response:
+
+> **What scope should the audit cover?**
+> 1. **Whole project** — scan the entire codebase
+> 2. **Specific branch** — diff against base branch
+> 3. **Specific paths/files** — audit only certain directories or files
+>
+> Enter 1-3:
+
+Map selection: `1` → `whole-project`, `2` → `branch`, `3` → `paths`.
+
+- If `branch`: ask "Which branch? And which base branch to diff against? (default: current main branch)" — save both.
+- If `paths`: ask "Which paths? (comma-separated)" and save the path list.
+
+## Step 3: Collect Output Mode
+
+Present this prompt and wait for the user's response:
+
+> **What output do you want?**
+> 1. **Report** — structured audit findings (analysis only)
+> 2. **Plan** — findings become an implementation plan with fix tasks
+>
+> Enter 1-2 (default: 1 — report):
+
+Map selection: `1` → `report`, `2` → `plan`. Default to `report`.
+
+## Step 4: Confirm and Start
+
+Summarize the audit parameters and ask for confirmation:
+
+> **Audit Summary:**
+> - **Type:** [audit_type]
+> - **Scope:** [scope_detail]
+> - **Output:** [output_mode]
+>
+> Proceed? (y/n)
+
+## Step 5: Research + Audit Execution (Autonomous)
+
+Compose a `researcher` agent with the audit-specific expertise modules from `expertise/composition-map.yaml` (see Concern Mapping below).
+
+Provide the researcher with the audit parameters as context in its prompt (do NOT write a synthetic file to `input/` — that directory is read-only human truth).
+
+The composed researcher will:
+1. Receive the audit parameters in its prompt context
+2. Scan the project (or scoped subset) for patterns relevant to the audit type
+3. Systematically inspect all files within scope
+4. Categorize findings by severity: **critical**, **high**, **medium**, **low**, **info**
+5. For each finding, provide:
+   - **Severity** — critical/high/medium/low/info
+   - **Justification** — why this severity level was assigned
+   - **Category** — specific concern (e.g., "SQL Injection", "Circular Dependency")
+   - **Location** — file path and line number
+   - **Evidence** — code snippet or pattern detected, with source citation
+   - **Remediation** — how to fix it
+6. Produce a summary: total findings, severity breakdown, top recommendations
+7. List open risks and unknowns (per researcher contract)
+
+## Step 6: Output
+
+### Artifact Metadata
+
+All audit output must include artifact metadata per `docs/artifact-model.md`:
+
+```yaml
+phase: discover
+role: researcher
+run_id: <generated UUID>
+created_at: <ISO 8601>
+sources: [<list of files/URLs inspected>]
+status: complete
+loop_number: 0
+```
+
+### Report Mode
+
+Present the audit report directly to the user with this structure:
+
+```markdown
+# <Type> Audit Report — <date>
+
+<!-- artifact: phase=discover role=researcher run_id=<uuid> created_at=<iso> status=complete loop_number=0 sources=[...] -->
+
+## Summary
+- **Scope:** <scope description>
+- **Total findings:** N
+- **Critical:** N | **High:** N | **Medium:** N | **Low:** N | **Info:** N
+
+## Sources Inspected
+- <list of files/directories/branches analyzed>
+
+## Top Recommendations
+1. ...
+2. ...
+3. ...
+
+## Findings
+
+### Critical
+
+#### [C-001] <title>
+- **Category:** <category>
+- **Severity justification:** <why critical>
+- **Location:** `<file>:<line>`
+- **Evidence:** <code snippet with source citation>
+- **Remediation:** <how to fix>
+
+### High
+...
+
+### Medium
+...
+
+### Low
+...
+
+### Info
+...
+
+## Open Risks and Unknowns
+- <anything the researcher could not verify or areas that need deeper investigation>
+```
+
+Announce: **"Audit complete. Report presented above."**
+
+If the user wants to save the report, they can copy it or ask to save it to a location of their choice.
+
+### Plan Mode
+
+After the audit report is produced and presented:
+
+1. **Present findings for approval.** Ask the user:
+   > **The audit found N findings (X critical, Y high, Z medium...). Review the findings above.**
+   > **Approve these findings as the basis for a fix plan? (y/n)**
+   >
+   > You can also ask to modify scope or exclude specific findings before approval.
+
+2. Once the user approves, save the approved findings to `docs/plans/YYYY-MM-DD-audit-<type>-findings.md`
+3. Group related findings into logical fix tasks within the findings doc
+4. Invoke the `wz:writing-plans` skill. Since the approved findings doc exists in `docs/plans/`, `wz:writing-plans` will read it as the approved design and produce the implementation plan + offer execution choice (subagent-driven or autonomous execution)
+
+This satisfies the `wz:writing-plans` contract: it requires an approved design from `docs/plans/` before proceeding. The user's explicit approval in step 1 serves as the approval gate.
+
+## Concern Mapping
+
+Audit type maps to `audit-*` concerns in `expertise/composition-map.yaml`, composed onto the `researcher` role:
+
+| Audit Type | Composition Concern |
+|-----------|--------------------|
+| Security | `audit-security` |
+| Code Quality | `audit-code-quality` |
+| Architecture | `audit-architecture` |
+| Performance | `audit-performance` |
+| Dependencies | `audit-dependencies` |
+| Custom | All `audit-*` concerns combined — researcher uses the full set and focuses based on the user's description |
+
+Note: Only `audit-*` concerns have `researcher` entries in the composition map. Other existing concerns (e.g., `security-auth`, `architecture-patterns`) are keyed on `executor`/`verifier`/`reviewer` and will not be loaded for the researcher role by the composition engine.

package/skills/scan-project/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: scan-project
+description: Build a project profile from manifests, docs, tests, and `input/` so clarification and planning start from evidence.
+---
+
+# Scan Project
+
+Inspect the smallest set of repo surfaces needed to answer:
+
+- what kind of project this is
+- which languages and toolchains are active
+- how verification is expected to work
+- where the relevant product and architecture docs live
+- what constraints appear in `input/`
+
+## Index build / refresh
+
+After the initial scan, ensure a Wazir index is available for
+symbol-level exploration in later phases:
+
+1. If no index exists, run:
+   ```
+   wazir index build && wazir index summarize --tier all
+   ```
+2. If an index already exists, run:
+   ```
+   wazir index refresh
+   ```
+3. Include the output of `wazir index stats` in the project profile so
+   downstream roles can see index coverage at a glance.
+
+Required output:
+
+- a concise project profile with file references
+- index stats (symbol count, file count, staleness)
+- open unknowns that require research or clarification
+
+Rules:
+
+- prefer manifests, scripts, CI config, and current docs over assumptions
+- treat inactive surfaces as historical context only

package/skills/self-audit/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: self-audit
+description: Run a self-audit loop in an isolated git worktree — validates, audits, fixes, verifies, and merges back only on green. Safe self-improvement that cannot break the main working tree.
+---
+
+# Self-Audit — Worktree-Isolated Audit-Fix Loop
+
+## Overview
+
+This skill runs a structured self-audit of the Wazir project itself, operating entirely in an isolated git worktree. It validates the project against all canonical checks, performs deeper structural analysis, fixes issues found, verifies the fixes pass, and only merges back on all-green.
+
+**Safety guarantee:** The main worktree is never modified until all checks pass in isolation.
+
+## Trigger
+
+On-demand: operator invokes `/self-audit` or requests a self-audit loop.
+
+## Worktree Isolation Model
+
+```
+main worktree (untouched)
+  └── agent spawns in isolated worktree (git worktree)
+        ├── Phase 1: Validate (run all checks)
+        ├── Phase 2: Deep audit (structural analysis)
+        ├── Phase 3: Fix (remediate findings)
+        ├── Phase 4: Verify (re-run all checks)
+        └── Phase 5: Report (commit in worktree if green)
+```
+
+If any Phase 4 check fails, the worktree is discarded — no changes reach main.
+
+## Phase 1: CLI Validation Sweep
+
+Run every validation check and capture results:
+
+```bash
+node tooling/src/cli.js validate manifest
+node tooling/src/cli.js validate hooks
+node tooling/src/cli.js validate docs
+node tooling/src/cli.js validate brand
+node tooling/src/cli.js validate runtime
+node tooling/src/cli.js validate changelog
+node tooling/src/cli.js validate commits
+node tooling/src/cli.js doctor --json
+node tooling/src/cli.js export --check
+```
+
+Collect pass/fail for each. Any failure is a finding.
+
+## Phase 2: Deep Structural Audit
+
+Beyond CLI checks, inspect for:
+
+1. **Cross-reference consistency**
+   - Every role in `wazir.manifest.yaml` has a file in `roles/`
+   - Every workflow in manifest has a file in `workflows/`
+   - Every skill directory has a `SKILL.md`
+   - Every schema referenced in docs exists in `schemas/`
+   - Composition map concerns reference existing expertise modules
+
+2. **Documentation drift**
+   - `docs/architecture.md` component table matches actual directory structure
+   - `docs/roles-and-workflows.md` role/workflow lists match manifest
+   - README claims match actual project state
+
+3. **Export freshness**
+   - Generated exports match canonical sources (via `export --check`)
+   - Host export directories contain expected structure
+
+4. **Schema coverage**
+   - Every workflow that produces artifacts has a corresponding schema
+   - Schema files are valid JSON
+
+5. **Hook integrity**
+   - Hook scripts referenced in `.claude/settings.json` exist and are executable
+   - Hook definitions in `hooks/definitions/` cover all manifest-required hooks
+
+6. **Skill structure**
+   - Each skill dir under `skills/` has a well-formed `SKILL.md` with frontmatter
+   - Skills referenced in documentation actually exist
+
+## Phase 3: Fix
+
+For each finding from Phases 1-2:
+
+1. Categorize as **auto-fixable** or **manual-required**
+2. Auto-fixable issues: apply the fix directly
+   - Missing files → create stubs or fix references
+   - Stale exports → run `export build`
+   - Documentation drift → update docs to match reality
+   - Permission issues → `chmod +x` hook scripts
+   - Schema formatting → auto-format
+3. Manual-required issues: document in the audit report with remediation guidance
+
+**Fix constraints:**
+- Never modify `input/` (read-only operator surface)
+- Prefer updating docs to match code (code is truth) unless the code is clearly wrong
+- Keep fixes minimal — one concern per change
+
+## Phase 4: Verify
+
+Re-run the entire Phase 1 validation sweep. All checks must pass.
+
+If any check fails after fixes:
+- Revert the failing fix
+- Document the revert and the root cause
+- Re-verify
+
+## Phase 5: Report & Commit
+
+Produce a structured report:
+
+```markdown
+# Self-Audit Report — Loop N — <date>
+
+## Validation Sweep
+| Check | Before | After |
+|-------|--------|-------|
+| manifest | PASS/FAIL | PASS |
+| hooks | PASS/FAIL | PASS |
+| ... | ... | ... |
+
+## Findings
+### Auto-Fixed (N)
+- [F-001] <description> — fixed by <change>
+- ...
+
+### Manual Required (N)
+- [M-001] <description> — remediation: <guidance>
+- ...
+
+## Changes Made
+- <file>: <what changed>
+- ...
+
+## Verification
+All checks: PASS/FAIL
+```
+
+If all checks pass, commit changes in the worktree with:
+```
+fix(self-audit): loop N — <summary of fixes>
+```
+
+The worktree agent returns its results. If changes were made, the caller can merge them.
+
+## Loop Behavior
+
+When running multiple loops:
+- Loop 1 audits the current state, fixes what it finds
+- Loop 2 audits the result of Loop 1, catches anything missed or introduced
+- Each loop is independent and runs in its own fresh worktree
+- Convergence: if Loop N finds 0 issues, the project is clean