@roopesh.yadava/qa-pack

AI-powered QA agent skills for Claude Code. Drop into any product repo — get manual testing, BDD automation, accessibility audits, UI/Figma diff, bug filing, and test charters all triggered by plain English.

Install

# One-time .npmrc line needed because of the CodeArtifact default registry on 7Edge machines
echo "@roopesh.yadava:registry=https://registry.npmjs.org" >> .npmrc
npm install --save-dev @roopesh.yadava/qa-pack

On install, the postinstall script copies all skills and commands into .claude/ (git-ignored — see Git hygiene below) and creates one-time config files (CLAUDE.md, .mcp.json, cucumber.cjs, .env) if they don't already exist. It also writes the .npmrc scope entry above automatically, so npm update works with no extra steps after the first install.

Update

npm update @roopesh.yadava/qa-pack

Skill files are overwritten with the latest version. Your CLAUDE.md, .mcp.json, .env, and — critically — product_context/ (your accumulated run history and known bugs) are never touched. The installed SKILLS_CONTEXT.md is stamped with the pack version, so you can always check which version a repo is running.

Upgrading from 1.0.x: credentials used to live in product_context/{PRODUCT}/context.md — skills now read them from .env instead. Move your username/password/OTP into .env and delete them from any existing context.md.

First-time setup

After installing:

1. Open .env (gitignored) and fill in the secrets: QA_APP_URL, QA_LOGIN_URL, QA_USERNAME, QA_PASSWORD, QA_OTP_CODE (plus JIRA_BASE_URL / JIRA_EMAIL / JIRA_API_TOKEN if you want bug screenshots attached).
2. Open CLAUDE.md and fill in the non-secret project facts (Jira key, environment, auth method).

.claude/settings.local.json (seeded from settings.local.json.example, and re-checked on every install/update) auto-approves Playwright MCP tool calls, since those run constantly during test execution and are scoped to the app under test. Every Atlassian/Jira MCP call — reading a card, filing a bug, commenting, transitioning — and any action needing your input (filing a bug, publishing a charter, overwriting product context) still prompts for confirmation.

Then open the repo in Claude Code and run:

run qa PROJ-123

How the QA agent works

Every run follows the same structured flow:

1. Card input — give a Jira card ID (run qa PROJ-123)
2. Product context — saved context + the Jira card are loaded automatically
3. Model recommendation — a one-line tier suggestion based on the card's Jira issue type (Story/Feature/Epic → default high-capability model, Task/Bug/Sub-task → a lighter model like Haiku). Informational only — switch with /model if you want, or ignore it; set QA_MODEL_ROUTING=off in .env to skip it. See SKILLS_CONTEXT.md for the opt-in subagent-override pattern.
4. Gap questions — you're asked only what isn't already known (one message)
5. Phase selection:
   • Phase 1 — Manual testing (UI/Figma diff → browser tests → bugs → charter)
   • Phase 2 — Write automation (reuse audit → Gherkin → steps → POM → real run + self-heal)
   • Phase 3 — Both (manual first — its findings feed the automation)

Automation is reuse-first: existing .feature files and step definitions are catalogued before any Gherkin is written, drafted steps must match existing ones (exact → parameterized → reworded) before a new step definition is allowed, and each run reports its reuse %.

Commands to run skills

Every skill is plain-English triggered — no slash command required — except /qa-agent and /write-acceptance-criteria, which are also available as explicit slash commands.

QA Agent (orchestrator)

| Command | What happens | |---|---| | /qa-agent PROJ-123 or run qa PROJ-123 | Loads context, asks only the missing gaps, then shows the phase menu | | manual test PROJ-123 / test PROJ-123 / do QA on PROJ-123 | Phase 1 — manual testing + bug filing + charter | | automate PROJ-123 / write automation for PROJ-123 | Phase 2 — reuse-first BDD automation | | full QA PROJ-123 / run everything for PROJ-123 / end to end PROJ-123 | Phase 3 — manual first, then automation | | run qa PROJ-123 --reset-context | Same as above but ignores saved product context and starts fresh (overwrites it on completion) |

Standalone skills (no card required, or card optional)

| Command | Skill | What happens | |---|---|---| | ui test / check design / compare with figma | ui-test-figma | Live app vs Figma design diff | | accessibility test PROJ-123 / a11y test [URL] | accessibility-testing | WCAG 2.1 A/AA audit, files bugs on the card if given | | file a bug / log a bug | bug-reporting | Interactive bug filing to Jira (new or existing card) | | generate a test charter / create a charter | test-charter | Publishes a Test Charter from a saved execution report | | delete files / clean up outputs | delete-files | Prompts to delete/keep files in outputs/ | | /write-acceptance-criteria PROJ-123 | write-acceptance-criteria | Generates AC, appends to the Jira card description | | /impacted-tests / which tests are impacted by this pull | impacted-tests | After pulling dev changes into a test branch, reports which Cucumber feature files are at risk — report-only, no card needed | | set up k6 / scaffold performance tests | k6-framework-scaffold | Scaffolds a k6-performance-tests/ framework (Grafana Cloud, protocol + optional browser layers) with commented templates to fill in — no card needed | | set up mobile testing / set up mobilewright / scaffold mobile BDD tests | mobilewright-setup | Scaffolds Cucumber.js + Mobilewright + a living-documentation HTML reporter into a mobile app repo (Expo, bare React Native, or native iOS/Android), plus one real smoke feature/step file — no card needed. Run once, before mobile-automation has anything to plug into | | automate mobile PROJ-123 / write mobile automation for this card | mobile-automation | Reuse-first Gherkin → step defs → Screen POM → real device run + self-heal for native iOS/Android apps, via Mobile MCP + Mobilewright — the mobile counterpart to automation (web) | | roam mode / explore the app | roam-testing | Card-free exploratory testing — capped breadth-first crawl, report + optional bug filing + charter | | qa dashboard / weekly digest / token roi | qa-insights | Cross-product health dashboard, weekly digest, or token-spend/ROI view — 100% script-generated, no card needed |

The toolkit — why these features stay cheap

Several features above (self-improving locator memory, DOM fingerprint caching, duplicate-bug detection, PII/secrets scanning, risk-based test ordering, the trust ratchet, and every qa-insights report) are powered by one dependency-free script: .claude/skills/qa-agent/toolkit/qa-toolkit.cjs. Skills shell out to it and read back a single line — parsing markdown tables, hashing DOM snapshots, scoring bug-title similarity, and aggregating every product's history are pure computation, so none of it costs a model token beyond the one line of output. This is also why qa-insights (dashboard/digest/ROI across every product you've ever tested) costs about the same whether you have 2 products or 200 — the script does the aggregation, not the model.

Team dashboard (optional, off by default)

qa-insights' dashboard is local and per-repo — it only sees runs on your own machine. To see the whole team's runs across every product, set QA_DASHBOARD_REPO and QA_DASHBOARD_TOKEN in .env (see .env.example). Once set, every skill reports its own execution as its last step — one small JSON file pushed to that shared GitHub repo via the GitHub Contents API. No local git commit/git push, so it never touches this repo's .git or shows up in git status. Leave the variables unset and nothing changes; the call is a silent no-op, same as the optional QA_TRACKING_DIR token tracking.

One record is one skill execution, not one card: a single card taken through qa-agent → manual-testing → bug-reporting reports three. The dashboard counts both ("skill runs" and "cards covered") so neither number is misleading.

What each record contains: product, card (when the skill has one), skill name, outcome, bug IDs, reuse %, date, calling repo name, and an author label taken from git config user.name — never user.email, since the dashboard repo is typically public and its history is permanent. Set QA_DASHBOARD_AUTHOR in .env to override the label. A push that fails (expired PAT, wrong repo, no network) stays silent and is appended to outputs/report-run-errors.log; add --verbose to a manual report-run call to see the result directly, which is the way to verify a freshly issued token.

What postinstall does

| File | Behaviour | |---|---| | .claude/skills/*/SKILL.md + companion .md/.cjs/.sh files (e.g. the toolkit script) | Always overwritten (versioned logic) | | .claude/skills/SKILLS_CONTEXT.md | Always overwritten + stamped with the installed pack version | | .claude/commands/*.md | Always overwritten | | .claude/skills/qa-agent/product_context/** | Never touched after first seed | | .claude/settings.json | Created once, never overwritten | | CLAUDE.md, .mcp.json, cucumber.cjs, .env | Created once, never overwritten | | .env.example | Always refreshed (shows latest env keys) | | .claude/settings.local.json | Created once from example. Every subsequent install/update also checks for the Playwright MCP auto-approve rule (mcp__playwright) and adds it if missing — merged in without touching any other key you've set in the file. If the file isn't valid JSON, this merge is skipped with a warning and the file is left untouched. | | .claude/settings.local.json.example | Always refreshed (shows latest options) | | .gitignore | Managed # >>> qa-pack block regenerated on every install — ignores all pack-installed skills/commands plus outputs/, session files, and local settings |

Git hygiene

Everything qa-pack copies into .claude/ is git-ignored via a managed block in your .gitignore (between # >>> qa-pack and # <<< qa-pack markers). Your product repo's own skills in .claude/skills/ are not affected — only the pack's skill folders are listed by name. The block is regenerated on every install, so skills added in future versions are ignored automatically; anything you write outside the markers is never touched.

Secrets live only in .env (gitignored). product_context/ contains no credentials but lives inside an ignored folder, so it also stays out of git — each machine builds its own context from its runs.

If you installed an older qa-pack version and already committed the skill files, postinstall prints the one-time git rm -r --cached command to untrack them (files stay on disk).

Publishing (maintainers)

# In qa-pack/ repo — commit your changes first (npm version needs a clean tree)
git add . && git commit -m "your message"

# Bump: patch = fixes, minor = new/changed skill behavior, major = breaking
npm version minor -m "release: v%s — short description"

git push origin main --follow-tags
# GitHub Actions publishes to npmjs automatically (triggers on package.json change on main)

Requirements

• Claude Code CLI
• Node.js 18+
• Atlassian MCP connected in Claude Code (for Jira)
• Playwright MCP — configured automatically via the seeded .mcp.json
• Python 3 — only if you enable the optional token tracking (QA_TRACKING_DIR in .env)