Coordinate multiple Claude Code sessions as an agent team to parallelize UX Harness work. Supports 4 modes: audit, migrate, build, review. Dispatches specialized ux- agents for token auditing, component extraction, story generation, accessibility checks, icon cleanup, and style migration.
Coordinate multiple Claude Code sessions as an agent team to parallelize UX Harness work. You are the team lead. Your job is to decompose the objective, spawn specialized ux- teammates, assign tasks with file ownership, coordinate to completion, and shut down cleanly.
$ARGUMENTS — The user's objective. May include flags:
--mode=<audit|migrate|build|review> — Explicit mode selection--full — Force Tier 3 full orchestration (plan-first, wave execution, quality gates)All agents use model: "opus". Lead and every teammate. No exceptions.
Context window exhaustion causes silent state loss in long-running swarms. Check session health before every wave.
./ai_docs/ux-harness/swarm-checkpoint-N.md including:
ux-whats-next skill.whats-next.md to resume the swarm."🛑 STOP orchestration entirely until resumed in a new session.
Extract flags from $ARGUMENTS:
mode = --mode value, or auto-detect from prompt
full = --full flag present (boolean)
remaining = prompt text after flags are removed
If no --mode flag, classify from prompt keywords:
| Signal | Mode |
|---|---|
| "audit", "score", "health", "check", "assess", "onboard" | audit |
| "migrate", "convert", "move", "upgrade", "refactor", "cleanup" | migrate |
| "build", "create", "scaffold", "new component", "compose" | build |
| "review", "guard", "validate", "story", "stories", "storybook" | review |
| Tier | Trigger | Behavior |
|---|---|---|
| 1 | Single component or page, 1-2 clear tasks | 2-3 agents, simple coordination, no plan phase |
| 2 | Multi-component work, 3-5 tasks, one page | Mode-specific team, task dependencies |
| 3 | --full flag OR whole-app migration OR 6+ tasks | Plan-first, wave execution, quality gates |
Before creating any agents:
ux-prime to load the design system context (tokens, Storybook inventory, tier map).agent-1.At Tier 3, before spawning any agents:
ux-audit to establish the baseline health scoreauditParallel assessment from multiple angles. Each agent audits a different concern.
Team structure:
ux-token-auditor — Scans all files for raw Tailwind color/spacing classes vs. semantic tokens. Reports adoption percentage and violation list.ux-accessibility-auditor — Checks every component for aria labels, keyboard navigation, contrast ratios, focus management.Spawn prompt additions for audit teammates:
You are a UX Harness audit agent. Your focus area: [SPECIFIC CONCERN]
Instructions:
1. Run `ux-prime` to load design system context
2. Scan all files in src/ for your concern area
3. Report findings as: file:line, issue, severity (critical/warning/info)
4. Calculate a score for your concern area (0-100)
5. Message the team lead with your structured findings when complete
migrateParallel component/page migration across independent file sets.
Pre-migration gate: Before spawning migration teammates:
ux-audit to establish baseline scoreux-guard to verify token foundation is solidux-guard fails: report to user. Do not spawn migration agents.Team structure:
ux-style-migrator agents (one per page/section) — Each owns a set of files and migrates raw Tailwind → semantic tokens, extracts repeated patterns into components.ux-component-extractor (one per shared component being created) — Extracts duplicated UI patterns into reusable Storybook components in the appropriate section (Components for atomic elements, Widget Garage for composed patterns). Foundations is for design primitives only — don't extract page patterns there.ux-test-writer — Writes/updates tests for migrated components.ux-story-writer to draft Storybook stories for newly migrated components. Does NOT write to disk — drafts require human approval before writing.Spawn prompt template for migration teammates:
You are a UX Harness migration agent. You own these files (ONLY modify these):
{FILE_LIST}
Design system context:
- Token file: {TOKEN_PATH}
- Semantic categories: background, text, border, icon, spacing
- Named spacing scale: xs=4, sm=8, md=16, lg=24, xl=32, 2xl=48
Instructions:
1. Run `ux-prime` to load full context
2. For each file you own:
a. Replace raw Tailwind color classes with semantic tokens (bg-blue-500 → bg-background-primary)
b. Replace numeric spacing with named spacing (gap-2 → gap-sm, p-4 → p-lg)
c. Extract repeated class patterns into component abstractions
d. Ensure all interactive elements have proper aria labels
3. Run `ux-guard` on your changed files before reporting complete
4. If blocked on a shared component, message the team lead
5. Report: files changed, classes converted, violations fixed, issues found
After each wave:
ux-guard on all changed filesux-polish on all changed files — verify style matches Storybook. Fix drift before next wave.ux-audit to measure score deltabuildParallel creation of new components, pages, or features.
Team structure:
ux-component-extractor agents — Each builds a new component from the design specux-test-writer — Writes tests for each new componentux-story-writer to draft stories for approvalSpawn prompt template for build teammates:
You are a UX Harness build agent creating: {COMPONENT_NAME}
Design spec:
{DESIGN_DETAILS}
Instructions:
1. Run `ux-prime` to load design system context
2. Use `ux-component-builder` patterns: semantic tokens only, named spacing only, proper aria labels
3. Place in the correct Storybook section: atomic elements → Components, composed widgets → Widget Garage, page layouts → Page Examples. Never place extracted patterns in Foundations (design primitives only).
4. Export from the appropriate barrel file
5. Run `ux-guard` on your new files before reporting complete
6. Message the team lead with: component path, props contract, Storybook section, any questions
Files you own (ONLY create/modify these): {FILE_LIST}
reviewMulti-perspective design system review of changed files.
Team structure:
ux-token-auditor — Reviews all class usage for semantic token complianceux-accessibility-auditor — Reviews all components for a11y complianceux-story-writer to check Storybook coverage for all changed components. Drafts missing stories for approval — does NOT auto-write.Review flow:
git diff --name-only main...HEAD## Critical
[Must fix — broken a11y, missing tokens, inline SVGs]
## Important
[Should fix — raw Tailwind colors, missing stories, inconsistent spacing]
## Minor
[Consider — naming conventions, story organization, tier classification]
Verdict: Any Critical = FAIL. Only Important = WARN. Only Minor or none = PASS.
Create the team using TeamCreate with a descriptive name (e.g., ux-dashboard-migration, ux-audit-full, ux-component-build).
Create all tasks using TaskCreate with:
subject in imperative form (e.g., "Migrate Dashboard cards to semantic tokens")description with: file paths, token mappings, acceptance criteriaactiveForm in present continuous (e.g., "Migrating Dashboard cards")Set dependencies with addBlockedBy for tasks that require other tasks' outputs.
Organize tasks into dependency-aware waves:
Post-Wave Checkpointing: After every wave, save progress to ./ai_docs/ux-harness/swarm-state.md with: completed files, migration metrics, key decisions, drift discovered.
Spawn teammates using the Task tool with team_name parameter.
All teammates:
model: "opus" — mandatory, no exceptionssubagent_type: "general-purpose"run_in_background: trueAll teammate spawn prompts include:
Begin by reading the project's CLAUDE.md for context and coding standards.
Then run `ux-prime` to load the design system context.
Then work on your assigned task.
After spawning, assign tasks using TaskUpdate with owner set to the agent's name.
As team lead:
SendMessage with type: "message" to specific agents.Before declaring the swarm complete:
TaskList shows every task completedux-guard on all files changed during the swarmux-polish on all files changed during the swarm — verify every migrated/built component visually matches Storybook's established style across all 10 element categories (backgrounds, text, borders, spacing, radius, typography, icons, transitions, hover states, layout). Present drift report to user and fix before proceeding.ux-audit and compare to baseline score (must improve or hold)SendMessage with type: "shutdown_request" to each agentTeamDelete after all teammates shut downThese are the specialized agent roles available for ux-swarm. Each has a dedicated agent definition in agents/.
| Agent | Role | Used in Modes |
|---|---|---|
ux-token-auditor | Scan for raw Tailwind vs. semantic token usage | audit, review |
ux-accessibility-auditor | Check a11y compliance (aria, keyboard, contrast) | audit, review |
ux-component-extractor | Extract repeated patterns into reusable components | migrate, build |
ux-style-migrator | Convert raw Tailwind to semantic tokens | migrate |
ux-test-writer | Write/update component tests | migrate, build |
Note: Storybook story drafting is handled by the ux-story-writer skill (called by the lead), not a dedicated agent.
in_progress.ux-guard on their changed files before reporting complete.