@roopesh.yadava/qa-pack 1.0.3

package/README.md

@@ -0,0 +1,79 @@
+# @roopesh.yadava/qa-pack
+
+AI-powered QA agent skills for Claude Code. Drop into any product repo — get manual testing, BDD automation, accessibility audits, UI/Figma diff, bug filing, and test charters all triggered by plain English.
+
+## Install
+
+```bash
+# One-time .npmrc line needed because of the CodeArtifact default registry on 7Edge machines
+echo "@roopesh.yadava:registry=https://registry.npmjs.org" >> .npmrc
+npm install --save-dev @roopesh.yadava/qa-pack
+```
+
+On install, the postinstall script copies all skills and commands into `.claude/` and creates one-time config files (`CLAUDE.md`, `.mcp.json`, `cucumber.cjs`) if they don't already exist. It also writes the `.npmrc` scope entry above automatically, so `npm update` works with no extra steps after the first install.
+
+## Update
+
+```bash
+npm update @roopesh.yadava/qa-pack
+```
+
+Skill files are overwritten with the latest version. Your `CLAUDE.md`, `.mcp.json`, and — critically — `product_context/` (your accumulated run history and known bugs) are **never touched**.
+
+## First-time setup
+
+After installing, open `CLAUDE.md` at your repo root and fill in:
+
+```
+Jira Project Key:  PROJ
+App URL:           https://your-app.example.com
+Auth Method:       form_login | SSO | token | none
+OTP Required:      yes (always 999999) | no
+Username / Password: your test credentials
+```
+
+Then open the repo in Claude Code and run:
+
+```
+run qa PROJ-123
+```
+
+## Triggers
+
+| Say this | What happens |
+|---|---|
+| `run qa PROJ-123` | Full QA — manual or automation branch |
+| `manual test PROJ-123` | Playwright manual testing + bug filing |
+| `automate PROJ-123` | Gherkin + step defs + POM |
+| `accessibility test PROJ-123` | WCAG 2.1 A/AA audit |
+| `ui test PROJ-123` | Live app vs Figma design diff |
+| `file a bug` | Files bug directly to Jira |
+| `/write-acceptance-criteria PROJ-123` | Generates AC, appends to Jira card |
+
+## What postinstall does
+
+| File | Behaviour |
+|---|---|
+| `.claude/skills/*/SKILL.md` + companion `.md` files | Always overwritten (versioned logic) |
+| `.claude/commands/*.md` | Always overwritten |
+| `.claude/skills/qa-agent/product_context/**` | **Never touched** after first seed |
+| `.claude/settings.json` | Created once, never overwritten |
+| `CLAUDE.md`, `.mcp.json`, `cucumber.cjs` | Created once, never overwritten |
+| `.claude/settings.local.json` | Created once from example |
+| `.claude/settings.local.json.example` | Always refreshed (shows latest options) |
+| `.gitignore` | `outputs/` and `settings.local.json` appended if missing |
+
+## Publishing (maintainers)
+
+```bash
+# In qa-pack/ repo, bump version and push
+npm version patch   # or minor / major
+git add . && git commit -m "your message" && git push origin main
+# GitHub Actions publishes to npmjs automatically
+```
+
+## Requirements
+
+- Claude Code CLI
+- Node.js 18+
+- Atlassian MCP connected in Claude Code (for Jira)

package/bin/postinstall.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PACK_DIR = path.join(__dirname, '..');
+const PROJECT_ROOT = process.env.INIT_CWD || process.cwd();
+
+// Don't run when working on the package itself
+if (PROJECT_ROOT === PACK_DIR) {
+  console.log('@roopesh.yadava/qa-pack: skipping postinstall (running inside package directory)');
+  process.exit(0);
+}
+
+const log = { added: [], updated: [], skipped: [], protected: [] };
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyFile(src, dest, { overwrite = true } = {}) {
+  ensureDir(path.dirname(dest));
+  const rel = path.relative(PROJECT_ROOT, dest);
+  if (!overwrite && fs.existsSync(dest)) {
+    log.skipped.push(rel);
+    return;
+  }
+  const isNew = !fs.existsSync(dest);
+  fs.copyFileSync(src, dest);
+  isNew ? log.added.push(rel) : log.updated.push(rel);
+}
+
+// Copy a directory recursively with per-file overwrite control
+function copyDir(src, dest, shouldOverwrite) {
+  ensureDir(dest);
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, shouldOverwrite);
+    } else {
+      copyFile(srcPath, destPath, { overwrite: shouldOverwrite(srcPath) });
+    }
+  }
+}
+
+// ── 1. Skills — always overwrite (these are the versioned logic files) ────────
+// Exception: product_context/ contents are user data — seed only, never overwrite
+const skillsSrc = path.join(PACK_DIR, 'claude', 'skills');
+const skillsDest = path.join(PROJECT_ROOT, '.claude', 'skills');
+
+copyDir(skillsSrc, skillsDest, (srcPath) => {
+  const rel = path.relative(skillsSrc, srcPath);
+  // product_context/README.md and CONTEXT_SCHEMA.md are templates — seed only
+  if (rel.startsWith(path.join('qa-agent', 'product_context'))) {
+    const destPath = path.join(skillsDest, rel);
+    if (fs.existsSync(destPath)) {
+      log.protected.push(path.join('.claude', 'skills', rel));
+      return false; // never overwrite
+    }
+    return true; // seed on first install
+  }
+  return true; // all other skill files: always update
+});
+
+// ── 2. Commands — always overwrite ────────────────────────────────────────────
+const commandsSrc = path.join(PACK_DIR, 'claude', 'commands');
+const commandsDest = path.join(PROJECT_ROOT, '.claude', 'commands');
+copyDir(commandsSrc, commandsDest, () => true);
+
+// ── 3. settings.json — create only if missing ─────────────────────────────────
+copyFile(
+  path.join(PACK_DIR, 'claude', 'settings.json'),
+  path.join(PROJECT_ROOT, '.claude', 'settings.json'),
+  { overwrite: false }
+);
+
+// ── 4. settings.local.json — create from example only if missing ──────────────
+const localSettingsDest = path.join(PROJECT_ROOT, '.claude', 'settings.local.json');
+if (!fs.existsSync(localSettingsDest)) {
+  copyFile(
+    path.join(PACK_DIR, 'templates', 'settings.local.json.example'),
+    localSettingsDest,
+    { overwrite: false }
+  );
+}
+// Always refresh the .example so teams can see what's new
+copyFile(
+  path.join(PACK_DIR, 'templates', 'settings.local.json.example'),
+  path.join(PROJECT_ROOT, '.claude', 'settings.local.json.example'),
+  { overwrite: true }
+);
+
+// ── 5. One-time templates (never overwrite — user fills these in) ─────────────
+const templates = [
+  ['templates/CLAUDE.md',    'CLAUDE.md'],
+  ['templates/mcp.json',     '.mcp.json'],
+  ['templates/cucumber.cjs', 'cucumber.cjs'],
+];
+for (const [src, dest] of templates) {
+  copyFile(
+    path.join(PACK_DIR, src),
+    path.join(PROJECT_ROOT, dest),
+    { overwrite: false }
+  );
+}
+
+// ── 6. .npmrc — ensure scope points to the public npm registry (needed for npm update) ──
+const npmrcPath = path.join(PROJECT_ROOT, '.npmrc');
+const npmrcEntry = '@roopesh.yadava:registry=https://registry.npmjs.org';
+if (fs.existsSync(npmrcPath)) {
+  const content = fs.readFileSync(npmrcPath, 'utf8');
+  if (!content.includes(npmrcEntry)) {
+    fs.appendFileSync(npmrcPath, `\n${npmrcEntry}\n`);
+    log.updated.push('.npmrc');
+  }
+} else {
+  fs.writeFileSync(npmrcPath, `${npmrcEntry}\n`);
+  log.added.push('.npmrc');
+}
+
+// ── 7. .gitignore — ensure outputs/ and settings.local.json are ignored ───────
+const gitignorePath = path.join(PROJECT_ROOT, '.gitignore');
+const gitignoreEntries = ['outputs/', '.claude/settings.local.json'];
+if (fs.existsSync(gitignorePath)) {
+  let content = fs.readFileSync(gitignorePath, 'utf8');
+  const toAdd = gitignoreEntries.filter(e => !content.includes(e));
+  if (toAdd.length) {
+    content += `\n# qa-pack\n${toAdd.join('\n')}\n`;
+    fs.writeFileSync(gitignorePath, content);
+    log.updated.push('.gitignore');
+  }
+} else {
+  fs.writeFileSync(gitignorePath, `# qa-pack\n${gitignoreEntries.join('\n')}\n`);
+  log.added.push('.gitignore');
+}
+
+// ── Summary ───────────────────────────────────────────────────────────────────
+console.log('\n@roopesh.yadava/qa-pack installed\n');
+if (log.added.length)      console.log('  Created  :', log.added.join(', '));
+if (log.updated.length)    console.log('  Updated  :', log.updated.join(', '));
+if (log.skipped.length)    console.log('  Skipped  :', log.skipped.join(', '));
+if (log.protected.length)  console.log('  Protected:', log.protected.join(', '), '(product context — never overwritten)');
+
+if (log.added.includes('CLAUDE.md')) {
+  console.log('\n  Next: open CLAUDE.md and fill in your Jira project key, app URL, and credentials.');
+}
+console.log('');

package/claude/commands/bug-report.md

@@ -0,0 +1,185 @@
+You are a Jira bug reporting assistant. Follow these steps precisely and in order.
+
+---
+
+## Step 1 — Select a project
+
+Use the Atlassian MCP tool (`getVisibleJiraProjects`) to fetch all visible projects immediately — do not wait for user input.
+
+Display the list and ask:
+"Which board are you working on? You can reply with the number or the board key:
+1. [KEY] — [Project Name]
+2. [KEY] — [Project Name]
+..."
+
+Wait for the user to select a project by number or board key. Save the selected project key for the rest of the flow.
+
+---
+
+## Step 1A/1B — Ask card type
+
+Ask the user:
+"Is this an **Exploratory Bug** (create a new card) or an **Existing Card** (add bugs to an existing one)?"
+
+Wait for the user's choice before proceeding.
+
+- If the user chooses **Exploratory Bug** → go to Step 1A
+- If the user chooses **Existing Card** → go to Step 1B
+
+---
+
+## Step 1A — Create a new Exploratory Bug card
+
+Ask the user: "Please enter a name for the Exploratory Bug card."
+
+Wait for the user's input.
+
+Use the Atlassian MCP tool (`createJiraIssue`) to create a new Jira issue in the selected project with:
+- **Issue Type:** Bug
+- **Summary:** [Card name entered by the user]
+- **Labels:** Exploratory
+
+After creating the issue, use `getTransitionsForJiraIssue` to fetch available transitions, then use `transitionJiraIssue` to move the card to **Backlog** status.
+
+Once created and moved to Backlog, display:
+
+> **Exploratory Bug card created:** [CARD-NUMBER] — [Card Name]
+> [Link to card]
+
+Save this card number as the active card for the rest of the flow. Then proceed to Step 2.
+
+---
+
+## Step 1B — Use an existing card
+
+Ask the user: "Please enter the card number (e.g. 123 or [KEY]-123) to attach this bug report to."
+
+Wait for the user's input.
+
+If the user enters only a number (e.g. `2446`), construct the full card number using the selected project key (e.g. QE-2446).
+
+Use the Atlassian MCP tool (`getJiraIssue`) to fetch the card details. Display:
+
+> **Card found:** [CARD-NUMBER] — [Card Summary/Title]
+
+If the fetched card's issue type is **Bug**, ask:
+"Do you want to add the bugs to the **Description** or as a **Comment**?"
+
+Wait for the user's choice and save it as the **save mode** (Description or Comment) for use in Step 6.
+
+Save this card number as the active card for the rest of the flow. Then proceed to Step 2.
+
+---
+
+## Step 2 — Collect bug details
+
+Ask the user: "Please describe the bug."
+
+Wait for the user's input. Accept whatever they provide — a sentence, a paragraph, or structured text.
+
+From the input, infer and derive all necessary fields:
+- **Bug Title** — extract or summarise from what was given
+- **Expected Outcome** — infer from context if not explicitly stated
+- **Actual Outcome** — extract the described problem
+- **Steps to Reproduce** — extract or derive from the description
+
+Do NOT ask the user for any missing fields. Use what was given and proceed.
+
+---
+
+## Step 3 — Display the formatted bug report
+
+Show the bug report in this exact format before posting:
+
+### Bug No. [n]: [Bug Title]
+
+### Expected Outcome:
+[Expected Outcome]
+
+### Actual Outcome:
+[Actual Outcome]
+
+### Steps to Reproduce:
+[Steps]
+
+After showing the report, ask:
+"Is this the only bug, or do you have another bug to add?"
+
+- If the user says **yes (another bug)** — go back to Step 2 and collect the next bug. Append it to the report using the same format with an incremented Bug No. Repeat until the user says no more bugs.
+- If the user says **no more bugs** — proceed to Step 4.
+
+---
+
+## Step 4 — Ask who to mention
+
+Before posting, ask:
+"Who should I notify about this bug? Please enter the person's name, or type **none** to skip."
+
+Wait for the user's input.
+
+- If the user types **none** (or says no one / skip) → set mention as empty, skip Step 5, and proceed directly to Step 6. Do NOT add any mention or "Please check this" line in the report.
+- Otherwise → proceed to Step 5.
+
+---
+
+## Step 5 — Search for the person in Jira
+
+Use the Atlassian MCP tool (`lookupJiraAccountId`) to search for the name the user entered.
+
+If multiple results are found, list them and ask:
+"Is this the right person? [Name — Account ID]"
+
+If only one result is found, display that person's name and ask:
+"Found: [Full Name]. Is this the right person? (yes / no)"
+
+Wait for confirmation before proceeding.
+
+---
+
+## Step 6 — Save the bug report to Jira
+
+### If the card is an Exploratory Bug (created in Step 1A):
+
+Use the Atlassian MCP tool (`editJiraIssue`) to update the **Description** field of the card with the full bug report AND the mention at the end.
+
+The description body must follow this structure:
+
+```
+h3. Bug No. [n]: [Bug Title]
+
+h3. Expected Outcome:
+[Expected Outcome]
+
+h3. Actual Outcome:
+[Actual Outcome]
+
+h3. Steps to Reproduce:
+[Steps]
+
+(repeat the above block for each additional bug if more than one was collected)
+
+(only include the line below if a person was confirmed in Step 5 — omit it entirely if the user chose none)
+@[confirmed person's display name], Please check.
+```
+
+Do NOT post a comment. Write everything into the Description field of the card.
+
+---
+
+### If the card is an Existing Card (from Step 1B):
+
+- If the user chose **Description** → use `editJiraIssue` to update the Description field with the full bug report and mention. Do NOT post a comment.
+- If the user chose **Comment** → use `addCommentToJiraIssue` to post one single comment with the full bug report and mention. Do NOT post a second separate comment.
+
+In both cases the content structure is the same as above.
+
+---
+
+## Step 7 — Confirm completion
+
+Show a summary:
+- Jira card: [Card number with link]
+- Bug report posted: ✓
+- Notified: [Confirmed person's name]
+
+Done.

package/claude/commands/qa-agent.md

@@ -0,0 +1,12 @@
+---
+name: qa-agent
+description: Launch the QA Agent — presents the skill menu and dispatches to the right skill based on your input.
+argument-hint: "[Jira card ID | 'full QA' | skill name | plain description]"
+user-invocable: true
+---
+
+Invoke the `qa-agent` skill.
+
+If the user provided an argument (e.g. a Jira card ID or the phrase "full QA for PROJ-123"),
+pass it directly into the skill as the initial intent so the agent does not re-ask for input
+it has already received.

package/claude/commands/write-acceptance-criteria.md

@@ -0,0 +1,167 @@
+---
+name: write-acceptance-criteria
+description: >
+  Generates structured acceptance criteria for a feature or user story,
+  covering happy paths, unhappy paths, and edge cases in a clear,
+  testable format suitable for development and QA handoff. If given a
+  Jira card ID (e.g. FF-420), fetches the card automatically and appends
+  the acceptance criteria to the bottom of the issue description without
+  overwriting any existing content.
+argument-hint: "<Jira card ID or feature description>"
+user-invocable: true
+---
+
+## Core Workflow
+
+0. **Detect Jira card ID** — If the argument matches the pattern `[A-Z]+-[0-9]+` (e.g. `FF-420`, `AA-12`),
+   fetch the issue using the `getJiraIssue` tool with cloudId `853e134e-6574-491a-a075-1b06f7d4b478`.
+   Use the issue summary and description as the feature input for the next steps.
+   If the issue has no description, use the summary only and note this in the Assumptions section.
+   If the argument is not a Jira card ID, treat it as a raw feature description and skip to step 1.
+
+1. **Parse the feature** — Read the feature description or user story provided by the user
+
+2. **Identify actors and goals** — Determine who is doing what and what success looks like
+
+3. **Derive all scenarios** — Map out standard flows, variations, error states, and edge cases
+
+4. **Write acceptance criteria** — Follow the output format exactly
+
+5. **Flag assumptions** — Note anything inferred that the user should confirm
+
+6. **Append to Jira description** — If the input was a Jira card ID:
+   - Fetch the current description of the issue using `getJiraIssue`
+   - Preserve the full existing description exactly as-is (do NOT remove or overwrite any content, including COS or any other existing sections)
+   - Append the generated acceptance criteria at the very bottom of the existing description, separated by a divider line (`---`)
+   - Update the issue description using `editJiraIssue` with cloudId `853e134e-6574-491a-a075-1b06f7d4b478`
+   - After updating, confirm to the user with the Jira issue URL: `https://7edge.atlassian.net/browse/<CARD-ID>`
+
+---
+
+## Output Format
+
+Always produce output in exactly this structure, in this order.
+
+---
+
+### Acceptance Criteria
+
+### Happy Paths
+
+Numbered list of standard, successful user flows. Each step is one clear action or system response. Steps must be sequential and realistic.
+
+1. Step one
+2. Step two
+3. ...
+
+Include one or more complete flows if the feature has multiple valid entry points or user types.
+
+---
+
+### Unhappy Paths
+
+Numbered list of failure scenarios, edge cases, and error conditions. Be specific — name the actual error, input, or state, not a generic category.
+
+Include:
+- Validation failures (missing fields, invalid formats, out-of-range values)
+- System errors (timeouts, service unavailability, unexpected states)
+- User errors (wrong order of actions, duplicate submissions, unauthorised access)
+- Edge cases (empty states, maximum limits, concurrent actions)
+- Missing or misleading feedback (no confirmation, silent failure, confusing error messages)
+
+---
+
+## Writing Guidelines
+
+- **Acceptance criteria must be testable.** Every `Then` clause must be answerable with pass/fail by a QA engineer.
+- **Happy paths = the expected, successful flow.** Write them as a user would experience them, step by step.
+- **Unhappy paths = everything that can go wrong.** Be exhaustive and specific. "User enters invalid email" is better than "validation fails."
+- **Avoid implementation language.** Write what happens, not how the system achieves it.
+- **One action per step.** Don't bundle two user actions into one step.
+- **Tone:** Neutral, precise, present tense. No filler.
+
+---
+
+## Handling Incomplete Input
+
+If the feature description is vague:
+- Infer the most common interpretation based on domain patterns
+- Write complete output using those inferences
+- Add a short **Assumptions** section at the end listing what was inferred
+- Only ask for clarification if the description is too ambiguous to produce any meaningful output
+
+---
+
+## Example
+
+**Input:** "Add email notifications when a report is exported"
+
+---
+
+### Acceptance Criteria
+
+### Happy Paths
+
+1. User navigates to the Reports section and selects a report to export
+2. User clicks "Export" and selects the desired format (e.g., CSV, PDF)
+3. System queues the export job and displays a confirmation message: "Your export is being processed. You'll receive an email when it's ready."
+4. Export job completes; system sends an email to the user's registered address
+5. Email arrives with subject line, report name, and a clearly labelled download button
+6. User clicks the download link; file downloads immediately in the selected format
+7. Link remains active for 24 hours from time of export completion
+
+---
+
+### Unhappy Paths
+
+1. User triggers an export but has no verified email address on file — system blocks the action and prompts the user to add and verify an email before exporting
+2. Export job fails due to a data processing error — user receives a failure email with a human-readable reason (not a raw error code) and a "Try Again" link
+3. User clicks the download link after it has expired (>24 hours) — page displays: "This link has expired. Return to Reports to export again." with a direct link back
+4. User clicks the download link but the file has been deleted from storage — system returns a 404 page with a clear message and re-export option, not a generic browser error
+5. Email delivery fails (e.g., inbox full, domain rejected) — system retries up to 3 times over 10 minutes; if all retries fail, the failure is logged and flagged in the admin panel
+6. User triggers the same export twice in quick succession — system deduplicates and sends only one email; no duplicate files are created
+7. User has disabled email notifications in their profile settings — system respects the preference and does not send the email; the export still completes and is accessible via the Reports page
+
+---
+
+*Assumed: web-based product with a registered user model and a transactional email provider already in place. Adjust if this is a mobile or API-only context.*
+
+
+
+<!-- Created by Roopesh Yadava
+
+Generate detailed documentation for the feature: {{feature_description}}
+
+Follow these steps:
+
+1. **Identify scenarios** — Analyze the feature description and derive all possible user flows, including standard usage and edge cases.
+
+2. **Understand expected behavior** — Determine:
+
+   * What the user is trying to achieve
+   * System responses for valid and invalid inputs
+   * Possible failure points or UX gaps
+
+3. **Generate output** with the following structure:
+
+## Acceptance Criteria
+
+(Leave this section empty — do not list or rewrite anything here.)
+
+## Happy Paths
+
+* List all happy paths using numbered bullets.
+* Each step should describe one clear user action or system result.
+* Keep steps concise, realistic, and sequential.
+
+## Unhappy Paths
+
+* List all unhappy paths using numbered bullets.
+* Include:
+
+  * User errors
+  * Validation failures
+  * System issues
+  * Edge cases
+  * Missing or incorrect feedback
+  * Be specific and practical in each scenario. -->

package/claude/settings.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@0.0.75",
+        "--browser", "chromium",
+        "--caps", "vision",
+        "--viewport-size", "1920x1080"
+      ]
+    }
+  }
+}

package/claude/settings.local.json.example

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx playwright *)",
+      "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"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "playwright"
+  ]
+}