claude-code-workflow 7.2.15 → 7.2.16

package/.codex/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>]
+            })
+   ```

package/.codex/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>
+              }
+            })
+   ```

package/.codex/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>]
+            })
+   ```

package/.codex/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

package/.codex/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

package/.codex/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.

package/.codex/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 `~  or <project>/.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) |