@wazir-dev/cli 1.0.0

package/AGENTS.md

@@ -0,0 +1,111 @@
+# Wazir Agent Instructions
+
+## Role-Based Workflow System
+
+Wazir uses canonical roles and phased workflows. Role contracts are in `roles/`. Workflow definitions are in `workflows/`.
+
+### Canonical Roles
+
+1. **clarifier** — disambiguate intent, extract acceptance criteria
+2. **researcher** — gather evidence, prior art, domain context
+3. **specifier** — write precise specs from clarified requirements
+4. **designer** — produce architecture and interface designs
+5. **content-author** — create documentation, guides, and prose artifacts
+6. **planner** — break specs into ordered, testable tasks
+7. **executor** — implement code following the plan
+8. **verifier** — run tests, linting, and validation gates
+9. **reviewer** — final quality review against acceptance criteria
+10. **learner** — capture lessons learned and update knowledge base
+
+See `roles/` for full contracts. See `wazir.manifest.yaml` for the authoritative list.
+
+### Entering a Workflow
+
+1. **Clarifier:** read and follow `~/.claude/agents/clarifier.md` — tasks are in `input/`
+2. **Subsequent phases:** the workflow system assigns roles per phase. See `workflows/` for phase sequence.
+3. **Review:** read and follow `~/.claude/agents/reviewer.md` — run all review phases
+
+## Build Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm install` | Install dependencies |
+| `npm test` | Run full test suite (node:test) |
+| `wazir validate` | Validate manifest, hooks, docs, brand, runtime, branches, commits, changelog |
+| `wazir doctor` | Check environment health |
+| `wazir export build` | Build host-native packages |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Usage / argument error |
+| 42 | Validation failure (non-fatal) |
+| 43 | Gate rejection (hard stop) |
+
+## Code Style
+
+- Pure JavaScript — no TypeScript, no JSX, no transpilation
+- Node.js >= 20
+- ES modules (`import` / `export`)
+- Test framework: `node:test` + `node:assert`
+- Zero runtime dependencies in the core kit
+
+### Test Pattern
+
+```js
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+describe('featureName', () => {
+  it('should behave correctly', () => {
+    const result = featureName();
+    assert.strictEqual(result, expected);
+  });
+});
+```
+
+## Project Structure
+
+| Directory | Purpose |
+|-----------|---------|
+| `roles/` | Canonical role contracts (one file per role) |
+| `workflows/` | Phase-based workflow definitions and entry points |
+| `expertise/` | Domain knowledge modules consumed by roles |
+| `skills/` | Reusable skill definitions (prefixed `wz:`) |
+| `hooks/` | Lifecycle hooks (pre-commit, pre-push, gates) |
+| `tooling/` | CLI source, tests, and internal utilities |
+| `exports/` | Generated host-native packages (do not edit) |
+| `templates/` | Scaffold and boilerplate templates |
+| `schemas/` | JSON / YAML schemas for validation |
+| `docs/` | Architecture docs, guides, and references |
+
+## Git Workflow
+
+- **Conventional commits:** `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
+- **Isolated feature branches** — never commit directly to `main`
+- **TDD cycle:** failing test -> implement -> verify -> commit
+
+## Boundaries
+
+- Never edit files in `exports/` directly — they are generated from canonical sources
+- Never modify pipeline input files — they are read-only task input
+- Never skip `wazir doctor` before starting work
+- Never add runtime dependencies to the core kit
+- Never use TypeScript, JSX, or any transpilation step
+- Never commit without running `npm test` first
+- Never bypass validation gates (`wazir validate`)
+
+## Review Mode
+
+This project uses Codex as a secondary reviewer. Review artifacts are in `tasks/opus/reviews/`.
+
+## Operating Constraints
+
+- Use `roles/` as the source of truth for role contracts
+- Keep default live run state outside the repo under `~/.wazir/projects/<project-slug>/`
+- Preserve evidence-first execution, TDD, verification, and conventional commits
+- Use isolated feature branches
+- Reference `wazir.manifest.yaml` for the project manifest and schema

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# 1.0.0 (2026-03-17)
+
+
+### Features
+
+* Wazir v0.1.0 - Engineering with itqan ([d9a5c1b](https://github.com/MohamedAbdallah-14/Wazir/commit/d9a5c1bf1ffe615f67d55181458ead68e5cf7ecf))
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]

package/CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing
+
+Wazir is a host-native engineering OS kit. Contributions that strengthen the product surface are welcome.
+
+## Ground rules
+
+- follow the architecture in `docs/concepts/architecture.md`
+- keep the product host-native — roles, workflows, skills, hooks, and host exports
+- prefer evidence:
+  - TDD for behavior changes
+  - verification commands before completion claims
+  - no fake green paths
+
+## Local setup
+
+1. Clone the repository and install dependencies:
+   ```bash
+   git clone https://github.com/MohamedAbdallah-14/Wazir.git
+   cd wazir
+   npm install
+   ```
+   You should see output ending with something like:
+   ```
+   added XX packages in Xs
+   ```
+2. Run the test suite:
+   ```bash
+   npm test
+   ```
+   Expected output:
+   ```
+   TAP version 13
+   # ... test descriptions ...
+   ok
+   ```
+   All tests must pass before you submit a PR.
+3. Regenerate host packages when export logic or canonical sources change:
+   ```bash
+   wazir export build
+   ```
+4. Check export drift:
+   ```bash
+   wazir export --check
+   ```
+5. Validate the project structure:
+   ```bash
+   wazir validate
+   ```
+
+## Testing expectations
+
+- **What to test:** Every behavior change, new CLI command, hook behavior, or schema change must have accompanying tests.
+- **How to run tests:**
+  ```bash
+  npm test              # run the full suite
+  ```
+- **Coverage:** Tests live alongside the code they verify. If you add a new module in `tooling/src/`, add a corresponding test in `tooling/test/`. If you add a new skill in `skills/`, include a test script or verification step in the skill directory.
+- **TDD is mandatory:** Write the failing test first, then implement the feature or fix.
+
+## Your first contribution
+
+New to Wazir? Start here:
+
+1. Browse issues labeled [`good first issue`](https://github.com/MohamedAbdallah-14/Wazir/labels/good%20first%20issue)
+2. Fork the repository and create a branch: `git checkout -b feat/your-change`
+3. Make your change, add tests, run `npm test`
+4. Open a pull request using the PR template
+
+### Good first issues
+
+Good first issues are small, well-scoped tasks that help you learn the codebase. They typically involve:
+
+- Fixing a typo or improving clarity in documentation
+- Adding a missing validation or error message to the CLI
+- Writing tests for an existing module that lacks coverage
+- Updating a role contract or workflow description to match current behavior
+
+Look for the `good first issue` label, and feel free to comment on the issue to claim it before starting work.
+
+Not sure where to start? Open a [Discussion](https://github.com/MohamedAbdallah-14/Wazir/discussions) and we'll help you find something.
+
+## Change expectations
+
+- keep docs current with the actual behavior you changed
+- update `CHANGELOG.md`
+- add or update tests for new CLI behavior, hook behavior, or schemas
+- avoid adding dependencies unless they materially reduce correctness risk
+
+## Pull requests
+
+- explain the problem, the change, and the verification you ran
+- call out any remaining gaps or follow-up work explicitly
+- if a review tool was unavailable, say so rather than implying review happened
+
+## PR review process
+
+1. **Automated checks:** When you open a PR, CI runs `npm test` and `wazir validate`. Both must pass before review begins.
+2. **Human review:** A maintainer will review your PR for correctness, test coverage, documentation, and alignment with the architecture.
+3. **Feedback:** If changes are requested, push additional commits to the same branch. Avoid force-pushing during review so that reviewers can see incremental changes.
+4. **Merge:** Once approved and all checks pass, a maintainer will merge your PR using a squash merge with a conventional commit message.
+5. **Timeline:** We aim to provide initial review feedback within a few days. If your PR has been open for more than a week without a response, feel free to leave a comment or ping in Discussions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wazir contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,314 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="assets/logo.svg">
+    <img alt="Wazir" src="assets/logo.svg" width="360">
+  </picture>
+</p>
+
+<h3 align="center">Engineering with itqan.</h3>
+
+<p align="center">
+  <a href="https://github.com/MohamedAbdallah-14/Wazir/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/MohamedAbdallah-14/Wazir/ci.yml?branch=main&label=CI" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@wazir-dev/cli"><img src="https://img.shields.io/npm/v/@wazir-dev/cli" alt="npm"></a>
+  <a href="https://github.com/MohamedAbdallah-14/Wazir/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?logo=node.js" alt="Node.js"></a>
+  <a href="https://codecov.io/gh/MohamedAbdallah-14/Wazir"><img src="https://codecov.io/gh/MohamedAbdallah-14/Wazir/graph/badge.svg" alt="codecov"></a>
+  <a href="https://github.com/MohamedAbdallah-14/Wazir/blob/main/CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Claude-supported-5436DA?logo=anthropic" alt="Claude">
+  <img src="https://img.shields.io/badge/Codex-supported-00A36C" alt="Codex">
+  <img src="https://img.shields.io/badge/Gemini-supported-4285F4?logo=google" alt="Gemini">
+  <img src="https://img.shields.io/badge/Cursor-supported-FF6B35" alt="Cursor">
+</p>
+
+
+---
+
+> AI agents don't have a quality problem. They have a management problem.
+
+I'm Mohamed Abdallah. I kept watching AI agents write confident code that broke in production, skip tests, and forget what we agreed on yesterday. So I stopped asking them to be better and built them an engineering department instead.
+
+**Wazir puts engineering discipline inside AI coding agents.**
+No wrapper. No server. Just structure -- inside Claude, Codex, Gemini, and Cursor. Built on 300+ research sources distilled into 261 curated expertise modules across 12 domains.
+
+---
+
+## Quick Start
+
+```bash
+/plugin marketplace add MohamedAbdallah-14/Wazir
+/plugin install wazir
+```
+
+Then tell your agent what to build:
+
+```
+/wazir Build a REST API for managing tasks with authentication
+```
+
+That's it. The pipeline takes over -- clarifies your requirements, writes a spec, plans the work, implements with TDD, reviews, and learns for next time. You approve at the gates. Everything else is automatic.
+
+You can also control the depth and intent directly:
+
+```
+/wazir quick fix the login redirect bug
+/wazir deep design a new onboarding flow
+/wazir audit security
+```
+
+---
+
+### The reviewer is never the author.
+
+When your AI agent reviews its own code, it finds what it expected to find -- nothing. Wazir's adversarial reviewer is a separate agent with different expertise modules. It catches the mistakes your agent is structurally blind to.
+
+### Silence isn't confidence -- it's assumptions.
+
+Your AI agent doesn't ask questions because it's sure. It doesn't ask questions because it's trained to be helpful. Wazir's clarifier forces ambiguity to the surface before a single line is written.
+
+### Done means verified, not declared.
+
+AI agents love to announce they're finished. Wazir doesn't care. Every phase loops until the work and its verification converge. The agent doesn't get to say "done." The process decides.
+
+---
+
+## The Pipeline
+
+Every task flows through 14 phases. Three are adversarial review gates that block progress until the reviewer explicitly approves. Rejection loops back to the authoring phase.
+
+```mermaid
+graph LR
+    P0["0 clarify<br/><sub>clarifier</sub>"]
+    P1["1 discover<br/><sub>researcher</sub>"]
+    P2["2 specify<br/><sub>specifier</sub>"]
+    P3["3 spec-challenge<br/><sub>reviewer | APPROVAL GATE</sub>"]
+    P4["4 author<br/><sub>content-author</sub>"]
+    P5["5 design<br/><sub>designer</sub>"]
+    P6["6 design-review<br/><sub>reviewer | APPROVAL GATE</sub>"]
+    P7["7 plan<br/><sub>planner</sub>"]
+    P8["8 plan-review<br/><sub>reviewer | APPROVAL GATE</sub>"]
+    P9["9 execute<br/><sub>executor</sub>"]
+    P10["10 verify<br/><sub>verifier</sub>"]
+    P11["11 review<br/><sub>reviewer</sub>"]
+    P12["12 learn<br/><sub>learner</sub>"]
+    P13["13 prepare-next<br/><sub>learner</sub>"]
+
+    P0 --> P1 --> P2 --> P3
+    P3 -- approved --> P4 --> P5 --> P6
+    P3 -. rejected .-> P2
+    P6 -- approved --> P7 --> P8
+    P6 -. rejected .-> P5
+    P8 -- approved --> P9 --> P10 --> P11
+    P8 -. rejected .-> P7
+    P11 --> P12 --> P13
+
+    style P3 fill:#c62828,color:#fff
+    style P6 fill:#c62828,color:#fff
+    style P8 fill:#c62828,color:#fff
+```
+
+
+
+> **GATE** = Approval gate. The phase blocks until the reviewer explicitly approves. Rejection loops back to the authoring phase.
+
+---
+
+## How It Works
+
+Three concepts.
+
+**1 -- Roles are isolation boundaries, not personas.** Each of the 10 roles has defined inputs, allowed tools, required outputs, escalation rules, and failure conditions. An agent inside a role cannot write to protected paths, cannot skip required outputs, and must escalate when ambiguity conditions are met. The discipline is structural, not instructional. See [Roles & Workflows](docs/concepts/roles-and-workflows.md).
+
+**2 -- Phases are artifact checkpoints, not conversation stages.** Every phase consumes a named artifact from the previous phase and produces a named artifact for the next. Nothing flows through conversation history. A session can end, a new agent can pick up the artifacts, and delivery continues. The handoff is explicit, structured, and schema-validated against 18 JSON schemas. See [Architecture](docs/concepts/architecture.md).
+
+**3 -- The composition engine loads the right expert automatically.** One agent pretending to be an expert in everything is an expert in nothing. A 4-layer system (always, auto, stacks, concerns) decides which of 261 expertise modules load into each role's context. The executor gets modules on how to build. The verifier gets modules on what to detect. The reviewer gets modules on what to flag. All resolved automatically from the task's declared stack and concerns. Max 15 modules per dispatch, token budget enforced.
+
+---
+
+## Token Savings
+
+Wazir's tiered recall system loads the minimum context each role needs.
+
+
+| Tier        | Tokens    | Content             | Used by                                                |
+| ----------- | --------- | ------------------- | ------------------------------------------------------ |
+| L0          | ~100      | One-line identifier | learner (inventory scans)                              |
+| L1          | ~500-2k   | Structural summary  | clarifier, researcher, planner, reviewer (exploration) |
+| Direct read | Full file | Exact source lines  | executor, verifier (implementation)                    |
+
+
+Capture routing redirects large tool output to run-local files. The agent gets a file path (~50 tokens) instead of the full output. Combined with tiered recall, this yields 60-80% token reduction on exploration-heavy phases.
+
+Run `wazir capture usage` at the end of a session to see the savings:
+
+```
+# Usage Report: run-20260316-091500-b3f7
+
+## Token Savings by Strategy
+| Strategy         | Raw (est. tokens) | After (est. tokens) | Avoided            |
+|------------------|--------------------|---------------------|--------------------|
+| Capture routing  |             36,000 |                  50 |             35,950 |
+| Context-mode     |             81,920 |               1,382 |             80,538 |
+| Compaction       |             80,000 |               5,000 |             75,000 |
+
+## "What If" Comparison
+| Scenario                          | Est. tokens consumed |
+|-----------------------------------|----------------------|
+| Without any savings strategies    |              197,920 |
+| With Wazir savings only           |               86,432 |
+| With Wazir + context-mode         |                6,432 |
+| **Actual savings**                | **96.8%**            |
+```
+
+---
+
+## What's Included
+
+**10 canonical role contracts.** Clarifier, researcher, specifier, content-author, designer, planner, executor, verifier, reviewer, learner. Each has enforceable inputs, outputs, and escalation rules. [Roles reference](docs/reference/roles-reference.md)
+
+**Adversarial review at three chokepoints.** Spec-challenge, plan-review, and final review run by the reviewer role, never the phase author. Nine hard approval gates span the 14-phase pipeline. Nothing advances without explicit clearance. [Architecture](docs/concepts/architecture.md)
+
+**261 curated expertise modules across 12 domains.** Loaded selectively per role per phase via a 4-layer composition engine. Max 15 modules per dispatch, token budget enforced. Wazir ships with 261. Yours could be next. [Expertise index](docs/reference/expertise-index.md)
+
+**Three-tier recall for token savings.** L0 (~~100 tokens), L1 (~~500-2k tokens), direct read for full source. Symbol-first exploration searches the index before reading source. Capture routing redirects large tool output to files. Result: 60-80% token reduction on exploration-heavy phases, measured per-session by `wazir capture usage`. [Indexing and Recall](docs/concepts/indexing-and-recall.md)
+
+**Structured learning.** Proposed learnings require explicit review and scope tagging before promotion. Only learnings whose file patterns overlap the current task get injected into context. The system improves per-project without drifting.
+
+**7 hook contracts for structural guardrails.** These enforce protected path writes (exit 42), loop caps (exit 43), and session observability. [Hooks](docs/reference/hooks.md)
+
+**20+ callable skills.** `/wazir` runs the full pipeline. `/wazir audit security` runs a codebase audit. `/wazir prd` generates a product requirements document from completed runs. Plus TDD, verification, debugging, and more -- each enforcing an exact procedure with evidence at every step. [Skills](docs/reference/skills.md)
+
+**Built-in text humanization.** The composition engine loads domain-specific language rules per role: code rules for the executor (commit messages, comments), content rules for the content-author (microcopy, glossary), and technical-docs rules for the specifier, planner, reviewer, and learner. A 61-item vocabulary blacklist, 24-pattern sentence taxonomy, and two-pass self-audit checklist keep all output sounding like it was written by a person.
+
+**Runs on 4 platforms.** `wazir export build` compiles canonical sources into native packages for Claude, Codex, Gemini, and Cursor. SHA-256 drift detection catches stale exports in CI. [Host exports](docs/reference/host-exports.md)
+
+---
+
+## Compared to Other Tools
+
+The AI coding tool space is fragmenting. Developers bolt together separate plugins for workflow management, specification, memory, output compression, and orchestration. Not every project needs 14 phases. For a weekend hack, prompting is fine. For production, you want structure.
+
+
+| Dimension              | Wazir                         | [Superpowers](https://github.com/obra/superpowers) | [Spec-Kit](https://github.com/github/spec-kit) | [Micro-Agent](https://github.com/BuilderIO/micro-agent) | [Distill](https://github.com/samuelfaj/distill) | [Claude-Mem](https://github.com/thedotmack/claude-mem) | [OMC](https://github.com/yeachan-heo/oh-my-claudecode) |
+| ---------------------- | ----------------------------- | -------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
+| **Category**           | Engineering OS                | Skills framework                                   | Spec toolkit                                   | Code gen agent                                          | Output compressor                               | Memory plugin                                          | Orchestration layer                                    |
+| **Scope**              | Full lifecycle (14 phases)    | Dev workflow (~20 skills)                          | Specify / Plan / Implement                     | Single-file TDD loop                                    | CLI output compression                          | Session memory                                         | Multi-agent orchestration                              |
+| **Enforced roles**     | 10 canonical, contractual     | None (skills only)                                 | None                                           | None                                                    | None                                            | None                                                   | 32 agents (behavioral)                                 |
+| **Phase model**        | 14 explicit, artifact-gated   | 7-step (advisory)                                  | 3-step                                         | 1 (generate/test)                                       | N/A                                             | N/A                                                    | 5-step pipeline                                        |
+| **Adversarial review** | 3 gate phases                 | Code review skill                                  | No                                             | No                                                      | No                                              | No                                                     | team-verify step                                       |
+| **Context management** | L0/L1 tiered recall           | None                                               | None                                           | None                                                    | LLM compression                                 | Vector DB (ChromaDB)                                   | Token routing                                          |
+| **Schema validation**  | 18 JSON schemas               | No                                                 | No                                             | No                                                      | No                                              | No                                                     | No                                                     |
+| **Guardrails**         | 7 hook contracts              | None                                               | None                                           | None                                                    | None                                            | 5 hooks (memory)                                       | Agent tracking                                         |
+| **External deps**      | None (host-native)            | None (prompt-only)                                 | Python CLI                                     | Node.js CLI                                             | Node.js + LLM                                   | ChromaDB, SQLite, Bun                                  | tmux, exp. teams API                                   |
+| **Host support**       | Claude, Codex, Gemini, Cursor | Claude, Codex, Gemini, Cursor, OpenCode            | Claude, Copilot, Gemini                        | Any LLM provider                                        | Any LLM                                         | Claude Code only                                       | Claude Code (+ workers)                                |
+
+
+Each of these tools solves a real problem. Wazir's approach is to solve them together -- one system, shared context, structural enforcement -- instead of asking developers to wire separate plugins into a coherent workflow.
+
+---
+
+## Install
+
+**Claude Code plugin (recommended):**
+
+```bash
+/plugin marketplace add MohamedAbdallah-14/Wazir
+/plugin install wazir
+```
+
+The plugin loads skills, roles, and workflows into your Claude sessions. Then type `/wazir` and go.
+
+**npm / Homebrew:**
+
+```bash
+npm install -g @wazir-dev/cli                                              # npm
+brew tap MohamedAbdallah-14/homebrew-wazir && brew install wazir           # Homebrew
+```
+
+---
+
+## Documentation
+
+**For users:**
+
+
+| I want to...                    | Go to                                                     |
+| ------------------------------- | --------------------------------------------------------- |
+| Install and get started         | [Installation](docs/getting-started/01-installation.md)   |
+| Run my first task               | [First Run](docs/getting-started/02-first-run.md)         |
+| Understand the architecture     | [Architecture](docs/concepts/architecture.md)             |
+| Learn about roles and workflows | [Roles & Workflows](docs/concepts/roles-and-workflows.md) |
+
+
+**For contributors:**
+
+
+| I want to...             | Go to                                                                |
+| ------------------------ | -------------------------------------------------------------------- |
+| Set up for development   | [CONTRIBUTING.md](CONTRIBUTING.md)                                   |
+| Look up CLI commands     | [CLI Reference](docs/reference/tooling-cli.md)                       |
+| Configure the manifest   | [Configuration Reference](docs/reference/configuration-reference.md) |
+| Browse all documentation | [Documentation Hub](docs/README.md)                                  |
+
+
+---
+
+## Project Status
+
+Wazir is in active early development (pre-1.0-alpha).
+
+The pipeline, roles, and expertise modules are stable and used in production by the maintainers. The CLI, schemas, and hook contracts work. But this is early software -- APIs may change before 1.0.
+
+What's solid:
+
+- The 14-phase pipeline and 10 role contracts
+- 261 expertise modules across 12 domains
+- Host exports for Claude, Codex, Gemini, and Cursor
+- The composition engine and tiered recall system
+
+What may change:
+
+- CLI command surface and flags
+- Schema field names
+- Hook contract signatures
+- State directory structure
+
+Feedback and contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Why "Wazir"?
+
+Wazir (وزير) -- the vizier. The operational mastermind who ran empires while the sultan held authority. In Arabic chess, the wazir became the queen: the most powerful piece on the board.
+
+The Arabic word *itqan* (إتقان) means mastery -- doing something so well that nothing remains to improve. This isn't a tagline. It's the test every commit runs against.
+
+---
+
+## Acknowledgments
+
+Wazir builds on ideas and patterns from these projects:
+
+- **[superpowers](https://github.com/obra/superpowers)** by [@obra](https://github.com/obra) -- skill system architecture, bootstrap injection pattern, session-start hooks
+- **[context-mode](https://github.com/mksglu/context-mode)** -- context window optimization and sandbox execution patterns
+- **[spec-kit](https://github.com/github/spec-kit)** by GitHub -- specification-driven development patterns
+- **[oh-my-claudecode](https://github.com/yeachan-heo/oh-my-claudecode)** by [@yeachan-heo](https://github.com/yeachan-heo) -- Claude Code customization and extension patterns
+- **[micro-agent](https://github.com/BuilderIO/micro-agent)** by Builder.io -- test-driven code generation patterns
+- **[distill](https://github.com/samuelfaj/distill)** by [@samuelfaj](https://github.com/samuelfaj) -- CLI output compression for token savings
+- **[claude-mem](https://github.com/thedotmack/claude-mem)** by [@thedotmack](https://github.com/thedotmack) -- persistent memory patterns for coding agents
+- **[ideation](https://github.com/bladnman/ideation_team_skill)** by [@bladnman](https://github.com/bladnman) -- multi-agent structured dialogue patterns
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, branch conventions, commit format, and contribution guidelines.
+
+---
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

package/assets/composition-engine.mmd

@@ -0,0 +1,34 @@
+graph TD
+    A["Task Spec<br/>(from Clarifier)"] --> B{"Composition<br/>Engine"}
+
+    B --> C["Layer 1: Always<br/>Role-intrinsic modules"]
+    B --> D["Layer 2: Auto<br/>Cross-stack modules"]
+    B --> E["Layer 3: Stacks<br/>Detected stack modules"]
+    B --> F["Layer 4: Concerns<br/>Declared concern modules"]
+
+    C --> |"e.g. antipatterns/process,<br/>error-handling, naming"| G["Role-scoped<br/>module set"]
+    D --> |"e.g. security/vulnerability,<br/>secrets, performance,<br/>technical-debt"| G
+    E --> |"e.g. flutter.md,<br/>react.md, node.md"| G
+    F --> |"e.g. rtl, i18n,<br/>accessibility, security-auth"| G
+
+    G --> H{"Token Budget<br/>Enforcer"}
+    H --> |"max 15 modules"| I["Composed<br/>Agent Prompt"]
+
+    subgraph "Role-specific loading rules"
+        J["executor: HOW to build<br/>+ antipatterns"]
+        K["designer: HOW to design<br/>+ design antipatterns"]
+        L["verifier: WHAT to detect<br/>(antipatterns + testing)"]
+        M["reviewer: WHAT to flag<br/>(antipatterns + architecture)"]
+        N["content-author: content<br/>foundations + i18n + editorial"]
+    end
+
+    B -.-> J
+    B -.-> K
+    B -.-> L
+    B -.-> M
+    B -.-> N
+
+    style B fill:#f9f,stroke:#333
+    style H fill:#ff9,stroke:#333
+    style I fill:#9f9,stroke:#333
+    style G fill:#9cf,stroke:#333

package/assets/demo-script.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Demo commands for terminal recording
+# This script is called by record-demo.sh via asciinema
+
+echo "$ wazir doctor"
+npx wazir doctor
+sleep 2
+
+echo ""
+echo "$ wazir export build"
+npx wazir export build
+sleep 2
+
+echo ""
+echo "$ wazir index build"
+npx wazir index build
+sleep 1

package/assets/logo-dark.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 100" role="img" aria-label="Wazir">
+  <title>Wazir</title>
+  <!-- Composition Star: two overlapping squares forming 8-pointed star (dark mode) -->
+  <!-- Square 1: Lightened Teal (visible on dark bg #0D1117) -->
+  <rect x="25" y="25" width="50" height="50" fill="#1A8A8A" />
+  <!-- Square 2: Lighter Warm Teal (kept bright for dark backgrounds) -->
+  <polygon points="50,14.64 85.36,50 50,85.36 14.64,50" fill="#8FBCBB" />
+  <!-- Overlap octagon: Mid-dark teal (drawn last, painter's model) -->
+  <polygon points="25,39.64 39.64,25 60.36,25 75,39.64 75,60.36 60.36,75 39.64,75 25,60.36" fill="#0D6060" />
+  <!-- Wordmark -->
+  <text x="110" y="62" fill="#F0F0F5"
+        font-family="'Inter','SF Pro Display','Segoe UI',system-ui,-apple-system,'Helvetica Neue',Arial,sans-serif"
+        font-size="42" font-weight="700" letter-spacing="0.08em">WAZIR</text>
+</svg>

package/assets/logo.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 100" role="img" aria-label="Wazir">
+  <title>Wazir</title>
+  <!-- Composition Star: two overlapping squares forming 8-pointed star -->
+  <!-- Square 1: Deep Teal (axis-aligned, centered at 50,50) -->
+  <rect x="25" y="25" width="50" height="50" fill="#0D4F4F" />
+  <!-- Square 2: Lighter Warm Teal (rotated 45 degrees, as polygon) -->
+  <polygon points="50,14.64 85.36,50 50,85.36 14.64,50" fill="#8FBCBB" />
+  <!-- Overlap octagon: Darkest value (drawn last, painter's model) -->
+  <polygon points="25,39.64 39.64,25 60.36,25 75,39.64 75,60.36 60.36,75 39.64,75 25,60.36" fill="#094040" />
+  <!-- Wordmark -->
+  <text x="110" y="62" fill="#0D4F4F"
+        font-family="'Inter','SF Pro Display','Segoe UI',system-ui,-apple-system,'Helvetica Neue',Arial,sans-serif"
+        font-size="42" font-weight="700" letter-spacing="0.08em">WAZIR</text>
+</svg>