@wazir-dev/cli 1.0.0

package/assets/pipeline.mmd

@@ -0,0 +1,39 @@
+graph LR
+    P0["[0] clarify<br/><i>clarifier</i>"]
+    P1["[1] discover<br/><i>researcher</i>"]
+    P2["[2] specify<br/><i>specifier</i>"]
+    P3{{"[3] spec-challenge<br/><i>reviewer</i><br/>APPROVAL GATE"}}
+    P4["[4] author<br/><i>content-author</i>"]
+    P5["[5] design<br/><i>designer</i>"]
+    P6{{"[6] design-review<br/><i>reviewer</i><br/>APPROVAL GATE"}}
+    P7["[7] plan<br/><i>planner</i>"]
+    P8{{"[8] plan-review<br/><i>reviewer</i><br/>APPROVAL GATE"}}
+    P9["[9] execute<br/><i>executor</i>"]
+    P10["[10] verify<br/><i>verifier</i>"]
+    P11["[11] review<br/><i>reviewer</i>"]
+    P12["[12] learn<br/><i>learner</i>"]
+    P13["[13] prepare-next<br/><i>learner</i>"]
+
+    P0 --> P1 --> P2 --> P3
+    P3 -->|approved| P4 --> P5 --> P6
+    P6 -->|approved| P7 --> P8
+    P8 -->|approved| P9 --> P10 --> P11 --> P12 --> P13
+
+    P3 -.->|rejected| P2
+    P6 -.->|rejected| P5
+    P8 -.->|rejected| P7
+
+    style P3 fill:#f96,stroke:#333,color:#000
+    style P6 fill:#f96,stroke:#333,color:#000
+    style P8 fill:#f96,stroke:#333,color:#000
+    style P0 fill:#e8f4fd,stroke:#333
+    style P1 fill:#e8f4fd,stroke:#333
+    style P2 fill:#e8f4fd,stroke:#333
+    style P4 fill:#d4edda,stroke:#333
+    style P5 fill:#d4edda,stroke:#333
+    style P7 fill:#fff3cd,stroke:#333
+    style P9 fill:#cce5ff,stroke:#333
+    style P10 fill:#f8d7da,stroke:#333
+    style P11 fill:#f8d7da,stroke:#333
+    style P12 fill:#e2e3e5,stroke:#333
+    style P13 fill:#e2e3e5,stroke:#333

package/assets/record-demo.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Record Wazir terminal demo
+# Prerequisites: brew install asciinema && pip3 install agg
+#
+# Usage:
+#   cd /path/to/wazir
+#   bash assets/record-demo.sh
+#
+# Output: assets/demo.gif (should be under 5MB)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_DIR="$(dirname "$SCRIPT_DIR")"
+cd "$REPO_DIR"
+
+# Check prerequisites
+if ! command -v asciinema &>/dev/null; then
+  echo "Error: asciinema not found. Install with: brew install asciinema"
+  exit 1
+fi
+
+if ! command -v agg &>/dev/null; then
+  echo "Error: agg not found. Install with: pip3 install agg"
+  exit 1
+fi
+
+echo "Recording demo..."
+asciinema rec assets/demo.cast \
+  --cols 100 \
+  --rows 25 \
+  --overwrite \
+  -c "bash assets/demo-script.sh"
+
+echo "Converting to GIF..."
+agg assets/demo.cast assets/demo.gif \
+  --cols 100 \
+  --rows 25 \
+  --speed 1.5
+
+# Check file size
+SIZE=$(stat -f%z assets/demo.gif 2>/dev/null || stat -c%s assets/demo.gif 2>/dev/null)
+SIZE_MB=$((SIZE / 1024 / 1024))
+echo "GIF size: ${SIZE_MB}MB"
+
+if [ "$SIZE_MB" -gt 5 ]; then
+  echo "Warning: GIF is over 5MB. Consider increasing --speed or trimming the demo."
+fi
+
+echo "Done. Output: assets/demo.gif"
+echo "Embed in README.md with: ![Wazir Demo](assets/demo.gif)"

package/docs/README.md

@@ -0,0 +1,51 @@
+# Wazir Documentation
+
+## Where should I start?
+
+| I want to... | Start here |
+|---|---|
+| **Get started** with Wazir | [Installation](getting-started/01-installation.md) then [First Run](getting-started/02-first-run.md) |
+| **Understand** how it works | [Architecture](concepts/architecture.md) then [Roles & Workflows](concepts/roles-and-workflows.md) |
+| **Do** a specific task | [Guides](guides/) |
+| **Look up** a command or config | [CLI Reference](reference/tooling-cli.md) then [Configuration](reference/configuration-reference.md) |
+
+## Getting Started (Tutorials)
+
+- [Installation](getting-started/01-installation.md)
+- [First Run](getting-started/02-first-run.md)
+- [Adding Wazir to an Existing Project](getting-started/03-adding-to-project.md) _(coming soon)_
+- [Host Setup](getting-started/04-host-setup.md) _(coming soon)_
+
+## Concepts (Understanding)
+
+- [Architecture](concepts/architecture.md)
+- [Roles and Workflows](concepts/roles-and-workflows.md)
+- [Artifact Model](concepts/artifact-model.md)
+- [Composition Engine](concepts/composition-engine.md)
+- [Observability](concepts/observability.md)
+- [Indexing and Recall](concepts/indexing-and-recall.md)
+- [Terminology Policy](concepts/terminology-policy.md)
+
+## Guides (How-To)
+
+- [Memory and Learnings](guides/memory-and-learnings.md)
+- [Troubleshooting](guides/troubleshooting.md)
+- [Writing Custom Roles](guides/writing-custom-roles.md) _(coming soon)_
+- [Creating Skills](guides/creating-skills.md) _(coming soon)_
+- [Expertise Module Authoring](guides/expertise-module-authoring.md) _(coming soon)_
+- [CI Integration](guides/ci-integration.md) _(coming soon)_
+- [Hook Development](guides/hook-development.md) _(coming soon)_
+- [Multi-Host Export](guides/multi-host-export.md) _(coming soon)_
+
+## Reference (Lookup)
+
+- [CLI Reference](reference/tooling-cli.md)
+- [Configuration Reference](reference/configuration-reference.md)
+- [Roles Reference](reference/roles-reference.md)
+- [Hooks Reference](reference/hooks.md)
+- [Expertise Index](reference/expertise-index.md)
+- [Skills Reference](reference/skills.md)
+- [Templates Reference](reference/templates.md)
+- [Host Exports Reference](reference/host-exports.md)
+- [Git-Flow Policy](reference/git-flow.md)
+- [Release Process](reference/release-process.md)

package/docs/adapters/context-mode.md

@@ -0,0 +1,60 @@
+# context-mode Adapter
+
+Status: implemented (optional, config-driven).
+
+## Position
+
+Wazir does not depend on `context-mode` for default operation. All built-in indexing, recall, capture, and hook surfaces stand on their own without this adapter.
+
+When enabled via init-time configuration, the adapter provides:
+
+1. **Researcher bridging** — the researcher role prefers `fetch_and_index` over WebFetch for external documentation. Fetched docs become searchable via FTS5 across all phases.
+2. **File read bridging** — large artifact reads can route through `execute_file` so raw content stays in the sandbox, only summaries enter context.
+3. **Stats collection** — `ctx_stats` data is read at compaction and session-end, recorded in `usage.json` for savings reporting.
+
+## Configuration
+
+Enabled during project setup:
+
+```json
+{
+  "context_mode": { "enabled": true }
+}
+```
+
+Stored in `~/.wazir/projects/<project-slug>/config.json`.
+
+## Adapter API
+
+Module: `tooling/src/adapters/context-mode.js` (pure functions, no side effects)
+
+| Function | Returns when enabled | Returns when disabled |
+|----------|---------------------|----------------------|
+| `isEnabled(config)` | `true` | `false` |
+| `bridgeResearcherFetch(config, url, source)` | `{ tool, args }` hint | `null` |
+| `bridgeFileRead(config, path, intent)` | `{ tool, args }` hint | `null` |
+| `collectStats(config)` | `{ should_collect, tool, args }` | `null` |
+
+## Constraints
+
+- External only, opt-in only, lazy-loaded
+- Must not block install, test, or normal CLI use when absent
+- All functions return `null` on any failure — never throw
+- `WAZIR_DISABLE_CONTEXT_MODE=1` overrides config to force-disable
+
+## Bridged Tools (2 of 9)
+
+| Tool | Bridge Function | Purpose |
+|------|----------------|---------|
+| `fetch_and_index` | `bridgeResearcherFetch` | Researcher fetches docs + indexes for FTS5 search |
+| `execute_file` | `bridgeFileRead` | Large file reads processed in sandbox |
+
+The remaining 7 context-mode tools (`execute`, `batch_execute`, `index`, `search`, `stats`, `doctor`, `upgrade`) operate independently via context-mode's own hooks.
+
+## Hook Interaction
+
+Context-mode hooks (Claude Code hook system) fire BEFORE Wazir CLI commands:
+1. context-mode PreToolUse may redirect WebFetch to fetch_and_index
+2. Wazir captures the RESULT of whatever tool actually executed
+
+Wazir's `usage.json` records savings regardless of which tool ran.

package/docs/concepts/architecture.md

@@ -0,0 +1,87 @@
+# Architecture
+
+Wazir is a host-native engineering OS kit. The host environment (Claude, Codex, Gemini, Cursor) remains the execution container. Wazir supplies the operating model, guardrails, and artifact contracts.
+
+## Core components
+
+| Component | Purpose |
+|-----------|---------|
+| Roles | Canonical contracts defining what each agent role does and produces |
+| Workflows | Phase entrypoints that sequence roles through delivery |
+| Skills | Reusable procedures (wz:tdd, wz:debugging, wz:verification, wz:brainstorming) |
+| Hooks | Guardrails enforcing protected paths, loop caps, and capture routing |
+| Expertise | 308 curated knowledge modules composed into agent prompts |
+| Templates | Artifact templates for phase outputs and handoff |
+| Schemas | Validation schemas for manifest, hooks, artifacts, and exports |
+| Exports | Generated host packages tailored per supported host |
+| Tooling | CLI for validation, indexing, recall, capture, and status |
+
+## Design influences
+
+| Source | What Wazir keeps |
+|--------|----------------------|
+| Wazir skill system | Disciplined workflows, TDD, verification, review rigor, skill ergonomics |
+| Spec-Kit | Spec-first development, explicit artifacts, approval gates |
+| Oh My Claude | Host-native prompt structure and operator ergonomics |
+| autoresearch | Research loops, experiment tracking, self-improvement discipline |
+
+## Context and indexing
+
+Wazir ships a built-in local index and recall surface that reduces context window consumption by 60-80% on exploration-heavy phases.
+
+### Context tiers
+
+| Tier | Token budget | Content | When to use |
+|------|-------------|---------|-------------|
+| L0 | ~100 tokens | One-line identifier (name, kind, language, line range) | Inventory scans, deciding what to load |
+| L1 | ~500-2k tokens | Structural summary (signature, fields, purpose, dependencies) | Understanding shape without full source |
+| L2 | Full content | Exact line-bounded source slice | Implementation, debugging, code review |
+
+### Role-specific recall defaults
+
+Roles are assigned default tiers based on their information needs:
+
+- **Exploration roles** (clarifier, researcher, specifier, content-author, designer, planner) default to L1 -- they need to understand structure across many files without reading every line
+- **Implementation roles** (executor, verifier) default to direct read (L2) -- they need exact source for code changes and verification
+- **Review role** (reviewer) starts at L1 as a triage pass, escalating to direct read only for logic errors, security concerns, or ambiguous summaries
+- **Learning role** (learner) defaults to L0 -- it needs only inventory-level context to identify what changed
+
+Every role includes a fallback chain: if the preferred tier fails (no index, no summaries), the role falls back to direct file reads. The system degrades gracefully -- no wasted tokens on failed index operations.
+
+### Capture routing
+
+Large tool output is routed to run-local files via `wazir capture route` and `wazir capture output`, keeping the context window lean. The agent receives a file path reference (~50 tokens) instead of the full output.
+
+### Pipeline integration points
+
+The index and recall surface integrates with the pipeline at five points:
+
+1. **Session start** -- the bootstrap hook runs `index refresh` (or `build` for first run) to ensure the index is current
+2. **Scan project** -- the `scan-project` skill runs `index stats` to report index health in the project profile
+3. **Debugging** -- the `wz:debugging` OBSERVE phase uses `index search-symbols` and `recall --tier L1` for symbol-first exploration
+4. **Execute** -- the executor uses `recall file` and `recall symbol` for targeted source reads
+5. **Verify** -- the verifier uses direct reads for full validation
+
+### Measuring savings
+
+`wazir capture usage` generates a per-run token savings report showing capture routing statistics and context window savings. This provides concrete evidence of token reduction per session.
+
+The context-mode integration remains an optional adapter -- off by default, never required for core install, build, or test paths.
+
+See [Indexing and Recall](indexing-and-recall.md) for full command details and extractor documentation.
+
+## Design Phase
+
+The design phase runs after specification and before planning. The `designer` role uses open-pencil MCP tools to produce visual designs from the approved spec. Outputs include a `.fig` design file, exported Tailwind JSX/HTML+CSS scaffolds, design tokens JSON, and screenshot PNGs.
+
+The `design-review` workflow validates designs against the spec before planning begins. The existing `review` workflow also checks design-vs-implementation alignment after execution.
+
+open-pencil is integrated as an optional adapter (`open_pencil`) — it is not required for core Wazir functionality.
+
+## Key references
+
+- [Roles & Workflows](roles-and-workflows.md)
+- [Artifact Model](artifact-model.md)
+- [Host Exports](../reference/host-exports.md)
+- [Hooks](../reference/hooks.md)
+- [Expertise & Antipatterns](composition-engine.md)

package/docs/concepts/artifact-model.md

@@ -0,0 +1,60 @@
+# Artifact Model
+
+Wazir separates operator input, committed repo artifacts, and live run state.
+
+## Human Truth
+
+- `input/` is the read-only operator briefing surface.
+
+## Default Live Run State
+
+Default run state lives outside the repo:
+
+- `~/.wazir/projects/<project-slug>/runs/<run-id>/`
+
+Typical run contents:
+
+- `manifest.json`
+- `sources.json`
+- phase subdirectories such as `clarify/`, `plan/`, `verify/`, `review/`
+- `status.json`
+- `events.ndjson`
+- `summary.md`
+
+## Committed Repo Artifacts
+
+Use `artifacts/` only for committed evidence such as:
+
+- release evidence
+- checked-in examples
+
+## Artifact Rules
+
+- every artifact should declare phase, role, run ID, timestamp, sources, status, and loop number
+- non-trivial claims must cite a source file, source URL, or verification command
+- approval-gated artifacts must record approval status and approver when relevant
+- scratch work must not be confused with durable artifacts
+- learnings belong in `memory/`, not in fresh-run source truth
+
+## Templates
+
+Canonical starting points live under:
+
+- `templates/artifacts/*.md`
+- `templates/artifacts/*.json`
+
+Those templates define the minimum metadata for clarification, research, specs, plan review, execution notes, verification, review, learning promotion, and next-run handoff artifacts.
+
+## Repo-Local Override
+
+Repo-local run state is opt-in only. If an operator deliberately uses a repo-local override, the recommended path is:
+
+- `.wazir-state/`
+
+That path must remain gitignored so a normal run still leaves `git status` clean.
+
+## Retention
+
+- keep committed `artifacts/` focused on release evidence and checked-in examples
+- archive stale or disproven learnings instead of rewriting history in place
+- prune external run-state captures when they no longer provide audit or debugging value

package/docs/concepts/composition-engine.md

@@ -0,0 +1,36 @@
+# Composition Engine
+
+Wazir uses a composition engine to assemble the right expertise into each role's context at each phase.
+
+## How expertise loading works
+
+- `clarify` and `discover` start from `input/`, active docs, and `docs/research/`
+- `specify` and `plan` pull only the expertise slices relevant to the stack and risks
+- `review` always considers `expertise/antipatterns/` before broader domain modules
+- `learn` can propose updates to expertise, but may not silently rewrite it
+
+## Anti-patterns first
+
+`expertise/antipatterns/` is first-class review input. It exists to catch:
+
+- fake completion
+- unwired abstractions
+- shallow tests
+- security theater
+- architecture drift
+- AI-coding failure modes
+
+Anti-patterns are loaded into reviewer context before any other domain modules. This ordering ensures that known failure modes are the first lens through which review happens.
+
+## Why scoped loading matters
+
+Brute-force loading of all expertise modules would flood the context window. The composition engine resolves which modules to load based on the task's declared stack and concerns, keeping context tight and relevant. Max 15 modules per dispatch, with token budget enforcement.
+
+## Source material
+
+- Research findings: `docs/research/`
+- Expertise modules: `expertise/`
+- Anti-pattern catalog: `expertise/antipatterns/`
+- Expertise metadata: `expertise/index.yaml`
+
+For the complete module listing and anti-pattern catalog, see the [Expertise Index reference](../reference/expertise-index.md).

package/docs/concepts/indexing-and-recall.md

@@ -0,0 +1,160 @@
+# Indexing and Recall
+
+Wazir ships a built-in local indexer so context reduction does not depend on an external commercial tool.
+
+## Current implementation
+
+- storage engine: built-in `node:sqlite`
+- index location: `<state-root>/index/index.sqlite`
+- default state root: `~/.wazir/projects/{project_slug}`
+- override: `--state-root <path>`
+- refresh model: hash-based incremental refresh
+- retrieval model: exact file slices and symbol slices read back from the working tree
+
+## Context tiers
+
+Wazir supports three context tiers for recall, enabling token-efficient context loading:
+
+| Tier | Target size | Content | Use case |
+| --- | --- | --- | --- |
+| L0 | ~100 tokens | One-line identifier summary (name, kind, language, line range) | Inventory scans, bulk listing, deciding what to load |
+| L1 | ~500-2k tokens | Structural summary (signature, key fields, purpose, dependencies) | Understanding shape and role without full source |
+| L2 | Full content | Exact line-bounded source slice | Implementation details, debugging, code review |
+
+L2 is the default recall behavior (exact slices). L0 and L1 require summaries to be generated first via `index summarize`.
+
+## Summary generation
+
+The `wazir index summarize` command generates L0 and L1 heuristic summaries for all indexed files and symbols.
+
+```
+wazir index summarize [--state-root <path>] [--refresh]
+```
+
+- Generates summaries for every file and symbol currently in the index
+- Summaries are stored in the index database alongside the source metadata
+- The `--refresh` flag regenerates summaries even if they already exist
+- Summary generation is heuristic-based (no external LLM calls required)
+- Each summary records the content hash at generation time for freshness checking
+
+## Tiered recall
+
+The `--tier` flag on `recall file` and `recall symbol` switches from full-content (L2) recall to summary recall:
+
+```
+wazir recall file <path> --tier L0
+wazir recall file <path> --tier L1
+wazir recall symbol <name> --tier L0
+wazir recall symbol <name> --tier L1
+```
+
+- `--tier` is mutually exclusive with `--start`/`--end` line-range options
+- When `--tier` is specified, the response includes the summary text and a `fresh` field
+- Without `--tier`, recall behaves exactly as before (L2 exact slices)
+
+## Freshness checking
+
+When summaries are recalled via `--tier`, the response includes a `fresh` boolean field:
+
+- `fresh: true` -- the content hash at summary generation time matches the current file hash on disk
+- `fresh: false` -- the file has been modified since the summary was generated; the summary may be stale
+
+Consumers should treat stale summaries as approximate and consider re-running `index summarize --refresh` or falling back to L2 recall for critical decisions.
+
+## Pipeline integration
+
+The index and recall surface integrates with the Wazir pipeline at multiple points:
+
+- **Session start** -- the session-start hook runs `index refresh` (or `index build` for first run) as part of the 3-step CLI bootstrap
+- **Scan project** -- the `scan-project` skill runs `index stats` to report index health in the project profile
+- **Debugging** -- the `wz:debugging` OBSERVE phase uses `index search-symbols` and `recall --tier L1` for symbol-first exploration before targeted source reads
+- **Execution** -- the executor uses `recall file` and `recall symbol` for targeted source access
+- **Verification** -- the verifier uses direct reads for full validation
+
+Each role has a default recall tier. See [Roles Reference -- Context retrieval defaults](../reference/roles-reference.md#context-retrieval-defaults) for the full table.
+
+## Current commands
+
+Implemented now:
+
+- `wazir index build`
+- `wazir index refresh`
+- `wazir index stats`
+- `wazir index summarize`
+- `wazir index search-symbols`
+- `wazir index get-symbol`
+- `wazir index get-file-outline`
+- `wazir recall file`
+- `wazir recall symbol`
+
+Reserved for later host/runtime work:
+
+- adapter-backed summary generation (LLM-powered summaries via optional adapters)
+- directory-level summaries (roll up file summaries into directory-level context)
+- adapter activation flows
+- richer parser inventories
+
+## Extractor coverage
+
+The current core extractor roster is heuristic and built in-repo:
+
+- `builtin-heuristic-javascript`
+- `builtin-heuristic-typescript`
+- `builtin-heuristic-python`
+- `builtin-heuristic-go`
+- `builtin-heuristic-rust`
+- `builtin-heuristic-java`
+- `builtin-heuristic-sql`
+- `builtin-heuristic-json`
+- `builtin-heuristic-yaml`
+- `builtin-heuristic-markdown`
+
+Behavior:
+
+- supported files get file metadata, hashes, outlines, and best-effort symbol extraction
+- unsupported text files can still be added later, but should not claim symbol precision they do not provide
+- markdown headings and top-level structured keys are first-class outline targets
+
+## Output model
+
+The index stores:
+
+- files
+- symbols
+- outlines
+- hashes
+- ingestion runs
+- retrieval logs
+
+Recall returns:
+
+- exact line-bounded slice
+- exact source path
+- exact line start and line end
+- optional surrounding context window
+
+## Ignore and hygiene rules
+
+The built-in index currently skips common non-source or generated trees such as:
+
+- `.git/`
+- `.worktrees/`
+- `node_modules/`
+- `dist/`
+- `build/`
+- `coverage/`
+- `.next/`
+
+If the chosen state root lives inside the repo, Wazir skips indexing that path so it does not index its own artifacts.
+
+## Adapter stance
+
+The built-in index is the default and required path.
+
+The optional `context-mode` adapter remains:
+
+- disabled by default
+- external
+- non-required for default install or test paths
+
+See the adapter docs for current status and constraints.

package/docs/concepts/observability.md

@@ -0,0 +1,41 @@
+# Observability
+
+Wazir observability is file-based and host-native. All observability requires no external services.
+
+## Current observability surfaces
+
+Implemented now:
+
+- `wazir status --run <id> [--json]`
+- canonical hook definitions for status, capture, compaction, and handoff events
+- external state-root policy for run-local files
+- `wazir capture init` for `status.json` and `events.ndjson` bootstrap
+- `wazir capture event` for event append and status updates
+- `wazir capture route` and `wazir capture output` for large-output artifact capture
+- `wazir capture summary` for `summary.md` and stop-time or compaction summaries
+
+Planned next:
+
+- host-specific native-hook or wrapper wiring that calls the capture commands automatically
+
+## Current status path
+
+The status command reads:
+
+- `<state-root>/runs/<run-id>/status.json`
+
+Use `--state-root <path>` to target a fixture or non-default state location.
+
+The capture command family writes under:
+
+- `<state-root>/runs/<run-id>/status.json`
+- `<state-root>/runs/<run-id>/events.ndjson`
+- `<state-root>/runs/<run-id>/summary.md`
+- `<state-root>/runs/<run-id>/captures/*`
+
+## Design rules
+
+- run-local observability lives outside the repo by default
+- machine-readable status must exist without any server
+- captured output should reduce context flooding, not increase it
+- summaries must point back to captured files instead of pretending the full output stayed in context

package/docs/concepts/roles-and-workflows.md

@@ -0,0 +1,59 @@
+# Roles and Workflows
+
+Wazir defines explicit canonical roles and explicit phase workflows. Understanding why these exist and how they interact is key to using the system effectively.
+
+## Why roles?
+
+Roles are isolation boundaries, not personas. Each role 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.
+
+Separating concerns into roles means that the entity implementing a task is never the same entity reviewing it. This adversarial separation is what makes quality enforcement structural rather than aspirational.
+
+## Why phases?
+
+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 via conversation history. A session can end, a new agent can pick up the artifacts, and delivery continues — because the handoff is explicit, structured, and schema-validated.
+
+## The phase model
+
+The canonical workflow sequence is:
+
+1. **clarify** — resolve ambiguity before committing to a spec
+2. **discover** — gather research and prior art
+3. **specify** — produce a measurable spec with acceptance criteria
+4. **spec-challenge** — adversarial review of the spec
+5. **author** — finalize content, microcopy, and i18n keys
+6. **design** — produce visual designs from the approved spec
+7. **design-review** — validate designs against spec, accessibility, and visual consistency
+8. **plan** — create an implementation plan from the approved spec and designs
+9. **plan-review** — adversarial review of the plan
+10. **execute** — implement the plan
+11. **verify** — QA hard gate with fresh proof
+12. **review** — adversarial quality review
+13. **learn** — capture scoped learnings
+14. **prepare-next** — produce a clean handoff for the next run
+
+## Role routing
+
+The orchestrator dispatches three roles per task: `executor`, `reviewer`, and `verifier`. By default, all three run for every task. The `required_roles` field in a task's YAML frontmatter controls which roles are dispatched, allowing the orchestrator to skip unnecessary roles and save context window budget.
+
+### Auto-detection
+
+The clarifier assigns `required_roles` based on task type:
+
+| Task type | Required roles | Rationale |
+|-----------|---------------|-----------|
+| `feature` | `[executor, reviewer, verifier]` | Full pipeline |
+| `bugfix` | `[executor, reviewer, verifier]` | Full pipeline |
+| `refactor` | `[executor, reviewer, verifier]` | Full pipeline |
+| `docs` | `[executor, verifier]` | No adversarial review needed |
+| `config` | `[executor, verifier]` | No adversarial review needed |
+
+If `security_critical: true`, `reviewer` is always included.
+
+### Constraints
+
+- `verifier` is always present — it is the QA hard gate and cannot be removed
+- Default when `required_roles` is absent: `[executor, reviewer, verifier]` (backward compatible)
+
+## Canonical source
+
+Use the files under `roles/` and `workflows/` as the canonical source for role contracts and phase entrypoints. For exact role and workflow tables, see the [Roles Reference](../reference/roles-reference.md).

package/docs/concepts/terminology-policy.md

@@ -0,0 +1,27 @@
+# Wazir Brand and Terminology Guide
+
+## Canonical Terms
+
+Use these terms in all product surfaces:
+
+- Wazir
+- host-native engineering OS kit
+- roles
+- workflows
+- skills
+- hooks
+- templates
+- schemas
+- research
+- memory
+- host exports
+
+## Terms That Do Not Describe This Product
+
+Do not use terms that describe Wazir as a background service, a web-based control surface, or a long-running process. The product is a host-native kit, and all terminology should reflect that.
+
+## Rules
+
+- Wazir is a host-native engineering OS kit, not a server or background service.
+- Use the canonical terms above in all roles, workflows, skills, and documentation.
+- When in doubt, describe what Wazir is, not what it is not.