@roopesh.yadava/qa-pack 1.2.0 → 1.4.0

package/README.md

@@ -31,6 +31,13 @@ After installing:
    (plus `JIRA_BASE_URL` / `JIRA_EMAIL` / `JIRA_API_TOKEN` if you want bug screenshots attached).
 2. Open `CLAUDE.md` and fill in the non-secret project facts (Jira key, environment, auth method).
 
+`.claude/settings.local.json` (seeded from `settings.local.json.example`, and re-checked on
+every install/update) auto-approves Playwright MCP tool calls, since those run constantly
+during test execution and are scoped to the app under test. Every Atlassian/Jira MCP call —
+reading a card, filing a bug, commenting, transitioning — and any action needing your input
+(filing a bug, publishing a charter, overwriting product context) still prompts for
+confirmation.
+
 Then open the repo in Claude Code and run:
 
 ```
@@ -43,8 +50,13 @@ Every run follows the same structured flow:
 
 1. **Card input** — give a Jira card ID (`run qa PROJ-123`)
 2. **Product context** — saved context + the Jira card are loaded automatically
-3. **Gap questions** — you're asked only what isn't already known (one message)
-4. **Phase selection**:
+3. **Model recommendation** — a one-line tier suggestion based on the card's Jira issue type
+   (Story/Feature/Epic → default high-capability model, Task/Bug/Sub-task → a lighter model
+   like Haiku). Informational only — switch with `/model` if you want, or ignore it; set
+   `QA_MODEL_ROUTING=off` in `.env` to skip it. See `SKILLS_CONTEXT.md` for the opt-in
+   subagent-override pattern.
+4. **Gap questions** — you're asked only what isn't already known (one message)
+5. **Phase selection**:
    - **Phase 1 — Manual testing** (UI/Figma diff → browser tests → bugs → charter)
    - **Phase 2 — Write automation** (reuse audit → Gherkin → steps → POM → real run + self-heal)
    - **Phase 3 — Both** (manual first — its findings feed the automation)
@@ -79,6 +91,7 @@ and `/write-acceptance-criteria`, which are also available as explicit slash com
 | `delete files` / `clean up outputs` | delete-files | Prompts to delete/keep files in `outputs/` |
 | `/write-acceptance-criteria PROJ-123` | write-acceptance-criteria | Generates AC, appends to the Jira card description |
 | `/impacted-tests` / `which tests are impacted by this pull` | impacted-tests | After pulling dev changes into a test branch, reports which Cucumber feature files are at risk — report-only, no card needed |
+| `set up k6` / `scaffold performance tests` | k6-framework-scaffold | Scaffolds a `k6-performance-tests/` framework (Grafana Cloud, protocol + optional browser layers) with commented templates to fill in — no card needed |
 
 ## What postinstall does
 
@@ -91,7 +104,7 @@ and `/write-acceptance-criteria`, which are also available as explicit slash com
 | `.claude/settings.json` | Created once, never overwritten |
 | `CLAUDE.md`, `.mcp.json`, `cucumber.cjs`, `.env` | Created once, never overwritten |
 | `.env.example` | Always refreshed (shows latest env keys) |
-| `.claude/settings.local.json` | Created once from example |
+| `.claude/settings.local.json` | Created once from example. Every subsequent install/update also checks for the Playwright MCP auto-approve rule (`mcp__playwright`) and adds it if missing — merged in without touching any other key you've set in the file. If the file isn't valid JSON, this merge is skipped with a warning and the file is left untouched. |
 | `.claude/settings.local.json.example` | Always refreshed (shows latest options) |
 | `.gitignore` | Managed `# >>> qa-pack` block regenerated on every install — ignores all pack-installed skills/commands plus `outputs/`, session files, and local settings |
 

package/bin/postinstall.js

@@ -104,6 +104,37 @@ copyFile(
   { overwrite: true }
 );
 
+// ── 4b. Force-ensure the Playwright MCP auto-approve rule ─────────────────────
+// Runs on every install/update, whether settings.local.json was just created above,
+// already existed from an older pack version that predates this rule, or was hand-
+// edited. Merges in only this one permissions.allow entry — every other key/value in
+// the file (including any other allow/deny/ask rules) is left exactly as it was.
+const PLAYWRIGHT_MCP_RULE = 'mcp__playwright';
+if (fs.existsSync(localSettingsDest)) {
+  try {
+    const settings = JSON.parse(fs.readFileSync(localSettingsDest, 'utf8'));
+    if (typeof settings.permissions !== 'object' || settings.permissions === null) {
+      settings.permissions = {};
+    }
+    if (!Array.isArray(settings.permissions.allow)) {
+      settings.permissions.allow = [];
+    }
+    const hasRule = settings.permissions.allow.some(
+      (rule) => rule === PLAYWRIGHT_MCP_RULE || rule === `${PLAYWRIGHT_MCP_RULE}__*`
+    );
+    if (!hasRule) {
+      settings.permissions.allow.push(PLAYWRIGHT_MCP_RULE);
+      fs.writeFileSync(localSettingsDest, `${JSON.stringify(settings, null, 2)}\n`);
+      log.updated.push(`${path.relative(PROJECT_ROOT, localSettingsDest)} (added Playwright MCP auto-approve rule)`);
+    }
+  } catch (e) {
+    console.warn(
+      `  Warning: could not parse ${path.relative(PROJECT_ROOT, localSettingsDest)} as JSON — left untouched.\n` +
+      `           Add "${PLAYWRIGHT_MCP_RULE}" to its permissions.allow array manually to auto-approve Playwright MCP calls.`
+    );
+  }
+}
+
 // ── 5. One-time templates (never overwrite — user fills these in) ─────────────
 const templates = [
   ['templates/CLAUDE.md',    'CLAUDE.md'],

package/claude/skills/SKILLS_CONTEXT.md

@@ -210,6 +210,16 @@ Also check `token_usage_log.json` for `cache_read_input_tokens` per phase to see
 Target: `cache_efficiency_pct` ≥ 70 after the first run on a given product.
 First run will always be 0% (cold cache). Second and subsequent runs should cache the stable block (product context + skill instructions).
 
+## Model Routing (optional)
+
+`QA_MODEL_ROUTING` in `.env` controls how qa-agent responds to Jira issue type at Step 1c:
+
+| Value | Behavior |
+|-------|----------|
+| unset or `recommend` (default) | qa-agent prints a one-line model-tier recommendation (Story/Feature/Epic → high-capability, Task/Bug/Sub-task → lighter model) after fetching the card, then continues on whatever model is already active. Portable — depends on no special tooling. |
+| `off` | Skip the recommendation line entirely. |
+| `subagent` (advanced, opt-in — not wired up by the shipped skills) | For Claude Code setups where phase dispatch runs through a subagent/Task-style tool that accepts a `model` parameter: adapt qa-agent's Step 4 dispatch to pass `model: haiku` for Task/Bug and the default model for Story/Feature when invoking `manual-testing` / `automation`. This is a pattern to wire into your own environment's actual subagent tool — qa-pack itself doesn't assume one exists, since not every Claude Code setup qa-pack installs into exposes the same dispatch mechanism. |
+
 ## Artifact Locations
 
 | Artifact | Path |

package/claude/skills/k6-framework-scaffold/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: k6-framework-scaffold
+description: Scaffold a ready-to-use k6 load-testing framework (Grafana Cloud) in a repo. Creates the k6-performance-tests/ tree — shared config/ + lib/, a protocol/ (API load) layer with api/flows/tests, and an OPTIONAL browser/ (UI) layer — with commented template files that testers then fill in. Use when someone asks to "set up k6", "create the k6 load testing structure/framework", "scaffold performance tests", or start load testing a new app.
+compatibility: >
+  Standalone skill — not part of the qa-agent pipeline. The bundled scaffold.sh only writes
+  files; the k6 CLI (and a Grafana Cloud account for `k6 cloud run`) is only needed later,
+  when the tester actually runs the generated tests.
+---
+
+# k6 Framework Scaffold
+
+Generates a standard, reusable k6 performance-testing framework so a tester can start from a
+ready structure and just fill in their app's endpoints, weights, and tokens.
+
+## What it creates
+
+```
+k6-performance-tests/
+├── config/     env.js · secrets.js · profiles.js        (shared: URLs, tokens, load shapes)
+├── lib/        http.js · rand.js · browser.js           (shared helpers)
+├── protocol/   api/{userTypeA,userTypeB}/ · flows/ · tests/{smoke,load,spike,breakpoint,endurance}/
+│               ── API / HTTP load — the CORE, needed for every app
+├── browser/    pages/ · flows/ · tests/
+│               ── real-browser UX — OPTIONAL, only for UI-heavy apps (delete if unneeded)
+└── README.md
+```
+
+Design principle: **separate WHAT we test (api → flows) from HOW MUCH load (profiles → tests)**,
+so the same endpoints/journeys are reused across every test type. All files are commented
+templates with `TODO`s.
+
+## How to run it
+
+From the target repo root, run the bundled script:
+
+```bash
+bash .claude/skills/k6-framework-scaffold/scaffold.sh
+```
+
+- It creates `k6-performance-tests/` in the current directory.
+- It is **safe**: if `k6-performance-tests/` already exists it aborts (won't overwrite).
+  Pass `--force` to scaffold into an existing folder (only adds missing files; still never
+  overwrites an existing file).
+
+After it runs, tell the tester the next steps:
+1. `config/env.js` — set `BASE` (API URL), `UI_BASE`s, `PROJECT_ID`, scale numbers, test data.
+2. `config/secrets.js` — paste auth tokens/credentials (git-ignored pattern).
+3. `protocol/api/**` — replace the sample endpoints with the real ones (one function per call).
+4. `protocol/flows/**` — set the weighted action table (feature-usage %) + thresholds (SLA).
+5. Browser layer is **optional** — keep it only for UI-heavy apps; otherwise delete `browser/`.
+6. Install k6, `k6 cloud login --token <token>`, then run from inside `k6-performance-tests/`:
+   `k6 run protocol/tests/smoke/example.smoke.js` (local) or `k6 cloud run ...`.
+
+## Notes
+- The script only writes files; it does not install k6 or run tests.
+- Keep real tokens out of version control (the scaffold's `.gitignore` covers `secrets.local.*`).
+- If the user wants the structure tailored (their user types, real endpoints from a Postman
+  collection), scaffold first, then edit the generated templates to match.

package/claude/skills/k6-framework-scaffold/scaffold.sh

@@ -0,0 +1,388 @@
+#!/usr/bin/env bash
+# k6-framework-scaffold — create a ready-to-use k6 load-testing framework in the CURRENT repo.
+# Usage:  bash .claude/skills/k6-framework-scaffold/scaffold.sh [--force]
+#   (no flag) aborts if k6-performance-tests/ already exists.
+#   --force   scaffolds into an existing folder; still never overwrites an existing file.
+set -euo pipefail
+
+ROOT="k6-performance-tests"
+FORCE="${1:-}"
+
+if [ -d "$ROOT" ] && [ "$FORCE" != "--force" ]; then
+  echo "ERROR: $ROOT/ already exists. Re-run with --force to add only missing files." >&2
+  exit 1
+fi
+
+# w <relative-path> : write heredoc (stdin) to $ROOT/<path>, only if the file doesn't exist.
+w() {
+  local path="$1"
+  if [ -f "$ROOT/$path" ]; then echo "  skip (exists): $path"; cat >/dev/null; return; fi
+  mkdir -p "$ROOT/$(dirname "$path")"
+  cat > "$ROOT/$path"
+  echo "  created: $path"
+}
+
+echo "Scaffolding $ROOT/ ..."
+
+# ---------------------------------------------------------------- config/
+w config/env.js <<'EOF'
+// config/env.js — shared configuration. Fill these in for your app + environment.
+
+export const BASE = 'https://api.example.com/v1'; // TODO: API base URL
+export const UI_BASE = 'https://app.example.com'; // TODO: web-app URL (browser tests only)
+
+export const PROJECT_ID = 0; // TODO: Grafana Cloud project id
+
+// Target concurrency — the production peak you reproduce. Rescale by editing these numbers.
+export const CONCURRENT = { userTypeA: 100, userTypeB: 100 };
+export const TOTAL = {
+  userTypeAVUs: CONCURRENT.userTypeA,
+  userTypeBVUs: CONCURRENT.userTypeB,
+  totalVUs: CONCURRENT.userTypeA + CONCURRENT.userTypeB,
+};
+
+// Credentials + ids used by auth and parameterised endpoints.
+export const CREDS = { username: 'TODO', password: 'TODO', otp: '000000' };
+export const TEST_DATA = { sampleId: 'TODO' };
+
+// Include mutating (write) endpoints in the mix? They modify real data on the target env.
+export const ENABLE_WRITES = false;
+
+// Long-lived auth token(s) live in secrets.js (rotate per run).
+export { ACCESS_TOKEN } from './secrets.js';
+EOF
+
+w config/secrets.js <<'EOF'
+// config/secrets.js — auth material, refreshed before each run.
+// ⚠️ Keep production tokens OUT of version control. Use short-lived non-prod tokens.
+export const ACCESS_TOKEN = 'Bearer TODO';
+EOF
+
+w config/profiles.js <<'EOF'
+// config/profiles.js — reusable LOAD PROFILES (the "how much"). A test wires a flow to one.
+
+export function loadProfile({ exec, target, rampUp = '2m', hold = '15m', rampDown = '2m', startVUs = 0 }) {
+  return { executor: 'ramping-vus', exec, startVUs, stages: [
+    { duration: rampUp, target }, { duration: hold, target }, { duration: rampDown, target: 0 },
+  ] };
+}
+export function arrivalRateProfile({ exec, rate, timeUnit = '1m', duration = '15m', preAllocatedVUs = 50, maxVUs = 100 }) {
+  return { executor: 'constant-arrival-rate', exec, rate, timeUnit, duration, preAllocatedVUs, maxVUs };
+}
+export function spikeProfile({ exec, target, rampUp = '30s', hold = '1m', rampDown = '30s', startVUs = 0 }) {
+  return { executor: 'ramping-vus', exec, startVUs, stages: [
+    { duration: rampUp, target }, { duration: hold, target }, { duration: rampDown, target: 0 },
+  ] };
+}
+export function breakpointProfile({ exec, maxRate, ramp = '30m', timeUnit = '1m', preAllocatedVUs = 50, maxVUs = 200 }) {
+  return { executor: 'ramping-arrival-rate', exec, startRate: 0, timeUnit, preAllocatedVUs, maxVUs,
+    stages: [{ duration: ramp, target: maxRate }] };
+}
+export function smokeProfile({ exec, vus = 1, iterations = 1 }) {
+  return { executor: 'per-vu-iterations', exec, vus, iterations, maxDuration: '1m' };
+}
+export function enduranceProfile({ exec, target, rampUp = '2m', hold = '2h', rampDown = '2m', startVUs = 0 }) {
+  return { executor: 'ramping-vus', exec, startVUs, stages: [
+    { duration: rampUp, target }, { duration: hold, target }, { duration: rampDown, target: 0 },
+  ] };
+}
+EOF
+
+# ---------------------------------------------------------------- lib/
+w lib/http.js <<'EOF'
+// lib/http.js — shared request headers + response handling.
+import { check } from 'k6';
+
+// `token` is the full Bearer string. Each flow passes its own token.
+export function authHeaders(token, extra = {}) {
+  return { Authorization: token, 'Content-Type': 'application/json', ...extra };
+}
+
+// 2xx check; logs 4xx (client-side) with a short body snippet. 5xx tracked by error-rate metric.
+export function checkResponse(res, name) {
+  check(res, { [`${name} ok`]: (r) => r.status >= 200 && r.status < 300 });
+  if (res.status >= 400 && res.status < 500) {
+    const body = String(res.body || '').replace(/\s+/g, ' ').slice(0, 300);
+    console.error(`FAIL ${name} | ${res.status} ${res.request.method} ${res.request.url} | ${body}`);
+  }
+  return res;
+}
+EOF
+
+w lib/rand.js <<'EOF'
+// lib/rand.js — deterministic pseudo-random for load distribution (NOT cryptographic; and
+// intentionally not the JS built-in RNG, which trips security scans). Reproducible runs.
+
+// xorshift32 -> fraction in [0,1). seed = any integer (e.g. the iteration index).
+export function frac(seed) {
+  let x = (seed >>> 0) || 1;
+  x ^= x << 13; x >>>= 0; x ^= x >>> 17; x ^= x << 5; x >>>= 0;
+  return (x >>> 0) / 4294967296;
+}
+
+// Pick a weighted action given the total weight and a value u in [0,1).
+export function weightedPick(actions, totalWeight, u) {
+  const target = u * totalWeight; let acc = 0;
+  for (let i = 0; i < actions.length; i++) { acc += actions[i].weight; if (target <= acc) return actions[i]; }
+  return actions[actions.length - 1];
+}
+EOF
+
+w lib/browser.js <<'EOF'
+// lib/browser.js — checkpoints for browser/ (real-Chromium) tests.
+import { check } from 'k6';
+
+// Element visible within timeout ms (a "stuck UI" surfaces here as a timeout -> failure).
+export async function expectVisible(page, selector, name, timeout = 10000) {
+  let ok = false;
+  try { await page.locator(selector).waitFor({ state: 'visible', timeout }); ok = true; } catch (e) { ok = false; }
+  check(ok, { [`${name} visible`]: (v) => v === true });
+  return ok;
+}
+// Element gone within timeout ms (e.g. a spinner cleared).
+export async function expectHidden(page, selector, name, timeout = 15000) {
+  let ok = false;
+  try { await page.locator(selector).waitFor({ state: 'hidden', timeout }); ok = true; } catch (e) { ok = false; }
+  check(ok, { [`${name} settled`]: (v) => v === true });
+  return ok;
+}
+// Best-effort screenshot (never fails the iteration).
+export async function shot(page, path) { try { await page.screenshot({ path }); } catch (e) {} }
+EOF
+
+# ---------------------------------------------------------------- protocol/api/
+w protocol/api/exampleUser/auth.js <<'EOF'
+// protocol/api/exampleUser/auth.js — token-issuing login. Adapt to your auth, or delete if
+// you only use a pre-issued static token (config/secrets.js).
+import http from 'k6/http';
+import { BASE, CREDS } from '../../../config/env.js';
+import { checkResponse } from '../../../lib/http.js';
+
+const JSON_HEADERS = { 'Content-Type': 'application/json' };
+
+// Example: POST /auth/sign-in -> returns a session (for a two-step OTP flow) or a token.
+export function signIn(tags) {
+  const res = http.post(`${BASE}/auth/sign-in`,
+    JSON.stringify({ username: CREDS.username, password: CREDS.password }),
+    { headers: JSON_HEADERS, tags: { name: 'auth-sign-in', ...tags } });
+  checkResponse(res, 'auth-sign-in');
+  try { return res.json('data.session'); } catch (e) { return null; }
+}
+// If login is two-step (OTP): read the session from signIn() and feed it into a verify() here.
+EOF
+
+w protocol/api/exampleUser/sample.js <<'EOF'
+// protocol/api/exampleUser/sample.js — ENDPOINTS: one function per API call. Copy this shape
+// for each endpoint (add a unique `name` tag so it shows per-endpoint in Grafana).
+import http from 'k6/http';
+import { BASE, TEST_DATA } from '../../../config/env.js';
+import { authHeaders, checkResponse } from '../../../lib/http.js';
+
+export function list(token, tags) {
+  const res = http.get(`${BASE}/sample/list?page=1&limit=10`,
+    { headers: authHeaders(token), tags: { name: 'sample-list', ...tags } });
+  return checkResponse(res, 'sample-list');
+}
+
+export function get(token, tags) {
+  const res = http.get(`${BASE}/sample/get/${TEST_DATA.sampleId}`,
+    { headers: authHeaders(token), tags: { name: 'sample-get', ...tags } });
+  return checkResponse(res, 'sample-get');
+}
+
+// ⚠️ WRITE example — mark write:true in the flow so ENABLE_WRITES can gate it.
+// export function create(token, tags) {
+//   const res = http.post(`${BASE}/sample`, JSON.stringify({ /* ... */ }),
+//     { headers: authHeaders(token), tags: { name: 'sample-create', ...tags } });
+//   return checkResponse(res, 'sample-create');
+// }
+EOF
+
+# ---------------------------------------------------------------- protocol/flows/
+w protocol/flows/exampleUserFlow.js <<'EOF'
+// protocol/flows/exampleUserFlow.js — JOURNEY: a weighted API traffic-split for one user
+// population. Each iteration a VU performs ONE weighted action; over the run the request mix
+// converges to these proportions (= the client's feature-usage %).
+import { sleep } from 'k6';
+import exec from 'k6/execution';
+import { ACCESS_TOKEN, ENABLE_WRITES } from '../../config/env.js';
+import { frac, weightedPick } from '../../lib/rand.js';
+import * as sample from '../api/exampleUser/sample.js';
+
+// Pass/fail thresholds (from the client's SLA).
+export const THRESHOLDS = {
+  http_req_duration: ['p(95)<2000'], // TODO: SLA
+  http_req_failed: ['rate<0.01'],
+};
+
+// weight = share of total traffic (sum ~ 1.0). write:true = mutating (gated by ENABLE_WRITES).
+const ACTIONS = [
+  { weight: 0.7, run: (t) => sample.list(t) },
+  { weight: 0.3, run: (t) => sample.get(t) },
+  // { weight: 0.1, write: true, run: (t) => sample.create(t) },
+];
+const ACTIVE = ENABLE_WRITES ? ACTIONS : ACTIONS.filter((a) => !a.write);
+const TOTAL_WEIGHT = ACTIVE.reduce((s, a) => s + a.weight, 0);
+
+export function exampleUserFlow() {
+  const token = ACCESS_TOKEN;
+  const seed = exec.scenario.iterationInTest + 1;
+  weightedPick(ACTIVE, TOTAL_WEIGHT, frac(seed)).run(token);
+  sleep(1 + frac(seed ^ 0x5bd1e995) * 2); // think time 1-3s
+}
+EOF
+
+# ---------------------------------------------------------------- protocol/tests/
+w protocol/tests/smoke/example.smoke.js <<'EOF'
+// protocol/tests/smoke/example.smoke.js — quick "does it work?" before a big run.
+import { PROJECT_ID } from '../../../config/env.js';
+import { smokeProfile } from '../../../config/profiles.js';
+import { THRESHOLDS } from '../../flows/exampleUserFlow.js';
+export { exampleUserFlow } from '../../flows/exampleUserFlow.js';
+
+export const options = {
+  cloud: { projectID: PROJECT_ID, name: 'MyApp API — Smoke' },
+  scenarios: { smoke: smokeProfile({ exec: 'exampleUserFlow', vus: 1, iterations: 1 }) },
+  thresholds: THRESHOLDS,
+};
+EOF
+
+w protocol/tests/load/example.load.js <<'EOF'
+// protocol/tests/load/example.load.js — the expected-peak run.
+import { PROJECT_ID, TOTAL } from '../../../config/env.js';
+import { loadProfile } from '../../../config/profiles.js';
+import { THRESHOLDS } from '../../flows/exampleUserFlow.js';
+export { exampleUserFlow } from '../../flows/exampleUserFlow.js';
+
+export const options = {
+  cloud: { projectID: PROJECT_ID, name: 'MyApp API — Load' },
+  scenarios: {
+    users: loadProfile({ exec: 'exampleUserFlow', target: TOTAL.userTypeAVUs, hold: '15m' }),
+  },
+  thresholds: THRESHOLDS,
+};
+EOF
+
+w protocol/tests/spike/README.md <<'EOF'
+# Spike tests
+Copy a load test here and swap the profile to `spikeProfile` (config/profiles.js) — a sudden
+burst then a quick drop, to check the system survives/recovers from a surge.
+EOF
+
+w protocol/tests/breakpoint/README.md <<'EOF'
+# Breakpoint tests
+Ramp load upward until it breaks (find capacity). Use `breakpointProfile` and pair with an
+`abortOnFail` threshold so the run stops at the breaking point.
+EOF
+
+w protocol/tests/endurance/README.md <<'EOF'
+# Endurance (soak) tests
+Moderate, sustained load for hours (memory leaks, resource growth). Use `enduranceProfile`.
+EOF
+
+# ---------------------------------------------------------------- browser/ (OPTIONAL)
+w browser/pages/exampleApp/loginPage.js <<'EOF'
+// browser/pages/exampleApp/loginPage.js — PAGE OBJECT (selectors + actions). Fill selectors
+// from the real DOM/source. SPA-safe: wait on the next screen's element, not full navigation.
+import { UI_BASE, CREDS } from '../../../config/env.js';
+
+const SEL = {
+  username: '#username',       // TODO
+  password: '#password',       // TODO
+  submit: '[data-testid="submit"]', // TODO
+};
+
+export async function login(page) {
+  await page.goto(`${UI_BASE}/login`, { waitUntil: 'networkidle' });
+  await page.locator(SEL.username).fill(CREDS.username);
+  await page.locator(SEL.password).fill(CREDS.password);
+  await page.locator(SEL.submit).click();
+}
+EOF
+
+w browser/pages/exampleApp/samplePage.js <<'EOF'
+// browser/pages/exampleApp/samplePage.js — checkpoints for a screen.
+import { expectVisible } from '../../../lib/browser.js';
+const SEL = { root: '[data-testid="page-root"]' }; // TODO
+export async function assertLoaded(page) {
+  return expectVisible(page, SEL.root, 'sample-page', 15000);
+}
+EOF
+
+w browser/flows/exampleUiFlow.js <<'EOF'
+// browser/flows/exampleUiFlow.js — UI JOURNEY (real browser): login -> a screen renders.
+import { browser } from 'k6/browser';
+import * as loginPage from '../pages/exampleApp/loginPage.js';
+import * as samplePage from '../pages/exampleApp/samplePage.js';
+import { shot } from '../../lib/browser.js';
+
+export const UI_THRESHOLDS = {
+  checks: ['rate>0.95'],
+  browser_web_vital_lcp: ['p(90)<2500'], // TODO: tune to UX SLA
+};
+
+export async function exampleUiJourney() {
+  const page = await browser.newPage();
+  try {
+    await loginPage.login(page);
+    const ok = await samplePage.assertLoaded(page);
+    await shot(page, `screenshots/example-${ok ? 'ok' : 'FAIL'}.png`);
+  } finally {
+    await page.close();
+  }
+}
+EOF
+
+w browser/tests/exampleUi.browser.js <<'EOF'
+// browser/tests/exampleUi.browser.js — run a FEW real-browser VUs (each is a real Chromium,
+// so keep counts small). Headless by default; K6_BROWSER_HEADLESS=false to watch locally.
+import { PROJECT_ID } from '../../config/env.js';
+import { UI_THRESHOLDS } from '../flows/exampleUiFlow.js';
+export { exampleUiJourney } from '../flows/exampleUiFlow.js';
+
+export const options = {
+  cloud: { projectID: PROJECT_ID, name: 'MyApp UI — Example Journey (browser)' },
+  scenarios: {
+    ui: {
+      executor: 'per-vu-iterations', exec: 'exampleUiJourney', vus: 1, iterations: 1,
+      maxDuration: '3m', options: { browser: { type: 'chromium' } },
+    },
+  },
+  thresholds: UI_THRESHOLDS,
+};
+EOF
+
+# ---------------------------------------------------------------- root files
+w .gitignore <<'EOF'
+config/secrets.local.js
+.env
+*.k6-summary.json
+summary.json
+screenshots/
+EOF
+
+w README.md <<'EOF'
+# k6 Performance & UX Test Framework
+
+Two layers, sharing `config/` + `lib/`:
+- **protocol/** — API / HTTP load (the CORE, every app). api/ (endpoints) -> flows/ (weighted
+  traffic-split + thresholds) -> tests/ (wire a flow to a load profile).
+- **browser/** — real-browser UX (OPTIONAL; UI-heavy apps only). Delete this folder if unneeded.
+
+## Fill in
+1. `config/env.js` — BASE / UI_BASE / PROJECT_ID / scale numbers / test data.
+2. `config/secrets.js` — auth token(s) (keep out of VCS).
+3. `protocol/api/**` — one function per real endpoint.
+4. `protocol/flows/**` — weighted action table (feature-usage %) + thresholds (SLA).
+
+## Run (from inside this folder)
+```
+k6 cloud login --token <GRAFANA_CLOUD_TOKEN>
+k6 run       protocol/tests/smoke/example.smoke.js    # local sanity
+k6 cloud run protocol/tests/load/example.load.js       # on Grafana Cloud
+# browser (optional): k6 run browser/tests/exampleUi.browser.js
+```
+EOF
+
+echo "Done. Structure created under $ROOT/"
+echo "Next: fill config/env.js + config/secrets.js, then replace the example endpoints/flows."

package/claude/skills/manual-testing/SKILL.md

@@ -27,6 +27,14 @@ user-invocable: true
 **After the ONE allowed login snapshot — never call `browser_snapshot()` again in this run.**
 Use `browser_evaluate` with a specific CSS selector or JS expression for all DOM inspection.
 
+## Test Data & Entity Selection Rules
+
+| Situation | Forbidden | Do instead |
+|-----------|-----------|------------|
+| A test step needs a value you don't have — a user record, a transaction PIN, a one-time user code | Calling a user-list endpoint or any other app API to fetch/guess it | Ask the user once, in the normal gap-question flow ("This test needs a valid user code — please provide one, or a test user's ID"), or pull it from `.env` / product context if already recorded there |
+| A test requires two specifically related entities (e.g. a parent user + a specific child user, an account + a specific linked card) and the AC/COS doesn't name the exact pair | Picking one at random and proceeding as if it passed | Ask the user to specify the pair once. If they can't provide it inline, mark that test `🔒 BLOCKED` with the note "entity relationship not specified — needs manual verification" and continue with the rest of the plan — don't stop the whole run over one test |
+| The AC/COS doesn't say how to reach the feature under test (menu path, URL, entry point) | Reading or grepping the `src/` tree to reverse-engineer the route | Ask once: "AC doesn't say how to reach {feature} — what's the navigation path (menu/page) to get there?" |
+
 ## Token Tracking
 
 Optional and silent — follow the **Token Tracking** pattern in `SKILLS_CONTEXT.md`
@@ -152,13 +160,19 @@ HINTS = {
 
 ### 3a — Generate Test Plan
 
+Before drafting test ideas, check each AC item for a stated entry point (menu path, URL,
+button/link name). Per the **Test Data & Entity Selection Rules** above, do not scan `src/`
+to infer a missing one — collect a single navigation question per missing entry point and
+fold it into the confirmation prompt below instead of guessing.
+
 From the AC, generate numbered test ideas:
 - 1–3 tests per AC item
 - 2+ negative/edge case tests
 - 1+ error state test
 
 Show as a compact table (T-01, T-02 ... with name and expected outcome).
-Ask: `"Ready to run these tests? (yes / no or edit)"`
+Ask: `"Ready to run these tests? (yes / no or edit)"` — include any missing navigation
+questions in this same message.
 Proceed on confirmation.
 
 ### 3b — Setup Browser + Capture Login Selectors

package/claude/skills/qa-agent/SKILL.md

@@ -95,6 +95,23 @@ Criteria / COS**, **Figma link**, **issue type**, **project name** (for Step 6 f
 If the description exceeds ~800 words, keep only Title + AC/Given-When-Then blocks +
 Figma links; discard prose, comment threads, embedded images. Do not mention the truncation.
 
+### 1c — Model Recommendation
+
+Using the issue type fetched in 1b, print one line — informational only, never blocking:
+
+| Issue type | Recommendation |
+|---|---|
+| Story / Feature / Epic | high-capability model (current default) |
+| Task / Bug / Sub-task | lighter model (e.g. Haiku) |
+
+> "Issue type: {type} → {tier} recommended for this run. Switch now with `/model` if you'd
+> like, or continue on the current model."
+
+Skip this line entirely if `.env` sets `QA_MODEL_ROUTING=off`. This is a recommendation
+only — qa-pack has no way to force a mid-run model switch, so proceed on whatever model is
+active regardless of the user's choice. See `SKILLS_CONTEXT.md` → "Model Routing" for the
+opt-in subagent-override pattern some environments can wire up instead.
+
 ---
 
 ## Step 2 — Ask Relevant Questions (gaps only)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roopesh.yadava/qa-pack",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "AI-powered QA agent skills for Claude Code — manual testing, BDD automation, accessibility, UI/Figma diff, bug reporting",
   "scripts": {
     "postinstall": "node bin/postinstall.js"
@@ -23,7 +23,10 @@
     "claude",
     "playwright",
     "cucumber",
-    "bdd"
+    "bdd",
+    "k6",
+    "performance-testing",
+    "load-testing"
   ],
   "license": "MIT"
 }

package/templates/.env.example

@@ -20,3 +20,7 @@ JIRA_API_TOKEN=
 # When unset or the scripts are missing, skills skip all tracking silently.
 # QA_TRACKING_DIR=
 # QA_TRACKING_MODEL=
+
+# ── Optional: model-tier recommendation for qa-agent (see SKILLS_CONTEXT.md) ──
+# recommend (default) | off | subagent (advanced — see "Model Routing" in SKILLS_CONTEXT.md)
+# QA_MODEL_ROUTING=recommend

package/templates/settings.local.json.example

@@ -5,11 +5,7 @@
       "Bash(npx cucumber-js *)",
       "Bash(echo \"Exit: $?\")",
       "Bash(playwright --version)",
-      "mcp__claude_ai_Atlassian__getAccessibleAtlassianResources",
-      "mcp__claude_ai_Atlassian__getJiraIssue",
-      "mcp__claude_ai_Atlassian__createJiraIssue",
-      "mcp__claude_ai_Atlassian__createIssueLink",
-      "mcp__claude_ai_Atlassian__addCommentToJiraIssue"
+      "mcp__playwright"
     ]
   },
   "enableAllProjectMcpServers": true,