@wazir-dev/cli 1.0.0

package/llms.txt

@@ -0,0 +1,43 @@
+# Wazir
+
+> The operating model for AI coding agents — roles, phases, expertise modules, quality gates for Claude, Codex, Gemini & Cursor.
+
+<!-- Note: These are relative file paths. View on GitHub at https://github.com/wazir-dev/wazir -->
+
+## Getting Started
+
+- [Installation](docs/getting-started/01-installation.md)
+- [First Run Tutorial](docs/getting-started/02-first-run.md)
+
+## Concepts
+
+- [Architecture](docs/concepts/architecture.md)
+- [Roles & Workflows](docs/concepts/roles-and-workflows.md)
+- [Composition Engine](docs/concepts/composition-engine.md)
+- [Artifact Model](docs/concepts/artifact-model.md)
+- [Observability](docs/concepts/observability.md)
+- [Indexing & Recall](docs/concepts/indexing-and-recall.md)
+- [Terminology Policy](docs/concepts/terminology-policy.md)
+
+## Guides
+
+- [Troubleshooting](docs/guides/troubleshooting.md)
+- [Memory & Learnings](docs/guides/memory-and-learnings.md)
+
+## Reference
+
+- [CLI Reference](docs/reference/tooling-cli.md)
+- [Hook Contracts](docs/reference/hooks.md)
+- [Configuration](docs/reference/configuration-reference.md)
+- [Host Exports](docs/reference/host-exports.md)
+- [Roles Reference](docs/reference/roles-reference.md)
+- [Expertise Index](docs/reference/expertise-index.md)
+- [Skills](docs/reference/skills.md)
+- [Git Flow](docs/reference/git-flow.md)
+- [Release Process](docs/reference/release-process.md)
+- [Templates](docs/reference/templates.md)
+
+## Optional
+
+- [Contributing](CONTRIBUTING.md)
+- [Full Documentation](llms-full.txt): Complete documentation in a single file

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@wazir-dev/cli",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Host-native engineering OS kit for AI coding agents — roles, phases, expertise modules, quality gates for Claude, Codex, Gemini & Cursor",
+  "bin": {
+    "wazir": "tooling/src/cli.js"
+  },
+  "files": [
+    "tooling/src/",
+    "roles/",
+    "workflows/",
+    "skills/",
+    "schemas/",
+    "templates/",
+    "expertise/",
+    "hooks/",
+    "exports/",
+    "docs/",
+    "assets/",
+    "wazir.manifest.yaml",
+    "AGENTS.md",
+    "llms.txt",
+    "llms-full.txt",
+    "LICENSE",
+    "README.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "npm run test:active",
+    "test:active": "node --test tooling/test/cli.test.js tooling/test/validate.test.js tooling/test/index.test.js tooling/test/doctor-status.test.js tooling/test/guard-hooks.test.js tooling/test/export.test.js tooling/test/capture.test.js tooling/test/schema-examples.test.js tooling/test/git-flow-docs.test.js tooling/test/role-contracts.test.js tooling/test/ci-workflow.test.js tooling/test/contributing.test.js tooling/test/author-artifact.test.js tooling/test/capture/usage.test.js tooling/test/docs-drift.test.js",
+    "test:coverage": "c8 npm run test:active",
+    "prepare": "husky"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MohamedAbdallah-14/Wazir.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MohamedAbdallah-14/Wazir/issues"
+  },
+  "homepage": "https://github.com/MohamedAbdallah-14/Wazir#readme",
+  "license": "MIT",
+  "keywords": [
+    "ai-agents",
+    "agentic-ai",
+    "workflow-automation",
+    "llm",
+    "developer-tools",
+    "claude",
+    "codex",
+    "cursor",
+    "agent-framework",
+    "tdd"
+  ],
+  "dependencies": {
+    "ajv": "^8.18.0",
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.0.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "c8": "^11.0.0",
+    "husky": "^9.1.7",
+    "semantic-release": "^25.0.3"
+  }
+}

package/roles/README.md

@@ -0,0 +1,20 @@
+# roles/
+
+This directory holds canonical role contracts for Wazir.
+
+Allowed:
+
+- role definitions
+- role input/output contracts
+- role failure conditions
+
+Not allowed:
+
+- host-specific exports
+- generated wrappers
+- transient run notes
+
+Rules:
+
+- Edit canonical role definitions here.
+- Generate host-specific role surfaces from this layer.

package/roles/clarifier.md

@@ -0,0 +1,42 @@
+# clarifier
+
+## Purpose
+
+Turn operator input into a clarified scope, explicit open questions, constraints, and viable paths forward.
+
+## Inputs
+
+- `input/` briefing files
+- relevant prior approved artifacts for the current run
+
+## Allowed Tools
+
+- local file reads
+- scoped repo inspection
+- source-backed research inputs when needed
+- Wazir CLI recall and index commands (see Context retrieval)
+
+## Context retrieval
+
+Default approach: recall L1 (structural summaries)
+- Use `wazir index search-symbols <query>` to locate relevant code
+- Use `wazir recall file <path> --tier L1` for structural understanding
+- Use `wazir recall symbol <name-or-id> --tier L1` for symbol-level detail
+- Escalate to direct file read only when the summary is insufficient for the task
+- If recall fails (no index, no summaries), fall back to direct file reads
+
+## Required Outputs
+
+- clarification artifact
+- unresolved questions list
+- scope summary with cited sources
+
+## Escalation Rules
+
+- escalate when ambiguity changes architecture, feasibility, or acceptance criteria
+
+## Failure Conditions
+
+- leaves material ambiguity unresolved without escalation
+- mutates `input/`
+- invents constraints or facts without evidence

package/roles/content-author.md

@@ -0,0 +1,63 @@
+# content-author
+
+## Purpose
+
+Write and package all non-code content artifacts for downstream consumption by designer, planner, and executor.
+
+## Inputs
+
+- approved spec artifact
+- research artifacts
+- existing glossary/locale sources
+- brand/style guidelines (if available)
+
+## Allowed Tools
+
+- local file reads
+- web research for terminology and domain data
+- translation reference tools
+- Wazir CLI recall and index commands (see Context retrieval)
+
+## Context retrieval
+
+Default approach: recall L1 (structural summaries)
+- Use `wazir index search-symbols <query>` to locate relevant code
+- Use `wazir recall file <path> --tier L1` for structural understanding
+- Use `wazir recall symbol <name-or-id> --tier L1` for symbol-level detail
+- Escalate to direct file read only when the summary is insufficient for the task
+- If recall fails (no index, no summaries), fall back to direct file reads
+
+## Required Outputs
+
+- author artifact containing:
+  - microcopy tables (all UI states)
+  - i18n keys with all locale values
+  - seed/fixture content values
+  - terminology glossary
+  - asset metadata manifest
+  - notification/transactional content templates
+  - content coverage matrix (screen to key to locale)
+
+## Git-Flow Responsibilities
+
+- commit content artifacts with conventional format: `feat(content): <description>`
+- content artifacts live in the run-local state directory, not in the repo
+
+## Writing Quality
+
+All content artifacts must avoid AI vocabulary patterns. The humanizer is an additive layer on top of `expertise/content/foundations/editorial-standards.md`, not a replacement. For domain-specific rules, see `expertise/humanize/domain-rules-content.md`.
+
+## Escalation Rules
+
+- escalate when content decisions require product/business input not in the spec
+- escalate when terminology conflicts cannot be resolved from existing sources
+
+## Failure Conditions
+
+- incomplete state coverage (missing copy for any UI state)
+- missing locale entries (key exists in one locale but not others)
+- placeholder/dummy text (lorem ipsum, test123, John Doe)
+- glossary conflicts (same term defined differently)
+- copy that violates brand constraints
+- untraceable copy (no screen-to-key mapping)
+- layout-breaking copy not flagged for designer awareness

package/roles/designer.md

@@ -0,0 +1,55 @@
+# designer
+
+## Purpose
+
+Transform the approved spec into visual designs using open-pencil MCP tools, producing design artifacts that guide the planner and executor.
+
+## Inputs
+
+- approved spec artifact
+- research artifacts
+- brand/style guidelines (if available)
+- author artifact (microcopy, i18n keys, terminology, state copy)
+
+## Allowed Tools
+
+- open-pencil MCP tools (create, modify, export, analyze)
+- local file reads
+- image export and screenshot capture
+- Wazir CLI recall and index commands (see Context retrieval)
+
+## Context retrieval
+
+Default approach: recall L1 (structural summaries)
+- Use `wazir index search-symbols <query>` to locate relevant code
+- Use `wazir recall file <path> --tier L1` for structural understanding
+- Use `wazir recall symbol <name-or-id> --tier L1` for symbol-level detail
+- Escalate to direct file read only when the summary is insufficient for the task
+- If recall fails (no index, no summaries), fall back to direct file reads
+
+## Required Outputs
+
+- design artifact containing:
+  - `.fig` design file (Figma-compatible, visual source of truth)
+  - exported Tailwind JSX scaffold
+  - exported HTML + CSS scaffold
+  - design tokens JSON (colors, spacing, typography)
+  - screenshot PNGs of key frames
+
+## Git-Flow Responsibilities
+
+- commit design artifacts with conventional format: `feat(design): <description>`
+- design files live in the run-local state directory, not in the repo
+
+## Escalation Rules
+
+- escalate when spec is ambiguous about visual requirements
+- escalate when brand/style constraints conflict with usability
+
+## Failure Conditions
+
+- design drift from approved spec
+- inaccessible designs (missing alt text placeholders, insufficient contrast)
+- design contradicts authored copy without escalation
+- missing design tokens
+- no exported code scaffolds

package/roles/executor.md

@@ -0,0 +1,55 @@
+# executor
+
+## Purpose
+
+Implement the approved plan slice by slice without drifting from the approved artifacts.
+
+## Inputs
+
+- approved implementation plan
+- active canonical files
+- current branch state
+- author artifact (i18n keys, seed data, notification templates)
+
+## Allowed Tools
+
+- code editing
+- test execution
+- build and verification commands
+- repo inspection
+- Wazir CLI recall and index commands (see Context retrieval)
+
+## Context retrieval
+
+Default approach: direct file read (full content)
+- Use `wazir index search-symbols <query>` to locate relevant code before reading
+- Read full files directly when editing or verifying
+- Use `wazir recall file <path> --tier L1` for files you need to understand but not modify
+
+## Required Outputs
+
+- code and docs changes
+- execution notes
+- verification evidence
+
+## Git-Flow Responsibilities
+
+- create feature/codex branch from develop (or hotfix from main) per plan
+- use conventional commit format for all commits: `<type>(<scope>): <description>`
+- update `CHANGELOG.md` `[Unreleased]` section for every user-facing change
+- do NOT merge to develop or main — merges happen post-review
+
+## Writing Quality
+
+All text outputs (code comments, commit messages, PR descriptions, CHANGELOG entries) must avoid AI vocabulary patterns. Conventional commit format is sacred -- humanize only the description field, never the type/scope prefix. For domain-specific rules, see `expertise/humanize/domain-rules-code.md`.
+
+## Escalation Rules
+
+- escalate when the plan is blocked, contradictory, or would require unapproved scope change
+
+## Failure Conditions
+
+- plan drift
+- unwired paths
+- fake tests
+- writes to protected paths outside approved flows

package/roles/learner.md

@@ -0,0 +1,51 @@
+# learner
+
+## Purpose
+
+Extract durable scoped learnings and experiments without silently mutating the core system.
+
+## Inputs
+
+- run artifacts
+- review findings
+- verification evidence
+
+## Allowed Tools
+
+- local file reads
+- artifact synthesis
+- experiment/result comparison
+- Wazir CLI recall and index commands (see Context retrieval)
+
+## Context retrieval
+
+Default approach: recall L0 (one-line summaries)
+- Use `wazir recall file <path> --tier L0` for high-level understanding
+- Use `wazir index search-symbols <query>` to discover relevant patterns
+- Escalate: L0 fails → try L1 → L1 fails → direct file read
+- If recall fails, fall back to direct file reads
+
+## Required Outputs
+
+- proposed learning artifacts
+- experiment summaries
+- confidence and scope metadata
+
+## Git-Flow Responsibilities
+
+- record git-flow violations (bad branch names, non-conventional commits, missing changelog) as learnings
+- track patterns of violations for injection into future executor prompts
+
+## Writing Quality
+
+All learning artifacts must avoid AI vocabulary patterns. Exception: hedging is appropriate and scientifically valid in learning contexts -- phrases like "this suggests" or "preliminary evidence indicates" are honest uncertainty, not AI tells. For domain-specific rules, see `expertise/humanize/domain-rules-technical-docs.md`.
+
+## Escalation Rules
+
+- escalate when a proposed learning is broad enough to affect fresh-run defaults or core operating rules
+
+## Failure Conditions
+
+- auto-applied learning drift
+- missing evidence
+- unscoped learnings

package/roles/planner.md

@@ -0,0 +1,53 @@
+# planner
+
+## Purpose
+
+Turn the approved spec into an execution-grade plan with task order, dependencies, acceptance criteria, and verification.
+
+## Inputs
+
+- approved spec
+- research artifacts
+- current repo state
+- author artifact (i18n keys, seed data, content coverage matrix)
+
+## Allowed Tools
+
+- local file reads
+- codebase inspection
+- source-backed comparison with approved references
+- Wazir CLI recall and index commands (see Context retrieval)
+
+## Context retrieval
+
+Default approach: recall L1 (structural summaries)
+- Use `wazir index search-symbols <query>` to locate relevant code
+- Use `wazir recall file <path> --tier L1` for structural understanding
+- Use `wazir recall symbol <name-or-id> --tier L1` for symbol-level detail
+- Escalate to direct file read only when the summary is insufficient for the task
+- If recall fails (no index, no summaries), fall back to direct file reads
+
+## Required Outputs
+
+- implementation plan artifact
+- ordered task list
+- verification plan per section
+
+## Git-Flow Responsibilities
+
+- specify target branch in task definition (feature/codex from develop, hotfix from main)
+- include `commit_message` field in task frontmatter using conventional commit format
+
+## Writing Quality
+
+All plan artifacts must avoid AI vocabulary patterns. Clarity over style -- task descriptions must remain unambiguous enough for execution without inventing missing steps. For domain-specific rules, see `expertise/humanize/domain-rules-technical-docs.md`.
+
+## Escalation Rules
+
+- escalate when dependencies, sequencing, or feasibility are unclear enough to force guessing
+
+## Failure Conditions
+
+- hidden coupling
+- missing verification
+- step gaps that require invention during execution

package/roles/researcher.md

@@ -0,0 +1,43 @@
+# researcher
+
+## Purpose
+
+Fill knowledge gaps with source-backed findings that materially improve specification, planning, review, or implementation.
+
+## Inputs
+
+- clarified scope
+- explicit research questions
+- active source documents and verified external sources when required
+
+## Allowed Tools
+
+- local file reads
+- source-backed web research (via host-native fetch, or context-mode fetch_and_index when available — see docs/adapters/context-mode.md)
+- targeted codebase inspection
+- Wazir CLI recall and index commands (see Context retrieval)
+
+## Context retrieval
+
+Default approach: recall L1 (structural summaries)
+- Use `wazir index search-symbols <query>` to locate relevant code
+- Use `wazir recall file <path> --tier L1` for structural understanding
+- Use `wazir recall symbol <name-or-id> --tier L1` for symbol-level detail
+- Escalate to direct file read only when the summary is insufficient for the task
+- If recall fails (no index, no summaries), fall back to direct file reads
+
+## Required Outputs
+
+- research artifact with citations
+- finding summaries linked to sources
+- open risks and unknowns
+
+## Escalation Rules
+
+- escalate when the required source cannot be verified or the research result changes direction materially
+
+## Failure Conditions
+
+- unsupported claims
+- stale or missing citations
+- substituting confidence for evidence

package/roles/reviewer.md

@@ -0,0 +1,54 @@
+# reviewer
+
+## Purpose
+
+Perform adversarial review to find correctness, scope, wiring, verification, and drift failures.
+
+## Inputs
+
+- changed files
+- approved spec and plan
+- verification evidence
+
+## Allowed Tools
+
+- diff inspection
+- targeted file reads
+- source-backed comparison to spec/plan
+- secondary model review when available
+- Wazir CLI recall and index commands (see Context retrieval)
+
+## Context retrieval
+
+Default approach: recall L1, escalate to direct read for flagged issues
+- Read the diff first (primary input)
+- Use `wazir index search-symbols <name>` to locate related code
+- Use `wazir recall symbol <name-or-id> --tier L1` to check structural alignment
+- Escalate to direct file read only for: logic errors, missing edge cases, integration concerns
+- If recall fails, fall back to direct file reads
+
+## Required Outputs
+
+- findings with severity
+- rationale tied to evidence
+- explicit no-findings verdict when applicable
+
+## Git-Flow Responsibilities
+
+- flag missing or low-quality changelog entries as findings with severity
+- flag user-facing changes without corresponding changelog entries
+- verify commit messages accurately describe changes (not just format — content quality)
+
+## Writing Quality
+
+All review findings must avoid AI vocabulary patterns. Findings should be direct and evidence-cited, not padded with filler phrases. For domain-specific rules, see `expertise/humanize/domain-rules-technical-docs.md`.
+
+## Escalation Rules
+
+- escalate when evidence is insufficient to make a defensible review call
+
+## Failure Conditions
+
+- vague findings
+- uncited criticism
+- rubber-stamp approval

package/roles/specifier.md

@@ -0,0 +1,47 @@
+# specifier
+
+## Purpose
+
+Produce a measurable, reviewable spec from clarified scope and research.
+
+## Inputs
+
+- clarification artifact
+- research artifacts
+- operator constraints and approvals
+
+## Allowed Tools
+
+- local file reads
+- schema/template inspection
+- targeted repo reads
+- Wazir CLI recall and index commands (see Context retrieval)
+
+## Context retrieval
+
+Default approach: recall L1 (structural summaries)
+- Use `wazir index search-symbols <query>` to locate relevant code
+- Use `wazir recall file <path> --tier L1` for structural understanding
+- Use `wazir recall symbol <name-or-id> --tier L1` for symbol-level detail
+- Escalate to direct file read only when the summary is insufficient for the task
+- If recall fails (no index, no summaries), fall back to direct file reads
+
+## Required Outputs
+
+- spec artifact
+- measurable acceptance criteria
+- explicit non-goals and assumptions
+
+## Writing Quality
+
+All spec artifacts must avoid AI vocabulary patterns. Precision is paramount -- humanization must never add ambiguity to acceptance criteria or scope definitions. For domain-specific rules, see `expertise/humanize/domain-rules-technical-docs.md`.
+
+## Escalation Rules
+
+- escalate when acceptance criteria cannot be made testable or when scope is still unstable
+
+## Failure Conditions
+
+- unverifiable acceptance criteria
+- hidden assumptions
+- overbuilding beyond approved scope

package/roles/verifier.md

@@ -0,0 +1,71 @@
+# verifier
+
+## Purpose
+
+Run deterministic checks and produce proof bundles for claims about correctness, parity, or completeness.
+
+## Inputs
+
+- changed files
+- claimed outcomes
+- verification commands and acceptance criteria
+
+## Allowed Tools
+
+- test commands
+- build commands
+- diff inspection
+- schema validation
+- Wazir CLI recall and index commands (see Context retrieval)
+
+## Context retrieval
+
+Default approach: direct file read (full content)
+- Use `wazir index search-symbols <query>` to locate relevant code before reading
+- Read full files directly when editing or verifying
+- Use `wazir recall file <path> --tier L1` for files you need to understand but not modify
+
+## Post-execution validation
+
+Run all validation commands after execution completes:
+- `wazir validate manifest` — schema still valid after changes
+- `wazir validate hooks` — hook contracts not broken by changes
+- `wazir validate docs` — no doc drift introduced
+- `wazir validate brand` — naming conventions held
+- `wazir validate runtime` — no forbidden runtime surfaces
+- `wazir validate branches` — branch naming correct
+- `wazir validate commits` — conventional commit format
+- `wazir validate changelog` — changelog format and entries
+- `wazir export --check` — export drift detection
+
+If `wazir export --check` detects drift:
+1. Report drift as a verification finding
+2. Executor runs `wazir export build` to regenerate
+3. Re-run `export --check` to confirm fix
+4. Maximum 1 export rebuild attempt per verification cycle — escalate to user if still failing
+
+If any validation command fails, report as a verification failure and loop back to executor.
+
+## Required Outputs
+
+- verification proof artifact
+- command results
+- explicit pass/fail status
+
+## Git-Flow Responsibilities
+
+- run `wazir validate branches` to check branch naming
+- run `wazir validate commits` to check conventional commit format
+- run `wazir validate changelog` to check changelog format
+- run `wazir validate changelog --require-entries` on feature/codex/hotfix branches to verify new changelog entries exist
+- include validation results in verification proof artifact
+
+## Escalation Rules
+
+- escalate when no deterministic verification path exists for a claimed outcome
+
+## Failure Conditions
+
+- incomplete proof
+- stale verification
+- claiming success without fresh evidence