aibot88 Agentic QA Onboard — First-time tour of this repo
Activate when a user lands on this repo for the first time and asks "where do I start?", "how does QA work here?", or invokes /agentic-qa-onboard. The skill is a guided tour, not an executor: it explains the stack, the QA pipeline (Stages 1-6), the MCPs, and the env vars that everything depends on, then hands off to the right downstream skill.
This skill is specific to this Playwright + KATA QA boilerplate and points at the concrete entry points (/sprint-testing, /test-automation, /test-documentation, /regression-testing, /framework-development).
Welcome
This is the Agentic QA Boilerplate — a QA-only boilerplate for testing web applications with AI agents in the loop. The repo ships skills, scripts, and conventions that turn a Jira QA ticket into documented test cases and automated regression coverage through a structured 6-stage pipeline. It does not ship the application under test — that lives in a separate target repo (configured via .agents/project.yaml).
If you cloned this repo and you don't yet have bun run setup complete, start there. Everything else assumes the foundation is green.
Stack
| Layer | Choice |
|---|---|
| Framework | Playwright (E2E + API) |
| Architecture | KATA (TestContext / Base / Domain / Fixture) |
| Reporting | Allure |
| TMS | Jira + Xray Cloud |
| Language | TypeScript (strict mode) |
| Runtime | bun |
| Lint/format | ESLint + Prettier (pre-commit hooks) |
| AI agent | Claude Code (primary), OpenCode (alt) |
The stack is intentionally locked. If your QA project needs a different stack (Cypress, Robot Framework, etc.), this boilerplate is not the right starting point — the KATA architecture is Playwright-specific.
First-time setup
Run the interactive installer once after cloning:
bun run setup
This bootstraps .agents/, installs the gentle-ai engram component (minimal preset), configures the 7 canonical MCPs, downloads Playwright browsers, installs 8 user-level community skills + 2 project-level Playwright skills, and writes .mcp.json. Full details in INSTALLER.md.
After setup, fill .env with the credentials the rest of the workflow expects (see "Critical env vars" below).
Primary pipeline: Stages 1-6
The QA work in this boilerplate is organized as a 6-stage pipeline. Each stage maps to a skill.
| Stage | Skill | What happens |
|---|---|---|
| 1-3 | /sprint-testing |
Per-ticket: Planning → Execution → Reporting. Smoke + trifuerza (UI/API/DB) exploration. |
| 4 | /test-documentation |
Document test cases in TMS (Test/ATP/ATR). ROI prioritization (Candidate/Manual/Deferred). |
| 5 | /test-automation |
KATA-compliant E2E + API tests on Playwright. Plan → Code → Review. |
| 6 | /regression-testing |
CI suite execution. Failure classification. GO/CAUTION/NO-GO release verdict. |
Jira QA state machine:
Ready For QA → In Testing → Tested → Closed
(For bugs found during QA: Open → In Progress → Resolved → Closed after fix verification.)
/sprint-testing orchestrates Stages 1-3. Stage 4 onwards are explicit hand-offs.
Stage 1-3 example flow
/sprint-testing UPEX-277:
- Reads the ticket from Jira via
/acli. - Loads module context from
.context/PBI/{module}/. - Explores the relevant code in the target repo.
- Creates the PBI folder and ATP (Acceptance Test Plan).
- Executes smoke + trifuerza exploration (UI / API / DB).
- Files ATR (Acceptance Test Report) + bug reports if defects found.
- Transitions the ticket through QA states.
- Hands off to Stage 4 (
/test-documentation) when a Candidate test case should be promoted to TMS.
You confirm at the gates.
When to use /framework-development instead
| When | Skill |
|---|---|
| Routine in-sprint QA on a Jira ticket (most cases) | /sprint-testing (ticket-driven) |
| Authoring new automated test for a Candidate TC | /test-automation |
| Refactor of the boilerplate itself — KATA bases, fixtures, cli/, scripts/ | /framework-development |
/framework-development covers framework evolution (changes to the boilerplate's own infrastructure, not per-ticket test writing). Self-contained Plan → Code → Verify → Archive pipeline; works under the minimal install preset (no SDD-* skills required).
MCPs available
Seven canonical MCPs ship with the boilerplate:
| MCP | Use it for |
|---|---|
| Context7 | Official library docs (Playwright, KATA-relevant TS, Allure…) |
| Tavily | Web search, troubleshooting community Q&A |
| Atlassian | Jira ticket reads, transitions, comment posting |
| Playwright | Live browser interactions for exploratory QA (when CLI is not enough) |
| DBHub | DB queries to validate state-mutating tests |
| OpenAPI | API endpoint exploration, contract checking |
| Postman | Saved request collections, request replay for API tests |
Decision rule:
- Use Context7 for "how to use X" — official docs, current API
- Use Tavily for "how to solve X" — community fixes, troubleshooting
- Use Atlassian for ticket operations; for bulk Jira work prefer
/acli - Use Playwright MCP for ad-hoc live browser interactions; for scripted runs use
/playwright-cli
.mcp.json lives at the repo root and is gitignored (it contains secrets).
Critical env vars
Place these in .env before running anything that talks to a real environment:
| Var | Used by |
|---|---|
LOCAL_USER_EMAIL / LOCAL_USER_PASSWORD |
Local app login (Playwright fixtures) |
STAGING_USER_EMAIL / STAGING_USER_PASSWORD |
Staging smoke tests, manual exploration |
ATLASSIAN_SITE / ATLASSIAN_EMAIL / API token |
acli Jira CLI + Atlassian MCP |
XRAY_CLIENT_ID / XRAY_CLIENT_SECRET |
bun xray CLI (Xray Cloud authentication) |
TAVILY_API_KEY |
Tavily MCP |
POSTMAN_API_KEY |
Postman MCP |
.env is gitignored. Never commit it. .agents/project.yaml (committed) holds non-secret context (URLs, project key, environment names); .env holds the matching secrets.
.mcp.json is also gitignored — it holds the wired-up MCP configuration with secrets resolved.
Verify your config with bun run vars:check (should report 0 errors when fully configured).
Local skills (committed in this repo)
| Skill | Trigger | Purpose |
|---|---|---|
agentic-qa-core |
(auto, cited by other skills) | Passive reference host: briefing template, dispatch patterns, orchestration doctrine, skill-composition strategy |
agentic-qa-onboard |
/agentic-qa-onboard |
This skill — first-time orientation |
project-discovery |
/project-discovery |
4-phase reverse-engineering of a target project |
sprint-testing |
/sprint-testing |
Stages 1-3 — per-ticket manual QA loop |
test-documentation |
/test-documentation |
Stage 4 — TMS test case authoring + ROI |
test-automation |
/test-automation |
Stage 5 — KATA + Playwright + TS automation |
regression-testing |
/regression-testing |
Stage 6 — CI suite execution + GO/NO-GO verdict |
playwright-cli |
/playwright-cli |
Browser automation CLI helpers |
playwright-best-practices |
/playwright-best-practices |
Reference skill: flaky-test fixes, POM, accessibility (axe-core), auth/OAuth, fixtures, tags, perf budgets, i18n. Auto-loads alongside /test-automation |
acli |
/acli |
Atlassian CLI wrapper for Jira/Confluence terminal work |
xray-cli |
/xray-cli |
Xray Cloud TMS CLI |
git-flow-master |
(auto on git intents) | End-to-end Git operator (branch, commit, push, PR, conflict, chained-PR) |
judgment-day |
/judgment-day, juzgar |
Vendored from gentle-ai (Apache-2.0). Adversarial dual-judge review (2 blind judges in parallel, fix loop, re-judge). Optional gate cited by /test-automation Phase 3 + /git-flow-master pre-PR. |
What bun run setup installs via gentle-ai
bun run setup runs gentle-ai install --preset minimal — installs ONLY the engram component (persistent memory binary + MCP adapter + agent config). No SDD-* skills, no foundation skills.
Rationale: this repo already covers Plan → Code → Verify natively in its workflow skills (/sprint-testing, /test-automation, /test-documentation, /regression-testing). SDD ceremony does not apply to test authoring.
Want the explicit SDD ceremony for an architectural change of your own? Run manually:
gentle-ai install --components engram,sdd --agent <claude-code|opencode|cursor>
Full details in INSTALLER.md.
Community skills installed at user level
bun run setup also runs bunx skills add --global for 8 cross-project skills:
| Skill | Source | Use |
|---|---|---|
skill-creator |
anthropics/skills | Create / edit / measure skills |
find-skills |
vercel-labs/skills | Discover installable skills |
gh-cli |
github/awesome-copilot | GitHub CLI patterns |
github-actions-docs |
xixu-me/skills | GitHub Actions reference |
brainstorming |
obra/superpowers | Pre-implementation discovery |
cli-printing-press |
mvanhorn/cli-printing-press | CLI report rendering |
html-ppt |
lewislulu/html-ppt-skill | HTML presentation authoring |
resend-cli |
resend/resend-skills | Email automation CLI |
Plus 2 project-level community skills installed into .claude/skills/ (not committed): playwright-cli, playwright-best-practices. See cli/install.ts PROJECT_LEVEL_SKILLS and USER_LEVEL_SKILLS arrays.
Next steps after the onboard
Run through this checklist before you reach for your first ticket:
- Did you run
bun run setup? - Did you fill
.envwith your own credentials (LOCAL_*,STAGING_*,ATLASSIAN_*,XRAY_*,TAVILY_API_KEY,POSTMAN_API_KEY)? - Did you populate
.agents/project.yaml(runbun run agents:setupif not yet)? - Does
bun run vars:checkexit clean (0 errors)? - Did you run
bun run jira:checkto verify Jira credentials? - Did you run
bun run pw:installto get Playwright browsers? - Does engram persistent memory respond (try
mem_contextafter restart)? - Ready for your first QA ticket:
/sprint-testing <UPEX-XXX>
If any box is unchecked, fix that first. The downstream skills assume a green foundation.
What this skill does NOT do
- Test a ticket → use
/sprint-testing - Document test cases in TMS → use
/test-documentation - Write automated tests → use
/test-automation - Run a regression suite → use
/regression-testing - Discover a brand-new target project → use
/project-discovery - Adapt the KATA test architecture to a target stack → use
/adapt-framework
The onboard tour ends at the moment the user knows which skill to call next. From there, the relevant workflow skill takes over.