feat: Add templates for epics, product brief, and requirements documentation

- Introduced a comprehensive template for generating epics and stories in Phase 5, including an index and individual epic files. - Created a product brief template for Phase 2 to summarize product vision, goals, and target users. - Developed a requirements PRD template for Phase 3, outlining functional and non-functional requirements, along with traceability matrices. feat: Implement tech debt roles for assessment, execution, planning, scanning, validation, and analysis - Added roles for tech debt assessment, executor, planner, scanner, validator, and analyst, each with defined phases and processes for managing technical debt. - Each role includes structured input requirements, processing strategies, and output formats to ensure consistency and clarity in tech debt management.
2026-03-10 17:11:04 +08:00 · 2026-03-07 13:32:04 +08:00
parent 7ee9b579fa
commit 29a1fea467
255 changed files with 14407 additions and 21120 deletions
--- a/.claude/skills/team-ux-improve/SKILL.md
+++ b/.claude/skills/team-ux-improve/SKILL.md
@@ -1,289 +1,135 @@
 ---
 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 role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "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: Agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, TaskList, TaskGet, TaskUpdate, TaskCreate, TeamCreate, TeamDelete, SendMessage, 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

-Unified team skill for systematically discovering and fixing UI/UX interaction issues. Built on **team-worker agent architecture** — all worker roles share a single agent definition with role-specific Phase 2-4 loaded from markdown specs.
+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(skill="team-ux-improve", args="<project-path> [--framework react|vue]")
                    |
-         Orchestration Mode (auto -> coordinator)
+         SKILL.md (this file) = Router
                    |
-              Coordinator (inline)
-              Phase 0-5 orchestration
-                    |
-    +-------+-------+-------+-------+-------+
-    v       v       v       v       v       v
- [team-worker agents, each loaded with a role-spec]
-  scanner  diagnoser  designer  implementer  tester
-
-  Utility Members (spawned by coordinator for utility work):
-    [explorer]
+     +--------------+--------------+
+     |                             |
+  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 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

-This skill is **coordinator-only**. Workers do NOT invoke this skill — they are spawned as `team-worker` agents directly.
+Parse `$ARGUMENTS`:
+- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` → Read `roles/coordinator/role.md`, execute entry router

-### Input Parsing
+## Shared Constants

-Parse `$ARGUMENTS`. No `--role` needed — always routes to coordinator.
+- **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

-### Role Registry
+## Worker Spawn Template

-| Role | Spec | Task Prefix | Type | Inner Loop |
-|------|------|-------------|------|------------|
-| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | - |
-| scanner | [role-specs/scanner.md](role-specs/scanner.md) | SCAN-* | worker | false |
-| diagnoser | [role-specs/diagnoser.md](role-specs/diagnoser.md) | DIAG-* | worker | false |
-| designer | [role-specs/designer.md](role-specs/designer.md) | DESIGN-* | worker | false |
-| implementer | [role-specs/implementer.md](role-specs/implementer.md) | IMPL-* | worker | true |
-| tester | [role-specs/tester.md](role-specs/tester.md) | TEST-* | worker | false |
-
-### Utility Member Registry
-
-**⚠️ COORDINATOR ONLY**: Utility members can only be spawned by Coordinator. Workers CANNOT call Agent() to spawn utility members. Workers must use CLI tools instead.
-
-| Utility Member | Spec | Callable By | Purpose |
-|----------------|------|-------------|---------|
-| explorer | [role-specs/explorer.md](role-specs/explorer.md) | **Coordinator only** | Explore codebase for UI component patterns, state management conventions, and framework-specific patterns |
-
-### Worker Alternatives
-
-Workers needing similar capabilities must use CLI tools:
-
-| Capability | CLI Command | Example |
-|------------|-------------|---------|
-| Codebase exploration | `ccw cli --tool gemini --mode analysis` | Explore architecture patterns |
-| Multi-perspective critique | Parallel CLI calls | Security + performance + quality reviews |
-| Document generation | `ccw cli --tool gemini --mode write` | Generate implementation guide |
-
-### Dispatch
-
-Always route to coordinator. Coordinator reads `roles/coordinator/role.md` and executes its phases.
-
-### Orchestration Mode
-
-User provides project path and optional framework flag.
-
-**Invocation**: `Skill(skill="team-ux-improve", args="<project-path> [--framework react|vue]")`
-
-**Lifecycle**:
-```
-User provides project path
-  -> coordinator Phase 1-3: Requirement clarification -> TeamCreate -> Create task chain
-  -> coordinator Phase 4: spawn first batch workers (background) -> STOP
-  -> Worker (team-worker agent) executes -> SendMessage callback -> coordinator advances
-  -> Loop until pipeline complete -> Phase 5 report + completion action
-```
-
-**User Commands** (wake paused coordinator):
-
-| Command | Action |
-|---------|--------|
-| `check` / `status` | Output execution status graph, no advancement |
-| `resume` / `continue` | Check worker states, advance next step |
-
---
-
-## Command Execution Protocol
-
-When coordinator needs to execute a command (dispatch, monitor):
-
-1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
-2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
-3. **Commands are inline execution guides** - NOT separate agents or subprocesses
-4. **Execute synchronously** - complete the command workflow before proceeding
-
-Example:
-```
-Phase 3 needs task dispatch
-  -> Read roles/coordinator/commands/dispatch.md
-  -> Execute Phase 2 (Context Loading)
-  -> Execute Phase 3 (Task Chain Creation)
-  -> Execute Phase 4 (Validation)
-  -> Continue to Phase 4
-```
-
---
-
-## Coordinator Spawn Template
-
-### v5 Worker Spawn (all roles)
-
-When coordinator spawns workers, use `team-worker` agent with role-spec path:
+Coordinator spawns workers using this template:

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

 Read role_spec file to load Phase 2-4 domain instructions.
-Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

-**Inner Loop roles** (implementer): Set `inner_loop: true`. The team-worker agent handles the loop internally.
+## User Commands

-**Single-task roles** (scanner, diagnoser, designer, tester): Set `inner_loop: false`.
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |

---
+## Specs Reference

-## Pipeline Definitions
-
-### Pipeline Diagram
-
-```
-scanner (SCAN) → diagnoser (DIAG) → designer (DESIGN) → implementer (IMPL) → tester (TEST)
-
-Stage 1: UI Scanning
-  └─ scanner: Scan UI components for interaction issues
-
-Stage 2: Root Cause Diagnosis
-  └─ diagnoser: Diagnose root causes of identified issues
-
-Stage 3: Solution Design
-  └─ designer: Design feedback mechanisms and state management solutions
-
-Stage 4: Code Implementation
-  └─ implementer: Generate fix code with proper state handling
-
-Stage 5: Test Validation
-  └─ tester: Generate and run tests to verify fixes
-```
-
-### Cadence Control
-
-**Beat model**: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP.
-
-```
-Beat Cycle (single beat)
-======================================================================
-  Event                   Coordinator              Workers
----------------------------------------------------------------------
-  callback/resume --> +- handleCallback -+
-                      |  mark completed   |
-                      |  check pipeline   |
-                      +- handleSpawnNext -+
-                      |  find ready tasks |
-                      |  spawn workers ---+--> [team-worker scanner] Phase 1-5
-                      |  (parallel OK)  --+--> [team-worker diagnoser] Phase 1-5
-                      +- STOP (idle) -----+         |
-                                                     |
-  callback <-----------------------------------------+
-  (next beat)              SendMessage + TaskUpdate(completed)
-======================================================================
-
-  Fast-Advance (skips coordinator for simple linear successors)
-======================================================================
-  [Worker scanner] Phase 5 complete
-    +- 1 ready task? simple successor?
-    |   --> spawn team-worker diagnoser directly
-    |   --> log fast_advance to message bus (coordinator syncs on next wake)
-    +- complex case? --> SendMessage to coordinator
-======================================================================
-```
-
-**Checkpoints**:
-
-| Checkpoint | Trigger | Location | Behavior |
-|------------|---------|----------|----------|
-| Pipeline complete | All tasks completed | coordinator Phase 5 | Execute completion action |
-
-### Task Metadata Registry
-
-| Task ID | Role | Phase | Dependencies | Description |
-|---------|------|-------|-------------|-------------|
-| SCAN-001 | scanner | 2-4 | [] | Scan UI components for interaction issues |
-| DIAG-001 | diagnoser | 2-4 | [SCAN-001] | Diagnose root causes of identified issues |
-| DESIGN-001 | designer | 2-4 | [DIAG-001] | Design feedback mechanisms and state management solutions |
-| IMPL-001 | implementer | 2-4 | [DESIGN-001] | Generate fix code with proper state handling |
-| TEST-001 | tester | 2-4 | [IMPL-001] | Generate and run tests to verify fixes |
-
---
-
-## Completion Action
-
-When the pipeline completes (all tasks done, coordinator Phase 5):
-
-```
-AskUserQuestion({
-  questions: [{
-    question: "Team pipeline complete. What would you like to do?",
-    header: "Completion",
-    multiSelect: false,
-    options: [
-      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
-      { label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
-      { label: "Export Results", description: "Export deliverables to a specified location, then clean" }
-    ]
-  }]
-})
-```
-
-| Choice | Action |
-|--------|--------|
-| Archive & Clean | Update session status="completed" -> TeamDelete(ux-improve) -> output final summary |
-| Keep Active | Update session status="paused" -> output resume instructions: `Skill(skill="team-ux-improve", args="resume")` |
-| Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean |
-
---
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry

 ## Session Directory

 ```
 .workflow/.team/ux-improve-<timestamp>/
 ├── .msg/
-│   ├── messages.jsonl     ← Messages + state_update audit log
-│   └── 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
+│   ├── 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/        ← Core principles
-    │   └── general-ux.md
-    ├── patterns/          ← Solution patterns
-    │   ├── ui-feedback.md
-    │   └── state-management.md
-    └── anti-patterns/     ← Issues to avoid
-        └── common-ux-pitfalls.md
+└── wisdom/                 # Session knowledge base
+    ├── contributions/      # Worker contributions (write-only for workers)
+    ├── principles/
+    ├── patterns/
+    └── anti-patterns/
 ```

 ## Error Handling

 | Scenario | Resolution |
 |----------|------------|
-| Role spec file not found | Error with expected path (role-specs/<name>.md) |
-| Command file not found | Fallback to inline execution in coordinator role.md |
-| Utility member spec not found | Error with expected path (role-specs/explorer.md) |
-| Fast-advance orphan detected | Coordinator resets task to pending on next check |
-| team-worker agent unavailable | Error: requires .claude/agents/team-worker.md |
-| Completion action timeout | Default to Keep Active |
-| Framework detection fails | Prompt user for framework selection |
-| No UI issues found | Complete with empty fix list |
+| 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 |
--- a/.claude/skills/team-ux-improve/roles/coordinator/commands/analyze.md
+++ b/.claude/skills/team-ux-improve/roles/coordinator/commands/analyze.md
@@ -0,0 +1,62 @@
+# Analyze Task
+
+Parse user task -> detect UX improvement scope -> assess complexity -> determine pipeline configuration.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Signal | Pipeline Hint |
+|----------|--------|---------------|
+| button, click, tap, unresponsive | interaction-issues | standard |
+| loading, spinner, feedback, progress | feedback-missing | standard |
+| state, refresh, update, stale | state-issues | standard |
+| form, input, validation, error | input-issues | standard |
+| accessibility, a11y, keyboard, screen reader | accessibility | standard |
+| performance, slow, lag, freeze | performance | standard |
+| all, full, complete, comprehensive | full-scope | standard |
+
+## Framework Detection
+
+| Keywords | Framework |
+|----------|-----------|
+| react, jsx, tsx, useState, useEffect | React |
+| vue, .vue, ref(), reactive(), v-model | Vue |
+| angular, ng-, @Component | Angular |
+| Default | auto-detect |
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Single component scope | +1 |
+| Multiple components | +2 |
+| Full project scope | +3 |
+| Accessibility required | +1 |
+| Performance issues | +1 |
+| Complex state management | +1 |
+
+Results: 1-2 Low (targeted fix), 3-4 Medium (standard pipeline), 5+ High (full pipeline)
+
+## Scope Determination
+
+| Signal | Pipeline Mode |
+|--------|---------------|
+| Specific component or file mentioned | targeted |
+| Multiple issues or general project | standard |
+| "Full audit" or "complete scan" | standard |
+| Unclear | ask user |
+
+## Output
+
+Write scope context to coordinator memory:
+```json
+{
+  "pipeline_mode": "standard",
+  "project_path": "<detected-or-provided-path>",
+  "framework": "<react|vue|angular|auto>",
+  "scope": "<detected-scope>",
+  "issue_signals": ["interaction", "feedback", "state"],
+  "complexity": { "score": 0, "level": "Low|Medium|High" }
+}
+```
--- a/.claude/skills/team-ux-improve/roles/coordinator/commands/dispatch.md
+++ b/.claude/skills/team-ux-improve/roles/coordinator/commands/dispatch.md
@@ -47,8 +47,7 @@ CONSTRAINTS: <scope limits, focus areas>
 ---
 InnerLoop: <true|false>
 <additional-metadata-fields>",
-  blockedBy: [<dependency-list>],
-  status: "pending"
+  blockedBy: [<dependency-list>]
 })
 ```

--- a/.claude/skills/team-ux-improve/roles/coordinator/commands/monitor.md
+++ b/.claude/skills/team-ux-improve/roles/coordinator/commands/monitor.md
@@ -1,131 +1,154 @@
-# Monitor Command
+# Monitor Pipeline

-## Purpose
+Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.

-Handle worker callbacks, status checks, pipeline advancement, and completion detection.
+## Constants

---
+- SPAWN_MODE: background
+- ONE_STEP_PER_INVOCATION: true
+- FAST_ADVANCE_AWARE: true
+- WORKER_AGENT: team-worker
+- MAX_TEST_ITERATIONS: 5

-## Handlers
+## Handler Router

-### handleCallback
+| Source | Handler |
+|--------|---------|
+| Message contains [scanner], [diagnoser], [designer], [implementer], [tester] | handleCallback |
+| "capability_gap" | handleAdapt |
+| "check" or "status" | handleCheck |
+| "resume" or "continue" | handleResume |
+| All tasks completed | handleComplete |
+| Default | handleSpawnNext |

-**Trigger**: Worker SendMessage with `[scanner]`, `[diagnoser]`, `[designer]`, `[implementer]`, or `[tester]` tag.
+## handleCallback

-1. Parse worker role from message tag
-2. Mark corresponding task as completed: `TaskUpdate({ taskId: <task-id>, status: "completed" })`
-3. Log completion to message bus:
+Worker completed. Process and advance.
+
+1. Parse message to identify role and task ID:
+
+| Message Pattern | Role |
+|----------------|------|
+| `[scanner]` or `SCAN-*` | scanner |
+| `[diagnoser]` or `DIAG-*` | diagnoser |
+| `[designer]` or `DESIGN-*` | designer |
+| `[implementer]` or `IMPL-*` | implementer |
+| `[tester]` or `TEST-*` | tester |
+
+2. Check if progress update (inner loop) or final completion
+3. Progress update -> update session state, STOP
+4. Completion -> mark task done:
   ```
-   team_msg(operation="log", session_id=<session-id>, from="coordinator",
-            type="task_complete", data={ role: <role>, task_id: <task-id> })
+   TaskUpdate({ taskId: "<task-id>", status: "completed" })
   ```
-4. Check if all tasks completed -> handleComplete
-5. Otherwise -> handleSpawnNext
+5. Remove from active_workers, record completion in session

-### handleCheck
+6. Check for checkpoints:
+   - **TEST-001 completes** -> Validation Gate:
+     Read test results from `.msg/meta.json`

-**Trigger**: User "check" or "status" command.
+     | Condition | Action |
+     |-----------|--------|
+     | pass_rate >= 95% | -> handleSpawnNext (pipeline likely complete) |
+     | pass_rate < 95% AND iterations < max | Log warning, still -> handleSpawnNext |
+     | pass_rate < 95% AND iterations >= max | Accept current state -> handleComplete |

-1. Load TaskList
-2. Build status graph:
-   ```
-   Pipeline Status:
-   ✅ SCAN-001 (scanner) - completed
-   ✅ DIAG-001 (diagnoser) - completed
-   🔄 DESIGN-001 (designer) - in_progress
-   ⏳ IMPL-001 (implementer) - pending [blocked by DESIGN-001]
-   ⏳ TEST-001 (tester) - pending [blocked by IMPL-001]
-   ```
-3. Output status graph, do NOT advance pipeline
-4. STOP
+7. -> handleSpawnNext

-### handleResume
+## handleCheck

-**Trigger**: User "resume" or "continue" command.
+Read-only status report, then STOP.

-1. Load TaskList
-2. Check for fast-advance orphans:
-   - Tasks with status "in_progress" but no active worker
-   - Reset orphans to "pending"
-3. -> handleSpawnNext
+```
+Pipeline Status (standard):
+  [DONE]  SCAN-001    (scanner)     -> artifacts/scan-report.md
+  [DONE]  DIAG-001    (diagnoser)   -> artifacts/diagnosis.md
+  [RUN]   DESIGN-001  (designer)    -> designing solutions...
+  [WAIT]  IMPL-001    (implementer) -> blocked by DESIGN-001
+  [WAIT]  TEST-001    (tester)      -> blocked by IMPL-001

-### handleSpawnNext
+Session: <session-id>
+Commands: 'resume' to advance | 'check' to refresh
+```

-**Trigger**: After handleCallback or handleResume.
+Output status -- do NOT advance pipeline.

-1. Load TaskList
-2. Find ready tasks:
-   - status = "pending"
-   - All blockedBy tasks have status "completed"
-3. For each ready task:
-   - Extract role from task owner
-   - Extract inner_loop from task description metadata
-   - Spawn team-worker agent:
-     ```
-     Agent({
-       subagent_type: "team-worker",
-       description: "Spawn <role> worker",
-       team_name: "ux-improve",
-       name: "<role>",
-       run_in_background: true,
-       prompt: `## Role Assignment
-     role: <role>
-     role_spec: .claude/skills/team-ux-improve/role-specs/<role>.md
-     session: <session-folder>
-     session_id: <session-id>
-     team_name: ux-improve
-     requirement: <task-description>
-     inner_loop: <inner-loop-value>
+## handleResume

-     Read role_spec file to load Phase 2-4 domain instructions.
-     Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
-     })
-     ```
-4. STOP (wait for next callback)
+1. Audit task list for inconsistencies:
+   - Tasks stuck in "in_progress" -> reset to "pending"
+   - Tasks with completed blockers but still "pending" -> include in spawn list
+2. -> handleSpawnNext

-### handleConsensus
+## handleSpawnNext

-**Trigger**: consensus_blocked message from worker.
+Find ready tasks, spawn workers, STOP.

-Route by severity:
+1. Collect: completedSubjects, inProgressSubjects, readySubjects (pending + all blockedBy completed)
+2. No ready + work in progress -> report waiting, STOP
+3. No ready + nothing in progress -> handleComplete
+4. Has ready -> for each:
+   a. Check inner loop role with active worker -> skip (worker picks up)
+   b. TaskUpdate -> in_progress
+   c. team_msg log -> task_unblocked
+   d. Spawn team-worker:

-| Severity | Action |
-|----------|--------|
-| HIGH | Pause pipeline, AskUserQuestion for resolution |
-| MEDIUM | Log warning, continue pipeline |
-| LOW | Log info, continue pipeline |
+```
+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: .claude/skills/team-ux-improve/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: ux-improve
+requirement: <task-description>
+inner_loop: <true|false>

-### handleComplete
+Read role_spec file to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+```

-**Trigger**: All tasks have status "completed".
+Stage-to-role mapping:
+| Task Prefix | Role |
+|-------------|------|
+| SCAN | scanner |
+| DIAG | diagnoser |
+| DESIGN | designer |
+| IMPL | implementer |
+| TEST | tester |

-1. Verify all tasks completed via TaskList
-2. Generate pipeline summary:
-   - Total tasks: 5
-   - Duration: <calculated>
-   - Deliverables: list artifact paths
-3. Execute completion action (see coordinator Phase 5)
+Inner loop roles: implementer (inner_loop: true)
+Single-task roles: scanner, diagnoser, designer, tester (inner_loop: false)

---
+5. Add to active_workers, update session, output summary, STOP

-## Fast-Advance Detection
+## handleComplete

-When handleCallback detects a completed task:
+Pipeline done. Generate report and completion action.

-| Condition | Action |
-|-----------|--------|
-| Exactly 1 ready successor, simple linear | Worker already fast-advanced, log sync |
-| Multiple ready successors | Coordinator spawns all |
-| No ready successors, all done | -> handleComplete |
-| No ready successors, some pending | Wait (blocked tasks) |
+1. Verify all tasks (including any fix-verify iterations) have status "completed"
+2. If any tasks not completed -> handleSpawnNext
+3. If all completed -> transition to coordinator Phase 5

---
+## handleAdapt

-## Error Handling
+Capability gap reported mid-pipeline.

-| Scenario | Resolution |
-|----------|------------|
-| Worker callback with unknown role | Log warning, ignore |
-| Task not found for callback | Log error, check TaskList |
-| Spawn fails | Mark task as failed, log error, try next ready task |
-| All tasks failed | Report failure, execute completion action |
+1. Parse gap description
+2. Check if existing role covers it -> redirect
+3. Role count < 5 -> generate dynamic role spec
+4. Create new task, spawn worker
+5. Role count >= 5 -> merge or pause
+
+## Fast-Advance Reconciliation
+
+On every coordinator wake:
+1. Read team_msg entries with type="fast_advance"
+2. Sync active_workers with spawned successors
+3. No duplicate spawns
--- a/.claude/skills/team-ux-improve/roles/coordinator/role.md
+++ b/.claude/skills/team-ux-improve/roles/coordinator/role.md
@@ -1,263 +1,139 @@
 # Coordinator Role

-## Identity
+UX Improvement Team coordinator. Orchestrate pipeline: analyze -> dispatch -> spawn -> monitor -> report. Systematically discovers and fixes UI/UX interaction issues.

- **Name**: coordinator
- **Type**: Orchestration
- **Responsibility**: Orchestrate UX improvement pipeline, spawn workers, monitor progress, handle completion
+## Identity
+- **Name**: coordinator | **Tag**: [coordinator]
+- **Responsibility**: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results

 ## Boundaries

 ### MUST
-
- Parse user requirements (project path, framework)
- Create team and session structure
- Generate task chain via dispatch.md
- Spawn team-worker agents with correct role-spec paths
- Monitor worker callbacks and advance pipeline
- Execute completion action when pipeline finishes
- Handle user commands (check, resume)
+- All output (SendMessage, team_msg, logs) must carry `[coordinator]` identifier
+- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
+- Parse project_path and framework from arguments
+- Dispatch tasks with proper dependency chains and blockedBy
+- Monitor worker progress via message bus and route messages
+- Handle wisdom initialization and consolidation
+- Maintain session state persistence

 ### MUST NOT
-
- Execute worker domain logic directly
+- Execute worker domain logic directly (scanning, diagnosing, designing, implementing, testing)
+- Spawn workers without creating tasks first
 - Skip completion action
- Spawn workers as general-purpose agents (must use team-worker)
-
---
+- Modify source code directly -- delegate to implementer
+- Omit `[coordinator]` identifier in any output

 ## Command Execution Protocol

-When coordinator needs to execute a command (dispatch, monitor):
+When coordinator needs to execute a command (analyze, dispatch, monitor):

-1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
-2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
-3. **Commands are inline execution guides** - NOT separate agents or subprocesses
-4. **Execute synchronously** - complete the command workflow before proceeding
-
-Example:
-```
-Phase 3 needs task dispatch
-  -> Read roles/coordinator/commands/dispatch.md
-  -> Execute Phase 2 (Context Loading)
-  -> Execute Phase 3 (Task Chain Creation)
-  -> Execute Phase 4 (Validation)
-  -> Continue to Phase 4
-```
-
---
+1. Read `commands/<command>.md`
+2. Follow the workflow defined in the command
+3. Commands are inline execution guides, NOT separate agents
+4. Execute synchronously, complete before proceeding

 ## Entry Router

-When coordinator is invoked, detect invocation type:
-
 | Detection | Condition | Handler |
 |-----------|-----------|---------|
-| Worker callback | Message contains `[scanner]`, `[diagnoser]`, etc. | -> handleCallback |
-| Status check | Arguments contain "check" or "status" | -> handleCheck |
-| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
-| Interrupted session | Active/paused session exists | -> Phase 0 (Resume Check) |
-| New session | None of above | -> Phase 1 (Requirement Clarification) |
+| Worker callback | Message contains [scanner], [diagnoser], [designer], [implementer], [tester] | -> handleCallback (monitor.md) |
+| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
+| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
+| Interrupted session | Active/paused session exists in .workflow/.team/ux-improve-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |

-For callback/check/resume: load `commands/monitor.md` and execute handler, then STOP.
-
-### Router Implementation
-
-1. **Load session context** (if exists):
-   - Scan `.workflow/.team/ux-improve-*/.msg/meta.json` for active/paused sessions
-   - If found, extract known worker roles from meta.json or SKILL.md Role Registry
-
-2. **Parse $ARGUMENTS** for detection keywords
-
-3. **Route to handler**:
-   - For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
-   - For Phase 0: Execute Session Resume Check below
-   - For Phase 1: Execute Requirement Clarification below
-
---
+For callback/check/resume/adapt/complete: load `commands/monitor.md`, execute matched handler, STOP.

 ## Phase 0: Session Resume Check

-**Trigger**: Interrupted session detected (active/paused session exists)
-
-1. Load session meta.json
-2. Audit TaskList -> reconcile session state vs task status
-3. Reset in_progress tasks -> pending (interrupted tasks)
-4. Check for fast-advance orphans (tasks spawned but not in TaskList)
-5. AskUserQuestion: "Resume session <session-id>? [Yes/No/New]"
-   - Yes -> Phase 4 (coordination loop)
-   - No -> Archive old session -> Phase 1
-   - New -> Keep old session paused -> Phase 1
-
---
+1. Scan `.workflow/.team/ux-improve-*/.msg/meta.json` for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile (audit TaskList, reset in_progress->pending, rebuild team, kick first ready task)
+4. Multiple -> AskUserQuestion for selection

 ## Phase 1: Requirement Clarification

-1. Parse $ARGUMENTS for project path and framework flag
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse `$ARGUMENTS` for project path and framework flag:
+   - `<project-path>` (required)
+   - `--framework react|vue` (optional, auto-detect if omitted)
 2. If project path missing -> AskUserQuestion for path
-3. If framework not specified -> detect from package.json or ask user
-4. Validate project path exists
-5. Store: project_path, framework (react|vue)
+3. Delegate to `commands/analyze.md` -> output scope context
+4. Store: project_path, framework, pipeline_mode, issue_signals

---
-
-## Phase 2: Team Creation
+## Phase 2: Create Team + Initialize Session

 1. Generate session ID: `ux-improve-<timestamp>`
-2. Create session directory structure:
+2. Create session folder structure:
   ```
-   .workflow/.team/<session-id>/
+   .workflow/.team/ux-improve-<timestamp>/
   ├── .msg/
   ├── artifacts/
   ├── explorations/
-   └── wisdom/
+   └── wisdom/contributions/
   ```
-3. TeamCreate(team_name="ux-improve")
-4. Initialize meta.json with pipeline config:
+3. **Wisdom Initialization**: Copy `.claude/skills/team-ux-improve/wisdom/` to `<session>/wisdom/`
+4. Initialize `.msg/meta.json` via team_msg state_update with pipeline metadata
+5. TeamCreate(team_name="ux-improve")
+6. Do NOT spawn workers yet - deferred to Phase 4

-### Wisdom Initialization
+## Phase 3: Create Task Chain

-After creating session directory, initialize wisdom from skill's permanent knowledge base:
+Delegate to `commands/dispatch.md`. Standard pipeline:

-1. Copy `.claude/skills/team-ux-improve/wisdom/` contents to `<session>/wisdom/`
-2. Create `<session>/wisdom/contributions/` directory if not exists
-3. This provides workers with initial patterns, principles, and anti-patterns
+SCAN-001 -> DIAG-001 -> DESIGN-001 -> IMPL-001 -> TEST-001

-Example:
-```bash
-# Copy permanent wisdom to session
-cp -r .claude/skills/team-ux-improve/wisdom/* <session>/wisdom/
-mkdir -p <session>/wisdom/contributions/
-```
+## Phase 4: Spawn-and-Stop

-5. Initialize meta.json with pipeline config:
-   ```
-   team_msg(operation="log", session_id=<session-id>, from="coordinator",
-            type="state_update",
-            data={
-              pipeline_mode: "standard",
-              pipeline_stages: ["scan", "diagnose", "design", "implement", "test"],
-              project_path: <path>,
-              framework: <framework>
-            })
-   ```
-
---
-
-## Phase 3: Task Chain Creation
-
-Delegate to dispatch.md:
-
-1. Read `roles/coordinator/commands/dispatch.md`
-2. Execute Phase 2 (Context Loading)
-3. Execute Phase 3 (Task Chain Creation)
-4. Execute Phase 4 (Validation)
-
---
-
-## Phase 4: Spawn-and-Stop Coordination
-
-1. Find ready tasks (status=pending, no blockedBy or all blockedBy completed)
-2. For each ready task:
-   - Extract role from task owner
-   - Spawn team-worker agent with role-spec path
-   - Use spawn template from SKILL.md
-3. STOP (idle, wait for worker callbacks)
-
-**Spawn template**:
-```
-Agent({
-  subagent_type: "team-worker",
-  description: "Spawn <role> worker",
-  team_name: "ux-improve",
-  name: "<role>",
-  run_in_background: true,
-  prompt: `## Role Assignment
-role: <role>
-role_spec: .claude/skills/team-ux-improve/role-specs/<role>.md
-session: <session-folder>
-session_id: <session-id>
-team_name: ux-improve
-requirement: <task-description>
-inner_loop: <true|false>
-
-Read role_spec file to load Phase 2-4 domain instructions.
-Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
-})
-```
-
-**Inner loop roles**: implementer (inner_loop: true)
-
---
+Delegate to `commands/monitor.md#handleSpawnNext`:
+1. Find ready tasks (pending + blockedBy resolved)
+2. Spawn team-worker agents (see SKILL.md Spawn Template)
+3. Output status summary
+4. STOP

 ## Phase 5: Report + Completion Action

-1. Load session state -> count completed tasks, duration
-2. List deliverables with output paths:
-   - artifacts/scan-report.md
-   - artifacts/diagnosis.md
-   - artifacts/design-guide.md
-   - artifacts/fixes/
-   - artifacts/test-report.md
+1. Read session state -> collect all results
+2. List deliverables:

-### Wisdom Consolidation
+| Deliverable | Path |
+|-------------|------|
+| Scan Report | <session>/artifacts/scan-report.md |
+| Diagnosis | <session>/artifacts/diagnosis.md |
+| Design Guide | <session>/artifacts/design-guide.md |
+| Fix Files | <session>/artifacts/fixes/ |
+| Test Report | <session>/artifacts/test-report.md |

-Before pipeline completion, handle knowledge contributions:
+3. **Wisdom Consolidation**: Check `<session>/wisdom/contributions/` for worker contributions
+   - If contributions exist -> AskUserQuestion to merge to permanent wisdom
+   - If approved -> copy to `.claude/skills/team-ux-improve/wisdom/`

-1. Check if `<session>/wisdom/contributions/` has any files
-2. If contributions exist:
-   - Summarize contributions for user review
-   - Use AskUserQuestion to ask if user wants to merge valuable contributions back to permanent wisdom
-   - If approved, copy selected contributions to `.claude/skills/team-ux-improve/wisdom/` (classify into patterns/, anti-patterns/, etc.)
-
-Example interaction:
-```
-AskUserQuestion({
-  questions: [{
-    question: "Workers contributed new knowledge during this session. Merge to permanent wisdom?",
-    header: "Knowledge",
-    options: [
-      { label: "Merge All", description: "Add all contributions to permanent wisdom" },
-      { label: "Review First", description: "Show contributions before deciding" },
-      { label: "Skip", description: "Keep contributions in session only" }
-    ]
-  }]
-})
-```
-
-3. **Completion Action** (interactive mode):
-
-```
-AskUserQuestion({
-  questions: [{
-    question: "Team pipeline complete. What would you like to do?",
-    header: "Completion",
-    multiSelect: false,
-    options: [
-      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
-      { label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
-      { label: "Export Results", description: "Export deliverables to a specified location, then clean" }
-    ]
-  }]
-})
-```
-
-4. Handle user choice:
-
-| Choice | Steps |
-|--------|-------|
-| Archive & Clean | TaskList -> verify all completed -> update session status="completed" -> TeamDelete("ux-improve") -> output final summary with artifact paths |
-| Keep Active | Update session status="paused" -> output: "Session paused. Resume with: Skill(skill='team-ux-improve', args='resume')" |
-| Export Results | AskUserQuestion for target directory -> copy all artifacts -> Archive & Clean flow |
-
---
+4. Calculate: completed_tasks, total_issues_found, issues_fixed, test_pass_rate
+5. Output pipeline summary with [coordinator] prefix
+6. Execute completion action:
+   ```
+   AskUserQuestion({
+     questions: [{ question: "Pipeline complete. What next?", header: "Completion", options: [
+       { label: "Archive & Clean", description: "Archive session and clean up team resources" },
+       { label: "Keep Active", description: "Keep session for follow-up work" },
+       { label: "Export Results", description: "Export deliverables to specified location" }
+     ]}]
+   })
+   ```

 ## Error Handling

-| Scenario | Resolution |
-|----------|------------|
+| Error | Resolution |
+|-------|------------|
 | Project path invalid | Re-prompt user for valid path |
 | Framework detection fails | AskUserQuestion for framework selection |
-| Worker spawn fails | Log error, mark task as failed, continue with other tasks |
-| TeamCreate fails | Error: cannot proceed without team |
-| Completion action timeout (5 min) | Default to Keep Active |
+| Task timeout | Log, mark failed, ask user to retry or skip |
+| Worker crash | Reset task to pending, respawn worker |
+| Dependency cycle | Detect, report to user, halt |
+| Session corruption | Attempt recovery, fallback to manual reconciliation |
+| No UI issues found | Complete with empty fix list, generate clean bill report |
+| Test iterations exceeded | Accept current state, continue to completion |
--- a/.claude/skills/team-ux-improve/roles/designer/role.md
+++ b/.claude/skills/team-ux-improve/roles/designer/role.md
@@ -0,0 +1,122 @@
+---
+role: designer
+prefix: DESIGN
+inner_loop: false
+message_types: [state_update]
+---
+
+# UX Designer
+
+Design feedback mechanisms (loading/error/success states) and state management patterns (React/Vue reactive updates).
+
+## Phase 2: Context & Pattern Loading
+
+1. Load diagnosis report from `<session>/artifacts/diagnosis.md`
+2. Load diagnoser state via `team_msg(operation="get_state", session_id=<session-id>, role="diagnoser")`
+3. Detect framework from project structure
+4. Load framework-specific patterns:
+
+| Framework | State Pattern | Event Pattern |
+|-----------|---------------|---------------|
+| React | useState, useRef | onClick, onChange |
+| Vue | ref, reactive | @click, @change |
+
+### Wisdom Input
+
+1. Read `<session>/wisdom/patterns/ui-feedback.md` for established feedback design patterns
+2. Read `<session>/wisdom/patterns/state-management.md` for state handling patterns
+3. Read `<session>/wisdom/principles/general-ux.md` for UX design principles
+4. Apply patterns when designing solutions for identified issues
+
+### Complex Design (use CLI)
+
+For complex multi-component solutions:
+
+```
+Bash(`ccw cli -p "PURPOSE: Design comprehensive feedback mechanism for multi-step form
+CONTEXT: @<component-files>
+EXPECTED: Complete design with state flow diagram and code patterns
+CONSTRAINTS: Must support React hooks" --tool gemini --mode analysis`)
+```
+
+## Phase 3: Solution Design
+
+For each diagnosed issue, design solution:
+
+### Feedback Mechanism Design
+
+| Issue Type | Solution Design |
+|------------|-----------------|
+| Missing loading | Add loading state + UI indicator (spinner, disabled button) |
+| Missing error | Add error state + error message display |
+| Missing success | Add success state + confirmation toast/message |
+| No empty state | Add conditional rendering for empty data |
+
+### State Management Design
+
+**React Pattern**:
+```typescript
+const [isLoading, setIsLoading] = useState(false);
+const [error, setError] = useState<string | null>(null);
+
+const handleSubmit = async (event: React.FormEvent) => {
+  event.preventDefault();
+  setIsLoading(true);
+  setError(null);
+  try {
+    const response = await fetch('/api/upload', { method: 'POST', body: formData });
+    if (!response.ok) throw new Error('Upload failed');
+  } catch (err: any) {
+    setError(err.message || 'An error occurred');
+  } finally {
+    setIsLoading(false);
+  }
+};
+```
+
+**Vue Pattern**:
+```typescript
+const isLoading = ref(false);
+const error = ref<string | null>(null);
+
+const handleSubmit = async () => {
+  isLoading.value = true;
+  error.value = null;
+  try {
+    const response = await fetch('/api/upload', { method: 'POST', body: formData });
+    if (!response.ok) throw new Error('Upload failed');
+  } catch (err: any) {
+    error.value = err.message || 'An error occurred';
+  } finally {
+    isLoading.value = false;
+  }
+};
+```
+
+### Input Control Design
+
+| Issue | Solution |
+|-------|----------|
+| Text input for file path | Add file picker: `<input type="file" />` |
+| Text input for folder path | Add directory picker: `<input type="file" webkitdirectory />` |
+| No validation | Add validation rules and error messages |
+
+## Phase 4: Design Document Generation
+
+1. Generate implementation guide for each issue and write to `<session>/artifacts/design-guide.md`
+
+### Wisdom Contribution
+
+If novel design patterns created:
+1. Write new patterns to `<session>/wisdom/contributions/designer-pattern-<timestamp>.md`
+2. Format: Problem context, solution design, implementation hints, trade-offs
+
+3. Share state via team_msg:
+   ```
+   team_msg(operation="log", session_id=<session-id>, from="designer",
+            type="state_update", data={
+              designed_solutions: <count>,
+              framework: <framework>,
+              patterns_used: [<pattern-list>]
+            })
+   ```
--- a/.claude/skills/team-ux-improve/roles/diagnoser/role.md
+++ b/.claude/skills/team-ux-improve/roles/diagnoser/role.md
@@ -0,0 +1,93 @@
+---
+role: diagnoser
+prefix: DIAG
+inner_loop: false
+message_types: [state_update]
+---
+
+# State Diagnoser
+
+Diagnose root causes of UI issues: state management problems, event binding failures, async handling errors.
+
+## Phase 2: Context & Complexity Assessment
+
+1. Load scan report from `<session>/artifacts/scan-report.md`
+2. Load scanner state via `team_msg(operation="get_state", session_id=<session-id>, role="scanner")`
+
+### Wisdom Input
+
+1. Read `<session>/wisdom/patterns/ui-feedback.md` and `<session>/wisdom/patterns/state-management.md` if available
+2. Use patterns to identify root causes of UI interaction issues
+3. Reference `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` for common causes
+
+3. Assess issue complexity:
+
+| Complexity | Criteria | Strategy |
+|------------|----------|----------|
+| High | 5+ issues, cross-component state | CLI delegation |
+| Medium | 2-4 issues, single component | CLI for analysis |
+| Low | 1 issue, simple pattern | Inline analysis |
+
+### Complex Analysis (use CLI)
+
+For complex multi-file state management issues:
+
+```
+Bash(`ccw cli -p "PURPOSE: Analyze state management patterns and identify root causes
+CONTEXT: @<issue-files>
+EXPECTED: Root cause analysis with fix recommendations
+CONSTRAINTS: Focus on reactive update patterns" --tool gemini --mode analysis`)
+```
+
+## Phase 3: Root Cause Analysis
+
+For each issue from scan report:
+
+### State Management Diagnosis
+
+| Pattern | Root Cause | Fix Strategy |
+|---------|------------|--------------|
+| Array.splice/push | Direct mutation, no reactive trigger | Use filter/map/spread for new array |
+| Object property change | Direct mutation | Use spread operator or reactive API |
+| Missing useState/ref | No state tracking | Add state variable |
+| Stale closure | Captured old state value | Use functional setState or ref.current |
+
+### Event Binding Diagnosis
+
+| Pattern | Root Cause | Fix Strategy |
+|---------|------------|--------------|
+| onClick without handler | Missing event binding | Add event handler function |
+| Async without await | Unhandled promise | Add async/await or .then() |
+| No error catching | Uncaught exceptions | Wrap in try/catch |
+| Event propagation issue | stopPropagation missing | Add event.stopPropagation() |
+
+### Async Handling Diagnosis
+
+| Pattern | Root Cause | Fix Strategy |
+|---------|------------|--------------|
+| No loading state | Missing async state tracking | Add isLoading state |
+| No error handling | Missing catch block | Add try/catch with error state |
+| Race condition | Multiple concurrent requests | Add request cancellation or debounce |
+
+## Phase 4: Diagnosis Report
+
+1. Generate root cause analysis for each issue and write to `<session>/artifacts/diagnosis.md`
+
+### Wisdom Contribution
+
+If new root cause patterns discovered:
+1. Write diagnosis patterns to `<session>/wisdom/contributions/diagnoser-patterns-<timestamp>.md`
+2. Format: Symptom, root cause, detection method, fix approach
+
+3. Share state via team_msg:
+   ```
+   team_msg(operation="log", session_id=<session-id>, from="diagnoser",
+            type="state_update", data={
+              diagnosed_issues: <count>,
+              pattern_types: {
+                state_management: <count>,
+                event_binding: <count>,
+                async_handling: <count>
+              }
+            })
+   ```
--- a/.claude/skills/team-ux-improve/roles/explorer/role.md
+++ b/.claude/skills/team-ux-improve/roles/explorer/role.md
@@ -0,0 +1,77 @@
+---
+role: explorer
+prefix: EXPLORE
+inner_loop: false
+message_types: [state_update]
+---
+
+# Codebase Explorer
+
+Explore codebase for UI component patterns, state management conventions, and framework-specific patterns. Callable by coordinator only.
+
+## Phase 2: Exploration Scope
+
+1. Parse exploration request from task description
+2. Determine file patterns based on framework:
+
+### Wisdom Input
+
+1. Read `<session>/wisdom/patterns/ui-feedback.md` and `<session>/wisdom/patterns/state-management.md` if available
+2. Use known patterns as reference when exploring codebase for component structures
+3. Check `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` to identify problematic patterns during exploration
+
+| Framework | Patterns |
+|-----------|----------|
+| React | `**/*.tsx`, `**/*.jsx`, `**/use*.ts`, `**/store*.ts` |
+| Vue | `**/*.vue`, `**/composables/*.ts`, `**/stores/*.ts` |
+
+3. Check exploration cache: `<session>/explorations/cache-index.json`
+   - If cache hit and fresh -> return cached results
+   - If cache miss or stale -> proceed to Phase 3
+
+## Phase 3: Codebase Exploration
+
+Use ACE search for semantic queries:
+
+```
+mcp__ace-tool__search_context(
+  project_root_path="<project-path>",
+  query="<exploration-query>"
+)
+```
+
+Exploration dimensions:
+
+| Dimension | Query | Purpose |
+|-----------|-------|---------|
+| Component patterns | "UI components with user interactions" | Find interactive components |
+| State management | "State management patterns useState ref reactive" | Identify state conventions |
+| Event handling | "Event handlers onClick onChange onSubmit" | Map event patterns |
+| Error handling | "Error handling try catch error state" | Find error patterns |
+| Feedback mechanisms | "Loading state spinner progress indicator" | Find existing feedback |
+
+For each dimension, collect:
+- File paths
+- Pattern examples
+- Convention notes
+
+## Phase 4: Exploration Summary
+
+1. Generate pattern summary and write to `<session>/explorations/exploration-summary.md`
+2. Cache results to `<session>/explorations/cache-index.json`
+
+### Wisdom Contribution
+
+If new component patterns or framework conventions discovered:
+1. Write pattern summaries to `<session>/wisdom/contributions/explorer-patterns-<timestamp>.md`
+2. Format: Pattern Name, Framework, Use Case, Code Example, Adoption
+
+4. Share state via team_msg:
+   ```
+   team_msg(operation="log", session_id=<session-id>, from="explorer",
+            type="state_update", data={
+              framework: <framework>,
+              components_found: <count>,
+              patterns_identified: [<pattern-list>]
+            })
+   ```
--- a/.claude/skills/team-ux-improve/roles/implementer/role.md
+++ b/.claude/skills/team-ux-improve/roles/implementer/role.md
@@ -0,0 +1,102 @@
+---
+role: implementer
+prefix: IMPL
+inner_loop: true
+message_types: [state_update]
+---
+
+# Code Implementer
+
+Generate executable fix code with proper state management, event handling, and UI feedback bindings.
+
+## Phase 2: Task & Design Loading
+
+1. Extract session path from task description
+2. Read design guide: `<session>/artifacts/design-guide.md`
+3. Extract implementation tasks from design guide
+4. **Wisdom Input**:
+   - Read `<session>/wisdom/patterns/state-management.md` for state handling patterns
+   - Read `<session>/wisdom/patterns/ui-feedback.md` for UI feedback implementation patterns
+   - Read `<session>/wisdom/principles/general-ux.md` for implementation principles
+   - Load framework-specific conventions if available
+   - Apply these patterns and principles when generating code to ensure consistency and quality
+5. **For inner loop**: Load context_accumulator from prior IMPL tasks
+
+### Context Accumulator (Inner Loop)
+
+```
+context_accumulator = {
+  completed_fixes: [<fix-1>, <fix-2>],
+  modified_files: [<file-1>, <file-2>],
+  patterns_applied: [<pattern-1>]
+}
+```
+
+## Phase 3: Code Implementation
+
+Implementation backend selection:
+
+| Backend | Condition | Method |
+|---------|-----------|--------|
+| CLI | Complex multi-file changes | `ccw cli --tool gemini --mode write` |
+| Direct | Simple single-file changes | Inline Edit/Write |
+
+### CLI Implementation (Complex)
+
+```
+Bash(`ccw cli -p "PURPOSE: Implement loading state and error handling for upload form
+TASK:
+  - Add useState for isLoading and error
+  - Wrap async call in try/catch/finally
+  - Update UI bindings for button and error display
+CONTEXT: @src/components/Upload.tsx
+EXPECTED: Modified Upload.tsx with complete implementation
+CONSTRAINTS: Maintain existing code style" --tool gemini --mode write`)
+```
+
+### Direct Implementation (Simple)
+
+For simple state variable additions or UI binding changes use Edit/Write tools directly.
+
+### Implementation Steps
+
+For each fix in design guide:
+1. Read target file
+2. Determine complexity (simple vs complex)
+3. Apply fix using appropriate backend
+4. Verify syntax (no compilation errors)
+5. Append to context_accumulator
+
+## Phase 4: Self-Validation
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Syntax | IDE diagnostics or tsc --noEmit | No errors |
+| File existence | Verify planned files exist | All present |
+| Acceptance criteria | Match against design guide | All met |
+
+Validation steps:
+1. Run syntax check on modified files
+2. Verify all files from design guide exist
+3. Check acceptance criteria from design guide
+4. If validation fails -> attempt auto-fix (max 2 attempts)
+
+### Context Accumulator Update
+
+Append to context_accumulator and write summary to `<session>/artifacts/fixes/README.md`.
+
+Share state via team_msg:
+```
+team_msg(operation="log", session_id=<session-id>, from="implementer",
+         type="state_update", data={
+           completed_fixes: <count>,
+           modified_files: [<file-list>],
+           validation_passed: true
+         })
+```
+
+### Wisdom Contribution
+
+If reusable code patterns or snippets created:
+1. Write code snippets to `<session>/wisdom/contributions/implementer-snippets-<timestamp>.md`
+2. Format: Use case, code snippet with comments, framework compatibility notes
--- a/.claude/skills/team-ux-improve/roles/scanner/role.md
+++ b/.claude/skills/team-ux-improve/roles/scanner/role.md
@@ -0,0 +1,93 @@
+---
+role: scanner
+prefix: SCAN
+inner_loop: false
+message_types: [state_update]
+---
+
+# UI Scanner
+
+Scan UI components to identify interaction issues: unresponsive buttons, missing feedback mechanisms, state not refreshing.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Project path | Task description CONTEXT | Yes |
+| Framework | Task description CONTEXT | Yes |
+| Scan scope | Task description CONSTRAINTS | Yes |
+
+1. Extract session path and project path from task description
+2. Detect framework from project structure:
+
+| Signal | Framework |
+|--------|-----------|
+| package.json has "react" | React |
+| package.json has "vue" | Vue |
+| *.tsx files present | React |
+| *.vue files present | Vue |
+
+3. Build file pattern list for scanning:
+   - React: `**/*.tsx`, `**/*.jsx`, `**/use*.ts`
+   - Vue: `**/*.vue`, `**/composables/*.ts`
+
+### Wisdom Input
+
+1. Read `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` if available
+2. Use anti-patterns to identify known UX issues during scanning
+3. Check `<session>/wisdom/patterns/ui-feedback.md` for expected feedback patterns
+
+### Complex Analysis (use CLI)
+
+For large projects with many components:
+
+```
+Bash(`ccw cli -p "PURPOSE: Discover all UI components with user interactions
+CONTEXT: @<project-path>/**/*.tsx @<project-path>/**/*.vue
+EXPECTED: Component list with interaction types (click, submit, input, select)
+CONSTRAINTS: Focus on interactive components only" --tool gemini --mode analysis`)
+```
+
+## Phase 3: Component Scanning
+
+Scan strategy:
+
+| Category | Detection Pattern | Severity |
+|----------|-------------------|----------|
+| Unresponsive actions | onClick/\@click without async handling or error catching | High |
+| Missing loading state | Form submit without isLoading/loading ref | High |
+| State not refreshing | Array.splice/push without reactive reassignment | High |
+| Missing error feedback | try/catch without error state or user notification | Medium |
+| Missing success feedback | API call without success confirmation | Medium |
+| No empty state | Data list without empty state placeholder | Low |
+| Input without validation | Form input without validation rules | Low |
+| Missing file selector | Text input for file/folder path without picker | Medium |
+
+For each component file:
+1. Read file content
+2. Scan for interaction patterns using Grep
+3. Check for feedback mechanisms (loading, error, success states)
+4. Check state update patterns (mutation vs reactive)
+5. Record issues with file:line references
+
+## Phase 4: Issue Report Generation
+
+1. Classify issues by severity (High/Medium/Low)
+2. Group by category (unresponsive, missing feedback, state issues, input UX)
+3. Generate structured report and write to `<session>/artifacts/scan-report.md`
+4. Share state via team_msg:
+   ```
+   team_msg(operation="log", session_id=<session-id>, from="scanner",
+            type="state_update", data={
+              total_issues: <count>,
+              high: <count>, medium: <count>, low: <count>,
+              categories: [<category-list>],
+              scanned_files: <count>
+            })
+   ```
+
+### Wisdom Contribution
+
+If novel UX issues discovered that aren't in anti-patterns:
+1. Write findings to `<session>/wisdom/contributions/scanner-issues-<timestamp>.md`
+2. Format: Issue description, detection criteria, affected components
--- a/.claude/skills/team-ux-improve/roles/tester/role.md
+++ b/.claude/skills/team-ux-improve/roles/tester/role.md
@@ -0,0 +1,84 @@
+---
+role: tester
+prefix: TEST
+inner_loop: false
+message_types: [state_update]
+---
+
+# Test Engineer
+
+Generate and run tests to verify fixes (loading states, error handling, state updates).
+
+## Phase 2: Environment Detection
+
+1. Detect test framework from project files:
+
+| Signal | Framework |
+|--------|-----------|
+| package.json has "jest" | Jest |
+| package.json has "vitest" | Vitest |
+| package.json has "@testing-library/react" | React Testing Library |
+| package.json has "@vue/test-utils" | Vue Test Utils |
+
+2. Get changed files from implementer state:
+   ```
+   team_msg(operation="get_state", session_id=<session-id>, role="implementer")
+   ```
+
+3. Load test strategy from design guide
+
+### Wisdom Input
+
+1. Read `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` for common issues to test
+2. Read `<session>/wisdom/patterns/ui-feedback.md` for expected feedback behaviors to verify
+3. Use wisdom to design comprehensive test cases covering known edge cases
+
+## Phase 3: Test Generation & Execution
+
+### Test Generation
+
+For each modified file, generate test cases covering loading states, error handling, state updates, and accessibility.
+
+### Test Execution
+
+Iterative test-fix cycle (max 5 iterations):
+
+1. Run tests: `npm test` or `npm run test:unit`
+2. Parse results -> calculate pass rate
+3. If pass rate >= 95% -> exit (success)
+4. If pass rate < 95% and iterations < 5:
+   - Analyze failures
+   - Use CLI to generate fixes:
+     ```
+     Bash(`ccw cli -p "PURPOSE: Fix test failures
+     CONTEXT: @<test-file> @<source-file>
+     EXPECTED: Fixed code that passes tests
+     CONSTRAINTS: Maintain existing functionality" --tool gemini --mode write`)
+     ```
+   - Increment iteration counter
+   - Loop to step 1
+5. If iterations >= 5 -> send fix_required message
+
+## Phase 4: Test Report
+
+### Wisdom Contribution
+
+If new edge cases or test patterns discovered:
+1. Write test findings to `<session>/wisdom/contributions/tester-edge-cases-<timestamp>.md`
+2. Format: Edge case description, test scenario, expected behavior, actual behavior
+
+Write report to `<session>/artifacts/test-report.md`.
+
+Share state via team_msg:
+```
+team_msg(operation="log", session_id=<session-id>, from="tester",
+         type="state_update", data={
+           total_tests: <count>,
+           passed: <count>,
+           failed: <count>,
+           pass_rate: <percentage>,
+           fix_iterations: <count>
+         })
+```
+
+If pass rate < 95%, send fix_required message to coordinator.
--- a/.claude/skills/team-ux-improve/specs/pipelines.md
+++ b/.claude/skills/team-ux-improve/specs/pipelines.md
@@ -0,0 +1,54 @@
+# Pipeline Definitions
+
+UX improvement pipeline modes and task registry.
+
+## Pipeline Modes
+
+| Mode | Description | Task Chain |
+|------|-------------|------------|
+| standard | Full UX improvement pipeline | SCAN-001 -> DIAG-001 -> DESIGN-001 -> IMPL-001 -> TEST-001 |
+
+## Standard Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Inner Loop | Description |
+|---------|------|-----------|------------|-------------|
+| SCAN-001 | scanner | [] | false | Scan UI components for interaction issues (unresponsive buttons, missing feedback, state problems) |
+| DIAG-001 | diagnoser | [SCAN-001] | false | Root cause diagnosis with fix recommendations |
+| DESIGN-001 | designer | [DIAG-001] | false | Feedback mechanism and state management solution design |
+| IMPL-001 | implementer | [DESIGN-001] | true | Code implementation with proper state handling |
+| TEST-001 | tester | [IMPL-001] | false | Test generation and validation (pass rate >= 95%, max 5 iterations) |
+
+## Checkpoints
+
+| Checkpoint | Trigger | Condition | Action |
+|------------|---------|-----------|--------|
+| Pipeline complete | TEST-001 completes | All tasks done | Coordinator Phase 5: wisdom consolidation + completion action |
+
+## Test Iteration Behavior
+
+| Condition | Action |
+|-----------|--------|
+| pass_rate >= 95% | Pipeline complete |
+| pass_rate < 95% AND iterations < 5 | Tester generates fixes, re-runs (inner loop within TEST-001) |
+| pass_rate < 95% AND iterations >= 5 | Accept current state, report to coordinator |
+
+## Output Artifacts
+
+| Task | Output Path |
+|------|-------------|
+| SCAN-001 | <session>/artifacts/scan-report.md |
+| DIAG-001 | <session>/artifacts/diagnosis.md |
+| DESIGN-001 | <session>/artifacts/design-guide.md |
+| IMPL-001 | <session>/artifacts/fixes/ |
+| TEST-001 | <session>/artifacts/test-report.md |
+
+## Wisdom System
+
+Workers contribute learnings to `<session>/wisdom/contributions/`. On pipeline completion, coordinator asks user to merge approved contributions to permanent wisdom at `.claude/skills/team-ux-improve/wisdom/`.
+
+| Directory | Purpose |
+|-----------|---------|
+| wisdom/principles/ | Core UX principles |
+| wisdom/patterns/ | Solution patterns (ui-feedback, state-management) |
+| wisdom/anti-patterns/ | Issues to avoid (common-ux-pitfalls) |
+| wisdom/contributions/ | Session worker contributions (pending review) |