@wazir-dev/cli 1.0.0

package/schemas/usage.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wazir.dev/schemas/usage.schema.json",
+  "title": "Usage Report",
+  "description": "Per-run token usage tracking and context savings data.",
+  "type": "object",
+  "required": ["schema_version", "run_id", "created_at", "updated_at", "phases", "roles", "savings", "totals"],
+  "properties": {
+    "schema_version": { "type": "integer", "const": 1 },
+    "run_id": { "type": "string", "minLength": 1 },
+    "created_at": { "type": "string", "format": "date-time" },
+    "updated_at": { "type": "string", "format": "date-time" },
+    "phases": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "started_at": { "type": "string", "format": "date-time" },
+          "completed_at": { "type": ["string", "null"], "format": "date-time" },
+          "events_count": { "type": "integer", "minimum": 0 },
+          "capture_bytes_raw": { "type": "integer", "minimum": 0 },
+          "capture_bytes_summary": { "type": "integer", "minimum": 0 },
+          "estimated_tokens_if_raw": { "type": "integer", "minimum": 0 },
+          "estimated_tokens_avoided": { "type": "integer", "minimum": 0 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "roles": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "events_count": { "type": "integer", "minimum": 0 },
+          "capture_bytes_raw": { "type": "integer", "minimum": 0 },
+          "estimated_tokens_if_raw": { "type": "integer", "minimum": 0 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "savings": {
+      "type": "object",
+      "properties": {
+        "capture_routing": {
+          "type": "object",
+          "properties": {
+            "raw_bytes": { "type": "integer", "minimum": 0 },
+            "summary_bytes": { "type": "integer", "minimum": 0 },
+            "estimated_tokens_avoided": { "type": "integer", "minimum": 0 },
+            "strategy": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        "context_mode": {
+          "type": "object",
+          "properties": {
+            "available": { "type": "boolean" },
+            "raw_kb": { "type": "number", "minimum": 0 },
+            "context_kb": { "type": "number", "minimum": 0 },
+            "savings_ratio": { "type": "string" },
+            "per_tool": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "call_count": { "type": "integer", "minimum": 0 },
+                  "raw_kb": { "type": "number", "minimum": 0 },
+                  "context_kb": { "type": "number", "minimum": 0 }
+                },
+                "additionalProperties": false
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "compaction": {
+          "type": "object",
+          "properties": {
+            "compaction_count": { "type": "integer", "minimum": 0 },
+            "pre_compaction_tokens_est": { "type": "integer", "minimum": 0 },
+            "post_compaction_tokens_est": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "totals": {
+      "type": "object",
+      "properties": {
+        "total_events": { "type": "integer", "minimum": 0 },
+        "total_capture_bytes_raw": { "type": "integer", "minimum": 0 },
+        "total_capture_bytes_summary": { "type": "integer", "minimum": 0 },
+        "total_estimated_tokens_if_raw": { "type": "integer", "minimum": 0 },
+        "total_estimated_tokens_avoided": { "type": "integer", "minimum": 0 },
+        "savings_percentage": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/verification-proof.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wazir.dev/schemas/verification-proof.schema.json",
+  "title": "Verification Proof Artifact",
+  "type": "object",
+  "required": ["phase", "role", "run_id", "created_at", "sources", "status", "loop_number", "commands"],
+  "properties": {
+    "phase": { "const": "verify" },
+    "role": { "const": "verifier" },
+    "run_id": { "type": "string", "minLength": 1 },
+    "created_at": { "type": "string", "format": "date-time" },
+    "sources": { "type": "array", "items": { "type": "string" } },
+    "status": { "type": "string", "minLength": 1 },
+    "loop_number": { "type": "integer", "minimum": 0 },
+    "commands": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["command", "exit_code"],
+        "properties": {
+          "command": { "type": "string", "minLength": 1 },
+          "exit_code": { "type": "integer" }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/wazir-manifest.schema.json

@@ -0,0 +1,173 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wazir.dev/schemas/wazir-manifest.schema.json",
+  "title": "Wazir Manifest v2",
+  "type": "object",
+  "required": [
+    "manifest_version",
+    "project",
+    "versioning_policy",
+    "paths",
+    "hosts",
+    "workflows",
+    "phases",
+    "roles",
+    "export_targets",
+    "required_hooks",
+    "protected_paths",
+    "prohibited_terms",
+    "adapters",
+    "index",
+    "validation_checks"
+  ],
+  "properties": {
+    "manifest_version": {
+      "const": 2
+    },
+    "project": {
+      "type": "object",
+      "required": ["name", "display_name", "version", "description", "license"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "display_name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "license": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "versioning_policy": {
+      "type": "object",
+      "required": ["strategy", "stability", "compatibility"],
+      "properties": {
+        "strategy": { "type": "string", "minLength": 1 },
+        "stability": { "type": "string", "minLength": 1 },
+        "compatibility": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "paths": {
+      "type": "object",
+      "required": [
+        "roles",
+        "workflows",
+        "skills",
+        "hooks",
+        "templates",
+        "schemas",
+        "expertise",
+        "docs",
+        "exports",
+        "tooling",
+        "examples",
+        "state_root_default"
+      ],
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "hosts": {
+      "type": "array",
+      "items": {
+        "enum": ["claude", "codex", "gemini", "cursor"]
+      },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "workflows": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "phases": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "roles": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "export_targets": {
+      "type": "array",
+      "items": {
+        "enum": ["claude", "codex", "gemini", "cursor"]
+      },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "required_hooks": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "protected_paths": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "prohibited_terms": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "adapters": {
+      "type": "object",
+      "required": ["context_mode"],
+      "properties": {
+        "context_mode": { "$ref": "#/$defs/adapter" },
+        "open_pencil": { "$ref": "#/$defs/adapter" }
+      },
+      "additionalProperties": false
+    },
+    "index": {
+      "type": "object",
+      "required": ["core_parsers", "optional_language_plugins"],
+      "properties": {
+        "core_parsers": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "optional_language_plugins": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "validation_checks": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    }
+  },
+  "$defs": {
+    "adapter": {
+      "type": "object",
+      "required": [
+        "enabled_by_default",
+        "required",
+        "install_mode",
+        "package_presence"
+      ],
+      "properties": {
+        "enabled_by_default": { "type": "boolean" },
+        "required": { "type": "boolean" },
+        "install_mode": { "enum": ["external"] },
+        "package_presence": { "enum": ["optional"] }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/skills/README.md

@@ -0,0 +1,40 @@
+# skills/
+
+This directory holds canonical reusable Wazir procedures.
+
+Allowed:
+
+- reusable operating procedures
+- scoped execution guides
+- review and verification skills
+
+Not allowed:
+
+- one-off task logs
+- generated host exports
+
+Rules:
+
+- Keep skill behavior aligned with the canonical operating model.
+- Remove superseded skills instead of leaving conflicting active instructions in place.
+- Active skills currently expected in this directory:
+  - `wz:brainstorming`
+  - `wz:debugging`
+  - `wz:design`
+  - `wz:dispatching-parallel-agents`
+  - `wz:executing-plans`
+  - `wz:finishing-a-development-branch`
+  - `wz:receiving-code-review`
+  - `wz:requesting-code-review`
+  - `wz:subagent-driven-development`
+  - `wz:tdd`
+  - `wz:using-git-worktrees`
+  - `wz:using-skills`
+  - `wz:verification`
+  - `wz:writing-plans`
+  - `wz:writing-skills`
+  - `prepare-next`
+  - `run-audit`
+  - `scan-project`
+  - `self-audit`
+- Only active skills belong in this directory.

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: wz:brainstorming
+description: Use before implementation work to turn operator briefings into an approved design with explicit trade-offs.
+---
+
+# Brainstorming
+
+Read `input/` first, then inspect only the repo surfaces needed to understand the request.
+
+Rules:
+
+1. Do not write implementation code before the design is reviewed with the operator.
+2. Ask clarifying questions only when the ambiguity changes scope, architecture, or acceptance criteria.
+3. Propose 2-3 approaches with trade-offs and a recommendation.
+4. Write the approved design to `docs/plans/YYYY-MM-DD-<topic>-design.md`.
+5. Hand off to `wz:writing-plans` after approval.
+
+Required outputs:
+
+- design summary
+- open questions or resolved assumptions
+- explicit recommendation and rejected alternatives
+
+---
+
+## Team Mode: Structured Dialogue
+
+**Condition:** Only activate when `team_mode: parallel` in `.wazir/runs/latest/run-config.yaml`. Otherwise, use the default single-agent brainstorming above.
+
+When team mode is active, spawn a 3-agent team using Claude Code Agent Teams:
+
+### Agents
+
+| Agent | Role | Cognitive Mode |
+|-------|------|----------------|
+| **Free Thinker** | Proposes design directions, creative leaps, "what if..." scenarios. Speaks first, opens new threads. | Divergent generation |
+| **Grounder** | Challenges proposals, sorts signal from noise, picks winners, redirects dead ends. Responds to Free Thinker. | Convergent editing |
+| **Synthesizer** | Observes silently, maintains a running summary, produces the final design document. Never participates in dialogue. | Synthesis only |
+
+### Communication Protocol
+
+- Free Thinker and Grounder exchange via **broadcast** (all agents see every message)
+- Synthesizer **NEVER** participates in dialogue — only observes and writes to files
+- After each direction is explored (3-5 exchanges), the Grounder decides: pursue, park, or redirect
+
+### Dialogue Flow
+
+1. **Open a direction** — Free Thinker proposes (broadcast)
+2. **Deepen** — 3-5 exchanges between Free Thinker and Grounder
+3. **Decide** — Grounder calls it: pursue, park, or redirect
+4. **Next direction** — Free Thinker opens a new thread, aware of connections to prior threads
+
+Early rounds: more divergent. Later rounds: more convergent.
+
+### Depth-Bounded Behavior
+
+| Depth | Directions to explore | Exchanges per direction |
+|-------|-----------------------|------------------------|
+| Standard | 3-5 | 3 exchanges |
+| Deep | 5-8 | 5 exchanges |
+
+### Convergence
+
+The dialogue has converged when:
+1. Enough directions have been explored for the depth level
+2. The pursued directions have genuine range (not variations of the same idea)
+3. The Grounder signals satisfaction
+4. Further dialogue is producing diminishing returns
+
+### Output
+
+The Synthesizer produces the design document following the same format as single-agent brainstorming:
+- Design summary
+- Open questions or resolved assumptions
+- Explicit recommendation and rejected alternatives
+
+The Synthesizer then writes the design to `docs/plans/YYYY-MM-DD-<topic>-design.md` and hands off to `wz:writing-plans`.

package/skills/debugging/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: wz:debugging
+description: Use when behavior is wrong or verification fails. Follow an observe-hypothesize-test-fix loop instead of guesswork.
+---
+
+# Debugging
+
+> **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)
+> still applies.
+
+Follow this order:
+
+1. **Observe**
+
+   Use symbol-first exploration to locate the fault efficiently:
+
+   1. `wazir index search-symbols <suspected-area>`
+      — find relevant symbols by name.
+   2. `wazir recall symbol <name-or-id> --tier L1`
+      — understand structure (signature, JSDoc, imports).
+   3. Form a hypothesis based on L1 summaries.
+   4. `wazir recall file <path> --start-line N --end-line M`
+      — read ONLY the suspect code slice.
+   5. Escalate to a full file read only if the bug cannot be localized from slices.
+   6. If recall fails (no index/summaries), fall back to direct file reads — the
+      generic OBSERVE methodology (read files, inspect state, gather evidence)
+      still applies.
+
+   Also record the exact failure, reproduction path, command output, and current
+   assumptions.
+
+2. **Hypothesize**
+
+   List 2-3 plausible root causes and rank them.
+
+3. **Test**
+
+   Run the smallest discriminating check that can confirm or reject the top hypothesis.
+
+4. **Fix**
+
+   Apply the minimum corrective change, then rerun the failing check and the relevant broader verification set.
+
+Rules:
+
+- change one thing at a time
+- keep evidence for each failed hypothesis
+- if three cycles fail, record the blocker in the active execution artifact or handoff instead of inventing certainty

package/skills/design/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: design
+description: Guide the designer role through open-pencil MCP workflow to produce design artifacts from an approved spec.
+---
+
+# Design
+
+Use open-pencil MCP tools to create visual designs from the approved spec.
+
+## Prerequisites
+
+- open-pencil MCP server running (`openpencil-mcp` or `openpencil-mcp-http`)
+- Approved spec artifact available
+- Bun runtime installed (required by open-pencil)
+
+## Workflow
+
+1. **Read the spec** -- understand what needs to be designed (screens, components, flows).
+2. **Create document** -- `new_document` to start fresh or `open_file` to work with existing `.fig`.
+3. **Set up design tokens** -- `create_collection` and `create_variable` for colors, spacing, typography from spec/brand.
+4. **Build frames** -- `create_shape` (type: FRAME) for each screen/component. Use `set_layout` for auto-layout.
+5. **Populate content** -- `render` (JSX) for complex component trees, or individual `create_shape` + `set_fill` + `set_text` calls.
+6. **Bind tokens** -- `bind_variable` to connect fills/strokes/text to design variables.
+7. **Export** -- `export_image` for screenshots, `export_svg` for vectors.
+8. **Save** -- `save_file` to persist the `.fig`.
+9. **Generate code** -- use CLI `open-pencil export design.fig -f jsx --style tailwind` for Tailwind JSX.
+10. **Extract tokens** -- `analyze_colors`, `analyze_typography`, `analyze_spacing` to build tokens JSON.
+
+## Key MCP Tools
+
+| Phase | Tools |
+|-------|-------|
+| Read | `get_page_tree`, `find_nodes`, `get_node`, `list_variables` |
+| Create | `create_shape`, `render` (JSX), `create_page`, `create_component` |
+| Style | `set_fill`, `set_stroke`, `set_layout`, `set_font`, `set_effects` |
+| Variables | `create_collection`, `create_variable`, `bind_variable` |
+| Export | `export_image`, `export_svg`, `save_file` |
+| Analyze | `analyze_colors`, `analyze_typography`, `analyze_spacing`, `analyze_clusters` |
+| Diff | `diff_create`, `diff_show` (before/after snapshots) |
+
+## Required Outputs
+
+- `.fig` design file saved
+- Tailwind JSX export
+- HTML + CSS export
+- Design tokens JSON
+- Screenshot PNGs of each top-level frame
+
+## When Open-Pencil is Unavailable
+
+If the open-pencil MCP server is not running or Bun is not installed, the design phase cannot produce `.fig` artifacts. In this case:
+- Skip this phase and proceed to planning with text-only design specifications.
+- Document the design intent in prose within the spec artifact instead.
+- The design-review workflow should also be skipped.
+
+## Rules
+
+1. Every design must have auto-layout on all frames (no absolute positioning except icons/decorations).
+2. Use design variables for all colors and spacing -- no hardcoded hex values.
+3. Export screenshots after every major change for visual verification.
+4. Create a `diff_create` snapshot before modifications to enable rollback.

package/skills/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: wz:dispatching-parallel-agents
+description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
+---
+
+# Dispatching Parallel Agents
+
+## 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.
+
+When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
+
+**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Multiple failures?" [shape=diamond];
+    "Are they independent?" [shape=diamond];
+    "Single agent investigates all" [shape=box];
+    "One agent per problem domain" [shape=box];
+    "Can they work in parallel?" [shape=diamond];
+    "Sequential agents" [shape=box];
+    "Parallel dispatch" [shape=box];
+
+    "Multiple failures?" -> "Are they independent?" [label="yes"];
+    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
+    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
+    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
+    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
+}
+```
+
+**Use when:**
+- 3+ test files failing with different root causes
+- Multiple subsystems broken independently
+- Each problem can be understood without context from others
+- No shared state between investigations
+
+**Don't use when:**
+- Failures are related (fix one might fix others)
+- Need to understand full system state
+- Agents would interfere with each other
+
+## The Pattern
+
+### 1. Identify Independent Domains
+
+Group failures by what's broken:
+- File A tests: Tool approval flow
+- File B tests: Batch completion behavior
+- File C tests: Abort functionality
+
+Each domain is independent - fixing tool approval doesn't affect abort tests.
+
+### 2. Create Focused Agent Tasks
+
+Each agent gets:
+- **Specific scope:** One test file or subsystem
+- **Clear goal:** Make these tests pass
+- **Constraints:** Don't change other code
+- **Expected output:** Summary of what you found and fixed
+
+### 3. Dispatch in Parallel
+
+```typescript
+// In Claude Code / AI environment
+Task("Fix agent-tool-abort.test.ts failures")
+Task("Fix batch-completion-behavior.test.ts failures")
+Task("Fix tool-approval-race-conditions.test.ts failures")
+// All three run concurrently
+```
+
+### 4. Review and Integrate
+
+When agents return:
+- Read each summary
+- Verify fixes don't conflict
+- Run full test suite
+- Integrate all changes
+
+## Agent Prompt Structure
+
+Good agent prompts are:
+1. **Focused** - One clear problem domain
+2. **Self-contained** - All context needed to understand the problem
+3. **Specific about output** - What should the agent return?
+
+```markdown
+Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
+
+1. "should abort tool with partial output capture" - expects 'interrupted at' in message
+2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
+3. "should properly track pendingToolCount" - expects 3 results but gets 0
+
+These are timing/race condition issues. Your task:
+
+1. Read the test file and understand what each test verifies
+2. Identify root cause - timing issues or actual bugs?
+3. Fix by:
+   - Replacing arbitrary timeouts with event-based waiting
+   - Fixing bugs in abort implementation if found
+   - Adjusting test expectations if testing changed behavior
+
+Do NOT just increase timeouts - find the real issue.
+
+Return: Summary of what you found and what you fixed.
+```
+
+## Common Mistakes
+
+**Dispatching dependent tasks**
+- **Problem:** Agent A changes file that Agent B needs
+- **Fix:** Identify dependencies, sequence those, parallelize the rest
+
+**Vague agent prompts**
+- **Problem:** "Fix the tests" → agent doesn't know which ones or where to start
+- **Fix:** Specific test names, file paths, expected vs actual behavior
+
+**Not reviewing integration**
+- **Problem:** Both agents fix same file differently → merge conflict
+- **Fix:** Always review all changes together, run full suite after integration
+
+**Too many agents at once**
+- **Problem:** 10 agents running, can't review them all
+- **Fix:** Start with 2-3, review, then dispatch more if needed