qa-workflow-cc 1.0.0

package/skills/qa/templates/visual-regression.md

@@ -0,0 +1,418 @@
+---
+name: visual-regression
+description: Set up and run visual regression tests for UI consistency. Use when verifying design system compliance and preventing visual regressions.
+context: fork
+agent: test-qa
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - Bash
+---
+
+# Visual Regression Testing
+
+This skill guides setup and execution of visual regression tests.
+
+## Prerequisites
+
+- Playwright installed for screenshot capture
+- Baseline screenshots established
+- CI/CD pipeline configured for visual tests
+
+---
+
+## Overview
+
+Visual regression testing captures screenshots and compares them against baselines to detect unintended visual changes.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ VISUAL REGRESSION WORKFLOW                              │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│   1. Capture baseline screenshots (first run)           │
+│   2. Make code changes                                  │
+│   3. Capture new screenshots                            │
+│   4. Compare against baselines                          │
+│   5. Review differences (if any)                        │
+│   6. Approve changes OR fix regressions                 │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Playwright Visual Testing Setup
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './visual-tests',
+
+  // Screenshot settings
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixels: 100,          // Allow small differences
+      maxDiffPixelRatio: 0.01,     // 1% pixel difference threshold
+      animations: 'disabled',      // Disable animations for consistency
+      caret: 'hide',               // Hide blinking cursor
+    },
+  },
+
+  // Use consistent viewport
+  use: {
+    viewport: { width: 1280, height: 720 },
+    deviceScaleFactor: 1,
+  },
+
+  // Only run on chromium for consistency
+  projects: [
+    {
+      name: 'visual-chromium',
+      use: { browserName: 'chromium' },
+    },
+  ],
+})
+```
+
+---
+
+## Basic Visual Test
+
+```typescript
+// visual-tests/pages.visual.ts
+import { test, expect } from '@playwright/test'
+
+test.describe('Page Visual Tests', () => {
+  test.beforeEach(async ({ page }) => {
+    // Login and navigate (customize per project)
+    await page.goto('/')
+    await page.waitForLoadState('networkidle')
+  })
+
+  test('homepage matches baseline', async ({ page }) => {
+    // Hide dynamic content
+    await page.evaluate(() => {
+      document.querySelectorAll('[data-testid="timestamp"]').forEach(el => {
+        el.textContent = '2024-01-15'
+      })
+    })
+
+    await expect(page).toHaveScreenshot('homepage-full.png', {
+      fullPage: true,
+    })
+  })
+
+  test('navigation matches baseline', async ({ page }) => {
+    const nav = page.locator('[data-testid="navigation"]')
+    await expect(nav).toHaveScreenshot('navigation.png')
+  })
+})
+```
+
+---
+
+## Component Visual Tests
+
+```typescript
+// visual-tests/components/buttons.visual.ts
+import { test, expect } from '@playwright/test'
+
+test.describe('Button Component Visual Tests', () => {
+  test('primary button states', async ({ page }) => {
+    await page.goto('/') // Navigate to a page with buttons
+
+    const primaryBtn = page.locator('[data-testid="btn-primary"]')
+
+    // Default state
+    await expect(primaryBtn).toHaveScreenshot('btn-primary-default.png')
+
+    // Hover state
+    await primaryBtn.hover()
+    await expect(primaryBtn).toHaveScreenshot('btn-primary-hover.png')
+
+    // Focus state
+    await primaryBtn.focus()
+    await expect(primaryBtn).toHaveScreenshot('btn-primary-focus.png')
+  })
+})
+```
+
+---
+
+## Responsive Visual Tests
+
+```typescript
+// visual-tests/responsive.visual.ts
+import { test, expect, devices } from '@playwright/test'
+
+const viewports = [
+  { name: 'mobile', ...devices['iPhone 13'] },
+  { name: 'tablet', viewport: { width: 768, height: 1024 } },
+  { name: 'desktop', viewport: { width: 1280, height: 720 } },
+  { name: 'wide', viewport: { width: 1920, height: 1080 } },
+]
+
+for (const vp of viewports) {
+  test.describe(`${vp.name} viewport`, () => {
+    test.use(vp)
+
+    test('layout', async ({ page }) => {
+      await page.goto('/')
+      await page.waitForLoadState('networkidle')
+
+      await expect(page).toHaveScreenshot(`layout-${vp.name}.png`, {
+        fullPage: true,
+      })
+    })
+  })
+}
+```
+
+---
+
+## Theme Visual Tests
+
+```typescript
+// visual-tests/themes.visual.ts
+import { test, expect } from '@playwright/test'
+
+test.describe('Theme Visual Tests', () => {
+  test('light theme', async ({ page }) => {
+    await page.goto('/')
+    await page.emulateMedia({ colorScheme: 'light' })
+    await page.waitForLoadState('networkidle')
+    await expect(page).toHaveScreenshot('theme-light.png')
+  })
+
+  test('dark theme', async ({ page }) => {
+    await page.goto('/')
+    await page.emulateMedia({ colorScheme: 'dark' })
+    await page.waitForLoadState('networkidle')
+    await expect(page).toHaveScreenshot('theme-dark.png')
+  })
+})
+```
+
+---
+
+## Handling Dynamic Content
+
+```typescript
+// visual-tests/utils/stabilize.ts
+import { Page } from '@playwright/test'
+
+export async function stabilizePage(page: Page) {
+  // Disable animations
+  await page.addStyleTag({
+    content: `
+      *, *::before, *::after {
+        animation-duration: 0s !important;
+        animation-delay: 0s !important;
+        transition-duration: 0s !important;
+        transition-delay: 0s !important;
+      }
+    `,
+  })
+
+  // Replace dynamic timestamps
+  await page.evaluate(() => {
+    document.querySelectorAll('[data-testid*="timestamp"]').forEach(el => {
+      el.textContent = '2024-01-15 10:00:00'
+    })
+    document.querySelectorAll('[data-testid*="relative-time"]').forEach(el => {
+      el.textContent = '5 minutes ago'
+    })
+  })
+
+  // Replace dynamic counts with stable values
+  await page.evaluate(() => {
+    document.querySelectorAll('[data-testid*="count"]').forEach(el => {
+      el.textContent = '42'
+    })
+  })
+
+  // Wait for fonts to load
+  await page.evaluate(() => document.fonts.ready)
+
+  // Wait for images to load
+  await page.waitForFunction(() => {
+    const images = document.querySelectorAll('img')
+    return Array.from(images).every(img => img.complete)
+  })
+}
+```
+
+---
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/visual-tests.yml
+name: Visual Regression Tests
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  visual-tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install # or pnpm install
+
+      - name: Install Playwright browsers
+        run: npx playwright install chromium
+
+      - name: Start app
+        run: npm run dev &
+
+      - name: Wait for app
+        run: npx wait-on http://localhost:3000
+
+      - name: Run visual tests
+        run: npm run visual-test
+
+      - name: Upload diff artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: visual-diff
+          path: visual-tests/test-results/
+          retention-days: 7
+```
+
+---
+
+## Updating Baselines
+
+```bash
+# Update all baselines
+npx playwright test --update-snapshots
+
+# Update specific test baselines
+npx playwright test pages.visual.ts --update-snapshots
+
+# Interactive update (approve changes one by one)
+npx playwright test --ui
+```
+
+---
+
+## Directory Structure
+
+```
+visual-tests/
+├── playwright.config.ts       # Visual test config
+├── pages.visual.ts            # Full page tests
+├── components/
+│   ├── buttons.visual.ts
+│   ├── cards.visual.ts
+│   └── forms.visual.ts
+├── responsive.visual.ts       # Responsive tests
+├── themes.visual.ts           # Theme tests
+├── utils/
+│   └── stabilize.ts          # Helper functions
+└── screenshots/               # Baseline images (git tracked)
+    ├── homepage-full-chromium.png
+    └── ...
+```
+
+---
+
+## Best Practices
+
+| Practice | Why |
+|----------|-----|
+| Use consistent viewport sizes | Prevents false positives from resize |
+| Disable animations | Animations cause flaky comparisons |
+| Replace dynamic content | Timestamps, counts change between runs |
+| Wait for network idle | Ensures all data loaded |
+| Wait for fonts | Font loading affects rendering |
+| Use data-testid for locators | More stable than CSS classes |
+| Run only on one browser | Reduces maintenance, ensures consistency |
+| Store baselines in git | Easy to review changes in PRs |
+
+---
+
+## Design System Assertions
+
+Visual regression tests should verify design system invariants programmatically:
+
+```typescript
+// visual-tests/design-system.visual.ts
+import { test, expect, Page } from '@playwright/test'
+
+async function getComputedStyle(page: Page, selector: string, property: string): Promise<string> {
+  return page.evaluate(
+    ({ sel, prop }) => {
+      const el = document.querySelector(sel)
+      if (!el) throw new Error(`Element not found: ${sel}`)
+      return window.getComputedStyle(el).getPropertyValue(prop)
+    },
+    { sel: selector, prop: property }
+  )
+}
+
+test.describe('Design System Invariants', () => {
+  test('touch targets meet 44x44px minimum', async ({ page }) => {
+    await page.goto('/')
+    await page.waitForLoadState('networkidle')
+
+    const violations = await page.evaluate(() => {
+      const interactive = document.querySelectorAll('button, a, [role="button"], input, select, textarea')
+      const small: string[] = []
+
+      for (const el of interactive) {
+        const rect = el.getBoundingClientRect()
+        if (rect.width > 0 && rect.height > 0) {
+          if (rect.width < 44 || rect.height < 44) {
+            small.push(`${el.tagName}${el.id ? '#' + el.id : ''}: ${rect.width}x${rect.height}`)
+          }
+        }
+      }
+
+      return small
+    })
+
+    expect(violations).toHaveLength(0)
+  })
+})
+```
+
+---
+
+## Checklist
+
+Before adding visual tests:
+
+- [ ] Identify pages/components to test
+- [ ] Handle dynamic content (timestamps, counts)
+- [ ] Disable animations
+- [ ] Define viewport sizes for responsive tests
+- [ ] Set appropriate diff thresholds
+- [ ] Configure CI/CD for visual test runs
+- [ ] Document baseline update process
+
+---
+
+## See Also
+
+- E2E testing skill
+- Component testing skill
+- Test standards
+- QA report template

package/skills/qa/workflows/bootstrap.md

@@ -0,0 +1,45 @@
+# Workflow: Bootstrap (Phase 0)
+
+<purpose>
+Thin interface document for bootstrap. Actual logic lives in SKILL.md (B1-B9). This file exists so commands can reference it consistently alongside other workflows.
+</purpose>
+
+<required_context>
+- SKILL: ~/.claude/skills/qa/SKILL.md (contains full B1-B9 protocol)
+</required_context>
+
+<process>
+
+## Input
+
+- `--rebootstrap` flag: Force re-discovery even if qa-profile.json exists
+
+## Execution
+
+Invoke the `/qa` skill which contains the full Phase 0 Bootstrap Protocol:
+
+| Step | Description |
+|------|-------------|
+| B1 | Root Discovery (package.json, framework detection, domain detection) |
+| B2 | Parallel Research (app discovery, security context, PRD analysis, Anthropic docs, stack/security/UX research) |
+| B3 | Monorepo structure detection |
+| B4 | Profile assembly (qa-profile.json) |
+| B5 | Directory creation + project-level CLAUDE.md registration |
+| B6 | File generation (skill files, agent files, test matrix) |
+| B7 | Existing file handling (skip user-modified files) |
+| B8 | Validation (check generated files) |
+| B9 | State checkpoint + output |
+
+## Output
+
+- `.claude/qa-profile.json` — project profile
+- `.claude/agents/qa-*.md` — 6 agent files
+- `.claude/skills/testing/*.md` — skill files
+- `docs/qa-reports/cycle-state.json` — initial state (`phase: "bootstrap_complete"`)
+
+## Terminal Output
+
+Read and output `~/.claude/skills/qa/templates/stop-points/bootstrap-complete.md`
+Substitute all `{placeholder}` values with profile data from B4.
+
+</process>

package/skills/qa/workflows/decision-gate.md

@@ -0,0 +1,66 @@
+# Workflow: Decision Gate (Phase 5)
+
+<purpose>
+Evaluate the consolidated report against exit criteria. Return PASS, FAIL, or ESCALATE. Pure logic — no agent spawning.
+</purpose>
+
+<required_context>
+- STATE: docs/qa-reports/cycle-state.json (cycle number, previousCycles, blockedDefectIds)
+- REPORT: docs/qa-reports/cycle-{N}-{date}.md (consolidated report)
+- EXIT_CRITERIA: ~/.claude/skills/qa/references/exit-criteria.md
+</required_context>
+
+<process>
+
+## 1. Read Exit Criteria
+
+Read `~/.claude/skills/qa/references/exit-criteria.md` on-demand.
+
+## 2. Read Consolidated Report
+
+Read the cycle report and extract:
+- Total tests, passing, failing
+- Defect counts by severity (critical, major, minor, cosmetic)
+- UX score, Lighthouse scores (if applicable)
+- Tenant isolation results (if applicable)
+- Auth boundary results (if applicable)
+
+## 3. Evaluate Against Thresholds
+
+For each gate in exit criteria, compare report values:
+
+| Gate | Threshold | Actual | Pass? |
+|------|-----------|--------|-------|
+{evaluate each gate}
+
+## 4. Determine Decision
+
+```
+IF all exit criteria pass:
+  → decision = "PASS"
+
+ELIF cycle >= 3 AND same defects persist across 2+ cycles:
+  → decision = "ESCALATE"
+
+ELIF cycle >= 3 AND blockedDefectIds.length > 0 across 2+ cycles:
+  → decision = "ESCALATE"
+
+ELSE:
+  → decision = "FAIL"
+```
+
+## 5. Write Decision to State
+
+Update cycle-state.json with decision BEFORE routing:
+```json
+{ "decision": "PASS|FAIL|ESCALATE", "verdict": "PASS|FAIL" }
+```
+
+## 6. Return Decision
+
+Return the decision to the calling command for phase routing:
+- **PASS** → Phase 8 (certification)
+- **FAIL** → Phase 6 (plan fixes)
+- **ESCALATE** → Phase 9 (escalation)
+
+</process>

package/skills/qa/workflows/fix-execute.md

@@ -0,0 +1,132 @@
+# Workflow: Fix Execution (Phase 7)
+
+<purpose>
+Execute approved fix plan by dispatching implementer agents per priority batch (P0 → P1 → P2), with post-implementation validation and correction loops.
+</purpose>
+
+<required_context>
+- PROFILE: .claude/qa-profile.json (commands.typeCheck, commands.build, agentRouting.fixRoutes)
+- STATE: docs/qa-reports/cycle-state.json (fixPlanPath, batchProgress)
+- MODEL_MAP: resolved models for fix-implementer and qa-verifier
+- FIX_PLAN: docs/qa-reports/fix-plan-cycle-{N}.md
+</required_context>
+
+<process>
+
+## 1. Write State Checkpoint
+
+```json
+{
+  "phase": "fixing",
+  "batchProgress": {
+    "completedBatches": [],
+    "currentBatch": null
+  }
+}
+```
+
+## 2. Load Fix Plan
+
+Read fix plan from `STATE.fixPlanPath`.
+Read agent routing from `PROFILE.agentRouting.fixRoutes`.
+
+## 3. For Each Priority Batch (P0 → P1 → P2)
+
+### 3a. Parse Batch
+
+Extract defect IDs, target files, fix approach, and target agent for each fix in the batch.
+
+### 3b. Pre-Applied Fix Detection
+
+For each fix, read target files and check if the fix appears already applied (e.g., from manual user changes). Skip to verification if already applied.
+
+### 3c. Analyze Independence
+
+- Fixes touching **different files** → dispatch in parallel
+- Fixes touching **same files** → dispatch sequentially
+
+### 3d. Dispatch Implementers
+
+For each fix needing implementation:
+
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="[FIX] Defect {defect-id} ({severity})
+
+  Root cause: {root-cause}
+  Fix approach: {approach}
+  Files to modify: {file-list}
+
+  PROJECT CONTEXT (inlined):
+  - TypeCheck command: {PROFILE.commands.typeCheck}
+  - Build command: {PROFILE.commands.build}
+
+  SCOPE CONSTRAINT: Targeted fix only, not a refactor.
+  Do NOT review your own code after writing it.",
+  model="{MODEL_MAP['fix-implementer']}",
+  description="Fix {defect-id}"
+)
+```
+
+### 3e. Post-Implementation Validation
+
+Orchestrator runs directly (not via agent):
+1. Type-check: `{PROFILE.commands.typeCheck}` → FAIL: re-dispatch (max 3 retries)
+2. Build: `{PROFILE.commands.build}` → FAIL: re-dispatch (max 3 retries)
+
+### 3f. Batch Verification
+
+Spawn qa-verifier for the batch:
+
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="[QA-VERIFIER] Read .claude/agents/qa-verifier.md.
+  IMPORTANT: Read the Resources section FIRST.
+
+  Re-run ONLY these previously failed tests: {batch-test-ids}
+
+  PROJECT CONTEXT (inlined):
+  - Test command: {PROFILE.commands.test}
+  - Apps: {relevant apps from PROFILE.apps}
+
+  Return PASS or STILL_FAILING for each test.",
+  model="{MODEL_MAP['qa-verifier']}",
+  description="Verify batch P{X}"
+)
+```
+
+### 3g. Correction Loop
+
+For STILL_FAILING results: re-dispatch implementer with verifier evidence (max 3 iterations per fix). After 3 failures, mark as BLOCKED and add to `blockedDefectIds`.
+
+### 3h. Batch Checkpoint
+
+Update state after each batch completes:
+```json
+{
+  "batchProgress": {
+    "completedBatches": ["P0"],
+    "currentBatch": "P1"
+  }
+}
+```
+
+## 4. Phase Gate
+
+Each batch must complete before the next starts. P0 → P1 → P2 strictly ordered.
+
+## 5. Final State Checkpoint
+
+After all batches complete:
+```json
+{ "phase": "verifying" }
+```
+
+## 6. Output Phase Transition
+
+Read and output `~/.claude/skills/qa/templates/stop-points/phase-transition.md`
+Substitute: {X} = 7, {Y} = 7b
+
+</process>

package/skills/qa/workflows/fix-plan.md

@@ -0,0 +1,52 @@
+# Workflow: Fix Plan (Phase 6)
+
+<purpose>
+Spawn fix planner agent to analyze defects and produce a prioritized fix plan. Does NOT include stop-point output — the calling command handles that.
+</purpose>
+
+<required_context>
+- PROFILE: .claude/qa-profile.json (agentRouting.fixRoutes, apps)
+- STATE: docs/qa-reports/cycle-state.json (cycle number, blockedDefectIds)
+- MODEL_MAP: resolved model for qa-fix-planner
+- REPORT: docs/qa-reports/cycle-{N}-{date}.md (consolidated report with defects)
+</required_context>
+
+<process>
+
+## 1. Spawn Fix Planner
+
+Inline defect data and agent routing into the prompt:
+
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="[QA-FIX-PLANNER] Read .claude/agents/qa-fix-planner.md.
+  IMPORTANT: Read the Resources section FIRST.
+
+  PROJECT CONTEXT (inlined from profile):
+  - Agent routing: {JSON of PROFILE.agentRouting.fixRoutes}
+  - Apps: {JSON summary of PROFILE.apps}
+
+  DEFECT SOURCE:
+  Analyze defects from: docs/qa-reports/cycle-{N}-{date}.md
+
+  EXCLUSIONS:
+  Exclude blocked defect IDs: {STATE.blockedDefectIds}
+
+  Write fix plan to: docs/qa-reports/fix-plan-cycle-{N}.md",
+  model="{MODEL_MAP['qa-fix-planner']}",
+  description="QA fix plan cycle {N}"
+)
+```
+
+## 2. Write State Checkpoint
+
+```json
+{ "phase": "awaiting_fix_approval", "fixPlanPath": "docs/qa-reports/fix-plan-cycle-{N}.md" }
+```
+
+## 3. Verify Files Exist
+
+Read back fix plan and cycle-state.json to confirm writes succeeded.
+
+</process>