maestro-flow 0.5.31 → 0.5.33

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

@@ -0,0 +1,180 @@
+---
+role: color-auditor
+prefix: COLOR
+inner_loop: false
+message_types: [state_update]
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# 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/.agents/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
+}
+```

package/.agents/skills/team-visual-a11y/roles/coordinator/commands/dispatch.md

@@ -0,0 +1,250 @@
+# Command: Dispatch
+
+Create the visual accessibility task chain with correct dependencies and structured task descriptions. Supports audit-only and full pipeline modes.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| User requirement | From coordinator Phase 1 | Yes |
+| Session folder | From coordinator Phase 2 | Yes |
+| Pipeline mode | From session meta.json `pipeline` | Yes |
+| Target info | From session meta.json `target` | Yes |
+
+1. Load user requirement and scope from meta.json
+2. Load pipeline stage definitions from specs/pipelines.md
+3. Read `pipeline` and `target` from meta.json
+
+## Phase 3: Task Chain Creation (Mode-Branched)
+
+### Task Description Template
+
+Every task description uses structured format:
+
+```
+create_task({
+  subject: "<TASK-ID>",
+  description: "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>
+TASK:
+  - <step 1: specific action>
+  - <step 2: specific action>
+  - <step 3: specific action>
+CONTEXT:
+  - Session: <session-folder>
+  - Target: <URL or file path>
+  - WCAG Level: <AA|AAA>
+  - Upstream artifacts: <artifact-1>, <artifact-2>
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: <deliverable path> + <quality criteria>
+CONSTRAINTS: <scope limits, focus areas>"
+})
+update_task({ taskId: "<TASK-ID>", addBlockedBy: [<dependency-list>], owner: "<role>" })
+```
+
+### Mode Router
+
+| Mode | Action |
+|------|--------|
+| `audit-only` | Create 4 tasks: [COLOR-001 + TYPO-001 + FOCUS-001] parallel -> REMED-001 |
+| `full` | Create 7 tasks: [COLOR-001 + TYPO-001 + FOCUS-001] -> REMED-001 -> FIX-001 -> [COLOR-002 + FOCUS-002] |
+
+---
+
+### Audit-Only Pipeline Task Chain
+
+**COLOR-001** (color-auditor):
+```
+create_task({
+  subject: "COLOR-001",
+  description: "PURPOSE: OKLCH color contrast audit for all color combinations | Success: Complete color audit with WCAG 2.1 + APCA contrast ratios and color blindness assessment
+TASK:
+  - Extract all color values (OKLCH, HSL, RGB, hex) from stylesheets
+  - Calculate WCAG 2.1 contrast ratios for all text/background combinations
+  - Calculate APCA Lc values for body and large text
+  - Assess OKLCH lightness ranges for text and backgrounds
+  - Simulate color blindness (protanopia, deuteranopia, tritanopia)
+  - Check dark mode color parity if applicable
+CONTEXT:
+  - Session: <session-folder>
+  - Target: <target>
+  - WCAG Level: <level>
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: <session>/audits/color/color-audit-001.md | Pass/fail per color combination
+CONSTRAINTS: Read-only analysis | Use Chrome DevTools for computed styles when available"
+})
+update_task({ taskId: "COLOR-001", owner: "color-auditor" })
+```
+
+**TYPO-001** (typo-auditor):
+```
+create_task({
+  subject: "TYPO-001",
+  description: "PURPOSE: Typography readability audit across all viewports | Success: Complete typography audit with size, line-height, reading width at each breakpoint
+TASK:
+  - Audit font sizes at each breakpoint (320px, 768px, 1024px, 1400px)
+  - Validate minimum body text >= 16px on mobile
+  - Check line-height ratios (body 1.5-1.75, headings 1.1-1.3)
+  - Validate clamp() functions for responsive scaling
+  - Measure reading width (45-75 characters per line)
+  - Assess font loading strategy (font-display values)
+CONTEXT:
+  - Session: <session-folder>
+  - Target: <target>
+  - WCAG Level: <level>
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: <session>/audits/typography/typo-audit-001.md | Breakpoint-by-breakpoint report
+CONSTRAINTS: Read-only analysis | Screenshot at multiple viewports if Chrome DevTools available"
+})
+update_task({ taskId: "TYPO-001", owner: "typo-auditor" })
+```
+
+**FOCUS-001** (focus-auditor):
+```
+create_task({
+  subject: "FOCUS-001",
+  description: "PURPOSE: Focus management and keyboard accessibility audit | Success: Complete focus audit with tab order, indicator visibility, ARIA coverage
+TASK:
+  - Audit tab order for logical sequence and no tab traps
+  - Check focus indicator visibility (outline >= 2px, contrast >= 3:1)
+  - Verify :focus-visible usage for keyboard vs mouse distinction
+  - Check skip link presence and functionality
+  - Audit focus traps in modals/dialogs (Tab cycles, Escape dismisses)
+  - Verify ARIA live regions for dynamic content
+  - Check ARIA roles and states on interactive elements
+  - Validate keyboard operability (Enter/Space, Arrow keys)
+CONTEXT:
+  - Session: <session-folder>
+  - Target: <target>
+  - WCAG Level: <level>
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: <session>/audits/focus/focus-audit-001.md | Element-by-element focus report
+CONSTRAINTS: Read-only analysis | Tab through elements if Chrome DevTools available"
+})
+update_task({ taskId: "FOCUS-001", owner: "focus-auditor" })
+```
+
+**CRITICAL**: COLOR-001, TYPO-001, FOCUS-001 have NO blockedBy -- they run in PARALLEL.
+
+**REMED-001** (remediation-planner):
+```
+create_task({
+  subject: "REMED-001",
+  description: "PURPOSE: Synthesize all 3 audit findings into prioritized remediation plan | Success: Complete remediation plan with severity ranking, code-level fix guidance, WCAG criterion mapping
+TASK:
+  - Read color, typography, and focus audit reports
+  - Merge and deduplicate findings
+  - Prioritize by severity (Critical > High > Medium > Low)
+  - Group by file/component for efficient fixing
+  - Provide code-level fix guidance (specific CSS/HTML changes)
+  - Map each fix to WCAG success criterion
+  - Estimate effort per fix
+CONTEXT:
+  - Session: <session-folder>
+  - Target: <target>
+  - WCAG Level: <level>
+  - Upstream artifacts: audits/color/color-audit-001.md, audits/typography/typo-audit-001.md, audits/focus/focus-audit-001.md
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: <session>/remediation/remediation-plan.md | All critical/high issues addressed
+CONSTRAINTS: Read-only synthesis | No code modifications"
+})
+update_task({ taskId: "REMED-001", addBlockedBy: ["COLOR-001", "TYPO-001", "FOCUS-001"], owner: "remediation-planner" })
+```
+
+---
+
+### Full Pipeline Task Chain
+
+Same as audit-only (COLOR-001, TYPO-001, FOCUS-001, REMED-001), plus:
+
+**FIX-001** (fix-implementer):
+```
+create_task({
+  subject: "FIX-001",
+  description: "PURPOSE: Implement accessibility fixes from remediation plan | Success: All critical and high severity issues fixed with passing contrast ratios and ARIA validation
+TASK:
+  - Read remediation plan for prioritized fix list
+  - Apply OKLCH color corrections for contrast compliance
+  - Add/fix focus styles (outline, outline-offset, :focus-visible)
+  - Add missing ARIA attributes (role, aria-label, aria-live, aria-expanded)
+  - Add reduced-motion media queries where needed
+  - Fix typography (clamp(), line-height, max-width for reading)
+  - Add skip link if missing
+  - Apply fixes in priority order (critical first)
+CONTEXT:
+  - Session: <session-folder>
+  - Target: <target>
+  - WCAG Level: <level>
+  - Upstream artifacts: remediation/remediation-plan.md
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: Modified source files + <session>/fixes/fix-summary-001.md | All critical/high fixes applied
+CONSTRAINTS: Modify only files identified in remediation plan | Preserve existing functionality"
+})
+update_task({ taskId: "FIX-001", addBlockedBy: ["REMED-001"], owner: "fix-implementer" })
+```
+
+**COLOR-002** (color-auditor):
+```
+create_task({
+  subject: "COLOR-002",
+  description: "PURPOSE: Re-audit color contrast after fixes applied | Success: All color combinations pass WCAG target level
+TASK:
+  - Re-extract all color values from modified stylesheets
+  - Re-calculate WCAG 2.1 contrast ratios
+  - Re-calculate APCA Lc values
+  - Compare before/after for each fixed combination
+  - Verify no regressions in unfixed combinations
+CONTEXT:
+  - Session: <session-folder>
+  - Target: <target>
+  - WCAG Level: <level>
+  - Upstream artifacts: fixes/fix-summary-001.md, audits/color/color-audit-001.md
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: <session>/re-audit/color-audit-002.md | Before/after comparison with pass/fail
+CONSTRAINTS: Read-only verification | Focus on fixed items + regression check"
+})
+update_task({ taskId: "COLOR-002", addBlockedBy: ["FIX-001"], owner: "color-auditor" })
+```
+
+**FOCUS-002** (focus-auditor):
+```
+create_task({
+  subject: "FOCUS-002",
+  description: "PURPOSE: Re-audit focus management after fixes applied | Success: All focus indicators visible with correct ARIA attributes
+TASK:
+  - Re-audit tab order after DOM changes
+  - Verify focus indicator fixes (outline, contrast)
+  - Check new ARIA attributes are valid
+  - Verify skip link implementation
+  - Test keyboard operability of fixed elements
+  - Compare before/after for each fixed element
+CONTEXT:
+  - Session: <session-folder>
+  - Target: <target>
+  - WCAG Level: <level>
+  - Upstream artifacts: fixes/fix-summary-001.md, audits/focus/focus-audit-001.md
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: <session>/re-audit/focus-audit-002.md | Before/after comparison with pass/fail
+CONSTRAINTS: Read-only verification | Focus on fixed items + regression check"
+})
+update_task({ taskId: "FOCUS-002", addBlockedBy: ["FIX-001"], owner: "focus-auditor" })
+```
+
+**CRITICAL**: COLOR-002 and FOCUS-002 both blocked only by FIX-001 -- they run in PARALLEL after fixes.
+
+---
+
+## Phase 4: Validation
+
+Verify task chain integrity:
+
+| Check | Method | Expected |
+|-------|--------|----------|
+| Task count correct | list_tasks count | audit-only: 4, full: 7 |
+| Dependencies correct | Trace dependency graph | Acyclic, correct blockedBy |
+| No circular dependencies | Trace dependency graph | Acyclic |
+| 3 audit tasks have NO blockedBy | Pattern check | COLOR-001, TYPO-001, FOCUS-001 are parallel |
+| REMED-001 blocked by all 3 | Check blockedBy | [COLOR-001, TYPO-001, FOCUS-001] |
+| Task IDs use correct prefixes | Pattern check | COLOR/TYPO/FOCUS/REMED/FIX |
+| Structured descriptions complete | Each has PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | All present |
+
+If validation fails, fix the specific task and re-validate.