Workflow Spec To Mockup

Codex compatibility note:

• Invoke $skill-name: load the registered .agents/skills/<name>/SKILL.md and execute it with Codex tools; no separate Skill tool or Claude mode switch is needed. Author .claude/**; mirrors are generated.
• Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
• Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Preserve protocol order unless the user approves a deviation. Workflows use $start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence. <!-- WORKFLOW-CALLS:START -->

Workflow Calls and Todo Bootstrap

Read the registry → workflows.workflow-spec-to-mockup together with this skill. Call $start-workflow workflow-spec-to-mockup to resolve the selected mode, pre-actions and fingerprint.

Todo FIRST: before triage, analysis or step execution, create one todo per phase of the selected mode, in order, listing every occurrence of that phase as a line, including conditional/optional ones (a mode that declares no phases gets one todo per occurrence); preserve occurrence IDs, roles and barrier groups. Use native todo tools or an equivalent persistent ledger. Then mark the first todo in_progress; close each step line with its run or skip evidence, and complete a phase todo only when every line is closed and its applicable exit gates hold. Mode selection and registry loading prepare tracking; any 'first action' below means the first substantive action after this bootstrap.

Call each step skill: read its linked SKILL.md and execute its protocol through the active host with the registry args. Reading or naming a skill alone is not execution. Required gates and core/optional flex follow the linked start-workflow Step Execution Protocol; keep this skill's quality gates, loops and evidence requirements.

Conditions: load each occurrence's registry applicability.when and skipReason verbatim, and record its run/skip evidence through the linked start-workflow protocol. Do not silently omit a todo or turn a conditional skill into an unconditional call; close, in one batch at triage, the todos whose condition is already false there. Declared parallel groups retain their all-return barrier.

Explicit step-skill calls by mode (registry order; roles and conditions remain owned by the registry):

• Mode default: $design-spec (core) → $work-item --mode=review --type=design --fix-loop (gate) → $work-item --mode=mockup --explore (core) → $ui-design --mode=review (gate) → $workflow-end (gate) → $watzup (optional; conditional) Phase todos: Specify (3) → Review (1; exit review-converged) → Close (2; exit run-closed) <!-- workflow-mode:default fingerprint:ef0c111f9e8ac21a9ff623490aa9bd9bbe8a3e09755a475e5440f7f2cc2b8fe4 -->

Regenerate this block with node .claude/scripts/lib/workflow-skill-contract.cjs --write after registry edits; $sync-codex refreshes it before mirroring. <!-- WORKFLOW-CALLS:END -->

Quick Summary

Goal: Produce one reviewed, journey-validated, interactive multi-view HTML mock app per UI-bearing canonical spec, in the user's chosen direction (recorded fallback only when they cannot be asked), or no mockup when they skip; stop before planned work or implementation.

Summary: Scope gate → triage → design spec → design review (--type=design) → mockup (--explore; it also renders the per-view evidence and links the spec's mockup: frontmatter) → UI review → close. Reuse reviewed journeys; record the user's direction before building the full app. A skip retains design review and workflow gates with explicit N/A mockup evidence.

Use when: a PO/BA/designer wants to click through a UI-bearing canonical spec before planned work or build. Adjacent routes: raw idea → workflow-planned-work --mode=idea-to-spec (or --mode=idea-to-tasks for planned work with mockups); spec + planned work → workflow-planned-work (spec-to-tasks); specified behavior to build → workflow-implement-spec; backend-only spec → no mockup.

Key Rules: Scope/pick stay in the main session; journey-first generation and review gates remain fixed; produce no task, story, plan or production code.

IMPORTANT MANDATORY Steps: $design-spec -> $work-item --mode=review --type=design --fix-loop -> $work-item --mode=mockup --explore -> $ui-design --mode=review -> $workflow-end -> $watzup

Step contract: Follow $start-workflow → Step Execution Protocol. The registry owns recommended order, roles and applicability; invoke each selected skill through the active host and log deviations. Gates (work-item --mode=review --type=design, ui-design --mode=review, workflow-end) always run; the optional step runs only when applicability.when holds. On a skip, UI review records N/A — no mockup to review.

Contents

• Workflow Calls and Todo Bootstrap
• Quick Summary
• 0. Mockup Scope Gate (FIRST action of the run)
• 1. Triage (right after the §0 scope gate, before choosing steps)
• 2. Journey-First Design Order (BLOCKING — every generation step)
• 3. Required Quality Gates
• 4. Recommended Skills
• 5. Orchestration Freedom
• 6. Memory, Reporting and Fix Path
• Closing Reminders

0. Mockup Scope Gate (FIRST action of the run)

Run work-item --mode=mockup Step 0 before any reading, analysis or $design-spec; it owns the question, options and no-question-tool fallback. Record its answer once for the whole run; later --explore reuses it. Keep the question in the main session; delegated agents may build direction drafts. Asking first lets a skip save tokens and time.

Skip mockup → record Mockup: SKIPPED by user; run $design-spec, $work-item --mode=review --type=design, and the $ui-design --mode=review gate with N/A — no mockup to review, then $workflow-end (and $watzup only when its registry condition holds). Log $work-item --mode=mockup as an N/A deviation (no mockup exists). The §3 gates Direction selected, Releasable multi-view mock app, Render evidence, Journeys walked and Spec linked (mockup:) record N/A — Mockup: SKIPPED by user.

1. Triage (right after the §0 scope gate, before choosing steps)

Record the result as the first section of the run report.

2. Journey-First Design Order (BLOCKING — every generation step)

Follow SYNC:ux-journey-gate; read .claude/docs/ux-journey-process.md when generating or reviewing a surface. No wireframe, direction draft, token table or mockup HTML precedes the Journey Report.

• design-spec Step 0a writes the Journey Report (UX-1) and design-authority record (UX-2).
• work-item --mode=mockup reuses both at Step 2a/3, re-confirming only changes. Surface a journey conflicting with the reviewed design spec to the user; never silently re-derive it.
• ui-design --mode=review walks every main journey (UX-8). The mockup closes with the UI/UX Gate Report (UX-11); fix any unserved step, orphan element or open FAIL before handoff.

3. Required Quality Gates

Rows marked (gate) are registry gate steps or outcome gates; the other rows are the quality bar of the core design-spec and work-item --mode=mockup --explore steps; §0 lists the rows a user-skipped mockup records as N/A.

4. Recommended Skills

5. Orchestration Freedom

Choose inline/delegated work, batching and order through the Step Execution Protocol. Preserve these dependencies: reviewed design spec → direction drafts → recorded pick → full app → render → UI review; fixes land before re-review; $workflow-end closes the run.

Keep the explore pick and every user confirmation in the main session, never parallelized or auto-answered while the user can be asked. Auto-selection is limited to the recorded mockup-owner paths: no question tool, drafts unshowable, question tool error. For direction drafts, spawn all N in ONE message and wait for all returns. Each sub-agent brief carries the spec path, Journey Report, design-authority paths and Design Plan skeleton verbatim; it inherits no conversation context. Triage's 3+ spec rule also applies to design-spec delegation.

6. Memory, Reporting and Fix Path

• One task per phase with a row per step (rows per spec when several) so nothing is lost after compaction; write the run report tmp/reports/workflow-spec-to-mockup-{YYMMDD}-{HHmm}-{slug}.md FIRST and append per step; after compaction re-read it, the current task list and tmp/design/<run>/direction-approved.md before continuing.
• Artifact placement: drafts, renders, product facts and run notes are disposable run output under tmp/design/<run>/ (<run> = YYMMDD-HHmm-<slug>); the design spec lives under the team-artifacts root (default team-artifacts/; docsRoots.teamArtifacts.path in docs/project-config.json overrides); the final mockup lives at the work-item --mode=mockup spec-source output path, design-specs/ under the same team-artifacts root — never inside the business spec root, which holds canonical specs only.
• Fix path: findings are validated before fixing; fix journey, priority or rule findings in the design spec (and re-run work-item --mode=review --type=design), visual or interaction findings in the mockup (and re-render, then re-run ui-design --mode=review), and spec-intent gaps in the spec through spec [mode=update]. Review loop: round 1 exits on zero open findings (LOW deferral); round 2 on zero CRITICAL/HIGH/MEDIUM with LOWs recorded as deferred; cap 3 review rounds; escalate via ask user question tool on no progress.
• Handoff at close: spec path(s), design-spec path(s), the final mockup path(s), the picked direction and its Selection: line quoted from direction-approved.md (or Mockup: SKIPPED by user), the walkthrough verdict per main journey, render evidence or NOT VERIFIABLE, open questions below 80% confidence, and the next route — workflow-planned-work (spec-to-tasks) for planned work or workflow-implement-spec to build.

<!-- PROTOCOL-GUIDES:START -->

Protocol guides — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.

• design-distinctiveness-gate — Design identity gate DD-1 to DD-8: subject, design plan, generic test, restraint; designing, implementing or reviewing a visual surface → .claude/skills/shared/protocols/design-distinctiveness-gate.md
• incremental-persistence — Persist results per file or section while the work proceeds; a sub-agent or heavy step processes more than three files → .claude/skills/shared/protocols/incremental-persistence.md
• session-goal-ledger — Keep the original goal and every user prompt of the session; running a long or multi-prompt session → .claude/skills/shared/protocols/session-goal-ledger.md
• subagent-return-contract — Sub-agents return a structured envelope and a report path, never an inline report; spawning a sub-agent → .claude/skills/shared/protocols/subagent-return-contract.md
• ui-intent-layer — Tech-agnostic UI intent layer in every UI-bearing spec; writing a spec for a feature with a user interface → .claude/skills/shared/protocols/ui-intent-layer.md
• ui-ux-design-principles — Forty usability and accessibility clauses, UI-1.1 to UI-9.4; designing, building or reviewing a user-facing interface → .claude/skills/shared/protocols/ui-ux-design-principles.md
• ux-journey-gate — Journey-first UX gate UX-1 to UX-11: report journeys, read the design authority, generate, then check every UI/UX gate; generating, specifying, planning, mocking up or reviewing a user-facing surface → .claude/skills/shared/protocols/ux-journey-gate.md
• workflow-registry-binding — Read the workflow registry entry and the workflow skill together, since they must agree; executing or editing a workflow → .claude/skills/shared/protocols/workflow-registry-binding.md

<!-- PROTOCOL-GUIDES:END -->

<!-- SYNC:ui-intent-layer:reminder -->

• MANDATORY For UI-bearing specs, author/maintain the tech-agnostic interaction-surface layer (views with information priority now/later/not-here and container role + navigation map + observable states + user-action flows), resolving it through the configured profile's intent/evidence roles and logical IDs; an unresolved owner, role, ID, carrier, or link stays UNKNOWN/BLOCKED. Strict portable fallback — only when neither config nor local references declares a native artifact contract: trace each flow to the default US-/OP-/BR- IDs and record the companion artifact in the design_spec:/mockup: frontmatter keys. Name ZERO frameworks/routes/CSS/component classes; skip ONLY for backend-only features with a stated reason.

<!-- /SYNC:ui-intent-layer:reminder -->

<!-- SYNC:ux-journey-gate:reminder -->

• MUST ATTENTION journey-first, BLOCKING order: REPORT the main user journeys (UX-1, evidence-tagged; confirm an inferred actor/job/outcome, or with no question tool record it INFERRED — unconfirmed and continue) → READ project design principles, design system, existing UI (UX-2) → generate → CHECK all gates. Checks: views = journey steps (UX-3) · important information first — one focal point, one primary action = next step, first viewport holds the primary tier (UX-4) · rules become prevention, states, recovery (UX-5) · the user's mental model (UX-6) · low-fi first (UX-7) · walkthrough + traceability, no unserved step or orphan (UX-8) · interaction cost per journey measured — steps, clicks, view changes, fields, decisions — every click confident, not a 3-click rule (UX-9) · wayfinding: where am I, where can I go, how do I get back, no dead ends (UX-10) · close with the UI/UX Gate Report covering UX-*, UI-*, DD-*, CL-* and UI copy — an unresolved FAIL blocks hand-off (UX-11). Catalog: .claude/docs/ux-journey-process.md. Skip ONLY with no user-facing surface, stated.

<!-- /SYNC:ux-journey-gate:reminder -->

<!-- SYNC:ui-ux-design-principles:reminder -->

Apply UI-1.1–UI-9.4 only to applicable user-interface work. Resolve platform and project conventions first. Use WCAG 2.2 AA as the web accessibility baseline plus any stricter applicable legal/project requirement; non-web surfaces use the documented platform standard. Other web/mobile metrics and component tiers are defaults/examples only for matching surfaces. Skip N/A clauses and non-UI work explicitly. Project config, references, and accepted decisions govern; cite applicable findings by UI-<clause> + file:line.

<!-- /SYNC:ui-ux-design-principles:reminder -->

<!-- SYNC:design-distinctiveness-gate:reminder -->

• MUST ATTENTION apply the design distinctiveness gate (DD-1–DD-8) to any user-facing visual surface: ground it in the named subject/audience/job and confirm when the brief is silent (DD-1) · every choice carries a WHY, token names included (DD-2) · write a design plan (colour 4–6 named hex · type families+roles+scale · layout prose+ASCII+alignment · principles) then run the BLOCKING generic test and state what you revised BEFORE coding (DD-3) · audit every free axis against the T1–T5 tell catalog — cream+serif+#D97757, acid-on-black, broadsheet, the SaaS-card kit, template chrome (ALL-CAPS eyebrows, A · B · C, spaced-em-dash labels, #0B0B0B, mono data labels, trailing →) — a match is a missed decision, never a defect (DD-4) · 1–2 clearly distinct families, real scale, <80ch, no single-word headline accent / ALL-CAPS labels / redundant eyebrows (DD-5) · numbering only on real sequences; hero = the subject's most characteristic thing, not big-number+gradient (DD-6) · one orchestrated motion moment, never per-section entrances plus universal card hovers (DD-7) · spend boldness once, critique the BUILT page, remove one accessory (DD-8). The brief's stated direction OUTRANKS the tell catalog; project design-system docs OUTRANK these clauses — genuine conflicts go to the user, NEVER resolved silently. Cite findings as DD-<clause> + file:line. Skip ONLY for surfaces with no user-facing visuals, stated explicitly.

<!-- /SYNC:design-distinctiveness-gate:reminder -->

<!-- SYNC:session-goal-ledger:reminder -->

• MANDATORY Session goal ledger per the Task Planning Rules: pin Original goal:, keep User prompts this session: P1…Pn, and map the result to every prompt before claiming done; full text: .claude/skills/shared/protocols/session-goal-ledger.md.

<!-- /SYNC:session-goal-ledger:reminder -->

Closing Reminders

IMPORTANT MUST ATTENTION Goal: Produce one reviewed, journey-validated, interactive multi-view HTML mock app per UI-bearing canonical spec, in the user's chosen direction (recorded fallback only when they cannot be asked), or no mockup when they skip; stop before planned work or implementation.

MUST ATTENTION Main steps: scope gate → triage → $design-spec → $work-item --mode=review --type=design → $work-item --mode=mockup --explore (render evidence + mockup: link) → $ui-design --mode=review → $workflow-end → conditional $watzup.

• MUST ATTENTION report journeys (UX-1) and read design authority (UX-2) before generating; walk every main journey with traceability (UX-8); no open UI/UX FAIL at handoff.
• MUST ATTENTION scope gate FIRST, before analysis or drafting. Keep scope and direction picks in the main session; record the Selection: line and never choose while the user can be asked.
• MUST ATTENTION deliver the full multi-view app: every view, navigation edge, component and state, with a connected full-flow demo per journey; one static screen fails.
• MUST ATTENTION design review, UI review and workflow-end gates always run. A skip records UI review N/A; render exit 3 is NOT VERIFIABLE, never an install.
• NEVER produce tasks, stories, plans or production code; keep drafts/renders in tmp/design/<run>/ and edit only companion-artifact frontmatter in the spec.