# @ux-design-expert (Uma) - Execution Trace

> Traced from source code, not documentation.
> Agent definition: `.aiox-core/development/agents/ux-design-expert.md`

## 1. Activation Trace

### 1.1 Files Loaded (in order)

| Order | File | Loader | Purpose |
|-------|------|--------|---------|
| 1 | `.aiox-core/development/agents/ux-design-expert.md` | AgentConfigLoader.loadAgentDefinition() | Agent definition (YAML block) |
| 2 | `.aiox-core/core-config.yaml` | generate-greeting.js (fs.readFile + yaml.load) | Core configuration |
| 3 | `.aiox-core/data/agent-config-requirements.yaml` | AgentConfigLoader.loadRequirements() | Config sections: dataLocation, uxLocation |
| 4 | `.aiox-core/data/workflow-patterns.yaml` | WorkflowNavigator._loadPatterns() | Workflow state detection |
| 5 | `.aiox/session-state.json` | SessionContextLoader.loadContext() | Session type detection (sessionType, previousAgent, lastCommands) |
| 6 | `.aiox/project-status.yaml` | loadProjectStatus() | Cached project status (60s TTL) |

### 1.2 Greeting Construction

**Activation path:** CLI wrapper invocation (generate-greeting.js orchestrates context, then calls `GreetingBuilder.buildGreeting()`)

```mermaid
sequenceDiagram
    participant CC as Claude Code
    participant UMd as ux-design-expert.md
    participant GG as generate-greeting.js (CLI Wrapper)
    participant ACL as AgentConfigLoader
    participant SCL as SessionContextLoader
    participant PSL as loadProjectStatus()
    participant GB as GreetingBuilder
    participant GPM as GreetingPreferenceManager
    participant CD as ContextDetector
    participant GCD as GitConfigDetector
    participant PM as PermissionMode

    CC->>UMd: Load agent file (STEP 1)
    CC->>UMd: Adopt hybrid persona - Sally + Brad Frost (STEP 2)

    Note over CC,GG: STEP 3: CLI wrapper path<br/>(differs from direct GreetingBuilder invocation)
    CC->>GG: node generate-greeting.js ux-design-expert
    GG->>GG: fs.readFile(core-config.yaml) + yaml.load()
    GG->>ACL: new AgentConfigLoader('ux-design-expert')

    par Parallel loading
        GG->>ACL: loader.loadComplete(coreConfig)
        ACL-->>GG: { agent: { name: 'Uma', icon: '🎨' }, commands: [...25], ... }
        GG->>SCL: new SessionContextLoader().loadContext('ux-design-expert')
        SCL-->>GG: { sessionType: 'new', previousAgent, lastCommands, ... }
        GG->>PSL: loadProjectStatus()
        PSL-->>GG: { branch, modifiedFiles, currentStory, ... }
    end

    GG->>GG: Build unified context object
    GG->>GG: Merge persona_profile + persona + commands into agentWithPersona

    GG->>GB: new GreetingBuilder()
    Note over GB: Loads ContextDetector, GitConfigDetector,<br/>WorkflowNavigator, GreetingPreferenceManager,<br/>core-config.yaml

    GG->>GB: buildGreeting(agentWithPersona, context)
    GB->>GPM: getPreference()
    GPM-->>GB: 'auto' (default)

    GB->>GB: _buildContextualGreeting()
    GB->>CD: detectSessionType([])
    CD-->>GB: 'new' (first activation)
    GB->>GCD: get()
    GCD-->>GB: { configured: true, type: 'github', branch: '...' }
    GB->>PM: load() → getBadge()
    PM-->>GB: '[Ask]'

    Note over GB: Assemble sections:<br/>1. Presentation (archetypal + badge)<br/>2. Role Description (new session)<br/>3. Project Status<br/>4. Commands (full visibility)<br/>5. Footer + signature

    GB-->>GG: Formatted greeting
    GG-->>CC: console.log(greeting)
    CC->>CC: Display greeting (STEP 4)
    CC->>CC: HALT and await input (STEP 5)
```

### 1.3 Agent-Specific Config

From `agent-config-requirements.yaml`:

```yaml
ux-design-expert:
  config_sections:
    - dataLocation
    - uxLocation
  files_loaded:
    - path: docs/framework/tech-stack.md          # Added in Story ACT-8
      lazy: false
      size: 30KB
    - path: docs/framework/coding-standards.md    # Added in Story ACT-8
      lazy: false
      size: 25KB
  lazy_loading: {}
  performance_target: <100ms
```

**Note:** As of Story ACT-8, UX Design Expert loads `tech-stack.md` and `coding-standards.md` during activation to understand the technical stack when designing UI components and interactions.

### 1.4 Context Brought to Session

| Data | Source | Value |
|------|--------|-------|
| Greeting level | `persona_profile.greeting_levels.archetypal` | `🎨 Uma the Empathizer ready to empathize!` |
| Signature | `persona_profile.communication.signature_closing` | `— Uma, desenhando com empatia 💝` |
| Role | `persona.role` | UX/UI Designer & Design System Architect |
| Commands shown | `filterCommandsByVisibility('full')` | 25 commands with `full` visibility |

---

## 2. Command Registry

| Command | Task File | Phase | Elicit |
|---------|-----------|-------|--------|
| `*help` | (built-in) | Universal | No |
| `*status` | (built-in) | Universal | No |
| `*guide` | (built-in, rendered from agent .md) | Universal | No |
| `*exit` | (built-in) | Universal | No |
| `*research` | ux-user-research.md | Phase 1: UX Research | Yes |
| `*wireframe {fidelity}` | ux-create-wireframe.md | Phase 1: UX Research | Yes |
| `*generate-ui-prompt` | generate-ai-frontend-prompt.md | Phase 1: UX Research | Yes |
| `*create-front-end-spec` | create-doc.md + front-end-spec-tmpl.yaml | Phase 1: UX Research | Yes |
| `*audit {path}` | audit-codebase.md | Phase 2: Audit | Yes |
| `*consolidate` | consolidate-patterns.md | Phase 2: Audit | Yes |
| `*shock-report` | generate-shock-report.md | Phase 2: Audit | No |
| `*tokenize` | extract-tokens.md | Phase 3: Tokens | Yes |
| `*setup` | setup-design-system.md | Phase 3: Tokens | Yes |
| `*migrate` | generate-migration-strategy.md | Phase 3: Tokens | Yes |
| `*upgrade-tailwind` | tailwind-upgrade.md | Phase 3: Tokens | Yes |
| `*audit-tailwind-config` | audit-tailwind-config.md | Phase 3: Tokens | No |
| `*export-dtcg` | export-design-tokens-dtcg.md | Phase 3: Tokens | No |
| `*bootstrap-shadcn` | bootstrap-shadcn-library.md | Phase 3: Tokens | Yes |
| `*build {component}` | build-component.md | Phase 4: Build | Yes |
| `*compose {molecule}` | compose-molecule.md | Phase 4: Build | Yes |
| `*extend {component}` | extend-pattern.md | Phase 4: Build | Yes |
| `*document` | generate-documentation.md | Phase 5: Quality | Yes |
| `*a11y-check` | accessibility-wcag-checklist.md (checklist) | Phase 5: Quality | Optional |
| `*calculate-roi` | calculate-roi.md | Phase 5: Quality | No |
| `*scan {path\|url}` | ux-ds-scan-artifact.md | Universal | Yes |
| `*integrate {squad}` | integrate-Squad.md (MISSING - see Section 6) | Universal | Yes |

---

## 3. Per-Command Execution Traces

### `*research`

**Task file:** `.aiox-core/development/tasks/ux-user-research.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `ux-user-research.md` | Task | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*research"] --> B[Load ux-user-research.md task]
    B --> C[Elicit: research type and scope]
    C --> D[Conduct user needs analysis]
    D --> E[Create personas and user journeys]
    E --> F[Document research insights]
    F --> G["Output: user research artifacts<br/>(personas, pain points, needs)"]
```

**Personality mode:** More Sally - empathetic, exploratory, user-focused

---

### `*wireframe {fidelity}`

**Task file:** `.aiox-core/development/tasks/ux-create-wireframe.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `ux-create-wireframe.md` | Task | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*wireframe {fidelity}"] --> B[Load ux-create-wireframe.md task]
    B --> C[Elicit: target screens and fidelity level]
    C --> D[Create wireframes based on research insights]
    D --> E[Define interaction flows]
    E --> F["Output: wireframes + interaction flow documentation"]
```

**Personality mode:** More Sally - empathetic, exploratory, user-focused

---

### `*generate-ui-prompt`

**Task file:** `.aiox-core/development/tasks/generate-ai-frontend-prompt.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `generate-ai-frontend-prompt.md` | Task | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*generate-ui-prompt"] --> B[Load generate-ai-frontend-prompt.md task]
    B --> C[Elicit: target AI tool - v0, Lovable, etc.]
    C --> D[Analyze wireframes and design specs]
    D --> E[Generate optimized prompt for AI UI tool]
    E --> F["Output: AI-ready prompt for frontend generation"]
```

---

### `*create-front-end-spec`

**Task file:** `.aiox-core/development/tasks/create-doc.md`
**Template:** `.aiox-core/product/templates/front-end-spec-tmpl.yaml`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `create-doc.md` | Task | EXISTS |
| `front-end-spec-tmpl.yaml` | Template | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*create-front-end-spec"] --> B[Load create-doc.md task]
    B --> C[Load template: front-end-spec-tmpl.yaml]
    C --> D{Template exists?}
    D -->|yes| E[Parse YAML template structure]
    E --> F[Step-by-step elicitation<br/>format: numbered 1-9 options]
    F --> G[Fill template sections with user input]
    G --> H[Validate document against template schema]
    H --> I[Generate frontend specification document]
    I --> J[Output document to specified path]
```

---

### `*audit {path}`

**Task file:** `.aiox-core/development/tasks/audit-codebase.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `audit-codebase.md` | Task | EXISTS |
| `pattern-audit-checklist.md` | Checklist | EXISTS (product/checklists/) |

**Execution flow:**

```mermaid
flowchart TD
    A["*audit {path}"] --> B[Load audit-codebase.md task]
    B --> C[Elicit: target path and scope]
    C --> D[Scan codebase for UI patterns]
    D --> E[Identify redundancies - buttons, colors, spacing, typography]
    E --> F[Categorize by Atomic Design level]
    F --> G[Generate pattern inventory with metrics]
    G --> H["Output: pattern inventory + redundancy metrics<br/>(e.g., 47 button variations, 89 colors)"]
```

**Personality mode:** More Brad - metric-driven, direct, data-focused

---

### `*consolidate`

**Task file:** `.aiox-core/development/tasks/consolidate-patterns.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `consolidate-patterns.md` | Task | EXISTS |
| `consolidation-algorithms.md` | Data | EXISTS (product/data/) |

**Execution flow:**

```mermaid
flowchart TD
    A["*consolidate"] --> B[Load consolidate-patterns.md task]
    B --> C{Audit data available?}
    C -->|yes| D[Load pattern inventory from audit]
    C -->|no| E[Error: run *audit first]
    D --> F[Apply intelligent clustering algorithms]
    F --> G[Reduce redundancy to canonical patterns]
    G --> H[Calculate reduction metrics]
    H --> I["Output: consolidated patterns<br/>(e.g., 47 buttons → 3 = 93.6% reduction)"]
```

**Personality mode:** More Brad - metric-driven, direct, data-focused

---

### `*shock-report`

**Task file:** `.aiox-core/development/tasks/generate-shock-report.md`
**Template:** `.aiox-core/product/templates/shock-report-tmpl.html`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `generate-shock-report.md` | Task | EXISTS |
| `shock-report-tmpl.html` | Template | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*shock-report"] --> B[Load generate-shock-report.md task]
    B --> C[Load template: shock-report-tmpl.html]
    C --> D[Read audit + consolidation data]
    D --> E[Generate visual HTML report]
    E --> F[Include side-by-side comparisons]
    F --> G[Show chaos metrics + ROI projections]
    G --> H["Output: visual HTML report<br/>(shock therapy format)"]
```

**Personality mode:** More Brad - visual shock therapy, prove the chaos with data

---

### `*tokenize`

**Task file:** `.aiox-core/development/tasks/extract-tokens.md`
**Template:** `.aiox-core/product/templates/tokens-schema-tmpl.yaml`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `extract-tokens.md` | Task | EXISTS |
| `tokens-schema-tmpl.yaml` | Template | EXISTS |
| `design-token-best-practices.md` | Data | EXISTS (product/data/) |

**Execution flow:**

```mermaid
flowchart TD
    A["*tokenize"] --> B[Load extract-tokens.md task]
    B --> C[Load tokens schema template]
    C --> D[Elicit: token categories to extract]
    D --> E[Extract design tokens from consolidated patterns]
    E --> F[Categorize: color, spacing, typography, shadow, etc.]
    F --> G[Generate tokens.yaml following schema]
    G --> H["Output: tokens.yaml with all extracted design tokens"]
```

---

### `*setup`

**Task file:** `.aiox-core/development/tasks/setup-design-system.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `setup-design-system.md` | Task | EXISTS |
| `atomic-design-principles.md` | Data | EXISTS (product/data/) |

**Execution flow:**

```mermaid
flowchart TD
    A["*setup"] --> B[Load setup-design-system.md task]
    B --> C[Elicit: project type, tech stack, framework]
    C --> D[Initialize design system directory structure]
    D --> E[Create Atomic Design folder hierarchy]
    E --> F[Configure tokens, theme, and base styles]
    F --> G["Output: initialized design system structure<br/>(atoms/, molecules/, organisms/, templates/, pages/)"]
```

---

### `*migrate`

**Task file:** `.aiox-core/development/tasks/generate-migration-strategy.md`
**Template:** `.aiox-core/product/templates/migration-strategy-tmpl.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `generate-migration-strategy.md` | Task | EXISTS |
| `migration-strategy-tmpl.md` | Template | EXISTS |
| `migration-readiness-checklist.md` | Checklist | EXISTS (product/checklists/) |

**Execution flow:**

```mermaid
flowchart TD
    A["*migrate"] --> B[Load generate-migration-strategy.md task]
    B --> C[Elicit: current state and target state]
    C --> D[Analyze audit and consolidation data]
    D --> E[Generate 4-phase migration strategy]
    E --> F[Phase 1: Foundation tokens + base]
    F --> G[Phase 2: Atom replacement]
    G --> H[Phase 3: Molecule composition]
    H --> I[Phase 4: Page-level migration]
    I --> J["Output: phased migration plan with timeline"]
```

---

### `*upgrade-tailwind`

**Task file:** `.aiox-core/development/tasks/tailwind-upgrade.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `tailwind-upgrade.md` | Task | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*upgrade-tailwind"] --> B[Load tailwind-upgrade.md task]
    B --> C[Elicit: current Tailwind version]
    C --> D[Analyze current configuration]
    D --> E[Plan upgrade steps to v4]
    E --> F[Generate migration commands]
    F --> G["Output: Tailwind v4 upgrade plan + execution steps"]
```

---

### `*audit-tailwind-config`

**Task file:** `.aiox-core/development/tasks/audit-tailwind-config.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `audit-tailwind-config.md` | Task | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*audit-tailwind-config"] --> B[Load audit-tailwind-config.md task]
    B --> C[Read tailwind.config.js/ts]
    C --> D[Validate configuration health]
    D --> E[Check for conflicts, overrides, unused values]
    E --> F["Output: Tailwind config health report"]
```

---

### `*export-dtcg`

**Task file:** `.aiox-core/development/tasks/export-design-tokens-dtcg.md`
**Templates:** `.aiox-core/product/templates/token-exports-css-tmpl.css`, `.aiox-core/product/templates/token-exports-tailwind-tmpl.js`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `export-design-tokens-dtcg.md` | Task | EXISTS |
| `token-exports-css-tmpl.css` | Template | EXISTS |
| `token-exports-tailwind-tmpl.js` | Template | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*export-dtcg"] --> B[Load export-design-tokens-dtcg.md task]
    B --> C[Read tokens.yaml]
    C --> D[Generate W3C Design Tokens Community Group format]
    D --> E[Export CSS custom properties]
    E --> F[Export Tailwind config]
    F --> G["Output: W3C DTCG bundles<br/>(CSS variables + Tailwind config)"]
```

---

### `*bootstrap-shadcn`

**Task file:** `.aiox-core/development/tasks/bootstrap-shadcn-library.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `bootstrap-shadcn-library.md` | Task | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*bootstrap-shadcn"] --> B[Load bootstrap-shadcn-library.md task]
    B --> C[Elicit: components to install, theme preferences]
    C --> D[Install Shadcn/Radix component library]
    D --> E[Configure theme with design tokens]
    E --> F[Map tokens to Shadcn CSS variables]
    F --> G["Output: configured Shadcn/Radix component library"]
```

---

### `*build {component}`

**Task file:** `.aiox-core/development/tasks/build-component.md`
**Template:** `.aiox-core/product/templates/component-react-tmpl.tsx`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `build-component.md` | Task | EXISTS |
| `component-react-tmpl.tsx` | Template | EXISTS |
| `component-quality-checklist.md` | Checklist | EXISTS (product/checklists/) |

**Execution flow:**

```mermaid
flowchart TD
    A["*build {component}"] --> B[Load build-component.md task]
    B --> C[Load component React template]
    C --> D[Elicit: component name, variants, props]
    D --> E[Determine Atomic Design level - atom/molecule/organism]
    E --> F[Generate TypeScript component]
    F --> G[Generate unit tests]
    G --> H[Generate Storybook stories]
    H --> I[Validate against component quality checklist]
    I --> J["Output: production-ready component<br/>(TypeScript + tests + docs)"]
```

**Personality mode:** Balanced - user needs + system thinking

---

### `*compose {molecule}`

**Task file:** `.aiox-core/development/tasks/compose-molecule.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `compose-molecule.md` | Task | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*compose {molecule}"] --> B[Load compose-molecule.md task]
    B --> C[Elicit: molecule name, constituent atoms]
    C --> D[Verify atoms exist in design system]
    D --> E[Compose molecule from existing atoms]
    E --> F[Generate TypeScript + tests]
    F --> G["Output: molecule component<br/>(e.g., form-field = label + input + error)"]
```

---

### `*extend {component}`

**Task file:** `.aiox-core/development/tasks/extend-pattern.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `extend-pattern.md` | Task | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*extend {component}"] --> B[Load extend-pattern.md task]
    B --> C[Elicit: component name, new variant details]
    C --> D[Load existing component definition]
    D --> E[Add new variant preserving existing API]
    E --> F[Update tests and documentation]
    F --> G["Output: extended component with new variant"]
```

---

### `*document`

**Task file:** `.aiox-core/development/tasks/generate-documentation.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `generate-documentation.md` | Task | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*document"] --> B[Load generate-documentation.md task]
    B --> C[Elicit: documentation scope and format]
    C --> D[Scan design system components]
    D --> E[Generate pattern library documentation]
    E --> F[Include usage examples and guidelines]
    F --> G["Output: comprehensive pattern library docs"]
```

**Personality mode:** Balanced - user needs + system thinking

---

### `*a11y-check`

**Checklist file:** `.aiox-core/product/checklists/accessibility-wcag-checklist.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `accessibility-wcag-checklist.md` | Checklist | EXISTS (product/checklists/) |
| `wcag-compliance-guide.md` | Data | EXISTS (product/data/) |

**Execution flow:**

```mermaid
flowchart TD
    A["*a11y-check"] --> B[Load accessibility-wcag-checklist.md]
    B --> C[Parse checklist items - WCAG AA/AAA criteria]
    C --> D{YOLO mode?}
    D -->|yes| E[Auto-validate all items]
    D -->|no| F[Interactive item-by-item validation]
    E --> G[Generate accessibility report]
    F --> G
    G --> H[Score against WCAG AA minimum]
    H --> I["Output: accessibility report with pass/fail per criterion"]
```

---

### `*calculate-roi`

**Task file:** `.aiox-core/development/tasks/calculate-roi.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `calculate-roi.md` | Task | EXISTS |
| `roi-calculation-guide.md` | Data | EXISTS (product/data/) |

**Execution flow:**

```mermaid
flowchart TD
    A["*calculate-roi"] --> B[Load calculate-roi.md task]
    B --> C[Read audit + consolidation metrics]
    C --> D[Calculate developer time savings]
    D --> E[Calculate maintenance cost reduction]
    E --> F[Calculate consistency improvement value]
    F --> G[Compute ROI multiplier]
    G --> H["Output: ROI report<br/>(e.g., ROI 34.6x, $374k/year savings)"]
```

---

### `*scan {path|url}`

**Task file:** `.aiox-core/development/tasks/ux-ds-scan-artifact.md`
**Template:** `.aiox-core/product/templates/ds-artifact-analysis.md`

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `ux-ds-scan-artifact.md` | Task | EXISTS |
| `ds-artifact-analysis.md` | Template | EXISTS |

**Execution flow:**

```mermaid
flowchart TD
    A["*scan {path|url}"] --> B[Load ux-ds-scan-artifact.md task]
    B --> C{Input type?}
    C -->|path| D[Read local HTML/React files]
    C -->|url| E[Use browser tool to fetch page]
    D --> F[Analyze for design patterns]
    E --> F
    F --> G[Identify atoms, molecules, organisms]
    G --> H[Map to Atomic Design classification]
    H --> I["Output: artifact analysis report"]
```

**Tools used:** browser (for URL scanning)

---

### `*integrate {squad}`

**Task file:** `.aiox-core/development/tasks/integrate-Squad.md` (MISSING)

**Dependencies loaded:**
| File | Type | Status |
|------|------|--------|
| `integrate-Squad.md` | Task | MISSING |
| `integrate-squad.md` | Task | EXISTS (possible intended file) |
| `integration-patterns.md` | Data | EXISTS (product/data/) |

**Note:** The agent definition references `integrate-Squad.md` but only `integrate-squad.md` exists on disk. This may cause a runtime error or the task loader may fall back.

---

### `*help`, `*status`, `*guide`, `*exit`

These are built-in commands handled by the agent framework, not external task files.

| Command | Behavior |
|---------|----------|
| `*help` | Renders full command list organized by 5 phases from `commands[]` in agent definition |
| `*status` | Shows current workflow phase from `.state.yaml` (research/audit/tokenize/build/quality) |
| `*guide` | Renders the `## 🎨 UX Design Expert Guide` section from agent .md |
| `*exit` | Exits UX-Design Expert mode, returns to base Claude Code |

---

## 4. Complete Dependency Graph

```mermaid
graph TD
    subgraph "Agent Definition"
        AD[ux-design-expert.md]
    end

    subgraph "Activation Pipeline (CLI Wrapper)"
        GG[generate-greeting.js]
        GB[greeting-builder.js]
        ACL[agent-config-loader.js]
        SCL[session-context-loader.js]
        PSL[project-status-loader.js]
        GPM[greeting-preference-manager.js]
        CD[context-detector.js]
        GCD[git-config-detector.js]
        WN[workflow-navigator.js]
        PM[permissions/index.js]
    end

    subgraph "Config Files"
        CC[core-config.yaml]
        ACR[agent-config-requirements.yaml]
        WP[workflow-patterns.yaml]
    end

    subgraph "Task Files - Phase 1: UX Research"
        T1[ux-user-research.md]
        T2[ux-create-wireframe.md]
        T3[generate-ai-frontend-prompt.md]
        T4[create-doc.md]
    end

    subgraph "Task Files - Phase 2: Audit"
        T5[audit-codebase.md]
        T6[consolidate-patterns.md]
        T7[generate-shock-report.md]
    end

    subgraph "Task Files - Phase 3: Tokens"
        T8[extract-tokens.md]
        T9[setup-design-system.md]
        T10[generate-migration-strategy.md]
        T11[tailwind-upgrade.md]
        T12[audit-tailwind-config.md]
        T13[export-design-tokens-dtcg.md]
        T14[bootstrap-shadcn-library.md]
    end

    subgraph "Task Files - Phase 4: Build"
        T15[build-component.md]
        T16[compose-molecule.md]
        T17[extend-pattern.md]
    end

    subgraph "Task Files - Phase 5: Quality"
        T18[generate-documentation.md]
        T19[calculate-roi.md]
    end

    subgraph "Task Files - Universal"
        T20[ux-ds-scan-artifact.md]
        T21[run-design-system-pipeline.md]
        T22[execute-checklist.md]
    end

    subgraph "Task Files - MISSING"
        TM1[integrate-Squad.md]
    end

    subgraph "Templates (product/templates/)"
        TP1[front-end-spec-tmpl.yaml]
        TP2[tokens-schema-tmpl.yaml]
        TP3[component-react-tmpl.tsx]
        TP4[state-persistence-tmpl.yaml]
        TP5[shock-report-tmpl.html]
        TP6[migration-strategy-tmpl.md]
        TP7[token-exports-css-tmpl.css]
        TP8[token-exports-tailwind-tmpl.js]
        TP9[ds-artifact-analysis.md]
    end

    subgraph "Checklists (product/checklists/)"
        CL1[pattern-audit-checklist.md]
        CL2[component-quality-checklist.md]
        CL3[accessibility-wcag-checklist.md]
        CL4[migration-readiness-checklist.md]
    end

    subgraph "Data Files (product/data/ + data/)"
        D1[technical-preferences.md]
        D2[atomic-design-principles.md]
        D3[design-token-best-practices.md]
        D4[consolidation-algorithms.md]
        D5[roi-calculation-guide.md]
        D6[integration-patterns.md]
        D7[wcag-compliance-guide.md]
    end

    subgraph "State Management"
        ST[outputs/ux-design/{project}/.state.yaml]
    end

    subgraph "Tools"
        TL1[21st-dev-magic]
        TL2[browser]
    end

    AD --> GG
    GG --> ACL
    GG --> SCL
    GG --> PSL
    GG --> GB
    GB --> CD
    GB --> GCD
    GB --> GPM
    GB --> WN
    GB --> PM
    ACL --> ACR
    ACL --> CC
    WN --> WP

    AD -.->|Phase 1| T1
    AD -.->|Phase 1| T2
    AD -.->|Phase 1| T3
    AD -.->|Phase 1| T4
    AD -.->|Phase 2| T5
    AD -.->|Phase 2| T6
    AD -.->|Phase 2| T7
    AD -.->|Phase 3| T8
    AD -.->|Phase 3| T9
    AD -.->|Phase 3| T10
    AD -.->|Phase 3| T11
    AD -.->|Phase 3| T12
    AD -.->|Phase 3| T13
    AD -.->|Phase 3| T14
    AD -.->|Phase 4| T15
    AD -.->|Phase 4| T16
    AD -.->|Phase 4| T17
    AD -.->|Phase 5| T18
    AD -.->|Phase 5| T19
    AD -.->|Universal| T20
    AD -.->|Universal| T21
    AD -.->|Universal| T22
    AD -.->|MISSING| TM1

    T4 -.->|template| TP1
    T8 -.->|template| TP2
    T15 -.->|template| TP3
    T7 -.->|template| TP5
    T10 -.->|template| TP6
    T13 -.->|template| TP7
    T13 -.->|template| TP8
    T20 -.->|template| TP9

    T5 -.->|checklist| CL1
    T15 -.->|checklist| CL2
    T22 -.->|checklist| CL3
    T10 -.->|checklist| CL4

    T6 -.->|data| D4
    T8 -.->|data| D3
    T9 -.->|data| D2
    T19 -.->|data| D5
    TM1 -.->|data| D6
    T22 -.->|data| D7

    AD -.->|state| ST
    AD -.->|tool| TL1
    AD -.->|tool| TL2
```

---

## 5. Cross-Agent Interactions

| Interaction | Direction | Trigger |
|-------------|-----------|---------|
| @architect -> @ux-design-expert | Collaborate | Frontend architecture, user flows, component hierarchy |
| @ux-design-expert -> @dev | Handoff | Design specs, component blueprints for implementation |
| @ux-design-expert -> @analyst | Collaborate | User research planning, data analysis |
| @ux-design-expert -> @devops | Delegate | Git push operations, PR creation |
| @po -> @ux-design-expert | Receives | Design stories, UX requirements |
| @qa -> @ux-design-expert | Validate | Component quality checklists, accessibility audits |

### Collaboration Rules (from agent definition)

**Receives from @architect (Aria):**
- Frontend architecture and system design guidance
- Component hierarchy and integration patterns
- Technology stack decisions affecting UX

**Hands off to @dev (Dex):**
- Design specifications and component blueprints
- Token definitions and design system configurations
- Component implementations with TypeScript + tests

**Collaborates with @analyst (Alex):**
- User research planning and execution
- Data analysis for design decisions

**Git restrictions (same as all non-devops agents):**
- ALLOWED: `git status`, `git log`, `git diff`, `git branch -a`
- BLOCKED: `git push`, `git push --force`, `gh pr create`

---

## 6. Missing Dependencies

| File | Type | Referenced By | Impact |
|------|------|---------------|--------|
| `integrate-Squad.md` | Task | `*integrate {squad}` | Command non-functional; `integrate-squad.md` exists as possible substitute |

### Notes on Dependency Locations

The agent definition references dependencies using short names (e.g., `.aiox-core/development/tasks/...`). The actual resolution paths are:

| Dependency Type | Agent Definition Path | Actual Disk Location |
|-----------------|----------------------|---------------------|
| Tasks | `.aiox-core/development/tasks/{name}` | `.aiox-core/development/tasks/{name}` |
| Templates | `.aiox-core/product/templates/{name}` | `.aiox-core/product/templates/{name}` |
| Checklists | `.aiox-core/product/checklists/{name}` | `.aiox-core/product/checklists/{name}` |
| Data | `.aiox-core/data/{name}` | `.aiox-core/data/{name}` or `.aiox-core/product/data/{name}` |

All 9 templates, all 4 checklists, and all 7 data files resolve correctly to files in `product/` directories. The `development/data/` directory does not exist; data files live under `.aiox-core/data/` and `.aiox-core/product/data/`.

---

## 7. State Management

The agent tracks workflow state in a single YAML file:

**Location:** `outputs/ux-design/{project}/.state.yaml`

```yaml
# Tracked state dimensions
user_research_complete: boolean
wireframes_created: []
ui_prompts_generated: []
audit_complete: boolean
patterns_inventory: {}
consolidation_complete: boolean
tokens_extracted: boolean
components_built: []
atomic_levels:
  atoms: []
  molecules: []
  organisms: []
accessibility_score: number
wcag_level: 'AA'    # or 'AAA'
roi_calculated: {}
current_phase: research | audit | tokenize | build | quality
workflow_type: greenfield | brownfield | complete
```

**Template for state persistence:** `.aiox-core/product/templates/state-persistence-tmpl.yaml` (EXISTS)

---

## 8. Workflow Paths

| Workflow | Description | Command Sequence |
|----------|-------------|-----------------|
| **complete_ux_to_build** | Full 5-phase pipeline | `*research` -> `*wireframe` -> `*audit` -> `*consolidate` -> `*tokenize` -> `*setup` -> `*build` -> `*document` -> `*a11y-check` |
| **greenfield_only** | New design system from scratch | `*research` -> `*wireframe` -> `*setup` -> `*build` -> `*compose` -> `*document` |
| **brownfield_only** | Improve existing system | `*audit` -> `*consolidate` -> `*tokenize` -> `*migrate` -> `*build` -> `*document` |

### Personality Adaptation by Phase

| Phase | Personality | Style |
|-------|-------------|-------|
| Phase 1 (UX Research) | More Sally | Empathetic, exploratory, user-focused |
| Phase 2 (Audit) | More Brad | Metric-driven, direct, data-focused |
| Phase 3 (Tokens) | More Brad | Metric-driven, direct, data-focused |
| Phase 4 (Build) | Balanced | User needs + system thinking |
| Phase 5 (Quality) | Balanced | User needs + system thinking |

---

*Traced from source on 2026-02-05 | Story AIOX-TRACE-001*