argus-qa

Argus — All-Seeing QA Guardian for Claude Code.

A zero-dependency npm package that installs the Argus autonomous QA agent directly into your project's .claude/ directory, making it immediately available in Claude Code — including on the Max plan.

Argus performs a complete, six-phase QA sweep: it reads your codebase, explores the running application with Playwright, harvests your GitHub/Jira tickets, writes professional Acceptance Criteria and Manual Test Cases, updates the tracker, and validates everything with a final Playwright pass.

Quick Start

# In your project root
npx argus-qa init

Then open Claude Code and say:

Run Argus. App is at http://localhost:3000, using GitHub Issues.

That's it. Argus takes over from there.

Installation

You don't need to install the package globally. npx argus-qa init downloads and runs it in one step.

If you prefer a local dev dependency (so your team always runs the same version):

npm install --save-dev argus-qa
npx argus-qa init

Or globally, if you want argus-qa available in every project:

npm install -g argus-qa
cd your-project
argus-qa init

What init does

Running init creates the following files in your project, which Claude Code reads automatically on startup:

.claude/
├── agents/
│   └── argus.md                          ← the main orchestrator agent
└── skills/
    └── argus/
        ├── 00-project-intelligence.md    ← Phase 1: codebase analysis
        ├── 01-playwright-explorer.md     ← Phase 2: visual app exploration
        ├── 02-ticket-harvester.md        ← Phase 3: ticket fetch + Playwright probes
        ├── 03-qa-documentation.md        ← Phase 4: ACs, test cases, bug reports
        ├── 04-ticket-updater.md          ← Phase 5: GitHub/Jira updates
        └── 05-playwright-validator.md    ← Phase 6: Playwright validation pass

Claude Code discovers agents in .claude/agents/ and skills in .claude/skills/ automatically — no additional configuration is needed.

Commands

argus-qa init

Installs Argus into the current project. Safe by default: files that already exist are skipped. Use --force to overwrite.

npx argus-qa init
npx argus-qa init --force     # overwrite existing files
npx argus-qa init --dry-run   # preview without writing anything
npx argus-qa init --yes       # skip confirmation prompt (CI-friendly)

argus-qa update

Re-installs all files using the latest version bundled in the package. Run this after upgrading argus-qa.

npx argus-qa update
npx argus-qa update --dry-run
npx argus-qa update --yes

argus-qa status

Shows which files are installed, missing, or outdated compared to the current package version.

npx argus-qa status

Example output:

  ✔ .claude/agents/argus.md  (up to date)
  ✔ .claude/skills/argus/00-project-intelligence.md  (up to date)
  ↑ .claude/skills/argus/03-qa-documentation.md  (outdated — run argus-qa update)
  ✖ .claude/skills/argus/05-playwright-validator.md  (not installed)

argus-qa uninstall

Removes all Argus files. Does not touch the .claude/ directory itself, so other agents and skills you have installed are not affected.

npx argus-qa uninstall
npx argus-qa uninstall --dry-run
npx argus-qa uninstall --yes

Triggering Argus in Claude Code

Once installed, Argus is triggered by natural language phrases in Claude Code. You don't need to use a specific command syntax — Claude Code recognises the intent from context.

The following phrases (and variations) will activate Argus:

• "Run Argus. App is at http://localhost:3000, using GitHub Issues."
• "Argus — full QA sweep. Jira project KEY. Staging URL: https://staging.myapp.com"
• "Start a full quality assurance run with Argus"
• "qa the project", "full qa sweep", "audit the project"

Argus will ask a few setup questions if it can't infer what it needs (app URL, tracker type, credentials for Jira), then proceed through its six phases.

What Argus Produces

Every run writes to .argus/run-<TIMESTAMP>/ in your project root, with a latest symlink for easy access:

.argus/
└── run-20250305T120000/
    ├── 00-project-intel/
    │   ├── BUSINESS_LOGIC.md      ← every business rule, user role, and workflow
    │   ├── ARCHITECTURE.md        ← tech stack, API surface, domain model
    │   ├── TEST_COVERAGE.md       ← existing coverage + gap analysis
    │   └── CODEBASE_MAP.md        ← annotated directory structure
    ├── 01-playwright-exploration/
    │   ├── EXPLORATION_REPORT.md  ← every route and feature found
    │   └── screenshots/
    ├── 02-ticket-analysis/
    │   ├── TICKET_OVERVIEW.md
    │   └── tickets/<ID>/
    │       ├── TICKET_DETAIL.md   ← enriched with Playwright findings
    │       └── screenshots/
    ├── 03-qa-documentation/
    │   └── tickets/<ID>/
    │       ├── ACCEPTANCE_CRITERIA.md
    │       ├── MANUAL_TEST_CASES.md
    │       └── BUG_REPORT.md      ← only present when bugs were found
    ├── 04-tracker-updates/
    │   └── UPDATE_LOG.md
    └── 05-validation/
        ├── VALIDATION_REPORT.md
        └── screenshots/

The Six Phases

Phase 1 — Project Intelligence reads the entire codebase (source files, tests, config, API definitions, migration files) and produces four structured documents covering business logic, architecture, test coverage gaps, and a codebase map. This gives Argus a foundation to interpret everything that follows.

Phase 2 — Playwright Explorer opens a real Chromium browser, creates a test user through the app's own registration flow, navigates every discoverable route, fills out forms, and captures screenshots. It behaves exactly like an exploratory tester on their first day with the product.

Phase 3 — Ticket Harvest fetches all open tickets from GitHub Issues and/or Jira, then fires a targeted Playwright session per ticket — navigating to the relevant feature and attempting to observe or reproduce the reported behavior. This phase spawns parallel sub-agents for speed.

Phase 4 — QA Documentation is the intellectual core of the run. Per-ticket parallel sub-agents each read all Phase 1–3 context and produce three professional QA documents: Acceptance Criteria in Given/When/Then format, step-by-step Manual Test Cases with priority levels, and Bug Reports for any defects discovered along the way.

Phase 5 — Tracker Updates posts the Phase 4 documentation to GitHub or Jira as structured comments, adds QA labels, and creates new bug tickets for anything Argus found. Argus always shows you the full update manifest and waits for explicit approval before posting a single thing to the tracker.

Phase 6 — Playwright Validation converts the written test cases into executable Playwright scripts, runs them against the live application, and produces a validation report that distinguishes between application bugs, documentation inaccuracies, and environment issues.

Approval Checkpoints

Argus pauses for your explicit approval at five points during a run. This design is intentional: the agent can discover a lot of information autonomously, but humans stay in control of all decisions that have real-world effects (like posting to a tracker or writing test documentation that will guide a team).

The five checkpoints are after Phase 1 (before Playwright exploration), after Phase 2 (before ticket analysis), after Phase 3 (before writing QA docs), after Phase 4 (before touching the tracker — also shows the full update manifest), and after Phase 6 (final report).

You can stop after any checkpoint without losing work — all prior-phase documents are already written.

Prerequisites

The following tools need to be available in your environment before running Argus. Most will already be present in a typical development setup.

Node.js 18 or newer and npm are required for Playwright. Playwright itself is installed automatically by Argus if it isn't already present.

Git — the project directory should be a git repository.

GitHub CLI (gh) authenticated via gh auth login, if you are using GitHub Issues as your ticket tracker. Verify with gh auth status.

Jira CLI or a Jira MCP connection, if using Jira.

A running application — Argus needs to be able to open a browser and load your app. Provide the base URL when invoking Argus (e.g., http://localhost:3000 or your staging URL).

Works with Claude Code Max

Argus uses Claude Code's sub-agent spawning (the Task tool) to run Phase 3 and Phase 4 work in parallel. This works on the Max plan and any Claude Code subscription that supports multi-agent workflows. The agent file declares tools: Task, Bash, Read, Write, Edit, Glob, Grep, mcp__github, mcp__jira — Claude Code will use whichever of these are available in your environment.

.gitignore recommendations

You can either commit .argus/ to give your team a permanent, searchable QA history, or ignore it to keep it local. If you want to keep the text documents but exclude large binary files:

# Keep text docs, exclude screenshots and video recordings
.argus/**/screenshots/
.argus/**/flows/

# Or ignore the entire audit directory
.argus/

Programmatic API

The package also exposes a small programmatic API for build scripts and monorepo tooling:

const argus = require('argus-qa');

// Install silently (no prompts)
const result = argus.install({ force: true });
console.log(`Installed ${result.installedCount} files`);

// Check status
const { missing, outdated } = argus.status();
if (missing.length > 0) {
  console.warn('Argus files missing — run argus-qa init');
}

// Remove all files
argus.uninstall();

License

MIT