claude-code-workflow 7.2.27 → 7.2.29

package/.codex/skills/team-ui-polish/specs/design-standards.md

@@ -0,0 +1,356 @@
+# Design Standards
+
+Impeccable's positive design standards. These are the target state -- what good looks like. Used by scanner for scoring (how close to ideal) and optimizer as fix targets.
+
+---
+
+## Color
+
+### Principles
+- Use **OKLCH** for perceptually uniform palettes. Colors at the same lightness actually look the same lightness
+- Tint neutrals toward brand hue (chroma 0.005-0.01). Never pure gray
+- **60-30-10 rule**: 60% neutral, 30% secondary/supporting, 10% accent
+- Semantic token hierarchy: primitive -> semantic -> component tokens
+- Never pure black (`#000`) or pure white (`#fff`). Always tint
+
+### Color Token Structure
+```
+--color-primary          oklch(0.55 0.2 250)
+--color-primary-hover    oklch(0.50 0.22 250)
+--color-primary-active   oklch(0.45 0.22 250)
+
+--color-neutral-50       oklch(0.98 0.005 250)    /* near-white, brand tinted */
+--color-neutral-100      oklch(0.95 0.005 250)
+--color-neutral-200      oklch(0.90 0.007 250)
+--color-neutral-300      oklch(0.80 0.007 250)
+--color-neutral-400      oklch(0.65 0.008 250)
+--color-neutral-500      oklch(0.50 0.008 250)
+--color-neutral-600      oklch(0.40 0.008 250)
+--color-neutral-700      oklch(0.30 0.008 250)
+--color-neutral-800      oklch(0.20 0.010 250)
+--color-neutral-900      oklch(0.13 0.010 250)
+--color-neutral-950      oklch(0.08 0.010 250)    /* near-black, brand tinted */
+
+--color-success          oklch(0.65 0.18 145)
+--color-warning          oklch(0.75 0.15 85)
+--color-error            oklch(0.55 0.22 25)
+--color-info             oklch(0.60 0.15 250)
+
+--color-surface          var(--color-neutral-50)
+--color-surface-raised   var(--color-neutral-100)
+--color-surface-overlay  var(--color-neutral-900 / 0.5)
+
+--color-text-primary     var(--color-neutral-900)
+--color-text-secondary   var(--color-neutral-600)
+--color-text-muted       var(--color-neutral-400)
+```
+
+### Contrast Requirements (WCAG AA)
+- Normal text (<18px / <24px bold): 4.5:1 minimum
+- Large text (>=18px / >=24px bold): 3:1 minimum
+- UI components and graphical objects: 3:1 minimum
+- Focus indicators: 3:1 against adjacent colors
+
+### Text on Colored Backgrounds
+- Never gray text on colored backgrounds (looks washed out)
+- Use shade of the background color, or white/dark with transparency
+- `color-mix(in oklch, var(--bg-color) 30%, black)` for text on colored surfaces
+
+---
+
+## Typography
+
+### Font Selection
+Avoid: Inter, Roboto, Open Sans, Lato, Montserrat, Arial (overused defaults).
+
+Recommended alternatives by category:
+- **Sans-serif body**: Instrument Sans, Plus Jakarta Sans, DM Sans, Geist, General Sans
+- **Sans-serif display**: Space Grotesk, Manrope, Outfit, Satoshi, Clash Display
+- **Serif display**: Fraunces, Playfair Display 2, Source Serif 4
+- **Monospace (code only)**: Geist Mono, JetBrains Mono, Fira Code
+
+### Modular Type Scale
+Choose one ratio and apply consistently:
+
+| Ratio | Name | Scale (base 16px) |
+|-------|------|--------------------|
+| 1.125 | Major Second | 16, 18, 20.25, 22.78, 25.63 |
+| 1.200 | Minor Third | 16, 19.2, 23.04, 27.65, 33.18 |
+| 1.250 | Major Third | 16, 20, 25, 31.25, 39.06 |
+| 1.333 | Perfect Fourth | 16, 21.33, 28.43, 37.9, 50.52 |
+| 1.500 | Perfect Fifth | 16, 24, 36, 54, 81 |
+
+### Fluid Sizing
+Use `clamp()` for display text:
+```css
+--text-xs:   0.75rem;                                    /* 12px, fixed */
+--text-sm:   0.875rem;                                   /* 14px, fixed */
+--text-base: 1rem;                                       /* 16px, body */
+--text-lg:   1.125rem;                                   /* 18px */
+--text-xl:   clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem);   /* 20-24px */
+--text-2xl:  clamp(1.5rem, 1.2rem + 1vw, 2rem);         /* 24-32px */
+--text-3xl:  clamp(1.875rem, 1.4rem + 1.5vw, 2.5rem);   /* 30-40px */
+--text-4xl:  clamp(2.25rem, 1.5rem + 2.5vw, 3.5rem);    /* 36-56px */
+```
+
+### Line Height & Spacing
+- Body text: `line-height: 1.5` (24px at 16px base)
+- Headings: `line-height: 1.2` (tighter)
+- Small text / captions: `line-height: 1.6`
+- Reading width: `max-width: 65ch` (range: 45-75ch)
+
+### Loading
+- `font-display: swap` on all custom fonts
+- Provide `size-adjust`, `ascent-override`, `descent-override` on fallback for minimal CLS
+
+---
+
+## Spacing
+
+### 4pt Base Scale
+```css
+--space-0:  0;
+--space-1:  0.25rem;   /* 4px */
+--space-2:  0.5rem;    /* 8px */
+--space-3:  0.75rem;   /* 12px */
+--space-4:  1rem;      /* 16px */
+--space-5:  1.25rem;   /* 20px */
+--space-6:  1.5rem;    /* 24px */
+--space-8:  2rem;      /* 32px */
+--space-10: 2.5rem;    /* 40px */
+--space-12: 3rem;      /* 48px */
+--space-16: 4rem;      /* 64px */
+--space-24: 6rem;      /* 96px */
+```
+
+### Rhythm
+- **Tight**: 4-8px within component groups (e.g., label + input, icon + text)
+- **Comfortable**: 16-24px between related items (e.g., list items, form fields)
+- **Generous**: 48-96px between major sections (e.g., page sections, content blocks)
+
+Monotonous spacing (same value everywhere) = no rhythm = boring. Vary spacing intentionally.
+
+### Layout Principles
+- Use `gap` instead of `margin` for sibling spacing
+- Cards only when content is truly distinct and actionable. Not everything needs a card
+- Flatten nested cards -- use spacing + subtle dividers instead
+- Container queries (`@container`) for component-level responsive
+- Touch targets: minimum 44x44px for all interactive elements
+- Optical adjustments: visually center, not mathematically center (e.g., play button in circle needs right offset)
+
+---
+
+## Motion
+
+### Property Rules
+- **Animate ONLY**: `transform`, `opacity`, `clip-path`, `background-color`, `color`, `border-color`, `box-shadow`, `filter`
+- **NEVER animate**: `width`, `height`, `top`, `left`, `right`, `bottom`, `margin`, `padding` (triggers layout)
+
+### Easing
+- **Default (ease-out-quart)**: `cubic-bezier(0.25, 1, 0.5, 1)` -- decelerates naturally
+- **Enter (ease-out)**: `cubic-bezier(0, 0, 0.25, 1)` -- elements arrive and settle
+- **Exit (ease-in)**: `cubic-bezier(0.5, 0, 0.75, 0)` -- elements accelerate away
+- **NEVER**: `ease` (default), `linear` (mechanical), bounce/elastic (dated)
+
+### Duration Scale
+```css
+--duration-instant:   100ms;   /* tooltip show, ripple */
+--duration-fast:      150ms;   /* button hover, focus ring */
+--duration-normal:    250ms;   /* dropdown open, tab switch */
+--duration-slow:      400ms;   /* modal open, sidebar slide */
+--duration-entrance:  500ms;   /* page entrance, hero animation */
+--duration-complex:   800ms;   /* complex sequence, page transition */
+```
+
+- Exit = 75% of entrance duration
+- Feedback (hover, active, focus): 100-150ms maximum
+- State change: 200-300ms
+- Layout change: 300-500ms
+
+### Stagger
+- Max visible items to stagger: 10
+- Total stagger duration: max 500ms
+- Formula: `animation-delay: calc(var(--index) * 50ms)`
+- Cap: `animation-delay: min(calc(var(--index) * 50ms), 500ms)`
+
+### Reduced Motion
+**Required** -- affects ~35% of adults over 40:
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+### will-change
+- Do NOT set in CSS (wastes GPU memory permanently)
+- Add via JS on `pointerenter` / `focusin`
+- Remove on `animationend` / `transitionend`
+
+---
+
+## Interaction States
+
+### The 8 Required States
+
+Every interactive element must define:
+
+| State | CSS | Visual Change |
+|-------|-----|---------------|
+| Default | -- | Base appearance |
+| Hover | `:hover` (wrap in `@media(hover:hover)`) | Subtle background/opacity change |
+| Focus | `:focus-visible` | Focus ring: 2px solid accent, offset 2px |
+| Active | `:active` | Scale down (0.97) or darker background |
+| Disabled | `[disabled], [aria-disabled="true"]` | Opacity 0.5, cursor not-allowed |
+| Loading | `[aria-busy="true"]` | Spinner/skeleton, disable interaction |
+| Error | `[aria-invalid="true"]` | Red border, error message below |
+| Success | custom class/attribute | Green check, success message |
+
+### Focus Ring Specification
+```css
+:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+  border-radius: inherit;
+}
+
+/* Only remove outline for mouse clicks */
+:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+Focus ring contrast: 3:1 minimum against all adjacent colors.
+
+### Form Labels
+- Always provide visible `<label>` elements
+- Placeholders are hints, NOT labels (they disappear)
+- Use `aria-labelledby` or `aria-label` for icon-only buttons
+- Error messages: `aria-describedby` linking input to error text
+
+### Touch Targets
+- Minimum: 44x44px (WCAG 2.5.5 AAA) / 24x24px (WCAG 2.5.8 AA minimum)
+- Use padding to increase hit area without changing visual size
+- Minimum 8px gap between adjacent targets
+
+---
+
+## Visual Hierarchy
+
+### Squint Test
+Blur the page (or squint). You should immediately identify:
+1. The most important element (usually primary heading or CTA)
+2. The second most important element
+3. Clear groupings of related content
+
+If everything looks the same when blurred, hierarchy has failed.
+
+### Hierarchy Tools (use 2-3 together)
+| Tool | Effect |
+|------|--------|
+| Size | Larger = more important. 3:1 ratio between major levels |
+| Weight | Bold vs regular vs light. Maximum 2 weights per page |
+| Color | Saturated vs muted. Primary color for emphasis |
+| Space | More surrounding space = more important |
+| Position | Top-left reads first (in LTR). Above fold > below fold |
+| Contrast | High contrast = more important. Low contrast recedes |
+
+### Primary Action Rule
+- Only 1 primary CTA per viewport
+- Primary: filled button, highest contrast, most saturated
+- Secondary: outline/ghost button
+- Tertiary: text link, no background
+
+### Progressive Disclosure
+- Show summary first, detail on demand
+- Expandable sections, "show more," detail panels
+- Do not dump all information at once
+
+---
+
+## Responsive Design
+
+### Breakpoints
+```css
+/* Mobile first */
+--bp-sm:  640px;    /* Small tablets */
+--bp-md:  768px;    /* Tablets */
+--bp-lg:  1024px;   /* Laptops */
+--bp-xl:  1280px;   /* Desktops */
+--bp-2xl: 1536px;   /* Large screens */
+```
+
+### Fluid Design Principles
+- Use `%`, `vw`, `fr`, `min()`, `max()`, `clamp()` instead of fixed `px` widths
+- `max-width` instead of `width` for containers
+- Grid with `fr` units for responsive layouts
+- Container queries (`@container`) for component-level responsiveness
+
+### Mobile Requirements
+- Minimum text: 14px (0.875rem), prefer 16px for body
+- Touch targets: 44x44px minimum
+- No horizontal scroll at >= 320px viewport
+- Must have `<meta name="viewport" content="width=device-width, initial-scale=1">`
+- Images: `max-width: 100%; height: auto`
+
+### Adapt, Don't Hide
+- Content should be restructured for smaller screens, not hidden
+- Stack horizontal layouts vertically
+- Use accordion/tabs for complex content
+- Simplify navigation (hamburger, bottom nav)
+
+---
+
+## UX Writing
+
+### Button Labels
+- NEVER: "OK", "Submit", "Yes", "No" (generic)
+- ALWAYS: verb + object -- "Save changes", "Create account", "Delete message"
+- Destructive: name the destruction + count -- "Delete 5 items"
+
+### Error Messages
+Formula: what happened + why + how to fix
+- "Password must be 8+ characters with a number" not "Invalid password"
+- Never blame user, never use codes alone
+- Preserve user input on error
+
+### Empty States
+Acknowledge + explain value + provide action
+- "No projects yet. Create your first project to start collaborating. [Create project]"
+
+### Loading Text
+- Specific: "Saving your draft..." not "Loading..."
+- Multi-step: "Uploading (2 of 5 files)..."
+
+### Consistency
+- One term per concept (delete/remove -> pick one)
+- Same icon for same action everywhere
+
+---
+
+## Dark Mode (when present)
+
+### Rules
+- NOT inverted light mode -- requires deliberate design
+- **Surface hierarchy**: lighter surfaces = higher elevation
+  - Base: `oklch(0.10-0.15 0.01 <hue>)`
+  - Raised: `oklch(0.18-0.22 0.01 <hue>)`
+  - Overlay: `oklch(0.24-0.28 0.01 <hue>)`
+- **Font weight**: reduce by 1 step (600->500, 500->400) -- light text on dark looks heavier
+- **Accent colors**: desaturate -- reduce OKLCH chroma by 0.05-0.10 from light theme values
+- Never: pure black `#000` background
+
+### Dangerous Combinations
+| Combination | Problem | Fix |
+|-------------|---------|-----|
+| Gray on colored bg | Washed out | Use shade of bg color or white with opacity |
+| Red + Green adjacent | Color blindness | Add icons/patterns |
+| Yellow on white | Invisible | Use dark amber |
+| Thin light text on images | Unpredictable contrast | Text shadow or overlay |
+| Saturated on dark | Visual vibration | Desaturate chroma |

package/.codex/skills/team-ui-polish/specs/fix-strategies.md

@@ -0,0 +1,235 @@
+# Fix Strategies
+
+Maps issue categories to Impeccable fix strategies. Used by diagnostician for fix planning and optimizer for implementation guidance.
+
+## Strategy Index
+
+| Issue Category | Fix Strategy | Impeccable Concept | Scope |
+|----------------|-------------|-------------------|-------|
+| AI slop aesthetic | De-template | normalize + critique | Systemic |
+| Color problems | Colorize | colorize | Systemic / Per-file |
+| Typography issues | Typeset | typeset | Systemic |
+| Spacing/layout | Arrange | arrange | Systemic / Per-file |
+| Animation issues | Animate | animate | Per-file |
+| Missing states | Harden | harden + polish | Per-component |
+| Visual noise | Simplify | quieter + distill | Per-component |
+| Too bland/weak | Strengthen | bolder + delight | Per-component |
+| Inconsistency | Normalize | normalize | Systemic |
+| Final pass | Polish | polish | Per-component |
+| Hierarchy issues | Clarify | distill + bolder | Per-page |
+| Responsive issues | Adapt | adapt | Per-component |
+
+---
+
+## De-template (Anti-AI-Slop)
+
+**When**: Anti-patterns dimension score 0-2 (AI slop or heavy AI influence)
+
+**Strategy**:
+1. Replace generic fonts with distinctive alternatives (see design-standards.md Typography)
+2. Convert gradient text to solid accent colors with weight/size emphasis instead
+3. Break identical card grids: vary sizes, add featured card, introduce asymmetry
+4. Remove decorative glassmorphism (keep functional like overlays)
+5. Redesign hero metrics with intentional hierarchy, not template layout
+6. Flatten nested cards into single-level with spacing
+7. Add left-alignment for body text, centering only for specific hero elements
+8. Create button hierarchy: 1 primary, ghost secondary, text tertiary
+9. Introduce spacing rhythm (tight within groups, generous between sections)
+10. Replace bounce easing with exponential curves
+
+**Dependency**: Requires Colorize and Typeset to be planned (often executed together).
+
+---
+
+## Colorize
+
+**When**: Color dimension score 0-2 or any P0/P1 color issues
+
+**Strategy**:
+1. **Token foundation** (if no tokens exist):
+   - Create CSS custom property file with full neutral scale (50-950)
+   - Define primary, semantic (success/warning/error/info), and surface tokens
+   - All neutrals tinted toward brand hue (OKLCH chroma 0.005-0.01)
+
+2. **Pure black/white removal**:
+   - `#000` -> `oklch(0.08-0.15 0.01 <hue>)` (near-black, brand tinted)
+   - `#fff` -> `oklch(0.97-0.99 0.005 <hue>)` (near-white, brand tinted)
+
+3. **Gray tinting**:
+   - Convert all pure grays to brand-tinted variants
+   - Add chroma 0.005-0.01 at brand hue
+
+4. **Contrast fixes**:
+   - Measure each text/background pair
+   - Adjust lightness until WCAG AA met (4.5:1 normal, 3:1 large)
+
+5. **OKLCH conversion**:
+   - Convert key palette colors from hex/hsl to oklch
+   - Generate tint/shade scales in OKLCH for perceptual uniformity
+
+6. **60-30-10 enforcement**:
+   - Audit accent color usage, reduce to ~10%
+   - Ensure neutral dominates at ~60%
+
+**Dependency**: Should run before De-template (anti-slop fixes may need new colors).
+
+---
+
+## Typeset
+
+**When**: Typography dimension score 0-2 or muddy hierarchy
+
+**Strategy**:
+1. **Font replacement**: Swap generic fonts for distinctive alternatives
+   - Body: Plus Jakarta Sans, Instrument Sans, DM Sans, Geist
+   - Display: Space Grotesk, Manrope, Fraunces
+2. **Scale establishment**: Choose modular ratio (1.25 or 1.333 recommended), generate size scale
+3. **Fluid sizing**: Add `clamp()` for h1-h3 display sizes
+4. **Line length**: Add `max-width: 65ch` to prose containers
+5. **Vertical rhythm**: Set line-height system (1.5 body, 1.2 headings)
+6. **Font loading**: Add `font-display: swap` to all @font-face
+
+**Dependency**: Run before Clarify (hierarchy depends on type scale).
+
+---
+
+## Arrange
+
+**When**: Spacing dimension score 0-2 or arbitrary spacing values
+
+**Strategy**:
+1. **Scale creation**: Define 4pt base scale as CSS custom properties
+2. **Value replacement**: Map arbitrary values to nearest scale value
+3. **Rhythm introduction**: Tight (4-8px) within groups, comfortable (16-24px) between items, generous (48-96px) between sections
+4. **Card flattening**: Remove nested cards, replace with spacing + subtle dividers
+5. **Gap conversion**: Replace margin between siblings with gap on flex/grid parent
+6. **Touch targets**: Ensure all interactive elements are 44x44px minimum
+
+**Dependency**: Independent, but benefits from Colorize tokens being in place.
+
+---
+
+## Animate
+
+**When**: Motion dimension score 0-2 or layout property animations
+
+**Strategy**:
+1. **Property fix**: Replace layout animations (width/height/margin/padding) with transform+opacity
+2. **Easing fix**: Replace ease/linear/bounce with exponential curves
+3. **Reduced-motion**: Add `@media (prefers-reduced-motion: reduce)` global rule
+4. **Token system**: Create duration + easing custom properties
+5. **Stagger cap**: Cap stagger at 10 items, 500ms total
+6. **will-change**: Remove from CSS, document JS activation pattern
+
+**Dependency**: Independent.
+
+---
+
+## Harden
+
+**When**: Interaction states dimension score 0-2 or missing critical states
+
+**Strategy**:
+1. **Hover**: Add `:hover` with subtle visual change, wrap in `@media(hover:hover)`
+2. **Focus**: Add `:focus-visible` with 2px solid accent ring, offset 2px
+3. **Active**: Add `:active` with scale(0.97) or darker background
+4. **Disabled**: Add `[disabled]` with opacity 0.5, cursor not-allowed
+5. **Loading**: Add aria-busy pattern with spinner/skeleton
+6. **Error/Success**: Add form validation visual states
+7. **Focus ring**: Ensure 3:1 contrast against all adjacent colors
+8. **Labels**: Replace placeholder-as-label with visible `<label>` elements
+9. **Touch targets**: Pad interactive elements to 44px minimum
+
+**Dependency**: Requires Colorize tokens for consistent state colors.
+
+---
+
+## Simplify (quieter + distill)
+
+**When**: Visual noise, too many decorations, competing elements
+
+**Strategy**:
+1. Remove decorative elements that do not aid comprehension
+2. Mute icon colors (reduce saturation/opacity)
+3. Remove background decorations and unnecessary borders
+4. Reduce shadow intensity
+5. Simplify card borders (remove or lighten)
+6. Remove sparkline decorations without data value
+
+**Dependency**: Independent.
+
+---
+
+## Strengthen (bolder + delight)
+
+**When**: Too bland, everything same weight, no emphasis
+
+**Strategy**:
+1. Increase primary element size by 1.5-2x
+2. Add color saturation to primary CTA
+3. Increase weight contrast (bold primary, regular secondary)
+4. Add subtle micro-interactions (hover lift, active press)
+5. Introduce one distinctive element (asymmetric layout, unexpected color, custom illustration)
+
+**Dependency**: Requires Typeset and Colorize to be in place.
+
+---
+
+## Clarify (hierarchy)
+
+**When**: Visual hierarchy dimension score 0-2 or fails squint test
+
+**Strategy**:
+1. Identify primary element, increase to 3:1 ratio over body
+2. Use 2-3 hierarchy tools together (size + weight + color)
+3. Group related content with proximity (smaller gaps within, larger between)
+4. Reduce visual weight of competing secondary elements
+5. Ensure only 1 primary CTA per viewport
+6. Add progressive disclosure where appropriate
+
+**Dependency**: Requires Typeset (size hierarchy) and Colorize (color hierarchy).
+
+---
+
+## Adapt (responsive)
+
+**When**: Responsive dimension score 0-2 or broken mobile experience
+
+**Strategy**:
+1. Replace fixed widths with fluid (%, vw, fr, min/max/clamp)
+2. Add missing breakpoints (640, 768, 1024, 1280px)
+3. Fix overflow (horizontal scroll causes)
+4. Fix mobile text sizes (minimum 14px)
+5. Fix touch targets (minimum 44px)
+6. Add container queries for component-level responsive
+7. Restructure hidden content (adapt, don't hide)
+8. Add viewport meta tag if missing
+
+**Dependency**: Run last -- tests all other fixes at different viewports.
+
+---
+
+## Fix Order (Default)
+
+When applying all strategies in a full polish cycle:
+
+```
+Phase 1: Foundation
+  1. Colorize (token system + color fixes)
+  2. Typeset (font + scale + fluid sizing)
+  3. Arrange (spacing scale + layout)
+
+Phase 2: Aesthetic
+  4. De-template (anti-AI-slop cleanup)
+  5. Simplify or Strengthen (as needed)
+
+Phase 3: Interaction
+  6. Animate (motion system)
+  7. Harden (interaction states)
+
+Phase 4: Structure
+  8. Clarify (visual hierarchy)
+
+Phase 5: Validation
+  9. Adapt (responsive -- tests everything)
+```

package/.codex/skills/team-ui-polish/specs/pipelines.md

@@ -0,0 +1,81 @@
+# Pipeline Definitions
+
+UI polish pipeline modes and task registry.
+
+## Pipeline Modes
+
+| Mode | Description | Task Count |
+|------|-------------|------------|
+| scan-only | Discover + diagnose, report only | 2 tasks |
+| targeted | Fix specific dimensions: scan -> diagnose -> optimize -> verify | 4 tasks |
+| full | Complete polish cycle with GC loop on verify failure | 4 tasks + GC |
+
+## Scan-Only Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| SCAN-001 | scanner | [] | 8-dimension UI audit against Impeccable design standards |
+| DIAG-001 | diagnostician | [SCAN-001] | Root cause analysis, severity classification, fix dependency graph |
+
+## Targeted Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| SCAN-001 | scanner | [] | 8-dimension UI audit (filtered to target dimensions) |
+| DIAG-001 | diagnostician | [SCAN-001] | Root cause analysis for targeted dimensions |
+| OPT-001 | optimizer | [DIAG-001] | Apply targeted fixes per Impeccable standards |
+| VERIFY-001 | verifier | [OPT-001] | Before/after comparison, regression check |
+
+## Full Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| SCAN-001 | scanner | [] | Full 8-dimension UI audit |
+| DIAG-001 | diagnostician | [SCAN-001] | Complete root cause analysis with fix dependency graph |
+| OPT-001 | optimizer | [DIAG-001] | Apply all fixes in dependency order |
+| VERIFY-001 | verifier | [OPT-001] | Verification with GC loop trigger |
+
+## GC Loop (Full Mode Only)
+
+| Checkpoint | Task | Condition | Action |
+|------------|------|-----------|--------|
+| VERIFY completes | VERIFY-* | verify_passed (no regressions, score >= before) | Pipeline complete |
+| VERIFY completes | VERIFY-* | verify_failed (non-critical regressions) | gc_rounds < 2 -> create OPT-fix task |
+| VERIFY completes | VERIFY-* | fix_required (critical regressions or score drop) | gc_rounds < 2 -> create OPT-fix task (CRITICAL) |
+| VERIFY completes | VERIFY-* | gc_rounds >= 2 | Escalate to user |
+
+### GC Fix Tasks (dynamically created)
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| OPT-fix-1 | optimizer | [VERIFY-001] | Fix regressions from round 1 verification |
+| VERIFY-002 | verifier | [OPT-fix-1] | Re-verify after round 1 fixes |
+| OPT-fix-2 | optimizer | [VERIFY-002] | Fix regressions from round 2 verification (if needed) |
+| VERIFY-003 | verifier | [OPT-fix-2] | Final re-verify (max round) |
+
+## Collaboration Patterns
+
+| Pattern | Roles | Description |
+|---------|-------|-------------|
+| CP-1 Linear Pipeline | All | Base sequential flow: scan -> diagnose -> optimize -> verify |
+| CP-2 Review-Fix (GC) | optimizer <-> verifier | Generator-Critic loop, max 2 rounds |
+
+## Spawn Rules
+
+| Mode | Behavior |
+|------|----------|
+| scan-only | Sequential: SCAN-001 then DIAG-001 |
+| targeted | Sequential: SCAN -> DIAG -> OPT -> VERIFY |
+| full | Sequential: SCAN -> DIAG -> OPT -> VERIFY, then GC loop if verify triggers |
+
+All modes use sequential spawning (one task at a time) since each task depends on the previous.
+
+## Output Artifacts
+
+| Task | Output Path |
+|------|-------------|
+| SCAN-001 | <session>/scan/scan-report.md |
+| DIAG-001 | <session>/diagnosis/diagnosis-report.md |
+| OPT-001 / OPT-fix-* | <session>/optimization/fix-log.md + modified source files |
+| VERIFY-001 / VERIFY-* | <session>/verification/verify-report.md |
+| Screenshots (if DevTools) | <session>/evidence/*.png |