@qa-gentic/stlc-agents 1.0.4 → 1.0.6

package/skills/{qa-stlc/generate-test-cases.md → generate-test-cases/SKILL.md}

@@ -1,3 +1,17 @@
+---
+name: generate-test-cases
+description: >-
+  Use when creating or generating manual test cases for an Azure DevOps PBI, Bug, User Story,
+  or Feature. Triggers on: "create test cases", "generate test cases", "link test cases",
+  "manual tests", "TestedBy", "ADO test cases". Never creates test cases for Epics. Always
+  confirms before creating test cases for a Feature.
+license: MIT
+compatibility: "Requires qa-test-case-manager MCP server. Azure DevOps connectivity required."
+metadata:
+  author: qa-gentic
+  version: "1.1"
+---
+
 # Skill: Generate Test Cases from Azure DevOps Work Item
 
 > **Read `AGENT-BEHAVIOR.md` before this skill.** The behavior rules there override any
@@ -35,8 +49,8 @@ If the user replies 'no' or 'cancel', abort and inform them no test cases were c
 
 ## ⛔ Mandatory Pre-Flight: Deduplication Protocol
 
-Before executing any step below, run the deduplication protocol:
-`skills/deduplication-protocol.md`
+Before executing any step below, run the deduplication protocol
+(see the `deduplication-protocol` skill).
 
 The protocol is **work-item-scoped**: PHASE 1 runs once per `work_item_id` and its results
 are cached. If this skill is invoked for the same `work_item_id` that another agent already

package/skills/qa-jira-manager/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: qa-jira-manager
+description: >-
+  Use for Jira Cloud QA pipeline: fetch issues, analyse acceptance criteria, generate test cases,
+  link to source issues, then generate Gherkin and Playwright. Triggers on: "Jira", "PROJ-123",
+  "Jira test cases", "Jira story", "Atlassian". Supports Story, Bug, Task, Sub-task, and Epic
+  types. Mirrors the ADO pipeline using shared qa-gherkin-generator, qa-playwright-generator,
+  qa-helix-writer agents.
+license: MIT
+compatibility: "Requires qa-jira-manager MCP server. Also uses qa-gherkin-generator, qa-playwright-generator, qa-helix-writer for downstream steps. Works with Claude Code, GitHub Copilot, Cursor, Windsurf."
+metadata:
+  author: qa-gentic
+  version: "1.0"
+---
+
+# qa-jira-manager — Skill Reference
+
+> MCP agent for Jira Cloud: fetch work items, analyse acceptance criteria, generate
+> structured test cases, and link them back to the source issue via Jira REST API v3.
+
+---
+
+## Tool Reference
+
+### `fetch_jira_issue`
+
+Fetch a Story, Bug, Task, or Sub-task from Jira Cloud.
+
+**Inputs**
+
+| Parameter  | Type   | Required | Description                                       |
+|------------|--------|----------|---------------------------------------------------|
+| `issue_key` | string | ✓       | Jira issue key, e.g. `PROJ-123`                  |
+| `cloud_id`  | string |          | Atlassian cloud ID (falls back to `JIRA_CLOUD_ID` env var) |
+
+**Returns**
+
+```json
+{
+  "work_item": {
+    "key": "PROJ-123",
+    "type": "Story",
+    "summary": "...",
+    "description": "...",
+    "acceptance_criteria": "...",
+    "status": "In Progress",
+    "priority": "High",
+    "assignee": "Jane Smith",
+    "labels": ["regression"],
+    "story_points": 5,
+    "project_key": "PROJ",
+    "epic_key": "PROJ-10"
+  },
+  "parent_issue": { "key": "PROJ-10", "type": "Epic", "summary": "..." },
+  "existing_test_cases_count": 0,
+  "coverage_hints": ["post_action_state", "cancel_flows"]
+}
+```
+
+**Routing rules (strict — do not infer)**
+
+| Issue type  | Correct tool               |
+|-------------|----------------------------|
+| Epic        | `fetch_jira_epic_hierarchy` |
+| Story/Bug/Task/Sub-task | `fetch_jira_issue` |
+
+---
+
+### `fetch_jira_epic_hierarchy`
+
+Fetch a Jira Epic and enumerate all child issues.
+
+**Inputs**
+
+| Parameter | Type   | Required | Description            |
+|-----------|--------|----------|------------------------|
+| `epic_key` | string | ✓       | Epic issue key         |
+| `cloud_id` | string |          | Atlassian cloud ID     |
+
+**Returns**
+
+```json
+{
+  "epic": { "key": "PROJ-10", "summary": "...", "project_key": "PROJ" },
+  "children": [
+    { "key": "PROJ-11", "type": "Story", "summary": "...", "status": "Open" }
+  ],
+  "child_count": 1
+}
+```
+
+---
+
+### `create_and_link_test_cases`
+
+Create test case issues in Jira and link them to the source issue.
+
+**Inputs**
+
+| Parameter     | Type    | Required | Description                                              |
+|---------------|---------|----------|----------------------------------------------------------|
+| `issue_key`   | string  | ✓        | Source Jira issue to link test cases to                  |
+| `project_key` | string  |          | Project where test cases are created (defaults to source issue project) |
+| `cloud_id`    | string  |          | Atlassian cloud ID                                       |
+| `test_cases`  | array   | ✓        | Array of test case objects (see schema below)            |
+| `confirmed`   | boolean |          | `true` only when retrying after Epic confirmation        |
+
+**Test case object**
+
+```json
+{
+  "summary": "Verify upload success toast appears",
+  "priority": "High",
+  "labels": ["regression", "smoke"],
+  "steps": [
+    { "action": "Navigate to the upload page", "expected_result": "Upload page is displayed" },
+    { "action": "Upload a valid PNG file", "expected_result": "Toast 'Upload successful' appears within 3 s" }
+  ]
+}
+```
+
+**Priority values:** `Highest` · `High` (default) · `Medium` · `Low` · `Lowest`
+
+**Epic confirmation gate**
+
+When `issue_key` resolves to an Epic, the server returns `confirmation_required: true`
+and creates nothing. Surface the message to the user, wait for confirmation, then
+retry with `confirmed: true`. Do not change any other parameter.
+
+---
+
+### `get_linked_test_cases`
+
+Return all issues linked to an issue via `is tested by` / `Test` link type.
+
+**Inputs**
+
+| Parameter  | Type   | Required |
+|------------|--------|----------|
+| `issue_key` | string | ✓       |
+| `cloud_id`  | string |          |
+
+---
+
+## Recommended Workflow
+
+The Jira pipeline mirrors the ADO pipeline exactly. After creating test cases in Jira,
+continue with Gherkin generation, Playwright code generation, and Helix-QA file writing
+using the shared agents (`qa-gherkin-generator`, `qa-playwright-generator`, `qa-helix-writer`).
+
+```
+Step 1 — Fetch the Jira issue
+  fetch_jira_issue(issue_key)
+  → read summary, acceptance_criteria, coverage_hints
+  → check existing_test_cases_count — if > 0 call get_linked_test_cases first
+  For Epics: use fetch_jira_epic_hierarchy instead, then process each child issue.
+
+Step 2 — Analyse and generate test case objects
+  Use acceptance_criteria + coverage_hints to draft test cases.
+  Complexity → TC range:
+    1–3 story points → Simple  → 3–6 test cases
+    4–8 story points → Medium  → 6–12 test cases
+    9+  story points → Complex → 12–18 test cases
+  Show the user the proposed list and get explicit confirmation before Step 3.
+
+Step 3 — Create test cases in Jira and link them
+  create_and_link_test_cases(issue_key, test_cases=[...])
+  → created_test_cases[].issue_key contains the new Jira keys
+  → link_result.linked_keys confirms the 'is tested by' links
+  Report created keys and direct browse URLs to the user.
+
+Step 4 — Generate Gherkin feature file   [shared agent: qa-gherkin-generator]
+  Use fetch_work_item_for_gherkin (pass the Jira issue key as the work item reference)
+  or use the acceptance_criteria already fetched in Step 1.
+  Navigate to the live screen in the browser before writing any scenario.
+  Follow all HARD STOP rules in generate-gherkin skill.
+  Ask the user whether to attach the .feature file to the Jira issue or save locally.
+
+Step 5 — Generate Playwright TypeScript   [shared agent: qa-playwright-generator]
+  Run validate_gherkin_steps → generate_playwright_code.
+  Ask the user whether to attach generated files to the Jira issue or save locally.
+
+Step 6 — Write files to Helix-QA project   [shared agent: qa-helix-writer]
+  Call qa-helix-writer with the generated locators.ts / *Page.ts / *.steps.ts files.
+  Follow write-helix-files skill for path conventions.
+
+Step 7 — Report to user
+  Summarise: Jira test case keys created, .feature file location, Playwright files
+  written, and Helix-QA paths updated.
+```
+
+> **Zero-inference rule** (from AGENT-BEHAVIOR.md): each delivery step (attach to Jira,
+> attach Playwright, write Helix) requires a **separate, explicit confirmation** from the user.
+> Completing one step does NOT automatically trigger the next.
+
+---
+
+## Coverage Hint Categories
+
+Use these to ensure test design covers edge cases beyond the happy path:
+
+| Hint | Trigger keywords |
+|------|-----------------|
+| `toast_notifications` | toast, notification, success message, confirmation |
+| `file_size_boundary` | mb, kb, size limit, file size, maximum size |
+| `post_action_state` | display, shows, reflects, after upload, after save, updated |
+| `platform_specific` | mobile, webview, ios, android |
+| `computed_values` | initials, first name, last name, derived, generated |
+| `data_persistence` | refresh, reload, re-login, persist, retained |
+| `accessibility` | tab, keyboard, accessible, aria, wcag, a11y |
+| `image_manipulation` | crop, resize, zoom, drag, rotate |
+| `file_formats` | format, png, jpg, jpeg, webp, svg |
+| `cancel_flows` | cancel, close, discard, dismiss |
+| `validation_errors` | required, invalid, error, validation, must be |
+
+---
+
+## Authentication Setup
+
+### Step 1 — Create an Atlassian OAuth 2.0 (3LO) app
+
+1. Go to <https://developer.atlassian.com/console/myapps/>
+2. Click **Create** → **OAuth 2.0 integration**
+3. Add callback URL: `http://localhost:8765/callback`
+4. Under **Permissions**, add:
+   - Jira API → `read:jira-user`, `read:jira-work`, `write:jira-work`
+5. Copy the **Client ID** and **Secret**
+
+### Step 2 — Find your Cloud ID
+
+```bash
+curl -H "Authorization: Bearer <any-token>" \
+  https://api.atlassian.com/oauth/token/accessible-resources
+```
+
+Copy the `id` field for your site.
+
+### Step 3 — Add to `.env`
+
+```env
+JIRA_CLIENT_ID=your-client-id
+JIRA_CLIENT_SECRET=your-client-secret
+JIRA_CLOUD_ID=your-cloud-id
+# Optional — defaults to http://localhost:8765/callback
+JIRA_REDIRECT_URI=http://localhost:8765/callback
+```
+
+### Step 4 — First run
+
+```bash
+qa-jira-manager
+```
+
+The browser opens once. Sign in to Jira. The token is cached at
+`~/.jira-cache/jira-token.json` and silently refreshed for ~60 days.
+
+---
+
+## MCP Config (VS Code / `.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "qa-jira-manager": {
+      "type": "stdio",
+      "command": "qa-jira-manager",
+      "env": {
+        "JIRA_CLIENT_ID": "${env:JIRA_CLIENT_ID}",
+        "JIRA_CLIENT_SECRET": "${env:JIRA_CLIENT_SECRET}",
+        "JIRA_CLOUD_ID": "${env:JIRA_CLOUD_ID}"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Notes
+
+- Steps are stored as an ADF table in the issue **description** — compatible with
+  Jira Software, Jira Service Management, and Xray-free environments.
+- If your project does not have a **Test** issue type, the agent automatically
+  falls back to **Task** and adds a `qa-test-case` label.
+- The link type used is **Test** (Jira's built-in test link type). If that link
+  type does not exist in your instance, the agent falls back to **Relates**.
+- `cloud_id` can be omitted on every call if `JIRA_CLOUD_ID` is set in `.env`.

package/skills/{qa-stlc/write-helix-files.md → write-helix-files/SKILL.md}

@@ -1,22 +1,16 @@
 ---
 name: write-helix-files
-description: >
-  Use this skill whenever generated Playwright TypeScript files (locators,
-  page objects, step definitions, feature files, healing infrastructure) need
-  to be placed into a local Helix-QA project on disk. Triggers after
-  generate-playwright-code or scaffold_locator_repository has produced a
-  'files' dict. Always calls inspect_helix_project first to determine whether
-  the framework exists, then picks the correct write mode automatically.
-compatibility:
-  tools:
-    - qa-helix-writer:inspect_helix_project
-    - qa-helix-writer:list_helix_tree
-    - qa-helix-writer:read_helix_file
-    - qa-helix-writer:write_helix_files
-    - qa-helix-writer:update_helix_file
-    - qa-playwright-generator:generate_playwright_code
-    - qa-playwright-generator:scaffold_locator_repository
-    - qa-playwright-generator:pre_validate_cucumber_steps
+description: >-
+  Use when placing generated Playwright TypeScript files into a Helix-QA project on disk.
+  Triggers after generate-playwright-code or scaffold_locator_repository has produced a
+  files dict. Triggers on: "write to helix", "helix-qa", "write files to disk", "write
+  locators", "write page objects", "write step definitions", "inspect helix", "helix root".
+  Always calls inspect_helix_project first.
+license: MIT
+compatibility: "Requires qa-helix-writer, qa-playwright-generator MCP servers."
+metadata:
+  author: qa-gentic
+  version: "1.1"
 ---
 
 # Write Helix Files Skill