@wazir-dev/cli 1.0.0

package/docs/readmes/features/workflows/clarify.md

@@ -0,0 +1,154 @@
+# clarify
+
+**Phase 1 — Turn noise into signal before anything else moves.**
+
+![Phase](https://img.shields.io/badge/phase-1%20of%2014-blue)
+![Role](https://img.shields.io/badge/role-clarifier-orange)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+---
+
+## One-Line Purpose
+
+Convert raw operator input into a clarified scope, an explicit question list, and a usable problem frame that every downstream phase can trust.
+
+---
+
+## Pipeline Position
+
+```
+  INPUT
+    │
+    ▼
+┌─────────┐
+│ CLARIFY │  ◄── YOU ARE HERE
+└─────────┘
+    │
+    ▼
+  DISCOVER
+    │
+    ▼
+  SPECIFY ...
+```
+
+---
+
+## Role Responsible
+
+`clarifier`
+
+The clarifier's sole job is honest problem framing. It does not solve the problem. It does not propose solutions. It surfaces what is actually known, what is assumed, and what remains genuinely open. A clarifier that fabricates certainty to move faster is a clarifier that has failed.
+
+---
+
+## Trigger
+
+One or more briefing files appear in `input/`. This can be:
+
+- A plain-text feature request
+- A bug report
+- A product brief
+- A user story or ticket dump
+- A conversation transcript handed off from a prior session
+
+If the `session_start` hook fires and `input/` is non-empty, the `clarify` workflow is the correct entry point.
+
+---
+
+## Steps
+
+1. **Ingest all input files.** Read every file in `input/`. Do not skim. Missing a buried constraint in a long brief is a clarify failure.
+
+2. **Extract explicit requirements.** List what the operator has actually stated — not implied, not inferred. Use the operator's exact language where possible.
+
+3. **Surface implicit assumptions.** Identify what the brief takes for granted. These become candidate assumptions in the spec.
+
+4. **Enumerate unresolved questions.** For every material ambiguity, write a question. Questions must be concrete and answerable — not philosophical.
+
+5. **Scope the problem frame.** Write a concise scope summary (1–3 paragraphs) that a reviewer who has not read the brief can use to understand the problem being solved.
+
+6. **Flag escalation items.** If any question is so fundamental that downstream phases cannot proceed without an answer, escalate explicitly. Do not pretend it can be deferred.
+
+7. **Produce the clarification artifact.** Combine explicit requirements, assumptions, questions, and scope summary into a single structured artifact.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Operator briefing | `input/` | Yes — at least one file |
+| Active research (prior run) | run state | Optional |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| Clarification artifact | Structured document: requirements, assumptions, questions, scope summary |
+| Unresolved questions list | Flat list of open items, marked by severity (blocking / advisory) |
+| Scope summary | 1–3 paragraph problem frame for downstream consumption |
+
+---
+
+## Approval Gate
+
+There is no formal hard gate after `clarify`. However:
+
+> [!IMPORTANT]
+> If any question is **materially blocking** — meaning the discover or specify phases cannot produce a correct output without its answer — the clarifier MUST escalate before proceeding. Hiding ambiguity as false certainty is the primary failure mode of this phase.
+
+Downstream phases treat the clarification artifact as the authoritative problem frame. Errors introduced here compound through every phase that follows.
+
+---
+
+## Example Run
+
+**Input brief** (`input/brief.md`):
+
+> "Add dark mode support to the dashboard. Users have been asking for it. Should work on mobile too."
+
+**Clarification artifact produced:**
+
+```
+## Explicit Requirements
+- Dark mode toggle on the dashboard
+- Mobile compatibility required
+
+## Implicit Assumptions
+- "Dark mode" means a CSS-variable-driven color scheme toggle (not OS-level detection only)
+- "Mobile" means responsive breakpoints already in use (< 768px)
+- Dashboard refers to /dashboard route, not the admin panel
+
+## Unresolved Questions
+[BLOCKING] Does "dark mode" require persistent user preference (localStorage / account setting),
+           or is per-session toggle sufficient?
+[ADVISORY] Should the toggle appear in the nav bar, user settings, or both?
+[ADVISORY] Are there brand color constraints for dark palette — is there a design system doc?
+
+## Scope Summary
+Add a dark mode color scheme to the main dashboard view with mobile compatibility.
+The primary ambiguity is persistence model for the user preference. All other
+requirements are inferable from current system state once that is resolved.
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Treating inferred requirements as explicit | Spec built on false foundations | Use operator's exact language; mark everything else as assumption |
+| Writing vague questions | Questions cannot be answered | Make every question concrete and answerable in one sentence |
+| Hiding a blocking question as advisory | Downstream phases proceed on bad assumptions | If in doubt, escalate as blocking |
+| Skipping briefing files in `input/` | Missing constraints emerge in execution | Read every input file — even the ones that look like noise |
+| Writing the scope summary as a solution | The clarifier is not the specifier | Scope summaries describe the problem, not the answer |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Next: discover](discover.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)

package/docs/readmes/features/workflows/design-review.md

@@ -0,0 +1,171 @@
+# design-review
+
+**Phase 7 — Adversarial validation of the design before a single task is planned.**
+
+![Phase](https://img.shields.io/badge/phase-7%20of%2014-blue)
+![Role](https://img.shields.io/badge/role-reviewer-orange)
+![Gate](https://img.shields.io/badge/gate-hard%20%E2%98%85-red)
+![Optional](https://img.shields.io/badge/optional-skippable-yellow)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+---
+
+## One-Line Purpose
+
+Validate the design artifact against the approved spec, checking visual consistency, accessibility compliance, and spec coverage before the design is locked in as the source of truth for planning and execution.
+
+---
+
+## Pipeline Position
+
+```
+  DESIGN
+    │
+    ▼
+┌───────────────┐
+│ DESIGN-REVIEW │  ◄── YOU ARE HERE
+└───────────────┘
+    │
+    ▼
+  PLAN  ★ gate (blocking findings stop planning)
+    │
+    ▼
+  PLAN-REVIEW ...
+```
+
+---
+
+## Role Responsible
+
+`reviewer`
+
+The reviewer is structurally independent from the designer who produced the artifact. This is the same structural separation as `spec-challenge`: the person who challenges the work did not produce it. A reviewer who designed the artifact cannot review it — that is not adversarial review, that is self-approval.
+
+---
+
+## Trigger
+
+All of the following are true:
+
+- Design artifact exists (`.fig`, exports, tokens, screenshots)
+- Human approval of design direction was given at the design gate
+- Design phase was not skipped (if design was skipped, this phase is also skipped)
+
+---
+
+## Steps
+
+1. **Load the design artifact and the approved spec.** Open the screenshots and review the exported scaffolds alongside the acceptance criteria.
+
+2. **Check spec coverage.** Does the design address every acceptance criterion that has a visual component? For each visual AC, identify whether the design satisfies it. Flag any AC not addressed.
+
+3. **Check design-spec consistency.** Does the design introduce anything not in the spec? Visual scope additions that are not in the AC are a red flag — they will cause plan scope creep.
+
+4. **Check accessibility.** At minimum:
+   - Color contrast ratios for text on dark and light backgrounds (WCAG 2.1 AA: 4.5:1 for normal text, 3:1 for large text)
+   - Focus states are visible on interactive elements
+   - Touch target sizes at mobile breakpoints (minimum 44x44px)
+
+5. **Check visual consistency.** Do the design tokens form a consistent system? Is the dark mode palette coherent with the light mode palette (same spacing, same type scale)?
+
+6. **Check exported code.** Do the exported scaffolds match the designs? Mismatches between `.fig` and exported code are a failure at this phase, not an implementation concern.
+
+7. **Produce findings with severity.** Each finding must include:
+   - Severity: `blocking` (planning cannot proceed) or `advisory` (proceed with awareness)
+   - Which AC, design component, or export it applies to
+   - Visual evidence reference (screenshot filename, canvas element, or token name)
+   - Required resolution
+
+8. **Issue a verdict.** No-findings verdict if all checks pass. Blocking verdict if any blocking finding exists.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Design artifact | Run state | Yes |
+| Approved spec artifact | Run state | Yes |
+| Accessibility guidelines | Repo or external | Optional (WCAG 2.1 AA assumed if absent) |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| Design review findings | Structured list of findings with severity, visual evidence, and required resolution |
+| No-findings verdict | Explicit statement that all checks passed (if applicable) |
+
+---
+
+## Approval Gate
+
+> [!IMPORTANT]
+> **Unresolved blocking findings must stop progression to planning.** Planning consumes the design artifact as a source of truth. If the design artifact has known defects, the plan will encode those defects into implementation tasks.
+
+Advisory findings may proceed to planning with explicit acknowledgement. If a finding is advisory but the designer elects to address it, the design artifact must be updated before planning begins.
+
+---
+
+## Example Run
+
+**Design artifact under review:**
+
+```
+screenshots/
+  dashboard-dark-desktop.png
+  dashboard-dark-mobile-768.png
+  toggle-states.png
+exports/
+  DarkModeToggle.tsx
+  tokens.json
+```
+
+**Design review findings:**
+
+```
+## Finding 1 — BLOCKING
+AC-4 requires the toggle to be accessible at 768px.
+dashboard-dark-mobile-768.png shows the toggle as a 32x32px icon with no visible
+focus ring. Touch target is below the 44x44px minimum. Focus state is absent.
+Visual evidence: dashboard-dark-mobile-768.png (toggle, top-right)
+Resolution: Redesign toggle at mobile to minimum 44x44px touch target with explicit
+focus ring (2px offset, --color-focus token).
+
+## Finding 2 — BLOCKING
+tokens.json defines --color-text-dark as #999999 on --color-bg-dark (#1a1a1a).
+Contrast ratio: 3.8:1. Fails WCAG 2.1 AA (4.5:1 required for body text).
+Visual evidence: tokens.json lines 12–14
+Resolution: Adjust --color-text-dark to minimum #b3b3b3 (4.6:1 ratio).
+
+## Finding 3 — ADVISORY
+DarkModeToggle.tsx export uses inline styles for transition timing rather than
+the transition tokens in tokens.json. This won't cause an AC failure but breaks
+token system consistency.
+Visual evidence: exports/DarkModeToggle.tsx:34
+Resolution: Move transition-duration to tokens.json --transition-toggle.
+
+## Verdict: BLOCKING — design requires revision before planning.
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Rubber-stamp approval without checking accessibility | Accessibility failures ship to production | Always check contrast ratios and focus states — these are not optional |
+| Generating vague findings without visual evidence | Designer cannot action the finding | Every finding must cite a screenshot, canvas element, or token name |
+| Checking only the happy path screens | Edge case designs block execution review | Check all exported screenshots, not just the hero screens |
+| Conflating design preferences with spec compliance | Findings noise drowns out real issues | Block only on AC failures and accessibility violations; flag preferences as advisory |
+| Approving when exported code diverges from designs | Executor implements the wrong component | Code scaffolds are part of the design artifact; review them |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Previous: design](design.md)
+- [Next: plan](plan.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)

package/docs/readmes/features/workflows/design.md

@@ -0,0 +1,169 @@
+# design
+
+**Phase 6 — From approved spec to visual reality, before a line of implementation code is written.**
+
+![Phase](https://img.shields.io/badge/phase-6%20of%2014-blue)
+![Role](https://img.shields.io/badge/role-designer-orange)
+![Gate](https://img.shields.io/badge/gate-hard%20%E2%98%85-red)
+![Optional](https://img.shields.io/badge/optional-skippable-yellow)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+---
+
+## One-Line Purpose
+
+Transform the approved, challenged spec into production-ready visual designs using open-pencil MCP tools — producing design files, exported code scaffolds, design tokens, and screenshots that the planner and executor consume directly.
+
+---
+
+## Pipeline Position
+
+```
+  AUTHOR (or SPEC-CHALLENGE if author skipped)
+    │
+    ▼
+┌────────┐
+│ DESIGN │  ◄── YOU ARE HERE
+└────────┘
+    │
+    ▼
+  DESIGN-REVIEW  ★ gate
+    │
+    ▼
+  PLAN ...
+```
+
+---
+
+## Role Responsible
+
+`designer`
+
+The designer uses open-pencil MCP tools to produce visual designs from the approved spec. The designer role does not write application code — it produces design artifacts that the executor implements. The distinction matters: a design artifact is the source of truth for visual implementation; it is not a suggestion.
+
+---
+
+## Trigger
+
+All of the following are true:
+
+- Spec artifact exists and is approved
+- Spec challenge findings are resolved (no outstanding blocking findings)
+- Project has visual design needs (this phase is skippable — see Skip Conditions below)
+
+---
+
+## Skip Conditions
+
+`design` and `design-review` may be skipped when:
+
+1. The project has no visual or UI component (a CLI tool, a background service, a data migration)
+2. The open-pencil MCP server is not available in the current session
+
+When skipped, proceed directly to `plan`. The plan must note the absence of a design artifact. Any visual decisions become the executor's responsibility, constrained by the spec's acceptance criteria.
+
+> [!NOTE]
+> Skipping design is a deliberate trade-off, not a shortcut. Visual decisions that should be designed will instead be made ad hoc during implementation. This is acceptable for non-visual work; it is a risk for user-facing features.
+
+---
+
+## Steps
+
+1. **Load the approved spec and research artifacts.** Identify all UI components, screens, and interactions mentioned in the acceptance criteria.
+
+2. **Load brand/style guidelines** (if available). If no design system doc exists (per research findings), note this and proceed with spec-derived constraints only.
+
+3. **Open or create the design file** using open-pencil MCP tools. Establish the canvas and document structure.
+
+4. **Design each required screen/state.** For each component or screen referenced in the spec:
+   - Light mode and dark mode variants (when relevant)
+   - Mobile and desktop breakpoints (per spec requirements)
+   - Interactive states (hover, active, focus, disabled)
+
+5. **Apply design tokens.** Define color, spacing, and typography tokens as structured data. These become the exported `tokens.json`.
+
+6. **Export code scaffolds.** Generate Tailwind JSX or HTML+CSS scaffolds from the design. These are the implementation starting points for the executor.
+
+7. **Export screenshots.** Capture PNG screenshots of each key screen/state for the design-review and post-execution review phases.
+
+8. **Produce the design artifact.** Package the `.fig` file, exported code scaffolds, `tokens.json`, and screenshot PNGs as a named artifact.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Approved spec artifact | Run state | Yes |
+| Research artifact | Run state | Yes |
+| Brand/style guidelines | Repo or external | Optional |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| `.fig` design file | Source design file (open-pencil format) |
+| Exported code scaffolds | Tailwind JSX or HTML+CSS starting points per component |
+| Design tokens (`tokens.json`) | Color, spacing, typography, and semantic tokens |
+| Screenshot PNGs | Visual evidence for design-review and post-execution review |
+| Design artifact (combined) | All of the above packaged as a single named artifact |
+
+---
+
+## Approval Gate
+
+> [!IMPORTANT]
+> **Explicit human approval is required before design-review begins.** The human reviews the designs visually at this gate. Design-review is a structured adversarial check; the approval gate here is the human's initial visual acceptance that the design direction is correct before a reviewer stress-tests it.
+
+---
+
+## Example Run
+
+**Spec inputs (abbreviated):**
+- AC-1: Toggle visible at all viewport widths
+- AC-3: localStorage persistence (dark mode preference)
+- AC-4: Correct rendering at 768px breakpoint
+
+**Design artifact produced:**
+
+```
+design/
+  dashboard-dark-mode.fig         ← source design file
+  exports/
+    DarkModeToggle.tsx            ← Tailwind JSX scaffold
+    tokens.json                   ← color tokens for light + dark
+  screenshots/
+    dashboard-light-desktop.png
+    dashboard-dark-desktop.png
+    dashboard-dark-mobile-768.png
+    toggle-states.png             ← hover, active, focus states
+```
+
+**Key design decisions (documented in artifact):**
+- Toggle placement: top-right of nav bar, persists across scroll
+- Dark palette tokens: defined as `--color-bg-dark`, `--color-text-dark`, etc.
+- 768px breakpoint: toggle collapses to icon-only (tooltip accessible via aria-label)
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Designing features not in the spec | Plan and execution drift from spec | Design only what the acceptance criteria require |
+| Missing exported code scaffolds | Executor starts from scratch; design-impl gap widens | Always export scaffolds as part of the design artifact |
+| Skipping mobile breakpoint design | AC-4 fails verification | Design every screen at every breakpoint mentioned in the spec |
+| Omitting design tokens | Dark mode colors are hardcoded; tokens can't be system-wide | tokens.json is a required output, not optional |
+| Designing only the happy path | Interactive states cause review findings | Design hover, focus, disabled, and error states |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Previous: author](author.md)
+- [Next: design-review](design-review.md)
+- [Architecture (design phase)](../../../concepts/architecture.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)

package/docs/readmes/features/workflows/discover.md

@@ -0,0 +1,162 @@
+# discover
+
+**Phase 2 — Source-backed research that eliminates planning risk before it becomes implementation debt.**
+
+![Phase](https://img.shields.io/badge/phase-2%20of%2014-blue)
+![Role](https://img.shields.io/badge/role-researcher-orange)
+![Status](https://img.shields.io/badge/status-stable-green)
+
+---
+
+## One-Line Purpose
+
+Gather cited, source-backed research on every open question and risk identified during clarification, so the specifier can write an artifact grounded in fact rather than assumption.
+
+---
+
+## Pipeline Position
+
+```
+  CLARIFY
+    │
+    ▼
+┌──────────┐
+│ DISCOVER │  ◄── YOU ARE HERE
+└──────────┘
+    │
+    ▼
+  SPECIFY
+    │
+    ▼
+  SPEC-CHALLENGE ...
+```
+
+---
+
+## Role Responsible
+
+`researcher`
+
+The researcher's job is to find what is actually true — about the codebase, the domain, the constraints, and the open questions — and to prove it with citations. A researcher who produces findings without sources is producing opinion, not research. Opinion cannot flow forward.
+
+---
+
+## Trigger
+
+The clarification artifact is complete. Specifically:
+
+- The scope summary is written
+- Explicit requirements are listed
+- Unresolved questions exist (at minimum: advisory items; blocking items must have been escalated and answered)
+
+If the clarification artifact has no open questions and no research gaps, `discover` can complete very quickly — but it must still run and produce a research artifact, even if brief.
+
+---
+
+## Steps
+
+1. **Load the clarification artifact.** Parse the unresolved questions list and scope summary. These are your research agenda.
+
+2. **Investigate the current codebase.** For questions about existing behavior, existing constraints, or current implementation state — the codebase is the primary source. Cite file paths and line numbers.
+
+3. **Research external dependencies and APIs.** If the scope involves third-party services, libraries, or protocols, find the current version, known constraints, and relevant documentation sections.
+
+4. **Investigate domain knowledge gaps.** If the scope involves a domain the agent is not expert in, research current best practice with citations.
+
+5. **Assess risk factors.** For each finding, assess implementation risk: is this a known-stable API, a deprecated path, a common footgun?
+
+6. **Resolve open questions.** For every unresolved question from clarification, produce a finding with a source. Mark questions that remain open after research.
+
+7. **Produce the research artifact.** One document. All findings. All citations. No finding without a source.
+
+---
+
+## Input Artifacts
+
+| Artifact | Location | Required |
+|----------|----------|----------|
+| Clarification artifact | Run state | Yes |
+| Unresolved questions list | Run state | Yes |
+| Codebase | Repo | Yes |
+
+---
+
+## Output Artifacts
+
+| Artifact | Description |
+|----------|-------------|
+| Research artifact | All findings with citations (file:line for codebase, URL/doc for external) |
+| Cited findings | Flat list of key facts the specifier will use as constraints |
+
+---
+
+## Approval Gate
+
+There is no formal hard gate after `discover`. However:
+
+> [!IMPORTANT]
+> **Unsupported research cannot flow forward.** Any finding without a citation is not a finding — it is a hypothesis. Hypotheses must be clearly labelled as such. The specifier will reject uncited input.
+
+The fail condition for this phase is not "finding the wrong answer." It is producing findings that cannot be verified because they have no source.
+
+---
+
+## Example Run
+
+**Open questions from clarify:**
+
+```
+[BLOCKING] Does dark mode require persistent user preference or per-session toggle?
+[ADVISORY] Are there brand color constraints — is there a design system doc?
+```
+
+**Research artifact produced:**
+
+```
+## Finding 1 — Current theme implementation
+File: src/styles/tokens.css, lines 1–47
+The app uses CSS custom properties (--color-bg, --color-text, etc.) declared on :root.
+No existing dark mode variant exists. A [data-theme="dark"] override pattern is viable
+without breaking existing styles.
+Citation: src/styles/tokens.css:1–47
+
+## Finding 2 — User preference persistence
+File: src/hooks/useLocalStorage.ts
+The codebase already has a useLocalStorage hook used by 3 components.
+localStorage persistence is the established pattern. No server-side preference
+storage exists currently.
+Citation: src/hooks/useLocalStorage.ts:1–38; src/components/Sidebar.tsx:14
+
+## Finding 3 — Brand color constraints
+No design system documentation found in repo. No external design system URL
+in README or package.json. This remains open — spec should note assumption
+that dark palette will be defined by designer from scratch.
+Status: OPEN (not resolvable from current sources)
+
+## Finding 4 — Mobile breakpoints
+File: src/styles/breakpoints.css
+Mobile breakpoint is defined at 768px (--breakpoint-md). Dark mode toggle
+component must be tested at this breakpoint.
+Citation: src/styles/breakpoints.css:3
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Impact | Prevention |
+|---------|--------|------------|
+| Producing findings without citations | Specifier cannot validate the finding | Cite every finding with file:line or external URL |
+| Researching only external sources while ignoring the codebase | Spec diverges from actual codebase reality | Always check the codebase first for in-repo constraints |
+| Marking open questions as resolved | Spec is built on false confidence | If a question cannot be answered, mark it OPEN explicitly |
+| Over-researching low-risk items | Bloat; important findings get buried | Focus research effort on blocking questions and high-risk areas |
+| Producing a research artifact organized as prose | Specifier has to re-parse findings manually | Use structured finding entries: finding, source, risk rating |
+
+---
+
+## Related
+
+- [Overview — All Workflows](README.md)
+- [Previous: clarify](clarify.md)
+- [Next: specify](specify.md)
+- [Roles and Workflows](../../../concepts/roles-and-workflows.md)