Agents

GAIA ships nine sub-agents (opens in a new tab) in .claude/agents/. You never start one yourself: a workflow starts each one when it needs it. Each sub-agent starts with a fresh context, so a reviewer judges the work without the reasoning of the session that wrote it, and its reading stays out of your session’s context. Each agent uses a fixed model and runs at your session’s /effort level, so a low-effort session audits at low and a high one at high. To fix the level on one machine, set the CLAUDE_CODE_EFFORT_LEVEL environment variable; see Effort. Each agent can use only the tools listed in its definition, which keeps what it starts with small.

Agent	Model	Started by	Edits files?
code-audit-frontend	Opus	the audit loop	No
code-audit-github-workflows	Opus	the audit loop	No
audit-rule-specialist	Haiku	code-audit-frontend	No (read-only)
audit-refuter	Sonnet	code-audit-frontend	No (read-only)
audit-loop-unit	Opus	the merge workflow	Commits fix rounds
audit-light-reviewer	Sonnet	the audit loop, for a light review	No (read-only)
worthiness-evaluator	Opus	the tdd skill	No
uat-fidelity-judge	Opus	a SPEC plan’s orchestrator	Writes its verdict file only
fitness-judge	Sonnet	/gaia-fitness	No (read-only)

The Code Audit Team

The audit before each merge is done by a team. Each member is responsible for the files that match its patterns in .gaia/audit-ci.yml, and a pull request is reviewed by every member whose files it changes. Members only report problems. A separate fixer makes the repairs, and a scripted check confirms each repair. Every finding is graded Critical, Major, or Minor. See Code Audit Team for the member list, approvals, and the loop.

code-audit-frontend

The default member. Responsible for the app and its tooling: frontend/app/**, tests, Storybook (opens in a new tab) and Playwright (opens in a new tab) trees, manifests, build and lint configs, root tooling such as .npmrc, and frontend/.claude/**. It reviews what lint and types cannot: security (a top priority), performance, how well the code fits the architecture, edge cases, accessibility, and maintainability. It also flags slow nested lookups (one loop inside another) that are split across two components or functions, where they are easy to miss.

Line-by-line rule checks go to audit-rule-specialist agents, one per area: React patterns and accessibility, TypeScript (opens in a new tab) and architecture, and translations. Library-specific rules live in frontend/.claude/agents/code-audit-frontend/: cn, Conform (opens in a new tab), the form components, React buckets, react-i18next, and shadcn (opens in a new tab). It also runs React Doctor (opens in a new tab), Knip (opens in a new tab), and a dependency security advisory check, and merges their output into its report in a Tooling table. Those findings are advisory: they never block its approval.

Before it reports a Critical or Major finding, an audit-refuter tries to disprove it. A finding that does not hold up is dropped or downgraded.

If a specialist or refuter cannot start because Claude Code has not loaded its agent type (a session started before an update that added it), code-audit-frontend does that review itself and says so in its report. Restart Claude Code to load the new types.

audit-rule-specialist

Checks changed files against the line-level rules for one area and reports every violation, graded and tagged with a confidence. It starts only when the change has files for its area:

• React patterns and accessibility: any changed .tsx file.
• TypeScript and architecture: any changed .ts or .tsx file, language files included.
• Translations: a changed language file under frontend/app/languages/, or a changed file that calls the translation functions (useTranslation, <Trans, i18n.t(, or t().

It is given the paths of the library rule files for its area and reads each one in full. It edits nothing. Its reply ends with a Files reviewed count, so a specialist that stopped early is caught and run again instead of being read as clean.

audit-refuter

Tries to disprove one Critical or Major finding from code-audit-frontend. It reads the flagged line, the code that calls it, and the tests that cover it. It can overturn the finding only with concrete evidence: a guard at a file:line that stops the problem, a test that already checks the right behavior, or proof the failing path cannot be reached. Without that, the finding stands. It edits nothing.

code-audit-github-workflows

Responsible for .github/workflows/*.yml and .github/actions/**/*.yml. Reviews workflow YAML for script injection, unsafe pull_request_target use, unpinned third-party actions, over-broad permissions, and secret handling.

audit-loop-unit

Runs a batch of audit rounds outside your main session. It starts the members, the fixer, and the checker, runs the Quality Gate, commits and pushes each round’s fixes, and returns a short report. Your session keeps only that report, so a long audit does not fill its context. It never merges and never posts GAIA-Audit; the main session does both. It starts the members as agents of its own, and the members start their specialists and checkers one level below that. This nesting needs Claude Code 2.1.287 or later.

audit-light-reviewer

Reviews a small change made since a member’s last full review, for members that turn this on with light_review: true in .gaia/audit-ci.yml. light_line_cap sets the largest change that qualifies (at most 50 lines), and light_hard_full lists patterns that always get a full review. Read-only. Whenever GAIA cannot confirm a change qualifies, the full member runs instead. To turn it on for a member, ask Claude:

Turn on light review for the <member> Code Audit Team member, with a line cap of <n>, and make <paths> always get a full review.

It also takes the first review of a small, purely presentational change, before any member has read the branch. A script admits only presentational shapes (static text, swapping one HTML tag for another, static class changes, translation text with the same keys and placeholders, story args: values). See Light review.

Tests and acceptance

How these two fit into building with tests is described in Test-driven development.

worthiness-evaluator

The advisory reviewer for tests the RED gate does not cover: stories, component interaction tests, and Playwright tests. The tdd skill starts it in a fresh context once the tests pass, since the test’s author would share its own blind spots. It reads only the tests the work changed plus the test files next to them, and reads source code only to judge whether a test goes through the public interface. It edits nothing.

It judges each test on honesty and worthiness (see the worthiness review) and returns one verdict per test: keep, fix, or delete. Every fix or delete carries evidence: the defect for a fix, and for a delete the redundant assertion and the test that already covers it. A delete whose cited assertion it cannot find in the sibling file is downgraded, never proposed. The tdd skill records each verdict, keyed to the test’s current content, and the worthiness verdict gate checks that record at merge.

uat-fidelity-judge

Before a SPEC plan’s pull request is audited, it reads the SPEC and each generated Playwright acceptance test (UAT), and judges whether each test body still checks what the SPEC promised. Differences in wording, selectors, or layout do not count; a weaker assertion or a changed user flow does, and an unclear case is judged as diverging. It writes one JSON verdict file and nothing else. A failure stops the plan. See UAT specs.

Integration health

fitness-judge

The part of /gaia-fitness that makes judgment calls instead of fixed checks: whether descriptions say enough, whether two skills would trigger on the same request, whether a rule’s paths: patterns fit what it covers, and whether a skill uses its terms consistently. Read-only, and it never changes the grade.