devflow-kit 0.8.1 → 1.0.0

package/shared/agents/validator.md

@@ -0,0 +1,86 @@
+---
+name: Validator
+description: Dedicated agent for running validation commands (build, typecheck, lint, test). Reports pass/fail with structured failure details - never fixes.
+model: haiku
+skills: test-patterns
+---
+
+# Validator Agent
+
+You are a validation specialist that runs build and test commands to verify code correctness. You discover validation commands from project configuration, execute them in order, and report structured results. You never fix issues - you only report them for other agents to fix.
+
+## Input Context
+
+You receive from orchestrator:
+- **FILES_CHANGED**: List of modified files
+- **VALIDATION_SCOPE**: `full` | `changed-only` (hints for test filtering if supported)
+
+## Responsibilities
+
+1. **Discover validation commands**: Check package.json scripts, Makefile, Cargo.toml, or similar for available commands
+2. **Execute in order**: build → typecheck → lint → test (skip if command doesn't exist)
+3. **Capture all output**: Record stdout/stderr for each command
+4. **Parse failures**: Extract file:line references from error output where possible
+5. **Report results**: Return structured pass/fail status with failure details
+
+## Validation Order
+
+Execute in this order, stopping on first failure:
+
+| Priority | Command Type | Common Examples |
+|----------|-------------|-----------------|
+| 1 | Build | `npm run build`, `cargo build`, `make build` |
+| 2 | Typecheck | `npm run typecheck`, `tsc --noEmit` |
+| 3 | Lint | `npm run lint`, `cargo clippy`, `make lint` |
+| 4 | Test | `npm test`, `cargo test`, `make test` |
+
+## Principles
+
+1. **Report only** - Never fix code, never commit, never modify files
+2. **Stop on failure** - First failure halts remaining commands
+3. **Parse intelligently** - Extract file:line from error messages when possible
+4. **Respect scope** - Use VALIDATION_SCOPE hint for test filtering if framework supports it
+5. **Fast feedback** - Use haiku model for speed on this simple task
+
+## Output
+
+Return structured validation results:
+
+```markdown
+## Validation Report
+
+### Status: PASS | FAIL | BLOCKED
+
+### Commands Executed
+| Command | Status | Duration |
+|---------|--------|----------|
+| npm run build | PASS | 3.2s |
+| npm run typecheck | FAIL | 1.8s |
+
+### Failures (if FAIL)
+
+#### typecheck
+```
+src/auth/login.ts:42:15 - error TS2339: Property 'email' does not exist on type 'User'.
+src/auth/login.ts:58:3 - error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
+```
+
+**Parsed References:**
+- `src/auth/login.ts:42` - Property 'email' does not exist on type 'User'
+- `src/auth/login.ts:58` - Argument type mismatch (string vs number)
+
+### Blockers (if BLOCKED)
+{Description of why validation couldn't run - e.g., missing dependencies, broken config}
+```
+
+## Boundaries
+
+**Escalate to orchestrator (BLOCKED):**
+- No validation commands found in project
+- Validation command crashes (not test failure, but command itself fails to run)
+- Missing dependencies that prevent any validation
+
+**Handle autonomously:**
+- All command execution and output parsing
+- Determining which commands exist and should run
+- Formatting error output into structured references

package/shared/skills/accessibility/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: accessibility
+description: This skill should be used when the user asks to "add accessibility", "check ARIA", "handle keyboard navigation", "add focus management", or creates UI components, forms, or interactive elements. Provides WCAG 2.1 AA patterns for keyboard navigation, ARIA roles and states, focus management, color contrast, and screen reader support.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.tsx"
+    - "**/*.jsx"
+    - "**/*.css"
+    - "**/*.scss"
+  exclude:
+    - "node_modules/**"
+    - "**/*.test.*"
+    - "**/*.spec.*"
+---
+
+# Accessibility Patterns
+
+Reference for web accessibility (WCAG 2.1 AA compliance), keyboard navigation, screen reader support, and inclusive design.
+
+## Iron Law
+
+> **EVERY INTERACTION MUST BE POSSIBLE WITHOUT A MOUSE**
+>
+> If a user cannot complete an action using only keyboard, the feature is broken.
+> Mouse-only interactions exclude users with motor disabilities, power users,
+> and anyone navigating with assistive technology. Tab order, focus management,
+> and keyboard shortcuts are not optional enhancements.
+
+## When This Skill Activates
+
+- Creating interactive UI components
+- Building forms and inputs
+- Working with React/JSX code
+- Discussing focus, ARIA, or screen readers
+- Reviewing color schemes or contrast
+
+---
+
+## Keyboard Navigation
+
+### Focus Management
+
+```tsx
+// CORRECT: Focus trap in modal
+function Modal({ isOpen, onClose, children }) {
+  const firstFocusable = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (isOpen) firstFocusable.current?.focus();
+  }, [isOpen]);
+
+  return (
+    <div role="dialog" aria-modal="true" onKeyDown={(e) => {
+      if (e.key === 'Escape') onClose();
+    }}>
+      <button ref={firstFocusable}>First action</button>
+      {children}
+    </div>
+  );
+}
+
+// VIOLATION: No focus management, no escape handler
+function BadModal({ children }) {
+  return <div className="modal">{children}</div>;
+}
+```
+
+### Skip Links
+
+```tsx
+// CORRECT: Skip to main content
+<a href="#main-content" className="sr-only focus:not-sr-only">
+  Skip to main content
+</a>
+<main id="main-content" tabIndex={-1}>...</main>
+```
+
+---
+
+## ARIA and Semantic HTML
+
+### Prefer Semantic Elements
+
+```tsx
+// CORRECT: Native semantics
+<button onClick={handleClick}>Submit</button>
+<nav aria-label="Main"><ul>...</ul></nav>
+<article><header>...</header></article>
+
+// VIOLATION: Div with role instead of semantic element
+<div role="button" onClick={handleClick}>Submit</div>
+<div role="navigation">...</div>
+```
+
+### Live Regions
+
+```tsx
+// CORRECT: Announce dynamic changes
+<div aria-live="polite" aria-atomic="true">
+  {message && <p>{message}</p>}
+</div>
+
+// For errors (assertive)
+<div role="alert">{errorMessage}</div>
+```
+
+---
+
+## Color and Contrast
+
+| Element | Minimum Ratio | WCAG Level |
+|---------|--------------|------------|
+| Normal text (<18px) | 4.5:1 | AA |
+| Large text (>=18px bold, >=24px) | 3:1 | AA |
+| UI components | 3:1 | AA |
+| Enhanced | 7:1 | AAA |
+
+### Never Color-Only Meaning
+
+```tsx
+// VIOLATION: Only color indicates error
+<input style={{ borderColor: hasError ? 'red' : 'gray' }} />
+
+// CORRECT: Icon + text + color
+<input aria-invalid={hasError} aria-describedby="error-msg" />
+{hasError && <span id="error-msg" role="alert">Required field</span>}
+```
+
+---
+
+## Motion and Animation
+
+```tsx
+// CORRECT: Respect user preferences
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+<div className={prefersReduced ? 'no-animation' : 'animate-fade'}>
+  Content
+</div>
+
+// CSS approach
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+---
+
+## Touch and Pointer
+
+### Minimum Target Size
+
+```css
+/* CORRECT: 44x44px minimum touch target */
+.button {
+  min-width: 44px;
+  min-height: 44px;
+  padding: 12px 16px;
+}
+
+/* VIOLATION: Tiny tap targets */
+.icon-button {
+  width: 20px;
+  height: 20px;
+}
+```
+
+---
+
+## Forms and Errors
+
+```tsx
+// CORRECT: Associated labels and error linking
+<div>
+  <label htmlFor="email">Email</label>
+  <input
+    id="email"
+    type="email"
+    aria-invalid={!!error}
+    aria-describedby={error ? 'email-error' : undefined}
+  />
+  {error && <span id="email-error" role="alert">{error}</span>}
+</div>
+
+// VIOLATION: Placeholder as label
+<input placeholder="Enter email" />
+```
+
+---
+
+## Extended References
+
+For additional patterns and detection rules:
+- `references/violations.md` - Extended accessibility violations
+- `references/patterns.md` - Extended correct patterns
+- `references/detection.md` - Grep patterns for finding issues
+
+---
+
+## Severity Guidelines
+
+| Severity | Criteria |
+|----------|----------|
+| CRITICAL | No keyboard access, missing form labels, zero contrast |
+| HIGH | Missing focus indicators, no skip links, color-only meaning |
+| MEDIUM | Missing ARIA labels, poor focus order, small touch targets |
+| LOW | Missing optional enhancements, could improve announcements |
+
+---
+
+## Checklist
+
+- [ ] All interactive elements reachable via Tab
+- [ ] Visible focus indicators on all focusable elements
+- [ ] Escape closes modals/dropdowns
+- [ ] Skip link to main content
+- [ ] All form inputs have associated labels
+- [ ] Errors linked via aria-describedby
+- [ ] Color contrast meets 4.5:1 (text) / 3:1 (UI)
+- [ ] No color-only meaning
+- [ ] prefers-reduced-motion respected
+- [ ] Touch targets minimum 44x44px
+- [ ] aria-live for dynamic content
+- [ ] Semantic HTML preferred over ARIA roles

package/shared/skills/accessibility/references/detection.md

@@ -0,0 +1,171 @@
+# Accessibility Detection Patterns
+
+Grep and regex patterns for detecting accessibility issues. Use with `Grep` tool.
+
+## Keyboard Access Issues
+
+```bash
+# onClick without keyboard handler
+rg 'onClick=\{[^}]+\}' --type tsx | rg -v 'onKeyDown|onKeyPress|onKeyUp|<button|<a '
+
+# Non-focusable interactive elements
+rg '<(div|span)\s+[^>]*onClick' --type tsx
+
+# tabIndex with positive values (breaks natural order)
+rg 'tabIndex=\{?[1-9]' --type tsx
+
+# Drag-only interactions
+rg 'onDrag(Start|End|Over)' --type tsx | rg -v 'onKey'
+```
+
+## Missing Labels
+
+```bash
+# Input without id (likely missing label association)
+rg '<input[^>]*>' --type tsx | rg -v 'id='
+
+# Button with only icon (no text or aria-label)
+rg '<button[^>]*>\s*<[A-Z][a-zA-Z]*Icon' --type tsx | rg -v 'aria-label'
+
+# Image without alt
+rg '<img[^>]*>' --type tsx | rg -v 'alt='
+
+# Links without text content
+rg '<a[^>]*>\s*<(img|[A-Z])' --type tsx | rg -v 'aria-label'
+```
+
+## ARIA Misuse
+
+```bash
+# Redundant role on semantic elements
+rg '<button[^>]*role="button"' --type tsx
+rg '<nav[^>]*role="navigation"' --type tsx
+rg '<a[^>]*role="link"' --type tsx
+
+# aria-hidden on focusable elements
+rg 'aria-hidden="true"[^>]*(tabIndex|onClick|href)' --type tsx
+
+# Missing required ARIA attributes
+rg 'role="slider"' --type tsx | rg -v 'aria-value(now|min|max)'
+rg 'role="checkbox"' --type tsx | rg -v 'aria-checked'
+rg 'role="tab"' --type tsx | rg -v 'aria-selected'
+```
+
+## Focus Management Issues
+
+```bash
+# Focus removal (outline: none without replacement)
+rg 'outline:\s*none' --type css --type scss | rg -v 'focus-visible|focus-ring'
+
+# Dialogs without role or aria-modal
+rg 'modal|dialog' --type tsx -i | rg -v 'role="dialog"|aria-modal'
+
+# Missing escape key handler in modals
+rg '(Modal|Dialog|Popup)' --type tsx | rg -v 'Escape|onKeyDown'
+```
+
+## Color and Contrast
+
+```bash
+# Light gray text (potential contrast issue)
+rg 'color:\s*#[a-fA-F0-9]{3,6}' --type css | rg -i '(#[cdef]{3}|#[cdef]{6})'
+
+# Color-only indicators
+rg 'color.*error|color.*success|color.*warning' --type css -i
+
+# Placeholder as only label indicator
+rg '<input[^>]*placeholder=' --type tsx | rg -v '<label|aria-label'
+```
+
+## Form Issues
+
+```bash
+# Missing error association
+rg 'aria-invalid' --type tsx | rg -v 'aria-describedby'
+
+# Form without noValidate (may conflict with custom validation)
+rg '<form[^>]*>' --type tsx | rg 'onSubmit' | rg -v 'noValidate'
+
+# Submit button without type
+rg '<button[^>]*>Submit' --type tsx | rg -v 'type="submit"'
+```
+
+## Motion Issues
+
+```bash
+# Animation without reduced motion check
+rg 'animation(-duration)?:' --type css | rg -v 'prefers-reduced-motion'
+
+# Transition without reduced motion check
+rg 'transition(-duration)?:' --type css | rg -v 'prefers-reduced-motion'
+
+# Autoplay video/audio
+rg '<(video|audio)[^>]*autoPlay' --type tsx
+
+# Infinite animation loops
+rg 'animation:.*infinite' --type css
+```
+
+## Touch Target Issues
+
+```bash
+# Small fixed dimensions
+rg '(width|height):\s*(1[0-9]|2[0-9]|3[0-9])px' --type css
+
+# Icon buttons without adequate sizing
+rg '\.icon(-btn|Button)' --type css -A5 | rg '(width|height)'
+```
+
+## Screen Reader Issues
+
+```bash
+# Generic link text
+rg '>click here<|>here<|>read more<|>learn more<' --type tsx -i
+
+# aria-label duplicating visible text
+rg 'aria-label="([^"]+)"[^>]*>\1<' --type tsx
+
+# Missing landmark regions
+rg '<div[^>]*class="(header|footer|nav|sidebar|main)"' --type tsx | rg -v 'role='
+```
+
+## Live Region Issues
+
+```bash
+# Dynamic content without aria-live
+rg '(loading|spinner|toast|notification|alert)' --type tsx -i | rg -v 'aria-live|role="alert"|role="status"'
+
+# Missing aria-atomic on live regions
+rg 'aria-live=' --type tsx | rg -v 'aria-atomic'
+```
+
+## Semantic HTML Issues
+
+```bash
+# Div/span used instead of semantic elements
+rg '<div[^>]*role="(button|link|navigation|main|banner|contentinfo)"' --type tsx
+rg '<span[^>]*role="(button|link)"' --type tsx
+
+# Heading level skips (partial detection)
+rg '<h[1-6]' --type tsx
+
+# List items outside lists
+rg '<li[^>]*>' --type tsx | rg -v '<ul|<ol'
+```
+
+## Testing Commands
+
+```bash
+# Full accessibility audit on changed files
+git diff --name-only HEAD~1 | xargs -I{} rg -l 'onClick|<input|<button|<a ' {} 2>/dev/null
+
+# Count potential issues by category
+echo "=== Potential Keyboard Issues ==="
+rg '<(div|span)\s+[^>]*onClick' --type tsx -c
+
+echo "=== Potential Label Issues ==="
+rg '<input[^>]*>' --type tsx | rg -v 'id=' | wc -l
+
+echo "=== Potential ARIA Issues ==="
+rg '<button[^>]*role="button"' --type tsx -c
+```