qa-agent

A standalone, code-aware QA agent for Next.js apps, built on the Claude Agent SDK.

Run it inside your repo — it auto-detects the app. No pointing, no config required.

It:

1. Understands the app — deterministically scans routes (app/ + pages/) and extracts per-page structure (components, data access, forms, links, buttons, testids) with ts-morph.
2. Documents every page as markdown (qa-docs/pages/<route>.md): purpose, code, content, data/state, and user-facing affordances.
3. Derives user flows — "what can a user do" — into qa-docs/flows/*.md + .qa-agent/flows.json.
4. Authors Playwright E2E tests from those flows (happy path + edge cases) into e2e/, then installs Playwright into your repo, runs the specs, and self-heals them.
5. Per sprint: takes a ClickUp or Jira task id, finds the related GitHub PR(s), reads the diff, and writes/extends edge-case tests for the feature.

Methodology (deterministic scan → LLM synthesis, never invent paths) is adapted from Understand-Anything.

Install (CLI build)

git clone <this repo> && cd qa-agent
pnpm install
pnpm build          # compiles src/ -> dist/ (the `qa` bin)
npm link            # makes `qa` available globally  (or: npm i -g .)

Then authenticate once: either set ANTHROPIC_API_KEY (env or a .env in your app repo) or be logged in to Claude Code. For the sprint phase, set GITHUB_TOKEN (or use the gh CLI), CLICKUP_API_TOKEN (+ CLICKUP_TEAM_ID), and JIRA_BASE_URL/JIRA_EMAIL/JIRA_API_TOKEN.

Usage

cd ~/code/my-next-app      # your Next.js repo

qa understand              # scan -> .qa-agent/understanding.json (+ qa-docs/OVERVIEW.md)
qa document                # -> qa-docs/pages/*.md
qa flows                   # -> qa-docs/flows/*.md + .qa-agent/flows.json
qa tests                   # -> e2e/*.spec.ts (installs Playwright, authors + self-heals)
qa run                     # run the Playwright suite (boots your dev server)
qa ci                      # write .github/workflows/qa-e2e.yml + a committable playwright.config.ts
qa sprint CU-abc123        # ClickUp/Jira task id -> PR diff -> edge-case e2e tests
qa all                     # full pipeline

It auto-detects: the repo root, App vs Pages router, package manager, dev command + port (→ baseUrl), and the GitHub owner/repo from your git remote. qa understand works without any LLM auth (it just skips the overview), so you can verify the scanner instantly.

Outputs written into your repo: qa-docs/ (docs — commit these), e2e/ (tests — commit these), .qa-agent/ (machine state — auto-gitignored).

Optional overrides — qa.config.json (repo root)

{
  "router": "auto",                       // auto | app | pages
  "baseUrl": "http://localhost:3000",
  "devCommand": "pnpm dev",
  "model": { "heavy": "claude-opus-4-8", "bulk": "claude-sonnet-4-6" },
  "github": { "owner": "me", "repo": "my-next-app" },
  "output": { "docsDir": "qa-docs", "e2eDir": "e2e", "stateDir": ".qa-agent" }
}

If your repo already has a playwright.config.*, qa-agent uses it; otherwise it generates one in .qa-agent/.

How it works

• src/detect.ts + src/config.ts — find the repo from cwd; config file is optional.
• src/scan/* — deterministic facts (routes + structure). Authoritative; the agent never re-scans.
• src/agent/* — runPhase() wraps the SDK query() (bypassPermissions, per-phase tools, outputFormat for structured flows); tools.ts exposes get_task/find_prs/get_pr_diff.
• src/phases/* — one module per phase.
• src/integrations/* — ClickUp/Jira REST + GitHub (Octokit, gh fallback).
• src/playwright.ts — writes a config into the target repo + ensures Playwright is installed.
• src/fingerprint.ts — skips unchanged pages/specs across runs.

Dev (without installing globally)

pnpm dev understand        # = tsx src/cli.ts understand, run from inside a target repo

Roadmap

More stacks (Vite/React Router, Vue) via a pluggable scanner; CI trigger; visual/a11y checks.