hatch3r 1.0.0

package/rules/hatch3r-testing.mdc

@@ -0,0 +1,87 @@
+---
+description: Test standards and conventions for the project
+alwaysApply: true
+---
+# Testing Standards
+
+## Core Principles
+
+- Unit tests: project test runner. Integration: test runner + emulators/mocks. E2E: browser automation (Playwright or equivalent).
+- **Deterministic.** Mock time where needed. No wall clock dependency.
+- **Isolated.** Each test sets up and tears down its own state.
+- **Fast.** Unit tests < 50ms. Integration tests < 2s.
+- **Named clearly.** Describe behavior: `"should award 15 XP for 25-min focus block"`.
+- **Regression.** Every bug fix includes a test that fails before the fix and passes after.
+- **No network.** Unit tests must not make network calls. Use mocks.
+- No `any` types in tests. No `.skip` without a linked issue.
+- Write tests to `tests/unit/`, `tests/integration/`, `tests/e2e/`, or equivalent.
+- Use test fixtures from `tests/fixtures/` or equivalent.
+- **Browser verification.** For UI changes, verify visually in the browser via browser automation MCP after automated tests pass. Capture screenshots as evidence.
+
+## Coverage Thresholds
+
+- **Statement coverage:** 80% minimum across the project. New code must not decrease overall coverage.
+- **Branch coverage:** 70% minimum. Uncovered branches must be justified (e.g., defensive error handling unlikely to trigger).
+- **Function coverage:** 80% minimum. Every exported function must have at least one test.
+- **Per-PR gate:** CI blocks merge if the PR decreases coverage by more than 1% in any metric.
+- **Critical modules** (auth, payments, data persistence, security rules): 90% statement, 85% branch minimum.
+- Generate coverage reports in CI and publish as PR comments or artifacts for visibility.
+- Exclude generated code, type declarations, and config files from coverage metrics.
+
+## Mocking Strategy
+
+- **Prefer fakes over mocks** for stateful dependencies (databases, caches). Fakes implement the real interface with in-memory state, making tests more realistic.
+- **Use stubs** for simple value returns where behavior is irrelevant to the test (e.g., config lookups, feature flags).
+- **Use mocks** (with call verification) only when the interaction itself is the behavior under test (e.g., verifying an event was emitted, an API was called with specific arguments).
+- **Mock boundaries, not internals.** Mock at module/service boundaries (HTTP clients, database drivers, external SDKs). Never mock private functions or internal implementation details.
+- **Reset mocks between tests.** Use `beforeEach` / `afterEach` to restore original implementations. Leaked mock state is a top source of flaky tests.
+- **Type-safe mocks.** Mock implementations must satisfy the same TypeScript interface as the real dependency. Avoid `as any` in mock setup.
+- **No mocking the unit under test.** If you need to mock part of the module you are testing, the module has too many responsibilities — refactor first.
+
+## Property-Based Testing
+
+- Use a property-based testing library (fast-check or equivalent) for functions with wide input domains.
+- **Priority targets:** parsers, serializers, validators, encoders/decoders, mathematical functions, and any pure function with complex input types.
+- Define invariants as properties: round-trip (encode then decode equals original), idempotency (applying twice equals applying once), monotonicity, commutativity.
+- Use `fc.assert` with at least 100 runs per property. Increase to 1000 for critical paths.
+- When a property test finds a failure, add the minimal counterexample as a dedicated regression unit test.
+- Shrinking must be enabled — it reduces failing inputs to the smallest reproduction case.
+- Property tests belong alongside unit tests in `tests/unit/`. Name them clearly: `"property: round-trip serialization for UserProfile"`.
+
+## Mutation Testing
+
+- Use Stryker (or equivalent mutation testing framework) on critical modules to measure test effectiveness beyond line coverage.
+- **Mutation score target:** 70% minimum on critical modules (auth, data layer, business rules). 60% minimum project-wide.
+- Run mutation testing in CI on a weekly schedule (not per-PR — too slow). Report results as a CI artifact.
+- **Surviving mutants** indicate tests that pass regardless of code changes — these are false-coverage tests. Fix them by adding assertions that detect the mutation.
+- Focus mutation testing effort on modules where a bug would cause data loss, security vulnerability, or financial impact.
+- Exclude test files, generated code, and UI presentation logic from mutation analysis.
+
+## Flaky Test Handling
+
+- **Zero tolerance policy.** A flaky test erodes trust in the entire suite. Fix or quarantine within 48 hours of detection.
+- **Quarantine process:** Move the flaky test to a `tests/quarantine/` directory or tag with `.skip("FLAKY: #issue-number")`. Create a tracking issue immediately.
+- **Retry strategy in CI:** Allow a maximum of 1 automatic retry for the full test suite. Never retry individual tests silently — that masks flakiness.
+- **Root cause investigation:** Common causes are shared mutable state, timing dependencies (real clocks, `setTimeout`), port conflicts, uncontrolled randomness, and external service calls.
+- **Fix patterns:** Replace `setTimeout` with fake timers, replace shared state with per-test setup, replace port binding with dynamic ports, seed random generators deterministically.
+- **Flaky test metrics:** Track flaky test rate over time. Target < 0.5% flaky rate (flaky runs / total runs). Alert when rate exceeds 1%.
+- **Quarantine review:** Review quarantined tests weekly. Tests quarantined for more than 30 days must be either fixed or deleted with justification.
+
+## Test Data Management
+
+- **Factories over fixtures.** Use factory functions (builder pattern) to generate test data with sensible defaults and per-test overrides. Factories produce valid objects by default; tests override only the fields relevant to the scenario.
+- **Builder pattern example:** `buildUser({ role: "admin" })` returns a full valid User with admin role and random but valid defaults for all other fields.
+- **No shared mutable fixtures.** If multiple tests read the same fixture data, each test must get its own copy. Use `structuredClone()` or factory functions.
+- **Realistic data.** Use faker or equivalent for generating realistic names, emails, dates. Avoid magic strings like `"test"`, `"foo"`, `"abc123"`.
+- **Deterministic seeding.** When using random data generators, seed them per test file so failures are reproducible.
+- **Fixture files** (JSON, YAML) are acceptable for large, complex, or externally-sourced test inputs (API response snapshots, configuration samples). Store in `tests/fixtures/`.
+- **Database state:** Integration tests that require database state must set up and tear down within the test using helpers. Never depend on database state from a previous test.
+
+## Snapshot Testing
+
+- **Use sparingly.** Snapshots are appropriate for serialized output (JSON API responses, CLI output, rendered HTML structure) where the exact output matters and is stable.
+- **Not appropriate for:** UI component visual appearance (use visual regression tests), objects with timestamps or random IDs (unstable), large objects (unreadable diffs).
+- **Review discipline.** Snapshot updates (`--update-snapshots`) must be reviewed as carefully as code changes. Reviewers must verify the new snapshot is intentionally correct, not just "different."
+- **Keep snapshots small.** Snapshot files > 100 lines suggest the test is asserting too broadly. Narrow the assertion to the relevant subset.
+- **Inline snapshots** (where supported) are preferred over external `.snap` files for short outputs (< 20 lines) because they keep the assertion co-located with the test.
+- **Name snapshot files** to match their test file: `auth.test.ts` → `auth.test.ts.snap`.

package/rules/hatch3r-theming.md

@@ -0,0 +1,51 @@
+---
+description: Theming, dark mode, and color system conventions for the project
+globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.css, src/**/*.scss
+alwaysApply: false
+---
+# Theming & Dark Mode
+
+## Color System
+
+- Define all colors as semantic CSS custom properties (`--color-surface`, `--color-text-primary`, `--color-text-secondary`, `--color-border`, `--color-brand`, `--color-error`, `--color-success`, `--color-warning`).
+- Maintain three token sets: **light** (default), **dark**, and **high-contrast**.
+- Never use raw hex, `rgb()`, or `hsl()` values in component code — always reference tokens.
+- Layer tokens: primitive (`--gray-900`) → semantic (`--color-text-primary: var(--gray-900)`) → component (`--btn-text: var(--color-text-primary)`).
+
+## Theme Detection & Persistence
+
+- Detect system preference with `prefers-color-scheme` media query for CSS defaults.
+- Read system preference in JS via `window.matchMedia('(prefers-color-scheme: dark)')` and listen for changes with `addEventListener('change', ...)`.
+- Persist explicit user override in `localStorage` (or equivalent settings store).
+- Resolution order: user override → system preference → light fallback.
+
+## Theme Switching
+
+- Apply theme via `data-theme` attribute on `<html>` (e.g., `<html data-theme="dark">`).
+- Define token overrides scoped to `[data-theme="dark"]` and `[data-theme="high-contrast"]` selectors.
+- Add `color-scheme: light dark` on `:root` so browser-native controls (scrollbars, form elements) adapt automatically.
+- Prevent flash of wrong theme (FOWT): inject a blocking `<script>` in `<head>` that reads the stored preference and sets `data-theme` before first paint.
+- Use `transition: background-color 200ms ease, color 200ms ease` on body for smooth theme changes — but disable transitions on initial load.
+
+## Dark Mode Patterns
+
+- Reduce color saturation 10–20% for dark backgrounds to avoid visual vibration.
+- Express elevation through progressively lighter surface colors (e.g., `--color-surface-raised`, `--color-surface-overlay`) — not box-shadows.
+- Adjust images: apply `filter: brightness(0.9)` or reduce opacity on decorative images; provide dark-optimized variants for logos and illustrations when possible.
+- Use reduced contrast (e.g., `--color-text-secondary: #a0a0a0`) for secondary text in dark mode — primary text should remain high contrast (≥ 7:1).
+- Avoid pure white (`#fff`) text on pure black (`#000`) backgrounds — use off-white on dark gray for reduced eye strain.
+
+## High Contrast Support
+
+- Provide a `high-contrast` token set with ≥ 7:1 contrast ratios for all text and ≥ 3:1 for non-text UI.
+- Detect user preference with `@media (prefers-contrast: more)` and apply high-contrast tokens.
+- Support `forced-colors` mode: use system color keywords (`Canvas`, `CanvasText`, `LinkText`, `ButtonFace`, `ButtonText`) and test that information is not conveyed by color alone.
+- Ensure focus indicators and borders remain visible under forced-colors by using `Highlight` / `SelectedItem` keywords.
+
+## Testing
+
+- Verify theme toggle switches all tokens correctly — no unstyled or hard-coded colors leak through.
+- Validate contrast ratios per theme using automated tools (axe-core, Lighthouse) against WCAG AA (4.5:1 text, 3:1 non-text).
+- Capture screenshots across light, dark, and high-contrast themes at key viewport sizes for visual regression comparison.
+- Test `prefers-color-scheme` and `prefers-contrast` media query overrides using browser DevTools emulation or Playwright `emulateMedia`.
+- Confirm no flash of wrong theme on hard refresh (disable cache, reload, verify first paint matches stored preference).

package/rules/hatch3r-theming.mdc

@@ -0,0 +1,51 @@
+---
+description: Theming, dark mode, and color system conventions for the project
+globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.css, src/**/*.scss
+alwaysApply: false
+---
+# Theming & Dark Mode
+
+## Color System
+
+- Define all colors as semantic CSS custom properties (`--color-surface`, `--color-text-primary`, `--color-text-secondary`, `--color-border`, `--color-brand`, `--color-error`, `--color-success`, `--color-warning`).
+- Maintain three token sets: **light** (default), **dark**, and **high-contrast**.
+- Never use raw hex, `rgb()`, or `hsl()` values in component code — always reference tokens.
+- Layer tokens: primitive (`--gray-900`) → semantic (`--color-text-primary: var(--gray-900)`) → component (`--btn-text: var(--color-text-primary)`).
+
+## Theme Detection & Persistence
+
+- Detect system preference with `prefers-color-scheme` media query for CSS defaults.
+- Read system preference in JS via `window.matchMedia('(prefers-color-scheme: dark)')` and listen for changes with `addEventListener('change', ...)`.
+- Persist explicit user override in `localStorage` (or equivalent settings store).
+- Resolution order: user override → system preference → light fallback.
+
+## Theme Switching
+
+- Apply theme via `data-theme` attribute on `<html>` (e.g., `<html data-theme="dark">`).
+- Define token overrides scoped to `[data-theme="dark"]` and `[data-theme="high-contrast"]` selectors.
+- Add `color-scheme: light dark` on `:root` so browser-native controls (scrollbars, form elements) adapt automatically.
+- Prevent flash of wrong theme (FOWT): inject a blocking `<script>` in `<head>` that reads the stored preference and sets `data-theme` before first paint.
+- Use `transition: background-color 200ms ease, color 200ms ease` on body for smooth theme changes — but disable transitions on initial load.
+
+## Dark Mode Patterns
+
+- Reduce color saturation 10–20% for dark backgrounds to avoid visual vibration.
+- Express elevation through progressively lighter surface colors (e.g., `--color-surface-raised`, `--color-surface-overlay`) — not box-shadows.
+- Adjust images: apply `filter: brightness(0.9)` or reduce opacity on decorative images; provide dark-optimized variants for logos and illustrations when possible.
+- Use reduced contrast (e.g., `--color-text-secondary: #a0a0a0`) for secondary text in dark mode — primary text should remain high contrast (≥ 7:1).
+- Avoid pure white (`#fff`) text on pure black (`#000`) backgrounds — use off-white on dark gray for reduced eye strain.
+
+## High Contrast Support
+
+- Provide a `high-contrast` token set with ≥ 7:1 contrast ratios for all text and ≥ 3:1 for non-text UI.
+- Detect user preference with `@media (prefers-contrast: more)` and apply high-contrast tokens.
+- Support `forced-colors` mode: use system color keywords (`Canvas`, `CanvasText`, `LinkText`, `ButtonFace`, `ButtonText`) and test that information is not conveyed by color alone.
+- Ensure focus indicators and borders remain visible under forced-colors by using `Highlight` / `SelectedItem` keywords.
+
+## Testing
+
+- Verify theme toggle switches all tokens correctly — no unstyled or hard-coded colors leak through.
+- Validate contrast ratios per theme using automated tools (axe-core, Lighthouse) against WCAG AA (4.5:1 text, 3:1 non-text).
+- Capture screenshots across light, dark, and high-contrast themes at key viewport sizes for visual regression comparison.
+- Test `prefers-color-scheme` and `prefers-contrast` media query overrides using browser DevTools emulation or Playwright `emulateMedia`.
+- Confirm no flash of wrong theme on hard refresh (disable cache, reload, verify first paint matches stored preference).

package/rules/hatch3r-tooling-hierarchy.md

@@ -0,0 +1,92 @@
+---
+id: hatch3r-tooling-hierarchy
+type: rule
+description: Priority order for tools and knowledge sources
+scope: always
+---
+# Tooling Hierarchy
+
+## A. GitHub CLI-First
+
+**Prefer `gh` CLI over GitHub MCP tools** for GitHub operations. CLI tools are optimized for agent use — lower token cost, faster execution, and deterministic output parsing.
+
+**Prerequisites:** `gh auth login` must be completed, or `GITHUB_TOKEN` environment variable set. For Projects v2: `gh auth refresh -s project`.
+
+**Primary tool for:**
+- Issue CRUD: `gh issue create`, `gh issue edit`, `gh issue view`, `gh issue list`
+- PR CRUD: `gh pr create`, `gh pr view`, `gh pr list`, `gh pr merge`
+- Search: `gh search issues`, `gh search prs`, `gh search code`
+- Labels: `gh label create`, `gh label list`
+- Releases: `gh release create`
+- CI/Actions: `gh run list`, `gh run view`, `gh run watch`
+- Projects v2: `gh project item-add`, `gh project item-edit`, `gh project item-list`, `gh project field-list`, `gh project view`
+
+**Fallback to GitHub MCP only when:**
+- The `gh` CLI lacks the specific capability (e.g., sub-issue management via `sub_issue_write`).
+- GraphQL queries are needed that `gh api graphql` cannot express concisely.
+
+**Never** use GitHub MCP for operations that `gh` CLI handles well (issue CRUD, PR CRUD, search, labels, releases).
+
+## B. Documentation MCP for Library Documentation
+
+Use documentation MCP (e.g., Context7) to retrieve up-to-date, version-specific documentation for external libraries and frameworks. This prevents hallucinated APIs and outdated patterns.
+
+**When to use:**
+- Working with any external dependency.
+- Verifying API signatures, configuration options, or migration paths.
+- Reviewing code that uses third-party libraries.
+- Writing tests with external test frameworks.
+- Debugging errors from external libraries.
+
+**When NOT to use:**
+- Internal project specs — use project docs.
+- Internal codebase patterns — use Grep, SemanticSearch, or exploration tools.
+- General programming concepts not tied to a specific library.
+
+## C. Web Research for External Context
+
+Use web search to retrieve current, real-world information not available in project docs or library documentation.
+
+**When to use:**
+- Latest security advisories, CVEs, or vulnerability disclosures for dependencies.
+- Breaking changes or deprecations in upcoming dependency versions.
+- Current best practices for architecture patterns, deployment strategies, or tooling.
+- Novel problems with no match in docs (e.g., obscure error messages, platform-specific quirks).
+- Comparing alternative approaches or tools with current community consensus.
+
+**When NOT to use:**
+- Questions answerable from project specs or codebase exploration.
+- Standard library API questions (use documentation MCP instead).
+- Internal project decisions (use project ADRs).
+
+## D. Browser Verification for UI Changes
+
+Use browser automation MCP tools to visually verify UI changes after automated tests pass.
+
+**When to use:**
+- Verifying UI component changes render correctly.
+- Reproducing and confirming fixes for visually observable bugs.
+- Accessibility auditing (keyboard nav, contrast, focus indicators).
+- Frontend performance profiling (CPU, frame rate, memory).
+- Capturing screenshot evidence for PRs.
+
+**When NOT to use:**
+- Pure backend or API changes with no visual impact.
+- Configuration or infrastructure changes.
+- Code refactors that do not alter rendered output.
+
+**Available tools:**
+- IDE-native browser MCP (e.g., `cursor-ide-browser` in Cursor).
+- Playwright MCP (`@anthropic/mcp-playwright`) for cross-editor browser automation.
+
+## E. Knowledge Augmentation Priority
+
+When seeking information, follow this priority order:
+
+1. **Project specs and ADRs** — authoritative for project-specific behavior, constraints, and decisions.
+2. **Codebase exploration** (code search tools, semantic code search) — ground truth for current implementation.
+3. **Documentation MCP** — authoritative for external library/framework APIs and patterns.
+4. **Web research** — current events, best practices, security advisories, novel problems.
+5. **Browser verification** — visual confirmation of UI changes after automated tests pass.
+
+Combine sources when valuable: read the spec first, then verify external API usage with docs MCP, then check for recent advisories via web research.

package/rules/hatch3r-tooling-hierarchy.mdc

@@ -0,0 +1,79 @@
+---
+description: Priority order for tools and knowledge sources
+alwaysApply: true
+---
+# Tooling Hierarchy
+
+## A. GitHub MCP-First (when available)
+
+**Prefer GitHub MCP tools over `gh` CLI** when the MCP server provides typed tools with structured input/output. Use them as the primary interface for GitHub operations.
+
+**Fallback to `gh` CLI only when:**
+- The MCP tool catalog lacks the specific capability.
+- An MCP call fails repeatedly and the CLI provides a viable alternative.
+
+**Never** use `gh` CLI for operations that have a direct MCP equivalent (issue CRUD, PR CRUD, search, labels).
+
+## B. Documentation MCP for Library Documentation
+
+Use documentation MCP (e.g., Context7) to retrieve up-to-date, version-specific documentation for external libraries and frameworks. This prevents hallucinated APIs and outdated patterns.
+
+**When to use:**
+- Working with any external dependency.
+- Verifying API signatures, configuration options, or migration paths.
+- Reviewing code that uses third-party libraries.
+- Writing tests with external test frameworks.
+- Debugging errors from external libraries.
+
+**When NOT to use:**
+- Internal project specs — use project docs.
+- Internal codebase patterns — use Grep, SemanticSearch, or exploration tools.
+- General programming concepts not tied to a specific library.
+
+## C. Web Research for External Context
+
+Use web search to retrieve current, real-world information not available in project docs or library documentation.
+
+**When to use:**
+- Latest security advisories, CVEs, or vulnerability disclosures for dependencies.
+- Breaking changes or deprecations in upcoming dependency versions.
+- Current best practices for architecture patterns, deployment strategies, or tooling.
+- Novel problems with no match in docs (e.g., obscure error messages, platform-specific quirks).
+- Comparing alternative approaches or tools with current community consensus.
+
+**When NOT to use:**
+- Questions answerable from project specs or codebase exploration.
+- Standard library API questions (use documentation MCP instead).
+- Internal project decisions (use project ADRs).
+
+## D. Browser Verification for UI Changes
+
+Use browser automation MCP tools to visually verify UI changes after automated tests pass.
+
+**When to use:**
+- Verifying UI component changes render correctly.
+- Reproducing and confirming fixes for visually observable bugs.
+- Accessibility auditing (keyboard nav, contrast, focus indicators).
+- Frontend performance profiling (CPU, frame rate, memory).
+- Capturing screenshot evidence for PRs.
+
+**When NOT to use:**
+- Pure backend or API changes with no visual impact.
+- Configuration or infrastructure changes.
+- Code refactors that do not alter rendered output.
+
+**Available tools:**
+- IDE-native browser MCP (e.g., `cursor-ide-browser` in Cursor).
+- Playwright MCP (`@anthropic/mcp-playwright`) for cross-editor browser automation.
+
+## E. Knowledge Augmentation Priority
+
+When seeking information, follow this priority order:
+
+1. **Project specs and ADRs** — authoritative for project-specific behavior, constraints, and decisions.
+2. **Codebase exploration** (Grep, SemanticSearch) — ground truth for current implementation.
+3. **Documentation MCP** — authoritative for external library/framework APIs and patterns.
+4. **Web research** — current events, best practices, security advisories, novel problems.
+5. **Browser verification** — visual confirmation of UI changes after automated tests pass.
+
+Combine sources when valuable: read the spec first, then verify external API usage with docs MCP, then check for recent advisories via web research.

package/skills/hatch3r-a11y-audit/SKILL.md

@@ -0,0 +1,131 @@
+---
+id: hatch3r-a11y-audit
+description: Comprehensive WCAG AA accessibility audit with findings and fixes. Use when auditing accessibility, verifying WCAG compliance, or improving a11y across the application.
+---
+# Accessibility Audit Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Read accessibility requirements from rules and specs
+- [ ] Step 2: Automated scan — run axe-core or similar on all pages/components
+- [ ] Step 3: Manual audit — keyboard, contrast, ARIA, reduced motion, screen reader
+- [ ] Step 4: Catalog findings by severity (critical/major/minor)
+- [ ] Step 5: Fix critical and major findings
+- [ ] Step 6: Verify fixes with re-scan and manual check
+```
+
+## Step 1: Read Accessibility Requirements
+
+**From project component rules (Accessibility section):**
+
+- All animations: wrap in `prefers-reduced-motion` media query AND check user's reduced motion setting.
+- Color contrast: ≥ 4.5:1 for text (WCAG AA).
+- Interactive elements: keyboard focusable with visible focus indicator.
+- Dynamic content changes: use `aria-live` regions.
+- Support high contrast mode.
+
+**From project quality documentation:**
+
+| Requirement         | Standard | Details                                                          |
+| ------------------- | -------- | ---------------------------------------------------------------- |
+| Reduced motion      | WCAG 2.1 | All animations respect `prefers-reduced-motion` and user setting |
+| Color contrast      | WCAG AA  | Text contrast ratio ≥ 4.5:1                                      |
+| Keyboard navigation | WCAG 2.1 | All interactive elements focusable and operable via keyboard     |
+| Screen reader       | WCAG 2.1 | Dynamic state and reactions announced via ARIA live regions      |
+| High contrast mode  | Custom   | User-configurable high contrast theme (if applicable)            |
+
+- For external library docs and current best practices, follow the project's tooling hierarchy.
+
+## Step 2: Automated Scan
+
+- Install and run `@axe-core/vue`, `vitest-axe`, or Playwright's `@axe-core/playwright` on all pages and key components.
+- Run against: main routes, key components (if testable in isolation).
+- Capture all violations. Map to WCAG criteria (e.g., 1.1.1, 1.4.3, 2.1.1, 4.1.2).
+- Document: rule ID, description, impact, elements affected, WCAG level.
+
+## Step 3: Manual Audit
+
+**Keyboard navigation:**
+
+- Tab through all interactive elements. Ensure logical order, no focus traps.
+- All buttons, links, inputs, custom controls focusable.
+- Visible focus indicator (outline or ring) — no `outline: none` without replacement.
+- Escape closes modals/dropdowns. Enter/Space activates buttons.
+
+**Color contrast:**
+
+- Check text vs background: ≥ 4.5:1 for normal text, ≥ 3:1 for large text.
+- Use DevTools or contrast checker. Test with design tokens — ensure no ad-hoc colors fail.
+
+**ARIA attributes:**
+
+- `aria-label` or `aria-labelledby` for icon-only buttons, custom controls.
+- `aria-live="polite"` or `aria-live="assertive"` for dynamic state changes, notifications.
+- `role` correct for custom widgets (button, link, tab, etc.).
+- `aria-expanded`, `aria-selected`, `aria-hidden` where appropriate.
+
+**Reduced motion:**
+
+- Test with `prefers-reduced-motion: reduce` (DevTools → Rendering → Emulate CSS media).
+- Verify animations are disabled or simplified. Check user's reduced motion setting.
+- No motion-dependent information (per WCAG 2.1).
+
+**Screen reader:**
+
+- Test with NVDA, VoiceOver, or similar. Verify announcements for dynamic content.
+- Dynamic state, errors, and success messages announced.
+- Form labels associated, error messages linked via `aria-describedby` or `aria-errormessage`.
+
+**High contrast mode:**
+
+- Verify user-configurable high contrast theme works (if applicable). No loss of information.
+
+## Step 4: Catalog Findings
+
+| Severity | Definition                              | Examples                                                      |
+| -------- | --------------------------------------- | ------------------------------------------------------------- |
+| Critical | Blocks core functionality, fails WCAG A | Missing form labels, no keyboard access to primary actions    |
+| Major    | Significant barrier, fails WCAG AA      | Contrast < 4.5:1, missing focus indicators, no reduced motion |
+| Minor    | Improves experience, best practice       | Redundant labels, suboptimal heading order                    |
+
+- Produce a findings table: ID, severity, WCAG criterion, description, location, fix suggestion.
+- Prioritize: critical first, then major. Minor can be batched.
+
+## Step 5: Fix Critical and Major Findings
+
+- Implement fixes following project component and quality requirements.
+- Use semantic HTML where possible (`<button>`, `<a>`, `<nav>`, `<main>`).
+- Add `aria-*` attributes for custom components.
+- Ensure `prefers-reduced-motion` respected in CSS and JS.
+- Add or fix focus styles. Use design tokens for focus ring.
+- Verify reduced-motion behavior in tests.
+
+## Step 6: Verify Fixes
+
+- Re-run automated scan. No critical or major violations.
+- Manual keyboard and screen reader check on fixed areas.
+- Run full test suite to ensure no regressions.
+- Document remaining minor findings for future backlog.
+
+## Required Agent Delegation
+
+You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`) at the appropriate points:
+
+- **`hatch3r-a11y-auditor`** — MUST spawn to perform the full WCAG AA compliance audit autonomously. Provide the list of surfaces/components to audit and the current violation list.
+
+## Related Rules
+
+- **Rule**: `hatch3r-browser-verification` — follow this rule for live browser-based accessibility testing
+
+## Definition of Done
+
+- [ ] No critical a11y violations
+- [ ] WCAG AA compliance on all audited surfaces
+- [ ] Reduced motion respected (`prefers-reduced-motion` + user setting)
+- [ ] Keyboard navigation complete with visible focus
+- [ ] Color contrast ≥ 4.5:1 for text
+- [ ] ARIA live regions for dynamic content
+- [ ] Automated scan clean for critical/major
+- [ ] Manual verification completed

package/skills/hatch3r-agent-customize/SKILL.md

@@ -0,0 +1,75 @@
+---
+id: hatch3r-agent-customize
+description: Create and manage per-agent customization files for model overrides, description changes, and project-specific markdown instructions. Use when tailoring agent behavior to project-specific needs.
+---
+# Agent Customization Management
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Identify which agent to customize
+- [ ] Step 2: Determine customization needs
+- [ ] Step 3: Create the customization files
+- [ ] Step 4: Sync to propagate changes
+- [ ] Step 5: Verify the customized output
+```
+
+## Step 1: Identify Agent
+
+Determine which hatch3r agent needs customization:
+- Review the agents in `.agents/agents/` and their default behaviors
+- Identify gaps between default behavior and project needs
+- Check for existing customization files in `.hatch3r/agents/`
+
+## Step 2: Determine Customization Needs
+
+Decide which customization approach to use:
+
+**YAML (`.customize.yaml`)** — for structured overrides:
+- **Model**: Override the agent's preferred model (e.g., `model: opus`)
+- **Description**: Change how the agent is described in adapter frontmatter
+- **Enabled**: Set to `false` to disable the agent entirely
+
+**Markdown (`.customize.md`)** — for free-form instructions:
+- Domain-specific review checklists
+- Architecture context and constraints
+- Project-specific workflow steps
+- Compliance and security requirements
+
+## Step 3: Create Customization Files
+
+Create files in `.hatch3r/agents/`:
+
+**For YAML overrides:**
+```yaml
+# .hatch3r/agents/{agent-id}.customize.yaml
+model: opus
+description: "Security-focused reviewer for healthcare platform"
+```
+
+**For markdown instructions:**
+Create `.hatch3r/agents/{agent-id}.customize.md` with project-specific instructions. This content is injected into the managed block under `## Project Customizations`.
+
+Set only the fields/content you need — partial customization is valid.
+
+## Step 4: Sync
+
+Run `npx hatch3r sync` to propagate customizations to all adapter outputs. The sync:
+- Reads `.customize.yaml` for structured overrides (model, description, enabled)
+- Reads `.customize.md` and appends it inside the managed block
+- Generates updated output for every configured adapter (Cursor, Claude, etc.)
+
+## Step 5: Verify
+
+Confirm customizations appear in adapter output files:
+- Check model appears in frontmatter (e.g., `.cursor/agents/hatch3r-reviewer.md`)
+- Check markdown instructions appear inside the managed block
+- Verify disabled agents are absent from adapter outputs
+
+## Definition of Done
+
+- [ ] Customization files created in `.hatch3r/agents/`
+- [ ] `npx hatch3r sync` completes without errors
+- [ ] Adapter output files reflect the customizations
+- [ ] Customization files committed to the repository

package/skills/hatch3r-api-spec/SKILL.md

@@ -0,0 +1,66 @@
+---
+id: hatch3r-api-spec
+type: skill
+description: Generate and validate OpenAPI specifications from codebase. Covers endpoint design, schema validation, and documentation generation.
+---
+
+# API Specification Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Inventory existing endpoints
+- [ ] Step 2: Generate OpenAPI spec
+- [ ] Step 3: Validate schemas
+- [ ] Step 4: Generate documentation
+- [ ] Step 5: Verify spec accuracy
+```
+
+## Step 1: Inventory Existing Endpoints
+
+- Scan route definitions across the codebase (controllers, handlers, route files).
+- For each endpoint, extract: HTTP method, path, request parameters, request body shape, response body shape, status codes, authentication requirements.
+- Identify inconsistencies in naming, parameter styles, or response formats.
+- Check for undocumented endpoints that exist in code but lack API docs.
+
+## Step 2: Generate OpenAPI Spec
+
+- Create or update `openapi.yaml` (or `openapi.json`) at the project root or `docs/api/` directory.
+- Use OpenAPI 3.1 format.
+- Include `info` block with title, version, description, and contact.
+- Group endpoints by tag (resource or domain area).
+- Define reusable `components/schemas` for shared request/response types.
+- Use `$ref` references to avoid schema duplication.
+- Add `security` schemes matching the project's authentication (Bearer, API key, OAuth2).
+
+## Step 3: Validate Schemas
+
+- Ensure all request bodies have JSON Schema validation constraints (`required`, `minLength`, `maxLength`, `pattern`, `enum`).
+- Verify response schemas match actual serialized output (check serializers, DTOs, or response builders).
+- Validate enum values match database constraints or application constants.
+- Check for nullable fields — mark explicitly with `nullable: true` or type union.
+- Run a spec linter (e.g., `spectral`, `redocly lint`) if available in the project.
+
+## Step 4: Generate Documentation
+
+- Produce human-readable API docs from the spec (Swagger UI, Redoc, or Markdown).
+- Include example request/response bodies for each endpoint.
+- Document error response shapes with status code meanings.
+- Add authentication setup instructions.
+- Include rate limiting and pagination details where applicable.
+
+## Step 5: Verify Spec Accuracy
+
+- Cross-reference the generated spec against integration tests to confirm endpoint behavior.
+- Verify content types (`application/json`, `multipart/form-data`, etc.) match actual handlers.
+- Check that path parameters, query parameters, and headers are correctly documented.
+- Validate against any existing API consumers (SDKs, frontend clients) for breaking changes.
+
+## Definition of Done
+
+- [ ] OpenAPI spec covers all endpoints in the codebase
+- [ ] All schemas have validation constraints
+- [ ] Spec passes linter validation
+- [ ] Example requests/responses included
+- [ ] No breaking changes to existing API consumers