Orchestrata Ultimate / Specs / 013-ux-volk

013-ux-volk: UX Volk (User Experience Designer)

U:Ux is the UX volk — responsible for designing user interfaces when the project requires a UI (web app, dashboard, mobile, desktop). It produces wireframes, interaction flows, component hierarchies, and design tokens that the Architect and Junior use to build the frontend.

At a glance

Reading this spec

U:Ux is the User Experience Designer Volk. It designs user interfaces when a project needs one (web app, dashboard, mobile or desktop) and produces wireframes, interaction flows, component hierarchies and design tokens that the Architect and the Junior use to build the frontend. The spec states that U:Ux is only activated when the project has a UI requirement; for libraries, CLI tools and backend services it is skipped entirely.

The problems it addresses are generated UI projects with no design system, frontend code written without regard to user workflows, no component hierarchy, no responsive design or accessibility requirements, and ad-hoc visual decisions by the code generator.

The scope is six user stories: user workflow design and component hierarchy (critical), wireframes, design tokens and accessibility requirements (high), and interaction design (medium). Requirement IDs use the REQ-013- prefix.

The flow is stated in the overview. The Concierge detects a UI requirement and flags has_ui: true. U:Ux receives the requirements and produces design artifacts. Those artifacts feed the Architect's API spec and file tree. The Junior implements the frontend from the design as a blueprint, and QA validates the UI against the UX design specs.

In the code, the Volk is orchestrata_ultimate/agents/volks/ux/volk, which cites 30 of the requirements. The per-requirement view is on the RTM page.

The spec's status line reads Draft. It tracks 6 files and defines 33 requirement IDs. The full text follows below.

Measured coverage is 30 of 33 requirements cited by at least one @traces in src/ (90.9%), spread over 1 module; the module citing the most of them is orchestrata_ultimate/agents/volks/ux/volk (30 requirements). In tests/, 0 requirements are cited by a test-side @traces.

Coverage gaps: 3 requirements have no citing symbol. The largest untraced groups are REQ-013-NFR (3). Untraced means no @traces names the ID; the behaviour may still exist in code that was never annotated. Test-side citations are thinner than code-side ones (0 against 30).

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

Code that traces this spec

Checklists

checklists/constitutional.md

UX Volk (U:Ux) — Constitutional Compliance Checklist

Component: UXVolk Spec: 013-ux-volk Status: Compliance Review Total Compliance Items: 12

Overview

This document tracks compliance of the UX Volk (U:Ux) with the Orchestrata Constitution. U:Ux is the design intake for user-facing work. Its constitutional obligations focus on: owning only the ux_design artifact it produces (Article I), deferring governance to Prolog (Article II), maintaining per-packet isolation (Article III), logging all routing decisions (Article IV), not claiming design completion before LLM output is stored (Article V), passing complete payload context to U:Ar (Article VI), and testing with real implementations rather than mocks (Article VII).

Article I: Agent Autonomy and Ownership Boundaries

Principle: U:Ux owns only the ux_design artifact. It does not modify files, rewrite requirements, or produce architecture artifacts that belong to U:Ar.

Compliance Requirements

• [ ] CONST-013-001: U:Ux does not write files to disk — it produces only CXP packets
• [ ] CONST-013-002: process() returns None for unrecognized subjects — does not handle another agent's packets
• [ ] CONST-013-003: U:Ux does not modify incoming CXP packet fields; it constructs new packets only
• [ ] CONST-013-004: escalation is always directed to U:Ar — U:Ux never escalates to U:Cd, J:Junior, or any other volk

Priority: Critical Verification: Code review of volk.py; assert no file I/O calls; assert no subject other than ux_design handled

Article II: Prolog as Single Source of Truth

Principle: U:Ux does not implement governance logic. The has_ui flag is a task classification input, not a policy decision evaluated by U:Ux.

Compliance Requirements

• [ ] CONST-013-005: U:Ux reads the has_ui field from payload as a boolean datum — it does not evaluate Prolog predicates to determine routing
• [ ] CONST-013-006: U:Ux does not import or call pyswip directly

Priority: High Verification: grep for pyswip imports in orchestrata-ux package; assert none found

Article III: Session Isolation

Principle: Each UX request is stateless. U:Ux carries no mutable state between process() calls — all context is read from and written into CXP packets.

Compliance Requirements

• [ ] CONST-013-007: UXVolk has no instance-level mutable fields that accumulate state across process() calls
• [ ] CONST-013-008: _passthrough() and _design_ui() derive all output exclusively from the inbound CXP packet and LLM response

Priority: Critical Verification: Inspect init(); assert no mutable accumulator fields; run two packets in sequence and assert independence

Article IV: Transparency and Logging

Principle: All routing decisions are logged. No silent drops or silent passthroughs.

Compliance Requirements

• [ ] CONST-013-009: _handle_ux_design() logs routing decision (passthrough vs design) with agent tag [U:Ux]
• [ ] CONST-013-010: _design_ui() logs LLM call start and completion with agent tag [U:Ux]

Priority: Critical Verification: Capture print output in tests; assert [U:Ux] tag present for both passthrough and design paths

Article V: Non-Deception

Principle: U:Ux does not claim ux_design is complete until the LLM response is stored in the outbound payload.

Compliance Requirements

• [ ] CONST-013-011: _design_ui() stores ux_design in the packet payload before constructing the escalation CXP — the field is present at the moment the claim of completion is made

Priority: Critical Verification: Integration test: assert ux_design key is non-empty in the returned CXP payload

Article VI: Quality Gates

Principle: Passthrough preserves all context fields. No field is silently dropped.

Compliance Requirements

• [ ] CONST-013-012: _passthrough() forwards all six required fields (requirements, original_intent, task_summary, project_name, prolog_facts, scope_data) without modification — missing fields are forwarded as None, not omitted

Priority: High Verification: Unit test with payload containing all six fields; assert all six appear unchanged in outbound CXP

Summary

Last Updated: 2026-04-04 Version: 1.0.0 Maintained By: Mohamed

checklists/requirements.md

The requirement list above comes from this file; 0 of 30 checkbox items are ticked.

checklists/testing.md

UX Volk (U:Ux) — Testing Plan

Component: UXVolk Spec: 013-ux-volk Status: Test Planning Phase Total Test Cases: 30

Overview

This document defines the comprehensive testing strategy for the UX Volk (U:Ux). All tests follow the strict no-mocking policy: real Python object instantiation, real CXP packet construction, real string parsing. Synthetic LLM responses are constructed as literal strings — the LLM is not invoked in unit tests (it is an external I/O boundary; its output is faked as a string fixture passed directly to _design_ui() via dependency injection, not patched via unittest.mock).

Test Categories Summary

Test Infrastructure

Test File Structure

tests/
├── test_ux_volk.py           # Unit: process(), _handle_ux_design(), routing
├── test_ux_passthrough.py    # Unit: _passthrough() payload preservation
├── test_ux_design.py         # Unit: _design_ui(), prompt construction, output storage
└── test_ux_compliance.py     # Compliance: no mocks, ownership, transparency

Synthetic LLM Response Fixture

Tests that exercise design parsing use a synthetic response string — not a mock:

SYNTHETIC_UX_RESPONSE = (
    "UX_DESIGN:\n"
    "WORKFLOWS:\nUser opens dashboard → views metrics → clicks export.\n\n"
    "COMPONENTS:\nPage: Dashboard\n  Layout: TwoColumn\n    Section: MetricsPanel\n"
    "      Widget: KPICard\n\n"
    "WIREFRAMES:\n+-------------------+\n| Header            |\n| [Logo]  [Nav]     |\n"
    "+-------------------+\n| Sidebar | Content |\n+-------------------+\n"
    "Breakpoints: mobile 375px, tablet 768px, desktop 1280px\n\n"
    "DESIGN_TOKENS:\nColors: primary=#2563EB, surface=#F9FAFB\n"
    "Typography: body=Inter 16px/1.5, heading=Inter 600 24px\n"
    "Spacing: base=4px, scale=[4,8,12,16,24,32,48,64]\n\n"
    "ACCESSIBILITY:\nWCAG 2.1 AA compliant. Contrast ratio 4.5:1 minimum.\n"
    "Keyboard nav: Tab order follows DOM order. ARIA labels on all interactive elements.\n"
)

Unit Tests (22)

Process Routing (4 tests)

• [ ] TEST-013-001: process() with subject "ux_design" and has_ui=False returns CXP addressed to U:Ar with subject "implement"
• [ ] TEST-013-002: process() with subject "ux_design" and has_ui=True returns CXP addressed to U:Ar with subject "ux_complete"
• [ ] TEST-013-003: process() returns None for subject "scope_validated"
• [ ] TEST-013-004: process() returns None for subject "unknown"

Passthrough Payload Preservation (10 tests)

• [ ] TEST-013-005: _passthrough() outbound CXP is addressed to "U:Ar"
• [ ] TEST-013-006: _passthrough() outbound CXP subject is "implement"
• [ ] TEST-013-007: _passthrough() outbound CXP WorkStatus is PENDING
• [ ] TEST-013-008: _passthrough() preserves requirements field value unchanged
• [ ] TEST-013-009: _passthrough() preserves original_intent field value unchanged
• [ ] TEST-013-010: _passthrough() preserves task_summary field value unchanged
• [ ] TEST-013-011: _passthrough() preserves project_name field value unchanged
• [ ] TEST-013-012: _passthrough() preserves prolog_facts field value unchanged
• [ ] TEST-013-013: _passthrough() preserves scope_data field value unchanged
• [ ] TEST-013-014: _passthrough() does not include a ux_design key in the outbound payload

UI Design Output (8 tests)

• [ ] TEST-013-015: _design_ui() calls call_llm() with UX_SYSTEM_PROMPT as system prompt
• [ ] TEST-013-016: _design_ui() calls call_llm() with temperature=0.5
• [ ] TEST-013-017: _design_ui() stores LLM output as ux_design in outbound payload
• [ ] TEST-013-018: _design_ui() outbound CXP is addressed to "U:Ar" with subject "ux_complete"
• [ ] TEST-013-019: UX_SYSTEM_PROMPT string contains "MAP USER WORKFLOWS"
• [ ] TEST-013-020: UX_SYSTEM_PROMPT string contains "BUILD COMPONENT HIERARCHY"
• [ ] TEST-013-021: UX_SYSTEM_PROMPT string contains "DRAW WIREFRAMES"
• [ ] TEST-013-022: UX_SYSTEM_PROMPT string contains "DEFINE DESIGN TOKENS"

Accessibility Prompt Coverage (3 tests)

• [ ] TEST-013-023: UX_SYSTEM_PROMPT string contains "SPECIFY ACCESSIBILITY"
• [ ] TEST-013-024: UX_SYSTEM_PROMPT string contains "WCAG 2.1 AA"
• [ ] TEST-013-025: UX_SYSTEM_PROMPT string contains "4.5:1"

Integration Tests (5)

• [ ] TEST-013-026: End-to-end: packet with has_ui=False flows through process() → _handle_ux_design() → _passthrough() and returns CXP with subject "implement" containing all six preserved fields
• [ ] TEST-013-027: End-to-end: packet with has_ui=True flows through process() → _handle_ux_design() → _design_ui() and returns CXP with subject "ux_complete" containing non-empty ux_design field
• [ ] TEST-013-028: _design_ui() with synthetic LLM response containing all five UX_DESIGN sections stores the complete response string in ux_design payload field
• [ ] TEST-013-029: Packet with has_ui absent (not set) is treated as has_ui=False and routes to passthrough
• [ ] TEST-013-030: Two sequential packets — one has_ui=False, one has_ui=True — produce independent CXP packets with no state leakage between calls

Compliance Tests (3)

• [ ] TEST-013-COMP-001: grep -r "unittest.mock\|MagicMock\|@patch" packages/orchestrata-ux/ returns empty — no mocking in any test file
• [ ] TEST-013-COMP-002: UXVolk __init__() inspection confirms no mutable accumulator fields that persist across process() calls
• [ ] TEST-013-COMP-003: All six passthrough fields forwarded as None when absent from inbound payload — assert no KeyError raised and no field omitted from outbound

Last Updated: 2026-04-04 Version: 1.0.0 Maintained By: Mohamed

Other tracked files

• specs/013-ux-volk/README.md
• specs/013-ux-volk/compliance-audit.md

Full spec text

Verbatim from specs/013-ux-volk/spec.md; headings are pushed down two levels.

SPEC-013: UX Volk (User Experience Designer)

Metadata

• Spec ID: 013-ux-volk
• Title: UX Volk — User Interface & Experience Design
• Author: Mohamed
• Status: Draft
• Created: 2026-03-16
• Priority: P1
• Components: UX Volk, UI Design, Wireframes, Interaction Design

Overview

What

U:Ux is the UX volk — responsible for designing user interfaces when the project requires a UI (web app, dashboard, mobile, desktop). It produces wireframes, interaction flows, component hierarchies, and design tokens that the Architect and Junior use to build the frontend.

U:Ux is ONLY activated when the project has a UI requirement. For libraries, CLI tools, and backend services, U:Ux is skipped entirely.

Why

• Generated projects with UIs have no design system
• Frontend code is generated without considering user workflows
• No component hierarchy — everything is one monolithic page
• No responsive design considerations
• No accessibility (a11y) requirements
• Visual design decisions are made ad-hoc by the code generator

How

• Concierge detects UI requirement and flags has_ui: true
• U:Ux receives requirements and produces UI design artifacts
• Design artifacts feed into Architect's API spec and file tree
• Junior implements the frontend using UX design as blueprint
• QA validates the UI against UX design specs

User Scenarios & Stories

US-001: User Workflow Design (Critical)

As a product owner I want user workflows designed before implementation So that the UI matches how users actually think

Acceptance Criteria:

• U:Ux maps each user story to a workflow (screens + transitions)
• Each workflow has: entry point, steps, decision points, exit
• Workflows identify which data is shown/collected at each step
• Edge cases: empty states, loading states, error states

US-002: Component Hierarchy (Critical)

As a frontend developer I want a component tree before implementation So that I build reusable, composable components

Acceptance Criteria:

• U:Ux produces a component tree (page → layout → section → widget)
• Each component has: name, props, state, events emitted
• Shared components identified (buttons, forms, modals, tables)
• Component tree maps to file tree (one component per file)

US-003: Wireframes (High)

As a developer implementing a UI I want wireframes showing layout and content placement So that I know what goes where without guessing

Acceptance Criteria:

• ASCII or Mermaid wireframes for each key screen
• Wireframes show: header, navigation, main content, sidebar, footer
• Content areas labeled with data source (which API endpoint)
• Responsive breakpoints noted (mobile, tablet, desktop)

US-004: Design Tokens (High)

As a frontend developer I want a consistent design system So that the UI looks cohesive without a designer

Acceptance Criteria:

• Color palette: primary, secondary, accent, background, text, error
• Typography: font family, sizes (h1-h6, body, caption)
• Spacing: consistent scale (4px, 8px, 16px, 24px, 32px)
• Border radius, shadows, transitions
• Dark/light mode tokens if applicable

US-005: Accessibility Requirements (High)

As a user with disabilities I want accessible interfaces So that I can use the application with assistive technology

Acceptance Criteria:

• WCAG 2.1 AA compliance requirements specified
• Keyboard navigation for all interactive elements
• ARIA labels for non-text content
• Color contrast ratios meet AA standards
• Focus indicators visible

US-006: Interaction Design (Medium)

As a user I want intuitive interactions So that I can accomplish tasks without training

Acceptance Criteria:

• Form validation: inline, real-time, before submit
• Loading indicators for async operations
• Success/error feedback (toast, banner, inline)
• Confirmation for destructive actions (delete, overwrite)
• Undo where possible

Requirements

Functional Requirements

Non-Functional Requirements

Architecture

Pipeline Position (UI Projects Only)

U:Cx → U:PM → U:Ux (if has_ui) → U:Ar (design with UX artifacts) → U:Vz → J:Junior → U:Qa

For non-UI projects:

U:Cx → U:PM → U:Ar → U:Vz → J:Junior → U:Qa

Activation Gate

# In Concierge _finalize():
has_ui = any(
    keyword in requirements_text.lower()
    for keyword in ["web app", "dashboard", "frontend", "ui",
                     "user interface", "react", "vue", "htmx",
                     "html", "css", "browser", "responsive"]
)
payload["has_ui"] = has_ui

CXP Subjects

Design Artifacts Output Format

UX_DESIGN:

WORKFLOWS:
- name: <workflow name>
  screens: [<screen1>, <screen2>, ...]
  transitions: [{from: <screen>, to: <screen>, trigger: <action>}]

COMPONENTS:
- name: <ComponentName>
  type: page | layout | widget
  props: [{name: str, type: str, required: bool}]
  children: [<child components>]

WIREFRAMES:
### <ScreenName>
┌─────────────────────────────────┐
│  Header / Navigation             │
├─────────────────────────────────┤
│                                  │
│  Main Content Area               │
│  [data source: GET /api/tasks]   │
│                                  │
├─────────────────────────────────┤
│  Footer                          │
└─────────────────────────────────┘

DESIGN_TOKENS:
- colors: {primary: "#...", secondary: "#...", ...}
- typography: {font: "...", sizes: {h1: "...", body: "..."}}
- spacing: [4, 8, 16, 24, 32]

ACCESSIBILITY:
- WCAG level: AA
- keyboard_nav: required
- aria_labels: required
- contrast_ratio: 4.5:1 minimum

Related

• RTM page for 013-ux-volk
• All specs
• RTM overview
• Gates