A free, open-source AI-driven QA framework for engineers. Take a ticket or
feature from investigation to test execution and evidence, using the tools your
team already has.
Designed for Cursor, Claude Code, Codex and other capable coding agents.
Your tracker, test runner, language and cloud remain your choices.
Runtime setup and verified limits.
Start with a real QA task
/qa Test checkout across our web app and API.
Verify totals and whether another user can read the order.
Use our existing tools and prepare the results locally.
For this task, the agent loads web + API + security guidance, checks the
available capabilities, then authors and executes relevant tests. It preserves
failures and reports what was actually checked. Missing tools limit the affected
checks; they do not stop every useful action.
A mobile lifecycle bug loads mobile guidance. A latency regression adds
performance. A quick question stays a quick question.
Five specialties, one entry point
Each specialty covers prepare → author → execute → diagnose → maintain.
/qa loads the relevant procedures and tool recipes as the task needs them.
| Specialty | Work it guides |
|---|
| API | Contracts and boundaries, actor permissions, persisted state, async completion, idempotency and cleanup |
| Web | Semantic locators, isolated fixtures, authentication, business assertions, browser variation and failure traces |
| Mobile | Android/iOS and native/hybrid procedures, build/device identity, observed locators, permissions, lifecycle and diagnostics |
| Security | Authorized checks selected by risk, actor/object controls, reproducible evidence and reasoned severity |
| Performance | Workloads, baselines, thresholds, resource limits, stopping conditions, latency distributions and investigation |
Security and performance are selected when the task calls for them. Focused
references extend the workflow to accessibility, exploratory testing, data
pipelines and connected-device/BLE work. The support matrix
separates implemented procedures, executed reference stacks and adaptation paths.
Quick start
Prerequisites: Python 3.11+, Git and Bash. Offline checks run on macOS and
Linux; validate your own WSL/Git Bash setup on Windows. Your agent and chosen
product-testing tools are separate prerequisites for live QA.
git clone https://github.com/Qadrillion/qadrillion-agent.git qa-workspace
cd qa-workspace
python3 tools/agents/sync.py
python3 tools/verify.py
python3 tools/workspace/doctor.py
Open the workspace root in your coding agent and give /qa a task, or use
/qa PROJ-123 with a configured tracker. Without slash-command support, ask the
agent to read AGENTS.md and .agent/skills/qa/SKILL.md and follow them.
Before adding company information, establish a private team workspace and
verify its remote and visibility. Configure the capabilities you actually have;
doctor.py checks local setup, not provider authentication or device access.
Follow the adoption guide for your first real ticket.
See it catch a defect
Try the bundled HTTP reference suites with no model or company account:
python3 tools/specialists/replay.py --out /tmp/qa-reference-first
Run from the workspace root and choose a new output directory each time. The
replay starts disposable local services, runs agent-authored API, authorization
and performance tests against defective and corrected behavior, and retains the
results in replay.json plus per-run artifacts.
A defective fixture should fail its tests. The replay succeeds only when the
expected defect is detected, the corrected fixture passes the same assertions,
and the owned services close. An unexpected failure remains a failure to diagnose.
This replays existing tests; it does not run a fresh AI evaluation.
Add Chromium + Firefox ·
Run the native Android fixture ·
Inspect the original evidence
How the work moves forward
- Understand the target. Read requirements and available source; pin the
build, environment and configuration. Black-box work is valid when source is absent.
- Choose the checks. Route by surface and risk. Load only useful specialties;
delegate bounded independent tasks when the runtime supports them.
- Write, run and investigate. Use observed interfaces and meaningful
assertions. Retain first failures; allow one diagnostic rerun for a stated hypothesis.
- Hand off a scoped result. Record Pass, Partial or Fail, tested identity,
evidence, remaining coverage and next action. Prepare tracker updates and
publish when the task authorizes it and the runtime permits it.
Routine authorized QA, test authoring and local maintenance proceed without
repeated approvals. Shared contracts keep authorization and evidence consistent
across specialties and runtime adapters.
Evidence you can inspect
The specialist evaluation records actual
test authoring and execution, including failed attempts and corrected claims:
- API and security: real HTTP suites detect contract/completion and cross-user
access defects; corrected fixtures pass the detecting assertions unchanged.
- Web: Chromium and Firefox detect incorrect business totals, with retained
traces and cleanup evidence.
- Mobile: a real Android emulator detects lost lifecycle state. Corrected
coverage is 10 passed, 2 skipped (Partial); a fresh-emulator portability
replay also detects and verifies correction of both lifecycle cases.
- Performance: a declared p95 budget detects a seeded latency regression,
with raw samples, a baseline and bounded request counts.
CI
runs offline verification on macOS/Linux and the HTTP/browser reference replays.
Nine completed isolated agent scenarios exercise routing and actual work;
research mappings explain the decisions.
These are reference-fixture results. iOS, physical devices, hybrid/BLE execution
and Appium/Maestro feature execution remain unverified here. Native agent
activation and hook enforcement also need checks in your own environment.
Full support boundaries.
Fit it to your team
| Configure | Where |
|---|
| Repository ownership, roots, branches and permitted mutations | workspace-manifest.json |
| Available integrations, runner commands, artifacts and target identity | qa-config.json |
| Production selectors and protected paths | .agent/hooks/guard.conf |
| Authentication and permissions | Your runtime's local settings; keep credentials out of Git |
Start with a configuration example, then use the
integration guide and
team handoff/upgrade guide. Existing Playwright,
Appium, native or other test tooling can be adapted; no runner is mandatory.
Specialty skills supply expertise; subagents supply bounded independent work.
Architecture and ownership.
Hooks provide defense in depth. Their coverage depends on runtime registration,
trust and events; they are not a sandbox. Production execution is excluded.
There is no framework telemetry or required Qadrillion account. Coding agents
and connected providers have their own costs, accounts and data policies.
Help build it
Useful contributions include runner recipes, reproducible bugs, specialist
regression fixtures and clearer adoption docs. Bring a concrete task and evidence
of the behavior you want to improve. Start with CONTRIBUTING.md,
ask a question or report a bug,
or read the fictional worked ticket.
If this fits your workflow, star the repository to help other engineers find
it. Pilot reports with honest failures and limits are especially useful.
Built by Qadrillion. Free to use, adapt and
contribute under the MIT license.
Security policy · Code of conduct
