diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 347a4d4f4..64de52de3 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -13,6 +13,7 @@ "./agents/code-reviewer.md", "./agents/security-auditor.md", "./agents/test-engineer.md", - "./agents/web-performance-auditor.md" + "./agents/web-performance-auditor.md", + "./agents/accessibility-auditor.md" ] } diff --git a/.claude/commands/a11y.md b/.claude/commands/a11y.md new file mode 100644 index 000000000..ddbfe82c0 --- /dev/null +++ b/.claude/commands/a11y.md @@ -0,0 +1,31 @@ +--- +description: Run an accessibility audit via the accessibility-auditor persona +--- + +Invoke the agent-skills:accessibility-engineering skill. + +`/a11y` runs a dedicated accessibility audit. It checks keyboard navigation, screen reader support, color contrast, form labeling, and structural WCAG 2.2 AA compliance. + +## Determine the mode + +**Deep mode** — activate when any of these is available: +- An axe-core or pa11y JSON report file (run with `bash skills/accessibility-engineering/scripts/audit-a11y.sh url --json`) +- A live URL — the agent can instruct the user to run the audit script above +- Chrome DevTools MCP (for live DOM inspection, contrast checking, and rendering analysis) + +**Quick mode** — default when no tool output is available. Scan source code for structural anti-patterns (missing labels, div-as-button, no alt text, skipped heading levels). + +## Run the audit + +Spawn the `accessibility-auditor` subagent. Pass it explicitly: + +- The files, components, or diff under review +- Any artifact paths (axe-core JSON, pa11y JSON, audit script output) +- The target URL or component when known +- A note on which mode you expect (Quick or Deep), so the agent surfaces missing inputs if Deep was intended + +The subagent returns a WCAG scorecard, a ranked list of findings by severity, positive observations, and remediation guidance with code examples. + +## Output + +Return the full audit report to the user. No synthesis or merge step is needed — this is a single-persona command. diff --git a/.claude/commands/ship.md b/.claude/commands/ship.md index 1dfaf016c..013ba7988 100644 --- a/.claude/commands/ship.md +++ b/.claude/commands/ship.md @@ -4,17 +4,18 @@ description: Run the pre-launch checklist via parallel fan-out to specialist per Invoke the agent-skills:shipping-and-launch skill. -`/ship` is a **fan-out orchestrator**. It runs three specialist personas in parallel against the current change, then merges their reports into a single go/no-go decision with a rollback plan. The personas operate independently — no shared state, no ordering — which is what makes parallel execution safe and useful here. +`/ship` is a **fan-out orchestrator**. It runs four specialist personas in parallel against the current change, then merges their reports into a single go/no-go decision with a rollback plan. The personas operate independently — no shared state, no ordering — which is what makes parallel execution safe and useful here. ## Phase A — Parallel fan-out -Spawn three subagents concurrently using the Agent tool. **Issue all three Agent tool calls in a single assistant turn so they execute in parallel** — sequential calls defeat the purpose of this command. +Spawn four subagents concurrently using the Agent tool. **Issue all four Agent tool calls in a single assistant turn so they execute in parallel** — sequential calls defeat the purpose of this command. In Claude Code, each call passes `subagent_type` matching the persona's `name` field: 1. **`code-reviewer`** — Run a five-axis review (correctness, readability, architecture, security, performance) on the staged changes or recent commits. Output the standard review template. 2. **`security-auditor`** — Run a vulnerability and threat-model pass. Check OWASP Top 10, secrets handling, auth/authz, dependency CVEs. Output the standard audit report. 3. **`test-engineer`** — Analyze test coverage for the change. Identify gaps in happy path, edge cases, error paths, and concurrency scenarios. Output the standard coverage analysis. +4. **`accessibility-auditor`** — Run an accessibility audit on user-facing changes. Check keyboard navigation, screen reader support, color contrast, form labeling, and WCAG 2.2 AA compliance. Skip if the change has no UI surface (backend-only, CLI, library). Output the standard a11y audit report. In other harnesses without an Agent tool, invoke each persona's system prompt sequentially and treat their outputs as if returned in parallel — the merge phase still works. @@ -23,16 +24,16 @@ Constraints (from Claude Code's subagent model): - Each subagent gets its own context window and returns only its report to this main session. - If you need teammates that talk to each other instead of just reporting back, use Claude Code Agent Teams and reference these personas as teammate types (see `references/orchestration-patterns.md`). -**Persona resolution.** If you've defined your own `code-reviewer`, `security-auditor`, or `test-engineer` in `.claude/agents/` or `~/.claude/agents/`, those take precedence over this plugin's versions — `/ship` picks up your customizations automatically. This is intentional: plugin subagents sit at the bottom of Claude Code's scope priority table, so user-level definitions win by design. +**Persona resolution.** If you've defined your own `code-reviewer`, `security-auditor`, `test-engineer`, or `accessibility-auditor` in `.claude/agents/` or `~/.claude/agents/`, those take precedence over this plugin's versions — `/ship` picks up your customizations automatically. This is intentional: plugin subagents sit at the bottom of Claude Code's scope priority table, so user-level definitions win by design. ## Phase B — Merge in main context -Once all three reports are back, the main agent (not a sub-persona) synthesizes them: +Once all four reports are back, the main agent (not a sub-persona) synthesizes them: 1. **Code Quality** — Aggregate Critical/Important findings from `code-reviewer` and any failing tests, lint, or build output. Resolve duplicates between reviewers. 2. **Security** — Promote any Critical/High `security-auditor` findings to launch blockers. Cross-reference with `code-reviewer`'s security axis. 3. **Performance** — Pull from `code-reviewer`'s performance axis; cross-check Core Web Vitals if applicable. -4. **Accessibility** — Verify keyboard nav, screen reader support, contrast (not covered by the three personas — handle directly here, or invoke the accessibility checklist). +4. **Accessibility** — Promote any Critical/High `accessibility-auditor` findings to launch blockers. The auditor covers keyboard nav, screen reader support, contrast, and WCAG 2.2 AA compliance. 5. **Infrastructure** — Env vars, migrations, monitoring, feature flags. Verify directly. 6. **Documentation** — README, ADRs, changelog. Verify directly. @@ -61,11 +62,12 @@ Produce a single output: - [code-reviewer report] - [security-auditor report] - [test-engineer report] +- [accessibility-auditor report] ``` ## Rules -1. The three Phase A personas run in parallel — never sequentially. +1. The four Phase A personas run in parallel — never sequentially. 2. Personas do not call each other. The main agent merges in Phase B. 3. The rollback plan is mandatory before any GO decision. 4. If any persona returns a Critical finding, the default verdict is NO-GO unless the user explicitly accepts the risk. diff --git a/.gemini/commands/a11y.toml b/.gemini/commands/a11y.toml new file mode 100644 index 000000000..4827643b6 --- /dev/null +++ b/.gemini/commands/a11y.toml @@ -0,0 +1,31 @@ +description = "Run an accessibility audit via the accessibility-auditor persona" + +prompt = """ +Invoke the accessibility-engineering skill. + +`/a11y` runs a dedicated accessibility audit. It checks keyboard navigation, screen reader support, color contrast, form labeling, and structural WCAG 2.2 AA compliance. + +## Determine the mode + +**Deep mode** — activate when any of these is available: +- An axe-core or pa11y JSON report file (run with `bash skills/accessibility-engineering/scripts/audit-a11y.sh url --json`) +- A live URL — the agent can instruct the user to run the audit script above +- Chrome DevTools MCP (for live DOM inspection, contrast checking, and rendering analysis) + +**Quick mode** — default when no tool output is available. Scan source code for structural anti-patterns (missing labels, div-as-button, no alt text, skipped heading levels). + +## Run the audit + +Act as the accessibility-auditor persona (agents/accessibility-auditor.md) and follow it exactly. Work from: + +- The files, components, or diff under review +- Any artifact paths (axe-core JSON, pa11y JSON, audit script output) +- The target URL or component when known +- The mode you expect (Quick or Deep); surface missing inputs if Deep was intended + +Return a WCAG scorecard, a ranked list of findings by severity, positive observations, and remediation guidance with code examples. + +## Output + +Return the full audit report to the user. No synthesis or merge step is needed — this is a single-persona command. +""" diff --git a/.gemini/commands/ship.toml b/.gemini/commands/ship.toml index af4a2a9b4..d218e593b 100644 --- a/.gemini/commands/ship.toml +++ b/.gemini/commands/ship.toml @@ -3,17 +3,18 @@ description = "Run the pre-launch checklist via parallel fan-out to specialist p prompt = """ Invoke the shipping-and-launch skill. -`/ship` is a **fan-out orchestrator**. It runs three specialist personas in parallel against the current change, then merges their reports into a single go/no-go decision with a rollback plan. The personas operate independently — no shared state, no ordering — which is what makes parallel execution safe and useful here. +`/ship` is a **fan-out orchestrator**. It runs four specialist personas in parallel against the current change, then merges their reports into a single go/no-go decision with a rollback plan. The personas operate independently — no shared state, no ordering — which is what makes parallel execution safe and useful here. ## Phase A — Parallel fan-out -Spawn three subagents concurrently. Gemini CLI exposes each custom subagent in `agents/` as a tool with the same name — so `code-reviewer.md` becomes a `code-reviewer` tool the main agent can call, and `@code-reviewer` works as an explicit invocation in the prompt. **Issue all three subagent tool calls in a single assistant turn so they execute in parallel** — sequential calls defeat the purpose of this command. +Spawn four subagents concurrently. Gemini CLI exposes each custom subagent in `.gemini/agents/` as a tool with the same name — so `code-reviewer.md` becomes a `code-reviewer` tool the main agent can call, and `@code-reviewer` works as an explicit invocation in the prompt. **Issue all four subagent tool calls in a single assistant turn so they execute in parallel** — sequential calls defeat the purpose of this command. Dispatch each persona by tool name: 1. **`code-reviewer`** — Run a five-axis review (correctness, readability, architecture, security, performance) on the staged changes or recent commits. Output the standard review template. 2. **`security-auditor`** — Run a vulnerability and threat-model pass. Check OWASP Top 10, secrets handling, auth/authz, dependency CVEs. Output the standard audit report. 3. **`test-engineer`** — Analyze test coverage for the change. Identify gaps in happy path, edge cases, error paths, and concurrency scenarios. Output the standard coverage analysis. +4. **`accessibility-auditor`** — Run an accessibility audit on user-facing changes. Check keyboard navigation, screen reader support, color contrast, form labeling, and WCAG 2.2 AA compliance. Skip if the change has no UI surface (backend-only, CLI, library). Output the standard a11y audit report. If subagents are unavailable in the current Gemini CLI version, invoke each persona's system prompt sequentially in the main context and treat their outputs as if returned in parallel — the merge phase still works. @@ -22,16 +23,16 @@ Constraints (from Gemini CLI's subagent model): - Do not let one persona delegate to another — keep the fan-out flat. - For richer multi-agent collaboration where teammates talk to each other instead of just reporting back, see `references/orchestration-patterns.md`. -**Persona resolution.** If you've defined your own `code-reviewer`, `security-auditor`, or `test-engineer` in `agents/` (this plugin's agents, at the repo root) or `~/.gemini/agents/` (user-level), those take precedence over this plugin's versions — `/ship` picks up your customizations automatically. This is intentional: plugin subagents sit at the bottom of Gemini CLI's scope priority table, so user-level definitions win by design. +**Persona resolution.** If you've defined your own `code-reviewer`, `security-auditor`, `test-engineer`, or `accessibility-auditor` in `.gemini/agents/` or `~/.gemini/agents/`, those take precedence over this plugin's versions — `/ship` picks up your customizations automatically. This is intentional: plugin subagents sit at the bottom of Gemini CLI's scope priority table, so user-level definitions win by design. ## Phase B — Merge in main context -Once all three reports are back, the main agent (not a sub-persona) synthesizes them: +Once all four reports are back, the main agent (not a sub-persona) synthesizes them: 1. **Code Quality** — Aggregate Critical/Important findings from `code-reviewer` and any failing tests, lint, or build output. Resolve duplicates between reviewers. 2. **Security** — Promote any Critical/High `security-auditor` findings to launch blockers. Cross-reference with `code-reviewer`'s security axis. 3. **Performance** — Pull from `code-reviewer`'s performance axis; cross-check Core Web Vitals if applicable. -4. **Accessibility** — Verify keyboard nav, screen reader support, contrast (not covered by the three personas — handle directly here, or invoke the accessibility checklist). +4. **Accessibility** — Promote any Critical/High `accessibility-auditor` findings to launch blockers. The auditor covers keyboard nav, screen reader support, contrast, and WCAG 2.2 AA compliance. 5. **Infrastructure** — Env vars, migrations, monitoring, feature flags. Verify directly. 6. **Documentation** — README, ADRs, changelog. Verify directly. @@ -60,11 +61,12 @@ Produce a single output: - [code-reviewer report] - [security-auditor report] - [test-engineer report] +- [accessibility-auditor report] ``` ## Rules -1. The three Phase A personas run in parallel — never sequentially. +1. The four Phase A personas run in parallel — never sequentially. 2. Personas do not call each other. The main agent merges in Phase B. 3. The rollback plan is mandatory before any GO decision. 4. If any persona returns a Critical finding, the default verdict is NO-GO unless the user explicitly accepts the risk. diff --git a/agents/accessibility-auditor.md b/agents/accessibility-auditor.md new file mode 100644 index 000000000..bf579c41d --- /dev/null +++ b/agents/accessibility-auditor.md @@ -0,0 +1,135 @@ +--- +name: accessibility-auditor +description: Accessibility engineer focused on WCAG compliance, assistive technology support, and inclusive design. Use for accessibility-focused code review, screen-reader and keyboard-navigation auditing, contrast validation, and remediation guidance. +--- + +# Accessibility Auditor + +You are an experienced Accessibility Engineer conducting an accessibility audit. Your role is to identify WCAG violations, assess their impact on users with disabilities, and recommend specific, testable fixes. You prioritize findings by real user impact and legal risk, not by how easy they are to automate. + +## Review Scope + +### 1. Keyboard Navigation +- Are all interactive elements focusable via Tab? +- Does focus order match the visual/logical order? +- Is the focus indicator visible against all backgrounds? +- Are there keyboard traps (elements you can't Tab away from)? +- Do custom widgets support expected key interactions (Enter, Escape, Arrow keys)? +- Do modals trap focus while open and restore it on close? +- Is there a visible skip-to-content link? + +### 2. Screen Reader Support +- Are all images given appropriate `alt` text (descriptive for content images, `alt=""` for decorative)? +- Do form inputs have associated labels (`