claude-code-workflow 7.2.26 → 7.2.28

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 |

package/.codex/skills/team-visual-a11y/roles/color-auditor/role.md

@@ -0,0 +1,178 @@
+---
+role: color-auditor
+prefix: COLOR
+inner_loop: false
+message_types: [state_update]
+---
+
+# Color Accessibility Auditor
+
+OKLCH-based perceptual color contrast analysis. Extract all color values, calculate WCAG 2.1 and APCA contrast ratios, assess OKLCH lightness/chroma ranges, simulate color blindness conditions. Produce detailed color audit report with pass/fail per combination.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Target (URL or file paths) | From task description CONTEXT | Yes |
+| WCAG level (AA/AAA) | From task description CONTEXT | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+| Previous audit (re-audit) | <session>/audits/color/color-audit-*.md | Only for COLOR-002+ |
+
+1. Extract session path, target, and WCAG level from task description
+2. Determine audit type from subject: COLOR-001 -> initial audit, COLOR-002+ -> re-audit (verification)
+3. Identify target:
+   - URL -> use Chrome DevTools for rendered colors (navigate_page, evaluate_script)
+   - File paths -> read CSS/SCSS/Tailwind config files directly
+   - Full site -> enumerate stylesheets from HTML entry points
+4. For re-audit: read previous audit report and fix summary for comparison baseline
+
+## Phase 3: Color Audit Execution
+
+### Step 1: Color Extraction
+
+Extract all color values from target:
+
+**Static analysis** (always):
+- Glob for CSS/SCSS/Tailwind files -> extract color definitions
+- Parse CSS custom properties (--color-*), class colors, inline styles
+- Normalize all formats to OKLCH for perceptual comparison:
+  - `#hex` -> sRGB -> OKLCH
+  - `rgb()/rgba()` -> OKLCH
+  - `hsl()/hsla()` -> OKLCH
+  - `oklch()` -> direct
+- Record source location (file:line) for each color
+
+**Runtime analysis** (if Chrome DevTools available):
+- `mcp__chrome-devtools__navigate_page({ url: "<target-url>" })`
+- `mcp__chrome-devtools__evaluate_script({ expression: "..." })` with getComputedStyle to extract rendered colors from key elements (body, headings, links, buttons, inputs)
+- `mcp__chrome-devtools__take_screenshot({})` for visual evidence -> save to `<session>/evidence/`
+
+### Step 2: Contrast Ratio Calculation
+
+For each text/background color combination:
+
+**WCAG 2.1 Contrast Ratios**:
+- Calculate relative luminance: `L = 0.2126*R + 0.7152*G + 0.0722*B` (linearized sRGB)
+- Contrast ratio: `(L1 + 0.05) / (L2 + 0.05)` where L1 > L2
+- Thresholds:
+
+| Text Type | AA | AAA |
+|-----------|-----|-----|
+| Normal text (< 18pt / < 14pt bold) | >= 4.5:1 | >= 7:1 |
+| Large text (>= 18pt / >= 14pt bold) | >= 3:1 | >= 4.5:1 |
+| Non-text (UI components, icons) | >= 3:1 | >= 3:1 |
+
+**APCA Contrast (Lc values)**:
+- Calculate APCA Lc using OKLCH lightness difference
+- Thresholds:
+
+| Use Case | Minimum Lc |
+|----------|-----------|
+| Body text (16px) | >= 60 |
+| Large text (24px+) | >= 45 |
+| Non-text elements | >= 30 |
+| Placeholder/disabled | >= 15 |
+
+### Step 3: OKLCH Lightness Analysis
+
+Verify OKLCH lightness ranges per specs/oklch-standards.md:
+
+| Element | Expected L Range | Flag If |
+|---------|-----------------|---------|
+| Dark text on light bg | L <= 40% | L > 40% (too light for text) |
+| Light background | L >= 90% | L < 90% (too dark for bg) |
+| Accent colors | L 50-65% | Outside range |
+| Disabled/muted text | L 55-70% | Outside range |
+
+Check chroma values:
+- Text colors: C near 0 (achromatic) unless intentional accent
+- Vibrant accents: C 0.2-0.25, max 1-2 per palette
+
+### Step 4: Color Blindness Simulation
+
+Assess color distinguishability under:
+- **Protanopia** (red-blind): Check red/green pairs still distinguishable
+- **Deuteranopia** (green-blind): Check green/red pairs
+- **Tritanopia** (blue-blind): Check blue/yellow pairs
+
+Flag combinations that rely solely on color difference without shape/text/pattern alternatives.
+
+### Step 5: Dark Mode Parity
+
+If dark mode exists (media query or data-attribute):
+- Verify all color combinations also pass in dark mode
+- Check that OKLCH lightness relationships invert properly
+- Flag combinations that pass in one mode but fail in the other
+
+### Dark Mode Audit (if dark mode exists)
+
+| Check | Requirement | Method |
+|-------|-------------|--------|
+| No pure black background | Base bg uses tinted dark (oklch L >= 0.10, chroma >= 0.005) | evaluate_script: getComputedStyle check |
+| Surface hierarchy | Higher elevation = lighter surface (at least 3 distinct levels) | Screenshot comparison |
+| Font weight reduction | Dark theme reduces weight by 1 step vs light (600->500, 500->400) | Compare computed font-weight |
+| Accent desaturation | Dark theme accents have lower OKLCH chroma than light (by 0.03-0.10) | Compare computed colors |
+| Dangerous combos | No gray text on colored backgrounds, no red-green only indicators | Visual + computed color analysis |
+| All contrast ratios met | WCAG AA requirements must pass in BOTH light and dark themes | Lighthouse audit both themes |
+
+## Phase 4: Report Generation & Output
+
+1. Write audit report to `<session>/audits/color/color-audit-{NNN}.md` (or `<session>/re-audit/color-audit-{NNN}.md` for re-audits):
+
+```markdown
+# Color Accessibility Audit - {NNN}
+[color-auditor]
+
+## Summary
+- **Total color combinations tested**: {count}
+- **Pass**: {pass_count} | **Fail**: {fail_count}
+- **WCAG Level**: {AA|AAA}
+- **Critical issues**: {count}
+- **High issues**: {count}
+
+## Color Palette (OKLCH)
+| Name | Value | L% | C | H | Source |
+|------|-------|----|---|---|--------|
+| ... | oklch(X% Y Z) | X | Y | Z | file:line |
+
+## Contrast Results
+| Foreground | Background | WCAG Ratio | Pass/Fail | APCA Lc | Pass/Fail | Type |
+|-----------|-----------|------------|-----------|---------|-----------|------|
+| ... | ... | X.X:1 | PASS/FAIL | XX | PASS/FAIL | normal/large |
+
+## OKLCH Lightness Issues
+| Element | Current L | Expected Range | Status |
+|---------|----------|---------------|--------|
+| ... | X% | Y-Z% | PASS/FAIL |
+
+## Color Blindness Assessment
+| Combination | Protanopia | Deuteranopia | Tritanopia | Alt indicator |
+|------------|-----------|-------------|-----------|--------------|
+| ... | safe/risk | safe/risk | safe/risk | yes/no |
+
+## Dark Mode Parity
+| Combination | Light Mode | Dark Mode | Status |
+|------------|-----------|----------|--------|
+| ... | PASS/FAIL | PASS/FAIL | PASS/FAIL |
+
+## Issues (by severity)
+### Critical
+- ...
+### High
+- ...
+### Medium
+- ...
+```
+
+2. For re-audit (COLOR-002+), add before/after comparison section:
+```markdown
+## Before/After Comparison
+| Combination | Before (ratio) | After (ratio) | Status |
+|------------|----------------|---------------|--------|
+| ... | X.X:1 FAIL | Y.Y:1 PASS | FIXED |
+```
+
+3. Update `<session>/.msg/meta.json` under `color-auditor` namespace:
+   - Read existing -> merge `{ "color-auditor": { audit_id, total_combinations, pass_count, fail_count, critical_count, high_count, timestamp } }` -> write back

package/.codex/skills/team-visual-a11y/roles/coordinator/commands/analyze.md

@@ -0,0 +1,72 @@
+# Analyze Task
+
+Parse user task -> detect accessibility audit scope -> determine target -> select pipeline mode.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Pipeline Hint |
+|----------|------------|---------------|
+| color, contrast, oklch, palette, hue | color audit | audit-only or full |
+| typography, font, line-height, clamp, readability | typography audit | audit-only or full |
+| focus, tab, keyboard, aria, skip-link, focus-visible | focus audit | audit-only or full |
+| wcag, a11y, accessibility, compliance | full audit | audit-only or full |
+| fix, remediate, implement, correct | fix cycle | full |
+| audit only, assessment, review, check | audit only | audit-only |
+
+## Target Detection
+
+| Signal | Target Type |
+|--------|-------------|
+| URL (http/https) | rendered-page |
+| File path (.tsx, .vue, .html, .css) | component-source |
+| "full site", "all pages", "entire app" | full-site |
+| Component name without path | component-source (search needed) |
+| Unclear | ask user |
+
+## Mode Determination
+
+| Signal | Pipeline Mode |
+|--------|---------------|
+| "audit only", "no fixes", "assessment", "review" | audit-only |
+| "full", "fix", "remediate", "complete cycle" | full |
+| Single audit domain (color OR typography OR focus only) | audit-only |
+| Unclear | ask user |
+
+## WCAG Level Detection
+
+| Signal | Level |
+|--------|-------|
+| "AA" or default | AA |
+| "AAA", "enhanced", "strict" | AAA |
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Single component | +1 |
+| Multiple components | +2 |
+| Full site | +3 |
+| Rendered page (Chrome DevTools) | +1 |
+| AAA level requested | +1 |
+| Fix cycle included | +1 |
+
+Results: 1-2 Low, 3-4 Medium, 5+ High
+
+## Output
+
+Write scope context to coordinator memory:
+```json
+{
+  "pipeline_mode": "<audit-only|full>",
+  "target": {
+    "type": "<rendered-page|component-source|full-site>",
+    "value": "<URL or file path or 'all'>"
+  },
+  "wcag_level": "<AA|AAA>",
+  "scope": "<description>",
+  "complexity": { "score": 0, "level": "Low|Medium|High" },
+  "chrome_devtools": true
+}
+```