Three-phase QA orchestrator that scans the codebase for quality issues using parallel subagents, presents findings for interactive triage, and applies guided fixes with individual commits.

Replaces the old qa.sh bash loop with an interactive, token-efficient approach that runs inside the user's session.

Arguments: $ARGUMENTS

--scope SCOPE — restrict scan to a directory/module (monorepo support)
--focus TEXT — boost severity of findings matching this focus area
--scan-only — report all findings, fix nothing
--auto — fix CRITICAL+HIGH, create issues for MEDIUM, skip LOW
No args — full scan with interactive triage

Step 1: Initialize

Parse arguments

Read $ARGUMENTS and determine the mode:

Default: full scan + interactive triage
--scan-only: scan and report, no fixes
--auto: automated triage (no approval gates)

Project configuration

Read .claude-toolkit.json for:
- qa.scanCategories — which scan dimensions to run
- commands.test — test command
- commands.lint — lint command
Read CLAUDE.md for project conventions
Scan .claude/agents/ for domain-specific agent files (filenames map to domains)

Scope resolution

If --scope is set:

Check if it matches a directory name in the project root
Check pnpm/npm/turbo workspace definitions for package name resolution
Set SCOPE_DIR to the resolved path — all scan agents will be restricted to this directory

Step 2: Phase 1 — Autonomous Scan

Launch ALL scan agents in parallel via the Task tool. Each agent must return concise findings (< 200 words).

Dimension	Agent (`subagent_type`)	Prompt Focus
Dead code & unused exports	`refactor-cleaner`	Find unused exports, dead code, duplicate logic
Code quality & patterns	`code-reviewer`	Review code quality, anti-patterns, error handling
Security patterns	`security-reviewer`	OWASP top 10, auth bypass, data exposure
Test coverage gaps	`planner`	Identify untested code paths and missing test files
Documentation freshness	`doc-updater`	Check if docs match current code (read-only assessment)
Incomplete features	`planner`	Find TODOs, FIXMEs, partial implementations
Build health	`build-error-resolver`	Check for build/type errors, dependency issues

Domain agent discovery: For each .md file in .claude/agents/, if the filename (minus extension) matches a relevant domain, also spawn that agent with a domain-specific scan prompt.

Direct commands: Also run test and lint commands directly via Bash tool (in parallel with agents):

Test: run the configured test command
Lint: run the configured lint command

If --scope is set, pass the scope directory to each agent and command.

Each Task call should include this instruction:

"Scan the codebase for . Return findings as a list: one line per finding with severity (CRITICAL/HIGH/MEDIUM/LOW) and a brief description. Maximum 200 words. Scope: <scope or 'entire project'>."

Step 3: Phase 2 — Interactive Triage

Merge findings

Collect all agent results and test/lint output. Merge into a unified findings table with columns:

#	Severity	Category	Finding	Source

Severity definitions

Severity	Criteria	Examples
CRITICAL	Security vulnerabilities, data loss risk, broken production	SQL injection, auth bypass, data corruption
HIGH	Failing tests, missing auth checks, broken build	Test failures, unhandled errors, build errors
MEDIUM	Code quality gaps, coverage holes, lint violations	Missing tests, code smells, outdated deps
LOW	Style nits, doc staleness, minor TODOs	Formatting, stale comments, trivial TODOs

Focus boost

If --focus is set, boost the severity of any finding whose description matches the focus text (LOW→MEDIUM, MEDIUM→HIGH).

Triage gate

If --scan-only: Print the full findings table. Done — skip Phase 3.

If --auto: Automatically triage:

CRITICAL + HIGH → mark for fix
MEDIUM → mark for GitHub issue creation
LOW → skip

Otherwise (interactive): Present the findings table to the user. For each finding (or group), ask:

Fix — apply a guided fix
Issue — create a GitHub issue with label claude-ready
Skip — ignore this finding

Step 4: Phase 3 — Guided Fix

Branch isolation

Before applying any fixes, create a dedicated branch to keep changes off the current branch:

Record the current branch name: ORIGINAL_BRANCH=$(git branch --show-current)
Create and switch to a QA branch: git checkout -b qa/<date> (e.g., qa/2026-02-15)
If the branch already exists (re-run), switch to it: git checkout qa/<date>

This ensures all fix commits land on a disposable branch. The user can review, cherry-pick, or merge at their discretion.

If not in a git repo, skip branch creation and apply fixes in-place.

Apply fixes

For each finding marked "Fix", spawn the appropriate agent:

Finding Category	Agent (`subagent_type`)
Security vulnerability	`security-reviewer`
Dead code / unused exports	`refactor-cleaner`
Test coverage gap	`tdd-guide`
Build / type error	`build-error-resolver`
Code quality issue	`code-reviewer`
Documentation staleness	`doc-updater`

Each fix agent receives:

"Fix the following issue: . Apply the minimal fix. Run tests after fixing. If tests pass, stage and commit with: fix(qa): <description>. If tests fail, revert and report."

For each finding marked "Issue":

gh issue create --title "<finding summary>" --body "<details>" --label "claude-ready" --label "from-qa-auto"

Each fix follows the cycle: apply → test → commit individually.

Step 5: Completion

Print a summary table:

QA Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Fixed:   N items
  Issues:  N created
  Skipped: N items
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Details:
  # | Action  | Finding
  1 | FIXED   | Missing null check in auth handler
  2 | ISSUE   | Test coverage gap in payment module (#123)
  3 | SKIPPED | Formatting nit in README

If all tests pass and no CRITICAL/HIGH findings remain, report success. Otherwise, note remaining items.

Write qa-report.json

Write a qa-report.json file to the project root with the full run results. This file persists across sessions and is useful for CI pipelines and re-runs.

{
  "date": "2026-02-15T14:30:00Z",
  "scope": "all",
  "focus": null,
  "mode": "interactive",
  "branch": "qa/2026-02-15",
  "findings": [
    {
      "id": 1,
      "severity": "HIGH",
      "category": "security",
      "description": "Missing null check in auth handler",
      "source": "security-reviewer",
      "action": "fixed",
      "commitHash": "abc1234"
    },
    {
      "id": 2,
      "severity": "MEDIUM",
      "category": "test-coverage",
      "description": "Test coverage gap in payment module",
      "source": "planner",
      "action": "issue",
      "issueUrl": "https://github.com/org/repo/issues/123"
    },
    {
      "id": 3,
      "severity": "LOW",
      "category": "docs",
      "description": "Formatting nit in README",
      "source": "doc-updater",
      "action": "skipped"
    }
  ],
  "summary": {
    "total": 3,
    "fixed": 1,
    "issued": 1,
    "skipped": 1
  }
}

If qa-report.json already exists, overwrite it — each run produces a fresh report.

After the summary, if a QA branch was created:

Ask the user: merge into original branch, keep as separate branch, or create a PR.
If merge: git checkout <ORIGINAL_BRANCH> && git merge qa/<date>
If PR: gh pr create --base <ORIGINAL_BRANCH> --head qa/<date>
If keep: leave the branch as-is and switch back to ORIGINAL_BRANCH.

Error Handling

Agent failures: If a Task agent fails, log the error and skip that dimension. Do not retry — the user can re-run /qa to try again.
Test failures after fix: Revert the fix (git checkout -- .) and create a GitHub issue instead.
No findings: Report a clean bill of health. No Phase 3 needed.