# Design Document

> ALWAYS invoke when the user wants a UI/UX design document or interface spec. Triggers: "design a UI for X", "create a design document", "design spec", "UX spec". Provide a brief as the argument.

- **Type:** Skill
- **Install:** `agentstack add skill-doctormozg-claude-pipelines-design-document`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [DoctorMozg](https://agentstack.voostack.com/s/doctormozg)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [DoctorMozg](https://github.com/DoctorMozg)
- **Source:** https://github.com/DoctorMozg/claude-pipelines/tree/master/plugins/mz-design/skills/design-document

## Install

```sh
agentstack add skill-doctormozg-claude-pipelines-design-document
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Design Document Pipeline

## Overview

Takes a UI/UX design brief and produces a comprehensive design document with ASCII wireframes, Mermaid diagrams, and a WCAG 2.2 AA contrast report. Refines the draft through four specialist critics in parallel (ui-designer, ux-designer, art-designer, accessibility-specialist) with a WCAG hard gate, for up to 5 iterations, until all critics approve and zero contrast violations remain.

## When to Use

- User asks to create a UI/UX design document, interface specification, or UX spec.
- Triggers: "design a X page/screen/flow", "create a design document for X", "design spec for X", "UX spec for X".
- Work produces a spec document (not implementation) for software UI/UX.

### When NOT to use

- Implementing the design in code — use `build` (mz-dev-pipe).
- Reviewing an existing design doc — use `audit` or `review-branch`.
- Brainstorming directions without committing to a spec — use `brainstorm` (mz-creative).
- Print, brand, or industrial design — out of scope for this skill.

## Input

`$ARGUMENTS` — The design brief. Supports inline modifiers:

- `scope:branch|global|working` — codebase scope for design-researcher (default: `global`)
- `@image:` — reference image path (acknowledged, not decoded)
- `@doc:` — existing requirement/brief document to ingest

If empty, ask the user for a brief via `AskUserQuestion`. Never guess.

## Constants

- **MAX_DESIGN_ITERATIONS**: 5
- **DESIGN_DIR**: `.mz/design/`
- **TASK_NAME_FORMAT**: `_design_`
- **WCAG_AA_NORMAL**: 4.5
- **WCAG_AA_LARGE**: 3.0

## Core Process

### Phase Overview

| #   | Phase             | File                                                       | Loop?                           |
| --- | ----------------- | ---------------------------------------------------------- | ------------------------------- |
| 0   | Setup             | inline below                                               | —                               |
| 1   | Intake & Research | `phases/intake_and_research.md`                            | —                               |
| 2   | Initial Draft     | `phases/initial_draft.md`                                  | —                               |
| 3   | Critique Loop     | `phases/critique_loop.md`                                  | max `MAX_DESIGN_ITERATIONS` (5) |
| 4   | Finalization      | Inline gate below (+ `phases/finalization.md` for details) | user-approval sub-loop          |

### Phase 0: Setup

1. Parse `$ARGUMENTS`. Extract brief, `scope:`, `@image:` refs, `@doc:` refs.
1. If brief is empty → `AskUserQuestion` asking for the brief. Do not guess.
1. Derive task name as `_design_` where `` is today's date (underscores) and slug is a snake_case summary of the brief (max 20 chars); on same-day collision append `_v2`, `_v3`.
1. Create `.mz/design//`.
1. Write `state.md` with `schema_version: 2` as the first line, then `Status`, `Phase`, `Started`, `phase_complete: false`, `what_remains: []`, `Iteration: 0`, `FilesWritten: []`.
1. Output a visible setup block showing: `task_name`, `DESIGN_DIR` path, detected modifiers.

### Phase 4: User Approval Gate

**This orchestrator** (not a subagent) presents this gate. This step is interactive and must not be delegated.

**Pre-read**: Read `.mz/design//design.md`, `.mz/design//wireframes.md`, and `.mz/design//wcag-report.md` with the Read tool. Capture the full design document body, ASCII wireframes, and WCAG contrast report into context. The critique loop must have converged with `AGGREGATE: PASS` and zero WCAG violations before this gate fires. See `phases/finalization.md` Step 4.1 for extended presentation rules and the revision-writer sub-loop.

**Surface 1 — emit the plan message.** Output the three artifacts verbatim as a normal markdown chat message. Emit the full verbatim contents of `.mz/design//design.md`, `wireframes.md`, and `wcag-report.md` — do not substitute a path, summary, or placeholder. Structure:

```
## Design ready for review — design-document

Design document finalized (/5 iterations · Aggregate:  · WCAG: PASS). All four specialist critics approved the design and the WCAG contrast report shows zero violations.

### Design Document (design.md)

### Wireframes (wireframes.md)

### WCAG Contrast Report (wcag-report.md)

---
**Approve** → write `final-summary.md` and mark the task complete  ·  **Reject** → mark the task aborted, nothing more written  ·  reply with feedback to revise
```

**Surface 2 — call AskUserQuestion.** A short selector — do not re-embed the design artifacts in the question body, they live in the plan message above:

- question: `The finalized design above is ready for review.`
- options: **Approve** — write `final-summary.md` and complete the task · **Reject** — abort the task, write nothing further

**Response handling**:

- **Approve** → update `state.md` to `complete`, proceed to write `final-summary.md`.
- **Reject** → update `state.md` to `aborted_by_user` and stop. Do not write `final-summary.md`.
- **Any other reply (feedback)** → dispatch `design-revision-writer` to apply the feedback, overwrite the affected artifact(s), return to this gate, re-read the updated artifact(s), and re-emit the entire plan message from scratch with the full new contents under each section — never diff-only, never summary-only, since context compaction may have destroyed the user's memory of earlier iterations. This is a loop — repeat until the user explicitly approves. Never proceed to `final-summary.md` without explicit approval.

## Techniques

Techniques: delegated to phase files — see Phase Overview table above.

## Common Rationalizations

| Rationalization                                      | Rebuttal                                                                                                                                                                    |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "The first draft is fine, skip the critique loop"    | "Four parallel critics catch issues in one round that would surface as rework during implementation. The loop costs 5 agents per round and prevents 10+ downstream cycles." |
| "WCAG AA is overkill for internal tools"             | "Internal users include colleagues with visual impairments. AA is the legal floor, not a stretch goal. The hard gate is non-negotiable."                                    |
| "Mermaid diagrams and ASCII wireframes are busywork" | "Flow diagrams surface IA gaps invisible in prose. Wireframes make layout decisions concrete — without them, ui-designer has nothing to critique."                          |
| "I'll approve iteration 1 to save time"              | "The 5-iteration cap is a ceiling, not a target. Most drafts pass in 1–2 rounds. Approving an unreviewed draft defeats the purpose of the specialist critics."              |

## Red Flags

- You dispatched the writer before the researcher returned `STATUS: DONE`.
- You accepted `AGGREGATE: FAIL` and advanced without running the revision writer.
- You advanced past `MAX_DESIGN_ITERATIONS` without escalating to the user.
- You trusted the writer's self-reported WCAG numbers instead of the accessibility-specialist's re-validation.
- You presented the final doc without the Phase 4 user approval gate.
- You serialized the four critics instead of dispatching them in parallel (single message, four Agent calls).

## Verification

At the end of Phase 4, output:

```
Design document finalized.
Task dir:   .mz/design//
Iterations: /5
Aggregate:  
WCAG gate:  
Files:
  - design.md ()
  - wireframes.md ()
  - wcag-report.md ( —  pairs)
  - final-summary.md
```

If any phase is incomplete, print the blocker explicitly. The verification block is mandatory — do not skip it.

## Error Handling

- Agent failure → retry once, then escalate via `AskUserQuestion`.
- Brief is empty → ask the user; never guess.
- `@image:` path does not exist → note in `intake.md`, continue with placeholder.
- `@doc:` path does not exist → ask the user whether to proceed without it.
- WCAG hard gate fails at iteration 5 → escalate with options (accept as-is, provide guidance for one more round, abort).
- Critic emits malformed output → treat as FAIL, proceed to revision.
- Always update `state.md` before and after spawning agents.

## State Management

After each phase, update `.mz/design//state.md` with:

- `Status:` `pending` | `running` | `complete` | `complete_with_unresolved` | `aborted_by_user` | `failed`
- `Phase:` `0` | `1` | `2` | `3` | `4`
- `PhaseName:` short label (`setup`, `intake_and_research_complete`, etc.)
- `Iteration:` `0..MAX_DESIGN_ITERATIONS`
- `LastVerdict:` (Phase 3 only) the 6-line verdict block from `critique_.md`
- `FilesWritten:` cumulative list of paths

Never rely on conversation memory for cross-phase state — context compaction destroys specific paths and decisions. The state file is the source of truth.

State persists to `.mz/task//state.md`. Schema is **v2**: the file's first line is `schema_version: 2`, and alongside the skill's existing `Status` / `Phase` / `Started` keys it carries `phase_complete` (boolean) and `what_remains` (YAML list of strings). Set `phase_complete: false` on phase entry and `true` once the phase's artifacts are written and its gates pass; refresh `what_remains` on every phase transition; `what_remains` MUST be `[]` when `Status: complete`. On reading a `schema_version: 1` or unversioned file, add the missing keys, set `schema_version: 2`, and log the upgrade.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [DoctorMozg](https://github.com/DoctorMozg)
- **Source:** [DoctorMozg/claude-pipelines](https://github.com/DoctorMozg/claude-pipelines)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-doctormozg-claude-pipelines-design-document
- Seller: https://agentstack.voostack.com/s/doctormozg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.