/gaia-review-a11y

What it does

Pre-merge accessibility gate reviewing code for WCAG 2.1 compliance: semantic HTML, ARIA usage, keyboard navigation, color contrast, and screen reader support. Conditional gate -- only fires when the project has UI components configured.

When to use it

• A story with UI changes is in review status. The project must have compliance.ui_present set to true.

Prerequisites

• Story must be in review status (for story-based reviews). The story file must exist under .gaia/artifacts/implementation-artifacts/.

Orchestration mode

When /gaia-review-a11y starts in subagent mode (Mode A -- the default), the framework emits a one-shot warning to your conversation. The warning text:

────────────────────────────────────────────────────────────────────────────
GAIA orchestration: running in subagent mode (Mode A)

The skill you're invoking belongs to a class (heavy-procedural or
conversational) whose output benefits from cross-step context. Mode A
dispatches each sub-agent in its own forked context, so context may
be lossy between steps — sub-agents return summaries, not full reasoning.

For the full-fidelity experience, enable Mode B (Agent Teams):
  1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment.
  2. Add orchestration.mode: team to .gaia/config/project-config.yaml.

Mode B uses persistent teammates that preserve in-conversation state
across dispatches.

This warning is shown once per session.
────────────────────────────────────────────────────────────────────────────

Why Mode B is better for this command

The /gaia-review-a11y skill declares orchestration_class: heavy-procedural in its SKILL.md frontmatter. Heavy-procedural skills produce output that benefits from cross-step context -- under Mode A every sub-agent dispatch runs in its own forked context and can only return a summary back to the orchestrator, losing the full reasoning trace of every prior step. Mode B uses persistent teammates that retain in-conversation state across dispatches, so each agent's contribution can build on what was said before instead of receiving only a summary.

How to enable Mode B

Both steps are required. If either is missing, the framework falls back silently to Mode A and the warning fires again on the next session.

Step 1 -- set the environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Add this to your shell rc file to persist across sessions, or set it in Claude Code's settings.json.

Step 2 -- add the YAML block to .gaia/config/project-config.yaml:

orchestration:
  mode: team

One-shot semantics

The warning is emitted once per Claude Code session. A marker file at _memory/checkpoints/orchestration-warning-shown.<session-id> suppresses the warning for the rest of the session. Starting a new session re-emits the warning once.

How to invoke

/gaia-review-a11y E3-S7
/gaia-review-a11y src/components/LoginForm.tsx

What it does step by step

1. Resolve target Locates the story file or review target.
2. Run deterministic analysis Executes per-stack tooling to collect evidence.
3. Apply LLM judgment Performs semantic review on top of the deterministic evidence.
4. Compute verdict The verdict (APPROVE, REQUEST_CHANGES, or BLOCKED) is computed by the verdict resolver -- the LLM does not determine the verdict.
5. Update Review Gate Records the verdict in the story's Review Gate table.

Inputs

Outputs

A review report is written to .gaia/artifacts/implementation-artifacts/. The story's Review Gate row is updated with PASSED or FAILED.

Example session

> /gaia-review-a11y E3-S7

Resolving story E3-S7...
Running deterministic analysis...
Applying semantic review...

Verdict: APPROVE
Review Gate updated: PASSED

0 critical, 1 warning, 2 suggestions.

What to run next

• /gaia-review-all -- run all remaining reviews.
• /gaia-check-review-gate -- check if all reviews pass.

Troubleshooting

"Story must be in review status"

Run /gaia-dev-story to implement and transition the story first.

"Story file not found"

Verify the story key and check that the file exists under .gaia/artifacts/implementation-artifacts/.

I keep seeing the GAIA orchestration warning every time I start this command

The warning is shown once per session, so if it fires again that's a new session -- not a per-skill repeat. If you want to silence it entirely, enable Mode B (full-fidelity orchestration via Agent Teams). Both of these conditions must be true:

• echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS returns 1 (not empty)
• .gaia/config/project-config.yaml contains:

  orchestration:
    mode: team

If either is missing the framework silently uses Mode A and re-emits the warning each session.

Related commands