@harness-engineering/cli 1.6.2 → 1.8.0

package/dist/agents/skills/gemini-cli/harness-soundness-review/skill.yaml

@@ -0,0 +1,48 @@
+name: harness-soundness-review
+version: "1.0.0"
+description: Deep soundness analysis of specs and plans with auto-fix and convergence loop
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-soundness-review
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: mode
+      description: Review mode — "spec" for spec soundness or "plan" for plan soundness
+      required: true
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-soundness-review
+    path: string
+type: rigid
+phases:
+  - name: check
+    description: Run all checks for the current mode and classify findings
+    required: true
+  - name: fix
+    description: Auto-fix inferrable issues and log changes
+    required: true
+  - name: converge
+    description: Re-run checks, compare issue counts, loop or stop
+    required: true
+  - name: surface
+    description: Present remaining issues to user for resolution
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/harness-test-advisor/SKILL.md

@@ -13,8 +13,23 @@
 
 ## Prerequisites
 
-A knowledge graph must exist at `.harness/graph/`. Run `harness scan` if no graph is available.
-If the graph exists but code has changed since the last scan, re-run `harness scan` first — stale graph data leads to inaccurate results.
+A knowledge graph at `.harness/graph/` enables full analysis. If no graph exists,
+the skill uses static analysis fallbacks (see Graph Availability section).
+Run `harness scan` to enable graph-enhanced analysis.
+
+### Graph Availability
+
+Before starting, check if `.harness/graph/graph.json` exists.
+
+**If graph exists:** Check staleness — compare `.harness/graph/metadata.json`
+scanTimestamp against `git log -1 --format=%ct` (latest commit timestamp).
+If graph is more than 10 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
+run `harness scan` to refresh before proceeding. (Staleness sensitivity: **Medium**)
+
+**If graph exists and is fresh (or refreshed):** Use graph tools as primary strategy.
+
+**If no graph exists:** Output "Running without graph (run `harness scan` to
+enable full analysis)" and use fallback strategies for all subsequent steps.
 
 ## Process
 
@@ -43,6 +58,20 @@ For each changed file, use graph traversal to find test files:
 
 3. **Co-change tests**: Check `co_changes_with` edges for test files that historically change alongside the modified files.
 
+#### Fallback (without graph)
+
+When no graph is available, use naming conventions, import parsing, and git history:
+
+1. **Tier 1 — Filename convention matching**: For each changed file `foo.ts`, search for:
+   - `foo.test.ts`, `foo.spec.ts` (same directory)
+   - `__tests__/foo.ts`, `__tests__/foo.test.ts`
+   - Test files in a parallel `tests/` directory mirroring the source path
+2. **Tier 2 — Import-linked tests**: Parse test files' import statements (grep for `import.*from` in `*.test.*` and `*.spec.*` files). If a test file imports the changed file, it belongs in Tier 2 (if not already in Tier 1).
+3. **Tier 3 — Co-change correlated tests**: Use `git log --format="%H" --name-only` to find test files that frequently change in the same commit as the target file. Files that co-change in >2 commits are co-change correlated.
+4. **Rank**: Tier 1 = direct filename match, Tier 2 = import-linked tests, Tier 3 = co-change correlated tests. Output the same tiered format as the graph version.
+
+> Fallback completeness: ~80% — naming conventions and imports catch most mappings; misses dynamic imports and indirect coverage.
+
 ### Phase 3: PRIORITIZE — Rank and Generate Commands
 
 Organize tests into three tiers:
@@ -85,7 +114,7 @@ npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes
 
 ## Harness Integration
 
-- **`harness scan`** — Must run before this skill to ensure graph is current.
+- **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses naming convention and import parsing fallbacks.
 - **`harness validate`** — Run after acting on findings to verify project health.
 - **Graph tools** — This skill uses `query_graph`, `get_impact`, and `get_relationships` MCP tools.
 
@@ -95,7 +124,7 @@ npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes
 - Executable run commands generated for quick and full test runs
 - Coverage gaps flagged for changed files with no test coverage
 - Report follows the structured output format
-- All findings are backed by graph query evidence, not heuristics
+- All findings are backed by graph query evidence (with graph) or systematic static analysis (without graph)
 
 ## Examples
 
@@ -122,8 +151,8 @@ Output:
 
 ## Gates
 
-- **No advice without graph.** If no graph exists, fall back to: "Run all tests in the same directory as changed files."
-- **Always include Tier 1.** Direct test coverage is non-negotiable — always recommend running these.
+- **Graph preferred, fallback available.** If no graph exists, use naming conventions, import parsing, and git co-change analysis to identify relevant tests. Do not stop — produce the best test selection possible.
+- **Always include Tier 1.** Direct test coverage is non-negotiable — always recommend running these (whether found via graph or naming conventions).
 
 ## Escalation
 

package/dist/agents/skills/node_modules/.bin/vitest

@@ -6,9 +6,9 @@ case `uname` in
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/harness-engineering/harness-engineering/node_modules/.pnpm/vitest@4.0.18_@types+node@22.19.15_yaml@2.8.2/node_modules/vitest/node_modules:/home/runner/work/harness-engineering/harness-engineering/node_modules/.pnpm/vitest@4.0.18_@types+node@22.19.15_yaml@2.8.2/node_modules:/home/runner/work/harness-engineering/harness-engineering/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/home/runner/work/harness-engineering/harness-engineering/node_modules/.pnpm/vitest@4.0.18_yaml@2.8.2/node_modules/vitest/node_modules:/home/runner/work/harness-engineering/harness-engineering/node_modules/.pnpm/vitest@4.0.18_yaml@2.8.2/node_modules:/home/runner/work/harness-engineering/harness-engineering/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/home/runner/work/harness-engineering/harness-engineering/node_modules/.pnpm/vitest@4.0.18_@types+node@22.19.15_yaml@2.8.2/node_modules/vitest/node_modules:/home/runner/work/harness-engineering/harness-engineering/node_modules/.pnpm/vitest@4.0.18_@types+node@22.19.15_yaml@2.8.2/node_modules:/home/runner/work/harness-engineering/harness-engineering/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/home/runner/work/harness-engineering/harness-engineering/node_modules/.pnpm/vitest@4.0.18_yaml@2.8.2/node_modules/vitest/node_modules:/home/runner/work/harness-engineering/harness-engineering/node_modules/.pnpm/vitest@4.0.18_yaml@2.8.2/node_modules:/home/runner/work/harness-engineering/harness-engineering/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
   exec "$basedir/node"  "$basedir/../vitest/vitest.mjs" "$@"

package/dist/agents/skills/shared/design-knowledge/anti-patterns/color.yaml

@@ -0,0 +1,106 @@
+description: "Color anti-patterns — common mistakes that harm accessibility, consistency, and brand integrity"
+
+patterns:
+  - name: "Hardcoded color values instead of tokens"
+    severity: warning
+    scope: all
+    detect:
+      method: "Grep for hex (#xxx, #xxxxxx), rgb(), rgba(), hsl(), hsla() values in component code that are not defined in tokens.json"
+      exclude: ["test files", "fixture files", "storybook stories"]
+    reason: "Hardcoded colors bypass the design token system, creating inconsistency and making global palette changes impossible without find-and-replace."
+    instead: "Reference design tokens: use CSS custom properties (var(--color-primary)), Tailwind classes (text-primary), or platform token bindings."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Insufficient contrast ratio (WCAG AA)"
+    severity: error
+    scope: all
+    detect:
+      method: "Calculate contrast ratio between foreground text color and background color"
+      threshold: "< 4.5:1 for normal text, < 3:1 for large text (18px+ or 14px+ bold)"
+    reason: "Low contrast text is unreadable for users with low vision, color blindness, or in bright ambient light. WCAG 2.1 Level AA requires 4.5:1 minimum."
+    instead: "Use pre-validated contrast pairs from the palette. Check ratios with a contrast checker before committing."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Color as the only differentiator"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for status indicators, form validation, or interactive states that rely solely on color change"
+      context: "Success/error/warning states, required field indicators, active/inactive toggles"
+    reason: "Approximately 8% of men and 0.5% of women have color vision deficiency. Color-only indicators are invisible to them."
+    instead: "Combine color with a secondary indicator: icons, text labels, patterns, or border changes. Error states should include both red color AND an error icon/message."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Too many colors in a single view"
+    severity: warning
+    scope: all
+    detect:
+      method: "Count distinct non-neutral hues in a single screen or component"
+      threshold: "> 5 distinct hues (excluding neutrals/grays)"
+    reason: "Excessive color variety creates visual noise, weakens brand identity, and makes it harder for users to learn the color semantics of the interface."
+    instead: "Limit to 1-2 brand colors + 1 accent + semantic colors (success/warning/error/info). Use neutrals for everything else."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Pure black (#000000) on pure white (#ffffff)"
+    severity: info
+    scope: web
+    detect:
+      css_properties: ["color", "background-color"]
+      values: ["#000000 on #ffffff", "#000 on #fff"]
+    reason: "Maximum contrast (21:1) can cause eye strain during extended reading, especially on bright displays. High contrast also creates harsh vibration at text edges."
+    instead: "Use near-black (e.g., #0f172a, #18181b) on near-white (e.g., #fafafa, #f8fafc) for a comfortable reading experience while maintaining excellent contrast ratios."
+    strictness:
+      permissive: info
+      standard: info
+      strict: warn
+
+  - name: "Opacity/alpha for semantic colors"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for rgba() or opacity applied to semantic colors (success, error, warning)"
+      context: "Background fills behind status text, badge backgrounds"
+    reason: "Transparent semantic colors shift hue depending on what's behind them. A red error badge over a blue card becomes purple, confusing the semantic meaning."
+    instead: "Use solid, pre-defined tint colors for semantic backgrounds (e.g., red-50 for error background, green-50 for success) instead of applying opacity to the base color."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Brand colors used for destructive actions"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check if primary brand color is applied to delete, remove, or destructive action buttons"
+    reason: "Using the brand color for destructive actions creates cognitive dissonance — the color that means 'go/primary' also means 'danger'. Users learn to hesitate on all primary-colored actions."
+    instead: "Reserve red (or a distinct danger color) for destructive actions. Primary brand color is for constructive actions only."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Gradient text without fallback"
+    severity: info
+    scope: web
+    detect:
+      css_properties: ["background-clip", "-webkit-background-clip"]
+      values: ["text"]
+      absent: ["color fallback"]
+    reason: "Gradient text using background-clip: text has inconsistent browser support and can disappear entirely if the gradient fails to render."
+    instead: "Always set a solid color fallback before the gradient declaration. Test in all target browsers."
+    strictness:
+      permissive: info
+      standard: info
+      strict: warn

package/dist/agents/skills/shared/design-knowledge/anti-patterns/layout.yaml

@@ -0,0 +1,109 @@
+description: "Layout anti-patterns — common mistakes in spacing, composition, and responsive design"
+
+patterns:
+  - name: "Inconsistent spacing values"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for margin/padding values that don't align with the spacing scale defined in tokens.json"
+      context: "Custom pixel values like 13px, 7px, 22px that don't match the 4px/8px grid or token scale"
+    reason: "Arbitrary spacing values create visual noise. Elements that are 'almost aligned' feel more wrong than elements that are clearly different."
+    instead: "Use spacing tokens from the design system scale (e.g., 4, 8, 12, 16, 24, 32, 48, 64). Every spacing value should reference a token."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Content wider than 80ch for reading"
+    severity: warning
+    scope: web
+    detect:
+      method: "Check max-width of text content containers"
+      threshold: "> 80ch or > 720px without max-width constraint"
+      context: "Applies to prose/article content, not dashboards or data tables"
+    reason: "Lines longer than 65-80 characters are hard to track from the end of one line to the beginning of the next. Reading speed and comprehension drop significantly."
+    instead: "Set max-width: 65ch to 75ch for prose content. Use wider layouts only for data-dense views like dashboards and tables."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Fixed pixel widths on containers"
+    severity: warning
+    scope: web
+    detect:
+      css_properties: ["width"]
+      values: ["px values on layout containers"]
+      exclude: ["max-width", "min-width", "icons", "avatars"]
+    reason: "Fixed-width containers break on screen sizes they weren't designed for. A 1200px container is unusable on a 1024px laptop."
+    instead: "Use relative units (%, rem, ch) or max-width constraints. Let containers be fluid within min/max bounds."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Missing touch targets on mobile"
+    severity: error
+    scope: mobile
+    detect:
+      method: "Check interactive element dimensions"
+      threshold: "< 44x44px (iOS) or < 48x48dp (Android)"
+      context: "Buttons, links, toggles, checkboxes, and other tappable elements"
+    reason: "Small touch targets cause mis-taps, frustration, and accessibility failures. WCAG 2.5.8 requires minimum 24x24 CSS pixels, but platform guidelines recommend 44-48px."
+    instead: "Ensure all interactive elements have a minimum tappable area of 44x44px (iOS) or 48x48dp (Android). Use padding to increase hit area without changing visual size."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Horizontal scrolling on mobile"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for content overflow causing horizontal scroll on viewports < 375px"
+      context: "Excludes intentional horizontal scroll components like carousels and code blocks"
+    reason: "Unintended horizontal scroll breaks the vertical reading flow and confuses users. It often indicates a layout bug."
+    instead: "Use overflow-x: hidden on the body, ensure all images have max-width: 100%, and test layouts at 320px minimum viewport width."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Z-index escalation"
+    severity: warning
+    scope: web
+    detect:
+      method: "Check for z-index values"
+      threshold: "> 100 or more than 10 distinct z-index values in the codebase"
+    reason: "Z-index wars create unpredictable stacking. When values escalate to 9999, every new overlay needs 99999, and the system becomes unmaintainable."
+    instead: "Define a z-index scale in tokens (e.g., base: 0, dropdown: 10, sticky: 20, modal: 30, toast: 40, tooltip: 50). Never use arbitrary values."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Nested scroll containers"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for scrollable elements inside other scrollable elements"
+      context: "Especially problematic when both scroll in the same direction"
+    reason: "Nested scrolling creates confusing interaction — users don't know which container will scroll when they swipe. Trackpad momentum makes it worse."
+    instead: "Flatten the layout so only one element scrolls at a time. If nested scroll is unavoidable, ensure they scroll in different directions (e.g., vertical page + horizontal carousel)."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Magic number breakpoints"
+    severity: info
+    scope: web
+    detect:
+      method: "Check for media query breakpoints that don't match standard device widths or design system breakpoints"
+      values: ["arbitrary values like 743px, 1023px, 867px"]
+    reason: "Non-standard breakpoints are hard to reason about and don't correspond to real device classes. They suggest the layout was 'fixed' at a specific size rather than designed responsively."
+    instead: "Use standard breakpoints (640, 768, 1024, 1280, 1536) or define custom breakpoints in the design system tokens and reuse them consistently."
+    strictness:
+      permissive: info
+      standard: info
+      strict: warn

package/dist/agents/skills/shared/design-knowledge/anti-patterns/motion.yaml

@@ -0,0 +1,109 @@
+description: "Motion and animation anti-patterns — common mistakes in transitions, animations, and interactive feedback"
+
+patterns:
+  - name: "Animation without prefers-reduced-motion"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for CSS animations or transitions without a @media (prefers-reduced-motion: reduce) override"
+      context: "Applies to all non-essential animations. Essential animations (progress indicators, loading states) should reduce, not remove."
+    reason: "Motion can trigger vestibular disorders, migraines, and seizures. WCAG 2.3.3 requires respecting user motion preferences."
+    instead: "Wrap animations in a motion-safe media query or provide a prefers-reduced-motion: reduce override that disables or minimizes the animation."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Animations longer than 500ms"
+    severity: warning
+    scope: all
+    detect:
+      css_properties: ["animation-duration", "transition-duration"]
+      threshold: "> 500ms"
+      exclude: ["page transitions", "skeleton loaders", "progress bars"]
+    reason: "Long animations feel sluggish and block user interaction. Users perceive delays over 400ms as 'slow'. Interface animations should feel instant and responsive."
+    instead: "Keep UI transitions between 150-300ms. Use 200ms as the default. Reserve longer durations (300-500ms) for complex multi-element orchestrations."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Linear easing on UI transitions"
+    severity: info
+    scope: all
+    detect:
+      css_properties: ["transition-timing-function", "animation-timing-function"]
+      values: ["linear"]
+      context: "Flagged for UI element transitions, not progress bars or loading animations"
+    reason: "Linear motion feels mechanical and unnatural. Real objects accelerate and decelerate — interfaces should too."
+    instead: "Use ease-out for entrances (elements arriving), ease-in for exits (elements leaving), and ease-in-out for state changes. Default: cubic-bezier(0.4, 0, 0.2, 1)."
+    strictness:
+      permissive: info
+      standard: info
+      strict: warn
+
+  - name: "Auto-playing animation loops"
+    severity: warning
+    scope: all
+    detect:
+      css_properties: ["animation-iteration-count"]
+      values: ["infinite"]
+      context: "Excludes loading spinners and progress indicators that are temporary"
+    reason: "Infinite animation loops are distracting, increase CPU/GPU usage, and can trigger motion sensitivity issues. They compete with content for attention."
+    instead: "Play animations once on entrance, or limit to 3 iterations. If continuous animation is needed, provide a pause control and respect prefers-reduced-motion."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Scroll-jacking"
+    severity: error
+    scope: web
+    detect:
+      method: "Check for JavaScript that overrides native scroll behavior (custom scroll speed, snap-to-section, parallax scroll hijacking)"
+      exclude: ["scroll-snap-type CSS (native)", "smooth-scroll for anchor links"]
+    reason: "Overriding native scroll breaks user expectations, disables accessibility features (keyboard scroll, screen reader navigation), and creates motion sickness. It is the single most complained-about UX pattern."
+    instead: "Use native CSS scroll-snap for section snapping. For parallax, use CSS transform with will-change, not scroll event listeners. Never change scroll speed or direction."
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error
+
+  - name: "Flash or strobe effects"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for elements that flash more than 3 times per second"
+      threshold: "> 3 flashes per second"
+    reason: "Flashing content can cause seizures in people with photosensitive epilepsy. WCAG 2.3.1 requires no more than 3 flashes per second."
+    instead: "Avoid flashing entirely. If attention is needed, use a subtle pulse (opacity 0.8-1.0) at no more than 2 cycles per second."
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error
+
+  - name: "Entrance animations on above-the-fold content"
+    severity: warning
+    scope: web
+    detect:
+      method: "Check for fade-in, slide-in, or scale animations on elements visible in the initial viewport"
+      context: "Hero sections, navigation, primary CTAs"
+    reason: "Animating content that should be immediately visible delays the user's ability to orient and act. It adds perceived load time to an already-loaded page."
+    instead: "Show above-the-fold content immediately. Reserve entrance animations for below-the-fold content revealed on scroll (intersection observer pattern)."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Transition on color-scheme change"
+    severity: info
+    scope: web
+    detect:
+      method: "Check for transitions applied during dark/light mode toggle that affect all elements"
+      context: "Global transition: all on :root or body during theme switch"
+    reason: "Transitioning every element's colors during theme change causes a jarring ripple effect and high paint cost. Individual element transitions compound into visual chaos."
+    instead: "Apply transition only to background-color and color on specific containers (body, main sections), not globally. Or use instant switch with no transition."
+    strictness:
+      permissive: info
+      standard: info
+      strict: info

package/dist/agents/skills/shared/design-knowledge/anti-patterns/typography.yaml

@@ -0,0 +1,112 @@
+description: "Typography anti-patterns — common mistakes that degrade readability, hierarchy, and brand consistency"
+
+patterns:
+  - name: "System font in user-facing UI"
+    severity: warning
+    scope: all
+    detect:
+      css_properties: ["font-family"]
+      values: ["system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif", "serif", "monospace"]
+      context: "Only flagged when used as the sole font-family without a branded font preceding it in the stack"
+    reason: "System fonts vary across platforms, creating inconsistent brand identity. Users on Windows see Segoe UI while macOS users see SF Pro — the product looks different on every device."
+    instead: "Declare a branded font first in the stack with system fonts as fallbacks: `font-family: 'Inter', system-ui, sans-serif`"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "More than 3 font families on a single page"
+    severity: warning
+    scope: all
+    detect:
+      method: "Count distinct font-family values in rendered page"
+      threshold: 3
+    reason: "Multiple typefaces create visual noise and weaken typographic hierarchy. Each additional font competes for attention."
+    instead: "Use a single font family with weight/size variation for hierarchy, or a deliberate display + body pairing (max 2-3 families including monospace)."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Body text below 14px / 0.875rem"
+    severity: error
+    scope: all
+    detect:
+      css_properties: ["font-size"]
+      threshold: "< 14px or < 0.875rem"
+      context: "Applies to body/paragraph text, not labels or captions"
+    reason: "Text below 14px is difficult to read on mobile devices and fails accessibility guidelines for users with low vision."
+    instead: "Use 16px (1rem) as the body text baseline. Use 14px only for secondary labels and metadata."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Line height below 1.4 for body text"
+    severity: warning
+    scope: all
+    detect:
+      css_properties: ["line-height"]
+      threshold: "< 1.4"
+      context: "Applies to body/paragraph text with font-size >= 14px"
+    reason: "Tight line height reduces readability, especially for longer passages. Users with dyslexia or cognitive disabilities are disproportionately affected."
+    instead: "Use line-height 1.5-1.6 for body text. Display headings can use tighter spacing (1.1-1.2)."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "All-caps body text"
+    severity: warning
+    scope: all
+    detect:
+      css_properties: ["text-transform"]
+      values: ["uppercase"]
+      context: "Flagged when applied to paragraphs or text blocks longer than 50 characters"
+    reason: "ALL CAPS reduces reading speed by 10-20% because word shapes become uniform rectangles. Acceptable for short labels and headings, not for body content."
+    instead: "Reserve text-transform: uppercase for buttons, labels, and section headers under 30 characters."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Insufficient heading size contrast"
+    severity: warning
+    scope: all
+    detect:
+      method: "Compare h1-h6 font sizes — flag when adjacent heading levels differ by less than 20%"
+      threshold: "< 1.2x ratio between adjacent levels"
+    reason: "When heading sizes are too similar, the visual hierarchy collapses. Users cannot scan the page structure at a glance."
+    instead: "Use a consistent type scale ratio (1.2 minor third, 1.25 major third, or 1.333 perfect fourth) to ensure clear size differentiation."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Justified text without hyphenation"
+    severity: info
+    scope: web
+    detect:
+      css_properties: ["text-align"]
+      values: ["justify"]
+      absent: ["hyphens: auto"]
+    reason: "Justified text without hyphenation creates uneven word spacing ('rivers of white') that disrupts reading flow, especially in narrow columns."
+    instead: "Use text-align: left for most content. If justified text is required, enable CSS hyphens: auto and ensure column width is at least 45 characters."
+    strictness:
+      permissive: info
+      standard: info
+      strict: warn
+
+  - name: "Font weight below 400 for body text"
+    severity: warning
+    scope: all
+    detect:
+      css_properties: ["font-weight"]
+      threshold: "< 400"
+      context: "Applies to body/paragraph text"
+    reason: "Light and thin font weights (100-300) reduce legibility on low-resolution screens and for users with vision impairments."
+    instead: "Use font-weight 400 (regular) as the minimum for body text. Light weights are acceptable only for large display text (24px+)."
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error

package/dist/agents/skills/shared/design-knowledge/industries/creative.yaml

@@ -0,0 +1,80 @@
+name: "Creative"
+description: "Expressive, editorial design with bold typography, intentional whitespace, and distinctive visual identity"
+
+styles:
+  primary: "Editorial layouts with strong typographic hierarchy and intentional use of whitespace as a design element"
+  secondary: "Portfolio-driven presentation with immersive imagery, grid-breaking layouts, and art-directed content"
+  avoid: ["Generic stock photography that undermines creative credibility", "Template-feeling layouts that contradict the creative message", "Overly uniform grids that feel corporate rather than curated", "Decorative effects without purpose (gratuitous parallax, unnecessary animation)"]
+
+palette:
+  primary:
+    - name: "Charcoal"
+      hex: "#1a1a1a"
+      usage: "Primary text, editorial headlines, strong contrast backgrounds"
+    - name: "Off-Black"
+      hex: "#2d2d2d"
+      usage: "Secondary surfaces, navigation backgrounds, card overlays"
+    - name: "Warm White"
+      hex: "#faf8f5"
+      usage: "Page backgrounds, content surfaces, breathing space"
+  accent:
+    - name: "Coral 500"
+      hex: "#f97066"
+      usage: "Primary accent, CTAs, highlighted portfolio items"
+    - name: "Electric Blue"
+      hex: "#3b82f6"
+      usage: "Links, interactive elements, secondary accent"
+    - name: "Saffron"
+      hex: "#e8a838"
+      usage: "Awards, featured work, premium tier indicators"
+  neutral:
+    - name: "Stone 800"
+      hex: "#292524"
+      usage: "Body text, primary readable content"
+    - name: "Stone 400"
+      hex: "#a8a29e"
+      usage: "Captions, metadata, subtle labels"
+    - name: "Stone 100"
+      hex: "#f5f5f4"
+      usage: "Section dividers, subtle background shifts"
+    - name: "White"
+      hex: "#ffffff"
+      usage: "Image framing, overlay text backgrounds, modal surfaces"
+  semantic:
+    success: "#22c55e"
+    warning: "#f59e0b"
+    error: "#ef4444"
+    info: "#6366f1"
+
+typography:
+  display:
+    families: ["Instrument Serif", "Playfair Display", "Fraunces"]
+    weights: [400, 700, 900]
+    characteristics: "Expressive serif typefaces with distinctive character for headlines. High contrast between thick and thin strokes creates visual drama at large sizes."
+  body:
+    families: ["Inter", "Geist", "DM Sans"]
+    weights: [400, 500]
+    characteristics: "Clean sans-serif paired with serif display creates editorial contrast. Body type should recede, letting display type and imagery lead."
+  mono:
+    families: ["Geist Mono", "Space Mono"]
+    usage: "Code examples in case studies, technical specifications, date stamps on editorial content"
+
+anti_patterns:
+  - pattern: "Using generic stock photography on a creative portfolio or agency site"
+    reason: "Stock imagery directly contradicts the message of original creative work; it signals inauthenticity"
+    instead: "Use original photography, custom illustrations, or carefully art-directed imagery that reflects actual creative capability"
+  - pattern: "Uniform grid layouts for all content types"
+    reason: "Creative sites should demonstrate design range; predictable grids feel template-driven and corporate"
+    instead: "Vary layout rhythm with full-bleed images, asymmetric grids, and intentional whitespace; let content dictate layout"
+  - pattern: "Autoplay background video on every page"
+    reason: "Overuse dilutes impact, increases load time, and creates accessibility issues; it becomes wallpaper rather than storytelling"
+    instead: "Use video intentionally for hero moments or case study intros; provide play controls and poster frames"
+  - pattern: "Cramming every project into the portfolio with equal weight"
+    reason: "Undifferentiated project lists signal lack of editorial judgment; the portfolio itself is a design artifact"
+    instead: "Curate 8-12 best projects with clear hierarchy; feature 2-3 as hero case studies with deeper storytelling"
+  - pattern: "Tiny body text to appear more 'design-forward'"
+    reason: "Sacrificing readability for aesthetics alienates users and fails accessibility standards"
+    instead: "Use generous body text (16px+) and let typographic hierarchy, spacing, and weight create sophistication"
+
+examples:
+  reference_sites: ["pentagram.com", "itsnicethat.com", "awwwards.com", "siteinspire.com", "creativeboom.com"]