qa-automation-framework

A skeleton for wiring AI agents into a real test automation stack, on web and native mobile. It ships the agents, the skills they use, and the connective tissue that lets them work against whatever language, runner, CI and tracker a project already picked.

Five QA workflows, working against one project:

• Requirement refinement and test design
• Assisted exploratory and manual testing
• Automated test generation
• Test maintenance and refactoring
• Quality auditing of automation suites

Full docs: https://eduramos21.github.io/qa-automation-framework/ Setup, including Jira and what this looks like on a repo that already has tests: https://eduramos21.github.io/qa-automation-framework/setup.html

The idea

Two layers with one contract between them.

The AI layer, agents/ and skills/, knows QA. It knows nothing about Playwright or pytest.

The profile layer, profiles/<name>/, knows one stack. How to run it, where files go, what good code looks like there. No QA reasoning in it.

The contract is qa.config.yml at the project root, plus a profile.yaml in each profile.

# qa.config.yml
stacks:
  web:
    profile: ts-playwright       # this line picks your language and runner
    root: e2e/
    base_url_env: BASE_URL
ci:
  provider: github-actions       # github-actions | gitlab-ci | jenkins
tracker:
  provider: jira                 # jira | github-issues | none
  project_key: SHOP
policies:
  test_id_attribute: data-testid
  forbid: [hard_sleeps, absolute_xpath, conditional_assertions]

# profiles/ts-playwright/profile.yaml
commands:
  test_one: npx playwright test {file} -g "{title}"
layout:
  tests: tests/
  test_glob: "**/*.spec.ts"
selector_priority: [getByRole, getByLabel, getByTestId, getByText]

When an agent needs to rerun one test it reads commands.test_one. When it needs to write a page object it reads the template and CONVENTIONS.md. That is why the framework is open on language, runner and CI: adding Java plus Selenium means writing four files and changing zero agents.

One command hands an agent all of it:

$ qa-context web
config:       /repo/qa.config.yml
web:          ts-playwright -> /plugin/profiles/ts-playwright
===== ...the config, the profile, and a pointer at the conventions... =====

Install

/plugin marketplace add eduramos21/qa-automation-framework
/plugin install qa@eduramos21-qa

Then in a project:

/qa:init

That works out the language, runner and CI from the repo, asks about what it cannot see, writes qa.config.yml, and drops in a pipeline file.

To try it without installing, claude --plugin-dir . from a clone.

The workflows

Command	Does	Produces
/qa:refine	Ticket to testable acceptance criteria, ambiguities, risk. Asks the questions that need a human	qa/requirements/<id>.md
/qa:design	Risk scored coverage matrix. What to check, at which layer, what not to cover	qa/design/<id>.md
/qa:explore	Session based exploratory testing in a real browser or on a device	qa/sessions/<date>-<charter>.md
/qa:generate	Writes tests in the profile's style, runs them, then breaks them to prove they can fail	test files, plus what it did not write
/qa:fix	Triages through five causes before changing anything, fixes the cause once	edits, plus what it found and did not fix
/qa:audit	Nine area rubric with evidence, findings ranked by cost over effort	qa/audit/<date>.md
/qa:profile	Reads a suite that already exists and writes down its house style	<project>/profiles/<name>/
/qa:prevalidate	Runs the policy check against what is staged, the same rules the edit hook enforces	pass/fail plus violations by file and line

If your repo already has tests

The common case, and the one worth being straight about.

cd your-repo
claude
/qa:init          # 5 minutes, mostly confirming what it worked out from the repo
/qa:audit         # run this first, it reads code you already have and writes nothing

/qa:audit is what tells you whether any of this is useful to you. It needs only the config, touches nothing, and hands back nine scores with evidence plus a ranked list of findings.

Before generating or fixing any code, fix the profile:

/qa:profile

A shipped profile knows how to run your tests. It does not know how you write them. /qa:profile reads your suite, weighted towards recently touched files because recent code is the current style, and drafts a profile.yaml and CONVENTIONS.md describing what your repo actually does, with every example lifted from your code. It writes into <your-repo>/profiles/, which wins over the plugin's copy, so updating the plugin never overwrites your description.

It describes, it does not correct. If your page objects hold assertions, the conventions will say so. Things worth changing go in a separate report and never into the conventions file, because a conventions file that mixes "what we do" with "what we should do" produces code your reviewers reject.

The policy hook will not fight your legacy code either. It reports violations only on lines an edit actually touched, so editing a file that already contains three sleeps, for an unrelated reason, reports nothing. Adding a new sleep reports that one. Pre-existing ones stay an audit finding, which is where a decision about them belongs.

The same check runs at commit time, not just on every edit, and does not need the plugin installed to do it. bin/qa-policy is a standalone stdlib Python script; add .pre-commit-hooks.yaml at this repo's root as a pre-commit hook source, or wire bin/qa-policy --changed-only into husky, lint-staged, or a raw git hook directly. See skills/prevalidate/SKILL.md, or /qa:prevalidate if you do have the plugin.

Try the demos

Both run against saucedemo.com, so they need no setup and no credentials.

This is the beginning of the README. Read the rest at the original. Read the full README ↗