UX Design Hub

Routes to specialist sub-skills or runs the built-in 8-step UX pipeline.

Hub Decision Tree

Request arrives
|
+-- Product planning (vision, roadmap, data model, export)?
|   -> Load: skill://lev-design-os
|      (~/.agents/skills/lev-design-os/SKILL.md + references/)
|
+-- Visual design / .pen file / design sweep?
|   -> Use Pencil MCP tools (batch_design, get_screenshot, style guides)
|      Ref: skillsdb://design-ux/pencil for character/illustration work
|
+-- CLI / agentic UX patterns?
|   -> Load Phase 0.5 lev-ref patterns (below)
|
+-- User research / personas / study design?
|   -> Run UX research mode:
|      Step 1 persona detection + Step 2 persona fanout + domain exploration + problem framing + synthetic user research
|      Optional: use CDO persona agents if CDO artifacts or "$cdo insights" are present
|
+-- UX pipeline (wireframes, flows, IA, JTBD)?
|   -> Run 7-step pipeline (this skill body)
|
+-- CDO insights / persona base / deliberation synthesis?
|   -> Run persona detection, compose one CDO agent per situation-specific persona,
|      then use those findings as persona seed material
|      Continue into research mode or full pipeline depending on context
|
+-- "What design skills exist?" / browse?
|   -> Query: ls ~/.agents/skills-db/design-ux/
|      Deep:  ~/.agents/lev-skills.sh discover "{query}" --json --category=design
|
+-- Ambiguous?
    -> Infer from local/contextual signals first. If confidence < 0.75, ask one
       clarifying question with these options:
       1. Full UX run
       2. User research/personas only
       3. Persona base from CDO insights
       4. Spike/wireframes only

Skills-DB Design Catalog (skillsdb://design-ux/*)

Skill	Load when
design-os	Product vision, roadmap, data model, design tokens, export
superdesign-prompt-library	AI image prompts, style/layout/component prompts
swiftui-* (6 skills)	SwiftUI/iOS/macOS UI work
metal-shaders, vfx-spell-effects	GPU graphics, visual effects

UX Thinking Patterns (scored, from skills-db)

Load from ~/.agents/skills-db/thinking/patterns/{name}/SKILL.md when reasoning depth needed:

Pattern	Score	Use when
nielsen-heuristics	50	Usability evaluation
design-of-everyday-things	48	Affordance/signifier analysis
dont-make-me-think	48	Simplicity audit
laws-of-ux	45	Psychology-based design
wcag	45	Accessibility compliance
design-systems	45	Component architecture
refactoring-ui	44	Developer-facing design tactics

Hub Shortcuts

Key	Action	Route
(p)	Product design wizard	skill://lev-design-os
(w)	Run UX pipeline	Persona-first steps + downstream UX phases below
(f)	Full UX run	Step 1 persona detection + Step 2 persona fanout + full downstream pipeline
(r)	User research/personas	Step 1 persona detection + Step 2 persona fanout + research synthesis
(d)	CDO-backed persona base	Step 1 persona detection + Step 2 CDO persona fanout + research synthesis
(v)	Visual design / .pen	Pencil MCP tools
(c)	CLI/agentic UX patterns	Phase 0.5 lev-ref
(b)	Browse design skills	lev-skill resolve

---

UX Pipeline

Mode Parsing

Treat the user's message (including any /ux ... text) as the input.

• First run the Intent Resolver below. Do not default to AUTO until context has been inspected.

• If the input or nearby context contains cdo, $cdo, CDO insights, persona base, deliberation, synthesis, multi-agent, or paths under tmp/cdo-*, set mode to cdo-research unless the user explicitly asks for only wireframes or only full pipeline.

• If the input or nearby context contains user research, synthetic research, persona, study, interview, JTBD research, or research matrix, set mode to research unless the user explicitly requests full pipeline.

• If it contains full or interactive: ask a small set of clarifying questions first, then run step-by-step.

• If it contains step N: in persona-first modes, step 1 means Persona Detection and step 2 means Persona Fanout. Otherwise, match the named downstream phase if provided.

• If it contains continue: resume the most recent run folder under .lev/ux/.

• If it contains spike: skip directly to the Wireframes phase. Sketch the interface based on the request alone — no analysis, no artifacts, just wireframes. After wireframes, optionally back-fill analysis from what was drawn. This is prototype-first design.

• If no mode is explicit:

  • Infer continue if the user is referring to an existing .lev/ux/ run.
  • Infer cdo-research if CDO artifacts are attached, cited, or present as the declared source of persona insight.
  • Infer research if the request asks who the users are, what personas need, what interviews/research should happen, or how to validate a UX/product premise.
  • Infer full if the request asks for an end-to-end product/UX package, flows, IA, research, and wireframes together.
  • Infer spike if the request asks to sketch, mock, wireframe, or make screens quickly with little analysis.

• If inference confidence is below 0.75, ask exactly one clarifying question: Should I run the full UX pipeline, user research/personas only, persona base from CDO insights, or spike/wireframes only?

• In any non-auto mode except spike, continue, or explicit step N, use the persona-first sequence:

  • Step 1: Persona Detection.
  • Step 2: Persona Fanout.
  • Step 3: Synthesis into problem framing, research, JTBD, or full UX pipeline. Do not skip straight to problem framing unless the user explicitly says to.

• Otherwise: AUTO mode. Run the downstream UX pipeline end-to-end and produce wireframes.

Intent Resolver

Before Phase -1, compile a small routing record:

ux_intent:
  inferred_mode: full | auto | interactive | research | cdo-research | spike | continue | step
  confidence: 0.0
  evidence:
    - "explicit token, nearby context, artifact path, user correction, or prior run"
  ask_if_below_confidence: 0.75
  clarification_question: "Should I run the full UX pipeline, user research/personas only, persona base from CDO insights, or spike/wireframes only?"

Context signals to inspect:

• Current user message and the last few user corrections.
• Files or attachments named by the user.
• Existing .lev/ux/ runs.
• CDO outputs under tmp/cdo-*, .lev/pm/, or paths named by the user.
• Product/domain artifacts already on disk.
• Whether the user is asking to design the product, validate the users, create personas, or draw screens.

Routing rules:

• research: run Step 1 Persona Detection, Step 2 Persona Fanout, Problem Framing, Synthetic User Research, then write summary.md and constraint_bundle.yaml if the signal is strong enough. Do not continue into wireframes unless the user asked for full pipeline or the gate decision is proceed and AUTO mode is active.
• cdo-research: run Step 1 Persona Detection, Step 2 CDO Persona Fanout, then Synthetic User Research using CDO findings as persona seed material. Continue into full UX only if requested or inferred with high confidence.
• full: run Step 1 Persona Detection, Step 2 Persona Fanout, Step 0b, then continue through the full downstream UX pipeline.
• auto: run Step 0b through the full downstream UX pipeline unless self-invalidation aborts.
• spike: run Wireframes only.
• continue: resume latest or explicitly named run.

Do not ask the clarifying question if the user already selected a mode in plain English. "Let's do research first" means research; "base personas on CDO" means cdo-research; "full run" means full.

Persona Detection Gate

In full, interactive, research, and cdo-research modes, persona detection is the first step unless the user explicitly bypasses it.

Naming rule: in non-auto mode this is Step 1. Step 2 is Persona Fanout. Problem framing happens after fanout synthesis. In AUTO mode, keep the existing pipeline numbering but still run this gate when research/persona context is relevant.

Write persona_detection.yaml:

persona_detection:
  source_context:
    - "user request, attachments, prior artifacts, CDO outputs, repo/product docs"
  situation: "{what situation these personas are reacting to}"
  domain: "{domain or market}"
  likely_persona_axes:
    - axis: "{role, authority, risk tolerance, domain expertise, buyer/user, technical literacy, urgency, trust posture}"
      why_it_matters: "{why this axis changes UX/research response}"
  candidate_personas:
    - id: "{persona-id}"
      role: "{domain-specific role}"
      personality_type: "{behavioral archetype specific to the situation, not MBTI by default}"
      context: "{what they know, need, fear, control, and misunderstand}"
      primary_question: "{what this persona needs answered}"
      likely_objection: "{what would make them reject the product/design}"
      source: named_person | role | investor | consumer | buyer | operator | gatekeeper | synthetic
      named_person: "{name if persona is based on a specific stakeholder, else null}"
  confidence: 0.0
  ask_user_if_below: 0.75

Persona source rule:

• If local context names people, each named person plus their role becomes a candidate persona unless the user excludes them. Example: founder, COO, CEO-track, marketing lead, UX researcher.
• Always consider outside-market personas when relevant: investors, consumers, buyers/customers, operators, compliance/risk gatekeepers, and strategic partners.
• Do not flatten named people into generic roles. "Steve as Argo/Kingly COO" and "Lewis as Argo CEO-track" are different personas because their incentives, authority, risk, and objections differ.
• For Argo/Kingly-style venture work, default persona pool is:
  • each named team member + role;
  • sponsor founders;
  • investors;
  • customers/buyers;
  • consumers/end users;
  • strategic partners;
  • risk/legal/compliance gatekeepers.

If confidence is below 0.75, ask one question:

Which persona base should I use: real users/buyers, internal operators, CDO-derived personality agents, or all of the above?

If confidence is high, continue without asking and explain the inferred persona base in summary.md.

Step 2: Persona Fanout

Persona Fanout turns persona_detection.yaml into parallel persona responses. Use it in research, cdo-research, full, and interactive modes after Step 1.

Write persona_fanout.md:

# Persona Fanout

## Fanout Matrix

| Persona | Source | Role | Question Asked | Output Artifact |
|---|---|---|---|---|

## Cross-Persona Synthesis

- Convergent needs:
- Divergent needs:
- Objections:
- Trust signals:
- Language that resonates:
- UX/research implications:
- Cap table/package/product implications, if relevant:

Fanout prompt for each persona:

You are {persona_id}, a {role} in this situation: {situation}.
Respond from your own incentives, authority, fears, and practical constraints.
Do not optimize for what the product team wants to hear.

Return:
1. What you need.
2. What you distrust.
3. What would make you engage.
4. What would make you reject this.
5. What language sounds credible to you.
6. What evidence or milestone would change your mind.
7. UX/product/research implications.

If CDO is not requested, fanout may be run as synthetic persona responses. If CDO is requested or inferred, use CDO Persona Agent Mode below.

CDO Persona Agent Mode

When mode is cdo-research, each CDO agent should be a situation-specific personality/persona, not a generic expert role.

The agent set should be derived from persona_detection.yaml. Each agent brief must include:

• Persona role and authority.
• Situation they are responding to.
• Personality/archetype in practical UX terms, not default MBTI labels.
• What they want.
• What they distrust.
• What evidence would change their mind.
• What they would do if confused.
• Output format: needs, objections, trust signals, language that resonates, failure modes, and design/research implications.

Examples:

• Skeptical enterprise buyer.
• Time-starved operator.
• Status-sensitive executive sponsor.
• Domain expert who distrusts generic AI.
• Novice user with high anxiety.
• Compliance/risk gatekeeper.
• Growth/marketing opportunist.

CDO composition rule:

cdo_persona_agents:
  source: persona_detection.yaml
  composition: "one agent per candidate persona/personality type; include each named person + role, investors, and consumers/customers when relevant"
  synthesis_goal: "convert persona reactions into research constraints, JTBD inputs, anti-patterns, and UX risks"
  output_artifacts:
    - persona_fanout.md
    - cdo_insights.md
    - persona_source_map.yaml

If actual CDO/agent dispatch is unavailable, create the proposed CDO persona matrix and ask before substituting single-model synthetic responses. Do not pretend a multi-agent run occurred.

Output Location

Create a run folder:

• RUN_DIR=.lev/ux/{YYYYMMDD-HHMMSS}-{slug}/

Write artifacts below. If resuming, reuse the existing RUN_DIR.

Artifacts (expected):

• domain_exploration.md

• problem_spec.yaml

• study_design.yaml

• user_and_agent_research.md

• cdo_insights.md (only in cdo-research or when CDO artifacts are used)

• persona_detection.yaml (required for non-auto full, interactive, research, and cdo-research)

• persona_fanout.md (required after persona_detection.yaml in non-auto research/full/cdo-research)

• persona_source_map.yaml (only in research or cdo-research)

• routed_skills.json

• jobs.graph.json

• task_graph.json

• ia_schema.json

• interaction_fsm.json

• components.md

• wireframes.md

• constraint_bundle.yaml

• summary.md

Phase -1: Setup (Deterministic)

1. Create run dir and establish shell vars:

TS="$(date +%Y%m%d-%H%M%S)"
SLUG="$(printf '%s' "$USER_MSG" | tr '[:upper:]' '[:lower:]' | rg -o "[a-z0-9]+" | head -n 6 | paste -sd- -)"
RUN_DIR=".lev/ux/${TS}-${SLUG}"
mkdir -p "$RUN_DIR"

2. Persist the raw request for traceability:

printf '%s\n' "$USER_MSG" > "$RUN_DIR/request.txt"

Phase 0: Prior Art (Fast)

1. If bd exists and .beads/ exists:

• bd list --status=open | rg -n "ux|design|wireframe|ia|flow" -i || true

2. Scan local UX artifacts:

• ls -t .lev/ux 2>/dev/null | head -n 10 || true

3. Scan UI code quickly (keep it cheap):

• rg -n "struct\\s+.*View\\b|SwiftUI|Navigation(Stack|SplitView)|TabView" apps packages extensions 2>/dev/null | head -n 50 || true

If you find relevant prior art, cite paths in summary.md and either extend it or explicitly supersede it.

Phase 0.5: Agentic UX Patterns (lev-ref)

Apply lev-ref patterns to all UX outputs (especially summary.md and any routed-skill handoff).

This phase doubles as the agentic-ux hub route. Load directly when asked about CLI design, progressive disclosure, or prompt steering — no need to run the full 7-step pipeline.

Key patterns:

• CLI-as-Prompt: Every CLI surface is a prompt-steering opportunity
• Progressive Disclosure: Metadata first, body on trigger, references on demand
• Every Surface a Steering Attempt: Follow-ups, related skills, confidence inline
• Audio Design: Consider sonic feedback for agent interactions

1. Load lev-ref patterns:

sed -n '1,220p' docs/_inbox/lev-ref/SKILL.md

2. Apply inline conventions (CLI-as-Prompt):

• Add confidence lines like [85% confident] for key recommendations.

• Add → Next: and → Related: follow-ups.

• Add a short 💡 Tip: in summary.md if there's a non-obvious UX lesson.

Phase 0.6: Skills-DB Enrichment

Route to specialized skills using the Hub Decision Tree above.

1. Check hub_routes (frontmatter) for trigger match against request keywords.

   • If match -> load that skill, optionally resume after persona fanout or at the named downstream phase.

2. If no hub_route match, query skills-db dynamically:

# Design-ux category first (high-signal, 12 skills)
rg -l -i "{keywords}" ~/.agents/skills-db/design-ux/*/SKILL.md

# Broader search only if design-ux returns empty
lev-skill resolve "{keywords}" --json 2>/dev/null | jq '.results[:5]'

3. If curated scores available, prefer higher-scored patterns:

grep -i "{keyword}" ~/.agents/skills-db/thinking/11-ui-ux/task.csv \
  | sort -t, -k8 -rn | head -3

4. Emit routed_skills.json (keep existing schema for compatibility):

{ "request_terms": [...], "candidates": [...], "selected": [...] }

5. Present discovered skills:

   • 1 clear match -> propose loading it
   • 2-3 matches -> ranked list, let user choose
   • 0 matches -> continue with built-in UX pipeline

6. Continue pipeline regardless — routing enriches, never blocks.

Step 0b: Unconstrained Domain Exploration

Optional. Runs in full and auto modes. Skip with step 1 or spike.

Before problem framing, construct 2-3 personas grounded ONLY in the domain — not in any specific problem. These personas don't know what you're building. They know the domain.

0b.1: Construct Domain Personas

From the user's request, identify the domain (e.g., "developer tooling", "healthcare scheduling", "social commerce"). Construct 2-3 personas who live in that domain daily — different roles, different frustrations, different expertise levels.

Each persona: ~150 words. Who they are, what they deal with, what drives them crazy. No problem_spec to anchor to — that's the point.

0b.2: Open-Ended Exploration

Ask each persona (via tribunal or Agent dispatch):

• "What frustrates you most about [domain] right now?"
• "If you could change one thing about how [domain] works, what would it be?"
• "What's broken that nobody talks about?"

0b.3: Compare with Intended Problem

After collecting responses, compare their unprompted concerns with the problem you planned to frame in the Problem Framing phase.

• Strong overlap: Your problem framing is grounded. Proceed.
• Partial overlap: Adjust problem_spec to incorporate concerns you missed.
• Significant divergence: Reconsider your problem framing entirely. The domain personas surfaced problems you didn't consider — maybe you're solving the wrong thing.

Write domain_exploration.md with personas, responses, and comparison.

Why this exists: Synthetic User Research constructs personas FROM the problem_spec, which means they can't say "you're solving the wrong problem." Step 0b breaks that circular validation by exploring the domain before committing to a problem frame.

Problem Framing

Write problem_spec.yaml:

problem:
  statement: "{1-2 sentences}"
  for_whom: "{primary user segment}"
  constraints:
    - "{constraint}"
  success_criteria:
    - "{measurable outcome}"
  scope:
    in: ["{in}"]
    out: ["{out}"]

Rules:

• Make success criteria measurable.

• Keep scope boundaries crisp.

Synthetic User Research

Depends on: problem_spec.yaml must exist. Reference: Load references/study-construction.md for methodology.

1b.1: Design the Study

Analyze problem_spec. Reason about:

• Who are the real user segments for THIS problem? Not generic archetypes — segments grounded in the problem's for_whom, constraints, and success_criteria.

• What psychological dimensions matter for THIS study? Not always Big 5. Maybe domain expertise. Maybe risk tolerance. Maybe tech literacy. Maybe regulatory burden. Pick the axes that would actually produce different reactions to this specific stimulus.

• How many personas does this study need? Could be 2, could be 6. Depends on user space breadth. More isn't better — more is more permutations.

• What's the stimulus? Problem statement? Feature concept? Wireframe? Could be all three across rounds.

Construct personas using axiom explorer's map-elements output format as a scaffold (load ~/.agents/skills-db/thinking/axioms/skills/map-elements.md for format reference) — but only the dimensions that matter. A developer tool study doesn't need political compass. A healthcare app might need ANS state.

Write study_design.yaml:

study:
  stimulus:
    type: problem_statement | feature_concept | wireframe
    content: "{from problem_spec}"
  personas:
    - id: "{descriptive-id}"
      description: "{who this person is, grounded in the problem}"
      key_dimensions:
        - "{dimension}: {value + reasoning}"
      prompt_injection: |
        {the actual persona prompt — full worldview, not just traits}
  matrix:
    models: ["{model-ids — reasoning: why these models}"]
    cli_runners: ["{cli names — reasoning: why these CLIs}"]
  rationale: "{why these personas, why this matrix, what signal are we looking for}"

Full mode: Present study design for review. User can add/remove/modify personas, change the model matrix, adjust dimensions.

Auto mode: Construct and run. Explain reasoning for every choice.

1b.2: Execute via Tribunal

For each cell in the persona × model matrix:

• Construct the persona-injected prompt (persona prompt + stimulus)

• Dispatch via tribunal (using CLI runner table at references/cli-runners.md for cross-CLI runs, or Agent tool for Claude-only)

• Collect structured responses

The same persona runs against every model. The same model runs every persona. The matrix is the point.

1b.3: Analyze & Integrate

Write user_and_agent_research.md:

• Per-persona across models: Does reasoning strength change the reaction? Where do edges appear?

• Per-model across personas: Which model surfaces the most differentiated responses?

• Convergence map: What do ALL personas agree on regardless of model? This is strong signal.

• Divergence map: Where do personas split? Where do models split? These are the tensions worth investigating.

• Edge cases: Unexpected reactions at low/high reasoning strength. Insights that only one persona × model combination surfaced.

Feed into JTBD:

• Convergent concerns → constraints for job statements

• Convergent excitement → motivation language

• Divergent reactions → separate user_types in jobs.graph.json

• Edge cases → risk register or scope exclusions

1b.4: Self-Invalidation Gate

After collecting results, evaluate whether the pipeline should continue:

• gate_decision: proceed — Clear signal. Personas differentiated. Convergence/divergence is actionable. Continue to JTBD.
• gate_decision: reframe — Step 0b concerns diverge significantly from problem_spec.yaml, OR personas surfaced a better problem. Go back to Problem Framing and revise problem_spec.yaml.
• gate_decision: abort — ALL personas across ALL models say "just build and iterate" or equivalent. OR convergence is below useful threshold (too much noise, no clear signal). Recommend a different approach: rapid prototyping, traditional user interviews, design sprint, or just-build-it.

A pipeline that can't recommend against itself isn't honest. If the research says this tool is wrong for this problem, say so and stop.

Append gate_decision to user_and_agent_research.md. If abort, write summary.md with the recommendation to NOT continue the pipeline, and why.

Artifacts

• study_design.yaml (study design with personas, matrix, rationale)

• user_and_agent_research.md (results, convergence/divergence analysis, gate decision, JTBD integration notes)

• domain_exploration.md (Step 0b output, if run)

JTBD: Jobs To Be Done

Write jobs.graph.json: