team-ux-improve

name	team-ux-improve
description	Unified team skill for UX improvement. Systematically discovers and fixes UI/UX interaction issues including unresponsive buttons, missing feedback, and state refresh problems. Uses team-worker agent architecture with roles/ for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team ux improve".
allowed-tools	["AskUserQuestion","Bash","Edit","Glob","Grep","Read","SendMessage","Write","mcp__maestro__edit_file","mcp__maestro__read_file","mcp__maestro__team_msg","mcp__maestro__write_file","teammate","todo"]
session-mode	run

<required_reading> @~/.maestro/workflows/run-mode-lite.md </required_reading>

Team UX Improve

Systematic UX improvement pipeline: scan -> diagnose -> design -> implement -> test. Built on team-worker agent architecture — all worker roles share a single agent definition with role-specific Phase 2-4 loaded from roles/<role>/role.md.

Architecture

Skill(skill="team-ux-improve", args="<project-path> [--framework react|vue]")
                    |
         SKILL.md (this file) = Router
                    |
     +--------------+--------------+
     |                             |
  no --role flag              --role <name>
     |                             |
  Coordinator                  Worker
  roles/coordinator/role.md    roles/<name>/role.md
     |
     +-- analyze → dispatch → spawn workers → STOP
                                    |
                    +-------+-------+-------+-------+
                    v       v       v       v       v
           [team-worker agents, each loads roles/<role>/role.md]
          scanner  diagnoser  designer  implementer  tester

Role Registry

Role	Path	Prefix	Inner Loop
coordinator	roles/coordinator/role.md	—	—
scanner	roles/scanner/role.md	SCAN-*	false
diagnoser	roles/diagnoser/role.md	DIAG-*	false
designer	roles/designer/role.md	DESIGN-*	false
implementer	roles/implementer/role.md	IMPL-*	true
tester	roles/tester/role.md	TEST-*	false

Utility Member Registry

Coordinator-only: Utility members can only be spawned by Coordinator. Workers CANNOT call teammate() to spawn utility members.

Utility Member	Path	Callable By	Purpose
explorer	roles/explorer/role.md	Coordinator only	Explore codebase for UI component patterns and framework-specific patterns

Pre-load (coordinator, before dispatch)

1. Codebase docs: If .workflow/codebase/ARCHITECTURE.md exists, read for module boundaries
2. Specs (ui): maestro load --type spec --category ui — load ui constraints as shared context
3. Wiki knowledge: maestro search "UX improvement interaction" --json — top 5 entries as prior context
4. All optional — proceed without if unavailable

Role Router

Parse $ARGUMENTS:

• Has --role <name> → Read roles/<name>/role.md, execute Phase 2-4
• No --role → @roles/coordinator/role.md, execute entry router

Shared Constants

• Session prefix: ux-improve
• Session path: {run_dir}/work/team/
• CLI tools: maestro delegate --mode analysis (read-only), maestro delegate --mode write (modifications)
• Message bus: mcp__maestro__team_msg(session_id=<run-id>, ...)
• Max test iterations: 5

Worker Spawn Template

Coordinator spawns workers using this template:

teammate({ agent: "team-worker", name: "<role>", description: "Spawn <role> worker for <task-id>", context: "fresh" })

User Commands

Command	Action
check / status	View execution status graph
resume / continue	Advance to next step

Specs Reference

• specs/pipelines.md — Pipeline definitions and task registry
• specs/design-standards.md — Impeccable visual design standards
• specs/anti-patterns.md — AI slop detection catalog (20 items)
• specs/heuristics.md — Nielsen's 10 usability heuristics evaluation framework

Session Directory

{run_dir}/work/team/
├── .msg/
│   ├── messages.jsonl      # Team message bus
│   └── meta.json           # Pipeline config + role state snapshot
├── {run_dir}/outputs/      # Run deliverables (via maestro run)
│   ├── scan-report.md      # Scanner output
│   ├── diagnosis.md        # Diagnoser output
│   ├── design-guide.md     # Designer output
│   ├── fixes/              # Implementer output
│   └── test-report.md      # Tester output
├── explorations/           # Explorer cache
│   └── cache-index.json
└── wisdom/                 # Session knowledge base
    ├── contributions/      # Worker contributions (write-only for workers)
    ├── principles/
    ├── patterns/
    └── anti-patterns/

Error Handling

Scenario	Resolution
Unknown command	Error with available command list
Role not found	Error with role registry
Project path invalid	Re-prompt user for valid path
Framework detection fails	AskUserQuestion for framework selection
Session corruption	Attempt recovery, fallback to manual
Fast-advance conflict	Coordinator reconciles on next callback
No UI issues found	Complete with empty fix list, generate clean bill report
Test iterations exceeded	Accept current state, continue to completion