A11Y Workflow

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

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) typically exceed the inject budget — check against the threshold below; when they do, the orchestrator routes them through a11y-evidence-reader (below) rather than reading them wholesale — never the critic itself. The critic's Phase 0 covers any targeted re-read via the passed paths.
• Evidence-reader delegation (the inject budget): when a step's evidence artifacts exceed 8K measured tokens (≈32KB on disk, chars/4), the orchestrator spawns a11y-evidence-reader (haiku extraction, sonnet if interpretation is needed, never opus) instead of reading the corpus itself, then hands the digest plus the original artifact paths to the critic/planner — which never spawns the reader itself (depth-1 holds). Findings cite digest handles; a targeted re-read routes back through the orchestrator, not a wholesale re-read. Rationale: 8K ≈ 2× the reader's own ≤4K-token digest ceiling (a11y-evidence-reader.md) — past that ratio delegation nets real compression. Tunable pending Phase 3 rows (docs/plans/2026-08-24-context-utilization-plan.md).
• Size budget rule: Output > 2K chars → write to file, next agent reads. Output ≤ 2K chars → inject into prompt. Exception: the evidence-reader's digest. The reader's Write/Edit tools are blocked by design, so its digest is exempt from this rule and injected whole regardless of size. If the digest opens with BUDGET EXCEEDED, the orchestrator — not the reader — writes it to a file verbatim and passes the path to the next agent; it never re-summarizes the digest to force it under budget.

Skill-Improvement Capture (gate-exit discipline)

A passive collection surface (a side file nobody is required to populate) is not a mechanism — engagements that set one up have produced nothing from it. Capture works only when it is a required field of a step that already has to run, not an optional extra step of its own. Every "Return to User" gate exit in Mode 1 (Steps 5 and 9 below) and every single-step dispatch in Mode 2 carries this requirement: before presenting findings, state one line — either "No skill-improvement candidate observed this run" or a one-line candidate naming the source step and the recurring gap it points at (a pattern a scout/planner/critic/tester kept re-deriving, a routing table that under- or over-fired, a false positive or false negative worth a fixture). This is not a document to maintain between runs; it is output the gate exit cannot skip.

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 4b: Role Audit — Design Mode (optional)

If user requests role-specific review, or the plan affects multiple team roles:

Agent(subagent_type="a11y-role-auditor", model="opus", prompt="
  Review this accessibility plan from team responsibility perspectives.
  Mode: design
  Roles: visual-design, ux-design (or all if requested)
  Plan file: <path>
  Source files: <file paths>
")

Step 5: Return to User

State the skill-improvement-capture line (see above), then present the plan + critique + perspective audit + role 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).
• Baseline sweep across a list of URLs (spot-check set, sampled route list, no .spec.js per page) → references/baseline-url-scan.mjs, with --census for DOM-census heuristics (empty paragraphs, autocomplete-absence, duplicate ids — reported under their own census key, never mixed into axe violations) and --alt-snapshot for a diffable per-page alt-text map. Detector output only, same as the axe-core lanes. The scanner's own detection coverage is regression-tested in evals/suites/baseline-scan/ (fixture pair + expected-rules.json + run_rig.sh) — that rig verifies the scanner still catches its known defect classes, it does not substitute for running the scanner against the target under test.
• Component announcement/name/reading-order behavior (pre-deploy, no URL) → virtual-screen-reader assertions in the project's own unit suite or Storybook play functions, 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 — match each finding's evidence type against the a11y-test Verification evidence contract before treating a fix as verified.

Step 6b: Role Audit — Code Mode (optional)

If user requests role-attributed findings, or findings need to be routed to specific team members:

Agent(subagent_type="a11y-role-auditor", model="opus", prompt="
  Review this implementation from team responsibility perspectives.
  Mode: code
  Roles: all (or specific roles if requested)
  Source files: <file paths>
  Test results summary: <inject test output summary>
")

Step 6c: Digest Evidence (conditional)

If Step 6's test artifacts exceed the inject budget (see "Context Passing Between Agents" above):

Agent(subagent_type="a11y-evidence-reader", model="haiku", prompt="
  Question: <what the critic must adjudicate>
  Artifacts: <paths>
  question_source: orchestrator, /a11y-workflow Step 6c
")

Escalate to model="sonnet" when interpretation is genuinely needed (schema not covered by a recipe, conflicting artifacts, an evidence class that isn't obvious from the question, vision-mode verdicts). Never opus — a question needing opus-tier judgment is not an extraction question; hand the reader's handles to the opus-tier critic instead. Pass the returned digest plus the original artifact paths into Step 7 — the coverage note travels with it, and a targeted re-read routes back through the orchestrator, never a wholesale re-read of the corpus.

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): <if Step 6c ran: the digest + coverage note from Step 6c, plus the original artifact paths. Otherwise: raw 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

State the skill-improvement-capture line (see above), then 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. Each dispatched step's own return to the user carries the skill-improvement-capture line before its findings — the requirement is per gate exit, not per mode.

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
/a11y-workflow step roles src/components/Modal.tsx --roles visual-design,ux-design

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):

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