claude-code-workflow 7.2.27 → 7.2.29

package/.codex/skills/team-ui-polish/specs/scoring-guide.md

@@ -0,0 +1,162 @@
+# Scoring Guide
+
+How to score each dimension consistently. Used by scanner for initial audit and verifier for re-assessment.
+
+## Rating Bands (Total Score out of 36)
+
+| Range | Rating | Description |
+|-------|--------|-------------|
+| 32-36 | Excellent | Distinctive, intentional design. Minimal or zero issues |
+| 25-31 | Good | Solid design with minor polish opportunities |
+| 18-24 | Acceptable | Functional but significant design work needed |
+| 11-17 | Poor | Major overhaul required across multiple dimensions |
+| 0-10 | Critical | AI slop gallery or fundamentally broken design |
+
+## Per-Dimension Scoring (0-4)
+
+### General Rubric
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Completely failing. Multiple major violations. Fundamental problems |
+| 1 | Major gaps. 3-4 violations. Some effort but insufficient |
+| 2 | Partial effort. 1-2 noticeable issues. Functional but not good |
+| 3 | Mostly clean. Subtle issues only. Good with minor polish needed |
+| 4 | Excellent. Genuinely distinctive/intentional. Meets all standards |
+
+### Dimension 1: Anti-AI-Slop Detection
+
+| Score | Criteria |
+|-------|----------|
+| 0 | 5+ AI slop tells present. Looks immediately AI-generated |
+| 1 | 3-4 AI slop tells. Heavy AI influence obvious |
+| 2 | 1-2 noticeable AI tells. Some templated elements |
+| 3 | Subtle traces only. Mostly intentional design choices |
+| 4 | Zero AI tells. Genuinely distinctive aesthetic. Would never guess AI-made |
+
+### Dimension 2: Color Quality
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Multiple WCAG AA failures, pure black/white everywhere, hard-coded colors, no system |
+| 1 | Some contrast issues, hard-coded colors, no token system, pure grays |
+| 2 | Basic contrast OK, some OKLCH or tokens, but gaps (untinted grays, missing semantic colors) |
+| 3 | Good color system with minor gaps (a few hard-coded values, imperfect 60-30-10) |
+| 4 | OKLCH-based, fully tokenized, WCAG AA+ compliant, proper 60-30-10, semantic roles defined |
+
+### Dimension 3: Typography Quality
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Generic font, no scale, body text <16px, no hierarchy |
+| 1 | Overused font, muddy sizes (many close values), missing fluid sizing |
+| 2 | Decent font choice but inconsistent scale or line-height issues |
+| 3 | Good typography with minor gaps (missing clamp, slight rhythm inconsistencies) |
+| 4 | Distinctive font, clear modular scale, fluid sizing, proper vertical rhythm, max-width on prose |
+
+### Dimension 4: Spacing & Layout Quality
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Random spacing, nested cards, fixed widths, tiny touch targets |
+| 1 | Some spacing pattern but many arbitrary values, cards overused |
+| 2 | Decent spacing but monotonous rhythm or occasional arbitrary values |
+| 3 | Good spacing system with minor gaps (occasional non-scale value, mostly gap usage) |
+| 4 | Consistent scale, varied rhythm, gap for siblings, proper touch targets, no card nesting |
+
+### Dimension 5: Motion & Animation Quality
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Layout animations, no reduced-motion, bounce easing, no system |
+| 1 | Some transform-based but bad easing, missing reduced-motion |
+| 2 | Decent animations but no token system or still missing reduced-motion |
+| 3 | Good system with minor gaps (occasional ease default, missing exit animation) |
+| 4 | Transform+opacity only, exponential easing, reduced-motion query, duration tokens, proper stagger |
+
+### Dimension 6: Interaction States
+
+| Score | Criteria |
+|-------|----------|
+| 0 | No hover, no focus, outline:none without replacement, no loading states |
+| 1 | Basic hover but missing focus/active on many elements, no loading states |
+| 2 | Hover + focus exist but no focus-visible, missing some states (disabled, error, empty) |
+| 3 | Most states present with minor gaps (imperfect focus ring, missing empty state) |
+| 4 | All 8 states implemented, focus-visible, proper focus ring, loading/error/success/empty states |
+
+### Dimension 7: Visual Hierarchy
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Everything same visual weight, no clear primary action, fails squint test completely |
+| 1 | Some size differences but no clear hierarchy system, multiple competing primary actions |
+| 2 | Basic hierarchy via size but missing weight/color/space dimensions |
+| 3 | Good hierarchy with minor issues (occasional visual competition, could be stronger) |
+| 4 | Clear squint test pass, obvious primary action, multi-dimension hierarchy, progressive disclosure |
+
+### Dimension 8: Responsive Design
+
+| Score | Criteria |
+|-------|----------|
+| 0 | No responsive design, horizontal scroll, completely broken on mobile |
+| 1 | Basic media queries but many breakage points, some fixed widths |
+| 2 | Decent mobile but some fixed widths, small targets, or missing breakpoints |
+| 3 | Good responsive with minor issues (missing container queries, occasional small target) |
+| 4 | Fluid design, proper breakpoints, container queries, 44px targets, no overflow, adapted content |
+
+### Dimension 9: Cognitive Load & UX Writing
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Information overload everywhere, no grouping, generic labels, useless error messages |
+| 1 | Some grouping but >7 data groups visible, many generic labels, errors without fix guidance |
+| 2 | Decent grouping but missing progressive disclosure, some generic buttons, partial error messages |
+| 3 | Good information architecture with minor issues (occasional generic label, one missing empty state) |
+| 4 | Clear progressive disclosure, verb+object labels, what+why+fix errors, guided empty states, proper grouping |
+
+### Dimension 10: Dark Mode Quality (Conditional)
+
+Only scored if dark mode exists. If no dark mode, this dimension is excluded from total.
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Pure black bg, no surface hierarchy, saturated colors vibrating, dangerous combos |
+| 1 | Some dark surfaces but flat (same lightness), still using light-mode font weights |
+| 2 | Basic surface hierarchy but still saturated accents or missing font weight reduction |
+| 3 | Good dark mode with minor issues (occasional pure black, one dangerous combo) |
+| 4 | Proper surface hierarchy (lighter=higher), desaturated accents, reduced font weights, tinted dark bg |
+
+When dark mode exists: total out of 40, bands shift +4. When no dark mode: total out of 36.
+
+---
+
+## Severity Mapping
+
+| Severity | Definition | Score Correlation | Action |
+|----------|-----------|-------------------|--------|
+| P0 Blocking | Prevents use or violates law/standard. WCAG AA failure, missing focus, horizontal scroll on mobile, no viewport meta | Any dimension at 0 | Fix immediately, blocks release |
+| P1 Major | Significant UX harm or near-violation. Pure black/white, missing hover, all buttons primary, muddy hierarchy | Any dimension at 1 | Fix before release |
+| P2 Minor | Annoyance with workaround. No OKLCH, overused fonts, monotonous spacing, no container queries | Any dimension at 2 | Fix in next polish pass |
+| P3 Polish | Nice-to-fix, minimal user impact. Missing exit animation, optical adjustments, font fallback metrics | Dimension at 3 with minor issues | Fix when convenient |
+
+---
+
+## Scoring Process
+
+1. For each dimension, go through every checklist item in the scanner audit
+2. Count the number and severity of violations found
+3. Apply the dimension-specific rubric to assign 0-4
+4. Sum all 8 dimensions for total (0-32)
+5. Apply rating band
+
+### Tie-Breaking Rules
+- If between two scores, the presence of any P0 issue in that dimension rounds down
+- If between two scores with no P0, consider the count of P1 issues
+- When in doubt, score lower (conservative) -- it is better to fix something unnecessary than miss something important
+
+### Verification Scoring
+When verifier re-scores after optimization:
+- Use identical checklist and rubric as original scan
+- Score independently (do not adjust based on "how much improved")
+- Report both absolute score and delta from original
+- Flag any dimension where score decreased (regression)

package/.codex/skills/team-ui-polish/specs/team-config.json

@@ -0,0 +1,73 @@
+{
+  "team_name": "ui-polish",
+  "team_display_name": "UI Polish",
+  "description": "Auto-discover and fix UI design issues using Impeccable design standards",
+  "version": "1.0.0",
+
+  "roles": {
+    "coordinator": {
+      "task_prefix": null,
+      "responsibility": "Pipeline orchestration, scope assessment, GC loop management",
+      "message_types": ["task_unblocked", "gc_checkpoint", "fix_required", "error", "shutdown"]
+    },
+    "scanner": {
+      "task_prefix": "SCAN",
+      "responsibility": "8-dimension UI audit using Impeccable design standards",
+      "message_types": ["scan_complete", "scan_progress", "error"]
+    },
+    "diagnostician": {
+      "task_prefix": "DIAG",
+      "responsibility": "Root cause analysis, severity classification, fix prioritization",
+      "message_types": ["diag_complete", "diag_progress", "error"]
+    },
+    "optimizer": {
+      "task_prefix": "OPT",
+      "responsibility": "Apply targeted fixes following Impeccable design standards",
+      "message_types": ["opt_complete", "opt_progress", "error"]
+    },
+    "verifier": {
+      "task_prefix": "VERIFY",
+      "responsibility": "Before/after comparison, regression detection",
+      "message_types": ["verify_passed", "verify_failed", "fix_required", "error"]
+    }
+  },
+
+  "pipelines": {
+    "scan-only": {
+      "description": "Discover + diagnose, no fixes (report only)",
+      "task_chain": ["SCAN-001", "DIAG-001"],
+      "complexity": "low"
+    },
+    "targeted": {
+      "description": "Fix specific dimensions only",
+      "task_chain": ["SCAN-001", "DIAG-001", "OPT-001", "VERIFY-001"],
+      "complexity": "medium"
+    },
+    "full": {
+      "description": "Complete polish cycle with GC loop",
+      "task_chain": ["SCAN-001", "DIAG-001", "OPT-001", "VERIFY-001"],
+      "gc_loop": true,
+      "complexity": "high"
+    }
+  },
+
+  "innovation_patterns": {
+    "generator_critic": {
+      "generator": "optimizer",
+      "critic": "verifier",
+      "max_rounds": 2,
+      "convergence": "verify.regressions === 0 && verify.score_delta >= 0",
+      "escalation": "Coordinator intervenes after max rounds"
+    }
+  },
+
+  "session_dirs": {
+    "base": ".workflow/.team/UIP-{slug}-{YYYY-MM-DD}/",
+    "scan": "scan/",
+    "diagnosis": "diagnosis/",
+    "optimization": "optimization/",
+    "verification": "verification/",
+    "evidence": "evidence/",
+    "messages": ".workflow/.team-msg/{team-name}/"
+  }
+}

package/.codex/skills/team-visual-a11y/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: team-visual-a11y
+description: Unified team skill for visual accessibility QA. OKLCH color contrast, typography readability, focus management, WCAG AA/AAA audit at rendered level. Uses team-worker agent architecture. Triggers on "team visual a11y", "accessibility audit", "visual a11y".
+allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), assign_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ccw-tools__read_file(*), mcp__ccw-tools__write_file(*), mcp__ccw-tools__edit_file(*), mcp__ccw-tools__team_msg(*), mcp__chrome-devtools__evaluate_script(*), mcp__chrome-devtools__take_screenshot(*), mcp__chrome-devtools__emulate(*), mcp__chrome-devtools__lighthouse_audit(*), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__resize_page(*)
+---
+
+# Team Visual Accessibility
+
+Deep visual accessibility QA: OKLCH-based perceptual color contrast, typography readability at all viewports, focus-visible completeness, WCAG AA/AAA audit at rendered level. 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-visual-a11y", args="task description")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- analyze -> dispatch -> spawn workers -> STOP
+                                    |
+                    +-------+-------+-------+
+                    v       v       v       |
+           [3 auditors spawn in PARALLEL]   |
+        color-auditor  typo-auditor  focus-auditor
+                    |       |       |
+                    +---+---+---+---+
+                        v
+               remediation-planner
+                        |
+                        v
+               fix-implementer (inner_loop)
+                        |
+                        v
+               [re-audit: color + focus in PARALLEL]
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | -- | -- |
+| color-auditor | [roles/color-auditor/role.md](roles/color-auditor/role.md) | COLOR-* | false |
+| typo-auditor | [roles/typo-auditor/role.md](roles/typo-auditor/role.md) | TYPO-* | false |
+| focus-auditor | [roles/focus-auditor/role.md](roles/focus-auditor/role.md) | FOCUS-* | false |
+| remediation-planner | [roles/remediation-planner/role.md](roles/remediation-planner/role.md) | REMED-* | false |
+| fix-implementer | [roles/fix-implementer/role.md](roles/fix-implementer/role.md) | FIX-* | true |
+
+## Role Router
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` -> `roles/coordinator/role.md`, execute entry router
+
+## Delegation Lock
+
+**Coordinator is a PURE ORCHESTRATOR. It coordinates, it does NOT do.**
+
+Before calling ANY tool, apply this check:
+
+| Tool Call | Verdict | Reason |
+|-----------|---------|--------|
+| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `assign_task` | ALLOWED | Orchestration |
+| `list_agents` | ALLOWED | Agent health check |
+| `request_user_input` | ALLOWED | User interaction |
+| `mcp__ccw-tools__team_msg` | ALLOWED | Message bus |
+| `Read/Write` on `.workflow/.team/` files | ALLOWED | Session state |
+| `Read` on `roles/`, `commands/`, `specs/` | ALLOWED | Loading own instructions |
+| `Read/Grep/Glob` on project source code | BLOCKED | Delegate to worker |
+| `Edit` on any file outside `.workflow/` | BLOCKED | Delegate to worker |
+| `Bash("ccw cli ...")` | BLOCKED | Only workers call CLI |
+| `Bash` running build/test/lint commands | BLOCKED | Delegate to worker |
+
+**If a tool call is BLOCKED**: STOP. Create a task, spawn a worker.
+
+**No exceptions for "simple" tasks.** Even a single-file read-and-report MUST go through spawn_agent.
+
+---
+
+## Shared Constants
+
+- **Session prefix**: `VA`
+- **Session path**: `.workflow/.team/VA-<slug>-<date>/`
+- **team_name**: `visual-a11y`
+- **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 GC rounds**: 2
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
+  items: [
+    { type: "text", text: `## Role Assignment
+role: <role>
+role_spec: <skill_root>/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+requirement: <task-description>
+inner_loop: <true|false>
+
+Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },
+
+    { type: "text", text: `## Task Context
+task_id: <task-id>
+title: <task-title>
+description: <task-description>
+pipeline_phase: <pipeline-phase>` },
+
+    { type: "text", text: `## Upstream Context
+<prev_context>` }
+  ]
+})
+```
+
+### Parallel Fan-in Spawn (3 Auditors)
+
+The 3 auditors run in parallel. Spawn all 3, then wait for all 3:
+
+```javascript
+// Spawn 3 auditors in parallel
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: "COLOR-001",
+  fork_context: false,
+  items: [
+    { type: "text", text: `## Role Assignment
+role: color-auditor
+role_spec: ${skillRoot}/roles/color-auditor/role.md
+session: ${sessionFolder}
+session_id: ${sessionId}
+requirement: ${colorTaskDescription}
+inner_loop: false
+
+Read role_spec file to load Phase 2-4 domain instructions.` },
+    { type: "text", text: `## Task Context
+task_id: COLOR-001
+title: OKLCH Color Contrast Audit
+description: ${colorTaskDescription}
+pipeline_phase: audit` }
+  ]
+})
+
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: "TYPO-001",
+  fork_context: false,
+  items: [
+    { type: "text", text: `## Role Assignment
+role: typo-auditor
+role_spec: ${skillRoot}/roles/typo-auditor/role.md
+session: ${sessionFolder}
+session_id: ${sessionId}
+requirement: ${typoTaskDescription}
+inner_loop: false
+
+Read role_spec file to load Phase 2-4 domain instructions.` },
+    { type: "text", text: `## Task Context
+task_id: TYPO-001
+title: Typography Readability Audit
+description: ${typoTaskDescription}
+pipeline_phase: audit` }
+  ]
+})
+
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: "FOCUS-001",
+  fork_context: false,
+  items: [
+    { type: "text", text: `## Role Assignment
+role: focus-auditor
+role_spec: ${skillRoot}/roles/focus-auditor/role.md
+session: ${sessionFolder}
+session_id: ${sessionId}
+requirement: ${focusTaskDescription}
+inner_loop: false
+
+Read role_spec file to load Phase 2-4 domain instructions.` },
+    { type: "text", text: `## Task Context
+task_id: FOCUS-001
+title: Focus & Keyboard Accessibility Audit
+description: ${focusTaskDescription}
+pipeline_phase: audit` }
+  ]
+})
+
+// Wait for ALL 3 auditors to complete
+wait_agent({ targets: ["COLOR-001", "TYPO-001", "FOCUS-001"], timeout_ms: 900000 })
+
+// Close all 3
+close_agent({ target: "COLOR-001" })
+close_agent({ target: "TYPO-001" })
+close_agent({ target: "FOCUS-001" })
+
+// Then spawn remediation-planner with all 3 audit results as upstream context
+```
+
+After spawning, use `wait_agent({ targets: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ target })` each worker.
+
+### Model Selection Guide
+
+Visual accessibility is a precision pipeline where auditors need thorough analysis and fix-implementer needs careful code changes.
+
+| Role | reasoning_effort | Rationale |
+|------|-------------------|-----------|
+| color-auditor | high | OKLCH calculations, contrast ratio precision |
+| typo-auditor | high | Multi-breakpoint analysis, clamp() validation |
+| focus-auditor | high | ARIA patterns, keyboard navigation completeness |
+| remediation-planner | high | Synthesize 3 audit reports into actionable plan |
+| fix-implementer | medium | Implementation follows defined remediation plan |
+
+### Audit-to-Remediation Context Flow
+
+All 3 audit findings must reach remediation-planner via coordinator's upstream context:
+```
+// After COLOR-001 + TYPO-001 + FOCUS-001 all complete, coordinator sends findings to planner
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: "REMED-001",
+  fork_context: false,
+  items: [
+    ...,
+    { type: "text", text: `## Upstream Context
+Color audit: <session>/audits/color/color-audit-001.md
+Typography audit: <session>/audits/typography/typo-audit-001.md
+Focus audit: <session>/audits/focus/focus-audit-001.md` }
+  ]
+})
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) -- Pipeline definitions and task registry
+- [specs/oklch-standards.md](specs/oklch-standards.md) -- OKLCH color accessibility rules
+- [specs/wcag-matrix.md](specs/wcag-matrix.md) -- WCAG 2.1 criteria matrix
+- [specs/typography-scale.md](specs/typography-scale.md) -- Typography accessibility rules
+- [specs/focus-patterns.md](specs/focus-patterns.md) -- Focus management patterns
+
+## Session Directory
+
+```
+.workflow/.team/VA-<slug>-<date>/
++-- .msg/
+|   +-- messages.jsonl         # Team message bus
+|   +-- meta.json              # Pipeline config + GC state
++-- audits/
+|   +-- color/                 # Color auditor output
+|   |   +-- color-audit-001.md
+|   +-- typography/            # Typography auditor output
+|   |   +-- typo-audit-001.md
+|   +-- focus/                 # Focus auditor output
+|       +-- focus-audit-001.md
++-- remediation/               # Remediation planner output
+|   +-- remediation-plan.md
++-- fixes/                     # Fix implementer output
+|   +-- fix-summary-001.md
++-- re-audit/                  # Re-audit output (GC loop)
+|   +-- color-audit-002.md
+|   +-- focus-audit-002.md
++-- evidence/                  # Screenshots, traces
+```
+
+## v4 Agent Coordination
+
+### Message Semantics
+
+| Intent | API | Example |
+|--------|-----|---------|
+| Queue supplementary info (don't interrupt) | `send_message` | Send audit findings to running remediation-planner |
+| Assign new work from reviewed plan | `assign_task` | Assign FIX task after remediation plan ready |
+| Check running agents | `list_agents` | Verify agent health during resume |
+
+### Agent Health Check
+
+Use `list_agents({})` in handleResume and handleComplete:
+
+```
+// Reconcile session state with actual running agents
+const running = list_agents({})
+// Compare with tasks.json active tasks
+// Reset orphaned tasks (in_progress but agent gone) to pending
+```
+
+### Named Agent Targeting
+
+Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
+- `send_message({ target: "REMED-001", items: [...] })` -- send additional audit findings to remediation-planner
+- `assign_task({ target: "FIX-001", items: [...] })` -- assign implementation from remediation plan
+- `close_agent({ target: "COLOR-001" })` -- cleanup after color audit
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| Session corruption | Attempt recovery, fallback to manual |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Completion action fails | Default to Keep Active |
+| GC loop stuck > 2 rounds | Escalate to user: accept / retry / terminate |
+| Chrome DevTools unavailable | Degrade to static analysis only |