@wazir-dev/cli 1.0.0 → 1.1.0

package/skills/brainstorming/SKILL.md

@@ -12,8 +12,8 @@ Rules:
 1. Do not write implementation code before the design is reviewed with the operator.
 2. Ask clarifying questions only when the ambiguity changes scope, architecture, or acceptance criteria.
 3. Propose 2-3 approaches with trade-offs and a recommendation.
-4. Write the approved design to `docs/plans/YYYY-MM-DD-<topic>-design.md`.
-5. Hand off to `wz:writing-plans` after approval.
+4. Write the approved design to `.wazir/runs/latest/clarified/design.md` (if inside a pipeline run) or `docs/plans/YYYY-MM-DD-<topic>-design.md` (if standalone).
+5. After user approves the design concept, the reviewer role runs the design-review loop with `--mode design-review` using canonical design-review dimensions (spec coverage, design-spec consistency, accessibility, visual consistency, exported-code fidelity). See `workflows/design-review.md` and `docs/reference/review-loop-pattern.md`. The designer resolves any findings. If the design-review loop completes all passes clean, hand off to `wz:writing-plans`. Planning does not start until design-review is complete.
 
 Required outputs:
 
@@ -23,55 +23,156 @@ Required outputs:
 
 ---
 
-## Team Mode: Structured Dialogue
+## Team Mode: Agent Teams Structured Dialogue
 
 **Condition:** Only activate when `team_mode: parallel` in `.wazir/runs/latest/run-config.yaml`. Otherwise, use the default single-agent brainstorming above.
 
-When team mode is active, spawn a 3-agent team using Claude Code Agent Teams:
+This mode uses **Agent Teams** (experimental, Claude Code + Opus 4.6) to run a
+multi-agent brainstorming session. Your role is the **Arbiter** — you coordinate
+the dialogue, evaluate convergence, and signal when to stop. You do NOT generate
+design ideas yourself.
+
+### Infrastructure: Claude Code Agent Teams
+
+This skill uses **Agent Teams** — not subagents. The distinction matters:
+
+| | Subagents (Task tool) | Agent Teams |
+|---|---|---|
+| **Lifecycle** | Spawn, return result, die | Full independent sessions that persist for team lifetime |
+| **Communication** | Report back to parent only | Direct peer-to-peer messaging via `SendMessage` |
+| **Coordination** | Parent manages everything | Shared task list with self-coordination |
+
+**Critical constraint:** Text output from teammates is NOT visible to the team.
+Teammates MUST use `SendMessage` to communicate with each other. Regular text
+output is only visible in a teammate's own terminal pane.
+
+### Prerequisites
+
+```bash
+# Check if Agent Teams is enabled
+echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
+```
+
+If not set (empty), tell the user:
+
+> Agent Teams is not enabled. Run this command and restart Claude Code:
+> ```bash
+> claude config set env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 1
+> ```
+
+Then fall back to single-agent brainstorming (rules 1-5 above).
+
+### Step 1: Create the Team
+
+Derive `<concept-slug>` from the briefing topic (lowercased, hyphens for spaces).
+
+Use `TeamCreate` to initialize the team with the name `wazir-brainstorm-<concept-slug>`.
+
+### Step 2: Spawn Teammates
+
+Spawn three teammates using the `Agent` tool with the `team_name` parameter set
+to `wazir-brainstorm-<concept-slug>`. Each agent receives a detailed system
+prompt via the `prompt` parameter.
+
+#### Free Thinker
+
+```
+Agent(
+  team_name: "wazir-brainstorm-<concept-slug>",
+  prompt: "You are the Free Thinker in a Wazir brainstorming session.
+Your job is to propose creative design directions without self-censoring.
+Open new threads, explore possibilities, make connections. Communicate
+ONLY via SendMessage — your text output is not visible to the team.
+After proposing a direction, wait for the Grounder's response before
+opening a new one."
+)
+```
+
+#### Grounder
+
+```
+Agent(
+  team_name: "wazir-brainstorm-<concept-slug>",
+  prompt: "You are the Grounder in a Wazir brainstorming session. Your
+job is to challenge every proposal from the Free Thinker with practical
+concerns: feasibility, complexity, risk, alternatives. After 3-5
+exchanges on a direction, decide: pursue, park, or redirect.
+Communicate ONLY via SendMessage — your text output is not visible to
+the team."
+)
+```
+
+#### Synthesizer
+
+```
+Agent(
+  team_name: "wazir-brainstorm-<concept-slug>",
+  prompt: "You are the Synthesizer in a Wazir brainstorming session.
+You NEVER participate in dialogue — only observe. Read all SendMessage
+traffic between Free Thinker and Grounder. When the Arbiter signals
+convergence, write the final design document to
+.wazir/runs/latest/clarified/design.md with: design summary, pursued
+directions, rejected alternatives, open questions, recommendation."
+)
+```
+
+### Step 3: Coordinate the Dialogue (You Are the Arbiter)
+
+1. Use `SendMessage` to tell the Free Thinker to open the first direction
+   based on the briefing, research brief, and hardened spec.
+2. Monitor exchanges via `SendMessage`. Do NOT generate ideas — only
+   coordinate, nudge, and evaluate.
+3. After each direction is explored (3-5 exchanges), the Grounder decides:
+   **pursue**, **park**, or **redirect**.
+4. After depth-appropriate directions are explored:
+
+   | Depth | Directions to explore | Exchanges per direction |
+   |-------|-----------------------|------------------------|
+   | Standard | 3-5 | 3-5 exchanges |
+   | Deep | 5-8 | 5-8 exchanges |
+
+5. **Signal convergence:** Use `SendMessage` to tell the Synthesizer to
+   produce the final design document.
+6. Wait for the Synthesizer to write the design to
+   `.wazir/runs/latest/clarified/design.md` (if inside a pipeline run) or
+   `docs/plans/YYYY-MM-DD-<topic>-design.md` (if standalone).
+
+### Step 4: Convergence Criteria
 
-### Agents
-
-| Agent | Role | Cognitive Mode |
-|-------|------|----------------|
-| **Free Thinker** | Proposes design directions, creative leaps, "what if..." scenarios. Speaks first, opens new threads. | Divergent generation |
-| **Grounder** | Challenges proposals, sorts signal from noise, picks winners, redirects dead ends. Responds to Free Thinker. | Convergent editing |
-| **Synthesizer** | Observes silently, maintains a running summary, produces the final design document. Never participates in dialogue. | Synthesis only |
-
-### Communication Protocol
-
-- Free Thinker and Grounder exchange via **broadcast** (all agents see every message)
-- Synthesizer **NEVER** participates in dialogue — only observes and writes to files
-- After each direction is explored (3-5 exchanges), the Grounder decides: pursue, park, or redirect
-
-### Dialogue Flow
+The dialogue has converged when:
 
-1. **Open a direction** — Free Thinker proposes (broadcast)
-2. **Deepen** — 3-5 exchanges between Free Thinker and Grounder
-3. **Decide** — Grounder calls it: pursue, park, or redirect
-4. **Next direction** — Free Thinker opens a new thread, aware of connections to prior threads
+1. Enough directions have been explored for the depth level
+2. The pursued directions have genuine range (not variations of the same idea)
+3. The Grounder signals satisfaction
+4. Further dialogue is producing diminishing returns
 
-Early rounds: more divergent. Later rounds: more convergent.
+Early rounds should be more divergent. Later rounds more convergent.
 
-### Depth-Bounded Behavior
+### Step 5: Clean Up
 
-| Depth | Directions to explore | Exchanges per direction |
-|-------|-----------------------|------------------------|
-| Standard | 3-5 | 3 exchanges |
-| Deep | 5-8 | 5 exchanges |
+Use `TeamDelete` to tear down the team after the Synthesizer has written the
+design document.
 
-### Convergence
+### Constraints
 
-The dialogue has converged when:
-1. Enough directions have been explored for the depth level
-2. The pursued directions have genuine range (not variations of the same idea)
-3. The Grounder signals satisfaction
-4. Further dialogue is producing diminishing returns
+- Text output from teammates is NOT visible to the team — they MUST use
+  `SendMessage`
+- The Arbiter (you) coordinates but does NOT generate ideas
+- The Synthesizer NEVER sends messages — only reads and writes files
+- Free Thinker and Grounder exchange via broadcast (all agents see every
+  message)
 
 ### Output
 
-The Synthesizer produces the design document following the same format as single-agent brainstorming:
+The Synthesizer produces the design document following the same format as
+single-agent brainstorming:
+
 - Design summary
+- Pursued directions with rationale
+- Rejected alternatives with reasons
 - Open questions or resolved assumptions
-- Explicit recommendation and rejected alternatives
+- Explicit recommendation
 
-The Synthesizer then writes the design to `docs/plans/YYYY-MM-DD-<topic>-design.md` and hands off to `wz:writing-plans`.
+After the design is written, submit it for the design-review loop
+(`--mode design-review`). After design-review is complete, hand off to
+`wz:writing-plans`.

package/skills/clarifier/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: wz:clarifier
+description: Run the clarification pipeline — research, clarify scope, brainstorm design, generate task specs and execution plan. Pauses for user approval between phases.
+---
+
+# Clarifier
+
+Run Phase 0 (Research) + Phase 1 (Clarify, Brainstorm, Plan) for the current project.
+
+**Pacing rule:** This skill has mandatory user checkpoints between phases. Do NOT skip checkpoints. Do NOT combine phases. Complete each phase fully, present the output, and wait for explicit user approval before advancing.
+
+Review loops follow the pattern in `docs/reference/review-loop-pattern.md`. All reviewer invocations use explicit `--mode`.
+
+**Standalone mode:** If no `.wazir/runs/latest/` exists, artifacts go to `docs/plans/` and review logs go alongside.
+
+## Prerequisites
+
+1. Check `.wazir/state/config.json` exists. If not, run `wazir init` first.
+2. Check `.wazir/input/briefing.md` exists. If not, ask the user what they want to build and save it there.
+3. Read config for `default_depth`, `default_intent`, `team_mode`, and `multi_tool` settings.
+4. Create a run directory if one doesn't exist:
+   ```bash
+   mkdir -p .wazir/runs/run-YYYYMMDD-HHMMSS/{sources,tasks,artifacts,reviews,clarified}
+   ln -sfn run-YYYYMMDD-HHMMSS .wazir/runs/latest
+   ```
+
+---
+
+## Phase 0: Research (delegated)
+
+Delegate to the discover workflow (`workflows/discover.md`):
+
+1. The **researcher role** produces the research artifact
+   (codebase scan, external sources, source manifest, research brief).
+2. The **reviewer role** runs the research-review loop
+   using research dimensions with `--mode research-review`
+   (see `docs/reference/review-loop-pattern.md`).
+3. The researcher resolves findings from each pass.
+4. Loop runs for `pass_counts[depth]` passes.
+5. Research artifact flows back to the clarifier for Checkpoint 0.
+
+Save result to `.wazir/runs/latest/clarified/research-brief.md`.
+
+### Checkpoint 0: Research Review
+
+Present the research brief to the user:
+
+> **Research complete. Here's what I found:**
+>
+> [Summary of existing codebase state, relevant architecture, external context]
+>
+> **Does this match your understanding? Anything to add or correct?**
+> 1. **Looks good, continue** (Recommended)
+> 2. **Missing context** — let me add more information
+> 3. **Wrong direction** — let me clarify the intent
+
+**Wait for user response before continuing.**
+
+---
+
+## Phase 1A: Clarify (autonomous, then review, then checkpoint)
+
+Read the briefing, research brief, and codebase context. Produce:
+
+- **What** we're building — concrete deliverables, not vague descriptions
+- **Why** — the motivation and business value
+- **Constraints** — technical, timeline, dependencies
+- **Assumptions** — what we're taking as given (explicitly stated)
+- **Scope boundaries** — what's IN and what's explicitly OUT
+- **Unresolved questions** — anything ambiguous that could change architecture or acceptance criteria
+
+Save to `.wazir/runs/latest/clarified/clarification.md`.
+
+Invoke the review loop for the clarification artifact using spec/clarification dimensions with `--mode clarification-review`. The **reviewer role** runs the loop (see `docs/reference/review-loop-pattern.md`). Resolve any findings before presenting to user.
+
+### Checkpoint 1A: Clarification Review
+
+Present the full clarification to the user:
+
+> **Here's the clarified scope:**
+>
+> [Full clarification with what/why/constraints/assumptions/scope/questions]
+>
+> **Are there any corrections, missing context, or open questions to resolve?**
+> 1. **Approved — continue to spec hardening**
+> 2. **Needs changes** — [user provides corrections]
+> 3. **Missing important context** — [user adds information]
+
+**Wait for user response. If the user provides corrections, update the clarification and re-present.**
+
+---
+
+## Phase 1A+: Spec Harden (delegated, then checkpoint)
+
+Delegate to the specify workflow (`workflows/specify.md`):
+
+1. The **specifier role** produces a measurable spec from the clarification
+   and research artifacts.
+2. The **reviewer role** runs the spec-challenge loop
+   (`workflows/spec-challenge.md`) with `--mode spec-challenge`.
+3. The specifier resolves findings from each pass.
+4. Loop runs for `pass_counts[depth]` passes.
+
+Save result to `.wazir/runs/latest/clarified/spec-hardened.md`.
+
+### Checkpoint 1A+: Hardened Spec Review
+
+Present the changes made during hardening:
+
+> **Spec hardened. Changes made:**
+>
+> [List of each gap found and how it was tightened]
+>
+> **Review the hardened spec. Approve or adjust?**
+> 1. **Approved — continue to brainstorming** (Recommended)
+> 2. **Disagree with a change** — [user specifies]
+> 3. **Found more gaps** — [user adds]
+
+**Wait for user response before continuing.**
+
+---
+
+## Phase 1B: Brainstorm (interactive — always pauses)
+
+Invoke the `brainstorming` skill (`wz:brainstorming`) and follow it.
+
+This phase explores design approaches:
+1. Propose 2-3 viable approaches with explicit trade-offs
+2. For each approach: effort estimate, risk assessment, what it enables/prevents
+3. Recommend one approach with rationale
+
+If `team_mode: parallel` in config, the brainstorming skill activates its
+**Agent Teams Structured Dialogue** mode:
+
+1. Checks that `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is enabled (falls back
+   to single-agent brainstorming if not)
+2. Creates a team via `TeamCreate` (`wazir-brainstorm-<concept-slug>`)
+3. Spawns three teammates via `Agent` with `team_name`:
+   - **Free Thinker** — proposes creative directions via `SendMessage`
+   - **Grounder** — challenges each direction with practical concerns via `SendMessage`
+   - **Synthesizer** — observes silently, writes the design document on convergence
+4. You (the Arbiter) coordinate the dialogue, signal convergence, and clean up
+   with `TeamDelete`
+
+See `skills/brainstorming/SKILL.md` "Team Mode: Agent Teams Structured Dialogue"
+for full spawn prompts, convergence criteria, and constraints.
+
+### Checkpoint 1B: Design Approval
+
+> **Proposed design approaches:**
+>
+> [Approaches with trade-offs, recommendation]
+>
+> **Which approach should we implement?**
+> 1. **Approach A** — [one-line summary]
+> 2. **Approach B** — [one-line summary]
+> 3. **Approach C** — [one-line summary]
+> 4. **Modify an approach** — [user specifies changes]
+
+**This is the most important checkpoint. Do NOT proceed without explicit design approval.**
+
+Save approved design to `.wazir/runs/latest/clarified/design.md`.
+
+### Design Review
+
+After the user approves the design concept, invoke the design-review loop with `--mode design-review`. The **reviewer role** validates the design against the approved spec using the canonical design-review dimensions:
+
+- Spec coverage
+- Design-spec consistency
+- Accessibility
+- Visual consistency
+- Exported-code fidelity
+
+See `workflows/design-review.md` and `docs/reference/review-loop-pattern.md`. The designer resolves findings. Proceed to planning only after all design-review passes complete.
+
+---
+
+## Phase 1C: Plan (delegated, then checkpoint)
+
+Delegate to `wz:writing-plans`:
+
+1. `wz:writing-plans` (using **planner role**) produces the execution plan
+   and task specs.
+2. The **reviewer role** runs the plan-review loop
+   (`workflows/plan-review.md`) with `--mode plan-review`.
+3. The planner resolves findings from each pass.
+4. Loop runs for `pass_counts[depth]` passes.
+
+### Checkpoint 1C: Plan Review
+
+> **Implementation plan: [N] tasks**
+>
+> | # | Task | Complexity | Dependencies | Description |
+> |---|------|-----------|--------------|-------------|
+> | 1 | ... | S | none | ... |
+> | 2 | ... | M | task-1 | ... |
+>
+> **Review the plan. Approve or adjust?**
+> 1. **Approved — ready for execution** (Recommended)
+> 2. **Reorder or split tasks** — [user specifies]
+> 3. **Missing tasks** — [user adds]
+> 4. **Too granular / too coarse** — [user adjusts scope]
+
+**Wait for user response before completing.**
+
+---
+
+## Done
+
+When the plan is approved, present:
+
+> **Clarification complete.**
+>
+> - Spec: `.wazir/runs/latest/clarified/spec-hardened.md`
+> - Design: `.wazir/runs/latest/clarified/design.md`
+> - Tasks: [count] tasks in `.wazir/runs/latest/tasks/`
+> - Plan: `.wazir/runs/latest/clarified/execution-plan.md`
+>
+> **Next:** Run `/wazir:executor` to execute the plan.

package/skills/debugging/SKILL.md

@@ -43,7 +43,17 @@ Follow this order:
 
    Apply the minimum corrective change, then rerun the failing check and the relevant broader verification set.
 
-Rules:
+## Loop Cap Awareness
+
+Debugging loops respect the loop cap when running inside a pipeline:
+- **Pipeline mode** (`.wazir/runs/latest/` exists): use `wazir capture loop-check` to track iteration count. If the cap is reached (exit 43), escalate to the user with all evidence collected so far.
+- **Standalone mode** (no `.wazir/runs/latest/`): the loop runs for `pass_counts[depth]` passes (quick=3, standard=5, deep=7) with no cap guard. Track iteration count manually.
+
+In standalone mode, any debug logs go to `docs/plans/` alongside the artifact.
+
+See `docs/reference/review-loop-pattern.md` for cap guard integration.
+
+## Rules
 
 - change one thing at a time
 - keep evidence for each failed hypothesis

package/skills/executing-plans/SKILL.md

@@ -7,7 +7,7 @@ description: Use when you have a written implementation plan to execute in a sep
 
 ## Overview
 
-Load plan, review critically, execute all tasks, report when complete.
+Load plan, review critically, execute all tasks with per-task review checkpoints, report when complete.
 
 **Announce at start:** "I'm using the executing-plans skill to implement this plan."
 
@@ -27,7 +27,18 @@ For each task:
 1. Mark as in_progress
 2. Follow each step exactly (plan has bite-sized steps)
 3. Run verifications as specified
-4. Mark as completed
+4. Review BEFORE marking complete (per-task review, 5 task-execution dimensions):
+   - Run task-review loop with `--mode task-review`
+   - Use `codex review --uncommitted` for uncommitted changes, or `codex review --base <sha>` if already committed
+   - Codex error handling: if codex exits non-zero, log the error, mark the pass as codex-unavailable, and use self-review findings only. Do not treat a Codex failure as a clean pass.
+   - Resolve all findings before proceeding
+   - Log to: `.wazir/runs/latest/reviews/execute-task-<NNN>-review-pass-<N>.md`
+   - Cap tracking: `wazir capture loop-check --task-id <NNN>`
+   - This is NOT the final scored review -- it is a per-task gate using 5 task-execution dimensions
+   - See `docs/reference/review-loop-pattern.md` for the full review loop contract
+5. Only after review passes: mark as completed, commit
+
+**Standalone mode:** When no `.wazir/runs/latest/` exists, review logs go to `docs/plans/` alongside the artifact. The loop runs for `pass_counts[depth]` passes with no cap guard.
 
 ### Step 3: Complete Development
 
@@ -58,9 +69,11 @@ After all tasks complete and verified:
 - Review plan critically first
 - Follow plan steps exactly
 - Don't skip verifications
+- Don't skip per-task review -- it catches issues before they cascade to later tasks
 - Reference skills when plan says to
 - Stop when blocked, don't guess
 - Never start implementation on main/master branch without explicit user consent
+- Review loop pattern: see `docs/reference/review-loop-pattern.md`
 
 ## Integration
 

package/skills/executor/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: wz:executor
+description: Run the execution phase — implement the approved plan with TDD, quality gates, and verification.
+---
+
+# Executor
+
+Run Phase 2 (Execute) for the current project.
+
+## Prerequisites
+
+1. Check `.wazir/runs/latest/clarified/execution-plan.md` exists. If not, tell the user to run `/wazir:clarifier` first.
+2. Read the execution plan and task specs from `.wazir/runs/latest/tasks/`.
+3. Read `.wazir/state/config.json` for team_mode and depth settings.
+
+## Pre-Execution Validation
+
+Run these checks before implementing:
+- `wazir validate manifest` — confirm manifest schema is valid
+- `wazir validate hooks` — confirm hook contracts are intact
+
+If either fails, surface the failure and do NOT proceed until resolved.
+
+## Execution
+
+Implement tasks in the order defined by the execution plan.
+
+For each task:
+
+1. **Read** the task spec at `.wazir/runs/latest/tasks/task-NNN/spec.md`
+2. **Implement** using TDD (write test first, make it pass, refactor)
+3. **Verify** — run tests, type checks, linting as appropriate
+4. **Review BEFORE commit** (per-task review, NOT final review):
+   - Reviewer runs task-review loop with `--mode task-review` using 5 task-execution dimensions (correctness, tests, wiring, drift, quality)
+   - Reads the Codex model from config: `CODEX_MODEL=$(jq -r '.multi_tool.codex.model // empty' .wazir/state/config.json 2>/dev/null); CODEX_MODEL=${CODEX_MODEL:-gpt-5.4}`
+   - Uses `codex review -c model="$CODEX_MODEL" --uncommitted` for the current task's changes
+   - Codex error handling: if codex exits non-zero, log error, mark pass as `codex-unavailable`, use self-review only for that pass. Do NOT treat a Codex failure as a clean review. Do NOT skip the pass. The next pass still attempts Codex (transient failures may recover).
+   - Executor resolves findings, reviewer re-reviews
+   - Loop runs for `pass_counts[depth]` passes (quick=3, standard=5, deep=7). No extension.
+   - Review logs: `.wazir/runs/latest/reviews/execute-task-<NNN>-review-pass-<N>.md`
+   - Loop cap tracking: `wazir capture loop-check --task-id <NNN>` (each task has its own cap counter)
+   - See `docs/reference/review-loop-pattern.md` for full protocol
+   - NOTE: this is the per-task review (5 dims), not the final scored review (7 dims) which runs later in `/wazir:reviewer --mode final`
+5. **Commit** — only after review passes, commit with conventional commit format: `<type>(<scope>): <description>`
+6. **CHANGELOG** — if the change is user-facing (new feature, behavior change, bug fix visible to users), update `CHANGELOG.md` `[Unreleased]` section. If not user-facing (refactor, internal tooling, tests), skip.
+7. **Record** evidence at `.wazir/runs/latest/artifacts/task-NNN/`
+
+Review loops follow the pattern in `docs/reference/review-loop-pattern.md`. Code review scoping: review uncommitted changes before commit. If changes are already committed (subagent workflow), use `codex review -c model="$CODEX_MODEL" --base <pre-task-sha>`.
+
+If `team_mode: parallel` in config, spawn Agent Teams for independent tasks. Otherwise, tasks run sequentially.
+
+**Standalone mode:** When no `.wazir/runs/latest/` exists, review logs go to `docs/plans/` alongside the artifact.
+
+## Context Retrieval
+
+- 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
+
+## Escalation
+
+Pause and ask the user when:
+- The plan is blocked or contradictory
+- Implementation would require unapproved scope change
+- A task's acceptance criteria can't be met
+
+## Done
+
+When all tasks are complete, present:
+
+> **Execution complete.**
+>
+> - Tasks: [completed]/[total] implemented
+> - Artifacts: `.wazir/runs/latest/artifacts/`
+>
+> **Next:** Run `/wazir:reviewer --mode final` to review the changes, or `/wazir` for the full pipeline.