Agents

Agents are subagents Claude Code can spawn from the main conversation. Each agent runs in its own isolated context, performs a focused task, and reports back a single result. Agents are defined as Markdown files at .claude/agents/*.md with frontmatter that names the agent, describes when to invoke it, and pins a model.

For Claude Code’s own subagent documentation, see the Subagents reference on docs.claude.com.

code-review-audit

Path: .claude/agents/code-review-audit.md. Model: opus.

Comprehensive code review, security audit, performance analysis, and architectural assessment. Goes beyond what ESLint and TypeScript catch by reasoning about intent, data flow, and architectural fit. Mandatory before any PR merge.

When to invoke

• Before merging a PR. The pr-merge-audit-check hook blocks gh pr merge until the agent has produced a clean run for the current HEAD.
• After a substantial change or refactor, when verification beyond the quality gate is warranted.
• On request, for a focused review of the current branch.

What it reviews

• Security: injection paths, auth/authorization gaps, secret exposure, CSRF/SSRF, data leakage through loaders, timing attacks.
• Performance: N+1 patterns, unnecessary re-renders, bundle size, SSR cost in loaders, network waterfalls.
• Architecture: separation of concerns, single responsibility, dependency direction, state placement, module-level duplication.
• Robustness: missing validation, race conditions, null safety, error states, boundary conditions.
• Accessibility: keyboard reachability, semantic HTML, focus management, ARIA usage.
• Maintainability: magic values, dead code, coupling, comment quality.

The review runs in two phases. In the first phase, the main agent surfaces every candidate finding tagged with severity and confidence (coverage-first: low-confidence candidates are surfaced, not silently dropped). In the second phase, each surviving Critical or Important holistic finding is handed to a fresh-context refuter subagent; the refuter overturns a finding only with concrete counter-evidence (a specific guard, a test, or a demonstration that the failure path is unreachable). The report is not written until the adversarial pass completes.

The main agent owns every spawn: specialist subagents (React patterns, TypeScript / architecture, translation), oracle tools (react-doctor, pnpm knip --reporter json, pnpm audit --json), and the per-finding refuters. None of these spawn further (depth-1 star topology). The pnpm audit pass is the Dependency-CVE advisory: it reports high and critical findings for you to decide on and never blocks the audit marker or gh pr merge. See the dep-audit rule.

Per-phase progress breadcrumbs (scope resolved, oracles done, holistic review done, adversarial verify done, report stamped) are written to .gaia/local/audit/progress.log and surfaced in the GitHub Actions step summary.

Output

The agent produces a structured report:

• Summary: overview, overall quality, top findings.
• Critical Issues (Must Fix): security and bugs that block merge. Each finding gives path:line, the issue, and a concrete fix.
• Important Issues (Should Fix): performance and architectural concerns at scale. Same shape.
• Suggestions (Consider Fixing): refactoring and minor improvements.
• What’s Done Well: included only when there are concrete patterns worth reinforcing.

Audit marker and trailer

When the report is clean (no Critical Issues, all Important Issues resolved in the working tree), the agent stamps HEAD with a GAIA-Audit: commit trailer and writes a marker file at .gaia/local/audit/<HEAD-sha>.ok. The marker unblocks gh pr merge locally; the trailer travels with the commit through the network so CI can recognize an already-audited tree and skip its own audit run.

If findings remain, the agent does not write the marker. Address findings, commit, and re-invoke the agent on the new HEAD.