---
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`.
