claude-code-workflow 7.2.26 → 7.2.28

package/.claude/skills/team-ui-polish/roles/coordinator/commands/monitor.md

@@ -0,0 +1,180 @@
+# Monitor Pipeline
+
+Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
+
+## Constants
+
+- SPAWN_MODE: background
+- ONE_STEP_PER_INVOCATION: true
+- FAST_ADVANCE_AWARE: true
+- WORKER_AGENT: team-worker
+- MAX_GC_ROUNDS: 2
+
+## Handler Router
+
+| Source | Handler |
+|--------|---------|
+| Message contains [scanner], [diagnostician], [optimizer], [verifier] | handleCallback |
+| "capability_gap" | handleAdapt |
+| "check" or "status" | handleCheck |
+| "resume" or "continue" | handleResume |
+| All tasks completed | handleComplete |
+| Default | handleSpawnNext |
+
+## handleCallback
+
+Worker completed. Process and advance.
+
+1. Parse message to identify role and task ID:
+
+| Message Pattern | Role |
+|----------------|------|
+| `[scanner]` or `SCAN-*` | scanner |
+| `[diagnostician]` or `DIAG-*` | diagnostician |
+| `[optimizer]` or `OPT-*` | optimizer |
+| `[verifier]` or `VERIFY-*` | verifier |
+
+2. Mark task completed: `TaskUpdate({ taskId: "<task-id>", status: "completed" })`
+3. Record completion in session state
+
+4. Check checkpoint for completed task:
+
+| Completed Task | Checkpoint | Action |
+|---------------|------------|--------|
+| SCAN-001 | - | Notify user: scan complete, proceed to diagnosis |
+| DIAG-001 | - | Check pipeline mode: scan-only -> handleComplete, else proceed to OPT |
+| OPT-001 / OPT-fix-* | - | Proceed to VERIFY |
+| VERIFY-001 / VERIFY-* | GC Checkpoint | Check verify signal -> GC loop or handleComplete |
+
+5. **GC Checkpoint handling** (VERIFY task completed):
+   Read verify signal from message: `verify_passed`, `verify_failed`, or `fix_required`
+
+   | Signal | Condition | Action |
+   |--------|-----------|--------|
+   | `verify_passed` | No regressions, score_delta >= 0 | GC converged -> handleComplete |
+   | `verify_failed` | Regressions found but non-critical | gc_rounds < max -> create OPT-fix task |
+   | `fix_required` | Score dropped or critical regressions | gc_rounds < max -> create OPT-fix task (CRITICAL) |
+   | Any | gc_rounds >= max | Escalate to user |
+
+   **GC Fix Task Creation**:
+   ```
+   TaskCreate({ subject: "OPT-fix-<round>",
+     description: "PURPOSE: Address verification regressions | Success: All regressions resolved
+   TASK:
+     - Parse verification feedback for specific regressions
+     - Apply targeted fixes for regression issues only
+   CONTEXT:
+     - Session: <session-folder>
+     - Upstream artifacts: verification/verify-report.md" })
+   TaskUpdate({ taskId: "OPT-fix-<round>", owner: "optimizer" })
+   ```
+   Then create new VERIFY task blocked by OPT-fix. Increment gc_state.round.
+
+   **GC Escalation Options** (when max rounds exceeded):
+   1. Accept current state - skip further fixes, complete pipeline
+   2. Try one more round
+   3. Terminate
+
+6. -> handleSpawnNext
+
+## handleCheck
+
+Read-only status report, then STOP.
+
+```
+Pipeline Status (<pipeline-mode>):
+  [DONE]  SCAN-001     (scanner)        -> scan-report.md
+  [DONE]  DIAG-001     (diagnostician)  -> diagnosis-report.md
+  [RUN]   OPT-001      (optimizer)      -> applying fixes...
+  [WAIT]  VERIFY-001   (verifier)       -> blocked by OPT-001
+
+GC Rounds: 0/2
+Score: <before-score>/32 -> pending
+Session: <session-id>
+Commands: 'resume' to advance | 'check' to refresh
+```
+
+Output status -- do NOT advance pipeline.
+
+## handleResume
+
+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
+
+## handleSpawnNext
+
+Find ready tasks, spawn workers, STOP.
+
+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:
+
+```
+Agent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker for <task-id>",
+  team_name: "ui-polish",
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: <project>/.claude/skills/team-ui-polish/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: ui-polish
+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 Phase 2-4 -> built-in Phase 5 (report).`
+})
+```
+
+**Spawn rules by mode**:
+
+| Mode | Behavior |
+|------|----------|
+| scan-only | Sequential: SCAN-001 -> DIAG-001 |
+| targeted | Sequential: SCAN -> DIAG -> OPT -> VERIFY |
+| full | Sequential: SCAN -> DIAG -> OPT -> VERIFY, then GC loop if needed |
+
+5. Add to active_workers, update session, output summary, STOP
+
+## handleComplete
+
+Pipeline done. Generate report and completion action.
+
+**Completion check by mode**:
+
+| Mode | Completion Condition |
+|------|---------------------|
+| scan-only | SCAN-001 + DIAG-001 completed |
+| targeted | All 4 tasks (+ any fix tasks) completed |
+| full | All 4 tasks (+ any fix tasks) completed |
+
+1. If any tasks not completed -> handleSpawnNext
+2. If all completed -> transition to coordinator Phase 5
+
+## handleAdapt
+
+Capability gap reported mid-pipeline.
+
+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

package/.claude/skills/team-ui-polish/roles/coordinator/role.md

@@ -0,0 +1,170 @@
+# Coordinator Role
+
+UI Polish Team coordinator. Orchestrate pipeline: analyze -> dispatch -> spawn -> monitor -> report. Manages linear task chains (scan -> diagnose -> optimize -> verify) with optimizer<->verifier GC loops.
+
+## Identity
+- **Name**: coordinator | **Tag**: [coordinator]
+- **Responsibility**: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results
+
+## Boundaries
+
+### MUST
+- All output (SendMessage, team_msg, logs) must carry `[coordinator]` identifier
+- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
+- Dispatch tasks with proper dependency chains and blockedBy
+- Monitor worker progress via message bus and route messages
+- Handle Generator-Critic loops (optimizer<->verifier) with max 2 iterations
+- Maintain session state persistence
+
+### MUST NOT
+- Implement domain logic (scanning, diagnosing, optimizing, verifying) -- workers handle this
+- Spawn workers without creating tasks first
+- Force-advance pipeline past failed verification
+- Modify source code or design artifacts directly -- delegate to workers
+- Omit `[coordinator]` identifier in any output
+
+## Command Execution Protocol
+
+When coordinator needs to execute a command (analyze, dispatch, monitor):
+
+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
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Worker callback | Message contains [scanner], [diagnostician], [optimizer], [verifier] | -> 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/UIP-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For callback/check/resume/adapt/complete: load `@commands/monitor.md`, execute matched handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan `.workflow/.team/UIP-*/.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
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse task description from arguments
+2. Detect polish scope:
+
+| Signal | Pipeline Mode |
+|--------|---------------|
+| "scan", "audit", "check", "report", "analyze" | scan-only |
+| "fix color", "fix typography", specific dimension keyword | targeted |
+| "polish", "fix all", "full", "improve", "clean up" | full |
+| Unclear | ask user |
+
+3. Ask for missing parameters if scope unclear:
+   ```
+   AskUserQuestion({
+     questions: [
+       { question: "What should I polish?", header: "Target", options: [
+         { label: "URL", description: "Live page URL for Chrome DevTools analysis" },
+         { label: "Component path", description: "Specific component files to polish" },
+         { label: "Full site", description: "Scan and polish entire frontend" }
+       ]},
+       { question: "Polish mode?", header: "Mode", options: [
+         { label: "Scan only", description: "Discover + diagnose, report only" },
+         { label: "Targeted fix", description: "Fix specific dimensions" },
+         { label: "Full polish", description: "Complete polish cycle" }
+       ]}
+     ]
+   })
+   ```
+4. Delegate to `@commands/analyze.md` -> output scope context
+5. Record: pipeline_mode, target, complexity, dimension_filters
+
+## Phase 2: Create Team + Initialize Session
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-ui-polish`
+2. Generate session ID: `UIP-<slug>-<YYYY-MM-DD>`
+3. Create session folder structure:
+   ```
+   .workflow/.team/UIP-<slug>-<date>/scan/
+   .workflow/.team/UIP-<slug>-<date>/diagnosis/
+   .workflow/.team/UIP-<slug>-<date>/optimization/
+   .workflow/.team/UIP-<slug>-<date>/verification/
+   .workflow/.team/UIP-<slug>-<date>/evidence/
+   .workflow/.team/UIP-<slug>-<date>/wisdom/
+   .workflow/.team/UIP-<slug>-<date>/.msg/
+   ```
+4. Initialize `.msg/meta.json` via team_msg state_update with pipeline metadata
+5. TeamCreate(team_name="ui-polish")
+6. Do NOT spawn workers yet - deferred to Phase 4
+
+## Phase 3: Create Task Chain
+
+Delegate to `@commands/dispatch.md`. Task chains by mode:
+
+| Mode | Task Chain |
+|------|------------|
+| scan-only | SCAN-001 -> DIAG-001 |
+| targeted | SCAN-001 -> DIAG-001 -> OPT-001 -> VERIFY-001 |
+| full | SCAN-001 -> DIAG-001 -> OPT-001 -> VERIFY-001 (GC loop if verify fails) |
+
+## Phase 4: Spawn-and-Stop
+
+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. Read session state -> collect all results
+2. List deliverables:
+
+| Deliverable | Path |
+|-------------|------|
+| Scan Report | <session>/scan/scan-report.md |
+| Diagnosis Report | <session>/diagnosis/diagnosis-report.md |
+| Optimization Log | <session>/optimization/fix-log.md |
+| Verification Report | <session>/verification/verify-report.md |
+| Before/After Screenshots | <session>/evidence/*.png |
+
+3. Calculate summary:
+   - `issues_found`: total from scan report
+   - `issues_fixed`: total from optimization log
+   - `issues_remaining`: issues_found - issues_fixed + regressions
+   - `before_score`: original scan score (out of 32)
+   - `after_score`: verification re-scan score (out of 32)
+   - `gc_rounds`: number of optimizer<->verifier iterations
+4. Output pipeline summary with [coordinator] prefix
+5. 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
+
+| Error | Resolution |
+|-------|------------|
+| 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 |
+| Invalid scope | Reject with error, ask to clarify |
+| Session corruption | Attempt recovery, fallback to manual reconciliation |
+| GC loop stuck > 2 rounds | Escalate to user: accept / try one more / terminate |
+| Chrome DevTools unavailable | Continue without screenshots, note in report |

package/.claude/skills/team-ui-polish/roles/diagnostician/role.md

@@ -0,0 +1,160 @@
+---
+role: diagnostician
+prefix: DIAG
+inner_loop: false
+message_types: [diag_complete, diag_progress, error]
+---
+
+# Root Cause Diagnostician
+
+Deep-dive root cause analysis of discovered design problems. Classify severity, group systemic vs one-off issues, build fix dependency graph, and map each issue group to Impeccable fix strategies.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Scan report | <session>/scan/scan-report.md | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Fix strategies | specs/fix-strategies.md | Yes |
+| Design standards | specs/design-standards.md | Yes |
+
+1. Extract session path from task description
+2. Read scan report: parse per-dimension scores, issue inventory, systemic patterns
+3. Read specs/fix-strategies.md for issue-to-fix mapping
+4. Read specs/design-standards.md for target state reference
+
+## Phase 3: Root Cause Analysis
+
+### Step 1: Issue Classification
+
+For each issue in the scan report, classify:
+
+| Classification | Definition | Example |
+|---------------|------------|---------|
+| Systemic | Affects whole project, single root cause creates many symptoms | "No design token system" causes 15 hard-coded color issues |
+| One-off | Single component, isolated fix | Button missing hover state in one component |
+
+### Step 2: Root Cause Grouping
+
+Group issues by shared root cause. Common root cause patterns:
+
+| Root Cause | Typical Symptoms |
+|------------|-----------------|
+| No design token system | Hard-coded colors, inconsistent spacing, no theme support |
+| AI-generated template | Multiple AI slop tells (gradient text, glassmorphism, generic fonts) |
+| No typography system | Muddy hierarchy, arbitrary font sizes, no modular scale |
+| No spacing scale | Arbitrary spacing values, monotonous rhythm, no gap usage |
+| No motion system | Random durations, bad easing, no reduced-motion |
+| Missing state layer | No hover/focus/active/disabled/loading across components |
+| No responsive strategy | Fixed widths, missing breakpoints, small mobile targets |
+| No hierarchy design | Everything same weight, no squint test pass, size-only hierarchy |
+
+### Step 3: Priority Assignment
+
+For each root cause group:
+
+| Priority | Criteria |
+|----------|----------|
+| P0 | Contains any blocking issue (WCAG AA failure, missing focus, horizontal scroll, no viewport meta) |
+| P1 | Contains major issues (pure black/white, contrast near-fail, missing hover/loading) |
+| P2 | Contains minor issues (no OKLCH, overused fonts, monotonous spacing) |
+| P3 | Polish only (missing exit animation, no container queries, optical adjustments) |
+
+### Step 4: Fix Strategy Mapping
+
+For each root cause group, map to Impeccable fix strategy (from specs/fix-strategies.md):
+
+| Root Cause | Fix Strategy | Effort |
+|------------|-------------|--------|
+| No token system | Create token file, tokenize all values | systemic, high |
+| AI template aesthetic | Break templates, add intentional design | systemic, high |
+| No type system | Define modular scale, apply across project | systemic, medium |
+| No spacing scale | Define 4pt scale, replace arbitrary values | systemic, medium |
+| No motion system | Create motion tokens, fix easing/duration | systemic, medium |
+| Missing states | Add state CSS to each component | distributed, medium |
+| No responsive | Add media queries, fix widths/targets | distributed, high |
+| Individual issues | Component-level fixes | one-off, low |
+
+### Step 5: Fix Dependency Graph
+
+Build ordered dependency graph:
+
+```
+1. Design token system (if missing) -- everything else depends on this
+2. Color fixes (pure black/white, contrast) -- visual foundation
+3. Typography system -- content hierarchy
+4. Spacing scale -- layout foundation
+5. Anti-AI-slop cleanup -- requires tokens, colors, type to be in place
+6. Motion system -- independent
+7. Interaction states -- independent per component
+8. Visual hierarchy -- requires typography + spacing
+9. Responsive fixes -- last, tests everything together
+```
+
+Rules:
+- Token system MUST come before individual token consumption fixes
+- Color fixes before anti-slop (anti-slop fixes may adjust colors)
+- Typography before hierarchy (hierarchy depends on type scale)
+- Responsive fixes last (they validate all other fixes at different viewports)
+
+## Phase 4: Validate Diagnosis Completeness
+
+| Check | Pass Criteria |
+|-------|---------------|
+| All issues covered | Every issue from scan report appears in at least one root cause group |
+| No orphan issues | No issues without a root cause group |
+| Fix strategies assigned | Every root cause group has a fix strategy |
+| Dependencies valid | Dependency graph is acyclic |
+| Priority consistent | Group priority matches highest-severity issue in group |
+
+Output: `<session>/diagnosis/diagnosis-report.md`
+
+Report structure:
+
+```markdown
+# Diagnosis Report
+
+## Summary
+- Total issues: N (P0: X, P1: X, P2: X, P3: X)
+- Root cause groups: N
+- Systemic issues: N
+- One-off issues: N
+- Estimated effort: <low|medium|high>
+
+## Root Cause Groups (by priority)
+
+### [P0] <Root Cause Name>
+- **Type**: systemic | one-off
+- **Affected issues**: <count>
+- **Affected files**: <file list>
+- **Description**: <what is fundamentally wrong>
+- **Fix strategy**: <from fix-strategies.md>
+- **Effort**: <quick fix | medium | systemic change>
+- **Dependencies**: <which other fixes must come first>
+- **Issues in this group**:
+  | # | Location | Severity | Description |
+  |---|----------|----------|-------------|
+  | 1 | file:line | P0 | ... |
+
+### [P1] <Root Cause Name>
+...
+
+## Fix Dependency Graph
+<ordered list of fix phases>
+
+## Recommended Fix Order
+1. <fix phase 1>: <root cause groups to address>
+2. <fix phase 2>: <root cause groups to address>
+...
+
+## Metadata
+- Source: <session>/scan/scan-report.md
+- Original score: X/32
+- Timestamp: <ISO timestamp>
+```
+
+After writing the report, send completion message:
+```
+mcp__ccw-tools__team_msg(session_id, role="diagnostician", type="diag_complete", content="Diagnosis complete. Root cause groups: N. Systemic: N. Fix phases: N.")
+SendMessage(participant="coordinator", message="[diagnostician] DIAG-001 complete. Root cause groups: N (P0: X, P1: X, P2: X, P3: X). Systemic: N, One-off: N. Report: <session>/diagnosis/diagnosis-report.md")
+```