OpenParable
Skip to content
← Back to skills

Team UX Improve

Design
team-ux-improve

Team UX Improve is an Agent Skill for design published in the catlog22/maestro-flow repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/catlog22/maestro-flow/blob/HEAD/.claude/skills/team-ux-improve/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/team-ux-improve, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

<required_reading> @~/.maestro/workflows/run-mode.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

RolePathPrefixInner Loop
coordinatorroles/coordinator/role.md——
scannerroles/scanner/role.mdSCAN-*false
diagnoserroles/diagnoser/role.mdDIAG-*false
designerroles/designer/role.mdDESIGN-*false
implementerroles/implementer/role.mdIMPL-*true
testerroles/tester/role.mdTEST-*false

Utility Member Registry

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

Utility MemberPathCallable ByPurpose
explorerroles/explorer/role.mdCoordinator onlyExplore 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: .workflow/.team/ux-improve-<timestamp>/
  • CLI tools: maestro delegate --mode analysis (read-only), maestro delegate --mode write (modifications)
  • Message bus: mcp__maestro__team_msg(session_id=<session-id>, ...)
  • Max test iterations: 5

Worker Spawn Template

Coordinator spawns workers using this template:

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker for <task-id>",
  team_name: "ux-improve",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: ux-improve
requirement: <task-description>
inner_loop: <true|false>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})

User Commands

CommandAction
check / statusView execution status graph
resume / continueAdvance to next step

Specs Reference

Session Directory

.workflow/.team/ux-improve-<timestamp>/
├── .msg/
│   ├── messages.jsonl      # Team message bus
│   └── meta.json           # Pipeline config + role state snapshot
├── artifacts/              # Role deliverables
│   ├── 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

ScenarioResolution
Unknown commandError with available command list
Role not foundError with role registry
Project path invalidRe-prompt user for valid path
Framework detection failsAskUserQuestion for framework selection
Session corruptionAttempt recovery, fallback to manual
Fast-advance conflictCoordinator reconciles on next callback
No UI issues foundComplete with empty fix list, generate clean bill report
Test iterations exceededAccept current state, continue to completion