a11y-workflow

name	a11y-workflow
description	Orchestrate the a11y accessibility lifecycle: scout → plan → critique → [perspective audit] → test → critique. Dual-mode: full lifecycle automation or step-by-step dispatch. Spawns specialist agents at depth-1 from the main session.
license	Apache-2.0
compatibility	Claude Code only — orchestrates Claude Code subagent spawning
metadata	{"author":"zivtech","version":"1.1.0"}

A11y Workflow Orchestrator

This skill sequences the accessibility lifecycle by spawning specialist agents from the main session. All agents run at depth-1 — no nested delegation.

When to Use

• /a11y-workflow full <target> — run the complete plan-critique-test-critique lifecycle
• /a11y-workflow step <step-name> <target> — run a single step, user drives the sequence
• When reviewing or planning accessibility for a component, page, or feature

Team Roles

Role	Agent	Model	Job
Scout	a11y-scout	haiku	File discovery, ARIA inventory, component type ID
Planner	a11y-planner	opus	Design accessibility before coding (9-phase)
Critic	a11y-critic	opus	Review ARIA patterns, focus management, state communication (8-phase)
Tester	a11y-test skill	n/a	Playwright keyboard tests, axe-core scans, keyboard-a11y-tester journey audits, virtual-screen-reader component SR assertions
Auditor	perspective-audit	opus	Deep 7-perspective review on escalated perspectives

Context Passing Between Agents

Each agent starts with a fresh context window. The main session bridges context between them:

• Scout → Planner/Critic: Scout returns a structured recon summary (~500-1500 chars). Inject verbatim into the next agent's prompt.
• Planner → Critic: Planner writes plan to docs/a11y-plans/YYYY-MM-DD-<feature>-a11y-plan.md. Critic is spawned with file paths to the plan and source code — it reads both using its Read tool.
• Critic → Perspective Audit: Extract only the alarm levels and findings for escalated perspectives (~500-1500 chars). Inject into the perspective-audit prompt.
• Test → Critic: Inject structured test results summary (~500-1000 chars) into the critic prompt alongside source file paths. keyboard-a11y-tester artifacts (trace.json, deterministic-findings.json, screen-reader-census.json) exceed the inject budget — pass their file paths instead; the critic's Phase 0 knows the format and its calibration rules.
• Size budget rule: Output > 2K chars → write to file, next agent reads. Output ≤ 2K chars → inject into prompt.

Mode 1 — Full Lifecycle

Invocation: /a11y-workflow full <target>

The main session follows these steps sequentially. Do NOT spawn all agents at once — each step's output informs the next.

Step 1: Scout

Agent(subagent_type="a11y-scout", model="haiku", prompt="
  Discover and inventory the accessibility state of: <target>
  Return: file paths, component type, existing ARIA attributes, estimated complexity.
  Keep output under 1500 chars — structured summary only.
")

Step 2: Plan

Agent(subagent_type="a11y-planner", model="opus", prompt="
  Design accessibility for the following component.
  Scout recon: <inject scout output>
  Source files: <file paths from scout>
  Write the plan to docs/a11y-plans/YYYY-MM-DD-<feature>-a11y-plan.md
")

Step 3: Critique the Plan

Agent(subagent_type="a11y-critic", model="opus", prompt="
  Review this accessibility plan for gaps before implementation.
  Plan file: <path written by planner>
  Source files: <file paths from scout>
  Flag perspective alarm levels (LOW/MEDIUM/HIGH) for each of the 7 perspectives.
")

Step 4: Perspective Audit (conditional)

Only if the critic flags any perspective at MEDIUM or HIGH alarm:

Agent(subagent_type="perspective-audit", model="opus", prompt="
  Deep review from escalated perspectives.
  Escalated perspectives and findings: <extract from critic output>
  Source files: <file paths>
")

Step 5: Return to User

Present the plan + critique + perspective audit findings. User revises and implements.

Step 6: Test (after implementation)

Invoke the /a11y-test skill, routing by target kind:

• Component/widget with (or needing) codified tests → npx playwright test .spec.js + axe-core scans (the skill's primary path).
• Component announcement/name/reading-order behavior (pre-deploy, no URL) → virtual-screen-reader assertions in the project's own unit suite, alongside the .spec.js lane — light-DOM components only (shadow roots are invisible to it), persistent-container pattern for live regions, never fake timers, never as keyboard evidence. See the a11y-test skill's component section.
• Live URL + user journey ("can a keyboard-only or screen-reader user complete X on this page?") → keyboard-a11y-tester: batch crawl for recon, then a driven serve/step session for interaction evidence. The main session drives the serve/step loop directly — it is a CLI, not an agent, so depth-1 is preserved. Calibration: batch-mode 4.1.3 findings are prompts to drive, never failures.

All lanes produce evidence for Step 7.

Step 7: Critique the Implementation

Agent(subagent_type="a11y-critic", model="opus", prompt="
  Review this implementation for accessibility design issues.
  Source files: <file paths>
  Test results summary: <inject test output summary>
  keyboard-a11y-tester artifacts (if produced): <paths to trace.json / deterministic-findings.json / screen-reader-census.json>
  virtual-screen-reader results (if produced): <inject spoken-phrase log slices + tool version + test file paths — logs are small enough to inject directly>
")

Step 8: Perspective Audit (conditional)

Same as Step 4 — only if critic flags MEDIUM/HIGH alarms.

Step 9: Return to User

Present implementation critique + perspective audit findings. User fixes and re-tests.

Mode 2 — Step Dispatcher

Invocation: /a11y-workflow step <step-name> <target>

User drives each step manually. The skill spawns the appropriate agent for the requested step.

Step Name	Agent	Model	What It Does
scout	a11y-scout	haiku	Discover files, inventory ARIA state
plan	a11y-planner	opus	Design accessibility (pass prior recon if available)
critique	a11y-critic	opus	Review plan or implementation
test	a11y-test skill	n/a	Run Playwright + axe-core; virtual-screen-reader assertions for component announcement targets; keyboard-a11y-tester journey audit for live-URL targets
audit	perspective-audit	opus	Deep perspective review (specify --perspectives to limit)

Examples

/a11y-workflow step scout src/components/Modal.tsx
/a11y-workflow step plan src/components/Modal.tsx
/a11y-workflow step critique src/components/Modal.tsx
/a11y-workflow step audit src/components/Modal.tsx --perspectives keyboard,cognitive

Triage Mode (Cost-Sensitive)

For cost-sensitive runs, add --triage to critique steps:

/a11y-workflow step critique --triage src/components/Modal.tsx

This spawns the critic at Sonnet first, reads the structured output, and checks escalation signals:

• CLEAN verdict (no bugs found) → re-run at Opus (false positive risk)
• ADVERSARIAL pattern / ambiguous tradeoff → re-run at Opus (verdict calibration)
• Low-confidence CRITICAL finding → re-run at Opus (severity calibration)
• No verdict emitted → re-run at Opus (model budget exhausted)

Perspective audit escalation (MEDIUM/HIGH alarm) always runs at Opus regardless of triage mode.

Benchmark Validation

Phase 1 benchmark (8 hard fixtures via Claude Code subagents, 2026-05-19):

Tier	FLAWED (5)	ADVERSARIAL (3)	Total
Opus	5/5 PASS	3/3 PASS (best-tier verdicts)	8/8
Sonnet-think	inherited from Haiku (pass)	resolved Haiku failures (acceptable verdicts)	8/8
Haiku	5/5 PASS	0/3 (wrong verdicts)	5/8

Opus achieves best-tier verdict quality on every ADVERSARIAL fixture on the first pass. This is the measured basis for Opus-default routing.