| name | wz:wazir |
| description | One-command pipeline — type /wazir followed by what you want to build. Handles init, clarification, execution, review, and audits automatically. |
Before anything else happens here: read your phase checklist. It's at .wazir/runs/latest/phases/. Every item on it is there because skipping it caused problems before. Are you going to follow it or skip it?
Wazir — Full Pipeline Runner
The user typed /wazir <their request>. Run the entire pipeline end-to-end, handling each phase automatically and only pausing where human input is required.
All questions use numbered interactive options — one question at a time, defaults marked "(Recommended)", wait for user response before proceeding.
User Input Capture
After every user response (approval, correction, rejection, redirect, instruction), capture it:
captureUserInput(runDir, { phase: '<current-phase>', type: '<instruction|approval|correction|rejection|redirect>', content: '<user message>', context: '<what prompted the question>' })
This uses tooling/src/capture/user-input.js. The log at user-input-log.ndjson feeds the learning system — user corrections are the strongest signal for improvement. At run end, prune logs older than 10 runs via pruneOldInputLogs(stateRoot, 10).
Command Routing
Follow the Canonical Command Matrix in hooks/routing-matrix.json.
- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
- Small commands (git status, ls, pwd, wazir CLI) → native Bash
- If context-mode unavailable, fall back to native Bash with warning
Codebase Exploration
- Query
wazir index search-symbols <query> first
- Use
wazir recall file <path> --tier L1 for targeted reads
- Fall back to direct file reads ONLY for files identified by index queries
- Maximum 10 direct file reads without a justifying index query
- If no index exists:
wazir index build && wazir index summarize --tier all
Subcommand Detection
Before anything else, check if the request starts with a known subcommand:
| Input | Action |
|---|
/wazir audit ... | Jump to Audit Mode (see below) |
/wazir prd [run-id] | Jump to PRD Mode (see below) |
/wazir init | Invoke the init-pipeline skill directly, then stop |
| Anything else | Continue to Phase 1 (Init) |
4-Phase Pipeline
The pipeline has 4 phases. Each phase groups related workflows. Individual workflows within a phase can be enabled/disabled via workflow_policy in run-config.
| Phase | Contains | Owner Skill | Key Output |
|---|
| Init | Setup, prereqs, run directory, input scan | wz:wazir (inline) | run-config.yaml |
| Clarifier | Research, clarify, specify, brainstorm, plan | wz:clarifier | Approved spec + design + plan |
| Executor | Implement, verify | wz:executor | Code + verification proof |
| Final Review | Integration verification, concern resolution, 2+1 pass review, learn, prepare next | wz:reviewer | Verdict + learnings + handoff |
Pre-Bootstrap: CLI + Init Check (MANDATORY BEFORE PHASE 0)
Before bootstrap, verify the Wazir CLI is installed:
which wazir
If not installed, check npm is available and auto-install:
which npm || { echo "npm not found — install Node.js 20+ first"; exit 1; }
npm install -g @wazir-dev/cli
After install, verify with which wazir. If install fails (permissions, no npm), ask the user for help — do not proceed without the CLI.
The CLI is required — the pipeline uses wazir capture, wazir validate, wazir index, and wazir doctor throughout execution.
Then check if this project is initialized:
wazir doctor --json
If doctor reports the project is not initialized (no .wazir/state/config.json), run:
wazir init
This creates state directories and detects the project's host and stack. It works in any project — no wazir.manifest.yaml needed.
Phase 0: Bootstrap (MANDATORY FIRST STEP)
After CLI check passes, run this command:
wazir capture ensure
This creates or resumes a pipeline run. Until this runs, you CANNOT write code — the bootstrap gate will block all Write/Edit/Bash calls. Please try 100% compliance with Wazir pipeline and skill usage.
Sync Task List From Phase Checklist
Immediately after wazir capture ensure, read the active phase checklist and populate your task list to match it exactly. This ensures your task list IS the pipeline — not a competing instruction set.
- Read the active phase file from
.wazir/runs/latest/phases/ (the file whose header contains — ACTIVE)
- Parse every unchecked item (lines matching
- [ ])
- Before creating tasks, call TaskList. If tasks already exist that match the phase checklist items, do not recreate them. If tasks exist that don't match the checklist (stale from a previous session or early agent behavior), they are stale — do not follow them. Create fresh tasks from the current phase checklist instead.
- For each unchecked item not already in the task list, call
TaskCreate with:
- subject: The checklist item text (strip the
- [ ] prefix and any <!-- ... --> comments)
- description: "Pipeline checklist item from the active phase"
- Do NOT create tasks for already-checked items (
- [x])
- Do NOT create your own tasks outside the phase checklist — the checklist is the complete task list
Why: The agent naturally follows its own task list. If that list matches the pipeline checklist, pipeline compliance happens automatically. If you create a separate task list, it competes with the pipeline and compliance drops.
Phase 1: Init
Before starting: Check .wazir/runs/latest/phases/init.md for your current checklist. Complete all items before proceeding to Phase 2.
Step 1: Capture the Request
Take whatever the user wrote after /wazir and save it as the briefing:
- Create
.wazir/input/ if it doesn't exist
- Write the user's request to
.wazir/input/briefing.md with a timestamp header
If the user provided no text after /wazir, ask:
What would you like to build?
Save their answer as the briefing, then continue.
Scan Input Directory
Scan both input/ (project-level) and .wazir/input/ (state-level) for existing briefing materials. If files exist beyond briefing.md, list them:
Found input files:
input/2026-03-19-deferred-items.md.wazir/input/briefing.md
Using all found input as context for clarification.
Inline Modifiers
Parse the request for inline modifiers before the main text:
/wazir quick fix the login redirect → depth = quick, intent = bugfix/wazir deep design a new onboarding flow → depth = deep, intent = feature
Recognized modifiers:
- Depth:
quick, deep (standard is default when omitted)
- Interaction mode:
auto, interactive (guided is default when omitted)
/wazir auto fix the auth bug → interaction_mode = auto/wazir interactive design the onboarding → interaction_mode = interactive
- Intent:
bugfix, feature, refactor, docs, spike
Step 2: Check Prerequisites
Config Check
Check if .wazir/state/config.json exists and has config_version: 2.
Run wazir doctor --json to verify repo health. Stop if unhealthy.
Branch Check
Run wazir validate branches to check the current git branch.
Index Check
INDEX_STATS=$(wazir index stats --json 2>/dev/null)
FILE_COUNT=$(echo "$INDEX_STATS" | jq -r '.file_count // 0')
if [ "$FILE_COUNT" -eq 0 ]; then
wazir index build && wazir index summarize --tier all
else
wazir index refresh
fi
Step 3: Create Run Directory
Generate a run ID using the current timestamp: run-YYYYMMDD-HHMMSS
mkdir -p .wazir/runs/run-YYYYMMDD-HHMMSS/{sources,tasks,artifacts,reviews,clarified}
ln -sfn run-YYYYMMDD-HHMMSS .wazir/runs/latest
Initialize event capture:
wazir capture init --run <run-id> --phase init --status starting
Resume Detection
Check if a previous incomplete run exists (via latest symlink pointing to a run without completed_at).
If previous incomplete run found, present:
A previous incomplete run was detected: <previous-run-id>
Ask the user via AskUserQuestion:
- Question: "A previous incomplete run was detected. Resume or start fresh?"
- Options:
- "Resume from the last completed phase" (Recommended)
- "Start fresh with a new empty run"
Wait for the user's selection before continuing.
If Resume:
- Copy
clarified/ from previous run into new run, EXCEPT user-feedback.md.
- Detect last completed phase by checking which artifacts exist.
- Staleness check: If input files are newer than copied artifacts, warn and offer to re-run clarification.
Step 4: Build Run Config
No questions asked. Depth, intent, and interaction mode are inferred or read from project config.
Interaction mode wiring: Read interaction_mode from .wazir/state/config.json as the project default. Inline modifiers override:
interaction_mode = inline_modifier ?? project_config.interaction_mode ?? 'guided'
Intent Inference
Infer intent from the request text using keyword matching:
| Keywords in request | Inferred Intent |
|---|
| fix, bug, broken, crash, error, issue, wrong | bugfix |
| refactor, clean, restructure, reorganize, rename, simplify | refactor |
| doc, document, readme, guide, explain | docs |
| research, spike, explore, investigate, prototype | spike |
| (anything else) | feature |
Depth defaults to standard. Override only via inline modifiers (/wazir quick ..., /wazir deep ...).
Write Run Config
Save to .wazir/runs/<run-id>/run-config.yaml:
run_id: run-YYYYMMDD-HHMMSS
parent_run_id: null
continuation_reason: null
request: "the original user request"
request_summary: "short summary"
parsed_intent: feature
entry_point: "/wazir"
depth: standard
interaction_mode: guided
workflow_policy:
discover: { enabled: true, loop_cap: 10 }
clarify: { enabled: true, loop_cap: 10 }
specify: { enabled: true, loop_cap: 10 }
spec-challenge: { enabled: true, loop_cap: 10 }
author: { enabled: false, loop_cap: 10 }
design: { enabled: true, loop_cap: 10 }
design-review: { enabled: true, loop_cap: 10 }
plan: { enabled: true, loop_cap: 10 }
plan-review: { enabled: true, loop_cap: 10 }
execute: { enabled: true, loop_cap: 10 }
verify: { enabled: true, loop_cap: 5 }
review: { enabled: true, loop_cap: 10 }
learn: { enabled: true, loop_cap: 5 }
prepare_next: { enabled: true, loop_cap: 5 }
run_audit: { enabled: false, loop_cap: 10 }
research_topics: []
created_at: "YYYY-MM-DDTHH:MM:SSZ"
completed_at: null
Workflow Skip Rules
Map intent + depth to applicable workflows. The system decides — the user does NOT pick.
| Class | Workflows | Rules |
|---|
| Core (always run) | clarify, execute, verify, review | Never skipped |
| Adaptive (run when evidence says so) | discover, design, author, specify | Skipped for bugfix/docs/spike at quick depth |
| Scale (intensity varies) | spec-challenge, plan-review, architectural-design-review, visual-design-review | Loop cap controls iteration depth |
| Post-run (always run) | learn, prepare_next | Part of Final Review phase |
Log skip decisions with reasons in workflow_policy.
Confidence Gate
After building run config:
-
High confidence — one-line summary and proceed:
Running: standard depth, feature, sequential. Proceeding...
-
Low confidence — show plan and ask:
Ask the user via AskUserQuestion:
- Question: "Does this run configuration look right?"
- Options:
- "Yes, proceed" (Recommended)
- "No, let me adjust"
Wait for the user's selection before continuing.
wazir capture event --run <run-id> --event phase_exit --phase init --status completed
Run the phase report and display it to the user:
wazir report phase --run <run-id> --phase init
Output the report content to the user in the conversation.
Interaction Modes
The interaction_mode field in run-config controls how the pipeline interacts with the user:
| Mode | Inline modifier | Behavior | Best for |
|---|
guided | (default) | Pipeline runs, pauses at phase checkpoints for user approval. Current default behavior. | Most work |
auto | /wazir auto ... | No human checkpoints. Codex reviews all. Gating agent decides continue/loop_back/escalate. Stops ONLY on escalate. | Overnight, clear spec, well-understood domain |
interactive | /wazir interactive ... | More questions, more discussion, co-designs with user. Researcher presents options. Executor checks approach before coding. | Ambiguous requirements, new domain, learning |
auto mode constraints
- External reviewer REQUIRED — refuse to start auto mode if no external reviewer is configured (requires multi-tool mode with Codex or Gemini in
.wazir/state/config.json). Error: "Auto mode requires an external reviewer (multi-tool mode with Codex or Gemini). Configure it first or use guided mode."
- On escalate: STOP immediately, write the escalation reason to
.wazir/runs/<id>/escalations/, and wait for user input
- Wall-clock limit: default 4 hours. If exceeded, stop with escalation.
- Never auto-commits to main — always work on feature branch
- All checkpoints (AskUserQuestion) are skipped — gating agent evaluates phase reports and decides
guided mode (default)
Current behavior — no changes needed. Checkpoints at phase boundaries, user approves before advancing.
interactive mode
- Clarifier: asks more detailed questions, presents research findings with options: "I found 3 approaches — which interests you?"
- Executor: checks approach before coding: "I'm about to implement auth with Supabase — sound right?"
- Reviewer: discusses findings with user, not just presents verdict: "I found a potential auth bypass — here's why I think it's high severity, do you agree?"
- Slower but highest quality for complex/ambiguous work
Mode checking in phase skills
All phase skills check interaction_mode from run-config at every checkpoint:
# Read from run-config
interaction_mode = run_config.interaction_mode ?? 'guided'
# At each checkpoint:
if interaction_mode == 'auto':
# Skip checkpoint, let gating agent decide
elif interaction_mode == 'interactive':
# More detailed question, present options, discuss
else:
# guided — standard checkpoint with AskUserQuestion
Two-Level Phase Model
The pipeline has 4 top-level phases, each containing multiple workflows with review loops:
Phase 1: Init
└── (inline — no sub-workflows)
Phase 2: Clarifier
├── discover (research) ← research-review loop
├── clarify ← clarification-review loop
├── specify ← spec-challenge loop
├── author (adaptive) ← approval gate
├── design ← architectural-design-review loop
└── plan ← plan-review loop
Phase 3: Executor
├── execute (per-task) ← task-review loop per task
└── verify
Phase 4: Final Review (Completion Pipeline)
├── integration-verify ← full suite on merged main
├── concern-resolve ← fresh agent, sycophancy guard
├── review (final) ← 2+1 pass compliance audit
├── learn ← adoption rates, quality delta, user corrections
└── prepare_next
Event capture uses both levels. When emitting phase events, include --parent-phase:
wazir capture event --run <id> --event phase_enter --phase discover --parent-phase clarifier --status in_progress
This is the point where compliance usually drops off. You feel like you're making progress so you stop checking the list. Don't fall into that trap. Pull up .wazir/runs/latest/phases/ again. What's next on it?
Progress markers between workflows: After each workflow completes, output:
Phase 2: Clarifier > Workflow: specify (3 of 6 workflows complete)
wazir status shows both levels: "Phase 2: Clarifier > Workflow: specify"
Phase 2: Clarifier
Before starting: Check .wazir/runs/latest/phases/clarifier.md for your current checklist. Complete all items before proceeding to Phase 3.
Before starting this phase, output to the user:
Clarifier Phase — About to research your codebase, clarify requirements, harden the spec, brainstorm designs, and produce an execution plan.
Why this matters: Without this, I'd guess your tech stack, misunderstand constraints, miss edge cases in the spec, and build the wrong architecture. Every ambiguity left unresolved here becomes a bug or rework cycle later.
Looking for: Unstated assumptions, scope boundaries, conflicting requirements, missing acceptance criteria
wazir capture event --run <run-id> --event phase_enter --phase clarifier --status in_progress
Invoke the wz:clarifier skill. It handles all sub-workflows internally:
- Source Capture — fetch URLs from input
- Research (discover workflow) — codebase + external research
- Clarify (clarify workflow) — scope, constraints, assumptions
- Spec Harden (specify + spec-challenge workflows) — measurable spec
- Brainstorm (architectural design + architectural-design-review) — design approaches
- Plan (plan + plan-review workflows) — execution plan
Each sub-workflow has its own review loop. User checkpoints between major steps.
Scope Invariant
Hard rule: items_in_plan >= items_in_input unless the user explicitly approves scope reduction. The clarifier MUST NOT autonomously tier, defer, or drop items from the user's input. It can suggest prioritization, but the decision belongs to the user.
Output: approved spec + design + execution plan in .wazir/runs/latest/clarified/.
After completing this phase, output to the user:
Clarifier Phase complete.
Found: [N] ambiguities resolved, [N] assumptions made explicit, [N] scope boundaries drawn, [N] acceptance criteria hardened
Without this phase: Requirements would be interpreted differently across tasks, acceptance criteria would be vague and untestable, the design would be ad-hoc, and the plan would miss dependency ordering
Changed because of this work: [List spec tightening changes, resolved questions, design decisions, scope adjustments]
wazir capture event --run <run-id> --event phase_exit --phase clarifier --status completed
Run the phase report and display savings to the user:
wazir report phase --run <run-id> --phase clarifier
wazir stats --run <run-id>
Show savings in conversation output:
Context savings this phase: Used wazir index for [N] queries and context-mode for [M] commands, saving ~[X] tokens ([Y]% reduction). Without these, this phase would have consumed [A] tokens instead of [B].
Output the report content to the user in the conversation.
Phase 3: Executor
Before starting: Check .wazir/runs/latest/phases/executor.md for your current checklist. Complete all items before proceeding to Phase 4.
Before starting this phase, output to the user:
Executor Phase — About to implement [N] tasks in dependency order with TDD (test-first), per-task code review, and verification before each commit.
Why this matters: Without this discipline, tests get skipped, edge cases get missed, integration points break silently, and review catches problems too late when they're expensive to fix.
Looking for: Correct dependency ordering, test coverage for each task, clean per-task review passes, no implementation drift from the approved plan
Phase Gate (Hard Gate)
Before entering the Executor phase, verify ALL clarifier artifacts exist:
If ANY file is missing, STOP:
Cannot enter Executor phase: missing prerequisite artifacts from Clarifier.
Missing: [list missing files]
The Clarifier phase must complete before execution can begin. Run /wazir:clarifier first.
Do NOT skip this check. Do NOT rationalize that the input is "clear enough" to bypass clarification. Every pipeline run must produce these artifacts.
wazir capture event --run <run-id> --event phase_enter --phase executor --status in_progress
Pre-execution gate:
wazir validate manifest && wazir validate hooks && wazir validate branches
Invoke the wz:executor skill. It handles:
- Execute (execute workflow) — per-task TDD cycle with review before each commit
- Verify (verify workflow) — deterministic verification of all claims
Per-task review: --mode task-review, 5 task-execution dimensions.
Tasks always run sequentially.
Output: code changes + verification proof in .wazir/runs/latest/artifacts/.
After completing this phase, output to the user:
Executor Phase complete.
Found: [N]/[N] tasks implemented, [N] tests written, [N] per-task review passes completed, [N] findings fixed before commit
Without this phase: Code would ship without tests, review findings would accumulate until final review (10x more expensive to fix), and verification claims would be unsubstantiated
Changed because of this work: [List of commits with conventional commit messages, test counts, verification evidence collected]
wazir capture event --run <run-id> --event phase_exit --phase executor --status completed
Run the phase report and display savings to the user:
wazir report phase --run <run-id> --phase executor
wazir stats --run <run-id>
Output the report content to the user in the conversation.
Show savings in conversation output:
Context savings this phase: Used wazir index for [N] queries and context-mode for [M] commands, saving ~[X] tokens ([Y]% reduction).
Phase 4: Final Review
Before starting: Check .wazir/runs/latest/phases/final_review.md for your current checklist. Complete all items before marking the run complete.
Before starting this phase, output to the user:
Final Review Phase — About to run adversarial 7-dimension review comparing the implementation against your original input, extract durable learnings, and prepare the handoff.
Why this matters: Without this, implementation drift ships undetected, missing acceptance criteria go unnoticed, untested code paths hide bugs, and the same mistakes repeat in the next run.
Looking for: Spec violations, missing features, dead code paths, unsubstantiated claims, scope creep, security gaps, stale documentation
Phase Gate (Hard Gate)
Before entering the Final Review phase, verify the Executor produced its proof:
If missing, STOP:
Cannot enter Final Review: missing verification proof from Executor.
The Executor phase must complete and produce verification-proof.md before final review. Run /wazir:executor first.
wazir capture event --run <run-id> --event phase_enter --phase final_review --status in_progress
This phase validates the implementation against the ORIGINAL INPUT (not the task specs — the executor's per-task reviewer already covered that).
4a: Integration Verification
Full verification suite on merged main before any review:
- Run plan-defined integration criteria from the execution plan
- Run standard suite: tests, type checking, lint, build, deterministic analysis
- Verify all declared external side effects were completed or compensated
If integration fails: identify culprit via sequential merge record. Targeted fix executor receives failing output + acceptance criteria.
4b: Concern Resolution
A fresh agent (NOT the executor or any producing agent) evaluates:
- Concern registry — all DONE_WITH_CONCERNS entries from execution
- Residuals — all
residuals-<subtask-id>.md files
- Batch-boundary disposition — concerns from final batch + cross-subtask patterns
Sycophancy guard: generating agent MUST NOT rebut concerns. Route contested concerns to human.
4c: Review (reviewer role in final mode)
Invoke wz:reviewer --mode final.
2+1 pass compliance audit comparing implementation against the original user input:
- Pass 1: Internal expertise-loaded review (7 dims, scored 0-70)
- Targeted fixes between passes (batched by severity tier)
- Pass 2: Cross-model review (fresh session, deterministic inputs only)
- Pass 3: Reconciliation (conditional — only if passes 1-2 have conflicting CRITICAL/HIGH)
Exit criteria: single unresolved CRITICAL blocks SHIP regardless of score.
Score verdicts: PASS (56+), NEEDS MINOR FIXES (42-55), NEEDS REWORK (28-41), FAIL (0-27).
Final sign-off (after all actions): SHIP / SHIP WITH CAVEATS / DO NOT SHIP.
4d: Learn (learner role)
Extract durable learnings from the completed run:
- Scan all review findings (all passes, internal + cross-model)
- Process user corrections as highest-priority signal
- Track finding adoption rates (per pass, per severity, per source)
- Calculate quality delta (per-dimension first-pass vs final-state)
- Propose learnings to
memory/learnings/proposed/ with impact scoring
- Learnings require explicit scope tags (roles, stacks, concerns)
4e: Prepare Next (planner role)
Prepare context and handoff for the next run:
- Write
execution-summary.md (complete) or handover-batch-N.md (incomplete)
- Include: concerns and resolutions, residuals disposition, quality delta, finding adoption rates
- Record SHIP / SHIP WITH CAVEATS / DO NOT SHIP recommendation
- Compress/archive unneeded files
After completing this phase, output to the user:
Final Review Phase complete (Completion Pipeline).
Integration verification: [PASS/FAIL] — [N] tests, [N] type errors, [N] lint errors
Concern resolution: [N] concerns evaluated, [N] residuals resolved, [N] escalated
Final review (2+1 passes): [N] findings — [N] CRITICAL, [N] HIGH, [N] MEDIUM, [N] LOW. Score: [score]/70.
Pass 3 reconciliation: [ran/skipped] — [reason]
Learnings: [N] proposed (adoption rate: [X]%, quality delta: [Y] points average)
Without this phase: Implementation drift would ship undetected, concerns would accumulate without resolution, cross-subtask integration bugs would hide, and recurring mistakes would never get captured
Changed because of this work: [List of findings fixed per pass, score improvement, learnings extracted, handoff prepared]
wazir capture event --run <run-id> --event phase_exit --phase final_review --status completed
Run the phase report and display it to the user:
wazir report phase --run <run-id> --phase final_review
Output the report content to the user in the conversation.
Step 5: CHANGELOG + Gitflow Validation (Hard Gates)
Before presenting results:
wazir validate branches
wazir validate commits
wazir validate changelog --require-entries --base $(git merge-base HEAD develop || git merge-base HEAD main)
Both must pass before PR. These are not warnings.
Step 6: Present Results
Completion is autonomous — the pipeline presents its sign-off and proceeds. User interaction happens only for two exceptions:
Autonomous Sign-Off
Present the completion pipeline results:
Completion Pipeline Results
Integration verification: [PASS/FAIL]
Concern resolution: [N] concerns, [N] residuals
Final review (2+1 passes): Score [score]/70 — [N] CRITICAL, [N] HIGH, [N] MEDIUM, [N] LOW
Sign-off: [SHIP / SHIP WITH CAVEATS / DO NOT SHIP]
Learnings: [N] proposed. Handoff: .wazir/runs/<run-id>/execution-summary.md
If SHIP or SHIP WITH CAVEATS: proceed to create PR automatically.
If DO NOT SHIP: present findings and stop.
Exception 1: Drift Escalation
If any CRITICAL or HIGH drift finding exists (implementation doesn't match what user asked for):
Drift detected — user decision required.
[List drift findings with evidence]
Ask the user via AskUserQuestion:
- Question: "Implementation drift detected. How should we proceed?"
- Options:
- "Accept the drift"
- "Fix and re-review"
- "Abort the run"
Exception 2: Unresolvable Concern
If a concern maps to a spec requirement but the resolution is unacceptable (requires spec/design change):
Unresolvable concern — user decision required.
[Concern details, spec requirement it maps to, why resolution failed]
Ask the user via AskUserQuestion:
- Question: "This concern requires a spec change to resolve. How should we proceed?"
- Options:
- "Accept as-is with caveat"
- "Modify spec and re-run affected tasks"
- "Abort the run"
CRITICAL Precedence
Even if score is 56+, a single unresolved CRITICAL finding overrides to DO NOT SHIP. Present the CRITICAL finding(s) and stop.
Run Summary
wazir capture summary --run <run-id>
wazir status --run <run-id> --json
Error Handling
If any phase fails:
Phase [name] failed: [reason]
Ask the user via AskUserQuestion:
- Question: "Phase [name] failed: [reason]. How should we proceed?"
- Options:
- "Retry this phase" (Recommended)
- "Skip and continue" (only if workflows within phase are adaptive)
- "Abort the run"
Wait for the user's selection before continuing.
Audit Mode
Triggered by /wazir audit or /wazir audit <focus>.
Runs a structured codebase audit. Invokes the run-audit skill.
Parse inline audit types: /wazir audit security → skip Question 1.
After audit:
Ask the user via AskUserQuestion:
- Question: "Audit complete. What would you like to do with the findings?"
- Options:
- "Review the findings" (Recommended)
- "Generate a fix plan"
- "Run the pipeline on the fix plan"
Wait for the user's selection before continuing.
If option 3, save findings as briefing and run pipeline with intent = bugfix.
PRD Mode
Triggered by /wazir prd or /wazir prd <run-id>.
Generates a PRD from a completed run. Reads approved design, task specs, execution plan, review results. Saves to docs/prd/YYYY-MM-DD-<topic>-prd.md.
After generation:
Ask the user via AskUserQuestion:
- Question: "PRD generated. What would you like to do?"
- Options:
- "Review the PRD" (Recommended)
- "Commit it"
- "Edit before committing"
Wait for the user's selection before continuing.
Reasoning Chain Output
Every phase produces reasoning output at two layers:
Layer 1: Conversation Output (concise — for the user)
Before each major decision, output one trigger sentence and one reasoning sentence:
"Your request mentions 'overnight autonomous run' — researching how Devin and Karpathy's autoresearch handle this, because unattended runs need different safety constraints than interactive ones."
After each phase, output what was found and a counterfactual:
"Found: you use Supabase auth (not custom JWT). If I'd skipped research, I would have built JWT middleware — completely wrong."
Layer 2: File Output (detailed — for learning and reports)
Save full reasoning chain to .wazir/runs/<id>/reasoning/phase-<name>-reasoning.md with entries:
### Decision: [title]
- **Trigger:** What prompted this decision
- **Options considered:** List of alternatives
- **Chosen:** The selected option
- **Reasoning:** Why this option was chosen
- **Confidence:** high | medium | low
- **Counterfactual:** What would have gone wrong without this information
Create the reasoning/ directory during run init. Every phase skill (clarifier, executor, reviewer) writes its own reasoning file. Counterfactuals appear in BOTH conversation output AND reasoning files.
Interaction Rules
- One question at a time — never combine multiple questions
- Numbered options — always present choices as numbered lists
- Mark defaults — always show "(Recommended)" on the suggested option
- Wait for answer — never proceed past a question until the user responds
- No open-ended questions — every question has concrete options to pick from
- Inline answers accepted — users can type the number or the option name
Final challenge: name every checklist item you completed and what you produced for each one. If any answer is "I think I covered that" instead of "here's the output," you have more work to do. Which items are you unsure about?
