agentic-qa-onboard

name	agentic-qa-onboard
description	Walks new users through this repo's QA flow — Playwright + KATA + Allure + Xray stack, Jira QA workflow (Ready For QA → In Testing → Tested → Closed), /sprint-testing for in-sprint manual QA, /test-documentation for TMS test cases, /test-automation for KATA-compliant E2E/API tests, /regression-testing for CI suite execution, /framework-development for boilerplate evolution, MCPs available (Context7, Tavily, Atlassian, Playwright, DBHub, OpenAPI, Postman), critical env vars. Triggers on: `onboard me to QA`, `explain this QA repo`, `first time using this`, `primer vez en QA`, `/agentic-qa-onboard`. Do NOT use for: feature QA on a ticket (use /sprint-testing), authoring test cases in TMS (use /test-documentation), writing automated tests (use /test-automation), running regression suites (use /regression-testing).
license	MIT
compatibility	["claude-code","opencode"]
phase	bootstrap
complementary_categories	["meta-skill"]

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:

1. Reads the ticket from Jira via /acli.
2. Loads module context from .context/PBI/{module}/.
3. Explores the relevant code in the target repo.
4. Creates the PBI folder and ATP (Acceptance Test Plan).
5. Executes smoke + trifuerza exploration (UI / API / DB).
6. Files ATR (Acceptance Test Report) + bug reports if defects found.
7. Transitions the ticket through QA states.
8. 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 Phase 3 + 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 .env with your own credentials (LOCAL_*, STAGING_*, ATLASSIAN_*, XRAY_*, TAVILY_API_KEY, POSTMAN_API_KEY)?
• Did you populate .agents/project.yaml (run bun run agents:setup if not yet)?
• Does bun run vars:check exit clean (0 errors)?
• Did you run bun run jira:check to verify Jira credentials?
• Did you run bun run pw:install to get Playwright browsers?
• Does engram persistent memory respond (try mem_context after 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.