QA Agents

Nucleus uses two AI-powered QA agents that automatically review every pull request. They run as GitHub Actions jobs and create issues for any findings.

Agents

Agent	Brief	Focus
Technical Quality	apps/agents/tech/agent.md	TypeScript health, security, duplication, structure
UX Quality	apps/agents/ux/agent.md	Accessibility, component conventions, layout patterns

Both agents receive a dynamically generated brief (from the agent markdown + PR diff context) via stdin and output their findings as GitHub issues.

CI Workflow

The workflow is defined in .github/workflows/qa-agents.yml and triggers on pull requests to main.

Steps

1. Setup — checkout, install pnpm + Node 22, install deps
2. Ensure QA labels exist — runs scripts/setup-labels.sh to create issue labels if missing
3. Validate branch name — rejects branches with unsafe characters (security: github.head_ref is attacker-controlled)
4. Build workspaces — pnpm --filter @nucleus/app build and pnpm --filter @nucleus/admin build
5. Generate brief — injects PR number and diff context into the agent brief markdown
6. Run agent — pipes brief to claude --print with a 600-second timeout

Each agent runs as a separate job with a 15-minute timeout.

Running Locally

# Technical review against a specific PR
scripts/run-tech-qa.sh 144

# UX review against a specific PR
scripts/run-ux-qa.sh 144

# Local-only run (prints report instead of creating issues)
scripts/run-tech-qa.sh local
scripts/run-ux-qa.sh local

Issue Severity Levels

Agents categorise findings by priority:

• P1 — Must fix before merge (build failures, security issues, broken accessibility)
• P2 — Fix in follow-up (type safety, duplication, convention violations)
• P3 — Housekeeping (pre-existing issues, minor cleanup)

Adding a New Agent

1. Create apps/agents/<name>/agent.md with the review brief template
2. Create scripts/run-<name>-qa.sh for local execution
3. Add a new job in .github/workflows/qa-agents.yml following the existing pattern