claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-ux-improve/SKILL.md

@@ -1,638 +1,142 @@
----
-name: team-ux-improve
-description: Systematic UX improvement pipeline. Discovers and fixes UI/UX interaction issues including unresponsive buttons, missing feedback, and state refresh problems using scan->diagnose->design->implement->test workflow.
-argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<project-path> [--framework react|vue]\""
-allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, request_user_input
----
-
-## Auto Mode
-
-When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
-
-# UX Improvement Pipeline
-
-## Usage
-
-```bash
-$team-ux-improve "ccw/frontend --framework react"
-$team-ux-improve -c 4 "src/components"
-$team-ux-improve -y "app/ui --framework vue"
-$team-ux-improve --continue "ux-improve-1709856000"
-```
-
-**Flags**:
-- `-y, --yes`: Skip all confirmations (auto mode)
-- `-c, --concurrency N`: Max concurrent agents within each wave (default: 4)
-- `--continue`: Resume existing session
-- `--framework react|vue`: Specify UI framework (auto-detected if omitted)
-
-**Output Directory**: `.workflow/.csv-wave/{session-id}/`
-**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report)
-
----
-
-## Overview
-
-Systematic UX improvement workflow that discovers UI/UX interaction issues (unresponsive buttons, missing feedback, state refresh problems) and fixes them methodically. The pipeline scans for issues, diagnoses root causes, designs solutions, implements fixes, and validates with tests.
-
-**Execution Model**: Hybrid — CSV wave pipeline (primary) + individual agent spawn (secondary)
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                    UX IMPROVEMENT PIPELINE WORKFLOW                      │
-├─────────────────────────────────────────────────────────────────────────┤
-│                                                                          │
-│  Phase 0: Framework Detection & Exploration (Interactive)                │
-│     ├─ Detect UI framework (React/Vue/etc.)                              │
-│     ├─ Explore component patterns and conventions                        │
-│     ├─ Build component inventory                                         │
-│     └─ Output: exploration cache for downstream tasks                    │
-│                                                                          │
-│  Phase 1: Requirement → CSV + Classification                             │
-│     ├─ Generate scan->diagnose->design->implement->test task chain       │
-│     ├─ Classify tasks: csv-wave (scan/implement) | interactive (design)  │
-│     ├─ Compute dependency waves (topological sort → depth grouping)      │
-│     ├─ Generate tasks.csv with wave + exec_mode columns                  │
-│     └─ User validates task breakdown (skip if -y)                        │
-│                                                                          │
-│  Phase 2: Wave Execution Engine (Extended)                               │
-│     ├─ For each wave (1..N):                                             │
-│     │   ├─ Execute pre-wave interactive tasks (design)                   │
-│     │   ├─ Build wave CSV (filter csv-wave tasks for this wave)          │
-│     │   ├─ Inject previous findings into prev_context column             │
-│     │   ├─ spawn_agents_on_csv(wave CSV)                                 │
-│     │   ├─ Execute post-wave interactive tasks (testing)                 │
-│     │   ├─ Merge all results into master tasks.csv                       │
-│     │   └─ Check: any failed? → skip dependents                         │
-│     └─ discoveries.ndjson shared across all modes (append-only)          │
-│                                                                          │
-│  Phase 3: Results Aggregation                                            │
-│     ├─ Export final results.csv                                          │
-│     ├─ Generate context.md with all findings                             │
-│     ├─ Display summary: issues found/fixed, test pass rate               │
-│     └─ Offer: view results | retry failed | done                        │
-│                                                                          │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Task Classification Rules
-
-Each task is classified by `exec_mode`:
-
-| exec_mode | Mechanism | Criteria |
-|-----------|-----------|----------|
-| `csv-wave` | `spawn_agents_on_csv` | One-shot, structured I/O, no multi-round interaction |
-| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Multi-round, clarification, inline utility |
-
-**Classification Decision**:
-
-| Task Property | Classification |
-|---------------|---------------|
-| Scanning tasks (pattern matching, issue detection) | `csv-wave` |
-| Diagnosis tasks (root cause analysis) | `csv-wave` |
-| Design tasks (solution design, user interaction) | `interactive` |
-| Implementation tasks (code fixes) | `csv-wave` |
-| Testing tasks (validation, iteration) | `interactive` |
-| Exploration tasks (framework patterns, component inventory) | `interactive` |
-
----
-
-## CSV Schema
-
-### tasks.csv (Master State)
-
-```csv
-id,title,description,deps,context_from,exec_mode,role,component,wave,status,findings,issues_found,issues_fixed,error
-EXPLORE-001,Framework Exploration,Explore React component patterns and conventions,,,"interactive",explorer,,1,pending,"","","",""
-SCAN-001,Scan for UX issues,Scan components for unresponsive buttons and missing feedback,EXPLORE-001,EXPLORE-001,"csv-wave",scanner,Button,2,pending,"","","",""
-DIAG-001,Diagnose root causes,Analyze root causes of identified UX issues,SCAN-001,SCAN-001,"csv-wave",diagnoser,Button,3,pending,"","","",""
-DESIGN-001,Design solutions,Design fix approach for UX issues,DIAG-001,DIAG-001,"interactive",designer,Button,4,pending,"","","",""
-IMPL-001,Implement fixes,Apply fixes to Button component,DESIGN-001,DESIGN-001,"csv-wave",implementer,Button,5,pending,"","","",""
-TEST-001,Test fixes,Validate fixes and run tests,IMPL-001,IMPL-001,"interactive",tester,Button,6,pending,"","","",""
-```
-
-**Columns**:
-
-| Column | Phase | Description |
-|--------|-------|-------------|
-| `id` | Input | Unique task identifier (string) |
-| `title` | Input | Short task title |
-| `description` | Input | Detailed task description |
-| `deps` | Input | Semicolon-separated dependency task IDs |
-| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
-| `exec_mode` | Input | `csv-wave` or `interactive` |
-| `role` | Input | Role name: explorer, scanner, diagnoser, designer, implementer, tester |
-| `component` | Input | Component name being processed (empty for exploration) |
-| `wave` | Computed | Wave number (computed by topological sort, 1-based) |
-| `status` | Output | `pending` → `completed` / `failed` / `skipped` |
-| `findings` | Output | Key discoveries or implementation notes (max 500 chars) |
-| `issues_found` | Output | Number of issues found (scanner/diagnoser only) |
-| `issues_fixed` | Output | Number of issues fixed (implementer only) |
-| `error` | Output | Error message if failed (empty if success) |
-
-### Per-Wave CSV (Temporary)
-
-Each wave generates a temporary `wave-{N}.csv` with extra `prev_context` column (csv-wave tasks only).
-
----
-
-## Agent Registry (Interactive Agents)
-
-| Agent | Role File | Pattern | Responsibility | Position |
-|-------|-----------|---------|----------------|----------|
-| explorer | ~/.codex/agents/ux-explorer.md | 2.3 | Explore codebase for UI component patterns | pre-wave (Phase 0) |
-| designer | ~/.codex/agents/ux-designer.md | 2.4 | Design fix approach for UX issues | pre-wave (per component) |
-| tester | ~/.codex/agents/ux-tester.md | 2.4 | Validate fixes and run tests | post-wave (per component) |
-
-> **COMPACT PROTECTION**: Agent files are execution documents. When context compression occurs, **you MUST immediately `Read` the corresponding agent.md** to reload.
-
----
-
-## Output Artifacts
-
-| File | Purpose | Lifecycle |
-|------|---------|-----------|
-| `tasks.csv` | Master state — all tasks with status/findings | Updated after each wave |
-| `wave-{N}.csv` | Per-wave input (temporary, csv-wave tasks only) | Created before wave, deleted after |
-| `results.csv` | Final export of all task results | Created in Phase 3 |
-| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
-| `context.md` | Human-readable execution report | Created in Phase 3 |
-| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
-| `agents/registry.json` | Active interactive agent tracking | Updated on spawn/close |
-| `artifacts/scan-report.md` | Scanner findings | Created by scanner |
-| `artifacts/diagnosis.md` | Diagnoser analysis | Created by diagnoser |
-| `artifacts/design-guide.md` | Designer solutions | Created by designer |
-| `artifacts/fixes/` | Implementation files | Created by implementer |
-| `artifacts/test-report.md` | Tester validation | Created by tester |
-
----
-
-## Session Structure
-
-```
-.workflow/.csv-wave/{session-id}/
-├── tasks.csv                  # Master state (all tasks, both modes)
-├── results.csv                # Final results export
-├── discoveries.ndjson         # Shared discovery board (all agents)
-├── context.md                 # Human-readable report
-├── wave-{N}.csv               # Temporary per-wave input (csv-wave only)
-├── interactive/               # Interactive task artifacts
-│   ├── {id}-result.json       # Per-task results
-│   └── cache-index.json       # Shared exploration cache
-├── agents/
-│   └── registry.json          # Active interactive agent tracking
-└── artifacts/                 # Role deliverables
-    ├── scan-report.md
-    ├── diagnosis.md
-    ├── design-guide.md
-    ├── fixes/
-    └── test-report.md
-```
-
----
-
-## Implementation
-
-### Session Initialization
-
-```javascript
-// Parse arguments
-const args = parseArguments($ARGUMENTS)
-const autoYes = args.yes || args.y
-const concurrency = args.concurrency || args.c || 4
-const continueMode = args.continue
-const projectPath = args._[0]
-const framework = args.framework
-
-// Validate project path
-if (!projectPath) {
-  throw new Error("Project path required")
-}
-
-// Generate session ID
-const timestamp = Math.floor(Date.now() / 1000)
-const sessionId = `ux-improve-${timestamp}`
-const sessionDir = `.workflow/.csv-wave/${sessionId}`
-
-// Create session structure
-Bash(`mkdir -p "${sessionDir}/interactive" "${sessionDir}/agents" "${sessionDir}/artifacts/fixes"`)
-
-// Initialize registry
-Write(`${sessionDir}/agents/registry.json`, JSON.stringify({
-  active: [],
-  closed: [],
-  created_at: new Date().toISOString()
-}, null, 2))
-
-// Initialize discoveries
-Write(`${sessionDir}/discoveries.ndjson`, '')
-
-// Store session config
-Write(`${sessionDir}/config.json`, JSON.stringify({
-  project_path: projectPath,
-  framework: framework || "auto-detect",
-  max_test_iterations: 5
-}, null, 2))
-```
-
----
-
-### Phase 0: Framework Detection & Exploration (Interactive)
-
-**Objective**: Detect UI framework and explore component patterns.
-
-```javascript
-// Spawn explorer
-const explorer = spawn_agent({
-  message: `### MANDATORY FIRST STEPS
-1. Read: ~/.codex/agents/ux-explorer.md
-
----
-
-## Task Assignment
-
-**Goal**: Explore codebase for UI component patterns and framework conventions
-
-**Project Path**: ${projectPath}
-
-**Framework**: ${framework || "auto-detect"}
-
-**Session Directory**: ${sessionDir}
-
-**Deliverables**:
-- Framework detection (if auto-detect)
-- Component inventory with file paths
-- Pattern analysis (state management, event handling, styling)
-- Exploration cache for downstream tasks
-
-**Instructions**:
-1. Detect framework if not specified (check package.json, file extensions)
-2. Scan for UI components (*.tsx, *.vue, etc.)
-3. Analyze component patterns and conventions
-4. Build component inventory
-5. Cache findings in explorations/cache-index.json
-6. Output result as JSON with framework and component list`
-})
-
-// Wait for completion
-const result = wait({ ids: [explorer], timeout_ms: 600000 })
-
-if (result.timed_out) {
-  send_input({ id: explorer, message: "Please finalize exploration and output current findings." })
-  const retry = wait({ ids: [explorer], timeout_ms: 120000 })
-}
-
-// Store result
-const explorerOutput = JSON.parse(result.output)
-Write(`${sessionDir}/interactive/EXPLORE-001-result.json`, JSON.stringify({
-  task_id: "EXPLORE-001",
-  status: "completed",
-  findings: explorerOutput.summary,
-  framework: explorerOutput.framework,
-  component_count: explorerOutput.components.length,
-  timestamp: new Date().toISOString()
-}, null, 2))
-
-close_agent({ id: explorer })
-
-// Update config with detected framework
-const config = JSON.parse(Read(`${sessionDir}/config.json`))
-config.framework = explorerOutput.framework
-Write(`${sessionDir}/config.json`, JSON.stringify(config, null, 2))
-```
-
-**Success Criteria**:
-- Framework detected or confirmed
-- Component inventory created
-- Exploration cache available for downstream tasks
-
----
-
-### Phase 1: Requirement → CSV + Classification
-
-**Objective**: Generate task breakdown for UX improvement pipeline per component.
-
-```javascript
-// Load exploration results
-const explorationResult = JSON.parse(Read(`${sessionDir}/interactive/EXPLORE-001-result.json`))
-const components = explorationResult.components || []
-
-// Generate tasks for each component
-const allTasks = []
-let taskCounter = 1
-
-// Add exploration task (already completed)
-allTasks.push({
-  id: "EXPLORE-001",
-  title: "Framework Exploration",
-  description: "Explore component patterns and conventions",
-  deps: "",
-  context_from: "",
-  exec_mode: "interactive",
-  role: "explorer",
-  component: "",
-  wave: 1,
-  status: "completed",
-  findings: explorationResult.findings,
-  issues_found: "",
-  issues_fixed: "",
-  error: ""
-})
-
-// For each component, create pipeline: scan -> diagnose -> design -> implement -> test
-for (const component of components) {
-  const compName = component.name
-  const compPath = component.path
-
-  // Scan task (csv-wave)
-  const scanId = `SCAN-${String(taskCounter).padStart(3, '0')}`
-  allTasks.push({
-    id: scanId,
-    title: `Scan ${compName}`,
-    description: `Scan ${compName} component for UX issues: unresponsive buttons, missing feedback, state refresh problems\n\nFile: ${compPath}`,
-    deps: "EXPLORE-001",
-    context_from: "EXPLORE-001",
-    exec_mode: "csv-wave",
-    role: "scanner",
-    component: compName,
-    wave: 0, // Computed later
-    status: "pending",
-    findings: "",
-    issues_found: "",
-    issues_fixed: "",
-    error: ""
-  })
-
-  // Diagnose task (csv-wave)
-  const diagId = `DIAG-${String(taskCounter).padStart(3, '0')}`
-  allTasks.push({
-    id: diagId,
-    title: `Diagnose ${compName}`,
-    description: `Analyze root causes of UX issues in ${compName}\n\nFile: ${compPath}`,
-    deps: scanId,
-    context_from: scanId,
-    exec_mode: "csv-wave",
-    role: "diagnoser",
-    component: compName,
-    wave: 0,
-    status: "pending",
-    findings: "",
-    issues_found: "",
-    issues_fixed: "",
-    error: ""
-  })
-
-  // Design task (interactive)
-  const designId = `DESIGN-${String(taskCounter).padStart(3, '0')}`
-  allTasks.push({
-    id: designId,
-    title: `Design fixes for ${compName}`,
-    description: `Design fix approach for UX issues in ${compName}\n\nFile: ${compPath}`,
-    deps: diagId,
-    context_from: diagId,
-    exec_mode: "interactive",
-    role: "designer",
-    component: compName,
-    wave: 0,
-    status: "pending",
-    findings: "",
-    issues_found: "",
-    issues_fixed: "",
-    error: ""
-  })
-
-  // Implement task (csv-wave)
-  const implId = `IMPL-${String(taskCounter).padStart(3, '0')}`
-  allTasks.push({
-    id: implId,
-    title: `Implement fixes for ${compName}`,
-    description: `Apply fixes to ${compName} component\n\nFile: ${compPath}`,
-    deps: designId,
-    context_from: designId,
-    exec_mode: "csv-wave",
-    role: "implementer",
-    component: compName,
-    wave: 0,
-    status: "pending",
-    findings: "",
-    issues_found: "",
-    issues_fixed: "",
-    error: ""
-  })
-
-  // Test task (interactive)
-  const testId = `TEST-${String(taskCounter).padStart(3, '0')}`
-  allTasks.push({
-    id: testId,
-    title: `Test fixes for ${compName}`,
-    description: `Validate fixes and run tests for ${compName}\n\nFile: ${compPath}`,
-    deps: implId,
-    context_from: implId,
-    exec_mode: "interactive",
-    role: "tester",
-    component: compName,
-    wave: 0,
-    status: "pending",
-    findings: "",
-    issues_found: "",
-    issues_fixed: "",
-    error: ""
-  })
-
-  taskCounter++
-}
-
-// Compute waves via topological sort
-const tasksWithWaves = computeWaves(allTasks)
-
-// Write master CSV
-writeMasterCSV(`${sessionDir}/tasks.csv`, tasksWithWaves)
-
-// User validation (skip if autoYes)
-if (!autoYes) {
-  const approval = request_user_input({
-    questions: [{
-      id: "task_approval",
-      question: `Generated ${tasksWithWaves.length} tasks for ${components.length} components. Proceed?`,
-      header: "Validate",
-      options: [
-        { label: "Proceed (Recommended)", description: "Start UX improvement pipeline" },
-        { label: "Cancel", description: "Abort workflow" }
-      ]
-    }]
-  })
-
-  if (approval.answers.task_approval.answers[0] !== "Proceed (Recommended)") {
-    throw new Error("User cancelled workflow")
-  }
-}
-```
-
-**Success Criteria**:
-- tasks.csv created with valid schema, wave, and exec_mode assignments
-- No circular dependencies
-- User approved (or AUTO_YES)
-
----
-
-### Phase 2: Wave Execution Engine (Extended)
-
-**Objective**: Execute tasks wave-by-wave with hybrid mechanism support.
-
-(Implementation follows same pattern as team-roadmap-dev Phase 2, adapted for UX improvement roles)
-
----
-
-### Phase 3: Results Aggregation
-
-**Objective**: Generate final results and human-readable report.
-
-```javascript
-// Load final master CSV
-const finalCSV = readMasterCSV(`${sessionDir}/tasks.csv`)
-
-// Calculate metrics
-const completed = finalCSV.filter(t => t.status === 'completed').length
-const failed = finalCSV.filter(t => t.status === 'failed').length
-const skipped = finalCSV.filter(t => t.status === 'skipped').length
-const totalIssuesFound = finalCSV.reduce((sum, t) => sum + (parseInt(t.issues_found) || 0), 0)
-const totalIssuesFixed = finalCSV.reduce((sum, t) => sum + (parseInt(t.issues_fixed) || 0), 0)
-
-// Export results.csv
-writeFinalResults(`${sessionDir}/results.csv`, finalCSV)
-
-// Generate context.md
-const contextMd = generateUXContextReport(finalCSV, sessionDir, {
-  totalIssuesFound,
-  totalIssuesFixed
-})
-Write(`${sessionDir}/context.md`, contextMd)
-
-// Cleanup active agents
-const registry = JSON.parse(Read(`${sessionDir}/agents/registry.json`))
-for (const agent of registry.active) {
-  close_agent({ id: agent.id })
-}
-registry.active = []
-Write(`${sessionDir}/agents/registry.json`, JSON.stringify(registry, null, 2))
-
-// Display summary
-console.log(`\n=== UX Improvement Pipeline Complete ===`)
-console.log(`Completed: ${completed}`)
-console.log(`Failed: ${failed}`)
-console.log(`Skipped: ${skipped}`)
-console.log(`Issues Found: ${totalIssuesFound}`)
-console.log(`Issues Fixed: ${totalIssuesFixed}`)
-console.log(`Fix Rate: ${totalIssuesFound > 0 ? Math.round(totalIssuesFixed / totalIssuesFound * 100) : 0}%`)
-console.log(`\nResults: ${sessionDir}/results.csv`)
-console.log(`Report: ${sessionDir}/context.md`)
-
-// Offer next steps
-const nextStep = request_user_input({
-  questions: [{
-    id: "completion",
-    question: "UX Improvement pipeline complete. What would you like to do?",
-    header: "Done",
-    options: [
-      { label: "Archive (Recommended)", description: "Archive session and clean up team resources" },
-      { label: "Keep Active", description: "Keep session for follow-up work" }
-    ]
-  }]
-})
-
-if (nextStep.answers.completion.answers[0] === "Archive (Recommended)") {
-  Bash(`tar -czf "${sessionDir}.tar.gz" "${sessionDir}" && rm -rf "${sessionDir}"`)
-  console.log(`Session archived to ${sessionDir}.tar.gz`)
-}
-```
-
-**Success Criteria**:
-- results.csv exported with UX metrics
-- context.md generated with issue summary
-- All interactive agents closed
-- Summary displayed to user
-
----
-
-## Shared Discovery Board Protocol
-
-All agents share `discoveries.ndjson` for UX findings.
-
-**Discovery Types**:
-
-| Type | Dedup Key | Data Schema | Description |
-|------|-----------|-------------|-------------|
-| `ux_issue` | `component+type` | `{component, type, description, severity}` | UX issues discovered |
-| `pattern` | `pattern` | `{pattern, files[], description}` | UI patterns identified |
-| `fix_approach` | `component+issue` | `{component, issue, approach, rationale}` | Fix strategies |
-| `test_result` | `component+test` | `{component, test, status, details}` | Test outcomes |
-
----
-
-## Error Handling
-
-| Error | Resolution |
-|-------|------------|
-| Framework detection fails | request_user_input for framework selection |
-| No components found | Complete with empty report, note in findings |
-| Circular dependency | Detect in wave computation, abort with error |
-| CSV agent timeout | Mark as failed, continue with wave |
-| Interactive agent timeout | Urge convergence via send_input |
-| Test iterations exceeded (5) | Accept current state, continue |
-| All agents in wave failed | Log error, offer retry or abort |
-| Project path invalid | Re-prompt user for valid path |
-
----
-
-## Core Rules
-
-1. **Start Immediately**: First action is session initialization, then Phase 0
-2. **Wave Order is Sacred**: Never execute wave N before wave N-1 completes
-3. **CSV is Source of Truth**: Master tasks.csv holds all state
-4. **CSV First**: Default to csv-wave; use interactive for design/testing
-5. **Context Propagation**: prev_context built from master CSV
-6. **Discovery Board is Append-Only**: Never clear discoveries.ndjson
-7. **Skip on Failure**: If dependency failed, skip dependent task
-8. **Lifecycle Balance**: Every spawn_agent has matching close_agent
-9. **Cleanup Temp Files**: Remove wave-{N}.csv after merge
-10. **DO NOT STOP**: Continuous execution until all waves complete
-
-
----
-
-## Coordinator Role Constraints (Main Agent)
-
-**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
-
-15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
-    - Spawns agents with task assignments
-    - Waits for agent callbacks
-    - Merges results and coordinates workflow
-    - Manages workflow transitions between phases
-
-16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
-    - Wait patiently for `wait()` calls to complete
-    - NOT skip workflow steps due to perceived delays
-    - NOT assume agents have failed just because they're taking time
-    - Trust the timeout mechanisms defined in the skill
-
-17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
-    - Use `send_input()` to ask questions or provide clarification
-    - NOT skip the agent or move to next phase prematurely
-    - Give agents opportunity to respond before escalating
-    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
-
-18. **No Workflow Shortcuts**: The coordinator MUST NOT:
-    - Skip phases or stages defined in the workflow
-    - Bypass required approval or review steps
-    - Execute dependent tasks before prerequisites complete
-    - Assume task completion without explicit agent callback
-    - Make up or fabricate agent results
-
-19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
-    - Total execution time may range from 30-90 minutes or longer
-    - Each phase may take 10-30 minutes depending on complexity
-    - The coordinator must remain active and attentive throughout the entire process
-    - Do not terminate or skip steps due to time concerns
+---
+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: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__read_file(*), mcp__ccw-tools__write_file(*), mcp__ccw-tools__edit_file(*), mcp__ccw-tools__team_msg(*)
+---
+
+# 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](roles/coordinator/role.md) | — | — |
+| scanner | [roles/scanner/role.md](roles/scanner/role.md) | SCAN-* | false |
+| diagnoser | [roles/diagnoser/role.md](roles/diagnoser/role.md) | DIAG-* | false |
+| designer | [roles/designer/role.md](roles/designer/role.md) | DESIGN-* | false |
+| implementer | [roles/implementer/role.md](roles/implementer/role.md) | IMPL-* | true |
+| tester | [roles/tester/role.md](roles/tester/role.md) | TEST-* | false |
+
+## Utility Member Registry
+
+**Coordinator-only**: Utility members can only be spawned by Coordinator. Workers CANNOT call spawn_agent() to spawn utility members.
+
+| Utility Member | Path | Callable By | Purpose |
+|----------------|------|-------------|---------|
+| explorer | [roles/explorer/role.md](roles/explorer/role.md) | Coordinator only | Explore codebase for UI component patterns and framework-specific patterns |
+
+## 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**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
+- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
+- **Max test iterations**: 5
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+spawn_agent({
+  agent_type: "team_worker",
+  items: [
+    { type: "text", text: `## Role Assignment
+role: <role>
+role_spec: <skill_root>/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+requirement: <task-description>
+inner_loop: <true|false>
+
+Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },
+
+    { type: "text", text: `## Task Context
+task_id: <task-id>
+title: <task-title>
+description: <task-description>
+pipeline_phase: <pipeline-phase>` },
+
+    { type: "text", text: `## Upstream Context
+<prev_context>` }
+  ]
+})
+```
+
+After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
+
+## 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
+
+| 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 | request_user_input 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 |