a11y-bee

After this page you can start an a11y-bee run from Slack or the CLI, scope it so it only touches the right files, and read the PR it opens. The contract holds here as everywhere: No human writes code. A human always reviews.

What it does

a11y-bee is an accessibility specialist. It audits a repo (or a scoped part of one) against WCAG 2.1 AA, fixes the issues that are mechanical and safe to fix automatically, and lists everything else in the PR for a human. It runs on a fixed action budget in three phases:

The budget is deliberate: a PR with 5 fixes and a thorough report beats 20 fixes that never get pushed. If the scan finds more than it can fix, the overflow lands in the PR description as remaining issues; it isn't silently dropped.

Auto-fixed: missing alt text, form label associations (htmlFor, aria-label, aria-labelledby), missing or incorrect ARIA roles/attributes, missing lang on the html element, empty links and buttons, decorative images missing aria-hidden="true" or alt="".

Reported only (needs a human): tab order and focus management, complex interaction patterns (modals, carousels, accordions), content rewriting for plain language, layout or navigation restructuring, heading hierarchy changes that span multiple components.

When to use it

Use a11y-bee when you want a scoped accessibility pass on a web project: before a client audit, after a big UI change, or as periodic hygiene. Always scope the ticket ("homepage only", "the checkout flow"): the bee is instructed to stay strictly inside the stated scope and budgets its actions around it. For anything that isn't a straight audit-and-fix, like "rebuild the nav to be keyboard-accessible", send the task to the swarm agent instead (just don't name a bee, see from Slack).

Starting a run

From Slack, name the bee and include the repo token:

@cube-agent a11y-bee repo:3sidedcube/3sc-website Audit the homepage for accessibility issues.

From the CLI (local dev):

./scripts/run-agent.sh \
  --recipe a11y-bee \
  --repo "https://github.com/3sidedcube/3sc-website" \
  --ticket "Audit homepage accessibility only, do not touch other pages" \
  --scan-scope "src/app/page.tsx"

--scan-scope is optional (defaults to full) and narrows the scan to a path. You can also pick a11y-bee from the Run a bee form on the dashboard, or trigger it from Jira by adding an a11y-bee label before moving the ticket to the "AI" status. An unlabelled ticket goes to the swarm agent.

What the PR looks like

The bee pushes a branch named agent/a11y-fixes-<short-desc> (never commits to the default branch) and opens a PR containing:

• A summary of what was fixed, counted by category.
• A "Manual Fix Required" section: for each remaining issue, the file, line, WCAG criterion, severity, and guidance on how to fix it.

If the in-scope scan finds zero issues, no PR is opened; the run ends with a NO_ISSUES_FOUND verdict instead of an empty PR. Every run ends with a machine-readable verdict block (SUCCESS, NO_ISSUES_FOUND, or BLOCKED_PUSH_REJECTED) that the settlement layer uses to report the outcome back to your thread.

Limits

• It fixes at most 10 issues per run. Big backlogs take multiple scoped runs.
• It won't restructure interactions, focus order, or navigation; those are reported for a human.
• It never touches CI/CD configs, deployment files, or environment variables.
• The ticket text is treated as untrusted data: instructions embedded in a ticket (e.g. "ignore the contrast standard") are refused and noted in the PR.
• WCAG 2.1 AA is the floor. A green run is not a completed accessibility audit; manual testing (screen readers, keyboard-only) still applies.