ctx-cc 3.5.0 → 4.1.0

package/skills/ctx-state/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: ctx-state
+description: |
+  WHEN: Any CTX operation needs to read or write project state (.ctx/STATE.json), track phase transitions, log agent invocations, or record completed tasks.
+  WHEN NOT: Non-CTX work, or when the user hasn't initialized a CTX project.
+---
+
+# CTX State Manager
+
+Manages persistent state in `.ctx/STATE.json` for phase tracking, agent history, and task completion.
+
+## State Schema
+
+```json
+{
+  "version": "4.0",
+  "phase": "init|plan|execute|verify|complete",
+  "activeStory": "S001",
+  "storyTitle": "Story title",
+  "completedTasks": [
+    { "taskId": "T1", "title": "...", "completedAt": "ISO", "criteriaSatisfied": ["AC1"] }
+  ],
+  "agentHistory": [
+    { "agent": "ctx-planner", "invokedAt": "ISO", "completedAt": "ISO", "taskSummary": "..." }
+  ],
+  "reviewGate": {
+    "cycle": 0,
+    "history": []
+  },
+  "pipeline": null,
+  "session": {
+    "startedAt": "ISO",
+    "lastActivity": "ISO"
+  }
+}
+```
+
+## Valid Phase Transitions
+
+```
+init     → plan
+plan     → execute
+execute  → verify
+verify   → complete (if pass)
+verify   → execute  (if fail — retry)
+complete → init     (next story)
+ANY      → init     (reset)
+```
+
+**All other transitions are INVALID.** If you need to skip phases, reset to init first.
+
+## Operations
+
+### Initialize
+Create `.ctx/STATE.json` with `phase: "init"`. Optionally set `activeStory` and `storyTitle`.
+
+### Transition Phase
+1. Read current state
+2. Validate transition (see table above)
+3. Update `phase` field
+4. Update `session.lastActivity`
+5. Write state
+
+### Log Agent Invocation
+Append to `agentHistory`:
+```json
+{ "agent": "<name>", "invokedAt": "<now>", "completedAt": null, "taskSummary": "<what>" }
+```
+
+### Complete Agent Invocation
+Find last incomplete entry for the agent, set `completedAt` to now.
+
+### Record Completed Task
+Append to `completedTasks`:
+```json
+{ "taskId": "<id>", "title": "<title>", "completedAt": "<now>", "criteriaSatisfied": ["AC1"] }
+```
+
+### Session Handoff (Pause/Resume)
+**Pause:** Write `.ctx/HANDOFF.json` with current state snapshot + summary + next action.
+**Resume:** Read HANDOFF.json, archive it to `.ctx/handoffs/`, display summary.
+
+## Context Profiles
+
+Different agents need different project context. Load only what's needed:
+
+| Agent Type | Context Sources |
+|------------|----------------|
+| Planning (planner, predictor, criteria) | state, prd, repoMap, readme |
+| Execution (executor, debugger) | state, plan, repoMap |
+| Review (reviewer, auditor, verifier) | state, gitDiff, prd |
+| Mapping (mapper, arch-map, tech-map) | fileTree, readme |
+| Coordination (handoff, team) | state only |
+
+## Rules
+
+- ALWAYS read state before modifying it (no blind writes)
+- ALWAYS validate transitions before applying them
+- NEVER modify state from review/mapper agents — they are read-only
+- State file is the single source of truth for CTX workflow position

package/skills/ctx-visual-qa/SKILL.md

@@ -0,0 +1,587 @@
+---
+name: ctx-visual-qa
+description: |
+  WHEN: Visual QA, design parity check, pixel-perfect verification, responsive testing across breakpoints, accessibility audit (WCAG 2.2 AA), visual regression after design changes.
+  WHEN NOT: Functional testing unrelated to visuals, API testing, backend bug fixes, non-visual logic bugs.
+---
+
+# CTX Visual QA — Measurement-Driven Design Parity
+
+You verify that rendered output matches design specifications using numerical comparison, not subjective visual judgment. Every delta is measured and reported as a number. Fixes are specific: "change `font-size` from `14px` to `16px`".
+
+## Core Principle: Measure, Don't Guess
+
+Visual QA is not screenshot comparison. It is numerical audit:
+
+1. **Extract specs** from Figma via MCP — the design source of truth
+2. **Measure rendered output** via Playwright `browser_evaluate` using `getComputedStyle` and `getBoundingClientRect`
+3. **Compute deltas** — property by property
+4. **Report specifics** — exact property, expected value, actual value, delta
+5. **Feed corrections** — tell the developer exactly what to change
+
+---
+
+## Phase 1: Extract Figma Specs
+
+For each component or page under QA:
+
+```javascript
+// Get node-level design specs
+const designContext = await mcp__figma__get_design_context({
+  fileKey: figmaFileKey,
+  nodeId: targetNodeId
+});
+
+// Get variable/token values applied to the node
+const variables = await mcp__figma__get_variable_defs({
+  fileKey: figmaFileKey
+});
+
+// Screenshot the Figma node for reference
+const figmaScreenshot = await mcp__figma__get_screenshot({
+  fileKey: figmaFileKey,
+  nodeId: targetNodeId
+});
+// Save to .ctx/qa/visual/figma-spec-[component].png
+```
+
+Extract into a spec table:
+
+```markdown
+## Design Spec: Button (Primary)
+
+| Property | Spec Value | Source |
+|----------|-----------|--------|
+| font-size | 16px | font.size.base token |
+| font-weight | 600 | font.weight.semibold token |
+| line-height | 24px | computed |
+| padding-top | 12px | space.3 token |
+| padding-right | 16px | space.4 token |
+| padding-bottom | 12px | space.3 token |
+| padding-left | 16px | space.4 token |
+| min-height | 44px | button.min-height token |
+| min-width | 44px | button.min-width token |
+| border-radius | 8px | radius.md token |
+| background | oklch(0.52 0.18 264) | color.interactive.default |
+| color | #ffffff | color.text.on-accent |
+| letter-spacing | 0em | none |
+```
+
+---
+
+## Phase 2: Measure Rendered Output
+
+Navigate to the live component at the target URL (load from `.ctx/.env`):
+
+```javascript
+await mcp__playwright__browser_navigate({ url: `${APP_URL}/components/button` });
+```
+
+Run measurement script:
+
+```javascript
+const measurements = await mcp__playwright__browser_evaluate({
+  function: `
+    const selector = '[data-testid="button-primary"]';
+    const el = document.querySelector(selector);
+    if (!el) return { error: 'Element not found: ' + selector };
+
+    const computed = getComputedStyle(el);
+    const rect = el.getBoundingClientRect();
+
+    return {
+      // Typography
+      fontSize:      computed.fontSize,
+      fontWeight:    computed.fontWeight,
+      lineHeight:    computed.lineHeight,
+      letterSpacing: computed.letterSpacing,
+      fontFamily:    computed.fontFamily,
+
+      // Spacing
+      paddingTop:    computed.paddingTop,
+      paddingRight:  computed.paddingRight,
+      paddingBottom: computed.paddingBottom,
+      paddingLeft:   computed.paddingLeft,
+      marginTop:     computed.marginTop,
+      marginBottom:  computed.marginBottom,
+
+      // Dimensions
+      width:         rect.width,
+      height:        rect.height,
+      minHeight:     computed.minHeight,
+      minWidth:      computed.minWidth,
+
+      // Appearance
+      backgroundColor: computed.backgroundColor,
+      color:           computed.color,
+      borderRadius:    computed.borderRadius,
+      borderWidth:     computed.borderWidth,
+      borderColor:     computed.borderColor,
+      boxShadow:       computed.boxShadow,
+
+      // Interaction
+      cursor:    computed.cursor,
+      outline:   computed.outline,
+      transition: computed.transition
+    };
+  `
+});
+```
+
+---
+
+## Phase 3: Generate Precision Diff Table
+
+Compare spec vs rendered. Flag any delta outside tolerance.
+
+**Tolerance rules:**
+- Exact match required: font-weight, border-radius, min-height, min-width
+- ±1px tolerance: padding, margin, font-size, line-height
+- Color: parse to same color space before comparing (convert all to oklch or sRGB)
+
+```markdown
+## Precision Diff: Button (Primary) — Desktop 1440px
+
+| Property | Spec | Rendered | Delta | Status |
+|----------|------|----------|-------|--------|
+| font-size | 16px | 14px | -2px | FAIL |
+| font-weight | 600 | 600 | 0 | PASS |
+| padding-top | 12px | 12px | 0 | PASS |
+| padding-right | 16px | 16px | 0 | PASS |
+| min-height | 44px | 40px | -4px | FAIL |
+| min-width | 44px | auto | - | FAIL |
+| background-color | oklch(0.52 0.18 264) | oklch(0.52 0.18 264) | 0 | PASS |
+| border-radius | 8px | 6px | -2px | FAIL |
+| color | #ffffff | #ffffff | 0 | PASS |
+
+Failures: 4
+```
+
+---
+
+## Phase 4: Responsive Matrix
+
+Test every component at all three breakpoints by resizing the viewport.
+
+| Breakpoint | Width | Device Class |
+|------------|-------|-------------|
+| Mobile | 375px | iPhone 15 |
+| Tablet | 768px | iPad |
+| Desktop | 1440px | MacBook Pro |
+
+```javascript
+const breakpoints = [
+  { name: 'mobile',  width: 375,  height: 812 },
+  { name: 'tablet',  width: 768,  height: 1024 },
+  { name: 'desktop', width: 1440, height: 900 }
+];
+
+for (const bp of breakpoints) {
+  await mcp__playwright__browser_resize({ width: bp.width, height: bp.height });
+  await mcp__playwright__browser_wait_for({ time: 0.3 }); // allow reflow
+
+  // Re-run measurement script
+  const measurements = await mcp__playwright__browser_evaluate({ function: measureScript });
+
+  // Take screenshot
+  await mcp__playwright__browser_take_screenshot({
+    filename: `.ctx/qa/visual/${component}-${bp.name}.png`
+  });
+
+  // Record diff table per breakpoint
+}
+```
+
+Report layout-specific failures per breakpoint:
+
+```markdown
+## Responsive Matrix: Button (Primary)
+
+| Property | Mobile 375px | Tablet 768px | Desktop 1440px |
+|----------|-------------|-------------|----------------|
+| font-size | 14px (FAIL) | 16px (PASS) | 16px (PASS) |
+| min-height | 44px (PASS) | 44px (PASS) | 44px (PASS) |
+| padding-right | 12px (PASS) | 16px (PASS) | 16px (PASS) |
+
+Mobile font-size regression: change from 14px → 16px
+```
+
+---
+
+## Phase 5: Accessibility Audit (Automated)
+
+Run all checks via `browser_evaluate`. No manual interpretation.
+
+### 5.1 Color Contrast
+
+```javascript
+const contrastResults = await mcp__playwright__browser_evaluate({
+  function: `
+    function relativeLuminance(rgbStr) {
+      const match = rgbStr.match(/rgb\\((\\d+),\\s*(\\d+),\\s*(\\d+)\\)/);
+      if (!match) return null;
+      const [r, g, b] = [match[1], match[2], match[3]].map(v => {
+        const s = parseInt(v) / 255;
+        return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+      });
+      return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    }
+
+    function contrast(c1, c2) {
+      const l1 = relativeLuminance(c1);
+      const l2 = relativeLuminance(c2);
+      if (l1 === null || l2 === null) return null;
+      const lighter = Math.max(l1, l2);
+      const darker  = Math.min(l1, l2);
+      return ((lighter + 0.05) / (darker + 0.05)).toFixed(2);
+    }
+
+    const results = [];
+    document.querySelectorAll('p, h1, h2, h3, h4, h5, h6, span, a, button, label').forEach((el, i) => {
+      if (i > 100) return; // limit scan
+      const style = getComputedStyle(el);
+      const fg = style.color;
+      const bg = style.backgroundColor;
+      const text = el.textContent.trim().substring(0, 30);
+      const ratio = contrast(fg, bg);
+      const fontSize = parseFloat(style.fontSize);
+      const fontWeight = parseInt(style.fontWeight);
+      const isLargeText = fontSize >= 18 || (fontSize >= 14 && fontWeight >= 700);
+      const required = isLargeText ? 3.0 : 4.5;
+      results.push({
+        element: el.tagName,
+        text,
+        fg,
+        bg,
+        ratio: parseFloat(ratio),
+        required,
+        passes: ratio !== null && parseFloat(ratio) >= required
+      });
+    });
+    return results.filter(r => !r.passes);
+  `
+});
+```
+
+### 5.2 Touch Target Sizes
+
+```javascript
+const touchTargetResults = await mcp__playwright__browser_evaluate({
+  function: `
+    const violations = [];
+    document.querySelectorAll('a, button, input, select, textarea, [role="button"], [role="link"]').forEach(el => {
+      const rect = el.getBoundingClientRect();
+      // WCAG 2.2 SC 2.5.8: 24x24px minimum target size
+      if (rect.width < 24 || rect.height < 24) {
+        violations.push({
+          element:    el.tagName,
+          role:       el.getAttribute('role'),
+          text:       el.textContent.trim().substring(0, 40),
+          ariaLabel:  el.getAttribute('aria-label'),
+          width:      Math.round(rect.width),
+          height:     Math.round(rect.height),
+          required:   '24x24px'
+        });
+      }
+    });
+    return violations;
+  `
+});
+```
+
+### 5.3 Focus Indicator
+
+```javascript
+const focusResults = await mcp__playwright__browser_evaluate({
+  function: `
+    const violations = [];
+    const focusable = document.querySelectorAll(
+      'a, button, input, select, textarea, [tabindex]:not([tabindex="-1"])'
+    );
+
+    focusable.forEach(el => {
+      el.focus();
+      const style = getComputedStyle(el);
+      const outlineWidth  = parseFloat(style.outlineWidth);
+      const outlineColor  = style.outlineColor;
+      const boxShadow     = style.boxShadow;
+
+      // Must have visible outline OR box-shadow focus ring
+      const hasOutline    = outlineWidth >= 2;
+      const hasRing       = boxShadow !== 'none' && boxShadow.includes('0 0 0');
+
+      if (!hasOutline && !hasRing) {
+        violations.push({
+          element:     el.tagName,
+          text:        el.textContent.trim().substring(0, 40),
+          outlineWidth,
+          outlineColor,
+          boxShadow
+        });
+      }
+      el.blur();
+    });
+    return violations;
+  `
+});
+```
+
+### 5.4 Heading Hierarchy
+
+```javascript
+const headingResults = await mcp__playwright__browser_evaluate({
+  function: `
+    const headings = [...document.querySelectorAll('h1, h2, h3, h4, h5, h6')].map(h => ({
+      level:   parseInt(h.tagName[1]),
+      text:    h.textContent.trim().substring(0, 60)
+    }));
+
+    const violations = [];
+    for (let i = 1; i < headings.length; i++) {
+      const delta = headings[i].level - headings[i - 1].level;
+      if (delta > 1) {
+        violations.push({
+          from:  'h' + headings[i - 1].level + ': ' + headings[i - 1].text,
+          to:    'h' + headings[i].level + ': ' + headings[i].text,
+          skipped: delta - 1 + ' level(s)'
+        });
+      }
+    }
+
+    const h1Count = headings.filter(h => h.level === 1).length;
+    if (h1Count !== 1) violations.push({ issue: 'h1 count: ' + h1Count + ' (must be exactly 1)' });
+
+    return { headings, violations };
+  `
+});
+```
+
+### 5.5 Image Alt Text
+
+```javascript
+const altTextResults = await mcp__playwright__browser_evaluate({
+  function: `
+    const violations = [];
+    document.querySelectorAll('img').forEach(img => {
+      const alt = img.getAttribute('alt');
+      if (alt === null) {
+        violations.push({ src: img.src.substring(0, 80), issue: 'Missing alt attribute' });
+      } else if (alt.toLowerCase().startsWith('image of') || alt.toLowerCase().startsWith('photo of')) {
+        violations.push({ src: img.src.substring(0, 80), alt, issue: 'Redundant alt text prefix' });
+      }
+    });
+    return violations;
+  `
+});
+```
+
+### 5.6 ARIA Label Completeness
+
+```javascript
+const ariaResults = await mcp__playwright__browser_evaluate({
+  function: `
+    const violations = [];
+    // Icon buttons with no visible text must have aria-label
+    document.querySelectorAll('button').forEach(btn => {
+      const text    = btn.textContent.trim();
+      const label   = btn.getAttribute('aria-label');
+      const labelBy = btn.getAttribute('aria-labelledby');
+      const hasIcon = btn.querySelector('svg, img, [class*="icon"]');
+      if (!text && !label && !labelBy) {
+        violations.push({ element: 'button', html: btn.outerHTML.substring(0, 100), issue: 'No accessible name' });
+      }
+    });
+    // Interactive elements without accessible names
+    document.querySelectorAll('[role="button"], [role="link"], [role="checkbox"]').forEach(el => {
+      const label = el.getAttribute('aria-label');
+      const labelBy = el.getAttribute('aria-labelledby');
+      const text = el.textContent.trim();
+      if (!text && !label && !labelBy) {
+        violations.push({ role: el.getAttribute('role'), html: el.outerHTML.substring(0, 100), issue: 'No accessible name' });
+      }
+    });
+    return violations;
+  `
+});
+```
+
+### 5.7 Accessibility Audit Summary
+
+```markdown
+## Accessibility Audit — [Component/Page] — [ISO-8601]
+
+### WCAG 2.2 AA Results
+
+| Criterion | Check | Violations | Status |
+|-----------|-------|-----------|--------|
+| 1.1.1 Non-text Content | Alt text | 0 | PASS |
+| 1.4.3 Contrast (Minimum) | Text contrast 4.5:1 | 2 | FAIL |
+| 1.4.11 Non-text Contrast | UI component 3:1 | 0 | PASS |
+| 2.1.1 Keyboard | All focusable | - | manual |
+| 2.4.7 Focus Visible | Outline or ring | 1 | FAIL |
+| 2.4.11 Focus Not Obscured | Focus visible in viewport | - | manual |
+| 2.5.7 Dragging Alternatives | Click alternative | - | manual |
+| 2.5.8 Target Size | 24x24px minimum | 3 | FAIL |
+| 3.1.1 Language of Page | lang attribute | - | manual |
+| 4.1.2 Name, Role, Value | ARIA completeness | 0 | PASS |
+
+### Contrast Violations
+| Element | Text | Foreground | Background | Ratio | Required |
+|---------|------|-----------|-----------|-------|---------|
+| SPAN | "Placeholder text" | rgb(150,150,150) | rgb(255,255,255) | 2.85:1 | 4.5:1 |
+
+### Touch Target Violations
+| Element | Text/Label | Size | Required |
+|---------|-----------|------|---------|
+| BUTTON | icon-close | 20x20px | 24x24px |
+
+### Focus Indicator Violations
+| Element | Text | Outline Width | Status |
+|---------|------|--------------|--------|
+| A | "Read more" | 0px | No visible focus |
+```
+
+---
+
+## Phase 6: Visual Regression
+
+Capture baseline screenshots and compare after changes.
+
+### Taking Baselines
+
+```javascript
+// Capture baselines (run before making changes)
+for (const bp of breakpoints) {
+  await mcp__playwright__browser_resize({ width: bp.width, height: bp.height });
+  await mcp__playwright__browser_take_screenshot({
+    filename: `.ctx/qa/baselines/${component}-${bp.name}-baseline.png`
+  });
+}
+```
+
+### Post-Change Comparison
+
+After implementing changes:
+
+```javascript
+for (const bp of breakpoints) {
+  await mcp__playwright__browser_resize({ width: bp.width, height: bp.height });
+  await mcp__playwright__browser_take_screenshot({
+    filename: `.ctx/qa/visual/${component}-${bp.name}-after.png`
+  });
+}
+```
+
+Then use Gemini to analyze diffs:
+
+```javascript
+const regressionAnalysis = await mcp__gemini-design__gemini_analyze_design({
+  images: [
+    `.ctx/qa/baselines/${component}-desktop-baseline.png`,
+    `.ctx/qa/visual/${component}-desktop-after.png`
+  ],
+  prompt: `
+    Compare these two screenshots (before and after a code change).
+    Identify:
+    1. Any unintended visual regressions (layout shifts, color changes, size changes)
+    2. Elements that appear misaligned or broken
+    3. Text that has changed font, size, or color unexpectedly
+    Output a structured list of differences with bounding box descriptions.
+  `
+});
+```
+
+---
+
+## Phase 7: Gemini Design Analysis
+
+Use Gemini to assess subjective design quality:
+
+```javascript
+const designAnalysis = await mcp__gemini-design__gemini_analyze_design({
+  imagePath: `.ctx/qa/visual/${component}-desktop-after.png`,
+  prompt: `
+    Analyze this UI component screenshot as a senior product designer.
+    Evaluate:
+    1. Visual hierarchy — does the eye travel correctly?
+    2. Spacing consistency — is the spacing rhythm uniform?
+    3. Typography scale — do font sizes create clear hierarchy?
+    4. Color harmony — do the colors complement each other?
+    5. Alignment — are elements aligned to a consistent grid?
+    6. Overall polish — does this feel production-ready?
+
+    For each category provide: rating (1-5), observation, specific fix if needed.
+    Be specific. No vague feedback.
+  `
+});
+```
+
+---
+
+## Phase 8: QA Report
+
+Write to `.ctx/qa/VISUAL_QA_REPORT.md`:
+
+```markdown
+# Visual QA Report — [Component or Page]
+
+**Date:** [ISO-8601]
+**Tester:** ctx-visual-qa
+**Figma Node:** [node ID]
+**Breakpoints:** 375px / 768px / 1440px
+
+## Executive Summary
+
+| Check | Status | Issues |
+|-------|--------|--------|
+| Design Parity | FAIL | 4 deltas |
+| Responsive Layout | PASS | 0 issues |
+| Accessibility | FAIL | 6 violations |
+| Visual Regression | PASS | No regressions |
+| Gemini Design Score | 4.2/5 | Minor spacing |
+
+## Design Parity Failures
+
+### Button (Primary) — Desktop
+
+| Property | Spec | Rendered | Delta | Fix |
+|----------|------|----------|-------|-----|
+| font-size | 16px | 14px | -2px | Change font-size from 14px to 16px |
+| min-height | 44px | 40px | -4px | Change min-height from 40px to 44px |
+| border-radius | 8px | 6px | -2px | Change border-radius from 6px to 8px |
+
+## Accessibility Failures
+
+[Full table from Phase 5 audit]
+
+## Gemini Design Analysis
+
+[Structured feedback from Gemini]
+
+## Screenshots
+
+| Breakpoint | Figma Spec | Rendered |
+|-----------|-----------|---------|
+| Mobile 375px | figma-spec-mobile.png | button-mobile.png |
+| Desktop 1440px | figma-spec-desktop.png | button-desktop.png |
+
+## Corrections Required
+
+Developer action items — copy-paste ready:
+
+1. `src/components/Button.tsx` line 24: Change `fontSize: '14px'` → `fontSize: '16px'`
+2. `src/components/Button.tsx` line 30: Change `minHeight: '40px'` → `minHeight: '44px'`
+3. `src/components/Button.css` line 12: Change `border-radius: 6px` → `border-radius: 8px`
+4. `src/components/Button.tsx` line 18: Add `outlineOffset: '2px'` to focus ring styles
+```
+
+---
+
+## Operational Rules
+
+- Always load the app URL from `.ctx/.env` — never hardcode.
+- Run the responsive matrix at all three breakpoints on every QA pass.
+- Contrast checks are automated — never eyeball color pairs.
+- A component passes visual QA only when the precision diff table has zero FAIL rows AND all automated accessibility checks pass.
+- Screenshot every breakpoint before and after changes for regression tracking.
+- Corrections must be specific — file path, line number, property, old value, new value.