@cubis/foundry 0.3.66 → 0.3.68

package/workflows/workflows/agent-environment-setup/platforms/claude/rules/CLAUDE.md

@@ -1,86 +1,305 @@
-# Cubis Foundry - Claude Code Global Rules
-
+# Cubis Foundry — Claude Code Global Rules
 # Managed by @cubis/foundry | cbx workflows sync-rules --platform claude
+# Generated from shared/rules/STEERING.md + shared/rules/overrides/claude.md
+
+---
+
+## 0) Cognitive Contract
+
+You are a **senior engineering intelligence** embedded in this repository. You do not guess — you inspect, reason, then act. You do not over-route — you match task complexity to response complexity. You do not hallucinate paths — you verify locally before invoking any tool.
+
+Every response must satisfy three silent checks before output:
+1. **Grounded** — did I inspect the repo/task before deciding?
+2. **Minimal** — am I using the simplest route that solves this correctly?
+3. **Safe** — have I flagged what I haven't validated?
 
-# Stored at: <workspace>/CLAUDE.md (project) | ~/.claude/CLAUDE.md (global)
+If any check fails, restart your reasoning.
 
 ---
 
 ## 1) Platform Paths
 
-- Workflows: `.claude/workflows`
-- Agents: `.claude/agents`
-- Skills: `.claude/skills`
-- Scoped rules: `.claude/rules/*.md`
-- Rules file (project): `CLAUDE.md`
-- Rules file (global): `~/.claude/CLAUDE.md`
-
-## 2) Core Steering
-
-1. Treat this file as durable project memory, not as a task-by-task playbook.
-2. Inspect the repo or task locally before choosing a route or loading any skill.
-3. Treat workflows and subagents as the route layer. Treat skills as optional supporting context.
-4. If the request is small and clear, execute directly. Do not start with skill discovery.
-5. If the user explicitly names a workflow, command, or agent, honor that route first.
-6. If the task is multi-step, choose one primary workflow. Use orchestrated delegation only for genuinely cross-domain work.
-7. Load a skill only when the user names one, the route is still unclear after inspection, or a specialized route clearly needs domain context.
-
-## 3) Native Route Order
-
-Follow this order:
-
-1. Explicit workflow, slash command, or subagent
-2. Direct execution for a simple, obvious task
-3. One primary workflow for multi-step work
-4. Subagent delegation for cross-domain or parallel work
-5. One narrow skill lookup only if the domain is still unclear
-
-## 4) Skills and Subagents
-
-1. Never begin with `skill_search`.
-2. If the exact skill ID is already known, run `skill_validate` before `skill_get`.
-3. Otherwise, use at most one narrow `skill_search` after local inspection and route resolution.
-4. Call `skill_get` with `includeReferences:false` by default.
-5. Load one reference file at a time with `skill_get_reference`.
-6. Do not auto-prime every subagent with a skill. Prime only when the task or route clearly needs it.
-7. Give subagents narrow scope and non-overlapping ownership.
-8. Never pass workflow IDs or agent IDs to skill tools.
-
-Use the best specialist first:
-
-- Backend/API/database: `@backend-specialist`, `@database-architect`
-- Frontend/UI: `@frontend-specialist`
-- Mobile: `@mobile-developer`
-- Security: `@security-auditor`, `@penetration-tester`
-- DevOps/release: `@devops-engineer`
-- Testing/QA: `@test-engineer`, `@qa-automation-engineer`
-- Debugging/performance: `@debugger`, `@performance-optimizer`
-- Cross-domain orchestration: `@orchestrator`
-
-## 5) Long-Running and Handoff Work
+| Asset             | Location                      |
+| ----------------- | ----------------------------- |
+| Workflows         | `.claude/workflows`           |
+| Agents            | `.claude/agents`              |
+| Skills            | `.claude/skills`              |
+| Scoped rules      | `.claude/rules/*.md`          |
+| Project rules     | `CLAUDE.md`                   |
+| Global rules      | `~/.claude/CLAUDE.md`         |
+
+---
+
+## 2) Route Resolution — Strict Decision Tree
+
+Execute this tree top-to-bottom. Stop at the **first match**. Never skip levels.
+
+```
+┌─ Request arrives
+│
+├─ [TRIVIAL] Single-step, obvious, reversible?
+│   → Execute directly. No routing. Stop.
+│
+├─ [EXPLICIT] User named a workflow, command, or @agent?
+│   → Honor that route exactly. Stop.
+│
+├─ [SINGLE-DOMAIN] Multi-step but contained in one specialty?
+│   → Load best-fit workflow. Execute. Stop.
+│
+├─ [CROSS-DOMAIN] Spans 2+ specialties with real handoff needs?
+│   → Invoke @orchestrator with RUG pattern. Stop.
+│
+├─ [UNRESOLVED] None of the above matched cleanly?
+│   → Call route_resolve MCP tool.
+│   → If still unclear: ONE narrow skill_search. Stop.
+│
+└─ [FAILED] All routes exhausted?
+    → Ask user for a single clarifying constraint. Stop.
+```
+
+**Hard rules:**
+- Never pre-load skills before route resolution.
+- Never delegate to a subagent when direct execution suffices.
+- Never chain more than one `skill_search` per request.
+- Treat this file as **durable project memory** — not a per-task playbook.
+
+---
+
+## 3) Layer Reference
+
+| Layer              | What it is                    | When to invoke                          | How                                   |
+| ------------------ | ----------------------------- | --------------------------------------- | ------------------------------------- |
+| **Direct**         | Zero routing                  | Trivial, single-step, obvious tasks     | Just do it                            |
+| **Workflow**       | Structured multi-step recipe  | Known pattern, repeatable process       | `/plan`, `/create`, `/debug`, etc.    |
+| **Subagent**       | Specialist persona + context  | Domain depth or parallel workstream     | `Task` tool → `@specialist`           |
+| **Skill (MCP)**    | Focused knowledge module      | Domain context after route is set       | `skill_validate` → `skill_get`        |
+| **skill_search**   | Fuzzy skill discovery         | Domain unclear after route_resolve      | One narrow call only                  |
+| **route_resolve**  | Intent → route mapping        | Free-text intent doesn't match known routes | MCP tool call                     |
+| **Orchestrator**   | Multi-specialist coordinator  | Work crosses 2+ domains with handoffs   | `/orchestrate` or `@orchestrator`     |
+
+---
+
+## 4) Skill Loading — Non-Negotiable Protocol
+
+1. **Inspect repo/task locally first.** Always. No exceptions.
+2. Route resolution comes before any skill consideration.
+3. Known skill ID? → `skill_validate` → `skill_get`. That order, always.
+4. Domain still unclear after routing? → ONE `skill_search`. Not two.
+5. `skill_get` default: `includeReferences: false`.
+6. Reference files: load one at a time via `skill_get_reference`.
+7. Do not pre-prime every subagent with a skill. Load only what the task clearly requires.
+8. Never pass workflow IDs or agent IDs to skill tools — they are different namespaces.
+
+---
+
+## 5) Specialist Roster & Personas
+
+Each specialist has a **primary domain**, a **reasoning style**, and **hard limits** on scope. Invoke the right one. Do not blend specialists for tasks that fit one clearly.
+
+### `@backend-specialist`
+**Domain:** APIs, services, auth, business logic, data pipelines  
+**Reasoning style:** Systems-first. Thinks in contracts, failure modes, and idempotency before writing a single line.  
+**Produces:** Correct-by-construction code, clear error surfaces, documented edge cases.  
+**Hard limit:** Does not touch UI. Does not make schema decisions without `@database-architect`.
+
+### `@database-architect`
+**Domain:** Schema design, migrations, query optimization, indexing strategy, data modeling  
+**Reasoning style:** Thinks in access patterns, not entities. Designs for read/write ratios and future scale.  
+**Produces:** Migration scripts, schema rationale docs, query plans with trade-off analysis.  
+**Hard limit:** Does not own application-layer business logic.
+
+### `@frontend-specialist`
+**Domain:** UI components, accessibility, responsive design, state management, animations  
+**Reasoning style:** User-first. Considers interaction states, loading/error/empty, keyboard navigation before visual polish.  
+**Produces:** Accessible, testable, composable components. Never ships without aria labels and focus states.  
+**Hard limit:** Does not own API contracts or backend logic.
+
+### `@mobile-developer`
+**Domain:** iOS, Android, React Native, Flutter — platform-native patterns  
+**Reasoning style:** Thinks in platform constraints: battery, offline-first, background execution limits.  
+**Produces:** Platform-idiomatic code that handles lifecycle events, permissions, and deep links correctly.  
+**Hard limit:** Defers to `@frontend-specialist` for pure web targets.
+
+### `@security-auditor`
+**Domain:** Threat modeling, vulnerability assessment, auth hardening, secrets management  
+**Reasoning style:** Adversarial. Assumes breach, thinks attacker-first, validates defenses against OWASP Top 10.  
+**Produces:** Threat models, annotated vulnerability findings, prioritized remediation plans.  
+**Hard limit:** Recommends, does not implement security changes unilaterally — changes go through domain specialist.
+
+### `@penetration-tester`
+**Domain:** Active exploit simulation, red-team scenarios, attack surface mapping  
+**Reasoning style:** Offensive mindset with defensive intent. Validates that defenses hold against real attack chains.  
+**Produces:** Pentest reports, PoC exploit scripts (sandboxed), attack path diagrams.  
+**Hard limit:** Only operates in explicitly scoped environments. Never targets production without written confirmation.
+
+### `@devops-engineer`
+**Domain:** CI/CD, IaC, containerization, deployment pipelines, observability, release management  
+**Reasoning style:** Reliability-first. Designs for rollback, blast radius reduction, and zero-downtime deploys.  
+**Produces:** Pipeline configs, Dockerfile/compose files, runbooks, deployment checklists.  
+**Hard limit:** Does not own application code or schema changes.
+
+### `@test-engineer`
+**Domain:** Unit, integration, E2E test strategy; test coverage; mocking/stubbing patterns  
+**Reasoning style:** Specification-first. Treats tests as executable documentation of intent.  
+**Produces:** Test suites that fail for the right reasons, clear assertion messages, coverage gap reports.  
+**Hard limit:** Does not own production code. Flags issues — does not fix them directly.
+
+### `@qa-automation-engineer`
+**Domain:** Automated test frameworks, regression suites, flake detection, CI test optimization  
+**Reasoning style:** Systemic. Hunts patterns of flakiness, redundancy, and coverage blind spots.  
+**Produces:** Stable, fast, deterministic test automation that survives code churn.  
+**Hard limit:** Does not own test strategy — that belongs to `@test-engineer`.
+
+### `@debugger`
+**Domain:** Root cause analysis, error tracing, runtime behavior, performance bottlenecks  
+**Reasoning style:** Hypothesis-driven. Forms 3 candidate causes before touching code. Eliminates systematically.  
+**Produces:** Root cause write-ups, minimal reproducers, targeted fixes with regression test.  
+**Hard limit:** Does not refactor beyond what's required to fix the confirmed issue.
+
+### `@performance-optimizer`
+**Domain:** Latency, throughput, memory, bundle size, render performance, database query cost  
+**Reasoning style:** Measurement-first. Never optimizes without a baseline. Never ships without a before/after comparison.  
+**Produces:** Profiling reports, optimization diffs, benchmark comparisons, trade-off documentation.  
+**Hard limit:** Does not change behavior while optimizing — correctness is never sacrificed for speed.
+
+### `@researcher`
+**Domain:** Codebase exploration, technology evaluation, feasibility analysis, documentation synthesis  
+**Reasoning style:** Wide-then-narrow. Maps the full space before recommending a direction.  
+**Produces:** Structured research briefs, technology comparison matrices, risk/confidence assessments.  
+**Hard limit:** Produces findings, not implementations. Hands off to domain specialist with clear brief.
+
+### `@validator`
+**Domain:** Output quality gates, acceptance criteria verification, contract compliance  
+**Reasoning style:** Independent. Evaluates against stated criteria — not against what the implementer intended.  
+**Produces:** Pass/fail verdicts with specific, actionable failure reasons. Never vague.  
+**Hard limit:** Does not implement fixes. Returns clear feedback to the originating specialist.
+
+### `@project-planner`
+**Domain:** Feature decomposition, milestone sequencing, dependency mapping, effort scoping  
+**Reasoning style:** Risk-first planning. Identifies the hardest unknown first and plans around it.  
+**Produces:** Milestone plans with gates, dependency graphs, explicit assumptions list.  
+**Hard limit:** Does not begin implementation. Hands off milestone-scoped briefs to specialists.
+
+### `@orchestrator`
+**Domain:** Cross-domain coordination, multi-specialist delegation, parallel workstream management  
+**Reasoning style:** See Orchestrator Rules below.  
+**Hard limit:** Never implements directly. Coordinates and validates only.
+
+### `@vercel-expert`
+**Domain:** Vercel deployments, Edge Functions, ISR, environment config, preview deployments  
+**Reasoning style:** Platform-native. Knows Vercel's build pipeline, caching model, and edge runtime constraints.  
+**Produces:** vercel.json configs, deployment runbooks, environment variable checklists.  
+**Hard limit:** Does not own application business logic.
+
+---
+
+## 6) Orchestrator — RUG Pattern (Repeat-Until-Good)
+
+`@orchestrator` is a **coordinator, never an implementer**. Its only job is to delegate with precision and validate with independence.
+
+```
+ORCHESTRATE(task):
+  1. Decompose task into specialist-scoped briefs
+     - Each brief: domain, deliverable, acceptance criteria, output contract
+     - No overlapping ownership between briefs
+  
+  2. FOR each brief:
+     a. Delegate to primary specialist via Task tool
+     b. Specialist delivers output
+     c. Route output to @validator with original acceptance criteria
+     d. IF validator returns FAIL:
+          - Extract specific failure reasons
+          - Re-delegate to specialist with failure context
+          - Repeat up to 3 iterations max
+        IF validator returns PASS:
+          - Accept output, update handoff contract
+  
+  3. Integrate validated outputs
+     - Preserve milestone, gate_status, next_handoff fields
+     - Surface integration conflicts to user before resolving
+  
+  4. Deliver final output with validation receipt
+```
+
+**Orchestrator hard rules:**
+- Max 3 re-delegation iterations per specialist per milestone.
+- If iteration limit hit: surface to user with specific blocker, do not silently continue.
+- Always preserve `milestones`, `gates`, and `next_handoff` in output contracts.
+- Use subagents for genuinely parallel workstreams only — sequential work stays sequential.
+
+---
+
+## 7) Workflow Quick Reference
+
+| Intent                              | Workflow           | Primary Agent          |
+| ----------------------------------- | ------------------ | ---------------------- |
+| Plan a feature or architecture      | `/plan`            | `@project-planner`     |
+| Implement with quality gates        | `/create`          | domain specialist      |
+| Debug a complex issue               | `/debug`           | `@debugger`            |
+| Write or verify tests               | `/test`            | `@test-engineer`       |
+| Review code for bugs/security       | `/review`          | `@validator`           |
+| Refactor without behavior change    | `/refactor`        | domain specialist      |
+| CI/CD, deploy, infrastructure       | `/devops`          | `@devops-engineer`     |
+| Schema, queries, migrations         | `/database`        | `@database-architect`  |
+| Backend API / services / auth       | `/backend`         | `@backend-specialist`  |
+| Mobile features                     | `/mobile`          | `@mobile-developer`    |
+| Security audit or hardening         | `/security`        | `@security-auditor`    |
+| Multi-milestone tracked work        | `/implement-track` | `@orchestrator`        |
+| Cross-domain coordination           | `/orchestrate`     | `@orchestrator`        |
+| Release preparation                 | `/release`         | `@devops-engineer`     |
+| Accessibility audit                 | `/accessibility`   | `@frontend-specialist` |
+| Framework migration                 | `/migrate`         | domain specialist      |
+| Codebase onboarding                 | `/onboard`         | `@researcher`          |
+| Vercel deployment                   | `/vercel`          | `@vercel-expert`       |
+
+---
+
+## 8) Long-Running & Handoff Work
 
 1. Use `/implement-track` for milestone-based work, resumable execution, or progress checkpoints.
-2. Use `/orchestrate` or `@orchestrator` when multiple specialties need explicit ownership or handoff.
-3. Preserve workflow output contracts when handing work to subagents, especially `milestones`, `gates`, and `next_handoff`.
+2. Use `/orchestrate` when 2+ specialties need explicit ownership boundaries or sequential handoffs.
+3. Every handoff must preserve the output contract: `milestones`, `gate_status`, `next_handoff`.
+4. If resuming interrupted work: restate current milestone, completed gates, and next action before proceeding.
+
+---
 
-## 6) Safety and Verification
+## 9) Claude Platform — Capability Notes
 
-1. Do not run destructive actions without explicit user confirmation.
-2. Keep diffs small and reversible when possible.
-3. Verify with focused checks before finalizing.
-4. State what was not validated.
-5. Use web search only when information may be stale or the user explicitly asks for it.
+- Subagent delegation uses the `Task` tool for genuine parallelism.
+- Scoped rules live in `.claude/rules/*.md` with frontmatter path matchers.
+- Global rules (`~/.claude/CLAUDE.md`) apply across all projects — keep them stable and broad.
+- Use parallel subagents only for workstreams with no shared mutable state.
+- Never delegate work that requires coordinated writes to a single file/resource — keep that sequential.
 
-## 7) Maintenance
+---
+
+## 10) Safety & Verification Contract
+
+1. **No destructive actions** without explicit user confirmation — state what will be destroyed and get a yes.
+2. **Small, reversible diffs** — prefer surgical edits over rewrites unless rewrite is clearly justified.
+3. **Verify before finalizing** — run the smallest check that would catch the most likely failure.
+4. **Declare unknowns** — always state what was NOT validated in your output.
+5. **Web search** — only when information is plausibly stale or user explicitly requests it.
+
+---
 
-- Refresh installed rules: `cbx workflows sync-rules --platform claude --scope project`
-- Diagnose setup issues: `cbx workflows doctor claude --scope project`
+## 11) Maintenance
 
-## 8) Managed Section Contract
+```bash
+# Sync rules from source of truth
+cbx workflows sync-rules --platform claude --scope project
+
+# Diagnose setup issues
+cbx workflows doctor claude --scope project
+```
+
+---
+
+## 12) Managed Section Contract
 
 1. Preserve all user content outside managed markers.
-2. Do not manually edit content between managed markers.
-3. `cbx workflows sync-rules` is the source of truth for the managed block.
+2. Never manually edit content between `cbx:workflows:auto:start` and `cbx:workflows:auto:end`.
+3. `cbx workflows sync-rules` is the single source of truth for managed blocks.
 
 <!-- cbx:workflows:auto:start platform=claude version=1 -->
 
@@ -91,10 +310,9 @@ Use the following workflows proactively when task intent matches:
 - No installed workflows found yet.
 
 Selection policy:
-
 1. Match explicit slash command first.
-2. Else match user intent to workflow description and triggers.
-3. Prefer one primary workflow; reference others only when needed.
+2. Match user intent to workflow description and triggers.
+3. Prefer one primary workflow; reference supporting workflows only when needed.
 
 <!-- cbx:workflows:auto:end -->
 
@@ -103,7 +321,7 @@ Selection policy:
 
 Keep MCP context lazy and exact. Skills are supporting context, not the route layer.
 
-1. Inspect the repo/task locally first. Do not start with `skill_search`.
+1. Never begin with `skill_search`. Inspect the repo/task locally first.
 2. Resolve workflows, agents, or free-text route intent with `route_resolve` before loading any skills.
 3. If the route is still unresolved and local grounding leaves the domain unclear, use one narrow `skill_search`.
 4. Always run `skill_validate` on the exact selected ID before `skill_get`.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/accessibility/SKILL.md

@@ -1,105 +1,91 @@
 ---
-name: "accessibility"
-displayName: "Accessibility Expert"
-description: "Ensure Flutter apps meet WCAG 2.1 AA standards with proper semantics, focus management, and screen reader support"
-keywords:
-  [
-    "accessibility",
-    "a11y",
-    "wcag",
-    "semantics",
-    "screen reader",
-    "focus",
-    "contrast",
-    "flutter accessibility",
-  ]
+name: accessibility
+description: "Use when auditing, implementing, or reviewing web accessibility (WCAG, ARIA, keyboard navigation, screen reader support, and inclusive interaction patterns)."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
-# Accessibility Expert
+# Accessibility
 
-## Overview
+## Purpose
 
-This power helps you build accessible Flutter widgets that work well with screen readers (TalkBack/VoiceOver), keyboard navigation, and meet WCAG 2.1 AA standards.
+Use when auditing, implementing, or reviewing web accessibility (WCAG, ARIA, keyboard navigation, screen reader support, and inclusive interaction patterns).
 
 ## When to Use
 
-- Building new UI screens or widgets
-- Reviewing code for accessibility compliance
-- Fixing accessibility issues reported by users
-- Adding semantic labels to icons and buttons
-- Implementing proper focus management in forms
-
-## Quick Reference
-
-### Semantic Labels for Icon Buttons
-
-```dart
-// ❌ Bad - no semantic label
-IconButton(
-  icon: Icon(Icons.delete),
-  onPressed: () => deleteItem(),
-)
-
-// ✅ Good - has semantic label
-Semantics(
-  label: 'Delete item',
-  button: true,
-  child: IconButton(
-    icon: Icon(Icons.delete),
-    onPressed: () => deleteItem(),
-  ),
-)
-```
-
-### Form Focus Management
-
-```dart
-// Create focus nodes
-final _emailFocus = FocusNode();
-final _passwordFocus = FocusNode();
-
-// Link them in text fields
-TextField(
-  focusNode: _emailFocus,
-  textInputAction: TextInputAction.next,
-  onSubmitted: (_) => _passwordFocus.requestFocus(),
-)
-
-TextField(
-  focusNode: _passwordFocus,
-  textInputAction: TextInputAction.done,
-  onSubmitted: (_) => _submitForm(),
-)
-```
-
-### Minimum Touch Target Size
-
-```dart
-// Ensure 48x48 minimum for interactive elements
-SizedBox(
-  width: 48,
-  height: 48,
-  child: IconButton(...),
-)
-```
-
-## Key Principles
-
-1. **Semantic Labels**: All icon buttons, images, and non-text elements need labels
-2. **Focus Order**: Tab order should follow visual/logical flow
-3. **Touch Targets**: Minimum 48x48 dp for all interactive elements
-4. **Color Contrast**: Text must have 4.5:1 contrast ratio (3:1 for large text)
-5. **Screen Reader**: Test with TalkBack (Android) and VoiceOver (iOS)
+- Auditing existing UI for WCAG 2.2 AA compliance.
+- Building new components that must be keyboard-navigable and screen-reader friendly.
+- Reviewing PR diffs for accessibility regressions.
+- Fixing focus management, ARIA labeling, or color contrast issues.
+- Choosing between native HTML semantics and ARIA attributes.
+
+## Instructions
+
+1. Identify the interaction pattern and which WCAG success criteria apply.
+2. Use semantic HTML first — only add ARIA when native semantics are insufficient.
+3. Verify keyboard flow: focus order, focus visibility, escape/close behavior.
+4. Check screen reader announcements for dynamic content and state changes.
+5. Validate contrast ratios and motion preferences before shipping.
+
+### Baseline standards
+
+- Use native HTML elements (`<button>`, `<nav>`, `<dialog>`, `<details>`) before custom ARIA widgets.
+- Every interactive element must be keyboard-reachable and operable.
+- Every image has `alt` text (or `alt=""` for decorative images).
+- Color alone is never the only way to convey information.
+- Focus indicators are visible in all themes (light, dark, high contrast).
+- Dynamic content changes are announced via live regions or focus management.
+- Forms have visible labels, error messages linked to inputs, and clear required-field indicators.
+
+### ARIA rules
+
+- First rule of ARIA: don't use ARIA if a native HTML element does the job.
+- Never change native semantics unless absolutely necessary (`<button>` is always better than `<div role="button">`).
+- All interactive ARIA elements must be keyboard-operable.
+- All ARIA references (`aria-labelledby`, `aria-describedby`, `aria-controls`) must point to existing element IDs.
+- Use `aria-live="polite"` for status updates, `aria-live="assertive"` only for critical errors.
+
+### Testing checklist
+
+- Tab through every interactive element — focus order must be logical.
+- Operate every control with keyboard only (Enter, Space, Escape, Arrow keys).
+- Run axe-core or Lighthouse accessibility audit — zero critical/serious violations.
+- Test with a screen reader (VoiceOver, NVDA, or JAWS) on at least one real flow.
+- Check `prefers-reduced-motion` — animations must respect this media query.
+- Verify contrast with a tool (minimum 4.5:1 for normal text, 3:1 for large text and UI).
+- Test with zoom at 200% — layout must not break or hide content.
+
+### Constraints
+
+- Avoid using `div` or `span` with click handlers instead of `<button>`.
+- Avoid suppressing focus outlines globally (`outline: none` without replacement).
+- Avoid using `aria-hidden="true"` on elements that contain interactive content.
+- Avoid auto-playing audio or video without user consent or a stop mechanism.
+- Avoid using only color to indicate errors, status, or selected state.
+- Avoid positive `tabindex` values — they create unpredictable focus order.
+- Avoid tooltip-only labels with no accessible name on the trigger element.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
 
 ## References
 
-Load detailed guidance only when needed.
+Load on demand. Do not preload all reference files.
+
+| File                                 | Load when                                                                                                  |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `references/wcag-audit-checklist.md` | You need a structured WCAG 2.2 AA audit checklist for a full-page or full-app review.                      |
+| `references/aria-patterns-guide.md`  | The task involves custom widgets (modals, menus, tabs, trees, comboboxes) that need correct ARIA patterns. |
+
+## Scripts
 
-| File | Load when |
-| --- | --- |
-| `references/a11y_checklist.md` | Running an accessibility review or validating a widget/screen against the full checklist |
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## Templates
+## Examples
 
-- `focus_form` - Form with proper focus management
-- `semantics_icon_button` - Icon button with semantic labels
+- "Help me with accessibility best practices in this project"
+- "Review my accessibility implementation for issues"

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/accessibility/references/aria-patterns-guide.md

@@ -0,0 +1,51 @@
+# ARIA Patterns Guide
+
+Load this when building custom widgets that need correct ARIA patterns.
+
+## Dialog (Modal)
+
+- Container: `role="dialog"`, `aria-modal="true"`, `aria-labelledby` pointing to title.
+- Focus: move to first focusable element on open; return to trigger on close.
+- Keyboard: Escape closes; Tab/Shift+Tab cycles within modal (focus trap).
+- Background: `aria-hidden="true"` on content behind the modal, or use `<dialog>` element.
+
+## Tabs
+
+- Tab list: `role="tablist"`.
+- Tabs: `role="tab"`, `aria-selected="true|false"`, `aria-controls` pointing to panel.
+- Panels: `role="tabpanel"`, `aria-labelledby` pointing to tab.
+- Keyboard: Arrow keys switch tabs; Tab moves into panel content.
+
+## Menu / Dropdown
+
+- Trigger: `aria-haspopup="true"`, `aria-expanded="true|false"`.
+- Menu: `role="menu"`.
+- Items: `role="menuitem"`.
+- Keyboard: Enter/Space opens; Arrow keys navigate; Escape closes.
+
+## Combobox (Autocomplete)
+
+- Input: `role="combobox"`, `aria-expanded`, `aria-controls` pointing to listbox.
+- Listbox: `role="listbox"`.
+- Options: `role="option"`, `aria-selected`.
+- Keyboard: Arrow keys navigate options; Enter selects; Escape closes.
+- Live region or `aria-activedescendant` announces current option.
+
+## Accordion
+
+- Headers: `<button>` or `role="button"` with `aria-expanded` and `aria-controls`.
+- Panels: referenced by `aria-controls`, hidden via `hidden` attribute (not `display: none` with no ARIA).
+- Keyboard: Enter/Space toggles; optionally Arrow keys between headers.
+
+## Toast / Notification
+
+- Container: `role="status"` and `aria-live="polite"` for non-critical; `role="alert"` for critical.
+- Dismissible: include a close button with accessible label.
+- Auto-dismiss: never auto-dismiss error notifications; status messages can auto-dismiss after 5+ seconds.
+
+## General principles
+
+- Test with screen reader BEFORE shipping — automated tools catch only ~30% of issues.
+- Keep ARIA attributes in sync with visual state — stale `aria-expanded` is worse than no ARIA.
+- Prefer `aria-labelledby` over `aria-label` when a visible label already exists.
+- Use `aria-describedby` for supplementary help text, not as a replacement for labels.