--- 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: ```bash 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`](../../../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 `/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: ```bash gentle-ai install --components engram,sdd --agent ``` Full details in [`INSTALLER.md`](../../../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 ` 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.